Digital PDFs

AA-LA83A-TE

December 1988

399 pages

Original

14MB

Document:	VMS 5.0 Record Management Services Manual 198804
Order Number:	AA-LA83A-TE
Revision:
Pages:	399
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.0/AA-LA83A-TE_VMS_5.0_Record_Management_Services_Manual_198804.pdf

OCR Text

VMS
Record Management
Services Reference
Manual
Order Number: AA-LA83A-TE

April 1988
This document contains general information intended for use in any
VAX programming language, as well as specific information on writing
programs in VAX MACRO that use VMS RMS. It also includes descriptions
of the VMS RMS macros provided for use by VAX MACRO programs.

Revision/Update Information:

This revised document supersedes
the Record Management Services
Reference Manual, Version 4.4.

Software Version:

VMS Version 5.0

digital equipment corporation
maynard, massachusetts

April 1988
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such li~ense.
No responsibility is assumed for the use or reliability of software on equipment
thc;it is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1988 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DEC US
DECwriter

DIBOL
Edu System
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

~urnua~u TM
ZK4523

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO Rico*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by DIGITAL. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format the
text, generate a table of contents and index, and paginate the entire document.
Writers can print the document on the terminal or line printer, or they can y_se
DIGITAL-supported devices, such as the LN03 laser printer and PostScript'g,
printers (PrintServer 40 or LN03R ScriptPrinter), to produce a typeset-quality
copy containing integrated graphics.

PostScript is a trademark of Adobe Systems, Inc.

Contents
PREFACE

xxiii

NEW AND CHANGED FEATURES

xxvii

GENERAL INFORMATION ABOUT VMS RECORD
MANAGEMENT SERVICES
CHAPTER 1 INTRODUCTION TO VMS RMS

1-1

1.1

VMS RMS FUNCTIONS

1-1

1.2
1.2.1
1.2.2
1.2.3
1.2.4

PASSING ARGUMENTS TO VMS RMS
VMS RMS Services and Control Blocks
Control Blocks for File Services
Control Blocks for Record Services
The Dual Purpose of Control Blocks

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

CHAPTER 2 THE PROGRAM INTERFACE WITH VMS RMS
2.1

2-1

THE RUN-TIME ENVIRONMENT AND VMS RMS
PROGRAMMING

2-1

2.2

CONVENTIONS FOR NAMING FIELDS

2-2

2.3

THE VMS RMS CALLING SEQUENCE

2-4

2.4

CONDITION VALUES

2-5

2.5

ALLOWABLE PROGRAM EXECUTION MODES

2-7

2.6

RESERVED EVENT FLAGS

2-7

Contents

2.7

DEC MULTINATIONAL CHARACTER SET

CHAPTER 3 VMS RMS MACROS AND VAX MACRO
PROGRAMMING

3-1

3.1
3.1.1
3.1.2

VMS RMS MACROS
Conventions for Naming VMS RMS Macros
Applicable VAX MACRO Syntax Rules

3-1
3-2
3-5

3.2
3.2.1
3.2.2
3.2.3
3.2.4

USING THE VMS RMS MACROS
Control Block Initialization Macros
Control Block Symbol Definition Macros
Control Block Store Macros
Service Macros

3-6
3-7
3-8
3-8
3-10

CHAPTER 4 VMS RMS EXAMPLE PROGRAMS

2-7

4-1

4.1
4.1.1
4.1.2

CREATING, ACCESSING, AND DEACCESSING A FILE
Example of Opening and Creating Files
Example of Creating a Multiple-Key Indexed File

4-1
4-2
4-5

4.2

PROCESSING FILE SPECIFICATIONS

4-9

4.3

CONNECTING AND DISCONNECTING RECORD STREAMS

4-12

4.4

OTHER FILE-PROCESSING OPERATIONS

4-14

4.5

RETRIEVING AND INSERTING RECORDS

4-16

4.6

DELETING RECORDS

4-19

4.7

UPDATING RECORDS

4-21

4.8
4.8.1
4.8.2

USING BLOCK 1/0
Mixed Block and Record 1/0
The Next Block Pointer (NBP)

4-23
4-24
4-25

Contents

4.9

OTHER RECORD-PROCESSING OPERATIONS

4-27

4.10

CONTROL ROUTINES

4-27

VMS RMS CONTROL BLOCKS
CHAPTER 5 FILE ACCESS BLOCK (FAB)

5-1

5.1

SUMMARY OF FIELDS

5-1

5.2

FAB$L_ALQ FIELD

5-3

5.3

FAB$B_BID FIELD

5-3

5.4

FAB$B_BKS FIELD

5-3

5.5

FAB$B_BLN FIELD

5-4

5.6

FAB$W_BLS FIELD

5-5

5.7

FAB$V_CHAN_MODE SUBFIELD

5-5

5.8

FAB$L_CTX FIELD

5-6

5.9

FAB$W_DEQ FIELD

5-6

5.10

FAB$L_DEV FIELD

5-7

5.11

FAB$L_DNA FIELD

5-8

5.12

FAB$B_DNS FIELD

5-9

5.13

FAB$B_FAC FIELD

5-9

vii

Contents

viii

5.14

FAB$L_FNA FIELD

5-11

5.15

FAB$B_FNS FIELD

5-12

5.16

FAB$L_FOP FIELD

5-12

5.17

FAB$B_FSZ FIELD

5-18

5.18

FAB$W_GBC FIELD

5-19

5.19

FAB$W_IFI FIELD

5-20

5.20

FAB$V_LNM_MQDE SUBFIELD

5-20

5.21

FAB$L_MRN FIELD

5-21

5.22

FAB$W_MRS FIELD

5-21

5.23

FAB$L_NAM FIELD

5-23

5.24

FAB$B_QRG FIELD

5-23

5.25

FAB$B_RAT FIELD

5-23

5.26

FAB$B_RFM FIELD

5-25

5.27

FAB$B_RTV Fl ELD

5-26

5.28

FAB$L_SDC FIELD

5-27

5.29

FAB$B_SHR FIELD

5-27

5.30

FAB$L_STS FIELD

5-29

5.31

FAB$L_STV FIELD

5-29

Contents

5.32

FAB$L_)(AB FIELD

CHAPTER 6 NAME BLOCK (NAM)

5-29

6-1

6.1

SUMMARY OF FIELDS

6-1

6.2

FILE SPECIFICATION COMPONENT DESCRIPTORS

6-3

6.3

NAM$B_BID FIELD

6-4

6.4

NAM$8_8LN FIELD

6-4

6.5

NAM$B_DEV AND NAM$L_DEV FIELDS

6-4

6.6

NAM$W_DID FIELD

6-4

6.7

NAM$B_DIR AND NAM$L_DIR FIELDS

6-5

6.8

NAM$T_DVI FIELD

6-5

6.9

NAM$L_ESA FIELD

6-5

6.10

NAM$B_ESL FIELD

6-5

6.11

NAM$B_ESS FIELD

6-5

6.12

NAM$W_FID FIELD

6-6

6.13

NAM$L_FNB FIELD

6-6

6.14

NAM$B_NAME AND NAM$L_NAME FIELDS

6-7

6.15

NAM$B_NODE AND NAM$L_NODE FIELDS

6-7

6.16

NAM$8_NOP FIELD

6-7
ix

Contents

6.17

NAM$L_RLF FIELD

6-8

6.18

NAM$L_RSA FIELD

6-9

6.19

NAM$B_RSL FIELD

6-9

6.20

NAM$B_RSS FIELD

6-9

6.21

NAM$B_TVPE AND NAM$L_TVPE FIELDS

6-9

6.22

NAM$B_VER AND NAM$L_VER FIELDS

6-10

6.23

NAM$L_WCC FIELD

6-10

CHAPTER 7 RECORD ACCESS BLOCK (RAB)

7-1

7.1

SUMMARY OF FIELDS

7-1

7.2

RAB$B_BID FIELD

7-2

7.3

RAB$L_BKT FIELD

7-2

7.4

RAB$B_BLN FIELD

7-3

7.5

RAB$L_CTX FIELD

7-3

7.6

RAB$L_FAB FIELD

7-3

7.7

RAB$W_ISI FIELD

7-3

7.8

RAB$L_KBF FIELD

7-3

7.9

RAB$B_KRF FIELD

7-4

7.10

RAB$B_KSZ FIELD

7-4

Contents

7.11

RAB$B_MBC FIELD

7-5

7.12

RAB$B_MBF FIELD

7-6

7.13

RAB$L_PBF FIELD

7-7

7.14

RAB$B_PSZ Fl ELD

7-7

7.15

RAB$B_RAC FIELD

7-7

7.16

RAB$L_RBF FIELD

7-8

7.17

RAB$W_RFA FIELD

7-9

7.18

RAB$L_RHB FIELD

7-9

7.19

RAB$L_RQP FIELD

7-10

7.20

RAB$W_RSZ FIELD

7-20

7.21

RAB$L_STS FIELD

7-20

7.22

RAB$L_STV FIELD

7-20

7.23

RAB$B_TMO FIELD

7-21

7.24

RAB$L_UBF FIELD

7-21

7.25

RAB$W_USZ FIELD

7-21

7.26

RAB$L->CAB FIELD

7-22

Contents

CHAPTER 8 ALLOCATION CONTROL XAB (XABALL)
8.1

SUMMARY OF FIELDS

8-1

8.2

XAB$B_AID FIELDS

8-2

8.3

XAB$B_ALN FIELD

8-2

8.4

XAB$L_ALQ FIELD

8-3

8.5

XAB$B_AOP FIELD

8-4

8.6

XAB$B_BKZ FIELD

8-5

8.7

XAB$B_BLN FIELD

8-5

8.8

XAB$B_COD FIELD

8-6

8.9

XAB$W_DEQ FIELD

8-6

8.10

XAB$L_LOC FIELD

8-6

8.11

XAB$L_NXT FIELD

8-6

8.12

XAB$W_RFI FIELD

8-7

8.13

XAB$W_VOL FIELD

8-7

CHAPTER 9 DATE AND TIME XAB (XABDAT)

xii

8-1

9-1

9.1

SUMMARY OF FIELDS

9-1

9.2

XAB$Q_BDT FIELD

9-2

9.3

XAB$B_BLN FIELD

9-2

Contents

9.4

XAB$Q_CDT FIELD

9-3

9.5

XAB$B_COD FIELD

9-3

9.6

XAB$Q_EDT FIELD

9-3

9.7

XAB$L_NXT FIELD

9-3

9.8

XAB$Q_RDT FIELD

9-3

9.9

XAB$W_RVN FIELD

9-3

CHAPTER 10 FILE HEADER CHARACTERISTIC XAB (XABFHC)

10-1

10.1

SUMMARY OF FIELDS

10-1

10.2

XAB$B_ATR FIELD

10-2

10.3

XAB$B_BKZ FIELD

10-3

10.4

XAB$B_BLN FIELD

10-3

10.5

XAB$B_COD FIELD

10-3

10.6

XAB$W_DXQ FIELD

10-3

10.7

XAB$L_EBK FIELD

10-4

10.8

XAB$W_FFB FIELD

10-4

10.9

XAB$W_GBC FIELD

10-4

10.10

XAB$L_HBK FIELD

10-4

10.11

XAB$B_HSZ FIELD

10-4
xiii

Contents

10.12

XAB$W_LRL FIELD

10-5

10.13

XAB$W_MRZ FIELD

10-5

10.14

XAB$L_NXT FIELD

10-5

10.15

XAB$B_RFO FIELD

10-5

10.16

XAB$L_SBN FIELD

10-6

10.17

XAB$W_VERLIMIT FIELD

10-6

ITEM LIST XAB (XABITM)

11-1

CHAPTER 11
11.1
11.1.1
11.1.2
11.1.3
11.1.4
11.1.5

SUMMARY OF FIELDS
XAB$B_BLN Field
XAB$B_COD Field
XAB$L_ITEMLIST Field
XAB$L_MODE Field
XAB$NXT Field

11-2
11-2
11-2
11-2
11-2
11-2

11.2

NETWORK FILE ACCESS ITEMS

11-3

11.3

VMS RMS PERFORMANCE MONITORING

11-9

CHAPTER 12 JOURNALING XAB (XABJNL)

12-1

CHAPTER 13 KEY DEFINITION XAB (XABKEY)

13-1

xiv

13.1

SUMMARY OF FIELDS

13-1

13.2

XAB$8_BLN FIELD

13-2

13.3

XAB$B_COD FIELD

13-2

Contents

13.4

XAB$L_COLNAM FIELD

13-3

13.5

XAB$L_COLSIZ FIELD

13-3

13.6

XAB$L_CQLTBL FIELD

13-3

13.7

XAB$B_DAN FIELD

13-4

13.8

XAB$B_DBS FIELD

13-4

13.9

XAB$W_DFL FIELD

13-4

13.10

XAB$B_DTP FIELD

13-5

13.11

XAB$L_DVB FIELD

13-7

13.12

XAB$B_FLG Fl ELD

13-8

13.13

XAB$B_IAN FIELD

13-10

13.14

XAB$B_IBS FIELD

13-10

13.15

XAB$W_IFL FIELD

13-10

13.16

XAB$L_KNM FIELD

13-11

13.17

XAB$B_LAN FIELD

13-11

13.18

XAB$B_LVL FIELD

13-12

13.19

XAB$W_MRL FIELD

13-12

13.20

XAB$B_NSG FIELD

13-12

13.21

XAB$B_NUL FIELD

13-12

Contents

13.22

XAB$L_NXT FIELD

13-12

13.23

XAB$W_POSO THROUGH XAB$W_POS7 FIELD

13-13

13.24

XAB$B_PROLOG FIELD

13-13

13.25

XAB$B_REF Fl ELD

13-14

13.26

XAB$L_RVB FIELD

13-14

13.27

XAB$B_SIZO THROUGH XAB$B_SIZ7 FIELD

13-14

13.28

XAB$B_TKS FIELD

13-15

CHAPTER 14 PROTECTION XAB (XABPRO}

xvi

14-1

14.1

SUMMARY OF FIELDS

14-1

14.2

XAB$L_ACLBUF FIELD

14-2

14.3

XAB$L_ACLCTX FIELD

14-2

14.4

XAB$W_ACLLEN FIELD

14-3

14.5

XAB$W_ACLSIZ FIELD

14-3

14.6

XAB$L__ACLSTS FIELD

14-3

14.7

XAB$B_BLN FIELD

14-4

14.8

XAB$B_COD FIELD

14-4

14.9

XAB$W_GRP FIELD

14-4

14.10

XAB$W_MBM FIELD

14-5

Contents

14.11

XAB$B_MTACC FIELD

14-5

14.12

XAB$L_NXT FIELD

14-5

14.13

XAB$W_PRO FIELD

14-6

14.14

XAB$B_PROT_OPT FIELD

14-7

14.15

XAB$L_UIC FIELD

14-8

CHAPTER 15 REVISION DATE AND TIME XAB (XABRDT)

15-1

15.1

SUMMARY OF FIELDS

15-1

15.2

XAB$B_BLN FIELD

15-2

15.3

XAB$B_COD FIELD

15-2

15.4

XAB$L_NXT FIELD

15-2

15.5

XAB$Q_RDT FIELD

15-3

15.6

XAB$W_RVN FIELD

15-3

CHAPTER 16 RECOVERY UNIT XAB (XABRU)

16-1

CHAPTER 17 SUMMARY XAB (XABSUM)

17-1

17.1

SUMMARY OF FIELDS

17-1

17.2

XAB$B_BLN FIELD

17-1

17.3

XAB$B_COD FIELD

17-2

xvii

Contents

17.4

XAB$B_NOA FIELD

17-2

17.5

XAB$B_NOK FIELD

17-2

17.6

XAB$L_NXT FIELD

17-2

17.7

XAB$W_PVN FIELD

17-2

CHAPTER 18 TERMINAL XAB (XABTRM)

18-1

18.1

SUMMARY OF FIELDS

18-1

18.2

XAB$B_BLN Fl ELD

18-2

18.3

XAB$B_COD FIELD

18-2

18.4

XAB$L_ITMLST FIELD

18-2

18.5

XAB$W_ITMLST_LEN FIELD

18-3

18.6

XAB$L_NXT FIELD

18-3

VMS RMS SERVICES
$CLOSE
$CONNECT
$CREATE
$DELETE
$DISCONNECT
$DISPLAY
$ENTER
$ERASE
$EXTEND
$FIND
$FLUSH
$FREE
$GET
xviii

RMS-3
RMS-6
RMS-10
RMS-21
RMS-23
RMS-25
RMS-29
RMS-32
RMS-35
RMS-38
RMS-43
RMS-45
RMS-47

Contents

$NXTVOL
$OPEN
$PARSE
$PUT
$READ
$RELEASE
$REMOVE
$RENAME
$REWIND
$SEARCH
$SPACE
$TRUNCATE
$UPDATE
$WAIT
$WRITE

RMS-55
RMS-58
RMS-66
RMS-70
RMS-76
RMS-79
RMS-81
RMS-85
RMS-89
RMS-91
RMS-95
RMS-97
RMS-99
RMS-102
RMS-104

APPENDIX A VMS RMS COMPLETION STATUS CODES

A-1

APPENDIX B RMS CONTROL BLOCK MACROS
$FAB
$FAB_STORE
$NAM
$NAM_STORE
$RAB
$RAB_STORE
$XABALL
$XABALL_STORE
$XABDAT
$XABDAT_STORE
$XABFHC
$XABFHC_STORE
$XABITM
$XABKEY
$XABKEV_STORE
$XABPRO
$XABPRO_STORE
$XABRDT
$XABRDT_STORE
$XABSUM
$XABSUM_STORE

B-1
B-2
B-4
B-6
B-7
B-9
B-11
B-13
B-14
B-15
B-16
B-17
B-18
B-19
B-20
B-22
B-24
B-26
B-27
B-28
B-29
B-30

xix

Contents

$XABTRM
$XABTRM_STORE

B-31
B-32

INDEX

EXAMPLES
3-1

Use of the $XABDAT and $XABDAT_STORE Macros

3-9

4-1

Use of the Create, Open, and Close Services

4-2

Use of the Create Service for an Indexed File

4-5

4-3

Wildcard Processing Using Parse and Search Services

4-10

4-4

Use of the Connect Service and Multiple Keys

4-13

4-5

Use of the Rename Service

4-15

4-6

Use of the Get and Put Services

4-17

4-7

Use of the Delete Service

4-19

4-8

Use of the Update Service

4-21

4-9

Use of Block 1/0

4-25

11-1

Using XABITM to Enable VMS RMS Statistics

11-10

FIGURES
2-1

Argument List Format

2-5

11-1

Item Descriptor Data Structure

11-1

14-1

File Protection Field

14-6

3-1

User Control Blocks

3-2

VMS RMS Services

3-3

File, Record, and Block 1/0 Processing Macros

3-12

5-1

FAB Fields

5-1

5-2

Device Characteristics

5-7

5-3

File Processing Options

5-12

5-4

Maximum Record Size for File Organizations and Record
Formats

5-22

6-1

NAM Block Fields

6-1

6-2

NAM$L_FNB Status Bits

6-6

7-1

RAB Fields

7-1

TABLES

Contents

7-2

Record Processing Options

7-10

8-1

XABALL Fields

8-1

9-1

XABDAT Fields

9-1

9-2

Services and the XABDA T Control Block

9-2

10-1

XABFHC Fields

10-1

11-1

XABITM Fields

11-2

XABITM Item List

11-3

System Networking Capabilities

11-8

13-1

XABKEY Fields

13-1

14-1

XABPRO Fields

14-1

15-1

XABRDT Fields

15-2

17-1

XABSUM Fields

17-1

18-1

XABTRM Fields

18-1

RMS-1

Close Service FAB and XAB Input Fields

RMS-4

RMS-2

Close Service FAB and XAB Output Fields

RMS-5
RMS-8

RMS-3

Connect Service RAB Input Fields

RMS-4

Connect Service RAB Output Fields

RMS-8

RMS-5

Create Service FAB and XAB Input Fields

RMS-11

RMS-6

Create Service FAB and XAB Output Fields

RMS-15

RMS-7

Create Service NAM Block Input Fields

RMS-16

RMS-8

Create Service NAM Block Output Fields

RMS-17

RMS-9

Delete Service RAB Input Fields

RMS-22

RMS-10

Delete Service RAB Output Fields

RMS-22

RMS-11

Disconnect Service RAB Input Fields

RMS-24

RMS-12

Disconnect Service RAB Output Fields

RMS-24

RMS-13

Display Service FAB and NAM Input Fields

RMS-26

RMS-14

Display Service FAB, NAM, and XAB Output Fields

RMS-26

RMS-15

Enter Service FAB and NAM Input Fields

RMS-30

RMS-16

Enter Service FAB and NAM Output Fields

RMS-30

RMS-17

Erase Service FAB and NAM Input Fields

RMS-33

RMS-18

Erase Service FAB and NAM Output Fields

RMS-34

RMS-19

Extend Service FAB Input Fields

RMS-36

RMS-20

Extend Service FAB Output Fields

RMS-36

RMS-21

Find Service RAB Input Fields

RMS-39

RMS-22

Find Service RAB Output Fields

RMS-41

RMS-23

Flush Service RAB Input Fields

RMS-44

RMS-24

Flush Service RAB Output Fields

RMS-44

RMS-25

Free Service RAB Input and Output Fields

RMS-46

RMS-26

Get Service RAB Input Fields

RMS-50

RMS-27

Get Service RAB Output Fields

RMS-53
xxi

Contents

xxii

RMS-28

Next Volume Service RAB Input and Output Fields

RMS-57

RMS-29

Open Service FAB and XAB Input Fields

RMS-59

RMS-30

Open Service FAB and XAB Output Fields

RMS-61

RMS-31

Open Service NAM Block Input Fields

RMS-63

RMS-32

Open Service NAM Block Output Fields

RMS-64

RMS-33

Parse Service FAB and NAM Block Input Fields

RMS-67

RMS-34

Parse Service FAB and NAM Block Output Fields

RMS-68

RMS-35

Put Service RAB Input Fields

RMS-73

RMS-36

Put Service RAB Output Fields

RMS-74

RMS-37

Read Service RAB Input Fields

RMS-77

RMS-38

Read Service RAB Output Fields

RMS-77

RMS-39

Release Service RAB Input and Output Fields

RMS-80

RMS-40

Remove Service FAB and NAM Block Input Fields

RMS-82

RMS-41

Remove Service FAB and NAM Block Output Fields

RMS-83

RMS-42

Rename Service FAB and NAM Block Input Fields

RMS-87

RMS-43

Rename Service FAB and NAM Block Output Fields

RMS-87

RMS-44

Rewind Service RAB Input Fields

RMS-90

RMS-45

Rewind Service RAB Output Fields

RMS-90

RMS-46

Search Service FAB and NAM Block Input Fields

RMS-92

RMS-47

Search Service FAB and NAM Block Output Fields

RMS-93

RMS-48

Space Service RAB Input Fields

RMS-96

RMS-49

Space Service RAB Output Fields

RMS-96

RMS-50

Truncate Service RAB Input Fields

RMS-98

RMS-51

Truncate Service RAB Output Fields

RMS-98

RMS-52

Update Service RAB Input Fields

RMS-100

RMS-53

Update Service RAB Output Fields

RMS-101

RMS-54

Wait Service RAB Input and Output Fields

RMS-102

RMS-55

Write Service RAB Input Fields

RMS-105

RMS-56

Write Service RAB Output Fields

RMS-105

A-1

Completion Status Hexadecimal Values and Codes

A-3

A-2

Descriptions of VMS RMS Completion Status Codes

A-9

Preface
Intended Audience
This document describes VMS RMS control blocks and services for
programmers.

Document Structure
This document consists of three parts and two appendixes.
•

Part I contains general information in four sections:
Chapter 1 introduces the reader to VMS RMS functions and
associated control blocks.
Chapter 2 discusses the VMS RMS program interface that applies to
using any VAX programming language.
Chapter 3 describes the program interface with VAX MACRO,
including how to use VMS RMS macros. This information will also be
of interest to advanced programmers using other VAX programming
languages.
Chapter 4 describes the groups of VMS RMS services and provides
VMS RMS example programs using VAX MACRO.

•

Part II describes the VMS RMS control blocks and their associated fields,
in Chapter 5 through Chapter 18. This information is intended for a
programmer using any VAX programming language.

•

Part III describes the VMS RMS services, including the control block fields
accessed by each service. This information is intended for a programmer
using any VAX programming language.

•

Appendix A lists VMS RMS messages.

•

Appendix B contains the formats and associated usage notes for the VMS
RMS control block initialization and store macros used by VAX MACRO
programmers. Note that this material was formerly located in Part III.

Associated Documents
The following documents contain information related to this reference
manual:
•

The Introduction to VMS System Routines and the VMS System Services
Volume contain information about the calling routines on a VMS system.

•

The Guide to VMS File Applications contains related information about
VAX RMS, FDL, and the use of files.

•

The VMS Networking Manual discusses the support of VMS RMS options
for remote file access to non-VMS systems. For example, when the
remote system is a PDP-11 system running RMS-11, Prolog 3 index files
are not supported and some VMS RMS key definition XAB fields, as well
as other control block fields, are not fully supported.
xxiii

Preface

For additional information about remote file access between VMS systems,
see the VMS I/O User's Reference Volume.

Conventions
Convention

Meaning
In examples, a key name (usually abbreviated)
shown within a box indicates that you press
a key on the keyboard; in text, a key name is
not enclosed in a box. In this example, the key
is the RETURN key. (Note that the RETURN
key is not usually shown in syntax statements
or in all examples; however, assume that you
must press the RETURN key after entering a
command or responding to a prompt.)

xx iv

CTRL/C

A key combination, shown in uppercase with a
slash separating two key names, indicates that
you hold down the first key while you press the
second key. For example, the key combination
CTRL/C indicates that you hold down the key
labeled CTRL while you press the key labeled C.
In examples, a key combination is enclosed in a
box.

$SHOW TIME
05-JUN-1988 11 :55:22

In examples, system output (what the system
displays) is shown in black. User input (what
you enter) is shown in red.

$ TYPE MYFILE.DAT

In examples, a vertical series of periods, or
ellipsis, means either that not all the data that
the system would display in response to a
command is shown or that not all the data a
user would enter is shown.

input-file, ...

In examples, a horizontal ellipsis indicates
that additional parameters, values, or other
information can be entered, that preceding
items can be repeated one or more times, or
that optional arguments in a statement have
been omitted.

[logical-name]

Brackets indicate that the enclosed item is
optional. (Brackets are not, however, optional
in the syntax of a directory name in a file
specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer
to double quotation marks ("). The term
apostrophe ( 1 ) is used to refer to a single
quotation mark.

Preface

Convention

Meaning

lowercase letters and words

Lowercase letters and words used in format
statements in this manual represent information
that you must supply. Such lowercase
information may contain hyphens for readability.
The accompanying text defines the information
to be supplied. For example:

window-size
address
uppercase letters and words

Uppercase letters and words, equal signs (= ),
angle brackets ( < > ), and dollar signs ( $)
must be coded as shown. For example:

RAT=<BLK,CR>
$OPEN

Information enclosed within braces indicates
that you may choose any one of the enclosed
values.
FIX

For example: RFM=

STM
STMCR
STMLF
UDF
VAR
VFC

xxv

Preface

Convention

Meaning

[]

Arguments enclosed within square brackets are
optional, but if an optional argument other than
a trailing optional argument is omitted, you must
include a place holder for the omitted argument.
This rule is shown syntactically below:

$OPEN

INF AB [, [ERR] [, SUC]]

If you use either or both of the optional
arguments, you must include the comma shown
in the outside set of brackets. This comma
acts as a delimiter between the first and second
arguments when you use the second argument.
When you omit the second argument and use
the third argument, this comma acts as a place
holder for the omitted argument. If you do not
use either of the optional arguments, you can
omit the comma.
Here is an example of an instance in which the
first optional argument is used and the second
is omitted:

$OPEN

INFAB,ERR

Here is an example of an instance in which the
second optional argument is used and the first
is omitted:

$OPEN

INFAB,,SUC

Here is an example of an instance in which only
the required argument is used:

$OPEN

xxvi

INFAB

New and Changed Features
•

Enhancements to the DAP /FAL interface
DAP and FAL are the components of VMS RMS that extend record and
file access through the network. The new features provide you with
information about accessing files and records across a network including
parameters that affect performance, functionality with other VMS systems,
and functionality with non-VMS systems.
To implement the enhancements, you open a file with a new XAB called
the XABITM. You declare a XABITM in the same manner as other XABs
and you select the appropriate features by means of fields within the
XABITM structure.
Most of the network file access controls are implemented explicitly
through XABITM in conjunction with either the $CREATE service or the
$OPEN service. Informational functions are implemented explicitly with
the $DISPLAY service and implicitly with $CREATE and $OPEN.

•

Performance monitoring enhancements
You can also use the XABITM to gather RMS performance statistics by
way of the Monitor Utility. To gather statistics for an RMS file, you must
create the file with a XABITM that enables statistics by way of the related
item list. You can also enable statistics gathering from either the FDL
or the DCL interface. If statistics gathering is enabled, it can only be
disabled from DCL.

•

Enhancements to RMS multinational keys
The enhancements to the RMS multinational key functions provide a way
to use alternative (non-ASCII) collating sequences. The multinational
key enhancements are based on the National Character Set Utility that
permits you to define alternative collating sequences for special characters
and to establish and maintain libraries of collating sequences. This
eliminates having to redefine an alternative collating sequence when the
application requires it. For information on NCS, see the VMS National
Character Set Utility Manual.
The use of multinational keys requires the setting up of user-specified
collating sequences for multinational characters on a per-key basis. With
these collating keys, a record field can be sorted according to several
languages where each language has its own key of reference.

•

Enhanced Asynchronous Interface
The FAB$V_ASY option has been added to the VMS RMS asynchronous
interface to support file operations. File operations and record operations
can request notification of the synchronous completion of asynchronous
operations with the FAB$V_SYNCSTS option or the RAB$V_SYNCSTS
option, respectively.

xxvii

General Information About VMS Record
Management Services
Part I introduces the reader to general mechanisms and conventions
associated with VMS Record Management Services (VMS RMS). It
discusses the following topics:
•

Argument passing

•

Control blocks

•

Symbols defined by VMS RMS

•

Invoking VMS RMS services

•

VMS RMS macros used by VAX MACRO programs

•

Syntax conventions for VAX MACRO

•

Example programs in VAX MACRO

Introduction to VMS RMS

This section presents an overview of the general functions available through
VMS Record Management Services (VMS RMS). It also briefly describes the
VMS RMS services and control blocks. Unless otherwise stated, the term
RMS refers to VMS RMS.

1 .1

VMS RMS Functions
VMS RMS is a set of generalized services that assist application programs in
processing and managing files and their contents. VAX MACRO programs
can invoke these services by using the corresponding macros supplied in
the system library SYS$LIBRARY:STARLET.MLB. (VMS RMS automatically
searches this library for unresolved references when you assemble a source
program.) Other VAX languages may support a similar means of invoking
VMS RMS services.
Although VMS RMS supports unit-record devices, such as terminals and
printers, it primarily provides a comprehensive software interface to mass
storage devices, such as disk and magnetic tape drives.
VMS RMS provides a variety of disk file organizations, record formats, and
record access modes from which you can select the processing techniques
best suited to your application. VMS RMS supports sequential, relative, and
indexed file organizations, and fixed-length and variable-length record formats
are supported for each file organization. (Relative and sequential files also
support other record formats.) The VMS RMS record access modes permit
you to access records within these files sequentially, directly by key value,
directly by relative record number, or directly by record file address (RFA).
VMS RMS also provides a means of performing block 1/0 operations to
support users with certain performance-critical applications (such applications
may require user-defined file organizations and/or record formats).
VMS RMS ensures safe and efficient file sharing by providing
•

Multiple file access modes, to allow file sharing to be consistent with the
file operations

•

Automatic record locking in applicable file access modes, to ensure data
integrity during record updates

•

Optional buffer sharing by multiple processes accessing the same file, to
minimize 1/0 operations

VMS RMS also enforces the security requirements of a multiuser system with
potential multinode access by restricting file access to one or more user UIC
types and to a list of user names.
For systems that support DECnet network capabilities, VMS RMS provides
a subset of file and record management services through the Data Access
Protocol (DAP) to remote network nodes. Network DAP remote file
operations are generally transparent to application programs.

1-1

Introduction to VMS RMS
1 .2 Passing Arguments to VMS RMS

1 .2

Passing Arguments to VMS RMS
The flexibility inherent in VMS RMS would require application programs to
pass a multitude of arguments to perform such common operations as file
creation and access. To eliminate the potential problems associated with
passing numerous arguments for each service call, the application program
places the arguments in one or more data control blocks before it invokes any
VMS RMS service. The only argument required to invoke most VMS RMS
services is the symbolic address of the appropriate data control block.

1.2.1

VMS RMS Services and Control Blocks
Because VMS RMS operates on files and records, its services generally fall
into one of two groups:
•

File services that create and access a new file, access (open) an existing
file, extend the disk space allocated to a file, close a file, obtain file
characteristics, and perform other functions related to files

•

Record services that get, find (locate), put (insert), update, and delete
records, and perform other operations not directly related to record I/O,
such as associating one or more record streams (methods of accessing
records) with an open file

To support service operations, VMS RMS provides two types of control
blocks:

1.2.2

•

Control blocks that provide file-related arguments to VMS RMS file
services

•

Control blocks that provide record-related arguments to VMS RMS record
services

Control Blocks for File Services
File services use a control block called the file access block (FAB). When
creating a file, the user must store arguments in the FAB that define the
file characteristics, the file specification, and certain run-time access options.
When your process opens an existing file, the FAB specifies only the file
specification and the run-time access options.
There are three categories of FAB arguments and the following list briefly
introduces each:

1-2

•

File specification arguments identify primary and default file
specifications used at run-time to locate the file.

•

File characteristics arguments specify the file organization, record type,
allocation information, and other information.

•

Run-time access options specify the operations that can be done by
the initiating process and the operations that can be done by sharing
processes, a variety of file-processing options, and the address (or
addresses) of one or more control blocks whose fields supplement or
supersede the information in the FAB.

Introduction to VMS RMS
1.2 Passing Arguments to VMS RMS

The two types of optional control blocks that can supplement or supersede
the information in the FAB are the name block (NAM) and the extended
attribute block (XAB).
The NAM block supplements the file specification information available in
a FAB. It is especially useful for locating and opening files when the file
specification is entered by an interactive user or when a file specification
includes a wildcard character or a search list logical name representing
multiple files.
There is only one type of NAM block, and you usually associate only one
NAM block with a file. To provide an extra level of defaults for a file
specification, however, VMS RMS will apply defaults using additional NAM
blocks that contain the file specifications of related files.
A XAB usually supersedes and supplements the file characteristics specified
in the associated FAB and multiple XABs may be used to support a single
file. There are several types of XABs, each of which is used for a different
purpose. Each type of XAB has a 6-letter mnemonic name consisting of
the prefix "XAB" followed by a 3-letter mnemonic that relates to the XAB
function. For instance, the XAB that supplements and supersedes the file
allocation information in the FAB is called an allocation control XAB, or
XABALL.
The XABs used for file operations are briefly described in the following list:
•

Allocation control XAB (XABALL)-allows greater control over disk file
allocation and positioning during file allocation.

•

Date and time XAB (XABDAT)-specifies date and time values for backup,
creation, expiration, and revision times, and the revision number.

•

File header characteristic XAB (XABFHC)-receives the file characteristics
information contained in the file header block.

•

Item list XAB (XABITM)-provides a convenient means for using item
lists to pass information between RMS and the application program.

•

Journaling XAB (XABJNL)-supports file journaling operations.

•

Key definition XAB (XABKEY)-defines the key characteristics to be
associated with an indexed file.

•

File protection XAB (XABPRO)-defines file protection characteristics
that specify what class of users or list of users can have certain specified
access rights. For ANSI magnetic tape files using HDRl labels, this XAB
specifies the accessibility field character.

•

Revision date and time XAB (XABRDT)-specifies the revision date and
time value and the revision number associated with a file.

•

Recovery unit XAB (XABRU)-supports the use of recovery units to
assure data file integrity.

•

Summary XAB (XABSUM)-stores additional file characteristics associated
with an indexed file.

1-3

Introduction to VMS RMS
1 .2 Passing Arguments to VMS RMS

1.2.3

Control Blocks for Record Services
Record services use a control block known as the record access block, or RAB.
Some of the arguments the user must store in the RAB include the address of
the related FAB, the address of input and output record buffers, the type and
size of general I/O buffers, whether a file's records will be accessed directly
or sequentially, certain tuning options, and other information.
An extended attribute block (XAB) can both supersede and supplement the
record characteristics specified in the RAB. As with a XAB that supersedes
and supplements a FAB, a XAB that supersedes and supplements a RAB has
a 6-letter mnemonic name consisting of the prefix "XAB" followed by three
letters. Note that there are only two XAB types for record operations, the
terminal XAB (XABTRM) and the recovery unit XAB (XABRU).
The XABTRM defines the symbolic address and length of a user-supplied
argument list that defines the terminal operation and provides more flexibility
than using RAB fields.
See the VAX RMS Journaling Manual for details relating to the use of the
XABRU.

1.2.4

The Dual Purpose of Control Blocks
Control blocks provide input to VMS RMS services and they provide output
from VMS RMS services including the following run-time information:
•

Detailed file characteristics, including file organization, record format, and
record size

•

Device characteristics

•

File, directory, and device identifiers

•

The address (location) and length of a requested record

•

Returned condition values

For this reason, certain programs specifically allocate a NAM block or one
or more XABs dedicated to receiving information returned by VMS RMS
services. Typically, such information can be examined to determine how the
file should be processed.
In most cases, however, control blocks are used both to transmit and to
receive information between the application program and VMS RMS and
should not be located in a read-only program section.
Be sure that control block fields not currently used by a particular service
have valid default values because future versions of VMS RMS may use
them. This applies also to control block fields that are currently described
as "ignored for DECnet operations" because future versions of VMS RMS or
DECnet may support those fields.

1-4

The Program Interface with VMS RMS

This section introduces the application program interface with VMS RMS that
is applicable to all VAX languages in terms of the following:

2.1

•

The VMS RMS run-time processing environment

•

VMS RMS symbol-naming conventions

•

The calling sequence for VMS RMS services

•

Allowable program execution modes

•

Condition values returned by VMS RMS services

The Run-Time Environment and VMS RMS Programming
The VMS RMS run-time processing environment consists of a set of blocks
and the run-time services. The control block fields accessed by each service
specify to VMS RMS the appropriate file and record operations. Depending
on the operation, VMS RMS uses one or more control blocks by referring to
one or more fields as input to, or output from, the operation.
To use VMS RMS, you must do the following:
1

Allocate the appropriate control block, usually at assembly time or
compilation time. Control blocks must not reside in read-only storage
and should be aligned on a longword boundary to maximize efficiency.

Insert the appropriate values into the control block fields before you
invoke the related service.

Invoke the appropriate VMS RMS service. As part of this step, a
condition value should always be examined.

To perform advanced VMS RMS functions, you may need to set various
control block field values at run time between the time the file is opened and
when the VMS RMS service is invoked.
Note that VAX languages perform some of these steps transparently when a
particular language statement or macro is present in a source program.
Two fields in each control block, the block length (BLN) field and the block
identifier (BID) (or block code (COD) field in a XAB), define the length of
the control block (in bytes) and identify the control block type, respectively.
These internal VMS RMS fields are always used as input arguments by the
VMS RMS service that accesses the control block and must be set before
the control block can be used. The fields are initialized automatically by
the appropriate VAX MACRO assembly-time initialization macro and must
contain the correct value for the type of control block. After the block length
and block identifier fields are established, you must treat them as read-only
fields until the control block is no longer needed.
Part II describes each control block field in detail, including its length and its
symbolic name.

2-1

The Program Interface with VMS RMS
2.1 The Run-Time Environment and VMS RMS Programming

Appendix B lists the VAX MACRO calling format for each VAX MACRO
control block macro.
Part III lists the calling format for each service together with the input control
block fields and the output control block fields for each service.

2.2

Conventions for Naming Fields
VMS RMS uses mnemonic names to identify control block fields. For
example, the mnemonic name for the FAB allocation quantity field is ALQ.
The mnemonic name (usually consisting of three characters) serves as a suffix
to a symbolic name that identifies the location of each control block field.
You should use the symbolic names to be sure you place values in the correct
control block fields. VMS RMS defines each symbolic name as a constant
value equal to the offset, in bytes, from the beginning of the control block to
the beginning of the field. These field names are thus called symbolic offsets.
Symbolic offset names are defined when the appropriate VAX MACRO control
block initialization macro is used, when the appropriate VAX MACRO control
block symbol definition macro is used, and when some VAX languages invoke
VMS RMS. Alternatively, all control block symbolic offset names are available
when you use the VAX MACRO $RMSDEF macro in a VAX MACRO program
or procedure.
The format of the symbolic offsets consists of a 3-letter control block identifier
(FAB, NAM, XAB, or RAB), a dollar sign ($),a I-letter indicator of the length
of the field (B, W, L, Q, or T), an underscore ( _ ), and the field mnemonic,
which is usually three letters.
The general format of the symbolic offset is shown in the following example:
ccc$x_fff

The components of the symbolic offset format are summarized in the
following table.

2-2

The Program Interface with VMS RMS
2.2 Conventions for Naming Fields

Component

Length

Description

ccc

3 letters

Identifies the type of control block:
FAB, NAM, XAB (for all XABs), or
RAB.

1 character

Separates the control block
identifier from the field length
identifier; a dollar sign ( $).

1 letter

Identifies the length of the field:
B for byte, W for word, L for
longword, Q for quadword, T for
text buffer address. Symbolic
length fields are identified by
the letter S in this position. For
example, the value field XAB$S_
CACHE_TMO specifies the number
of bytes allocated for defining the
value of the cache timeout. See
text for exceptions.

1 character

Separates the field length identifier
from the field name; always an
underscore(_).

3 or more letters

Identifies the mnemonic name
of the field, which is used in the
VAX MACRO control block macro.
Some mnemonics contain more
than three letters; for example,
symbolic offset XAB$B_PROLOG
(from XABKEY).

fff

For example, the FAB field whose mnemonic is ALQ has a length of one
longword and is identified by the symbolic offset FAB$L_ALQ. The field
NAM$L_RLF is a NAM longword field whose mnemonic RLF reflects its
name, the related file field.
Exceptions to the length designation are NAM$W_DID, NAM$W_FID,
XAB$W_RFI, and RAB$W_RFA. These symbolic offsets mark the locations of
fields that are three words, not one word.
The length of a T field is specified by the corresponding S field; for example,
the length of the NAM$T_DVI field is specified by the symbolic value field
named NAM$S_DVI.
When a control block field contains options identified by bits, each valid bit
location has a symbolic offset name. Certain control block fields are binary
options fields consisting of bit values. For these bits in a binary options field,
the format of symbolic names resembles the format of the field names, except
for the length indicator. Instead of identifying the field length, which is
always one bit, the length field indicates whether a mask value ( M) or bit
offset (V) is defined by the symbolic name, as described below.

2-3

The Program Interface with VMS RMS
2.2 Conventions for Naming Fields

Format

Description

xxx$M_fff

Indicates a mask value in a binary options field, typically where
multiple bit options can be chosen. Used to set or clear bit
values.

xxx$V_fff

Indicates the symbolic bit offset (number of bits from the
beginning of the binary options field). Used to test bit values or
to set bit values.

The xxx identifies the control block (FAB, NAM, XAB, or RAB); the$ and_
are separator characters, and the !ff defines the mnemonic for the bit option.
For example, the option CTG in the FAB file-processing options (FOP) field
has a symbolic bit offset of FAB$V_CTG and a mask value of FAB$M_CTG.
Another type of field can contain only certain values; thus there are no mask
values or symbolic bit offsets. Unlike a binary options field, each possible
value is identified by a symbolic constant value, in the following form:
xxx$C_f ff

Note that the letter C replaces the letter M, denoting that this field is a
constant (keyword) value field, not a mask value field. For example, the
file organization (ORG) field of the FAB (FAB$B_ORG) can only contain
the values FAB$C_IDX (indexed), FAB$C_REL (relative), or FAB$C_SEQ
(sequential). In some instances, the letter K is used to denote a constant
(keyword) value field in place of the letter C; otherwise, the naming
convention is the same.
When specifying control block field locations, avoid using actual byte
displacement values to identify control block field locations; instead, use the
supplied symbolic offsets. VMS RMS control block field locations may not
always be the same from release to release of VMS; however, the symbolic
offset names that identify the field locations always identify the same fields.

2.3

The VMS RMS Calling Sequence
VMS RMS uses the standard VAX calling sequence and conventions, and
preserves all general registers across a call, except for register 0 (RO) and
register 1 (Rl). When the service completes execution, it returns control to
the calling program, passing a condition value in RO. You should analyze the
completion value to determine the success or failure of the service and to alter
the flow of execution of your program, if necessary. Where applicable, you
should use the SIS field and the STY field of the appropriate control block
for signaling errors, instead of RO. For additional information about VMS
RMS completion values, see Section 2.4.
When calliQ_g a VMS RMS service, you must provide an argument list to
specify the associated control block (FAB or RAB) and, optionally, any
completion routines. The argument list is from two to four longwords in
length, as shown in Figure 2-1. (The Rename service, however, uses a
5-longword argument list.)

2-4

The Program Interface with VMS RMS
2.3 The VMS RMS Calling Sequence

Figure 2-1

Argument List Format

reserved

control block address

!- ----------------'=~ ::~'~'""~o~"."~ ~~~'
1

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

success completion routine address

-i}

optional

I
I

~-----------------------------------------------J

ZK-875-82

VMS RMS interprets the fields in the argument list as follows:

2.4

•

The argument count field contains a binary value, from 1 through 3,
representing the number of arguments in the argument list. For the
Rename service only, set this value to 4.

•

The control block address field contains the address of either the FAB (for
file operations) or the RAB (for record operations).

•

The error completion routine address field optionally contains the address
of the entry mask of a user-written completion routine to be called if the
requested operation fails. If used, the completion routine executes as an
asynchronous system trap (AST).

•

The success completion routine address field optionally contains the
address of the entry mask of a user-written completion routine to be
called if the requested operation completes successfully. If used, the
completion routine executes as an asynchronous system trap (AST).

•

The new FAB address field (not shown in Figure 2-1) contains the address
of the FAB that contains the new file name for the Rename service. This
field must be present only for the Rename service.

Condition Values
Before returning to your program from a file or record operation, VMS RMS
indicates the success or failure of the operation by setting a condition value in
the completion status code field (STS) of the associated control block (FAB or
RAB).
When first returning to your program after a call to an operation, VMS
RMS also sets general register 0 to the value in the status code field. In
asynchronous operations, register 0 may simply indicate that the operation
has been initiated.
In general, you may receive one of many error or success codes from an
operation. (The discussion of each VMS RMS service in Part III includes a
list of the possible condition values that you can receive.) (See Appendix A
for a complete list of all VMS RMS status codes.) You should test for success
by checking only the low-order bit of the status code for a true condition (bit

2-5

The Program Interface with VMS RMS
2.4 Condition Values

set). The three low-order bits returned in the status code indicate the severity
of the code. The severity codes are as follows:
001 ( 1)

Success (low-order bit set).

011 ( 3)

Information (low-order bit set).

000 (0)

Warning; indicates a nonstandard condition. The operation may
have performed some, but not all, of the requested function.

010 (2)

Error; you must recognize that a problem exists and provide a
contingency plan in your program for such a condition.

100 (4)

Severe error; normally caused by program logic errors or other
unrecoverable conditions.

The usual method of testing the completion status is to examine register 0 for
success, failure, or specific completion values. For certain completion values,
VMS RMS returns additional information in the status value field (STV) of
the control block. The description of the codes in Appendix A indicates the
instances when the STV contains such information.
The STS and STV fields should be used to signal VMS RMS errors to
ensure that the error message includes all relevant information. For the
file processing and file naming services, use the STS and STV fields of
the specified FAB (use the old FAB for the Rename service). For record
processing and block I/O processing services, use the STS and STV fields of
the corresponding RAB. (Consult Table 3-2 if you are not sure of the group
to which a particular VMS RMS service belongs.)
The recommended way to signal VMS RMS errors is to provide both the STS
and STV fields of the RAB or FAB as arguments to the Run-Time Library
(RTL) routine LIB$SIGNAL (or LIB$STOP). Certain VAX languages provide
a built-in means of signaling errors, such as by providing a system-defined
function. For a more detailed explanation of condition signaling and invoking
RTL routines, see the VMS Run-Time Library Routines Volume.
VMS RMS services are considered system services for the purpose of
generating system service exceptions on errors. You can choose whether
to test and handle errors in your program or set the system service failure
exception mode (using the Set System Failure Exception Mode system service,
SYS$SETSFM) to have failures automatically signaled. For most applications,
especially if a high-level language is used, testing and handling errors in
your program is the preferred method. If you test for error conditions in
your program, you should be sure to disable any unwanted system service
exception generation.
Note that if the FAB or RAB is invalid or inaccessible, then the error
completion routine will not attempt to store the error code in the STS
field of an invalid control block structure. The following errors can be
detected only by testing RO (or by enabling system service failure exception
mode), following the completion of a VMS RMS operation (even if an error
completion AST has been specified):

2-6

The Program Interface with VMS RMS
2.4 Condition Values

RMS$_BLN

Invalid block length field (either FAB or RAB)

RMS$_BUSY

User structure (FAB/RAB) still in use

RMS$_FAB

FAB not writable or invalid block ID field

RMS$_RAB

RAB not writable or invalid block ID field

RMS$_STR

User structure (FAB/RAB) became invalid during operation

These completion codes indicate that the FAB or RAB is invalid or
inaccessible. These completion codes can only be detected and signaled
using RO, but are usually rare and, if they occur at all, would most likely
occur during initial program debugging and testing. Thus, you must examine
the completion value in RO (instead of the STS field of the FAB or RAB) for
the completion codes listed above. If necessary, your program could test for
these errors and, if encountered, signal these completion values using RO
instead of the STS and STV fields.

2.5

Allowable Program Execution Modes
Generally, VMS RMS executes in either executive mode or executive AST
mode. When a VMS RMS operation is initiated, processing begins in
executive mode. If device I/O is necessary to process the request, the $QIO
system service is called. VMS RMS specifies an executive-mode AST to
signal completion. At this point, VMS RMS exits from executive mode. If the
operation is being performed asynchronously, control is returned to the caller;
if the operation is synchronous, VMS RMS waits for an event flag in the
access mode of the caller. When the I/O is complete, VMS RMS continues
processing in executive AST mode. Thus, user-mode ASTs can be serviced
while a synchronous VMS RMS operation called from user mode is awaiting
1/0 completion. However, processing in user mode during an asynchronous
VMS RMS operation is interrupted by VMS RMS processing in executive AST
mode when I/O completes.
VMS RMS should not be called from kernel mode, from executive AST mode,
nor from executive mode when executive-mode ASTs are disabled.

2.6

Reserved Event Flags
VMS RMS uses system-reserved event flags to synchronize its internal
operations. VMS RMS reserves event flags 27, 28, 29, and 30 for possible
use; in addition, event flag 31 is used to specify a "do not care" event flag for
asynchronous processing.

2. 7

DEC Multinational Character Set
You can use any character in the DEC Multinational Character Set in VMS
RMS records, including the key value of an indexed file. Keys are collated
according to their corresponding character code value.
For a list of characters in the DEC Multinational Character Set, see the VAX

EDT Refere nee Manual.

2-7

VMS RMS Macros and VAX MACRO Programming

This chapter describes the four types of VMS RMS macros used in VAX
MACRO programming. It begins with a description of each of the four types
of macros, macro naming conventions and macro syntax rules. The remainder
of the chapter describes how to use the macros and includes examples for
each of the four types. Note that in the remainder of Part I, the use of
the term "macro" refers to a program macro written in the VAX MACRO
language.

3.1

VMS RMS Macros
VMS RMS provides four types of macros used by VAX MACRO programs
implementing VMS RMS features. The functions these macros provide are
described below.
•

Control block initialization macros initialize a control block at assembly
time. This type of macro performs five separate actions:
Allocates space within the program image for the specified control
block
Defines the symbolic names associated with a control block
Initializes certain control block fields with internally used values
Initializes specified control block fields with user-specified values
Initializes certain fields with system-supplied defaults (does not apply
to all control block macros)
As an alternative to using this type of macro, an application program
would have to allocate each control block needed with its correct
length, initialize the internally used fields with the correct values,
and initialize or set user-specified values in the appropriate fields.· It
is stzongly recommended that the supplied macros be used for VAX
MACRO programs.

•

Control block symbol definition macros define control block symbolic
names at assembly time without allocating and initializing the control
block. These macros are needed only when the corresponding
initialization macro is not used and the symbols are not defined by
the VAX language used.

•

Control block store macros set (or reset) specified fields in a control block
with user-specified values at run time. Alternatively, you can set values
in control block fields at run time using VAX MACRO instructions, such
as the MOVx and MOVAx instructions. Field locations are made available
using the symbolic name assigned to each control block field to represent
its offset from the start of the control block.

3-1

VMS RMS Macros and VAX MACRO Programming
3.1 VMS RMS Macros

•

Service macros invoke VMS RMS services at run time. When a service
is invoked, one or more control blocks are examined for required field
values. Values are also returned in one or more control blocks, including
condition codes. VMS RMS services conform to the VAX calling standard
and thus can be invoked directly from any VAX language, if needed,
without the calling program having to use the supplied macro. However,
the appropriate control block must be present with the appropriate field
values set for the requested operation.

VMS RMS stores its macros for use by VAX MACRO programs in
SYS$LIBRARY:STARLET.MLB.

3.1.1

Conventions for Naming VMS RMS Macros
The corresponding macro name that initializes each control block at assembly
time consists of a dollar sign ( $ ) followed by the name of the control block.
Thus, the macro that initializes a FAB is called $FAB; the macro that initializes
an XABALL is called $XABALL.
The macros that define symbolic offsets without performing control
block initialization contain the suffix "DEF" following the corresponding
initialization macro name; for example, $FABDEF and $XABALLDEF.
For the macros that set control block field values at run time, the name of the
assembly time macro is followed by _STORE. Thus, the $FAB macro has a
$FAB_STORE macro for setting FAB values at run time and the $XABALL
macro has a $XABALL _STORE macro for setting XABALL values at run time.
Table 3-1 summarizes the control blocks, their assembly time macro names,
and their functions.
Table 3-1
Control
Block

User Control Blocks
Macro
Names

FAB

Describes a file and contains file-related
information
$FAB

Allocates storage for a FAB and initializes
certain FAB fields; also defines symbolic offsets
for a FAB

$FABDEF

Defines symbolic offsets for a FAB

$FAB_STORE

Moves specified values into a previously
allocated and initialized FAB
Contains file specification information beyond
that in the file access block

NAM

3-2

Function

$NAM

Allocates storage for a NAM and initializes
certain NAM fields; also defines symbolic
offsets for a NAM

$NAMDEF

Defines symbolic offsets for a NAM

$NAM_STORE

Moves specified values into a previously
specified and allocated NAM

VMS RMS Macros and VAX MACRO Programming
3.1 VMS RMS Macros

Table 3-1 (Cont.)
Control
Block

User Control Blocks

Macro
Names

RAB

Describes a record stream and contains recordrelated information
$RAB

Allocates storage for a RAB and initializes
certain RAB fields; also defines symbolic offsets
for a RAB

$RABDEF

Defines symbolic offsets for a RAB

$RAB_STORE

Moves specified values into a previously
specified and allocated RAB

XAB

Function

Contains file attribute information beyond that
in the file access block; for XABTRM, contains
information beyond that in the record access
block
$XABxxx 1

Allocates and initializes an XAB

$XABxxxDEF

Defines symbolic offsets for an XABxxx

$XABxxx_STORE

Moves specified values into a previously
specified and allocated XABxxx

The variable xxx represents a 3-character mnemonic.

VMS RMS services can be called from any VAX language using the VAX
Procedure and Condition Handling standard. VMS RMS services are system
services identified by the entry point prefix "SYS$" followed by three or
more characters. In the corresponding VAX MACRO macro name, the "SYS"
prefix is not used. For example, the Create service has an entry point of
SYS$CREATE and a VAX MACRO macro name of $CREATE. A complete
description of each service is provided in Part Ill.
Table 3-2 describes the functions of each VMS RMS service, including the
service entry point name and its corresponding VAX MACRO macro name.
Table 3-2

VMS RMS Services

Service Name

Macro Name

Description

File Processing and File Naming Macros
SYS$CLOSE

$CLOSE

Terminates file processing and disconnects
all record streams

SYS$CREATE

$CREATE

Creates and opens a new file of any
organization

SYS$DISPLA Y

$DISPLAY

Returns the attributes of an open file to the
application program

SYS$ENTER 1

$ENTER

Enters a file name into a directory

SYS$ERASE

$ERASE

Deletes a file and removes its directory
entry

1 This service is not supported for DECnet operations involving remote file access between
two VMS systems.

3-3

VMS RMS Macros and VAX MACRO Programming
3.1 VMS RMS Macros

Table 3-2 (Cont.)
Service Name

VMS RMS Services

Macro Name

Description

File Processing and File Naming Macros
SYS$EXTEND

$EXTEND

Extends the allocated space of a file

SYS$0PEN

$OPEN

Opens an existing file and initiates file
processing

$PARSE

Parses a file specification

$REMOVE

Removes a file name from a directory

SYS$PARSE
SYS$REMOVE

SYS$RENAME

$RENAME

Assigns a new name to (renames) a file

SYS$SEARCH

$SEARCH

Searches a directory, or possibly multiple
directories, for a file name

Record Processing Macros
SYS$CONNECT

$CONNECT

Establishes a record stream by associating
a RAB with an open file

SYS$DELETE

$DELETE

Deletes a record from a relative or indexed
file

SYS$DISCONNECT $DISCONNECT

Terminates a record stream by
disconnecting a RAB from an open file

SYS$FIND

$FIND

Locates and positions to a record and
returns its RFA

SYS$FLUSH

$FLUSH

Writes (flushes) modified 1/0 buffers and
file attributes

SYS$FREE

$FREE

Unlocks all records previously locked by the
record stream

$GET

Retrieves a record from a file

$NXTVOL

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

SYS$PUT

$PUT

Writes a new record to a file

SYS$RELEASE

$RELEASE

Unlocks a record pointed to by the contents
of the RAB$W_RFA field

SYS$REWIND

$REWIND

Positions to the first record of a file

SYS$TRUNCATE

$TRUNCATE

Truncates a sequential file

SYS$UPDATE

$UPDATE

Rewrites (updates) an existing record in a
file

SYS$WAIT

$WAIT

Awaits the completion of an asynchronous
record operation

SYS$GET
SYS$NXTVOL

1 This service is not supported for DECnet operations involving remote file access between
two VMS systems.

3-4

VMS RMS Macros and VAX MACRO Programming
3.1 VMS RMS Macros

Table 3-2 (Cont.)
Service Name

VMS RMS Services

Macro Name

Description

Block 1/0 Processing Macros

3.1.2

SYS$READ

$READ

Retrieves a specified number of bytes from
a file, beginning on block boundaries

SYS$SPACE

$SPACE

Positions forward or backward in a file to a
block boundary

SYS$WRITE

$WRITE

Writes a specified number of bytes to a file,
beginning on block boundaries

Applicable VAX MACRO Syntax Rules
One of the conventions of VMS RMS control block macros is to use the
mnemonic name associated with each field as a keyword to identify each
argument. Using a keyword ensures the accuracy of argument value
placement regardless of the ordering you use when you code the related
argument. For example, the mnemonic keyword for the FAB field that
specifies the allocation quantity is ALQ. Thus, when using the $FAB macro
to initialize the allocation quantity field, you might use the following macro
expression:
INFAB:

$FAB

ALQ=500

This macro statement defines the start of the FAB at label (symbolic address)
INFAB and initializes the allocation field (at symbolic offset ALQ) to provide
500 blocks of space to the file being created.
In this instance, if you want to change the allocation value to 250 blocks at
run time, you could use the following macro expression:
MOVL

#250, INFAB+FAB$L_ALQ

; Set allocation quantity

In fields that contain binary options or keyword values, you should use the
appropriate keyword or symbolic binary option value. For example, the FAB
has a field at symbolic offset ORG that specifies the file organization. Three
keywords are defined for this field; SEQ (sequential file), REL (relative file)
and IDX (indexed file). To specify an indexed file organization, you should
use the following macro expression:
OUTFAB: $FAB

ORG=IDX

To set this value at run time, you must move the formal title of the value into
the formal title of the field:
MOVAL OUTFAB, R5
MOVB #FAB$C_IDX, FAB$B_ORG(R5)

; Move address into R5
; Store constant value

In control block macros, arguments for bit fields that can contain multiple
values are usually enclosed within left angle ( <) and right angle (> )
brackets. Consider the file access (FAC) field (FAB$B_FAC) in the FAB, a bit
field that can contain multiple values. To permit a process to do get and put
operations, the following macro expression could be used:
INFAB:

$FAB

FAC=<GET,PUT>

; Specify Put and Get operations

3-5

VMS RMS Macros and VAX MACRO Programming
3.1 VMS RMS Macros

Control block macro arguments that are interpreted as ASCII characters (such
as a file specification) are enclosed within left angle ( <) and right angle (> )
brackets. The use of the left angle ( <) and right angle (> ) delimiters is
noted in the format and argument descriptions of the control block macros in
Part II.
At run time, you could use the following code sequence to make the file
accessible to a Get operation:
MOVAL OUTFAB, R6
BBS
#FAB$V_GET, FAB$B_FAC(R6), OK
BISB #FAB$M_GET, FAB$B_FAC(R6)
OK:

Move addr into R6
Branch i f set
Set if not set
Complete operation

When you use VMS RMS macros, follow the coding rules used by the VAX
MACRO assembler as described in the following list:
•

Comments must be separated from the rest of the code line by a
semicolon (; ). For example:
$FAB

•

; Bucket size

All the arguments for a macro must be coded in a single statement. If the
arguments do not fit on a line or if you want to use multiple lines, type
the continuation character, a hyphen ( - ), as the last character on the line,
and then continue typing arguments on the next line. Comments can
follow the hyphen. For example:
$FAB

•

BKS=4

FNA=FLNAM.ALQ=100,BKS=4

Filename address
; Allocation quantity
; Bucket size

Arguments and subarguments can be separated from each other by one
of the following:
A comma, with or without spaces or tabs
FNA=FLNAM,ALQ=100

A space
FNA=FLNAM ALQ=100

Multiple spaces or tabs
FNA=FLNAM

ALQ=100

The comma without a space or tab is preferred. All coding examples in
this manual use a comma to separate arguments.

3.2

Using the VMS RMS Macros
This section provides examples of using the four types of VMS RMS macros.

3-6

VMS RMS Macros and VAX MACRO Programming
3.2 Using the VMS RMS Macros

3.2.1

Control Block Initialization Macros
A major advantage to using the control block initialization macros is that
they direct the initialization values to the correct field locations in the control
block. Returned status values do not apply here because RMS evaluates this
type of macro at assembly time.
The program location of a control block initialization macro defines the
beginning of the control block. Because the address of the control block is a
required argument for most services and for some control block macros, the
macro name should be preceded by a label, as shown in the following code
example:
MYFAB:

$FAB

Arguments usually require an address, such as a symbolic address, or a value.
VMS RMS initializes the appropriate field by simply taking the supplied
argument and placing it after the appropriate macro data declaration directive,
as shown in the following code example:
.ADDRESS address
.BYTE value

There are fields that must be treated as ASCII character strings or they
become values in a binary options field. Such fields must be enclosed within
left angle ( <) and right angle (> ) brackets, under the following conditions:
•

When the argument is a file specification (ASCII character string)

•

When more than one argument is supplied for a binary options field,
where each bit option is identified by a 3-letter mnemonic

•

Where otherwise indicated in the format of the macro, such as for
UICs and file identifiers in which multiple values separated by commas
constitute the argument

Here are several examples:
MYFAB:

$FAB

MYXPRD: $XABPRD

FAC=<GET, PUT>,FNM=<DEGREE_DAY.DAT>,-

Multioption field
File specification

NXT=MYXPRD,ORG=SEQ

XAB address
Single-option field

PRD=<RWED,RWED,R,R>,UIC=<377,377>

File protection
UIC

The complete format of each control block initialization macro is provided in
Appendix B, showing those arguments that must be enclosed within left angle
( <)and right angle(> ) brackets.
Do not position the macro name in a read-only program section, because
control block fields may receive values during the execution of a service. For
efficiency, align the control blocks on a longword boundary. The initialization
macros display an informational message in the listing file if the control block
is not longword aligned.
In summary, initialization macros must be placed in a writable data program
section in which the data has been aligned on a longword boundary.

3-7

VMS RMS Macros and VAX MACRO Programming
3.2 Using the VMS RMS Macros

3.2.2

Control Block Symbol Definition Macros
A control block symbol definition macro includes the macro name only and
has no arguments. The macro name has the suffix "DEF" following the name
of the initialization macro that defines all symbols in the affected control
block.
Control block symbol definition macros can be placed in any program section.
VMS RMS does not provide return values for these macros.

3.2.3

Control Block Store Macros
A control block store macro consists of executable run-time code, so it must
be placed within an executable code program section. RO cannot be used to
return condition codes because these macros may use it to move arguments.
The only detectable errors are assembly-time errors.
The calling format of each control block store macro resembles the calling
format of the corresponding initialization macro except that a control block
store macro can take a run-time value as an argument. Run-time values
include date and time values, file identifier values, device identifier values,
directory identifier values, and record file address values.
The following list describes other differences between the format of a control
block store macro and its corresponding control block initialization macro:
•

The argument for the address of the FAB, NAM block, RAB, or XAB to
receive the argument values is required. This argument can be omitted
if the control block address is contained in RO. If this argument is not
a register value in the form Rn, the control block address is loaded into
RO. This argument is not present in the corresponding control block
initialization macro.

•

For each argument that requires an address, the store macro uses the
VAX MACRO instruction MOVAx (usually MOVAL) to move the address
into the appropriate control block field. Thus, VAX MACRO expressions
can be used. For instance, you can use a symbolic address to specify
the control block address argument directly (for example, FAB=MYFAB,
NAM=MYNAM, RAB=MYRAB, or XAB=MYXAB).
You may also specify a register that contains the address using the form
Rn, where n is a decimal number from 0 through 12.

3-8

•

For each argument that requires a nonkeyword data value, the store
macro uses the VAX MACRO instruction MOVx to move data into the
appropriate control block field. Thus, VAX MACRO expressions can be
used. Note that a number sign ( #) must precede a literal nonkeyword
value, except when a literal value is enclosed within left angle ( <) and
right angle (> ) brackets. However, if you specify the address where the
argument value resides, a number sign must not precede the symbolic
address nor the register expression that contains the address.

•

For binary option or keyword value fields, use the supplied keyword
without a number sign and do not use a VAX MACRO expression.
Multiple keyword arguments must be enclosed within left angle ( <) and
right angle ( > ) brackets.

VMS RMS Macros and VAX MACRO Programming
3.2 Using the VMS RMS Macros

In some cases, arguments are specified as run-time values using one of the
following forms:
•

A VAX MACRO expression

•

The symbolic address of the argument value

The format for each store macro is provided in Appendix B, which includes
exceptions to the general rules previously described.
Example 3-1 illustrates the use of the $XABDAT_STORE macro to set
the creation date of the file to the beginning of a fiscal quarter, thereby
establishing a valid starting date for the file data.
Example 3-1

Use of the $XABDAT and $XABDAT_STORE Macros

.TITLE CREAT - SET CREATION DATE
Program that uses XABDAT and XABDAT_STORE
.PSECT LONG WRT,NOEXE
MYFAB: $FAB

ALQ=500, FOP=CBT, FAC=PUT, FNM=<DISK$: [PROGRAM]SAMPLE_FILE.DAT>,ORG=SEQ, RAT=CR, RFM=VAR, SHR=NIL, MRS=52, XAB=MYXDAT

MYXDAT: $XABDAT
ATIM:
BTIM:

.ASCID
.BLKQ

/9-AUG-1988 00:00:00.00/
1

.PSECT CODE NOWRT,EXE
.ENTRY CREAT, -M<>
START: $BINTIM_S TIMBUF=ATIM, TIMADR=BTIM
RO,SS_ERR
BLBC
$XABDAT_STORE XAB=MYXDAT, CDT=BTIM
$CREATE FAB=MYFAB
BLBC
RO.ERROR
CLOSE: $CLOSE FAB=MYFAB
FINI
BRB
FAB$L_STV+MYFAB
ERROR: PUSHL
FAB$L_STS+MYFAB
PUSHL
#2, G-LIB$SIGNAL
CALLS
BRB
FINI
SS ERR: PUSHL
RO
#1, G-LIB$SIGNAL
CALLS
FINI:
RET
.END CREAT

Convert ASCII to binary time
Branch on error
Move time into XAB$Q_CDT
Create file; populate
file later
Close file
and exit
Push FAB STS and
STV on stack
Signal error
Push RO
Signal error

This short program creates a file with a creation date of midnight,
August 9, 1988. The FAB at symbolic address MYFAB defines a sequential
file with variable-length records up to 52 bytes in length and specifies an
allocation size of 500 blocks using the contiguous-best-try file processing
option. It also specifies the file specification. The .ASCID assembler directive
defines the constant date-time character string at symbolic address ATIM.

3-9

VMS RMS Macros and VAX MACRO Programming
3.2 Using the VMS RMS Macros

The SYS$BINTIM system service is invoked to convert the constant ASCII
time at symbolic address ATIM to binary format in the quadword at BTIM.
The BTIM value is moved into the XAB$Q_CDT field of the XABDAT control
block at symbolic address MYXDAT using the following XABDAT_STORE
macro:
$XABDAT_STORE XAB=MYXDAT, CDT=BTIM

Because the creation date in field XAB$Q_CDT is input to the Create service
($CREATE macro), the value must be stored before the program invokes the
Create service. The file is created, then closed. Note that Create service errors
are signaled using the FAB$L_STS and FAB$L_STV fields, not RO.

3.2.4

Service Macros
The general macro format of VMS RMS service macros is described in Part I.
Part III describes each service in detail, including the VAX calling format.
Note that the general information applicable to invoking VMS RMS services
in Chapter 2 also applies to programs written in VAX MACRO.
The service macros use two general formats:
1. label: macro-name
2. label: macro-name

RAB=rab-address,ERR=entry,SUC=entry

The first format above takes no arguments. You supply the argument list
within your program, and the argument pointer register (AP) is assumed to
contain the address of the argument list. An example of this format is shown
below.
ARG_LOC: . BLKL 2

MOVL
MOVAL
MOVAL
$OPEN

#1,ARG_LOC
INFAB, ARG_LOC+4
ARG_LOC, AP

Move number of args to ARG_LOC
Move FAB address to ARG_LOC+4
Move ARG_LOC address to AP
Open file

In this form, the $OPEN macro expands to the following VAX MACRO code:
CALLG

(AP),

G~SYS$0PEN

In the second format, you supply arguments that automatically generate an
argument list on the stack according to the values you supplied. You specify
these arguments using keywords, which can be in any order. You must
separate keywords using a comma, a blank space, or tabs. The only argument
required when using the second format is the control block address
(FAB=fab-address or RAB=rab-address). This argument must be either a
general register (RO through Rll) containing the control block address, or a
suitable address for a PUSHAL instruction. If you omit this argument, no
other arguments are allowed; in other words, you must use the first format.

3-10

VMS RMS Macros and VAX MACRO Programming
3.2 Using the VMS RMS Macros

The ERR=entry and SUC=entry arguments are optional and, if used, provide
the addresses of completion routine entry points. Completion routines are
always executed as ASTs. VMS RMS places the values you supply in the
argument list on the stack during execution of the expanded macro. These
values must be addresses that can be used by a PUSHAL instruction.
Here is an example of the second format:
$OPEN FAB=INFAB

This macro line expands to the following VAX MACRO code:
PUSHAL
CALLS

INFAB
#01, G-svS$0PEN

When the argument list contains a completion routine argument, an AST is
queued. When the AST routine executes, the following conditions hold:
•

General registers RO through Rll are undefined. The AP contains the
address of the AST argument list; the AST argument value in the AST
argument list specifies the address of the associated control block (FAB or
RAB). The status must be retrieved from the completion status code field
(STS) of the associated control block.

•

Any general registers saved by an entry mask can be modified, in addition
to RO and Rl.

•

Additional calls to VMS RMS services can be made within the completion
routines.

•

To exit from a completion routine, you must perform any necessary
cleanup operations and execute a RET instruction.

The calling format of each VMS RMS service is listed alphabetically in Part III.
The format for the Close service is shown in the following code example:
SYS$CLOSE

fab

[,[err]

[,sue]]

When you use a macro to call a service, remember to omit the "SYS" prefix.
For example, use $CLOSE instead of SYS$CLOSE.
All file-processing macros require the FAB address as an argument and
optionally allow you to specify the entry points for error or success condition
handlers, as shown in the following format illustration:
$macro

FAB=fab-addr

[,ERR=error-entry]

[,SUC=success-entry]

For example, to invoke the $OPEN macro and pass it the FAB address of
INFAB and the error entry point of OPEN_ERR, you could use the following
macro:
$OPEN

FAB=INFAB, ERR=OPEN_ERR

Note that the $RENAME macro has a different format, as noted in Table 3-3.
This file processing macro has the following format:
$RENAME

OLDFAB=old-fab-addr [,ERR=error-entry]
[,SUC=success-entry] ,NEWFAB=new-fab-addr

3-11

VMS RMS Macros and VAX MACRO Programming
3.2 Using the VMS RMS Macros

The format for record processing macros and block I/O macros requires the
RAB address as an argument and optionally allows you to specify the entry
points for error or success condition handlers, as shown in the following
format illustration:
$macro

RAB=rab-addr

[,ERR=error-entry]

[,SUC=success-entry]

Note that the $WAIT macro has a different format, in that it does not use the
error and success arguments:
$WAIT

RAB=rab-addr

Table 3-3 lists each service macro according to its macro type.
Table 3-3

File, Record, and Block 1/0 Processing Macros

File
Processing

Record
Processing

Block 1/0

$CLOSE

$CONNECT

$READ

$CREATE

$DELETE

$SPACE

$DISPLAY

$DISCONNECT

$WRITE

$ENTER

$FIND

$ERASE

$FLUSH

$EXTEND

$FREE

$NXTVOL

$GET

$OPEN

$PUT

$PARSE

$RELEASE

$REMOVE
$RENAME

$REWIND
1

$SEARCH

$TRUNCATE
$UPDATE
$WAIT

1 Denotes macro with nonstandard format (see text).

After calling a VMS RMS service, you should check the status code returned
in RO (and the STS field of the appropriate control block). The recommended
way to signal errors is to provide both the STS and STV fields of the FAB
or RAB as arguments to the appropriate Run-Time Library routine. The
following VAX MACRO instructions invoke the LIB$SIGNAL routine for a
file-related (FAB) error using the CALLS (stack) form of calling a routine,
where the FAB is located at symbolic address MYFAB (not shown):
PUSHL
PUSHL
CALLS

3-12

MYFAB+FAB$L_STV
MYFAB+FAB$L_STS
#2, G-LIB$SIGNAL

Push fields on stack
in reverse order
Invoke signal routine

VMS RMS Example Programs

This section includes very brief examples illustrating the implementation of
VMS RMS at the VAX MACRO programming level. See the Guide to VMS
File Applications for VMS RMS examples using the File Definition Language
(FDL) Utility.
Using VMS RMS macros, you can create new files, process existing files,
extend and delete files, and read, write, update, and delete records within
files.
To create and process VMS RMS files, your program must contain calls to
appropriate VMS RMS services. Generally, you make these calls by using
the VAX RMS service macros for run-time processing. When encountered
at run time, the expanded code of these macros generates a call to the
corresponding VMS RMS service. Each macro and its resultant call represent
a program request for a VMS RMS file or record service, or a block I/O
transfer operation.

4.1

Creating, Accessing, and Deaccessing a File
The Create service constructs a new file according to the attributes you
specify in the FAB for the file, whereas the Open service makes an existing
file available for processing by your program. Both of these services, invoked
by the $CREATE and $OPEN macros respectively, allocate resources within
the system to establish access (a path) to a file. You must open or create a
file to perform most file operations and any record operations on that file.
Applications designed for shared access must declare the type of sharing at
this time. The user specifies the various types of shared access by setting bits
in the file access control (FAB$B_FAC) and share (FAB$B_SHR) fields in the
appropriate FAB.
VMS RMS provides several file-processing options for the Create service. The
create-if option (FAB$V_CIF option in the FAB$L_FOP field) requests that
the file be created only if it does not exist. If the file does exist in the specified
directory, the file is opened, not created. The Open and Create services both
establish access to the desired file, but the Create service additionally allocates
disk space and performs functions related to allocation.
When you are finished processing a file, you invoke the Close service
($CLOSE macro) to close the file, disconnect all record streams associated
with the file and free all resources allocated to the file. If you do not explicitly
invoke the Close service when the program image exits, VMS RMS attempts
an implicit close. All resources associated with open files are returned when
the files are deaccessed at image rundown time. However, process permanent
files are not implicitly closed when an image exits. These are special files that
the current CLI opens outside the context of a normal image.

4-1

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

4.1.1

Example of Opening and Creating Files
Example 4-1 illustrates the use of the Open, Create, Connect, Get, Put and
Close services to access and copy records from one file to another. Note
that the arguments to the $FAB and $RAB macros are listed vertically on
separate lines for ease in reading them. However, the argument list must
be contiguous and a common programming error is omission of required
delimiters and continuation characters when the arguments are listed in this
manner.
Example 4-1
. TITLE

Use of the Create, Open, and Close Services
COPYFILE

This program copies the input file to the output file.
INFAB:

.PSECT
$FAB

INRAB:

$RAB

OUTFAB: $FAB

OUTRAB: $RAB

REC_SIZE = 132
REC_BUFF:
.BLKB
.PSECT

DATA,WRT,NOEXE
FNM = <INFILE:>,DNM = <.INV>
FAB = INFAB,ROP =RAH,UBF = REC_BUFF,USZ = REC SIZE
FNM = <OUTFILE:>,DNM = <.INV>, FOP = CTG,FAC = <PUT>,SHR =<NIL>,MRS= REC_SIZE,RAT = CR
FAB = OUTFAB,ROP = WBH,RBF = REC_BUFF

Primary input file name
Default input file type
Pointer to FAB
Read-ahead option
Record buffer
and size
Primary output file name
Default output file name
Make contiguous file
Open for PUT operations
Exclusive file access
Maximum record size
Implied carriage control
Pointer to FAB
Write-behind option
Output uses same buff er
as input
Maximum record size

REC_SIZE

Record buff er

CODE,NOWRT,EXE

Initialization - Open input and output files and connect streams
.ENTRY COPYFILE,-M<R6>
$OPEN
FAB=INFAB
BLBC
RO,EXIT1
$CONNECT RAB=INRAB
BLBC
RO,EXIT2
MOVL
INFAB+FAB$L_ALQ,OUTFAB+FAB$L_ALQ
$CREATE FAB=OUTFAB
BLBC
RO,EXIT3
$CONNECT
RAB=OUTRAB
BLBS
RO.READ
BRB
EXIT4

Example 4-1 Cont'd. on next page

4-2

Save R6
Open input file
Quit on error
Connect to input
Quit on error
Set proper size for output
Create output file
Quit on error
Connect to output
Branch to READ loop
Trap error

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

Example 4-1 (Cont.)
EXIT1:
EX IT2 :
EXIT3:
EXIT4:

MOVAL
BRB
MOVAL
BRB
MOVAL
BRB
MOVAL
BRB

Use of the Create, Open, and Close Services

INFAB,R6
F ERR
INRAB,R6
R_ERR
OUTFAB,R6
F ERR
OUTRAB,R6
R_ERR

Error: Keep FAB address
Signal file error
Keep RAB address
Signal record error
Keep FAB address
Signal record error
If error, retain RAB addr.
Signal record error

Copy records loop
READ:

WRITE:

$GET
BLBS
CMPL
BEQL
BRB
MOVW
$PUT
BLBC
BRB

RAB=INRAB
RO.WRITE
RO,#RMS$_EOF
DONE
EXIT2
INRAB+RAB$W_RSZ, OUTRAB+RAB$W_RSZ
RAB=OUTRAB
RO,EXIT4
READ

Get a record
Write the record
Was error end-of-file?
Successful completion
Error otherwise
Input RAB sets record
size for output RAB
Write the record
Quit on error
Go back for more

Close files, signal any errors, and exit
F ERR:

R_ERR:
DONE:
EXIT:

FAB$L_STV(R6)
PUSHL
FAB$L_STS(R6)
PUSHL
#2, G-LIB$SIGNAL
CALLS
EXIT
BRB
PUSHL
RAB$L_STV(R6)
RAB$L_STS(R6)
PUSHL
#2, G-LIB$SIGNAL
CALLS
$CLOSE FAB=INFAB
$CLOSE FAB=OUTFAB
RET
.END
COPYFILE

Push STV and STS of FAB
on the stack
Signal error
Push STV and STS of RAB
on the stack
Signal error
Close input
and output
Return with status in RO

This example illustrates how you can use the sequential file organization to
create a new file by copying records from an existing file. The newly created
file and the source file have variable-length records.
This example assumes that an external program has identified the input file
as a search list logical name using this statement:
$ ASSIGN [INV]30JUN85, [INV.OLD]30JUN85 INFILE:

This dictates that VMS RMS should look for the input file in directory [INV]
first, and if it does not find the file, it should look in directory [INV.OLD].
The program also specifies the default file type INV for the input file using
this statement:
DNM=<.INV>

; Default input file name

Next the program configures the RAB used for the input file (labeled INRAB).
The first argument links the RAB to the associated FAB (INFAB) and this is
the only required argument to a RAB. The rest of the arguments specify the
read-ahead option (described in later text) and the record buffer for the input
file. The Get service uses the user record buffer address (UBF) field and the
user record buffer size (USZ) field as inputs to specify the record buffer and
the record size, respectively.

4-3

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

Note: When you invoke the GET service, RMS takes control of the record buffer
and may modify it. RMS returns the record size and only guarantees the
contents from where it accessed the record to the completion of the record.
The program then configures the FAB for the output file. The first argument
uses the FNM field to equate the file name to the externally defined logical
name OUTFILE. After the program specifies the default file specification
extension for the output file, it specifies three additional FAB fields.
First it specifies that VMS RMS should allocate contiguous space for the
output file by setting the CTG bit in the FAB$L_FOP field of the FAB.
Next the progam uses a program-defined variable to store the value 132 in
the MRS field:
MRS=REC_SIZE
REC_SIZE= 132

The program then specifies that each record is to be preceded by a line feed
and followed by a carriage return whenever the record is output to a line
printer or terminal:
RAT=CR

Because the program alternately reads and then writes each record, the input
file and the output file may share the same buffer. However, because the
Put service does not have access to the UBF and UBZ fields, the output RAB
defines the buffer using the RBF and the RSZ fields.
Note that the UBF, USZ, and RBF values are set prior to run time, but that
the RSZ value is set at run time, just prior to invocation of the Put service.
This is done because the input file contains variable-length records and the
Put service relies on the Get service to supply each record's size by way of
the RSZ field, an INRAB output field.
The following statement from the sample program illustrates this feature:
WRITE:

MOVW

INRAB+RAB$W_RSZ, OUTRAB+RAB$W_RSZ

; Input RAB sets record
; size for output RAB

The run-time processing macros for the input file consist of a $OPEN, a
$CONNECT, a $GET, and a $CLOSE macro. Because the input file already
exists, the program accesses it with a $OPEN macro. The sole argument to
this macro identifies the FAB to the Open service:
$OPEN

FAB=INFAB

Next, the program connects a record stream to the input file by calling the
Connect service and specifying INRAB as the appropriate RAB:
$CONNECT RAB=INRAB

Note that upon completion of each service call, the program tests the
condition value in RO returned by the service before proceeding to the
next call. If the call fails, the program exits with the appropriate control block
address in R6.
After creating the output file and establishing its record stream, the program
begins a processing loop in which the Get service reads a record from the
input file and the Put service writes the record to the output file. When all
file records are copied, as indicated by the detection of the end of the file, the
program exits to label DONE which closes both files.

4-4

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

The Close service disconnects the record stream for all RABs connected to
the specified FAB. In a multistream environment (more than one RAB can
be connected to a single FAB), a program may disconnect individual record
streams using the Disconnect service.

4.1.2

Example of Creating a Multiple-Key Indexed File
Example 4-2 creates an indexed file on a remote DECnet node from a
sequential file on the local node. The indexed file contains three keys.
Example 4-2
.TITLE
. IDENT

Use of the Create Service for an Indexed File
CREATEIDX - CREATE INDEXED FILE
/V001/

This program creates an indexed file with three keys from a
sequential file containing a name and address list. The record
format of the input file is shown below:
First Name
Middle Initial
Last Name
Street
City
State
Zip Code
Reserved for
new data

Column
Column
Column
Column
Column
Column
Column

00-10
12-26
27-46
47-58
59-60
61-65

Column

66-end of record

11-11

The input and output files are specified by the logical names SRC
and DST, respectively. For example:
$DEFINE SRC DBB1: [TEST] INPUT.DAT
$ DEFINE DST TRNTO: :DRA4: [RMS.FILES]OUTPUT.DAT
$ RUN CREATEIDX

;********************************************************************
.SBTTL
.PSECT

Control block and buffer storage
DATA
NOEXE,LONG

Define the source file FAB and RAB control blocks.
SRC_FAB:
$FAB

FAC=<GET>,FOP=<SQO>,-

File access for GET only
DAP file transfer mode

FNM=<SRC:>

Name of input file

FAB=SRC_FAB,RAC=SEQ,UBF=BUFFER,USZ=BUFFER_SIZE

Address of associated FAB
Sequential record access
Buff er address
Buff er size

SRC_RAB:
$RAB

Example 4-2 Cont'd. on next page

4-5

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

Example 4-2 (Cont.)

Use of the Create Service for an Indexed File

Define the destination file FAB and RAB control blocks.
DST_FAB:
$FAB

FAC=<PUT>,FOP=CTG,FAC = <PUT>,SHR = <NIL>,FNM=<DST:>,MRS=128,RFM=VAR,RAT=<CR>,ORG=IDX, XAB=DST KEYO

File access for PUT only
Allocate contiguous
Open for PUT operations
Exclusive file access
Name of output file
Maximum record size
Variable length records
Implied carriage control
Indexed file organization
Address of start of XAB chain

$RAB

FAB=DST_FAB,MBF=3,RAC=KEY,RBF=BUFFER,ROP=LOA,RSZ=BUFFER SIZE

Address of associated FAB
Use 3 buffers
Random record writes
Buff er address
Specify initial fill size
Buff er size

DST_RAB:

Define key definition XABs to describe the three keys.
DST KEYO:
$XABKEY REF=O,DAN=O,DFL=1536,IAN=1,IFL=1536,PROLOG=3,POS=<12, 0, 11>, SIZ=<15,1,1>,NXT=DST KEY1
DST KEY1:
$XABKEY REF=1,DAN=2,IAN=2,IFL=768,POS=47,SIZ=12,FLG=<CHG,DUP>,NXT=DST KEY2
DST KEY2:
$XABKEY REF=2,DAN=2,IAN=2,IFL=768,POS=59,FLG=<CHG,DUP>,SIZ=2,NXT=DST ALLO

Example 4-2 Cont'd. on next page

4-6

Primary key is Name
Key reference number
Define data XABALL
Define data fill of 75%
Define index XABALL
Initial index fill 75%
Request Prolog 3
Segmented key: last name,
first initial, middle initial
Address of next XAB in chain
1st alternate key is City
Key reference number
Data level (SIDR) XABALL
Index XABALL
Initial index fill 75%
Starting key position
Key size
Duplicates and changes
Address of next XAB in chain
2nd alternate key is State
Key reference number
Data level (SIDR) XABALL
Index XABALL
Initial index fill 75%
Starting key position
Duplicates and changes
Key size
Designate next XAB

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

Example 4-2 (Cont.)

Use of the Create Service for an Indexed File

Define allocation control XABs to define multiple areas
DST_ALLO:
$XABALL AID=O,ALQ=328,AOP=<CBT>,BKZ=4,DEQ=112,NXT=DST ALL!
DST_ALL1:
$XABALL AID=! , ALQ=8,AOP=<CBT>,BKZ=4,DEQ=4,NXT=DST ALL2
DST_ALL2:
$XABALL AID=2, ALQ=112,AOP=<CBT>,BKZ=2,DEQ=38,NXT=DST_ALL3

Data area definition
Allocation quantity and
contiguous best try
Bucket size of 4 blocks
Default extension quantity
Designate next XAB
Primary key index area
Allocation quantity and
contiguous best try
Bucket size of 4 blocks
Default extension quantity
Designate next XAB
Alternate key data area
Allocation quantity and
contiguous best try
Bucket size of 2 blocks
Default extension quantity
Designate next XAB

Allocate buffer to the size of the largest record being read.
BUFFER: .BLKB
66
BUFFER_SIZE=.-BUFFER

; Buff er for input and output
; Buff er size

;*********************************************************************
.SBTTL
.PSECT

Mainline
CODE

NOWRT,BYTE

Start of program
.ENTRY

CREATEIDX,~M<R6>

Entry point

Open the source and destination files.

EXIT!:
EXIT2:
EXIT3:
EXIT4:

$OPEN
FAB=SRC FAB
BLBC
RO.EXIT!
$CONNECT RAB=SRC_RAB
BLBC
RO,EXIT2
$CREATE FAB=DST_FAB
BLBC
RO,EXIT3
$CONNECT RAB=DST_RAB
BLBC
RO,EXIT4
BRB
LOOP
MOVAL
SRC_FAB,R6
BRB
F_ERR
MOVAL
SRC_RAB,R6
BRB
R_ERR
MOVAL
DST_FAB,R6
BRB
F_ERR
MOVAL
DST_RAB,R6
BRB
R_ERR

Open input file
Branch on failure
Connect input record stream
Branch on failure
Create output file
Branch on failure
Connect output record stream
Branch on failure
Bypass signaling code
Keep FAB address
Signal error
Keep RAB address
Signal error
Keep FAB address
Signal error
Keep RAB address
Signal error

Example 4-2 Cont'd. on next page

4-7

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

Example 4-2 (Cont.)

Use of the Create Service for an Indexed File

; Transfer records until end-of-file is reached.
LOOP:

PUT:

$GET
BLBS
CMPL
BNEQ
BRB
$PUT
BLBS
BRB

RAB=SRC_RAB
RO.PUT
RO,#RMS$_EOF
EXIT2
CLOSE
RAB=DST RAB
RO.LOOP
EXIT4

Read next rec from input file
Branch on success
Was it end-of-file (EDF)?
Branch if not EDF error
Close and exit if EDF
Write 66-byte record to output
On success, continue loop
On error, signal and exit

Close the source and destination files.
F ERR:

R_ERR:
CLOSE:
EXIT:

FAB$L_STV(R6)
PUSHL
FAB$L_STS(R6)
PUSHL
#2, GALIB$SIGNAL
CALLS
BRB
EXIT
RAB$L_STV(R6)
PUSHL
RAB$L_STS(R6)
PUSHL
#2, GALIB$SIGNAL
CALLS
$CLOSE FAB=DST_FAB
$CLOSE FAB=SRC FAB
$EXIT_S
.END
CREATEIDX

Push STV and STS fields
on stack
Signal file error
Exit
Push STV and STS fields
on stack
Signal file error
Close output file
Close input file
Exit
Specify starting address

This example program creates an indexed file with a primary key and two
alternate keys that are defined by appropriate key definition control blocks
(XABKEY). For efficiency, the file is divided into areas consisting of a data
area and an index area for each key using multiple allocation control blocks
(XABALL).
In each XABKEY, the DAN and IAN arguments (XAB$B_DAN and XAB$B_
IAN fields) indicate the area identification number (AID) of the corresponding
XABALL. By setting the RAB$V_LOA bit in RAB field RAB$L_ROP, the
program indicates that VMS RMS should use the DFL and IFL arguments
(XAB$W_DFL and XAB$W_IFL fields) to determine the maximum initial fill
size (in bytes) for data and index buckets (each bucket contains the number of
blocks specified in the XABALL BKZ argument, XAB$B_BKZ field).
These are the XABKEY and XABALL control blocks for the primary key (the
NAME key) in this example:
DST_KEYO:
$XABKEY REF=O,DAN=O,DFL=1536,IAN=1, IFL=1536,PROLOG=3,-

4-8

Primary key is Name
Key reference number
Define data XABALL
Define data fill of 75%
Define index XABALL
Initial index fill 75%
Request Prolog 3

VMS RMS Example Programs
4.1 Creating, Accessing, and Deaccessing a File

DST_ALLO:
$XABALL AID=O,ALQ=328,AOP=<CBT>,BKZ=4,DEQ=112. NXT=DST_ALL1
DST_ALL1:
$XABALL AID=1, ALQ=8,AOP=<CBT>, BKZ=4,DEQ=4,NXT=DST_ALL2

The allocation information was obtained using the File Definition Language
(FDL) editor which is especially useful when you are creating large indexed
files. The DCL commands CREATE/FDL and CONVERT can be used to
create files by using an FDL file produced by the FDL editor, without any
programming. Instead of using the multiple XABs for the key definition and
area allocations in this program, a simpler approach is to use the FDL file
produced by the FDL editor by invoking the FDL routines FDL$P ARSE and
FDL$RELEASE (for more information on these routines, see the VMS Utility
Routines Manual).
Fixed-length records are copied from the sequential input file on the local
node to the indexed file on the remote node. Each variable-length output
record is initially 66 bytes long and may be extended to a maximum of 128
bytes. A subsequent example in this document shows how to access this file
using different key paths.

4.2

Processing File Specifications
The file name and file specification services, Parse and Search, are used for
relatively complex operations such as processing wildcard characters.
Before you can perform operations on a file, you must establish a path to
the file. You do this by specifying the file specification string address and
size (FAB$L_FNA and FAB$B_FNS) fields (and possibly the default file
specification string address and size fields) of the FAB to describe an ASCII
string within the program. In this ASCII string, you can have a concatenation
of the network node name; a logical or device name; the directory name; and
the file name, type, and version number.
If a logical name is used, VMS RMS translates the logical name into

its equivalent file specification before it applies defaults to any missing
components of the file specification. If the logical name is a search list
logical name, VMS RMS translates each element of the search list into an
equivalent file specification before it applies defaults to that element. When
using the Search service, a file specification that may contain a search list
logical name must be handled as if wildcard characters were present in the
file specification.
The Parse service is required prior to the Search service in order to examine
the file specification for wildcard characters or a search list. If the file is
found, the Parse service sets a NAM block bit that VMS RMS uses internally
and sets an appropriate value in the wildcard character context which is used
as input by the Search service. The Parse service is invoked once, then the
Search service is repetitively invoked as many times as there are files that
match the original file specification.

4-9

VMS RMS Example Programs
4.2 Processing File Specifications

If a wildcard is present, the Search service attempts to find all files that match
the file specification. If an asterisk ( *) is in the directory field, all directories

on the specified device are searched for files that match the remaining file
specification components. As with the use of wildcard characters, when a
search list logical name is present, a single Parse service and multiple Search
services return all files that match the file specification. With search lists,
however, all list elements are searched for matching file specifications in
the specified order without regard to uniqueness between the resulting file
specifications. Search lists can be used in place of (or in addition to) wildcard
characters to specify a more efficient search order, which can mean different
combinations for the device, directory, file name, file type, and version
number parts of a file specification. Search lists can also contain wildcard
characters, if needed.
In summary, the Parse and Search services use a search list logical name very
mm;h like a wildcard. Unlike the case of opening a file, in which the first
instance where the file is found successfully ends the use of additional search
list file specifications, the Parse and Search services use all search list file
specifications.
Example 4-3 shows how the $PARSE and $SEARCH macros can be used in
wildcard processing.
Example 4-3

Wildcard Processing Using Parse and Search Services

.TITLE WILD
Program to accept wildcard characters in input (partial) file
specification and display full file specification.
$NAMDEF

; NAM block definitions

.PSECT

DATA,NOEXE,WRT

$NAM

RSA=RES_STR,RSS=NAM$C_MAXRSS,ESA=EXP_STR,ESS=NAM$C_MAXRSS

Result buff er address
Result buff er size
Expanded buff er address
Expanded buff er size

$FAB

FOP=NAM,NAM=NAM_BLK,FNA=INP STR

Use NAM block option
Pointer to NAM block
Addr of file name string

.BLKB

NAM$C_MAXRSS

.BLKB
RES STR_D:
.BLKL
.LONG
INP STR:
.BLKB
INP_STR_D:
.LONG
.LONG
INP STR_LEN:
.BLKL

NAM$C_MAXRSS

NAM_BLK:

FAB_BLK:

Expanded string buff er

EXP STR:

Resultant string buffer

RES STR:

Resultant string descriptor
1

RES_STR
Input string buffer
NAM$C_MAXRSS
Input string descriptor
NAM$C_MAXRSS
INP_STR
Input string length
1

Example 4-3 Cont'd. on next page

4-10

VMS RMS Example Programs
4.2 Processing File Specifications

Example 4-3 (Cont.)
PROMPT_D:
.ASCID

Wildcard Processing Using Parse and Search
Services

; User prompt string
/Please enter the file specification: I

.PSECT CODE,EXE,NOWRT
.ENTRY WILD' AM<>
PUSHAB INP STR_LEN
PUSHAB PROMPT_D
PUSHAB INP_STR_D
#3,G-LIB$GET_INPUT
CALLS
BLBC
RO.EXIT

Address for string length
Prompt string descriptor
String buff er descriptor
Get input string value
Quit on error

Store user input string and perform initial parse to
set up VMS RMS context for subsequent search.
MOVB
$PARSE
BLBC

INP_STR_LEN, FAB_BLK+FAB$B_FNS
FAB=FAB_BLK
RO,F_ERR

Set string size
Parse the file spec
Quit and signal on error

Search until all possibilities are exhausted.
SEARCH_LOOP:
$SEARCH FAB=FAB_BLK
BLBC
RO,SRCHERR

Find next file
Any more?

Print out the resultant string from the search operation
MOVZBL

NAM_BLK+NAM$B_RSL, RES_STR_D
PUSHAB RES STR_D
#1,G-LIB$PUT_OUTPUT
CALLS
BLBC
RO.EXIT
SEARCH_ LOOP
BRB
SRCHERR:
CMPL
BEQL

RO,#RMS$_NMF
S_EXIT

F ERR:

PUSHL
FAB_BLK+FAB$L_STV
PUSHL
FAB_BLK+FAB$L_STS
CALLS
#2, GALIB$SIGNAL
S EXIT: MOVL
#1,RO
EXIT:
RET
.END WILD

Set string length
String descriptor
Output the result
Quit on error
Go for more
If the error is "No more
files" then this is the
normal completion of the
search loop.
Push STV and STS on stack
in reverse order
Signal error
Suppress "No More Files"

This program is designed to locate all files corresponding to a partial file
specification input. The program prompts the user for an input string, which
can consist of a partial file specification, using the wildcard characters
and/ or any type of logical name, including a search list logical name. In
many respects, this program emulates the DCL command DIRECTORY,
which is discussed in the VMS DCL Dictionary.
The program illustrates the use of the $PARSE and $SEARCH file name
processing macros. Here is the program statement that invokes the Parse
service for parsing the file name string:
$PARSE FAB=FAB_BLK

4-11

VMS RMS Example Programs
4.2 Processing File Specifications

Before invoking the Parse service ($PARSE macro), the program moves the
input string length to the file name string (FAB$B_FNS) field. If the Parse
service returns an error completion status, the program branches to the
F_ERR error routine.
Assuming no error, the program searches the disk directories specified by the
expanded string area address field in the NAM block (NAM$L _ESA) until all
possible files conforming to the partial file specification input are found. Here
is the program line that invokes the Search service:
$SEARCH FAB=FAB BLK

A status test is performed immediately after the $SEARCH macro. If an
error is detected, the program branches to the SRCHERR label. If a no-morefiles condition is detected, VMS RMS returns the RMS$_NMF message to
indicate that all files that match the specification have been found. (This
error, however, is not signaled.)
This program contains two Run-Time Library routines: LIB$GET_INPUT and
LIB$PUT_OUTPUT. The LIB$GET_INPUT routine inputs a record from the
current controlling input device, specified by SYS$INPUT, using the VMS
RMS Get service. The LIB$PUT_OUTPUT routine outputs a record (line) to
the current controlling output device, specified by SYS$0UTPUT, using the
VMS RMS Put service. Both routines are discussed in greater detail in the

VMS Run-Time Library Routines Volume.

4.3

Connecting and Disconnecting Record Streams
To associate or disassociate a file with one or more record streams, VMS RMS
provides the Connect and Disconnect services, which are invoked using the
$CONNECT and $DISCONNECT macros.
Before reading and writing file records, the program must open (or create)
the input and output files and then connect the files to the appropriate record
streams by executing the $OPEN (or $CREATE) macro followed by the
$CONNECT macro.
Closing a file implicitly disconnects the record stream. Use the Disconnect
service to explicitly disconnect a record stream that is not to be used
immediately. This keeps the file open but releases various data structures
for use by other processes until your program needs the record stream.
Example 4-4 shows a program in which a user-entered reply determines
which key path is selected to access the indexed file created in Example 4-2.
The user-entered value determines the value specified for the RAB$B_KRF
field. The RAB$B_:ELRF value is set before the connect operation occurs
because this field is input to the Connect service.

4-12

VMS RMS Example Programs
4.3 Connecting and Disconnecting Record Streams

Example 4-4
.TITLE
REC_SIZE=128
.PSECT

Use of the Connect Service and Multiple Keys
MULTIKEY
DATA NOEXE,LONG

** RMS DATA **
FAB file spec.
Get access needed
Allow Get, Update, Put
Specify record size
RAB; indicate FAB
Use 3 buffers
Specify buff er

REC_MODBUF:

FNM=<DATA_OUTPUT.DAT>,FAC=<GET>,SHR=<GET, UPD, PUT>,MRS=REC SIZE
FAB=MODFAB,MBF=3,UBF=REC_MODBUF,USZ=REC_SIZE,KRF=O
.LONG
REC SIZE
.ADDRESS REC_MODBUF
.BLKB
REC_SIZE

MPROO: . ASC ID
MPR01: . ASCID
ENTRYERR:

TERMINAL I/O DATA **
I I
/Enter list order: 1-by name, 2-by city, 3-by state, 9-end
.ASCID I* * Value entered must be 1, 2, 3, or 9. * */

MODFAB: $FAB

MODRAB: $RAB

REC START:

REGANS:
REGBUF:

.LONG
1
.ADDRESS REGBUF
.BLKB
1

DONE:

.ASCID /Press RETURN to continue/

.PSECT CODE
.WORD
AM<>
PUSHAL MPROO
PUSHAL MPR01
PUSHAL REGANS
CALLS
#3, GALIB$GET_INPUT
BLBC
RO.FINI
CMPB
#AA/1/,REGBUF
BEQLU PRIM
CMPB
#AA/2/,REGBUF
BEQLU ALT1
CMPB
#AA/3/,REGBUF
BEQLU ALT2
CMPB
#AA/9/,REGBUF
BEQLU FINI
BADANS: PUSHAL ENTRYERR
CALLS
#1, GALIB$PUT_OUTPUT
BLBC
RO.FINI
BRB
INPUT
PRIM:
MOVB
#O,MODRAB+RAB$B_KRF
BRB
OPEN
ALT1:
MOVB
#1,MODRAB+RAB$B_KRF
BRB
OPEN
ALT2:
MOVB
#2,MODRAB+RAB$B_KRF
OPEN:
$OPEN
FAB=MODFAB
BLBC
RO,ERROR_OPEN
$CONNECT RAB=MODRAB
BLBC
RO.ERROR
START:
INPUT:

Primary is default key
Record buffer

Get input
Display prompt

Test value of menu answer
1 means primary
Continue testing
2 means first alternate
Continue testing
3 means second alternate
Continue testing
9 means end program
otherwise, display error message
Entry error; retry
Set key of reference in RAB
Set key of reference in RAB
Set key of reference in RAB
Open file
Connect record stream

Example 4-4 Cont'd. on next page

4-13

VMS RMS Example Programs
4.3 Connecting and Disconnecting Record Streams

Example 4-4 (Cont.)
NEXT:

CLEAN:

$GET
CMPL
BEQLU
BLBC
MOVZWL
PUSHAL
CALLS
BLBS
BRB
$CLOSE
BLBC
PUS HAL
CALLS
BLBC
PUSHAL
PUS HAL
CALLS
BLBC
BRB

ERROR_OPEN:
PUSHL
PUSHL
CALLS
BRB
ERROR: PUSHL
PUSHL
CALLS
$CLOSE
FINI:
RET
.END

Use of the Connect Service and Multiple Keys

RAB=MODRAB
Get record
#RMS$_EOF,RO
; Test i f EDF
CLEAN
RO.ERROR
RAB$W_USZ+MODRAB,REC_START Set ASCII descriptor length
REC_START
Display each record
#1, G-LIB$PUT_OUTPUT
RO.NEXT
FINI
Repeat until EDF
FAB=MODFAB
Close file
RO,ERROR_OPEN
MPROO
#1, G-LIB$PUT_OUTPUT
RO.FINI
DONE
REGANS
#2, G-LIB$GET_INPUT
RO, FINI
INPUT
MODFAB+FAB$L_STV
MODFAB+FAB$L_STS
#2, G-LIB$SIGNAL
FINI
MODRAB+RAB$L_STV
MODRAB+RAB$L_STS
#2, G-LIB$SIGNAL
FAB=MODFAB

Error opening
file. Signal error
using LIB$SIGNAL.
End program
Record-related error
Signal error, then
close file

START

Here the SHR argument limits access to processes that perform the Get
service, Put service, and Update service. If you anticipate no file modifications
as your program accesses the file, you can improve performance by having the
SHR argument limit access to processes that use the Get service (SHR=GET).
Errors are signaled according to the recommended practice of using the
FAB$L_STS and FAB$L_STV fields for file errors and RAB$L_STS and
RAB$L_STV fields for record errors.

4.4

Other File-Processing Operations
Other VMS RMS file services include the Display, Erase, Extend, Remove,
and Rename services, which can be invoked using the $DISPLAY, $ERASE,
$EXTEND, $REMOVE, and $RENAME macros, respectively.
Example 4-5 illustrates the use of the Rename service to rename a file from
directory [USER] named NAMES.DAT to directory [USER.HISTORY] named
OLD_NAMES.DAT.

4-14

VMS RMS Example Programs
4.4 Other File-Processing Operations

Example 4-5
.TITLE

Use of the Rename Service
RENAME

Program that renames a file into a different directory and
displays the resultant string .
. PSECT

DATA,NOEXE,WRT

Define old FAB, old NAM, new FAB, new NAM, and buffers
OLD FAB:

Define old file FAB
$FAB

OLD NAM:
$NAM

NEW FAB:
$FAB

FNM=<[USER]NAMES.DAT>,NAM=OLD NAM

Pointer to NAM block
Define old file NAM
ESA=EXP_OLD,Equivalence string
ESS=NAM$C_MAXRSS,address and size
RSA=RES_OLD,Resultant string
RSS=NAM$C_MAXRSS
address and size
Define new file FAB
FNM=<[USER.HISTORY]OLD_NAMES.DAT>,NAM=NEW NAM
Pointer to NAM block

NEW NAM:
$NAM

ESA=EXP_NEW,ESS=NAM$C_MAXRSS,RSA=RES_NEW,RSS=NAM$C_MAXRSS

.BLKB

NAM$C_MAXRSS

.BLKB

NAM$C_MAXRSS

.BLKB
RES OLD D:
.BLKL
.LONG
RES NEW:
.BLKB
RES_NEW_D:
.BLKL
.LONG

NAM$C_MAXRSS

EXP OLD:
EXP NEW:
RES OLD:

MESS:

Equivalence string
address and size
Resultant string
address and size
Old file equivalence
string buff er
New file equivalence
string buff er
Old file resultant
string buffer
String descriptor

RES_OLD
NAM$C_MAXRSS

New file resultant
string buff er
String descriptor

RES_NEW

.ASCID /has been successfully relocated to I
.PSECT
.ENTRY

CODE,EXE,NOWRT
RENAME,-M<>
Rename file

$RENAME OLDFAB=OLD_FAB, NEWFAB=NEW_FAB
BLBC
RO.ERROR
; Set up descriptors

Example 4-5 Cont'd. on next page

4-15

VMS RMS Example Programs
4.4 Other File-Processing Operations

Example 4-5 (Cont.)
MOVZBL
MOVZBL

Use of the Rename Service

OLD_NAM+NAM$B_RSL,RES_OLD_D
NEW_NAM+NAM$B_RSL,RES_NEW_D

PUS HAL RES OLD D
#1,G-LIB$PUT_OUTPUT
CALLS
RO,TERM_ERROR
BLBC
PUS HAL MESS
#1,G-LIB$PUT_OUTPUT
CALLS
RO,TERM_ERROR
BLBC
PUS HAL RES NEW_D
#1,G-LIB$PUT_OUTPUT
CALLS
BLBS
RO.DONE
TERM_ERROR:
PUSHL
RO
#1,G-LIB$SIGNAL
CALLS
BRB
DONE
ERROR: PUSHL
OLD_FAB+FAB$L_STV
PUSHL
OLD_FAB+FAB$L_STS
CALLS
#2,G-LIB$SIGNAL
DONE:
RET
.END RENAME

Push resultant name,
display old file spec.
Branch on error
Push message on stack,
display message
Branch on error
Push resultant name,
display new file spec.
Branch on success
Signal output error
from RO
Push STV and STS on
stack (reverse order)
Signal error

This program uses the Rename service to change both the directory and the
name of the object file, which is being replaced by a new file (created by a
separate program). If the Rename service executes correctly, the resultant
file specification of the old file, the message defined by the ASCII descriptor
following the label MESS, and the resultant file specification of the new file
are displayed as verification that the Rename service successfully completed.

4.5

Retrieving and Inserting Records
The record-processing services provided by VMS RMS insert records into a
file and retrieve records from a file. These services are the Find, Get, and
Put services, which can be invoked by the $FIND, $GET, and $PUT macros,
respectively.
Example 4-6 illustrates the use of the $GET and $PUT macros. It connects
the input and output record streams, reads a record from an indexed file, and
writes the record to a relative file. The program illustrates the use of the key
string buffer, the key string descriptor and the key string length when reading
indexed records and it includes the use of a user prompt string.

4-16

VMS RMS Example Programs
4.5 Retrieving and Inserting Records

Example 4-6
.TITLE

Use of the Get and Put Services
LOOKUP

This program looks up records in the input file and
writes the records to the output file.
INFAB:

.PSECT
$FAB

INRAB:

$RAB

OUTFAB: $FAB

OUTRAB: $RAB
REC SIZE = 132
REC_BUFF:
.BLKB
INP STR:
.BLKB
INP STR_D:
.LONG
.LONG
INP_STR_LEN:
.BLKL
PROMPT_D:
.ASCID
.PSECT

DATA,WRT,NOEXE
FNM = <INFILE:>,SHR = <GET,PUT,UPD,DEL>
FAB
INFAB,KBF
INP_STR,KRF
0,RAC
KEY,ROP =WAT,UBF = REC_BUFF,USZ = REC SIZE
FNM = <OUTFILE:>,BKS = 3,MRS = REC_SIZE,ORG =REL.RAT
CR
FAB
OUTFAB,RBF
REC_BUFF

REC SIZE

Input file logical name
Allow read/write sharing
Pointer to FAB
Key buff er
Primary key
Keyed access
Wait for record
Record buff er
and size
Output file logical name
3 blocks per bucket
Maximum record size
Relative file
Implied carriage control
Pointer to FAB
Output uses same buff er
as input
Maximum size records
Record buffer
Key string buff er

REC_SIZE
Key string descriptor
REC_SIZE
INP_STR
; Key string length
1
; User prompt string
/Please input key value: I
CODE,NOWRT,EXE

Initialization - Open input and output files and connect streams
.ENTRY LOOKUP ~M<>
$OPEN
FAB=INFAB
RO,EXIT1
BLBC
$CONNECT
RAB=INRAB
BLBC
RO,EXIT2
$CREATE FAB=OUTFAB
BLBC
RO,EXIT3
$CONNECT
RAB=OUTRAB
BLBC
RO,EXIT4
BRB
READ
MOVAL
INFAB, R6
BRW
F ERR
INRAB, R6
MOVAL
R_ERR
BRW
MOVAL
OUTFAB, R6
BRB
F ERR
MOVAL
OUTRAB, R6
BRB
R ERR
I

EXIT1:
EXIT2:
EXIT3:
EXIT4:

No registers to save
Open input file
Quit on error
Connect to input
Quit on error
Create output file
Quit on error
Connect to output
Quit on error
Skip error branching
Keep INFAB address
Signal FAB error
Keep INRAB address
Signal RAB error
Keep OUTFAB address
Signal FAB error
Keep OUTRAB address
Signal RAB error

Example 4-6 Cont'd. on next page

4-17

VMS RMS Example Programs
4.5 Retrieving and Inserting Records

Example 4-6 (Cont.)

Use of the Get and Put Services

Loop to copy records
READ:

GET:

PUSHAB
PUSHAB
PUSHAB
CALLS
BLBS
CMPL
BEQL
BRB
MOVB

PUT:

$GET
BLBS
CMPL
BEQL
BRB
MOVW
$PUT
BLBC
BRB

INP_STR_LEN
PROMPT_D
INP STR_D
#3,G-LIB$GET_INPUT
RO.GET
RO,#RMS$_EOF
DONE
EXIT
INP_STR_LEN, INRAB+RAB$B_KSZ
RAB=INRAB
RO.PUT
RO,#RMS$_RNF
READ
EXIT2
INRAB+RAB$W_RSZ, OUTRAB+RAB$W_RSZ
RAB=OUTRAB
RO,EXIT4
READ

Address for string length
Prompt string descriptor
String buff er descriptor
Get input string value
Quit on error or end-of-file
Was error end-of-file?
Successful completion
Error otherwise
Set key size
Get a record
Put if successful
No such record?
Try again
Error otherwise
Set the record size
for output
Write the record
Quit on error
Go back for more

Close files and exit
F ERR:

R_ERR:
DONE:
EXIT:

FAB$L_STV(R6)
PUSHL
FAB$L_STS(R6)
PUSHL
#2, G-LIB$SIGNAL
CALLS
BRB
EXIT
RAB$L_STV(R6)
PUSHL
RAB$L_STS(R6)
PUSHL
#2, G-LIB$SIGNAL
CALLS
$CLOSE FAB=INFAB
$CLOSE FAB=OUTFAB
RET
.END
LOOKUP

Push STV and STS on
stack in reverse order
Signal message
Push STV and STS on
stack in reverse order
Signal message
Close input
and output
Return with status in RO

This program writes records from an existing indexed input file into a newly
created relative output file.
The program configures the file-sharing field (FAB$B_SHR) in the input FAB
to permit sharing of the file by processes that use the Get, Put, Update and
Delete services.
The output FAB sets the bucket size field (FAB$B_BKS) at three blocks per
bucket, limits the record size in the output file to 132 bytes, specifies the
relative file organization and specifies an implicit carriage control when the
file output is directed to a terminal.
The RAB for the input file establishes the key data, sets the WAIT record
option and defines the record buffer. The output RAB locates the record
buffer. The rest of the first program section assigns values and allocates space
to various program variables. After the program opens and creates the two
files and connects the record streams, it executes a series of instructions at
label READ that input the required key values and the user prompt. Then the
program uses the $GET and $PUT macros to invoke the respective services
for retrieving and inserting the records. The $GET macro uses the INRAB,

4-18

VMS RMS Example Programs
4.5 Retrieving and Inserting Records

and the $PUT macro uses the OUTRAB as shown in the following program
statements:
$GET

RAB=INRAB

$PUT

RAB=OUTRAB

Each time the program reads or writes a record, it performs a status check. If
the status check is successful, the program branches back to the READ label
for the next record. If any of the status checks indicate an error, the program
branches to the appropriate error handler before exiting.
When the program completes the records transfers, it branches to the DONE
label to close the record and exit.

4.6

Deleting Records
This service can only be used with relative and indexed files. Example 4-7
illustrates use of the Delete service.
Example 4-7

Use of the Delete Service

.TITLE DELETE
This program looks up records in the input file and
deletes those records.

INFAB:

.PSECT
$FAB

INRAB:

$RAB

REC SIZE = 132
INP_STR:
.BLKB
INP STR_D:
.LONG
.LONG
INP_STR_LEN:
.BLKL
KEY_PMT_D:
.ASCID
.PSECT

DATA,WRT,NOEXE
FNM = <INFILE:>,FAC = <DEL.GET>
FAB
INFAB,INP_STR,KBF
KRF = 0,RAC = KEY

Input file logical name
DEL access
Pointer to FAB
Key buff er
Primary key
Keyed access
Maximum size records
Key string/record buff er

REC_SIZE
Key string descriptor
REC_SIZE
INP_STR
; Key string length
1
; Key value prompt string
/Please enter key value: I
CODE,NOWRT,EXE

Initialization - Open file and connect stream
.ENTRY DELETE,~M<>
$OPEN
FAB=INFAB
BLBC
RO,F_ERR
$CONNECT
RAB=INRAB
BLBC
RO,R_ERR

No registers to save
Open input file
Quit on error
Connect to input
Quit on error

Example 4-7 Cont'd. on next page

4-19

VMS RMS Example Programs
4. 6 Deleting Records

Example 4-7 (Cont.)

Use of the Delete Service

Delete record loop
READ:

FIND:

DEL:

PUSHAB
PUSHAB
PUSHAB
CALLS
BLBS
CMPL
BEQL
BRB
MOVB

INP_STR_LEN
KEY_PMT_D
INP_STR_D
#3,G-LIB$GET_INPUT
RO.FIND
RO,#RMS$_EOF
DONE
EXIT
INP_STR_LEN, INRAB+RAB$B_KSZ
$FIND
RAB=INRAB
BLBS
RO.DEL
CMPL
RO,#RMS$_RNF
BEQL
READ
BRB
R_ERR
$DELETE RAB=INRAB
BLBC
RO,R_ERR
BRB
READ

Address for string length
Prompt string descriptor
String buff er descriptor
Get input string value
Quit on error or end-of-file
Was error end-of-file?
Successful completion
Error otherwise
Set key size
Locate the record
Continue if found
No such record?
Try again
Error otherwise
Delete the record
Quit on error
Go back for more

Close files and exit
F ERR:

R_ERR:
DONE:
EXIT:

PUSHL
PUSHL
CALLS
BRB
PUSHL
PUSHL
CALLS
$CLOSE
RET
.END

FAB$L_STV+INFAB
FAB$L_STS+INFAB
#2, G-LIB$SIGNAL
EXIT
RAB$L_STV+INRAB
RAB$L_STS+INRAB
#2, G-LIB$SIGNAL
FAB=INFAB

Push STV and STS on
stack in reverse order
Signal message
Push STV and STS on
stack in reverse order
Signal message
Close files
Return with status in RO

DELETE

This program uses a key to find and delete a record. To use the $DELETE
macro, the $FAB macro for the file must set the FAB$V_DEL bit as shown in
the following code example:
INFAB:

$FAB

FNM=<INFILE:>,FAC=<DEL>

The following program statement invokes the Delete Service and points to
the input RAB:
$DELETE

4-20

RAB=INRAB

VMS RMS Example Programs
4. 7 Updating Records

4. 7

Updating Records
Example 4-8 illustrates the use of the Update service.
Example 4-8

Use of the Update Service

.TITLE UPDATE
This program looks up records in the input file and
updates those records.

INFAB:

.PSECT
$FAB

INRAB:

$RAB

REC SIZE = 132
INP STR:
.BLKB
INP_STR_D:
.LONG
.LONG
INP_STR_LEN:
.BLKL
KEY_PMT_D:
.ASCID
DATA_PMT_D:
.ASCID
.PSECT

DATA,WRT,NOEXE
FNM = <INFILE:>,FAC = <GET,UPD>
FAB
INF AB, KBF
INP_STR,KRF
0,RAC =KEY,RBF = INP STR

Input file logical name
Read and Write access
Pointer to FAB
Key buff er
Primary key
Keyed access
Record buff er
Maximum size records
Key string/record buff er

REC_SIZE
Key string descriptor
REC_SIZE
INP_STR
; Key string length
1

; Key value prompt string
/Please input key value: I
; Data value prompt string
/Please input new record value: I
CODE,NOWRT,EXE

Initialization - Open file and connect stream

FAB E:
RAB_E:

.ENTRY UPDATE,-M<>
$OPEN
FAB=INFAB
BLBC
RO,FAB_E
$CONNECT
RAB=INRAB
BLBC
RO,RAB_E
BRB
READ
BRW
F ERR
BRW
R_ERR

No registers to save
Open input file
Quit on error
Connect to input
Quit on error
Begin update loop
File (FAB) error
Record (RAB) error

; Update record loop
READ:
Prompt for key value to look up.
PUSHAB
PUSHAB
PUSHAB
CALLS
BLBS
CMPL
BEQL
BRW

INP_STR_LEN
KEY_PMT_D
INP STR_D
#3,G-LIB$GET_INPUT
RO.FIND
RO,#RMS$_EOF
ALL_D
EXIT

Address for string length
Prompt string descriptor
String buff er descriptor
Get input string value
Quit on error or end-of-file
Was error end-of-file?
Successful completion
Error otherwise

Example 4-8 Cont'd. on next page

4-21

VMS RMS Example Programs
4. 7 Updating Records

Example 4-8 (Cont.)
ALL_D:
FIND:

BRW
MOVB
$FIND
BLBS
CMPL
BEQL
BRB

Use of the Update Service

DONE
INP_STR_LEN, INRAB+RAB$B_KSZ
RAB=INRAB
RO,UPD
RO,#RMS$_RNF
READ
R_ERR

Set key size
Locate the record
Continue if found
No such record?
Try again
Error otherwise

Prompt for new data record.
UPD:
INP_STR_LEN
DATA PMT_D
INP_STR_D
#3,G-LIB$GET_INPUT
RO.EXIT
INP_STR_LEN, INRAB+RAB$W_RSZ
$UPDATE RAB=INRAB
BLBC
RO,R_ERR
BRW
READ
PUSHAB
PUSHAB
PUSHAB
CALLS
BLBC
MOVW

Address for string length
Prompt string descriptor
String buffer descriptor
Get input string value
Quit on error
Set record size
Write the record
Quit on error
Go back for more

Close files and exit
F ERR:

R_ERR:
DONE:
EXIT:

PUSHL
PUSHL
CALLS
BRB
PUSHL
PUSHL
CALLS
$CLOSE
RET
.END

FAB$L_STV+INFAB
FAB$L_STS+INFAB
#2, GALIB$SIGNAL
EXIT
RAB$L_STV+INRAB
RAB$L_STS+INRAB
#2, GALIB$SIGNAL
FAB=INFAB

Push STV and STS on
stack in reverse order
Signal message
Push STV and STS on
stack in reverse order
Signal message
Close files
Return with status in RO

UPDATE

This program uses a key and a new record entered from the terminal to
update a record in the input file.
To use the $UPDATE macro, the $FAB macro for the file must specify that
the FAB$V_UPD bit is marked in the file access (FAB$B_FAC) field as shown
in the following code example:
INFAB:

$FAB

FNM=<INFILE:>,FAC=<GET, UPD> -

Before updating a record, the program uses the Find service to locate the
record by executing the $FIND macro located at the FIND label.
$FIND

4-22

RAB=INRAB

VMS RMS Example Programs
4.8 Using Block 1/0

4.8

Using Block 1/0
In addition to the major types of record access provided by the sequential,
random by key value or relative record number, and random by RFA access
modes, VMS RMS provides another means to access data in a file: block I/O.
Block I/O operations let you directly read or write the blocks of a file. These
operations are provided for users who must keep system overhead to a
minimum and need no interpretation of file data as logical records, yet still
want to take advantage of the easy file access of VMS RMS. Block I/O is an
intermediate step between the VMS RMS record operations and direct use of
VMS $QIO system services.
The three block 1/0 services are invoked using the $READ, $SPACE, and
$WRITE macros, respectively.
•

The Read service transfers a specified number of bytes to memory.

•

The Space service positions a file forward or backward a specified number
of blocks.

•

The Write service writes a specified number of bytes to a file.

The Read and Write services always begin on a block boundary.
In addition to the Read, Space, and Write services, you can use the following
services on a record stream connected for block I/O operations:
•

The Disconnect service ($DISCONNECT macro)

•

The Flush service ($FLUSH macro)

•

The Next Volume service ($NXTVOL macro)

•

The Rewind service ($REWIND macro)

These services perform miscellaneous operations or disconnect the record
stream. They do not work on the contents of the records themselves.
You cannot perform block I/O operations on shared files. That is, file access
for block I/O operations is denied unless the FAB$V_UPI or the FAB$V_NIL
bit is set in the FAB$B_SHR field.
You specify block 1/0 operations for a record stream by setting the FAB$V_
BIO bit in the file access (FAB$B_FAC) field as input to the Open or Create
services. If you intend to write to the file, you must set the PUT option in the
FAB$B_FAC field; if you intend to read from the file, you must set the GET
option in the FAB$B_FAC field. Setting the FAB$V_BIO bit when you are
creating a relative or indexed file causes VMS RMS to omit prolog processing
for indexed files and initial space prezeroing in relative files.
For files of unknown organization, block I/O is the only form of processing
allowed. Processing proceeds identically to that for block I/O to the relative
file organization described above.

4-23

VMS RMS Example Programs
4.8 Using Block 1/0

4.8.1

Mixed Block and Record 1/0
How and when VMS RMS allows you to switch between record I/O and
block IjO depends on the organization of the file being accessed.
When you access sequential files, VMS RMS allows you to switch between
record I/O and block I/O with each record operation, if desired. To enable
I/O switching for a record stream connected to a sequential file, use the
following procedure:
1

Set the FAB$V_BRO option in the FAB$B_FAC field as input to the
Create or Open service.

Clear the RAB$L_ROP field RAB$V_BIO option as input to the Connect
service.

This procedure informs VMS RMS that it should check the RAB$V_BIO
option in the RAB$L_ROP field after each operation.
To do a block I/O operation:
1

Set the RAB$L_ROP field RAB$V_BIO option.

Invoke a VMS RMS block I/O service (Read, Space, or Write).

To do a record I/O operation:
1

Clear the RAB$L_ROP field RAB$V_BIO option.

Invoke a VMS RMS record I/O service.

Use care if you do choose to mix record and block I/O operations for
sequential files. When you switch operations on disk devices, the context
of the current record, the next record, and the next block pointer is undefined.
Thus, the first operation after the switch must not use sequential record access
mode. For magnetic tape devices, the context of the next record or next block
indicates the start of the following block on the tape for the first operation
after the switch.
As previously noted, you usually set the FAB$B_FAC field FAB$V_BRO
option only to indicate to VMS RMS that you want to mix record I/O and
block I/O operations. If you decide that you want to perform block IjO
processing only, you can set the RAB$L_ROP field RAB$V_BIO option after
you open the file but before you invoke the Connect service. This connecttime operation overrides the setting of the FAB$V_BRO option for the current
record stream and indicates to the Connect service that you only intend to
do block I/O for this file, thus eliminating the need to allocate internal I/O
buffers. (However, you must still allocate buffers for block I/O operations
in your application program.) If you set the FAB$V_BRO option when you
create an indexed file, the key definition XABs for that file must be present.
When you access relative or indexed files, switching is available only if you
close and reopen the file. VMS RMS does not permit both types of I/O
simultaneously. When multiple record streams are used, all record streams
must use the same type of I/O, either record I/0 or block I/O.
You specify the I/O type when you create or open a file by either selecting
the block I/O option (FAB$V_BIO bit set) or by selecting record IjO (FAB$V_
BIO bit clear). For relative and indexed files, the decision to use block IjO or
record I/O for a file can be postponed, if desired, until the record stream is
connected by the following procedure:

4-24

VMS RMS Example Programs
4.8 Using Block 1/0

4.8.2

Set the FAB$B_FAC field FAB$V_BRO option when you are opening (or
creating) the file.

Indicate the appropriate operation to the Connect service by either setting
the RAB$V_BIO bit in the RAB$L _ROP for block I/O or by clearing it
for record I/ 0.

The Next Block Pointer (NBP)
For block 1/0 operations to sequential files on disk devices, VMS RMS
maintains an internal next block pointer (NBP) that does the following
functions:
•

Points to the beginning of the file following execution of a Connect
service if the RAB$V_EOF option in the RAB$L_ROP field of the RAB
is cleared. If the RAB$L_ROP field RAB$V_EOF option is set, the NPB
points to the block following the end of file. The RAB$V_EOF option is
relevant only for sequential files doing block I/O processing.

•

Points to the block following the highest numbered block transferred by a
read or write operation.

•

Points to the next block following an operation invoked by the Space
service.

An explicit Extend service is required for relative and indexed files because
VMS RMS does not automatically extend a file's allocation when using block
I/ 0 processing.
Example 4-9 illustrates how to copy a file using block 1/0.
Example 4-9
. TITLE

Use of Block 1/0
BLOCKIO

This program copies the input file to the output file.
It illustrates block I/0 using the VMS RMS $READ and $WRITE
macros .
INFAB:

. PSECT
$FAB

INRAB:

$RAB

OUTFAB: $FAB

OUTRAB: $RAB

DATA,WRT,NOEXE
FNM = <INFILE:>,FAC = <BID.GET>
FAB = INFAB,BKT = 0,UBF = REC_BUFF,USZ = REC_SIZE
FNM = <OUTFILE:>,FOP = CBT,MRS = REC_SIZE,FAC = <BIO,PUT>,RAT = CR
FAB = OUTFAB,BKT = 0,RBF = REC_BUFF

REC SIZE = 1024

Input file name
Block I/O read operations
Pointer to FAB
Start with current block
Record buff er
and size
Output file name
Try for contiguous file
Maximum record size
Block I/O write operations
Implied carriage control
Pointer to FAB
Start with current block
Output uses same buff er
as input
Maximum record size

Example 4-9 Cont'd. on next page

4-25

VMS RMS Example Programs
4.8 Using Block 1/0

Example 4-9 (Cont.)
REC_BUFF:
.BLKB
.PSECT

Use of Block 1/0

REC SIZE

Record buff er

CODE,NOWRT,EXE

Initialization - Open input and output files and connect streams
.ENTRY BLOCKIO,~M<>
$OPEN
FAB=INFAB
BLBC
RO,EXIT1
$CONNECT
RAB=INRAB
BLBC
RO,EXIT2
MOVL
INFAB+FAB$L_ALQ,OUTFAB+FAB$L_ALQ
$CREATE FAB=OUTFAB
BLBC
RO,EXIT3
$CONNECT
RAB=OUTRAB
BLBC
RO,EXIT4

No registers to save
Open input file
Quit on error
Connect to input
Quit on error
Set proper size
for output
Create output file
Quit on error
Connect to output
Quit on error

Copy loop
READ:

WRITE:

$READ
BLBS
CMPL
BEQL
BRB
MOVW
$WRITE
BLBC
BRB

RAB=INRAB
RO.WRITE
RO,#RMS$_EOF
DONE
EXIT2
INRAB+RAB$W_RSZ, OUTRAB+RAB$W_RSZ
RAB=OUTRAB
RO,EXIT4
READ

Get a block
Write the block
Was error end-of-file?
Successful completion
If not, signal error
Set the record size
for output
Write the block
Quit on error
Go back for more

Error Signaling
EXIT!:
EXIT2:
EXIT3:
EXIT4:

MOVL
MOVL
BRB
MOVL
MOVL
BRB
MOVL
MOVL
BRB
MOVL
MOVL
BRB

INFAB+FAB$L_STS,R2
INFAB+FAB$L_STV,R3
EXIT
INRAB+RAB$L_STS,R2
INRAB+RAB$L_STV,R3
EXIT
OUTFAB+FAB$L_STS,R2
OUTFAB+FAB$L_STV,R3
EXIT
OUTRAB+RAB$L_STS,R2
OUTRAB+RAB$L_STV,R3
EXIT

Move STS into R2
Move STV into R3
Signal error
Move STS into R2
Move STV into R3
Signal error
Move STS into R2
Move STV into R3
Signal error
Move STS into R2
Move STV into R3
Signal error

Close files and exit
DONE:
EXIT:

4-26

$CLOSE
$CLOSE
RET
PUSHL
PUSHL
CALLS
RET
.END

FAB=INFAB
FAB=OUTFAB
R3
R2
#2,

G~LIB$SIGNAL

BLOCK IO

Close input and
output files
Return w/ success in RO
Push STV and STS
on stack
Signal error
Return w/ status in RO

VMS RMS Example Programs
4.8 Using Block 1/0

This example program uses block I/O to transfer the contents of the input file
to the output file. The following program data statements specify block I/O
read operations from the input file by setting the FAB$V_BIO bit (block I/O)
and the FAB$V_GET bit (read) in the FAB$B_FAC field of the input file's
FAB:
INFAB:

$FAB

FNM = <INFILE>, FAC = <BIO,GET>,-

; Input file name

The following data statements specify block I/O write operations to the
output file by setting the FAB$V_BIO bit (block I/O) and the FAB$V_PUT bit
(write) in the FAB$B_FAC field of the output file's FAB:
OUTFAB: $FAB

FNM = <INFILE>, FAC = <BIO,PUT>,-

;Output file name

The input file's contents are copied until the end of file is encountered. Any
errors are signaled with the convention of using both the STS and STV fields
of the appropriate control block.

4.9

Other Record-Processing Operations
See Part III for details of VMS RMS record services not discussed in this
chapter, including the Flush, Free, Next Volume, Release, Rewind, and
Wait services. A process invokes these services using the $FLUSH, $FREE,
$NXTVOL, $RELEASE, $REWIND, and $WAIT macros, respectively.

4.10

Control Routines
In addition to the general- and special-purpose file-processing macros, VMS
RMS provides three control routines for processing files. These routines are
identified by the following entry point names:
•

SYS$RMSRUNDWN

•

SYS$SETDDIR

•

SYS$SETDFPROT

These routines do not reference fields in user control blocks and are not called
with a macro. Instead, you provide an argument list and call VMS RMS at
the entry point for the routine. None of these routines is widely used, and
none is essential to normal VMS RMS file and record processing.
For information on these routines, see the VMS System Services Reference

Manual.

4-27

VMS RMS Control Blocks
Part II describes each VMS RMS control block, including a complete listing
and description of each field.

File Access Block (FAB)

The file access block (F AB) defines file characteristics, file access, and certain
run-time options. It also indicates whether other control blocks are associated
with the file.

5.1

Summary of Fields
Certain FAB fields are directly equivalent to certain File Definition Language
(FDL) attributes. For information about FDL, refer to the VMS File Definition

Language Facility Manual.
The symbolic offset, size, FDL equivalent, and a brief description of each FAB
field are presented in Table 5-1.
Table 5-1

FAB Fields

Field Offset

Size
(Bytes}

FOL Equivalent

Description

FAB$L_ALQ

FILE ALLOCATION

Allocation quantity (blocks)

None

Block identifier

FILE BUCKET_SIZE

Bucket size

None

Block length

FAB$W_BLS

FILE MT_BLOCK_SIZE

Magnetic tape block size

FAB$V_CHAN _MODE

-2

None

Channel access mode
protection

FAB$L_CTX

FILE CONTEXT

Context

FAB$W_DEQ

FILE EXTENSION

Default file extension quantity

FAB$L_DEV 3

None

Device characteristics

FAB$L_DNA

FILE DEFAULT_NAME

Default file specification string
address

FAB$B_DNS

FILE DEFAULT_NAME

Default file specification string
size

FAB$B_FAC

ACCESS 4

File access

FILE NAME

File specification string address

FILE NAME

File specification string size

FILE 4

File-processing options

RECORD CONTROL_FIELD_SIZE

Fixed-length control area size

FILE GLOBAL_BUFFER_COUNT

Global buffer count

FAB$B_BID

FAB$B_BKS
FAB$B_BLN

FAB$L_FNA

FAB$B_FNS
FAB$L_FOP

FAB$B_FSZ
FAB$W_GBC

1 This field is statically initialized by the $FAB macro to identify this control block as a FAB.
2 This is a 2-bit field.

3 This field

cannot be initialized by the $FAB macro.

4 This field contains options; corresponding FOL equivalents are listed in the description of the field.

5-1

File Access Block (FAB)
5.1 Summary of Fields

Table 5-1 {Cont.)

FAB Fields
Size
(Bytes)

FOL Equivalent

FAB$W_IFl 3

None

Internal file identifier

FAB$V_LNM_MODE

-2

None

Logical name translation access
mode

FAB$L_MRN

FILE MAX _RECORD_NUMBER

Maximum record number

FAB$W_MRS

RECORD SIZE

Maximum record size

FAB$L_NAM

None

Name block address

Field Offset

FAB$8_0RG

FILE ORGANIZATION
4

Description

File organization

FAB$8_RAT

RECORD

FAB$8_RFM

RECORD FORMAT

Record format

FILE WINDOW_SIZE

Retrieval window size

None

Secondary device
characteristics

SHARING 4

File sharing

FAB$B_RTV
FAB$L_SDC

FAB$8_SHR

Record attributes

None

Completion status code

None

Status values

FAB$L_XAB

None

Extended attribute block
address

FAB$L_STS

FAB$L_STV

2 This is a 2-bit field.

3 This field cannot be initialized by the $FAB macro.
4 This field contains options; corresponding FDL equivalents are listed in the description of the field.

Each FAB field is described below. Unless indicated otherwise, each field
is supported for DECnet operations on remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file -~ccess to
other systems, see the VMS Networking Manual.
To use a FAB, you must allocate process storage and specify the character
string for the primary file specification and, optionally, the default file
specification. The FAB$L_FNA and FAB$B_FNS fields define the primary
file specification to VMS RMS; the FAB$L _DNA and FAB$B_DNS fields
define the default file specification to VMS RMS.
The format and arguments of the $FAB macro and the $FAB_STORE macro
are defined in Appendix B.

5-2

File Access Block (FAB)
5.2 FAB$L_ALQ Field

5.2

FAB$L_ALQ Field
The allocation quantity (ALQ) field defines the number of blocks to be
initially allocated to a disk file when it is created (using a Create service) or to
be added to the file when it is explicitly extended (using an Extend service).
This field corresponds to the FDL attribute FILE ALLOCATION.
This field contains a numeric value in the range of 0 through 4,294,967,295,
although the maximum value depends on the number of blocks available on
the device to be used. A value of 0 indicates no allocation.
When you create a new file using the Create service, VMS RMS interprets the
value in the FAB$L_ALQ field as the number of blocks for the initial extent
of the file. If the value is 0, the minimum number of blocks for the specific
file organization is the allocation quantity used for the initial extent. For
example, in indexed files, only the number of blocks necessary to contain key
and area definitions is used as the initial extent quantity when FAB$L_ALQ
is 0.
When VMS RMS opens an existing file, it sets the FAB$L_ALQ field to
indicate the highest virtual block number currently allocated to the file.
When you use the Extend service, this field specifies the number of blocks to
be added to the file. Note that VMS RMS uses this value as the extension
value when a process extends a file using the Extend service unless the
process changes the value before it invokes the Extend service.
Note that the value 0 is not acceptable for extending a file.
When you use the Create and Extend services, the allocation quantity value is
rounded up to the next disk cluster boundary; the number of blocks actually
allocated is returned in the FAB$L_ALQ field.
Note that the function of the FAB$L_ALQ field with the Create and Extend
services changes if allocation control XABs are present during the operation.
The description of the XABALL control block (see Chapter 8) discusses
allocation control XABs and their effect on the FAB$L_ALQ field during file
creation or extension.

5.3

FAB$B_BID Field
The block identifier· (BID) field is a static field that identifies a control block
as a FAB. Once set, this field should not be altered unless the control block
is no longer needed. This field must. be initialized to the symbolic value
FAB$C_BID (this is done by the $FAB macro).

5.4

FAB$B_BKS Field
The bucket size (BKS) field is used only for relative or indexed files to specify
the number of blocks in each bucket of the file.
This field contains a numeric value in the range of 0 to 63. If you do not
specify a value or specify a value of 0, VMS RMS uses a default of the
minimum number of blocks needed to contain a single record, or a minimum
of two records for indexed files. If the file will be processed by RMS-11, the
bucket size must be less than or equal to 32 blocks.

5-3

File Access Block (FAB}
5.4 FAB$B_BKS Field

When calculating the bucket size, you must consider the control information
(overhead) associated with each bucket. Also, certain record types contain
control bytes; thus, the number of records per bucket multiplied by the
number of control bytes per record equals the number of record overhead
bytes per bucket. See the Guide to VMS File Applications for more information.
Before specifying a bucket size, you must be aware of the relationship
between bucket size and record size. You must also consider any record
control bytes (overhead) required by VMS RMS for the type of record chosen.
Because VMS RMS does not allow records to cross bucket boundaries, you
must ensure that the number of blocks per bucket conforms to formulae
designed to handle one of the following:
•

Relative files with fixed-length records

•

Relative files with variable-length records

•

Relative files with VFC (variable with fixed control) records

•

Indexed files with fixed-length records

•

Indexed files with variable-length records

You can use the Edit/FOL Utility to determine the optimum bucket size.
Note that if an allocation control XAB is specified, the value specified in the
XAB$B_BKZ field supersedes the value specified in the FAB$B_BKS field.
When multiple allocation control XABs are specified, the largest value in any
XAB$B_BKZ field supersedes the value in the FAB$B_BKS field. Refer to
Chapter 8 for information about the XAB$B_BKZ field.
When you open an existing relative or indexed file, VMS RMS sets the
FAB$B_BKS field to the defined size of the largest bucket size in the file.
However, when you create a new relative or indexed file, set the FAB$B_BKS
field before you invoke the Create service rather than use the default.
With indexed files, note that if the FAB$B_BKS field is not specified and a
maximum record size (FAB$W_MRS field) is specified, then VMS RMS selects
a bucket size that allows at least one maximum size record to fit. Generally,
performance for record insertion and sequential retrieval on the primary key
improves if at least six or seven data records fit into a primary data bucket.
If either the bucket size or the disk cluster size is other than one block, use a
default extension quantity (FAB$W_OEQ) that is the least common multiple
of the bucket size and cluster size to avoid allocated but unused blocks within
the file.
This field corresponds to the FOL attribute FILE BUCKET_SIZE.

5.5

FAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
FAB. Once set, this field should not be altered unless the control block is no
longer needed. This field must be initialized to the symbolic value FAB$C_
BLN (this is done by the $FAB macro).

5-4

File Access Block (FAB)
5.6 FAB$W_BLS Field

5.6

FAB$W_BLS Field
VMS RMS uses the block size (BLS) field as input for nondisk files. The
BLS field usually defines the size, in bytes, of the blocks on a magnetic tape.
Note that for some devices, this value must be an even number. This field
corresponds to the FDL attribute FILE MT_BLOCK_SIZE.
The FAB$W_BLS field contains a numeric value in the range of 20 through
65,535 for ANSI-formatted tapes and 14 through 65,532 for foreign tapes.
(Foreign tapes are those that are not in the standard ANSI format used by
the VMS operating system and must be mounted using the DCL command
MOUNT /FOREIGN.) If no value or a value of 0 is specified, the default
selected when the volume was mounted is used.
When you create a magnetic tape file, you can set the FAB$W_BLS field
before you invoke the Create service. In all other cases, VMS RMS ignores
this field. When you open an existing sequential file with an Open service,
VMS RMS returns the device buffer size. For terminals, this field defines the
WIDTH setting; for mailboxes, this field defines the maximum message size.
For compatibility with RMS-11, VMS RMS always rounds off the block size
for an ANSI-formatted tape to the next highest multiple of 4. For example,
if you set the block length to 38, VMS RMS sets it to 40. The block size of a
foreign tape is not rounded off by VMS RMS.
To create a magnetic tape for interchange with DEC operating systems other
than VMS, consult the documentation for the recipient system to identify
possible limitations on block size. ANSI standards require that the block size
be less than or equal to 2048 bytes.

5.7

FAB$V_CHAN_MODE Subfield
The channel access mode protection (CHAN_MODE) subfield is the
component part of the FAB$B_ACMODES field that specifies the access
mode in which the requested channel is assigned. VMS RMS ignores this
2-bit field unless the process first sets either the FAB$V_UFO bit or the
FAB$V_NFS bit in the FAB$L_FOP field.
The FAB$V_CHAN _MODE subfield may contain one of the four values
listed below with the related constant value for each shown in parentheses.
0

None

Executive mode (PSL$C_EXEC)

Supervisor mode (PSL$C_SUPER)

User mode (PSL$C_USER)

The default value is 0 (none), which is interpreted by VMS RMS as executive
mode.
If the access mode requested is more privileged than the access :node of the
calling process, VMS RMS uses the access mode of the caller and does not
return an error. For more information about logical name concepts, see the

VMS System Services Volume.
There is no corresponding FDL equivalent for this field. The FAB$V_CHAN_
MODE subfield is used locally for channel to DECnet communications but is
ignored on the remote system.

5-5

File Access Block (FAB)
5.7 FAB$V_CHAN_MQDE Subfield

To set this field from MACRO level, you include the appropriate expression as
an argument to the $FAB macro. For example, to specify supervisor channel
access mode, you might include a statement in this format:
$FAB

... ,CHAN_MODE = PSC$C_SUPER, ...

From a high-level language, refer to your documentation as to how (and
whether) you can directly access VMS RMS fields and then incorporate the
appropriate channel access mode expression into the appropriate language
statement.

5.8

FAB$L_CTX Field
The user context (CTX) field allows you to convey user information to a
completion routine in your program. This field contains a user-specified
value, up to four bytes long, and is intended solely for your use. VMS RMS
never uses it for record management activities.
This field corresponds to the FDL attribute FILE CONTEXT.

5.9

FAB$W_DEQ Field
The default file extension quantity (DEQ) field specifies the number of blocks
to be added when VMS RMS automatically extends the file. Automatic
extension only applies to files that reside on disk devices and occurs whenever
your process invokes a Put or Write service and the currently allocated file
space is exhausted. When you invoke a Put service, automatic file extension
occurs when needed, regardless of the file organization. When you invoke
the Write service, automatic extension occurs only for sequential files (indexed
and relative files require the Extend service to extend file allocation).
This field corresponds to the FDL attribute FILE EXTENSION.
This field contains a numeric value in the range 0 through 65,535, which
is rounded up to the next cluster boundary. A large value results in fewer
file extensions over the life of a file; a small value results in numerous file
extensions over the life of a file. When a file has numerous file extensions
that may be noncontiguous, this slows record access.
For file creation, if you do not specify a value or specify 0, VMS RMS uses
the default specified by the DCL command SET RMS_DEFAULT/EXTEND_
QUANTITY. If this value is also 0, then VMS RMS uses the system default
extension quantity specified by the SYSGEN parameter RMS_EXTEND_SIZE.
If this value is 0, then VMS RMS computes the default value.
When the value in this field, the value set by the SET RMS_DEFAULT
/EXTEND_QUANTITY command, and the value of the SYSGEN parameter
RMS_EXTEND_SIZE are all 0, VMS RMS calculates what is often a large
value to minimize the number of extend operations that it must perform. At
times, this value can exceed the available disk quota even though there is
actually enough space for the file if only the required amount is used. You
can use the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY to
limit (explicitly specify) the extension size to the recommended number of
blocks. An appropriate size is the number of blocks specified as the cluster
size for the device (set by the DCL command INITIALIZE/CLUSTER_SIZE).
For large files on a volume where there is sufficient disk space, consider using
a multiple of the cluster size to improve subsequent performance.

5-6

File Access Block (FAB)
5.9 FAB$W_DEQ Field

When creating a new file, you can specify the extension quantity for the file
by setting the desired value in the FAB$W_DEQ field before or after issuing a
Create service. This value becomes a permanent attribute for the file.
When processing an existing file, you can temporarily override the default
extension quantity specified when the file was created. To do this, set the
desired value before or after issuing the Open service. Once the file is closed,
the default extension quantity reverts to the value set when the file was
created.
See the discussion under FAB$B_BKS for indexed files.
Note that the use of an allocation control XAB overrides the value in this
field. See Chapter 8 for a detailed description of allocation control XABs.

5.10

FAB$L_DEV Field
The device characteristics (DEV) field allows your program to obtain the
generic characteristics of the device containing the file. You can locate and
test the various bits in the field using symbolic offsets. This is a binary
options field set by VMS RMS when you invoke an Open, Create, Display, or
Parse service (this is set by the Parse service only if the NAM$V_SYNCHK
option in the NAM$B_NOP field is clear).
Table 5-2 describes the bits in the device characteristics field. Each bit
has its own symbolic bit offset and mask value. These definitions are
made available to your program by referring to the $DEVDEF macro in
SYS$LIBRARY:STARLET.MLB. The symbolic bit offset is formed by prefixing
the characteristic name with DEV$V_. The mask value is formed by prefixing
the characteristic name with DEV$M_. For example, the DEV$V_REC bit has
a mask value of DEV$M_REC.
Table 5-2

Device Characteristics

Bit Offset

Description

DEV$V_ALL

Device is allocated.

DEV$V_AVL

Device is available for use.

DEV$V_CCL

Carriage control device.

DEV$V_CDP

Device has dual access paths, one of which is a remote node
using an MSCP server.

DEV$V_CLU

Device is available on a VAXcluster.

DEV$V_DET

Terminal device is detached.

DEV$V_DIR

Directory-structured device.

DEV$V_DMT

Device is marked for dismount.

DEV$V_DUA

Device has dual access paths, both of which use a disk class
driver.

DEV$V_ELG

Device is error log enabled.

DEV$V_FOD

File-oriented device (disk and magnetic tape).

DEV$V_FQR

Device is mounted foreign (non-file-structured).

DEV$V_GEN

Device is a generic device.

5-7

File Access Block (FAB)
5.10 FAB$L_DEV Field

Table 5-2 (Cont.)

Device Characteristics

Bit Offset

Description

DEV$V_IDV

Device can provide input.

DEV$V_MBX

Device is a mailbox.

DEV$V_MNT

Device is currently mounted.

DEV$V_NET

Network device.

DEV$V_ODV

Device can accept output.

DEV$V_OPR

Device has been enabled as an operator console terminal.

DEV$V_RCK

Device has read-check enabled.

DEV$V_RCT

Disk device is an RASO, RA81, RA82 or RA60.

DEV$V_REC

Record-oriented device (terminal, mailbox, line printer, for
example). If field is 0, device is assumed to be block-oriented
(disk device or magnetic tape device). All record-oriented
devices are considered sequential in nature.

DEV$V_RND

Device is random access in nature (disk).

DEV$V_RTM

Device is real-time in nature; not suitable for use by VMS RMS.

DEV$V_RTT

Terminal device is a remote terminal (DCL command SET HOST).

DEV$V_SDI

Single directory device (master file directory only).

DEV$V_SHR

Shareable device.

DEV$V_SPL

Device is bein~ spooled.

DEV$V_SQD

Sequential block-oriented device (magnetic tape).

DEV$V_SWL

Device is currently software write-locked.

DEV$V_TRM

Terminal device.

DEV$V_WCK

Device has write-check enabled.

For DECnet operations, this field represents the actual characteristics of the
target device when a Create, Open, or Display service is invoked. It is not
filled in when a Parse service is invoked using a file specification that contains
a node name.

5.11

FAB$L_DNA Field
The default file specification string address (DNA) field provides the address
of a file specification string VMS RMS uses to apply defaults for any missing
components qf the file specification. This field works with the FAB$B_DNS
field, which initializes the default file specification string size, to provide a
default file specification string. Defaults are applied after VMS RMS examines
the primary file specification string that the FAB$L_FNA field (described
below) points to.
This field and the FAB$B_DNS field correspond to the FDL attribute FILE
DEFAULT_NAME.
The FAB$L_DNA field contains the symbolic address of a default file
specification string, which is an ASCII string containing one or more
components of a file specification. The components in the string must be
in the order in which they would occur in a complete file specification.

5-8

File Access Block (FAB)
5.11 FAB$L_DNA Field

The default file specification string is used primarily when a process accepts
file specifications interactively; normally, file specifications known to a user
program are specified completely in the FAB$L_FNA and FAB$B_FNS fields.
You can specify defaults for one or more of the following file specification
components:

•

Node

•
•

Device

•

File name

•
•

File type

Directory

File version number

The default file specification string is used only if components are missing
from the string whose address is stored in the FAB$L_FNA field and those
components are present in the default file specification string.
If you use VAX MACRO, you can use the DNM keyword to specify the
FAB$L_DNA and FAB$B_DNS fields.

5.12

FAB$B_DNS Field
The default file specification string size (DNS) field indicates the size, in bytes,
of the string whose address is contained in the FAB$L_DNA field. This field
contains a numeric value in the range 1 to 255.
This field and the FAB$L_DNA field correspond to the FDL attribute FILE
DEFAULT_NAME.

5.13

FAB$B_FAC Field
The file access (FAC) field specifies the operations and services a process is
seeking to use in accessing a file. RMS uses this field, together with the share
field (SHR) in each potential accessor's FAB, to determine whether or not
to permit a process to access a file. The FAC field corresponds to the FDL
primary attribute ACCESS.
Within the FAC field, each bit position corresponds to an operation or service
option that the process intends to use when accessing the file. In this manner,
a process may specify several options, assuming they are compatible, by
setting the appropriate bits. Each option has its own symbolic bit offset and
mask value. For example, the GET service option has a symbolic bit offset of
FAB$V_GET and a mask value of FAB$M_GET.
When RMS attempts to open a file for a process, it examines the process's
FAB$B_FAC field to determine what operations or services the process is
seeking to use in conjunction with the file access.
VMS RMS determines whether or not the process seeking access to the file
intends to use operations and services that are compatible with the sharing
options permitted by processes currently accessing the file. It checks the FAC
field of the requesting process to determine whether it requires read or write
access to the file. It then checks the SHR field of the requesting process to
determine whether it will share read or write access with other processes that

5-9

File Access Block (FAB)
5.13 FAB$B_FAC Field

are accessing the file. A read (GET) implies read access. Delete (DEL), write
(PUT), truncate (TRN), and update (UPD) all imply write access.
For example, assume that Process A opens the file for GET access (FAC=GET)
and is willing to share the file with processes that are doing GET and PUT
accesses (SHR=GET,PUT). Since this is the only process accessing the file,
RMS permits it to read access the file.
Assume that a second process, Process B, wants to access the same file doing
PUT accesses (FAC=PUT) and is willing to share the file with processes
doing GET accesses and PUT accesses (SHR=GET,PUT). Because Process Bis
compatible with Process A (they both agree to share the file with any process
that is doing either GET accesses or PUT accesses), VMS RMS permits the
second process to access the file.
Now assume that a third process, Process C, wants GET access (FAC=GET) to
the same file but will share the file only with processes doing GET accesses
(SHR=GET). Although Process C is compatible with Process A (FAC=GET), it
is not compatible with Process B (FAC=PUT), so RMS denies Process C access
to the file. Conversely, if C tries to access the file before B, C gets access and
B is denied access.
VMS RMS always grants file access to the first process accessing a file,
assuming no security access restrictions exist. When a process acquires access
to a file, RMS rejects any attempt to use a service not included in the initial
access request.
The FAB$B_FAC field options are listed below.
Options
FAB$V_BIO
Requests file access for doing block 1/0 operations that use Read (FAB$V_
GET), Write (FAB$V_PUT) or the Space services. Specifying block 1/0
prohibits the use of record 1/0 operations (such as the Get, Put, Update,
Delete, or Truncate services).
This option corresponds to the FDL attribute ACCESS BLOCK_IO.
FAB$V_BRO
Requests file access for doing either block 1/0 or record 1/0 as determined
by the state of the RAB$V_BIO bit in the RAB at connect time. For additional
information, see Section 4.8, under the discussion of block 1/0, and
Section 7.19.
This option corresponds to the FDL attribute ACCESS RECORD_IO.
FAB$V_DEL
Requests file access for invoking the Delete service (or the equivalent VAX
language statement that deletes a record). This option applies only to relative
and indexed files.
This option corresponds to the FDL attribute ACCESS DELETE.
FAB$V_GET
Requests file access for invoking either the Get or Find service (or equivalent
VAX language statement that reads a record). This is the default if a process
requests access to a file without including FAB$B_FAC field information or if
the FAB$V_DEL, FAB$V_UPD, or FAB$V_TRN option is set in the FAB$B_
SHR field. If the process takes the FAB$V_GET option together with either

5-10

File Access Block (FAB)
5.13 FAB$B_FAC Field

the FAB$V_BIO option or the FAB$V_BRO option, it can invoke the Read
service.
This option corresponds to the FDL attribute ACCESS GET.
FAB$V_PUT
Requests file access for invoking either the Put or Extend service (or the
equivalent VAX language statement that writes a record or extends a file).
This is the default when a process creates a file. If the process takes the
FAB$V_PUT option together with either the FAB$V_BIO option or the
FAB$V_BRO option, it can invoke the Write service.

This option corresponds to the FDL attribute ACCESS PUT.
FAB$V_TRN
Requests file access for invoking the Truncate service (or the equivalent VAX
language statement that truncates a file). Also allows use of the RAB$L_ROP
truncate-on-put (RAB$V_TPT) option with the Put and Write service. This
option applies only to sequential files.

This option corresponds to the FDL attribute ACCESS TRUNCATE.
FAB$V_UPD
Requests file access for invoking either an Update or Extend service (or the
equivalent VAX language statement that rewrites a·reeord or extends a file).
Also allows use of the RAB$L_ROP update-if (RAB$V_UIF) option for the
Put service.

This option corresponds to the FDL attribute ACCESS UPDATE.

5.14

FAB$L_FNA Field
The file specification string address (FNA) field works with the FAB$B_FNS
field to specify the primary file specification of the file to be processed. If this
string does not contain all the components of a full file specification, VAX
RMS uses the defaults supplied in the default file specification string (see
FAB$L_DNA and FAB$B_DNS). If no default string is present or if the file
specification is still incomplete, VMS RMS provides additional defaults.
This field contains the symbolic address of a file specification string, which
is an ASCII string containing one or more components of a file specification.
This field is used as input by many file-processing services. To obtain the file
specification returned by VMS RMS after it translates any logical names and
applies defaults, a NAM block must be present (see FAB$L_NAM).
If you use VAX MACRO, you can use the FNM keyword to specify the

FAB$L_FNA and FAB$B_FNS fields.
This field and the FAB$B_FNS field correspond to the FDL attribute FILE
NAME.

5-11

File Access Block (FAB}
5.15 FAB$B_FNS Field

5.15

FAB$B_FNS Field
The file specification string size (FNS) field specifies the size, in bytes, of the
ASCII file specification string, whose address is contained in the FAB$L_FNA
field. This field contains a numeric value in the range of 0 through 255.
This field and the FAB$L_FNA field correspond to the FDL attribute FILE
NAME.

5.16

FAB$L_FOP Field
FAB$L_FOP is the symbolic offset value for the FAB's file-processing options
(FOP) field. This field specifies which of the various optional file operations
are to be implemented for the process.
The FOP is a 32-bit field in which each file-processing option has a
corresponding bit assignment to let you specify multiple options (multiple
bits can be set), when applicable. Each option has a unique symbolic offset
value and mask value but you need only specify the appropriate 3-letter
mnemonic when coding a function. For example, the spool-file-on-close
option has a symbolic offset value of FAB$V_SPL but to specify the option,
you use the following MACRO statement:
FOP=SPL

As detailed in the appropriate descriptions, the only file-processing option
bits that may be affected by VMS RMS services are the FAB$V_CBT, FAB$V_
CTG, FAB$V_RCK, and FAB$V_WCK bits.
This section presents the file-processing options alphabetically within the
various functional categories, of which there are seven:

•
•
•
•
•

Allocation and extension options

•
•

Magnetic tape processing options

Performance options
Reliability options
File name parsing modifiers
File disposition options

Nonstandard processing options

Table 5-3 lists each of the options alphabetically by category.
Table 5-3

File Processing Options

Option

Symbolic Offset

Allocation and Extension Options
Contiguous best try
Contiguous allocation
Truncate at end of file

5-12

FAB$V_CBT
FAB$V_CTG
FAB$V_TEF

File Access Block (FAB)
5.16 FAB$L_FQP Field

Table 5-3 (Cont.)

File Processing Options

Option

Symbolic Offset

Performance Options
Asynchronous operation

FAB$V_ASY

Deferred write

FAB$V_DFW

Sequential only

FAB$V_SQO

Synchronous status

FAB$V_SYNCSTS

Reliability Options
Read-check

FAB$V_RCK

Write-check

FAB$V_WCK

File Name Parsing Modifier Options
Create-if

FAB$V_CIF

Maximum version number

FAB$V_MXV

Use NAM block inputs

FAB$V_NAM

Output file parse

FAB$V_OFP

Supersede existing file

FAB$V_SUP

File Disposition Options
Delete on close

FAB$V_DLT

Submit command file on close

FAB$V_SCF

Spool file on close

FAB$V_SPL

Temporary marked for delete

FAB$V_TMD

Temporary file

FAB$V_TMP

Magnetic Tape Options
Do not set to EOF

FAB$V_NEF

Current position

FAB$V_POS

Rewind file on close

FAB$V_RWC

Rewind file on open

FAB$V_RWO

Nonstandard Options
Non-file-structured

FAB$V_NFS

User file open

FAB$V_UFO

This field corresponds to the FDL primary attribute FILE.

5-13

File Access Block (FAB)
5.16 FAB$L_FQP Field

Allocation and Extension Options
FAB$V_CBT
Contiguous best try; indicates that the file is to be allocated contiguously
on a "best effort" basis. It is input to the Create service and output from
the Open service to indicate the file status. Note that the FAB$V_CBT bit
remains set only if allocation using one, two, or three extents is actually
performed. That is, the FAB$V_CBT bit is switched off before the return from
the Create service unless VMS RMS can allocate the file within three extents.
The FAB$V_CBT option overrides the FAB$V_CTG option. Note that this
option is ignored if multiple areas are defined for an indexed file.

This option corresponds to the FDL attribute FILE BEST_TRY_
CONTIGUOUS.
FAB$V_CTG
Contiguous; indicates that the space for the file is to be allocated contiguously.
If this cannot be done, the operation fails. It is input to the Create service
and is output by the Open service to indicate the status of the file. Note that
this option is ignored if multiple areas are defined for an indexed file. The
FAB$V_CBT option overrides the FAB$V_CTG option.

This option corresponds to the FDL attribute FILE CONTIGUOUS.
FAB$V_TEF
Truncate at end of file;. indicates that unused space allocated to a file is to be
deallocated on a Close service. The FAB$V_TEF option applies to unshared
sequential files.

This option corresponds to the FDL attribute FILE TRUNCATE_ON _CLOSE.
Performance Options
FAB$V_ASY
Asynchronous; indicates that the specified task is to be done asynchronously.
The FAB$V_ASY option is relevant only to tasks that involve I/O operations
and is ignored for process permanent files. The asynchronous I/O option is
typically used with success/error ASTs, or in conjunction with the $WAIT
service, to synchronize the program with task completion. When you specify
FAB$V_ASY, you pass the address of the FAB as an argument to the AST
routine and VMS RMS returns control to your program immediately.
FAB$V_DFW
Deferred write; indicates that writing back to the file of modified I/O buffers
is to be deferred until the buffer must be used for other purposes. This option
applies to relative files, indexed files and sequential files opened for shared
access.

This option corresponds to the FDL attribute FILE DEFERRED_WRITE and is
not supported for DECnet operations.
FAB$V_SQO
Sequential only; indicates that the file can be processed only in a sequential
manner, permitting certain processing optimizations. Any attempt to perform
random access results in an error. The FAB$V_SQO option is input to the
Create and Open services.

5-14

File Access Block (FAB)
5.16 FAB$L_FQP Field

This option corresponds to the FDL attribute FILE SEQUENTIAL_ONLY.

Note: For DECnet operations, this option enables file transfer mode for Get, Put,
Read, and Write services. File transfer mode is a Data Access Protocol
(OAP) feature that allows several records to be transferred in a singlenetwork 1/0 operation to maximize throughput for single-direction,
sequential access file transfer.
FAB$V_SVNCSTS
When you select this option, VMS RMS returns the success status RMS$_
SYNCH if the requested service completes its task immediatly. The most
common reason for not completing a task immediatly is that the task involves
I/O operations.

The status RMS$_SYNCH is returned in RO. Refer to the FAB$L_STS field
for the actual success status or failure status of the task.
The FAB$V_SYNCSTS option is best used in conjunction with the FAB$V_
ASY option.
Reliability Options
FAB$V_RCK
Read-check; specifies that transfers from disk volumes are to be checked by a
read-compare operation, which effectively doubles the amount of disk I/O at
some increase in reliability. This option is an input to the Open and Create
services. If FAB$V_RCK is set, then checking is performed for the duration
of the access. The FAB$V_RCK option is also an output of the Open service,
which indicates the default for the file. This option is not available for RXOl
and RX02 devices, or for any device that has been mounted using the DCL
command MOUNT/FOREIGN.

This option corresponds to the FDL attribute FILE READ_CHECK.
FAB$V_WCK
Write-check; indicates that transfers to disk volumes are to be checked by a
read-compare operation. The FAB$V_WCK option is similar to the FAB$V_
RCK option. This option is not available for RXOl and RX02 devices, or
for any device that has been mounted using the DCL command MOUNT
/FOREIGN.

This option corresponds to the FDL attribute FILE WRITE_CHECK.
File Name Parsing Modifiers
FAB$V_CIF
Create if nonexistent; opens an already existing file if it exists. If the file does
not exist, it is created and the alternate success status RMS$_CREATED is
returned to indicate that the file was created, not just opened. The FAB$V_
CIF option is input only to the Create service and overrides the FAB$V_SUP
option. When the create-if option is used with a search list logical name and
the file is not found in any of the file specifications supplied using the search
list, the file is created using the file specification from the first element of the
search list.

This option corresponds to the FDL attribute FILE CREATE_IF.

5-15

File Access Block (FAB)
5.16 FAB$L_FQP Field

FAB$V_MXV
Maximize version number; indicates that the version number of the file
should be the maximum of the explicit version number given in the file
specification, or one greater than the highest version number for an existing
file in the same directory with the same file name and file type. This option
enables you to create a file with a specific version number (if the requested
version number is greater than that of the existing file) or a file with a version
number that is one higher than the existing file's version number.

This option is used as input to the Create service only and it corresponds to
the FDL attribute FILE MAXIMIZE_VERSION (default is "YES").
FAB$V_NAM
Use NAM block inputs; indicates that the NAM block whose address is
contained in the FAB$L_NAM (name block address) field provides the
device, file, and/or the directory identification when a file is being opened,
closed, or erased (deleted). If a file is being created, the field specifies the
device and directory identification.

This option has no corresponding FDL attribute and it is not supported for
DECnet operations. See Chapter 6.
FAB$V_OFP
Output file parse; specifies that related file resultant file specification strings, if
used, are to provide directory, file name, and file type defaults only (requires
NAM block).

This option corresponds to the FDL attribute FILE OUTPUT_FILE_P ARSE.
FAB$V_SUP
Supersede existing file; allows an existing file to be superseded on a Create
service by a new file of the same name, type, and version. The FAB$V_CIF
and the FAB$V_MXV option take precedence over the FAB$V_SUP option.

This option corresponds to the FDL attribute FILE SUPERSEDE.
File Disposition Options

FAB$V_DLT
Delete file on Close; indicates that the file is to be deleted when closed. This
option may be specified for the Create, Open, or Close services. However,
if you set the bit when you create or open a file, VMS RMS deletes the file
when you close it, regardless of the state of the bit when you invoke the
Close service. You can specify the FAB$V_DLT option with the FAB$V_SCF
or FAB$V_SPL option.

This option corresponds to the FDL attribute FILE DELETE_ON _CLOSE.
FAB$V_SCF
Submit command file on Close; indicates that the file is to be submitted as a
batch-command file to the process-default batch queue (SYS$BATCH) when
the file is closed. This option can be specified for the Create, Open, and Close
services. However, if you set the bit when you create or open a file, VMS
RMS submits the file to SYS$BATCH when you close it, regardless of the
state of the bit when you invoke the Close service.

The FAB$V_SCF option applies to sequential files only and it corresponds to
the FDL attribute FILE SUBMIT_ON _CLOSE.

5-16

File Access Block (FAB)
5.16 FAB$L_FQP Field

FAB$V_SPL
Spool file on Close; indicates that the file is to be spooled to the processdefault print queue (SYS$PRINT) when the file is closed. This option can
be specified for the Create, Open, or Close services. However, if you set the
bit when you create or open a file, VMS RMS spools the file to SYS$PRINT
when you close it, regardless of the state of the bit when you invoke the
Close service.

The FAB$V_SPL option applies to sequential files only and it corresponds to
the FDL attribute FILE PRINT_ON _CLOSE.
FAB$V_TMD
Temporary file marked for delete; indicates that a temporary file is to be
created but is to be deleted when the file is closed. This option is input only
to the Create service. The FAB$V_TMD option takes precedence over the
FAB$V_TMP option.

This option corresponds to the FDL attribute FILE TEMPORARY.
FAB$V_TMP
Temporary file; indicates that a temporary file is to be created and retained,
but that no directory entry is to be made for it. This option is used solely as
input to the Create service. If you have a NAM block, you are given the file
identification (FID) of the file which you can use to reopen the file. If you
do not have a NAM block or if you do not save the FID, the file becomes
inaccessible once it is closed. The FAB$V_TMD option overrides the FAB$V_
TMP option.

This option corresponds to the FDL attribute FILE DIRECTORY_ENTRY
("NO" means this bit is set).
Magnetic Tape Processing Options
FAB$V_NEF
Do not position to end of file; inhibits positioning to the end of a file when
a tape file is opened and the FAB$B_FAC (file access) field indicates a Put
service.

This option corresponds to the FDL attribute FILE MT_NOT_EOF.
FAB$V_PQS
Current position; directs VMS RMS to position the magnetic tape volume set
immediately after the most recently closed file when it creates the next file.
If you use this option when you invoke the $CREATE service, VMS RMS
overwrites all files located beyond the current tape position.

The FAB$V_POS option corresponds to the FDL attribute FILE MT_
CURRENT_POSITION. The FAB$V_RWO option overrides the FAB$V_
POS option.
FAB$V_RWC
Rewind file on Close; specifies that the magnetic tape volume is to be
rewound when the file is closed. This option can be specified for the Close,
Create, or Open services.

This option corresponds to the FDL attribute FILE MT_CLOSE_REWIND.

5-17

File Access Block (FAB)
5.16 FAB$L_FQP Field

FAB$V_RWO
Rewind on Open; specifies that the magnetic tape volume is to be rewound
before the file is opened or created. If you use this option when you invoke
the $CREATE service, VMS RMS overwrites all files currently on the tape
volume or volume set. The FAB$V_RWO option takes precedence over the
FAB$V_POS option.

This option corresponds to the FDL attribute FILE MT_OPEN_REWIND.
Nonstandard Processing Options
FAB$V_NFS
Non-file-structured; indicates (on an Open or Create service) that the volume
is to be processed in a non-file-structured manner. This option allows the use
of volumes created on non-DIGITAL systems.

The FAB$V_NFS option corresponds to the FDL attribute FILE NON_FILE_
STRUCTURED and it is not supported for DECnet operations.
FAB$V_UFO
User file open; indicates that VMS RMS operations for this file are limited to
opening it or creating it. To perform additional processing of the file, invoke
the SYS$QIO system service using the channel number returned by VMS
RMS in the status value field (FAB$L_STV). This channel is assigned the
access mode of the caller unless otherwise specified by the FAB$V_CHAN _
MODE bits.
If you specify this option, you must set the FAB$B_SHR field FAB$V_UPI
bit option unless the file is not shared (FAB$B_SHR field FAB$V_NIL option
is set). For the Create service, the end-of-file mark is set to the end of the
block specified in the FAB$L_ALQ field on input. For either the Open or
Create services, the FAB$W_IFI field is set to 0 on return to indicate that VMS
RMS cannot perform any more operations on the file. If you set the FAB$V_
UFO option with the Open or Create service, the channel needs only to be
deassigned when you finish with the file. A Close service is not required.

This option corresponds to the FDL attribute FILE USER_FILE_OPEN and it
is not supported for DECnet operations.

5.17

FAB$B_FSZ Field
The fixed-length control area size (FSZ) field is used only for variable with
fixed-length control (VFC) records. When you create a file with this record
type, you must set the value for the fixed-control area before you issue the
Create service. When you open an existing file that contains variable with
fixed control records, VMS RMS sets this field equal to the value specified
when the file was created. The FAB$B_FSZ field is not applicable to indexed
files.
This field corresponds to the FDL attribute FILE CONTROL _FIELD_SIZE.
This field contains a numeric value in the range of 1 to 255 that indicates, in
bytes, the size of the fixed control area; the default size is two bytes. If you
do not specify a value or specify 0, then the default size is used.

5-18

File Access Block (FAB)
5.18 FAB$W_GBC Field

5.18

FAB$W_GBC Field
The global buffer count (GBC) field indicates the requested number of global
buffers for a file. This field contains a numeric value in the range of 0 to
32,767; the default is 0.
Global buffers support sharing of I/O buffers by more than one process.
The use of global buffers can minimize I/O operations for a shared file, thus
reducing record access time at the cost of using additional system resources.
VMS RMS is able to locate requested records (or blocks) in the global buffers
associated with this file, which it can read directly from memory, eliminating
much I/O. However, since global buffers use global sections, the value
contained in FAB$W_GBC is limited by systemwide restrictions on resources
determined by the system parameters GBLSECTIONS (number of global
sections), GBLPAGES (number of global page table entries), GBLPAGFIL
(number of systemwide pages allowed for global page-file sections, or scratch
global sections), and RMS_GBLBUFQUO (total number of simultaneously
active VMS RMS global buffers allowed for the system).
For a complete description of these parameters, see the VMS System Generation

Utility Manual.
If global buffers are specified for a file, global buffers are used instead of local
(process) buffers, with the exception of deferred write operations (FAB$L_
FOP field FAB$V_DFW option).

The value that is specified when the file is created is returned in the FAB$W_
GBC field as output from the Open service. This value is then used as input
to the Connect service.
If you want to override the default value specified when the file was created,
you can set a different value in the FAB$W_GBC field after opening the file
but before invoking the Connect service. If you do not want to use global
buffers, you can clear the field before issuing the Connect service if the
default value is not 0.
If you modify the value in the FAB$W_GBC field that is returned from the
Open service prior to the Connect service, this action determines whether or
not global buffers are assigned to your process.
If you want to permanently change the default global buffer count value for
the file, use the following DCL command:
$ SET FILE file-spec /GLOBAL_BUFFERS=buffer-count

If you want to permanently clear the default global buffer count for a file, use
the following DCL command:
$ SET FILE file-spec /GLOBAL_BUFFERS=O

You can also vary the number of global buffers used each time you process
the file. If you choose this method, you change (or clear) the FAB$W_GBC
field after you open the file, but before you invoke the Connect service. In
this case, the specified value is assigned to the FAB$W_GBC field, or the
FAB$W_GBC field remains clear only for the current processing of the file;
that is, you do not permanently alter the FAB$W_GBC field in the FAB. If
no value is specified in the FAB$W_GBC field when the file is created, the
default value is 0.

5-19

File Access Block (FAB)
5.18 FAB$W_GBC Field

The number of global buffers for a file is determined by the first record stream
to connect to the file (systemwide). If the file is already open and connected,
then the number of global buffers is already set and modifications made
before the Connect service are useful only to request that this process use (or
not use) global buffers.
To specify a read-only global buffer cache, the initial accessor must set the
FAB$B_SHR field FAB$V_SHRGET and FAB$V_MSE bits on. Selecting the
FAB$V_MSE option turns on locking to coordinate access to the global buffer
cache.
You can use global buffers for all file organizations opened for shared record
access. If the global buffer count is nonzero for the first process that connects
to the file, then a temporary global section that is large enough to contain the
specified number of buffers (as well as internal VMS RMS data structures) is
created and mapped. Subsequent processes that connect to the file map this
section, thus allowing multiple processes to reference a single set of one or
more buffers without performing additional 1/0 operations. Thus, the first
user to open the file requesting global buffers determines the number of the
global buffers.
This field corresponds to the FDL attribute FILE GLOBAL _BUFFER_COUNT
and it is not supported for DECnet operations.

5.19

FAB$W_IFI Field
The internal file identifier (IFI) field is set by VMS RMS to associate the FAB
with the corresponding internal file access block. VMS RMS sets this field
on successful Create or Open services. It is then an input for subsequent
Close, Connect, Display, and Extend services. The Close service deallocates
the internal control structures and clears the FAB$W_IFI field. When the
user file open (FAB$V_UFO) option in the FAB$L_FOP field is specified, no
internal structures are allocated on Create or Open services. Therefore, the
FAB$ W_IFI field remains cleared.
There is no FDL equivalent for this field.

5.20

FAB$V_LNM_MODE Subfield
The logical name translation access mode (LNM_MODE) subfield is the
component part of the FAB$B_ACMODES field that specifies the outermost
access mode that VMS RMS uses to translate logical names during parsing.
The FAB$V_LNM_MODE subfield contains one of the following values:
0

None

Executive mode (PSL$C_EXEC)

Supervisor mode (PSL$C_SUPER)

User mode (PSL$C_USER)

The default value is 0 (none), which VMS RMS interprets as user mode.
The FAB$V_LNM_MODE field is not supported for DECnet operations, and
it is ignored during any DECnet remote file access.
There is no corresponding FDL equivalent for this field.

5-20

File Access Block (FAB)
5.21 FAB$L_MRN Field

5.21

FAB$L_MRN Field
The maximum record number (MRN) field applies only to relative files and
indicates the highest record number that can be written to a file.
This field contains a numeric value of the highest numbered record allowed
in the file, in the range of 0 to 2,147,483,647, although the maximum value
depends on the number of blocks on the device to be used. The default for
this field is 0.
If you attempt to write (put) or retrieve (get) a record with a relative record
number higher than the specified limit, an error occurs and VMS RMS returns
a message indicating an invalid record number. Checking is suppressed if you
specify 0 for the FAB$L_MRN field.

Note that VMS RMS does not maintain the relative record number of the
highest existing record in the file.
This field corresponds to the FDL attribute FILE MAX_RECORD_NUMBER.

5.22

FAB$W_MRS Field
The maximum record size (MRS) field defines the size of all records in a file
with fixed-length records, the maximum size of variable-length records, the
maximum size of the data area for variable with fixed-length control records,
and the cell size (minus overhead) for relative files.
This field contains a numeric value in the range applicable to the file type
and record format (see Table 5-4) that indicates the size of the records in the
file, in bytes. This value specifies the number of bytes of data and does not
include any control bytes associated with each record.
For fixed-length records, the value represents the actual size of each record
in the file. You must specify a size when you create a file with fixed-length
records.
For variable-length records, the value represents the size of the largest record
that can be written into the file. If the file is not a relative file, a value of 0
is used to suppress record size checking, thus indicating that there is no user
limit on record size, except for the limitations listed in Table 5-4 and certain
physical limitations. For magnetic tape files, a value of 0 sets an effedive
maximum record size that is equal to the block size minus 4.
The size of variable-length records must conform to physical limitations.
With indexed and relative files, for example, records may not cross bucket
boundaries. If both the FAB$B_BKS and FAB$W_MRS fields are 0 (not
specified) for an indexed file, VMS RMS attempts to calculate a reasonable
bucket size, usually 2. Thus, if any record requires more than two buckets,
you must explicitly specify the required value for the FAB$B_BKS or the
FAB$W_MRS field. If FAB$B_BKS field is specified, the value should specify
a bucket size large enough to exceed the longest possible record.
For variable with fixed-length control records, the value includes only the
data portion; it does not include the size of the fixed control area.
For all relative files, the size is used in conjunction with the FAB$B_BKS field
to determine the size of the record cell. You must specify the FAB$W_MRS
field when you create a relative file.

5-21

File Access Block (FAB)
5.22 FAB$W_MRS Field

You specify a value when you invoke a Create service. VMS RMS returns the
maximum record size when you invoke an Open service.
Table 5-4 summarizes the maximum record size allowed for the various file
and record formats.
Table 5-4

Maximum Record Size for File Organizations and Record
Formats

File Organization

Record Format

Maximum
Record Size

Sequential

Fixed length

32,767

Sequential (disk)

Variable length

32,765

Sequential (disk)

VFC

32,767-FSZ 1

Sequential (disk)

Stream

32,767

Sequential (disk)

Stream-CR

32,767

Sequential (disk)

Stream-LF

32,767

Sequential (ANSI Tape)

Variable length

9,995

Sequential (ANSI Tape)

VFC

9,995-FSZ 1

Relative

Fixed length

32,255

Relative

Variable length

32,253

Relative

VFC

32,253-FSZ 1

Indexed, Prolog 1 or 2

Fixed length

32,234

Indexed, Prolog 1 or 2

Variable length

32,232

Indexed, Prolog 3

Fixed length

32,224

Indexed, Prolog 3

Variable length

32,224

1 The FSZ represents the size, in bytes, of the fixed control area in a record having VFC
record format. On a disk device, the length of the largest record in a sequential file using
variable or VFC format is also maintained by VMS RMS and is available through the longest
record length field (XAB$W_LRL) in the file header characteristics XAB (XABFHC). See
Chapter 10.

For DECnet remote file access, the maximum record size may be set by the
/NETWORK_BLOCK_COUNT=n qualifier to the SET RMS_DEFAULT
command or by a $XABITM parameter. DECnet remote file access can
support record sizes as large as the record sizes that VMS RMS supports. The
default number of blocks is equal to the SYSGEN parameter RMS_DFNBC,
the default for which is 8 blocks (4096 bytes). For more information about the
SET RMS_DEFAULT command, see the VMS DCL Dictionary. The SYSGEN
parameters are detailed in the VMS System Generation Utility Manual.
This field corresponds to the FDL attribute RECORD SIZE.

5-22

File Access Block (FAB)
5.23 FAB$L_NAM Field

5.23

FAB$L_NAM Field
The name block address (NAM) field specifies the address of the NAM
block used to invoke a file service, such as an Open or Create. The NAM
block, described in Chapter 6, is required only in conjunction with the file
specification processing services. But it can also be used with other services,
typically to obtain a file specification string after all logical name translation
is completed and all defaults applied. Note that the FAB$L_FOP option
FAB$V_NAM must be specified for the NAM block to be used as input (see
FAB$L_FOP).

5.24

FAB$8_QRG Field
The file organization (ORG) field assigns the organization of the file.
The FAB$B_ORG field is a keyword value field in which each file
organization has a symbolic value. Options are identified using 3-letter
mnemonics. Each option in the FAB$B_ORG field has its own symbolic
constant value. For example, the relative (REL) file organization has a
constant value of FAB$C_REL.
You must set this field before you invoke a Create service. VMS RMS returns
the contents of this field when you invoke an Open service. The options are
described in the following list:
•

FAB$C_IDX -

Indexed file organization

•

FAB$C_REL -

Relative file organization

•

FAB$C_SEQ -

Sequential file organization (default)

This field corresponds to the FDL attribute FILE ORGANIZATION.

5.25

FAB$8_RAT Field
The record attributes (RAT) field indicates the record control information
associated with each record in a file.
Within the FAB$B_RAT field, each record attribute has a corresponding bit
assignment. Each record attribute option in the field has a unique symbolic
bit offset and constant value. For example, the CR record attribute has a
symbolic bit offset of FAB$V_CR and a mask value of FAB$M_CR.
Only the FAB$V_BLK option can be paired with another option. You cannot
use FAB$V_CR, FAB$V_FTN, and FAB$V_PRN together in any combination.
For most VMS programs, the default value for this field is FAB$V_CR
(carriage return). When you create your own file, however, the default
value is 0. When you want to create a stream format file or any text file
(a file containing ASCII text), specify the FAB$V_CR option for the Create
service. VMS RMS sets this field when you invoke an Open service. When a
process-permanent file is accessed indirectly for output, the value in this field
is always an input value. VMS RMS automatically converts the records from
the record attributes specified to the actual attributes of the process-permanent
file.
This field corresponds to the FDL primary attribute RECORD.

5-23

File Access Block (FAB)
5.25 FAB$B_RAT Field

Options
FAB$V_BLK
Applicable to sequential files only; indicates that records are not permitted to
cross block boundaries.

This option corresponds to the FDL attribute RECORD BLOCK_SPAN.
FAB$V_CR
Indicates that each record is to be preceded by a line feed and followed by a
carriage return when the record is written to a carriage control device such as
a line printer or terminal.

This option corresponds to the FDL attribute RECORD CARRIAGE_
CONTROL CARRIAGE_RETURN.
FAB$V_FTN
Indicates that the first byte of each record contains a FORTRAN (ASA)
carriage control character.

This option corresponds to the FDL attribute RECORD CARRIAGE_
CONTROL FORTRAN. Records are defined as follows:
Byte 0
Value (hex)

ASCII
Character

Meaning

(null)

Null carriage control (sequence: print buffer
contents).

(space)

Single-space carriage control (sequence: line
feed, print buffer contents, carriage return).

Double-space carriage control (sequence: line
feed, line feed, print buffer contents, carriage
return).
Page eject carriage control (sequence: form
feed, print buffer contents, carriage return).

Overprint carriage control (sequence: print
buffer contents, carriage return). Allows
double printing for emphasis.

Prompt carriage control (sequence: line feed,
print buffer contents).

Other values

Same as ASCII space character: single-space
carriage control.

FAB$V_PRN
Indicates print file format for variable with 2-byte fixed-length control records,
where the fixed control area contains the carriage control specification. The
first byte of the fixed control area constitutes a "prefix" area, and the second
byte constitutes a "suffix" area, specifying carriage control to be performed
before and after printing the record respectively.

5-24

File Access Block (FAB)
5.25 FAB$B_RAT Field

This option corresponds to the FDL attribute RECORD CARRIAGE_
CONTROL PRINT.
The coding scheme of both bytes is presented below (even though they are
interpreted separately):

5.26

Bit 7

Bits 6-0

Meaning

No carriage control is specified, that is, NULL.

1-7F

Bits 6 through 0 are a count of new lines (line feed
followed by carriage return).

Bit 7

Bit 6

Bit 5

Bits 4-0

Meaning

0-1F

Output the single ASCII control
character specified by the
configuration of bits 4 through 0
(7-bit character set).

0-1F

Output the single ASCII control
character specified by the
configuration of bits 4 through 0
that are translated as ASCII characters
128 through 159 (8-bit character set).

0-1 F

Reserved.

FAB$B_RFM Field
The record format (RFM) field specifies the format for all the records in a file.
The FAB$B_RFM field is a keyword value field where each record format has
a symbolic value. Options are identified by mnemonics. Each option has its
own symbolic constant value. For example, the FIX (fixed) record format has
a symbolic constant value of FAB$C_FIX; the STMCR (stream with carriage
return) record format has a symbolic constant value of FAB$C_STMCR.
When you create the file, you must set this field before you invoke the Create
service. VMS RMS returns the record format when you invoke an Open
service. The record format options are described below.
This field corresponds to the FDL attribute RECORD FORMAT.
Options

FAB$C_FIX
Indicates fixed-length record format.
This option corresponds to the FDL attribute RECORD FORMAT FIXED.
FAB$C_STM
Indicates stream record format. Records are delimited by FF, VT, LF, or CR
LF. This format is supported for sequential files only.
This option corresponds to the FDL attribute RECORD FORMAT STREAM.

5-25

File Access Block (FAB)
5.26 FAB$B_RFM Field

FAB$C_STMCR
Indicates stream record format. Records are delimited by CR. This format is
supported for sequential files only.
This option corresponds to the FDL attribute RECORD FORMAT STREAM_
CR.

FAB$C_STMLF
Indicates stream record format. Records are delimited by LF. This format is
supported for sequential files only.
This option corresponds to the FDL attribute RECORD FORMAT STREAM_
LF.

FAB$C_UDF
Indicates undefined record format. The undefined record format is valid for
sequential files only. This is the default value if the FAB is not initialized
with a $FAB macro.
This option corresponds to the FDL attribute RECORD FORMAT
UNDEFINED.

FAB$C_VAR
Indicates variable-length record format. For the $FAB macro, this is the
default value.
This option corresponds to the FDL attribute RECORD FORMAT VARIABLE.

FAB$C_VFC
Indicates variable-length with fixed-length control record format. This format
is not supported for indexed files.
This option corresponds to the FDL attribute RECORD FORMAT VFC.

If you intend to use stream record format, then specify the FAB$V_CR record
attribute (see FAB$B_RAT).

5.27

FAB$B_RTV Field
The retrieval window size (RTV) field specifies the number of retrieval
pointers VMS RMS is to maintain in memory for the file. Retrieval pointers
are stored in the file header and indicate the beginning of each extent
associated with the file. If a file has been extended repeatedly, the extents
may be scattered noncontiguously on the disk, requiring numerous retrieval
pointers. When VMS RMS needs to access a new extent, it must first obtain
the retrieval pointer for that extent. VMS RMS first looks for the retrieval
pointer in the retrieval window, which contains the number of retrieval
pointers specified by this field. If the retrieval pointer is not in the retrieval
window, VMS RMS must first read the file header, causing an additional IjO
operation.
This field contains a numeric value in the range of 0 through 127, or 255. A
value of 0 indicates that VMS RMS is to use the system default number of
retrieval pointers. A value of 255 means to map the entire file, if possible. If
you specify a value of 255 when creating a file, the initial number of retrieval
pointers is minimal; as records are added, however, the number of retrieval
pointers increases as the number of extents increases. The system resources

5-26

File Access Block (FAB)
5.27 FAB$B_RTV Field

required for retrieval windows are subtracted from the buffered 1/0 quota of
the process. Values from 128 to 254 (inclusive) are reserved for future use.
This field corresponds to the FDL attribute FILE WINDOW_SIZE and it is not
supported for DECnet operations.

5.28

FAB$L_SDC Field
The secondary device characteristics (SDC) field is equivalent to the
FAB$L_DEV field, except that secondary device characteristics refer to
the intermediate device used for spooling or the logical link for DECnet
operations. Within the FAB$L_SDC field, the bit definitions are the same as
those defined for the FAB$L_DEV field (see Table 5-2). Like the FAB$L_
DEV field, the bit definitions must first be made available to your process
referring to the $DEVDEF system macro definition; the values are set by
certain VMS RMS services (see FAB$L_DEV for additional information).

5.29

FAB$B_SHR Field
The file sharing (SHR) field defines the record operations that the opening
process allows sharing processes to perform. VMS RMS supports file .sharing
for all file organizations.
Within the FAB$B_SHR field, each record operation that sharing processes
are permitted to do has a corresponding bit assignment. You can specify
multiple record operations (multiple bits may be set).
Options are identified by symbolic bit offsets. Note that conflicts between the
names of symbolic offsets in the FAB$B_SHR field and the names of symbolic
offsets in the FAB$B_FAC field are resolved by prefixing the letters SHR to
the symbolic offset in the FAB$B_SHR field. For example, both the FAB$B_
FAC and FAB$B_SHR fields have a bit that specifies the get record option. In
the FAB$B_FAC field, this bit offset is assigned the symbol FAB$V_GET; in
the FAB$B_SHR field, this bit is assigned the symbol FAB$V_SHRGET.
Note that the letters SHR in the mnemonic part of the bit offset symbol
may be omitted by VAX MACRO programs. Thus, the GET option, which
is common to the FAB$B_FAC and FAB$B_SHR fields, has a symbolic
bit offset of FAB$V_SHRGET and a mask value of FAB$M_SHRGET, but
VAX MACRO programs may use the synonyms FAB$V_GET and FAB$M_
GET. This rule applies to the FAB$V_SHRPUT, FAB$V_SHRGET, FAB$V_
SHRDEL, and FAB$V_SHRUPD options.
The way in which VMS RMS uses the file access (FAB$B_FAC) field and file
sharing (FAB$B_SHR) field is described in greater detail in the FAB$B_FAC
field discussion.
Note that if you do not specify a value, VMS RMS enters a value of 0 in the
FAB$B_SHR field. Defaults apply as follows:
•

If the FAB$B_FAC field is set or defaulted to FAB$V_GET, the FAB$B_

SHR field defaults to FAB$V_SHRGET.
•

If the FAB$B_FAC field is set or defaulted to either FAB$V_PUT, FAB$V_

DEL, FAB$V_UPD, or FAB$V_TRN, the FAB$B_SHR field defaults to
FAB$V_NIL. Thus, write-sharing must be explicitly requested using the
FAB$B_SHR field (because it is not the default).

5-27

File Access Block (FAB)
5.29 FAB$B_SHR Field

See the Guide to VMS File Applications for additional details on file sharing.
This field corresponds to the FDL primary attribute SHARING.
The following list includes descriptions of the sharing options.
Options

FAB$V_MSE
Allows multistream access and is relevant for record operations only. You
must specify FAB$V_MSE whenever you want to call Connect services for
multiple RABs for this FAB.

Note that if you specify the FAB$V_MSE and FAB$V_BIO options, you must
set the FAB$V_UPI bit regardless of the other sharing bits. To specify a readonly global buffer cache, the initial accessor must set the FAB$B_SHR field
FAB$V_SHRGET and FAB$V_MSE bits. Selecting the FAB$V__MSE option
turns on locking to coordinate access to buffers.
The FAB$V_MSE option is not supported for DECnet operations; an error is
returned. Although VMS RMS cannot perform multistreaming for DECnet
operations, you can obtain similar functionality by using multiple FABs to
access the file in a shared manner.
This option is available for all file organizations and corresponds to the FDL
attribute SHARING MUL TISTREAM.
FAB$V_NIL
Prohibits any file sharing by other users. If FAB$V_NIL is specified with
other options, it takes precedence.

This option corresponds to the FDL attribute SHARING PROHIBIT.
FAB$V_SHRPUT
Allows other users to write records to the file or to extend the file.

This option corresponds to the FDL attribute SHARING PUT.
FAB$V_SHRGET
Allows other users to read the file.

This option corresponds to the FDL attribute SHARING GET.
FAB$V_SHRDEL
Allows other users to delete records from the file.

This option corresponds to the FDL attribute SHARING DELETE.
FAB$V_SHRUPD
Allows other users to update records that currently exist in the file or extend
the file.

This option corresponds to the FDL attribute SHARING UPDATE.
FAB$V_UPI
This option is used when the user wants to assume responsibility for
interlocking of multiple, simultaneous accessors of a VMS RMS file. This
option disables all VMS RMS locking for the current access of the file. Except
for block I/O, the FAB$V_MSE option overrides the FAB$V_UPI option.

5-28

File Access Block (FAB)
5.29 FAB$8_SHR Field

Usually, the FAB$V_UPI option is used for a file that is open for block I/O
(FAB$V_BIO or FAB$V_BRO).
When you select the FAB$V_UFO option, you must also select the FAB$V_
UPI option if the file is write shared. A file is specified as being write shared
when you select either the FAB$V_PUT option, the FAB$V_DEL option, the
FAB$V_TRN option or the FAB$V_UPD option in the FAB$B_SHR field.
This option corresponds to the FDL attribute SHARING USER_INTERLOCK.

5.30

FAB$L_STS Field
VMS RMS sets the completion status code (STS) field with success or failure
codes before it returns control to your program (except for a subset of
errors, as detailed in Section 2.4). Register 0 contains the same status as
the SIS field. Potential error codes for specific services are listed under their
descriptions in Part III. Status codes are discussed further in Part I.

5.31

FAB$L_STV Field
The status value (STV) field is set by VMS RMS and, on the basis of the
operation performed and the contents of the completion status code (FAB$L_
SIS) field, communicates additional completion information to your program.
See Part III for the instances when VMS RMS uses the status value field.

5.32

FAB$L->CAB Field
The extended attribute block address (XAB) field specifies the XAB, or first of
a series of XABs, that you want to use for file operations. This field contains
the symbolic address of an XAB control block. A value of 0 (the default)
indicates no XABs for the file.
For some operations, you must associate extended attribute blocks (XABs)
with a FAB to convey additional attributes about a file. (See Part I for a
description of an XAB.) The FAB$L_XAB field can contain the symbolic
address of the first associated block (of a potential chainedlist of such blocks)
for the file.
VMS RMS uses XAB values as follows:
1

If you specify an XAB for either an Open or Display service, VMS RMS
returns the file attributes to the XAB.

If you specify an XAB for a Create, Close, or Extend service, VMS RMS
uses the XAB as input to those functions.

5-29

Name Block (NAM)

The name (NAM) block provides additional fields for extended file
specification use, including parsing and obtaining the actual file specification
used for a file opera ti on.

6.1

Summary of Fields
The symbolic offset, size, and a brief description of each NAM block field are
presented in Table 6-1. Additional details are given in the remaining sections
of this chapter.
Table 6-1

NAM Block Fields

Field Offset

Size
(Bytes)

NAM$B_BID 1
NAM$B_BLN

Description
Block identifier

Block length

NAM$B_DEV 2

Device string length

NAM$L_DEV 2

Device string address

Directory identification

NAM$L_DIR 2

Directory string address

NAM$T_DV1 2

Device identification

NAM$L_ESA

Expanded string area address

NAM$W_DID
NAM$B_DIR

Directory string length

NAM$B_ESL2

Expanded string length

NAM$B_ESS

Expanded string area size

File identification

NAM$W_FID
NAM$L_FNB

File name status bits

NAM$B_NAME 2

File name string length

File name string address

NAM$L _NAME
NAM$B_NODE

NAM$L_NODE

Node name string length
4

NAM$B_NOP

Node name string address
Name block options

NAM$L_RLF

Related file NAM block address

NAM$L_RSA

Resultant string area address

NAM$B_RSL2

Resultant string length

NAM$B_RSS

Resultant string area size

1 This field is statically initialized by the $NAM macro to identify this control block as a
NAM.
2 This field cannot be initialized by the $NAM macro.

6-1

Name Block (NAM)
6.1 Summary of Fields

Table 6-1 (Cont.)

NAM Block Fields

Field Offset

Size
(Bytes)

Description

NAM$8_TYPE

File type string length

NAM$L _ TYPE

File type string address

File version string length

File version string address

NAM$L_WCC 2

Wildcard context

NAM$8_VER

NAM$L_VER

This field cannot be initialized by the $NAM macro.

Each NAM block field is described below. The NAM block fields have no
corresponding FDL equivalents. However, if your application requires the
presence of a NAM block, consider using the $NAM macro (or equivalent)
perhaps in a USEROPEN or a USERACTION routine.
Unless indicated otherwise, each field is supported for DECnet operations
when the remote node is a VMS system. Note that the words "DECnet
operations" in the following descriptions refer to remote file operations
between two VMS systems. For information about the support of VMS RMS
options for remote file access to other systems, see the VMS Networking

Manual.
Depending on the VMS RMS services to be used, the user may need to
allocate program storage for the expanded string and the resultant string.
The Parse service uses the expanded string to pass information related to
wildcards (or search lists) to the Search service. When it creates a resultant
string for other VMS RMS file services, VMS RMS uses the expanded string
as a work area to apply defaults. You can use the resultant string with
VMS RMS file services to provide the file specification that results from the
translation of logical names and the application of defaults. Typical uses of
the resultant string include showing the resulting file specification after a
partial file specification is entered by a terminal user, for error reporting, and
for logging the progress of a program.
To request use of the expanded or resultant strings, you must indicate to VMS
RMS the address and size of the user-allocated buffer to receive the string.
The expanded string is indicated by the NAM$L_ESA and NAM$B_ESS
fields; the resultant string is indicated by the NAM$L _RSA and NAM$B_
RSS fields. When it fills in the expanded or resultant strings, VMS RMS
returns the actual length of the returned string in the NAM$B_ESL or
NAM$B_RSL fields.
The format and arguments of the $NAM and $NAM_STORE macros are
defined in Appendix B.

6-2

Name Block (NAM)
6.2 File Specification Component Descriptors

6.2

File Specification Component Descriptors
For each element of the fully qualified file specification returned in the
expanded-string field or the resultant-string field in the NAM block, VMS
RMS returns a descriptor in the NAM block. Two fields describe the element:
a 1-byte size field and a 4-byte (longword) address field. The fields of these
descriptors are described as one of the following:
NAM$B_xxx

(size field of xxx)

NAM$L_xxx

(address field of xxx)

Each descriptor is summarized below.
Descriptor

NAM$B_NQDE, NAM$L_NQDE
Node name descriptor, including access control string and double colon ( :: )
delimiter.
NAM$B_DEV, NAM$L_DEV
Device name descriptor, including colon (:) delimiter.
NAM$B_DIR, NAM$L_DIR
Directory name descriptor, including brackets ([and] or

< and > ).

NAM$B_NAME, NAM$L_NAME
File name descriptor or, if the file specification following a node name is
within quotation marks ("file"), a quoted string descriptor.
NAM$B_TVPE, NAM$L_TVPE
File type descriptor, including period (.) delimiter.
NAM$B_VER, NAM$L_VER
File version number descriptor, including semicolon (;) or period ( . )
delimiter.
These descriptors are returned, enabling the program to extract a particular
component from the resultant string without having to parse the resultant
or expanded string. The entire resultant or expanded string, including
delimiters, is described by the various component descriptors. If the value in
the NAM$B_RSL field is nonzero, then the descriptors point to the NAM$L_
RSA field. If the value in the NAM$B_RSL field is 0 and the value in the
NAM$B_ESL field is nonzero, then the descriptors point to the NAM$L_ESA
field. In all other cases, they are undefined.

6-3

Name Block (NAM)
6.2 File Specification Component Descriptors

As an example, a resultant file specification and its file specification
component descriptors are shown below.
NODE"TEST password"::WORK_DISK:[TEST.TEMP)FILE.DAT;3
NODE

NODE"TEST password"::

DEV

WORK_DISK:

DIR

(TEST. TEMP]

NAME

FILE

TYPE

.DAT

VER

You can use the field descriptors individually or collectively to describe
sections of the resultant or expanded string. For example, if you want to use
the file name and file type fields, use NAM$L_NAME for the starting address
and NAM$B_NAME+NAM$B_TYPE for the total length.

6.3

NAM$B_BID Field
The block identifier (BID) field is a static field that identifies this control block
as a NAM block. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
NAM$C_BID (this is done by the $NAM macro).

6.4

NAM$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
NAM block, in bytes. Once set, this field must not be altered unless the
control block is no longer needed. This field must be initialized to the
symbolic value NAM$C_BLN (this is done by the $NAM macro).

6.5

NAM$B_DEV and NAM$L_DEV Fields
The device name length and address (DEV) field contains a pointer to either
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse
service was invoked or an Open, Create, or Search service was invoked.
You can tell which name string is used by referring to the NAM$B_ESL or
NAM$B_RSL fields, which contain the length of the returned file specification
string.

6.6

NAM$W_DID Field
The directory identification (DID) field identifies the directory for the file.
VMS RMS outputs this 3-word field as part of the Open, Create, Display, and
Parse services. If, once you open the file, you want to refer to this directory
again, you can do so more quickly by specifying that the NAM block has a
valid directory identifier.
This field is not supported for DECnet operations; it is ignored on input and
zero-filled on output.

6-4

Name Block (NAM)
6.7 NAM$B_DIR and NAM$L_DIR Fields

6. 7

NAM$B_DIR and NAM$L_DIR Fields
The directory name length and address (DIR) field contains a pointer to either
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse
service was invoked or an Open, Create, or Search service was invoked.
You can tell which name string is used by referring to the NAM$B_ESL or
NAM$B_RSL fields, which contain the length of the returned file specification
string.

6.8

NAM$T_DVI Field
The device identification (DVI) field defines the device for the file. VMS RMS
outputs this field as part of the Open, Create, Display, and Parse services.
You can use this field with the file identification field to reopen the file by
referring to the NAM block. The symbolic value NAM$S_DVI gives the
length of this field in bytes. The form of this field is a counted string. The
first byte is a count of the number of characters following it.
This field is not supported for DECnet operations; it is ignored on input and
zero-filled on output.

6.9

NAM$L_ESA Field
The expanded string area address (ESA) field contains the symbolic address of
a user buffer in the application program to receive the file specification string
resulting from the translation of logical names and the application of default
file specification information.
You must specify this field for processing wildcard characters.

6.10

NAM$B_ESL Field
The expanded string length (ESL) field is set by VMS RMS as part of the
Open, Create, and Parse services. This field contains the length, in bytes,
of the file specification string returned in the buffer whose address is in the
NAM$L_ESA field.

6.11

NAM$B_ESS Field
The expanded string area size (ESS) field contains the size of the userallocated buffer whose address is contained in the NAM$L_ESA field.
This field contains a numeric value representing the size, in bytes, of the user
buffer that will receive the file specification string, in the range of 0 through
255.
The symbolic value NAM$C_MAXRSS defines the maximum possible length
of an expanded file specification string.

6-5

Name Block (NAM)
6.12 NAM$W_FID Field

6.12

NAM$W_FID Field
The file identification (FID) field is a 3-word field that VMS RMS uses to
identify the file when it invokes an Open, Create, or Display service. When
you want to open a file by using the file identifier, set this field before you
open the file.
This field is not supported for DECnet operations; it is ignored on input and
zero-filled on output.

6.13

NAM$L_FNB Field
The file name status (FNB) field is a binary options field that VMS RMS
uses to convey status information obtained from the file specification parsing
routine. Each bit within this field denotes a specific status relative to the
various components of the file specification.
Each status bit has its own offset and mask value. For instance, the number of
directory levels (DIR_LVLS) field has a symbolic bit offset of NAM$V_DIR_
LVLS and a mask value of NAM$M_DIR_LVLS. The bits and the conditions
they express for the NAM$L_FNB field are described in Table 6-2.
Table 6-2

NAM$L_FNB Status Bits

Field Offset

Description

NAM$V_CNCL _DEV

Device name is a concealed device.

NAM$V_DIR_L VLS

Indicates the number of subdirectory levels (value is 0
if there is a user file directory only); a 3-bit field.

NAM$V_EXP_DEV

Device name is explicit.

NAM$V_EXP_DIR

Directory specification is explicit.

NAM$V_EXP_NAME

File name is explicit.

NAM$V_EXP_TYPE

File type is explicit.

NAM$V_EXP_VER

Version number is explicit.

NAM$V_GRP_MBR

Directory specification is in the group/member number
format.

NAM$V_HIGHVER

A higher-numbered version of the file exists (output
from Create and Enter services). For DECnet
operations, this bit is returned as a binary zero.

NAM$V_LQWVER

A lower-numbered version of the file exists (output
from Create and Enter services). For DECnet
operations, this bit is returned as a binary zero.

NAM$V_NQDE

File specification includes a node name.

NAM$V_PPF

File is indirectly accessed process-permanent file.

NAM$V_QUOTED

File specification includes a quoted string; indicates
that the file name length and address field contains
a quoted string file specification. Applies to network
operations or magnetic tape devices only. 1

1 To distinguish network quoted string file specifications from quoted strings containing
ASCII "a" file names (supported for ANSI-labeled magnetic tapes), both the NAM$V_
QUOTED and NAM$V_NODE bits are set.

6-6

Name Block (NAM)
6.13 NAM$L_FNB Field

Table 6-2 (Cont.)

6.14

NAM$L_FNB Status Bits

Field Offset

Description

NAM$V_ROOT_DIR

Device name incorporates a root directory.

NAM$V_SEARCH_LIST

A search list logical name is present in the file
specification.

NAM$V_WILDCARD

File specification string includes a wildcard; returned
whenever any of the other wildcard bits is set.

NAM$V_WILD_DIR

Directory specification includes a wildcard character.

NAM$V_WILD_GRP

Group number contains a wildcard character.

NAM$V_WILD_MBR

Member number contains a wildcard character.

NAM$V_WILD_NAME

File name contains a wildcard character.

NAM$V_WILD_SFD 1NAM$V_WILD_SFD7

Subdirectory 1 through 7 specification includes a
wildcard character.

NAM$V_WILD_TYPE

File type contains a wildcard character.

NAM$V_WILD_UFD

User file directory specification includes a wildcard
character.

NAM$V_WILD_VER

Version number contains a wildcard character.

NAM$B_NAME and NAM$L_NAME Fields
The file name length and address (NAME) field contains a pointer to either
the NAM$L _ESA or NAM$L _RSA fields, depending on whether a Parse
service was invoked or an Open, Create, or Search service was invoked.
You can tell which name string is used by referring to the NAM$B_ESL or
NAM$B_RSL fields, which contain the length of the returned file specification
string.

6.15

NAM$B_NODE and NAM$L_NQDE Fields
The node name length and address (NODE) field contains a pointer to either
the NAM$L _ESA or NAM$L _RSA fields, depending on whether Parse
service was invoked or an Open, Create, or Search service was invoked.
You can tell which name string is used by referring to the NAM$B_ESL or
NAM$B_RSL fields, which contain the length of the returned file specification
string.

6.16

NAM$B_NOP Field
The name block options (NOP) field indicates the options applicable to the
file name parsing services.

6-7

Name Block (NAM)
6.16 NAM$B_NQP Field

The NAM$B_NOP field is a binary options field in which each option has
a corresponding bit assignment. Multiple options can be specified (multiple
bits can be set) but the default state for each bit is clear (not set). Each option
has its own symbolic bit offset and mask value. For example, the SYNCHK
option has a symbolic bit offset of NAM$V_SYNCHK and a mask value of
NAM$M_SYNCHK.
Each of these options is discussed below.
Options

NAM$V_NQCONCEAL
When used with the Open, Create, Search, or Display services, a concealed
device logical name, if present, is translated into its physical device name (and
directory, if so defined) in the resultant string field, whose address is supplied
by the NAM$L_RSA field. If this option is not set and a concealed device
name is used, the concealed device name appears in the resultant string field,
instead of the physical device name (and directory, if so defined).
NAM$V_PWD
When used with the Create, Open, Parse, Search, or Display services, the
password in the access control string of a node specification, if present, is
returned unaltered in the expanded or resultant file specification fields. If
you do not select this option, the actual password used is replaced by the
word "password" in the resultant or expanded file specification string fields
for security reasons.
NAM$V_SRCHXABS
When used with the Search service for remote file access, this option directs
VMS RMS to fill in the FAB and any chained XABs as if a Display service had
been invoked. This allows you to obtain file attribute information using the
Search service without the need to open the file.
NAM$V_SVNCHK
This gives you the option of using the Parse service to verify the syntax
validity of the file specification without invoking 1/0 processing that verifies
the actual existence of the specified device, directory and file.
If you invoke the Parse service without setting this bit, an accompanying 1/0
process verifies that the device and directory exist. Note that this processing
does not verify the existence of the file; you can only verify the existence of
the file with either a $SEARCH or $OPEN.
If you opt to set the NAM$V_SYNCHK bit when you invoke the Parse
service, VMS RMS does not return the device characteristics (FAB$L_DEV
and FAB$L_SDC fields) and does not fill in the NAM$W_DID and NAM$T_
DVI fields, rendering the results of the $PARSE unusable for subsequent
Search services.

6.17

NAM$L_RLF Field
The related file NAM block address (RLF) field contains the symbolic address
of the NAM block for the related file. This field supports the secondary file
concept of the command language (DCL), giving an extra default level in
processing file specifications.

6-8

Name Block (NAM)
6.17 NAM$L_RLF Field

To provide an extra level of file specification defaults, the related NAM block
must have been used previously by an Open, Create, Search or Display
service to create a resultant file specification string. Moving the address of
the related NAM block into the NAM$L _RLF field of the current NAM block
specifies that the previously parsed NAM block's resultant file specification
string should be used as a default when the current NAM block is parsed.
Note that the previously parsed NAM block must contain a resultant file
specification (see NAM$L_RSA and NAM$B_RSS for additional details).
Refer to the Guide to VMS File Applications for additional details on file
specification parsing concepts.

6.18

NAM$L_RSA Field
The resultant string area address (RSA) field contains the symbolic address
of a buffer in your program to receive the resultant file specification string.
The NAM$B_RSS field must also be specified to obtain a resultant file
specification string.
This string is the fully specified name of the file that results from the
resolution of all system defaults, including version numbers and wildcard
character substitution in the expanded file name string. You must specify this
field for wildcard processing.

6.19

NAM$B_RSL Field
The resultant string length (RSL) contains the length, in bytes, of the
resultant file specification string returned in the buffer whose address is
in the NAM$L_RSA field.

6.20

NAM$B_RSS Field
The resultant string area size (RSS) field defines the size of the user-allocated
buffer whose address is contained in the NAM$L_RSA field.
This field contains a numeric value representing the size, in bytes, of the user
buffer that will receive the resultant file specification string, in the range of 0
through 255.
The symbolic value NAM$C_MAXRSS defines the maximum possible length
of a resultant file specification string.

6.21

NAM$B_TVPE and NAM$L_TVPE Fields
The file type length and address (TYPE) field contains a pointer to either the
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service
was invoked or an Open, Create, or Search service was invoked. You can tell
which name string is used by referring to the NAM$B_ESL or NAM$B_RSL
fields, which contain the length of the returned file specification string.

6-9

Name Block (NAM)
6.22 NAM$B_VER and NAM$L_VER Fields

6.22

NAM$B_VER and NAM$L_VER Fields
The file version length and address (VER) field contains a pointer to either the
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service
was invoked or an Open, Create, or Search service was invoked. You can
determine the name string that is used by referring to the NAM$B_ESL or
NAM$B_RSL fields, which contain the length of the returned file specification
string.

6.23

NAM$L_WCC Field
The wildcard context (WCC) field contains the information needed to use
wildcard characters in place of the various file specification components. In
particular, this field restarts a directory search to find the next matching file
name, type, and/or version number. You can also use it to identify various
VMS RMS extended contexts; for instance, during remote file processing.

6-10

Record Access Block {RAB)

The record access block (RAB) defines run-time options for a record stream
and for individual operations within a predefined record stream context. After
you connect the file to a record stream and associate the record stream with
a FAB, you use the RAB fields to specify the next record you want to access
and to identify appropriate record characteristics.

7 .1

Summary of Fields
Table 7-1 gives the symbolic offset, size, FDL equivalent, and a brief
description of each RAB field.
Table 7-1

RAB Fields
Size
(Bytes)

Field Offset

FOL Equivalent

Description

None

Block identifier

CONNECT BUCKET_CODE

Bucket code

None

Block length

RAB$L_CTX

CONNECT CONTEXT

User context

RAB$L_FAB

None

File access block address

None

Internal stream identifier

RAB$L_KBF

RAB$B_BID 1
RAB$L_BKT
RAB$B_BLN

RAB$W_ISl

None

Key buffer address

RAB$B_KRF

CONNECT KEY_OF_REFERENCE

Key of reference

RAB$B_KSZ

None

Key size

RAB$B_MBC

CONNECT MULTIBLOCK_COUNT

Multiblock count

RAB$B_MBF

CONNECT MULTIBUFFER_COUNT

Multibuffer count

None

Prompt buffer address

RAB$L_PBF

RAB$B_PSZ

Prompt buffer size

None
3

RAB$B_RAC

CONNECT

RAB$L_RBF

None

Record buffer address

RAB$W_RFA

None

Record file address

RAB$L_RHB

None

Record access mode

Record header buffer
3

RAB$L_ROP

CONNECT

RAB$W_RSZ

None

Record size

RAB$L_STS 2

None

Completion status code

None

Status value

RAB$L_STV

Record-processing options

1 This field is statically initialized by the $RAB macro to identify this control block as a RAB.
2 This field cannot be initialized by the $RAB macro.

3 This field contains options; corresponding FOL equivalents are listed in the description of the field.

7-1

Record Access Block (RAB)
7 .1 Summary of Fields

Table 7-1 (Cont.)

RAB Fields

Field Offset

Size
(Bytes)

FOL Equivalent

Description

RAB$W _STV0

None

Low-order word status value

RAB$W _STV2

None

High-order word status value

RAB$B_TMO

CONNECT TIMEOUT_PERIOD

Timeout period

RAB$L_UBF

None

User record buffer address

RAB$W_USZ

None

User record buffer size

RAB$L_XAB

None

Next XAB address

4 Alternate definition of RAB$L_STV field.

Each RAB field is described below. Unless indicated otherwise, each field is
supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file access to
other systems, see the VMS Networking Manual.
The format and arguments of the $RAB macro and the $RAB_STORE macro
are described in Appendix B.

7 .2

RAB$B_BID Field
The block identifier (BID) field is a static field that identifies the block as a
RAB. Once set, this field must not be altered unless the control block is no
longer needed. This field must be initialized to the symbolic offset value (this
is done by the $RAB macro).

7 .3

RAB$L_BKT Field
The bucket code (BKT) field is used with records in a relative file and when
performing block 1/0.
This field contains a relative record number or a numeric value representing
the virtual block number to be accessed.
For relative files, the relative record number of the record acted upon (or
which produced an error) is returned to the RAB$L_BKT field only after the
completion of a sequential operation. That is, VMS RMS returns the relative
record number when you set the record access mode for sequential access
(RAB$B_RAC is RAB$C_SEQ) on the execution of a Get, Put, or Find service.
Before performing block 1/0 on disk devices, this field must contain the
virtual block number (VBN) of the first block you want to read or write.
For all other devices, this field is not used. If you specify a VBN of 0, VMS
RMS begins the block transfer at the block pointed to by the next block
pointer (NBP). (The NBP is an internal pointer maintained by VMS RMS; it is
described in Section 4.8.)

7-2

Record Access Block (RAB)
7.3 RAB$L_BKT Field

This field is also input to the Space service to specify the number of blocks to
be spaced forward or backward.
This field corresponds to the FDL attribute CONNECT BUCKET_CODE.

7 .4

RAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
RAB, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
RAB$C_BLN (this is done by the $RAB macro).

7.5

RAB$L_CTX Field
The user context (CTX) field contains any user-selected value, up to four bytes
long. This field is devoted exclusively to your use. VMS RMS makes no use
of the contents of this field; therefore, you can set any value you want in this
field. For example, you could use this field to communicate with a completion
routine in your program.
This field corresponds to the FDL attribute CONNECT CONTEXT.

7.6

RAB$L_FAB Field
The file access block address (FAB) field contains the symbolic address of the
FAB for the file. Before you invoke the Connect service, you must set this
field to indicate the address of the FAB associated with the open file.

7. 7

RAB$W_ISI Field
The internal stream identifier (ISI) field associates the RAB with a
corresponding FAB. VMS RMS sets this field after the execution of a Connect
service. A Disconnect service clears this field. This field should not be altered.

7 .8

RAB$L_KBF Field
The key buffer address (KBF) field contains the symbolic address of the buffer
containing the key for random access. Note that the RAB$B_KBF field has the
same offset as the RAB$B_PBF (prompt buffer address) field, but no conflict
is presented because the fields are used in mutually exclusive operations.
You use this field when the RAB$B_RAC (record access mode) field specifies
random access by key value and you set it to the address of the buffer that
contains the key of the desired record. For a relative file (or for a sequential
disk file with fixed-length records), the key is the relative record number.
For an indexed file, the key is the key value within the record for the key of
reference (RAB$B_KRF).

7-3

Record Access Block (RAB)
7 .8 RAB$L_KBF Field

Before you invoke the Get or Find service in random mode to an indexed file,
you place the address of a location containing a key value in the RAB$L_
KBF field. The size of this key value must be specified in the RAB$B_KSZ
field. During execution of the Get or Find service, VMS RMS uses the key
value described by the RAB$L_KBF and RAB$B_KSZ fields to search an
index (which you specify through the contents of the RAB$B_KRF) and locate
the desired record in the file. The type of match (that is, exact, generic,
approximate, or approximate and generic) that VMS RMS attempts between
the key value you specify and key values in records of the file is determined
by the RAB$B_KSZ field and the RAB$L_ROP field.

7 .9

RAB$B_KRF Field
The key of reference (KRF) field specifies the key or index (primary, first
alternate, and so on) to which the operation applies. The RAB$B_KRF field is
applicable to indexed files only.
This field contains a numeric value representing the key path to records in a
file. The value 0, the default, indicates the primary key. The values 1 through
254 indicate alternate keys.
When your program invokes a Get or Find service in random access mode,
the key of reference specifies the index to search for a match on the key value
that is described by the RAB$L_KBF and RAB$B_KSZ fields. When your
program invokes a Connect or Rewind service, the key of reference identifies
the index in the file of the next record in the stream. The next record is
important when records are retrieved sequentially.
This field corresponds to the FDL attribute CONNECT KEY_OF_
REFERENCE.

7.10

RAB$B_KSZ Field
The key size (KSZ) field contains a numeric value equal to the size, in bytes,
of the record key pointed to by the RAB$L_KBF field.
Note that the RAB$B_KSZ field has the same offset as the RAB$B_PSZ
(prompt buffer size) field but no conflict is presented because the fields are
used in mutually exclusive operations.
For indexed files, the size of the key depends on the key data type:
•

For string keys, a value from 1 through the size of the key field can be
used. If the specified size is less than the size of the key field, then only
the leftmost characters of each key are used for comparison.

•

For numeric key data types, a value of 0 causes VMS RMS to use the key
data type defined at file creation to determine the key size. A nonzero
value is checked against the defined size, and an error is returned if they
are not equal.

Note that for DECnet operations, the RAB$B_KSZ field must be explicitly
specified as a nonzero value because the key data type information may not
be available to VMS RMS at the local node.

7-4

Record Access Block (RAB)
7 .10 RAB$B_KSZ Field

The size of the relative record number of a record in a relative file or a
sequential file with fixed-length records is a longword, positive, integer value;
therefore, the key size is 4. For relative record numbers, the default value
of 0 causes a key size of 4 to be used. For DECnet operations, however, the
RAB$B_KSZ field must be explicitly specified as 4 for relative files.
With indexed files, the size of key values in bytes of an indexed file can be
from 1 to 255 bytes.
A program may access indexed file records directly in one of four ways:
•

By an exact match

•
•
•

By an approximate match
By a generic match
By a combination of approximate and generic matches

The program specifies the type of match using the RAB$B_KSZ field together
with two bits from the RAB$L_ROP field: the RAB$V_KGE (logically
synonymous with RAB$V_EQNXT) bit and the RAB$V_KGT (logically
synonymous with RAB$V_NXT) bit.
•

To specify an exact match, set a value in the RAB$B_KSZ field equal to
the number of bytes in the key, and reset the RAB$V_KGE bit and the
RAB$V_KGT bit.

•

To specify an approximate match, set a value in the RAB$B_KSZ field
equal to the number of bytes in the key, and set the appropriate bit.
Specifically, if you want to match on a record having either an equal
key value or the next value (greater for ascending sort order, lesser for
descending sort order) set the RAB$V_KGE (logically synonymous with
RAB$V_EQNXT) bit. If you want to match on a record having the next
value and to ignore equal key values, set the RAB$V_KGT (logically
synonymous with RAB$V_NXT) bit.

Note: Sort order is established in the data type (XAB$B_DTP) field of the
associated XABKEY when the file is created.

7.11

•

To specify a generic match, set a value in the RAB$B_KSZ field equal to
the number of leading bytes in the key you want to match on, and set the
RAB$V_KGE bit and the RAB$V_KGT bit.

•

To specify an approximate generic match, set a value in the RAB$B_KSZ
field equal to the number of leading bytes in the key you want to match
on, and set the appropriate bit.

RAB$B_MBC Field
The multiblock count (MBC) field applies only to sequential disk file
operations. This field specifies the number of blocks, in the range of 0
through 127, to be allocated to each 1/0 buffer and correspondingly, the
number of blocks of data to be transferred in each 1/0 unit. If this field is

7-5

Record Access Block (RAB)
7 .11 RAB$B_MBC Field

not specified or is specified as 0, the process default for the multiblock count
is used. If the process default is also 0, VMS RMS uses the system default.
If the system default is also 0, then the default size for each 1/0 buffer is
1 block. The DCL command SET RMS_DEFAULT is used to set process or
system defaults.
When it invokes the Connect service, VMS RMS uses the RAB$B_MBC field
to determine the number of blocks in the 1/0 transfers for this record stream
and allocates a buffer with the appropriate storage capacity. Note that the
RAB$B_MBF (multibuffer count) field may be used to allocate multiple buffers
of this size for the record stream.
The use of the RAB$B_MBC field optimizes data throughput for sequential
operations, and does not affect the structure of the file. It reduces the number
of disk accesses for record operations, resulting in faster program execution.
However, the extra buffering increases memory requirements.
Note that the RAB$B_MBC field is not used with block IfO. With
multiblocks, the number of blocks in an 1/0 unit is fixed by the multiblock
count, whereas in block 1/0 operations the number of blocks being
transferred is specified by the program.
This field corresponds to the FDL attribute CONNECT MUL TIBLOCK_
COUNT and it is not supported for DECnet operations.

7.12

RAB$8_MBF Field
The multibuffer count (MBF) field indicates the number of process-local 1/0
buffers you want VMS RMS to allocate when you invoke the Connect service
for a record stream.
This field contains a numeric value in the range of 0 to 127 that represents
the number of buffers to be allocated.
If this field is not specified or is set to 0, VMS RMS uses the process default
for the particular file organization and device type. If the process default is

also 0, the system default for the particular file organization and device type
applies. If the system default is likewise 0, one buffer is allocated. However,
if read-ahead or write-behind is specified, a minimum of two buffers is
allocated. A minimum of two buffers is also allocated for an indexed file.
VMS RMS requires that at least one buffer allocated for sequential and relative
files and at least two buffers for indexed files, unless the file is to be processed
with block 1/0 operations only. Multiple buffers can be used efficiently to
overlap 1/0 time with compute time, particularly in read-ahead or writebehind processing (see RAB$L_ROP for information on these options), and
to increase use of the buffers (as compared to disk 1/0) when performing
random processing.
Note that the RAB$B_MBF field is not used when block 1/0 access is
specified with the Open, Create, or Connect services because no buffers
are required.
This field corresponds to the FDL attribute CONNECT MUL TIBUFFER_
COUNT and it is not supported for DECnet operations.

7-6

Record Access Block (RAB)
7 .13 RAB$L_PBF Field

7.13

RAB$L_PBF Field
The prompt buffer address (PBF) field points to a character string to be used
as a prompt for terminal input. Note that the RAB$B_PBF field has the same
offset as the RAB$B_KBF (key buffer address) field but because the fields are
used in mutually exclusive operations, no conflict is presented.
This field contains the symbolic address of the buffer containing the prompt
character string. If you select the RAB$V_PMT option of the RAB$L_ROP
field when you invoke a Get service, VMS RMS outputs this character string
to the terminal before the Get service begins its task.
To perform any carriage control on the terminal, you must insert the
appropriate carriage control characters into this character string.
This field is not supported for DECnet operations; it is ignored.

7.14

RAB$B_PSZ Field
The prompt buffer size (PSZ) field indicates the size of the prompt character
string to be used as a terminal prompt. This field contains the size, in bytes,
in the range of 0 to 255.
Note that the RAB$B_PSZ field has the same offset as the RAB$B_KSZ (key
buffer size) field but no conflict is presented because the fields are used in
mutually exclusive operations.
This field is not supported for DECnet operations; it is ignored.

7.15

RAB$B_RAC Field
The record access mode (RAC) field indicates the method of retrieving or
inserting records in the file; that is, whether records are read (or written)
sequentially, directly, or by record file address. Only one access method may
be specified for any single record operation, but you can change the record
access mode between record operations.
The RAB$B_RAC field is a keyword value field in which each record access
mode has a symbolic offset. Options are identified using mnemonics. Each
access mode in the RAB$B_RAC field has its own symbolic constant. For
example, the SEQ (sequential) access mode has the symbolic constant
RAB$C_SEQ.
The RAB$B_RAC field is not applicable to block 1/0 operations and there is ,;1
no corresponding FDL attribute for this field.
The record access mode options and their meanings are described below.
Options

RAB$C_SEQ
Indicates sequential record access mode (the default); it can be specified with
any type of file organization.
Records read from (or written to) sequential files are accessed in chronological
order. That is, older records are accessed before newer records.

7-7

Record Access Block (RAB)
7 .15 RAB$B_RAC Field

Records read sequentially from indexed files are accessed by the key of
reference according to the key's sort order. Where records have duplicate
keys, older records are read before newer records regardless of the key's sort
order.
For example, assume an ascending key indexed file with four 2-byte records
(Al, Bl, B2, Cl) where the key is the first byte of each record. When
processed sequentially, the records are encountered in the following order:
A1

Here records Bl and B2 have the duplicate key B, but record Bl was inserted
chronologically before record B2 and therefore, is encountered before B2
when the program is reading records sequentially.
If this file is reorganized as a descending-key indexed file, the records are

encountered in the following order:
C1

Note that the chronological order of insertion for the two records with
duplicate keys is maintained without regard to sort order.
When records are written sequentially to indexed files, VMS RMS verifies that
the key value of each successive record is ordered correctly with respect to the
key value in the previously written record. For example, with a descending
key of reference VMS RMS ensures that the key value of the third record
written is less than the value of the second record.

RAB$C_KEY
Indicates random access by key. For relative files and sequential files on
disk with fixed-length records, random access is by relative record number.
Indexed files are accessed directly by specifying the appropriate value for the
key of reference.

RAB$C_RFA
Indicates random access by record file address; used for all disk file
organizations.

7.16

RAB$L_RBF Field
When a program invokes a service that writes records to a file, the output
record buffer address (RBF) field contains the symbolic address of the buffer
that holds the record to be written .

•

When you invoke the Get or Read service, VMS RMS sets this field to the
address of the record just read from the file; you need not initialize this field.

7-8

Record Access Block (RAB)
7.17 RAB$W_RFA Field

7.17

RAB$W_RFA Field
The record file address (RFA) field comprises three words that define the
physical disk address (not symbolic address) of the current record.
After the successful execution of a Get, Put, or Find service, VMS RMS sets
the RAB$W_RFA field to the address of the record acted on by the operation.
This address provides an unambiguous means of directly locating this same
record at some later time but is meaningful for disk files only.
You can store the contents of the RAB$W_RFA field for future use. When
you want to retrieve the record again, merely restore the saved contents of
the field, set the record access mode to random by RF A, and invoke a Get or
Find service.
The following rules apply to RFA access:
1

There are two additional names for portions of this field: RAB$L_RFAO
is the offset of the first of three words; RAB$W_RFA4 is the offset of the
last word.
Using VAX MACRO, the field may be copied:
MOVAL
MOVL
MOVW

7.18

RABBLK,RO
RAB$L_RFAO(RO),SAVE_RFA
RAB$W_RFA4(RO),SAVE_RFA+4

RFA values remain valid for a record in a sequential file as long as the
record is within the space defined by the logical file; that is, until the file
is truncated to a point before the record.

RFA values remain valid for a record in a relative file for the life of the
file; that is, until the file is reorganized, using the VMS Convert Utility, or
deleted.

With an indexed file, RFA values remain valid until the file is reorganized,
using the VMS Convert Utility, or deleted. Note that the VMS Convert
/Reclaim Utility partially reorganizes a file while maintaining RFA values.

RAB$L_RHB Field
The fixed-length record header buffer (RHB) field contains the symbolic
address of the record header buffer, which VMS RMS uses only when
processing VFC records.
For a Get service, VMS RMS strips the fixed control area portion of the record
and places it in the buffer whose address is specified in this field. For Put or
Update services, VMS RMS writes the contents of the specified buffer to the
file as the fixed control area portion of the record.
If this field is not specified, VMS RMS assumes the absence of a record
header buffer. When no record header buffer exists, the fixed control area is
discarded for a Get service, zeroed for a Put service, and left unchanged for
an Update service.

The size of the fixed control area is defined in the FAB, using the FAB$B_FSZ
field. You must ensure that the buffer size described in the RAB$L_RHB field
is equal to the value specified by the FAB$B_FSZ field.

7-9

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

7.19

RAB$L_RQP Field
RAB$L_ROP is the symbolic offset for the RAB's record-processing options
(ROP) field. This field specifies which of the various optional record
operations are to be implemented for the program.
The ROP is a 32-bit field in which each record-processing option has a
corresponding bit assignment to let you specify multiple options (multiple
bits can be set), when applicable. Each option has a unique symbolic offset
and a unique mask value but you need only specify the appropriate 3-letter
mnemonic when coding a function. For example, the end-of-file option is
assigned symbolic offset RAB$V_EOF, but to specify the option, you use the
following MACRO statement:
ROP=EOF

The record-processing option bits are never affected by VMS RMS services.
This section describes the record-processing options alphabetically by
functional category, of which there are seven:

•
•
•
•
•
•
•

Connect service input options
Indexed file options
Miscellaneous options
Performance options
Put service options
Record locking options
Terminal device options

This field corresponds to the FDL primary attribute CONNECT.
Table 7-2 lists the options alphabetically by category.
Table 7-2

Record Processing Options

Option

Symbolic Offset

Connect Service Options
Block 1/0

RAB$V_BIO

End of file

RAB$V_EOF

Read ahead

RAB$V_RAH

Synchronous status

RAB$V_SYSCSTS

Write behind

RAB$V_WBH

Indexed File Options

7-10

Key greater than or equal

RAB$V_EQNXT (or RAB$V_KGE)

Limit

RAB$V_LIM

Load

RAB$V_LOA

Key greater than

RAB$V_NXT or (RAB$V_KGT)

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

Table 7-2 (Cont.)

Record Processing Options

Option

Symbolic Offset

Miscellaneous Option
Timeout

RAB$V_TMO

Performance Options
Asynchronous

RAB$V_ASY

Fast delete

RAB$V_FDL

Locate mode

RAB$V_LOC

Read ahead

RAB$V_RAH

Write behind

RAB$V_WBH

Put Service Options
Truncate on put

RAB$V_TPT

Update-if

RAB$V_UIF

Record Locking Options
Do not lock

RAB$V_NLK

Nonexistent record

RAB$V_NXR

Lock for read

RAB$V_REA

Lock for write

RAB$V_RLK

Ignore read lock

RAB$V_RRL

Timeout

RAB$V_TMO

Manual unlock

RAB$V_ULK

Wait to lock

RAB$V_WAT

Terminal Device Options
Cancel CTRL/O

RAB$V_CCO

Convert

RAB$V_CVT

Extended operation

RAB$V_ETO

Prompt

RAB$V_PMT

Purge type-ahead

RAB$V_PTA

Read, no echo

RAB$V_RNE

Read, no filter

RAB$V_RNF

Timeout

RAB$V_TMO

In the following text, each of the options is described under its symbolic
offset. For example, the asynchronous option is described under RAB$V_
ASY.

7-11

Record Access Block (RAB)
7.19 RAB$L_RQP Field

Connect Service Options
RAB$V_BIO
Block 1/0; specifies that only block 1/0 operations are to occur, when mixed
record 1/0 and block 1/0 operations are allowed. This option is meaningful
only if the FAB$B_FAC FAB$V_BRO option was specified when the file was
opened (by a Create or Open service). When the RAB$V_BIO option is set
for the Connect service, only block 1/0 operations are allowed for this record
stream. When the RAB$V_BIO option is clear for the Connect service, only
record 1/0 operations are allowed when accessing a relative or indexed file
and mixed (block 1/0 and record 1/0) operations are allowed for sequential
files. This option corresponds to the FDL attribute CONNECT BLOCK_IO.
RAB$V_EOF
End-of-file; indicates that VMS RMS is to position the record stream to the
end of the file for the connect record operation only.

This option corresponds to the FDL attribute CONNECT END_OF_FILE.
RAB$V_RAH, RAB$V_WBH
Read ahead and write behind; see explanation under "Performance Options".

Note that the first three indexed file options have limited application with
relative files. See the Guide to VMS File Applications for details.
The indexed file options may be enabled or disabled during any record
operation.
As shown in the following chart, synonyms have been defined for the two
key search options, RAB$V_KGT and RAB$V_KGE, to reflect the functional
capability for processing records in ascending or descending order. DIGITAL
recommends you use these synonyms when coding new applications.
Search Option

Synonym

Definition

RAB$V_KGE

RAB$V_EQNXT

Return the record with an equal key
value, or the next key value according
to the sort order for the current key of
reference.

RAB$V_KGT

RAB$V_NXT

Return the record with the next key
value according to the sort order for the
current key of reference.

Indexed File Options
RAB$V_EQNXT
The symbolic offset RAB$V_EQNXT is logically synonymous with the
symbolic offset RAB$V_KGE. When you select this option and ascending
sort order is specified, VMS RMS returns the next record having a key value
equal to or greater than the value specified by the RAB$L _KBF and RAB$B_
KSZ fields. If descending sort order is specified, VMS RMS returns the next
record that contains a key value equal to or less than the value specified by
the RAB$L_KBF and RAB$B_KSZ fields.

7-12

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

Note: Sort order is established in the data type field (symbolic offset XAB$B_
DTP) of the associated XABKEY when the file is created.
If the program specifies a RAB$V_EQNXT search and no record has a key
value identical to the specified search value, VMS RMS returns the record
with the next key value according to the specified sort order. (See the
description of the RAB$V_NXT bit.)
If the program specifies a RAB$V_EQNXT search and a record with a key
value identical to the search key is found, VMS RMS returns the record
regardless of sort order.

For example, consider an ascending-key indexed file having three records, A,
B, and C, where the key for each record is the record itself. When the file is
processed sequentially, the records are encountered in the following order:
A

If the program does a RAB$V_EQNXT search specifying the B key value,
VMS RMS returns record B.
If this file is reorganized as descending-key indexed file and it is processed
sequentially, the records are encountered in the following order:

Again, when the program does a RAB$V_EQNXT search specifying the B key
value, VMS RMS returns record B.
If neither a RAB$V_EQNXT search nor a RAB$V_NXT search (logically
synonymous with RAB$V_KGT) is specified, an exact key match is required
unless a generic key match is specified. (See the description of the RAB$B_
KSZ bit.)

This option corresponds to the FDL CONNECT attribute KEY_GREATER_
EQUAL.
RAB$V_KGE
This option is logically synonymous with the RAB$V_EQNXT option and is
described under RAB$V_EQNXT.
RAB$V_KGT
This bit is logically synonymous with the RAB$V_NXT option and is
described under RAB$V_NXT.
RAB$V_LIM
This option is supported for indexed files only. It permits you to use VMS
RMS as a limit sensor when accessing a file sequentially. When the RAB$V_
LIM bit is set, the key value defined by the RAB$L_KBF and RAB$B_KSZ
fields (limit key value) is compared to the key value in each record as it is
accessed. When a record is accessed that has a key value different from the
limit key value, VMS RMS returns the RMS$_0K_LIM success status code.

This option corresponds to the FDL attribute CONNECT KEY_LIMIT.
RAB$V_LQA
This option is supported for indexed files only. It specifies that VMS RMS is
to load buckets according to the fill size established when the file is created.
The bucket fill size is established in the XAB$W_DFL and XAB$W_IFL fields

7-13

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

of the key definition XAB. If LOA is not specified, VMS RMS ignores the
established bucket fill size; that is, buckets are completely filled.
This option corresponds to the FDL attribute CONNECT FILL _BUCKETS.
RAB$V_NXT
The symbolic offset (RAB$V_NXT) is logically synonymous with the symbolic
offset RAB$V_KGT. When the bit is set and ascending sort order is specified,
VMS RMS returns the next record having a key value greater than the value
specified by the RAB$L_KBF and RAB$B_KSZ fields. If descending sort
order is specified, VMS RMS returns the next record having a key value
less than the value specified by the RAB$L_KBF and RAB$B_KSZ fields.
If neither RAB$V_KGT nor RAB$V_EQNXT (logically synonymous with
RAB$V_KGE) is specified, an exact key match is required.

Note: Sort order is established in the data type XAB$B_DTP field of the
associated XABKEY when the file is created.
The key searching usually produces different results depending on the
specified sort order. For example, consider an ascending-key indexed file
having three records, A, B, and C, where the key for each record is the record
itself. When the file is processed sequentially, VMS RMS returns the records
in the following order:
A

If the program does a RAB$V_KGT search specifying the B key value, VMS
RMS returns record C.
If this file is reorganized as descending-key indexed file and is processed
sequentially, the records are returned in the following order:

Now when the program does a RAB$V_KGT search specifying the B key
value, VMS RMS returns record A.
This option corresponds to the FDL CONNECT attribute KEY_GREATER_
THAN.
Miscellaneous Options

RAB$V_TMO
Timeout; in addition to its use for terminals and preventing delays due
to record locks (described later), the RAB$V_TMO option serves a special
purpose for mailbox devices. If specified in combination with a timeout value
of 0 (RAB$B_TMO), Get and Put services to mailbox devices use the 10$M_
NOW modifier. Doing so causes the operation to complete immediately,
instead of synchronizing with another cooperating writer or reader of the
mailbox.

This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE
and is not supported for DECnet operations.
See the VMS 1/0 User's Reference Volume for a further discussion of
mailboxes.

7-14

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

Performance Options
RAB$V_ASY
Asynchronous; indicates that this I/O operation is to be performed
asynchronously. When you specify RAB$V_ASY, you pass the address of
the RAB as an argument to the AST routine. VMS RMS returns control to
your program as soon as an I/O operation is initiated, even though that
operation may not yet be completed. This option is normally used with
a Wait service to synchronize with operation completion; it is ignored for
process-permanent files.

The RAB$V_ASY option corresponds to the FDL attribute CONNECT
ASYNCHRONOUS.
RAB$V_FDL
Fast delete; this option reduces the time required to delete records in indexed
files. The saving in time is achieved by temporarily avoiding the processing
needed to eliminate pointers from alternative indexes to the record. However,
there is a cost associated with this option. First, the structural linkage from
the alternate indexes remains in place but has no utility; therefore, a certain
amount of space is wasted. Second, if the program tries to access the deleted
record from an alternate index, VMS RMS traverses the linkage, finds the
record no longer exists and then generates a "nonexistent record" error
message which the program must process.

You should take the fast delete option only if the immediate saving in time is
of greater benefit to you than the associated costs in space and overhead.
This option corresponds to the FDL attribute CONNECT FAST_DELETE.
RAB$V_LQC

Locate mode; under specified conditions, you have the option of specifying
locate mode instead of move mode, the default method of buffer handling.
In locate mode, your program accesses records directly in an I/O buffer.
Thus, VMS RMS does not have to move records between I/O buffers and an
application program buffer. The RAB$V_LOC option activates locate mode.
VMS RMS supports this option for the Get service only. The conditions that
may prohibit the use of the locate mode option are given in the following list:
•

Record crosses block boundaries.

•

The FAB$B_FAC field FAB$V_UPD option is set.

•

There are multiple record streams.

•

Process-permanent files are accessed indirectly.

•

Records are compressed in indexed Prolog 3 files.

In move mode, VMS RMS transfers individual records between I/O buffers
and your program buffer. When you invoke a Get service, VMS RMS reads
a block or set of blocks (for sequential files) or a bucket (for relative and
indexed files) into an I/O buffer. VMS RMS then selects the desired record
from the buffer and moves it into the program-specified location. Locate
mode eliminates the last step.
This option corresponds to the FDL attribute CONNECT LOCATE_MODE
and it is not supported for DECnet operations; move mode is always used.

7-15

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

RAB$V_RAH
Read-ahead; used with multiple buffers (see RAB$B_MBF) to indicate readahead operations. VMS RMS issues I/O requests as soon as possible when
a buffer is needed. When the first buffer is filled, the I/O operation takes
place for the first buffer as the second buffer receives the next record; the
second buffer soon becomes filled and the next record is read into the first
buffer as the I/O operation for the second buffer occurs. The system does
not have to wait for I/O completion, which permits an overlapping of input
and computing. Read-ahead is ignored for unit record device I/O and is
supported only for the nonshared sequential file organization. If the RAB$V_
RAH option is specified when the multibuffer count (RAB$B_MBF) is 0,
two buffers are allocated to allow multibuffering. If two or more buffers are
specified, multibuffering is allowed regardless of what was specified to the
Connect service. Conversely, if a buffer count of 1 is specified, multibuffering
is disabled regardless of what was specified to the Connect service.

This option corresponds to the FDL attribute CONNECT READ_AHEAD and
it is not supported for DECnet operations.
RAB$V_SYNCSTS
When you select this option, VMS RMS returns the success status RMS$_
SYNCH if the requested service completes its task immediately. The most
common reason for not completing a task immediately is that the task
involves I/O operations.

The status RMS$_SYNCH is returned in RO only. Refer to the RAB$L_STS
field for the actual success status or failure status of the task.
The RAB$V_SYNCSTS option should be used in conjunction with the
RAB$V_ASY option.
RAB$V_WBH
Write-behind; used with multiple buffers (see RAB$B_MBF). When one
buffer is filled, the next record is written into the next buffer while the
IjO operation takes place for the first buffer. The system does not have
to wait for I/O completion, which allows for an overlapping of computing
and output. Write-behind is ignored for unit record devices. This option
is implemented only for the nonshared sequential file organization. If the
RAB$V_WBH option is specified when the multibuffer count (RAB$B_MBF)
is 0, two buffers are allocated to allow multibuffering. If two or more buffers
are specified, multibuffering is allowed regardless of what was specified to the
Conned service. Conversely, if a buffer count of 1 is specified, multibuffering
is disabled regardless of what was specified to the Connect service.

This option corresponds to the FDL attribute CONNECT WRITE_BEHIND
and it is not supported for DECnet operations.
Put Service Options
RAB$V_TPT
Truncate-on-put; specifies that a Put or Write service using sequential record
access mode can occur at any point in the file, truncating the file at that point.
The end-of-file mark is set to the position immediately following the last byte
written.

7-16

Record Access Block (RAB}
7 .19 RAB$L_RQP Field

Truncating a file deletes all records beyond the point of truncation. In a
shared environment, the application must ensure proper interpretation of a
truncate operation. The process must have specified truncate access by setting
the FAB$V_TRN option in the FAB$B_FAC field when the file was opened or
created.
This option applies only to sequential files and corresponds to the FDL
attribute CONNECT TRUNCATE_ON_PUT.
RAB$V_UIF
Update-if; indicates that if a Put service is invoked for a record that already
exists in the file, the operation is converted to an Update. This option is
necessary to overwrite (as opposed to update) an existing record in relative
and indexed files. Indexed files using this option must not allow duplicates
on the primary key. The process must have specified Update access by setting
the FAB$V_UPD option in the FAB$B_FAC field when the file was opened or
created.

When using this option with shared files and automatic record locking, you
should be aware that the Put service, unlike the Update service, briefly
releases record locks until it is determined that an Update should take
place. At that point, the record is relocked for the Update operation. Note
that during the time the Put operation is being converted into an Update
operation, it is possible that another record stream could update or delete the
record.
This option corresponds to the FDL attribute CONNECT UPDATE_IF.
The record-processing options related to controlling record locking are
described below. Except as noted, these options apply to all file organizations
and may be selected for each operation.
Record Locking Options
RAB$V_NLK
Do not lock record; specifies that the record accessed through a Get or Find
service is not to be locked. The RAB$V_NLK option takes precedence over
the RAB$V_ULK option.

This option corresponds to the FDL attribute CONNECT NOLOCK.
RAB$V_NXR
Nonexistent record processing; specifies that if the record directly accessed
through a Get or Find service does not exist (was never inserted into the file
or was deleted), the service is to be performed anyway. For a Get service,
the previous contents of a deleted record are returned. The processing of a
deleted record returns a completion status code of RMS$_0K_DEL, and the
processing of a record that never existed returns RMS$_0K_RNF.

This option applies only to relative files and it corresponds to the FDL
attribute CONNECT NONEXISTENT_RECORD.
RAB$V_REA
Lock record for read; specifies that the record is to be locked for a read
operation for this process, while allowing other accessors to read the record
(but not to modify the record). Use this option only when you do not want
the file to be modified by any subsequent activities. Use the RAB$V_RLK
option to allow possible subsequent modification of the file.

This option corresponds to the FDL attribute CONNECT LOCK_ON _READ.

7-17

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

RAB$V_RLK
Lock record for write; specifies that a user who locks a record for modification
is allowing the locked record to be read by other accessors. If both RAB$V_
RLK and RAB$V_REA option are specified, the RAB$V_REA option is
ignored. The RAB$V_NLK option takes precedence over all others.

This option corresponds to the FDL attribute CONNECT LOCK_ON _
WRITE.
RAB$V_RRL
Read regardless of lock; read the record even if another stream has locked the
record. This option allows the reader some control over access. If a record
is locked against all access and this bit is set for either a Put or Get service
request, the record is returned with alternate status RMS$_0K_RRL.

This option corresponds to the FDL attribute CONNECT READ_
REGARDLESS.
RAB$V_TMO
Timeout; specifies that if the RAB$V_WAT option was specified, the RAB$B_
TMO field contains the maximum time value, in seconds, to be allowed for
a record input wait caused by a locked record. If the timeout period expires
and the record is still locked, VMS RMS aborts the record operation with the
RMS$_TMO completion status. Note that the maximum time allowed for a
timeout is 255 seconds. Other functions of the RAB$V_TMO option are listed
under "Miscellaneous Options."

This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE
and it is not supported for DECnet operations.
RAB$V_ULK
Manual unlocking; prohibits VMS RMS from automatically unlocking records.
Instead, once locked (through a Get, Find, or Put service), a record must be
specifically unlocked by a Free or Release service. The RAB$V_NLK option
(above) takes precedence over the RAB$V_ULK option.

This option corresponds to the FDL attribute CONNECT MANUAL_
UNLOCKING.
RAB$V_WAT
Wait; if the record is currently locked by another stream, wait until it is
available. This option may be used with the RAB$V_TMO option (see above)
to limit waiting periods to a specified time interval.

This option corresponds to ~he FDL attribute CONNECT WAIT_FOR_
RECORD.
The record-processing options related to terminal devices are described
below. These options map directly into equivalent modifiers to the QIO
function code. For a further discussion of their effects, see the VMS 1/0
User's Reference Volume. These options can be selected for each operation.

7-18

Record Access Block (RAB)
7 .19 RAB$L_RQP Field

Terminal Device Options
RAB$V_cco
Cancel CTRL/O; guarantees that terminal output is not discarded if the
operator presses CTRL/O.

This option corresponds to the FDL attribute CONNECT TT_CANCEL_
CONTROL _O and it is not supported for DECnet operations.
RAB$V_CVT
Convert; changes characters to uppercase on a read from a terminal.

This option corresponds to the FOL attribute CONNECT TT_UPCASE_
INPUT and it is not supported for DECnet operations.
RAB$V_ETO
Extended terminal operation; indicates presence of a Terminal XAB (XABTRM)
to describe terminal input using extended terminal characteristics. Note that
if this option is specified, all other RAB$L_ROP options specific to terminal
devices are ignored (including the RAB$V_TMO option).

This option is not supported for DECnet operations.
RAB$V_PMT
Prompt option; indicates that the contents of the prompt buffer are to be used
as a prompt for reading data from a terminal (see RAB$L_PBF field).

This option corresponds to the FOL attribute CONNECT TT_PROMPT and it
is not supported for DECnet operations.
RAB$V_PTA
Purge type-ahead; eliminates any information that may be in the type-ahead
buffer on a read from a terminal.

This option corresponds to the FOL attribute CONNECT TT_PURGE_TYPE_
AHEAD and it is not supported for DECnet operations.
RAB$V_RNE
Read no echo; indicates that input data is not echoed (displayed) on the
terminal as it is entered on the keyboard.

This option corresponds to the FOL attribute CONNECT TT_READ_
NOECHO and it is not supported for DECnet operations.
RAB$V_RNF
Read no filter; indicates that CTRL/U, CTRL/R, and DELETE are not to be
considered control commands on terminal input but are to be passed to the
application program.

This option corresponds to the FOL attribute CONNECT TT_READ_
NO FILTER and it is not supported for DECnet operations.
RAB$V_TMO
Timeout; for terminal operations, indicates that the content of the RAB$B_
TMO field is to be used to determine the number of seconds allowed between
characters received during terminal input. If the timeout period expires,
VMS RMS returns an error status (see RAB$B_TMO). Other functions of the
RAB$V_TMO option are listed under "Miscellaneous Options" and "Record
Locking Options".

7-19

Record Access Block (RAB)
7.19 RAB$L_RQP Field

This option corresponds to the FOL attribute CONNECT TIMEOUT_ENABLE
and is not supported for DECnet operations.

7.20

RAB$W_RSZ Field
The record size (RSZ) field contains the size, in bytes, of the record. For a
Write service, the range is 1 through 65,535. For a Put or Update service, the
range is 0 to the maximum value shown in Table 5-4. This field controls the
size· of a record that a Put or Update service can write, or the number of bytes
that a Write (block 1/0) service can write. This field is required for an Update
service only if the file contains variable-length records or VFC records.
On input from a file, VMS RMS sets this field to indicate the length, in bytes,
of the record that a Get service transfers or that a Read service (block 1/0)
reads.
Three notes apply to this field:

7.21

After a Get service, VMS RMS places the record size in the RAB$W_RSZ
field. On a Read service, VMS RMS sets the RAB$W_RSZ field to the
number of bytes actually transferred.

For variable with fixed-length control records, VMS RMS does not include
the size of the fixed control area in the RAB$W_RSZ field.

For block 1/0 operations, some devices require that an even number of
bytes be transferred.

RAB$L_STS Field
The completion status code (STS) field is set by VMS RMS with the success
or failure status codes for a record operation before returning control to your
program. For an asynchronous operation that has been initiated but not
yet completed, this field is 0. When the operation is complete, the field is
updated with the completion status. See Part I for additional details about
signaling VMS RMS status codes. Potential error codes for specific operations
are listed with their descriptions in Part III.

7.22

RAB$L_STV Field
The completion status value (STV) field communicates additional completion
information to your program, on the basis of the type of operation and the
contents of the completion status code field. For additional information on
the RAB$L _STS and RAB$L _STV fields, see Part I.
The RAB$L _STV field can be accessed using alternate symbolic offsets;
RAB$W_STVO is the location of the first word and RAB$W_STV2 is the
location of the second word within RAB$L_STV.

7-20

Record Access Block (RAB)
7.23 RAB$B_TMO Field

7.23

RAB$B_TMO Field
The timeout (TMO) field indicates the maximum number of seconds, in the
range 0 to 255, that VMS RMS should wait for an operation to conclude. If
the operation does not conclude within the specified timeout period, VMS
RMS returns an error status code.
To use this field, you must also specify the RAB$V_TMO record-processing
option.
For a Get service using a terminal device, this value specifies the number
of seconds to wait between the characters being typed. If you specify 0
along with RAB$V_TMO, the current contents of the type-ahead buffer are
returned.
When you use a wait-on-record lock (RAB$V_WAT) with a Get, Find, or Put
service, this value specifies the maximum number of seconds for VMS RMS
to wait for the record to become available.
Note that if the RAB$B_TMO field contains a value of 0 and RAB$V_TMO
is set when you invoke either a Get or Put service to a mailbox device, the
operation terminates immediately, rather than waiting for another process.
For example, if you invoke the Put service to a mailbox device with the
RAB$B_TMO field clear, the Put service does not wait for the receiving
process to get the record.
This field corresponds to the FDL attribute CONNECT TIMEOUT_PERIOD
and it is not supported for DECnet operations.

7.24

RAB$L_UBF Field
The user record buffer address (UBF) field indicates the location of a record or
block buffer.

Note: When you invoke the GET service, RMS takes control of the record buffer
and may modify it. RMS returns the record size and only guarantees the
contents from where it accessed the record to the completion of the record.
This field contains the symbolic address of a work area (buffer) within your
program. The size of this buffer must be defined in the RAB$W_USZ (user
record area size) field.
When you invoke a Get service, this field must contain the buffer address,
regardless of the record transfer mode (locate or move). This option also
applies when you invoke the Read service for block I/O. However, a Put or
Write service never needs a user buffer.

7.25

RAB$W_USZ Field
The user record buffer size (USZ) field indicates the length, in bytes, of the
user record or block buffer. This field contains a numeric value representing
the size of the buffer, in the range of 1 through 65,535.
The user record buffer should be large enough to contain the largest record in
the file. If the buffer is not large enough on an operation with a Get service,
VAX RMS moves as much of the record as possible into the buffer and returns
a warning status code.

7-21

Record Access Block (RAB)
7 .25 RAB$W_usz Field

The value in this field specifies the transfer length, in bytes, for block 1/0
operations with a Read service and for a Get service to UDF (undefined)
format sequential files.

7.26

RAB$L->CAB Field
The extended attribute block address (XAB) field contains the symbolic
address of an XAB control block that you want to use when performing
an operation such as a Get service for a terminal device. A value of 0 (the
default) indicates no XABs for this record stream.
For certain record operations, you can associate XABs with a RAB to convey
additional attributes about an operation. (See Part I for the description of an
XAB.)

7-22

Allocation Control XAB (XABALL)

The allocation control XAB (XABALL) provides additional control over file or
area space allocation on disk devices in order to optimize performance. In the
following descriptions, the terms file and area are synonymous for sequential
and relative files because these file organizations are limited to a single area
(Area 0).

8.1

Summary of Fields
When VMS RMS uses a XAB to create or extend an area, the following
XABALL fields duplicate and take precedence over associated fields in the
related FAB:
•

Allocation quantity (ALQ) field, XAB$L_A.LQ, overrides FAB$L_A.LQ

•

Bucket size (BKZ) field, XAB$B_BKZ, overrides FAB$B_BKS

•

Default extension quantity (DEQ) field, XAB$W_DEQ, overrides FAB$W_
DEQ

•

The XAB$V_CBT and XAB$V_CTG options of the allocation options field,
XAB$B_A.OP, override the FAB$V_CBT and FAB$V_CTG options of the
file-processing options field, FAB$L_FOP

When opening a file or displaying a file's attributes, VMS RMS outputs
appropriate information to your program using these fields.
The symbolic offset, size, FDL equivalent, and a brief description of each
XABALL field are presented in Table 8-1.
Table 8-1

XABALL Fields

Field Offset

Size
(Bytes)

Description

FOL Equivalent

Area identification number

AREA n

XAB$B_AID
XAB$B_ALN
XAB$L_ALQ

AREA POSITION
4

AREA ALLOCATION
1

XAB$B_AOP

AREA

XAB$B_BKZ

AREA BUCKET_SIZE

XAB$B_BLN

Alignment boundary type
Allocation quantity
Allocation options
Bucket size

None

Block length

XAB$B_COD 2

None

Type code

XAB$W_DEQ

AREA EXTENSION

Default extension quantity

XAB$L_LOC

AREA POSITION

Location

XAB$L_NXT

None

Next XAB address

1 This field contains options; corresponding FOL equivalents are listed in the description of the field.
2 This field

is statically initialized by the $XABALL macro to identify this control block as a XABALL.

8-1

Allocation Control XAB (XABALL)
8.1 Summary of Fields

Table 8-1 (Cont.)

XABALL Fields

Field Offset

Size
(Bytes)

XAB$W_RFI
XAB$W_VOL

FOL Equivalent

Description

AREA POSITION FILE_ID
or FILE_NAME

Related file identifier

AREA VOLUME

Related volume number

Each XABALL field is described below. Unless indicated otherwise, each field
is supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file access to
other systems, see the VMS Networking Manual.
The format and arguments of the $XABALL macro and the $XABALL_
STORE macro are described in Appendix B.

8.2

XAB$B_AID Fields
VMS RMS uses the area identification number (AID) field to determine which
area within a file is supported by this XAB. Note that sequential and relative
files are limited to area 0.
The area is identified by a numeric value in the range 0 through 254 (default
is 0) and is most appropriate for use with index files having multiple areas
allocated.
This field corresponds to the FDL attribute AREA n where n indicates the area
number.

8.3

XAB$B_ALN Field
The alignment boundary type (ALN) field gives you several options for
aligning the allocated area. VMS RMS uses this field in conjunction with
the XAB$L_LOC field and with the XAB$W_RFI field to provide precise
positioning control of the area or area extension.
The XAB$B_ALN field is a keyword value field in which an alignment
boundary option is defined by a symbolic constant value. For example, the
cylinder boundary option has a symbolic constant value of XAB$C_CYL.
Note that if no value is defined for this field, VMS RMS assumes the
XAB$C_ANY option (no additional positioning control desired). Additional
positioning control is not supported for DECnet operations.
The XAB$B_ALN field corresponds to the FDL attribute AREA POSITION.
The following list describes the options for the XAB$B_ALN field:

Options
XAB$C_ANY
Any allocation; specifies that no positioning control over the area is desired. If
this option is selected, the XAB$L_LOC and XAB$W_RFI fields are ignored.
This option corresponds to the FDL attribute AREA POSITION NONE.

8-2

Allocation Control XAB (XABALL)
8.3 XAB$B_ALN Field

XAB$C_CYL
Specifies that the area boundary begin at the cylinder number identified by
the location field XAB$L_LOC.
This option corresponds to the FDL attribute AREA POSITION CYLINDER.

XAB$C_LBN
Specifies that the area boundary begin at the logical block number identified
by the location field XAB$L_LOC.
This option corresponds to the FDL attribute AREA POSITION LOGICAL.

XAB$C_RFI
This option is used only for extending an area. It specifies that the area
extension begin as close as possible to the file identified by the related-fileidentification field (XAB$W_RFI), and that the extent begin with the VBN
specified by the location field XAB$L_LOC.
This option corresponds to the FDL attribute AREA POSITION FILE_ID or
AREA POSITION FILE_NAME. If you try to use this option with DECnet
operations, VMS RMS automatically replaces it with the XAB$C_ANY option.

XAB$C_VBN
This option applies to area extension only. It specifies that the area extension
begin as close as possible to the virtual block number identified by the
location field XAB$L_LOC.
This option corresponds to the FDL attribute AREA POSITION VIRTUAL.

8.4

XAB$L_ALQ Field
This field defines the number of blocks to be initially allocated to an area
when it is created using a Create service, or the number of blocks to be added
to an area when it is explicitly extended using an Extend service (as opposed
to automatic extension). In both cases, this field overrides the allocation
quantity in the associated FAB (see Chapter 5).
The XAB$L_ALQ field accepts numeric values of up to 4,294,967,295 for
initial allocation, but the allocation is limited by the number of blocks
available on the device.
When you create a new area using the Create service, VMS RMS interprets
the value in the XAB$L _ALQ field as the number of blocks for the area's
initial extent. If the value is 0, VMS RMS allocates a minimum number of
blocks depending on the file organization. For example, VMS RMS allocates
only the number of blocks needed for the key and area definitions with
indexed files.
When you use either the Create or Extend services with indexed files, VMS
RMS rounds the allocation quantity value up to the next cluster boundary
and returns this value to the program in the XAB$L_ALQ field. VMS RMS
uses this value as the extension value when you extend an existing area using
the Extend service, unless the program changes the value before invoking the
Extend service. Note that the value 0 is not acceptable for extending an area.

8-3

Allocation Control XAB (XABALL)
8.5 XAB$B_AQP Field

8.5

XAB$B_AOP Field
The allocation options (AOP) field lets you specify a particular type of
allocation.
This field is a binary options field where one or more options may be selected
by setting the appropriate bits. Each option is identified by a symbolic offset
and has a mask value; for example, the CBI option has an offset of XAB$V_
CBI and a mask value of XAB$M_CBT.
The options for the XAB$B_AOP field are summarized in the following list.
Options
XAB$V_CBT
Contiguous best try; indicates that the allocation or extension should use
contiguous blocks, on a "best effort" basis. This option overrides the FAB$L_
FOP field FAB$V_CBT option.

This opt~on corresponds to the FDL attribute AREA BEST_TRY_
CONTIGUOUS.
XAB$V_CTG
Contiguous; indicates that the initial allocation extension must use contiguous
blocks only; the allocation fails if the requested number of contiguous blocks
is not available. If this is the initial allocation and only a single area is
specified, the file is marked contiguous. This option overrides the FAB$L_
FOP field FAB$V_CTG option.

This option corresponds to the FDL attribute AREA CONTIGUOUS.
XAB$V_HRD
Hard; indicates that if the requested alignment cannot be performed, an error
will be returned. By default, the allocation is performed as near as possible to
the requested alignment.

Note that the XAB$V_HRD option is applicable only to XAB$C_CYL and
XAB$C_LBN alignment boundary types, specified by the XAB$B-ALN field.
This option corresponds to the FDL attribute AREA EXACT-POSITIONING.
XAB$V_QNC
On cylinder boundary; indicates that VMS RMS is to begin the allocation on
any available cylinder boundary.

This option corresponds to the FDL attribute AREA POSITION ANY_
CYLINDER.

8-4

Allocation Control XAB (XABALL)
8.6 XAB$B_BKZ Field

8.6

XAB$B_BKZ Field
When VMS RMS creates relative and indexed files, this field specifies bucket
size using numeric values ranging from 0 through 63 to represent the number
of blocks in a bucket. If this argument is omitted, or if a value of 0 is
inserted, VMS RMS uses a default size equal to the minimum number of
blocks required to contain a single record. For RMS-11 processing, the bucket
size must be less than or equal to 32 blocks.
When calculating the bucket size, you must consider the control information
(overhead) associated with each bucket. Note that some record types contain
control bytes and to calculate the overhead you must multiply the number of
records per bucket by the number of control bytes per record. See the Guide
to VMS File Applications for more information.
The FDL editor can be used to calculate efficient bucket sizes for indexed files.
(For information about the FDL editor, see the VMS File Definition Language

Facility Manual.
When you create a file, VMS RMS uses this field as input to determine the
specified bucket size and upon conclusion, uses the field to output the bucket
size. Because relative files are limited to one area, this field specifies the size
for all buckets in the file. For indexed files, you can specify a different size
for each area using this field in the appropriate XABALL.
When you open an existing file, VMS RMS uses this field to output the bucket
size to your program.
The value in this field overrides the contents of the bucket size field of the
FAB on a Create service (see Chapter 5).
You can specify multiple areas for a single index by having the XAB$B_IAN
and XAB$B_LAN fields in the key definition XAB (XABKEY) indicate that the
lowest level of the index and the remainder of that index occupy different
areas (defined by different XABALLs). However, the number of blocks
per bucket (XAB$B_BKZ value) must be the same for the entire index of a
particular key. If multiple areas are specified for an index and if the XAB$B_
BKZ values are not the same, VMS RMS returns an error because the values
for one index must be the same. However, if you specify the XAB$B_BKZ
field for at least one area and use the default ( 0) for the XAB$B_BKZ field
of a different area (or areas) of the same index, VMS RMS uses the largest
XAB$B_BKZ value specified among the XABALL control blocks to determine
the bucket size for that index.
This field corresponds to the FDL attribute AREA BUCKET_SIZE.

8. 7

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABALL, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_ALLEN (this is done by the $XABALL macro).

8-5

Allocation Control XAB (XABALL)
8.8 XAB$B_CQD Field

8.8

XAB$B_CQD Field
The type code (COD) field is a static field that identifies this control block as
a XABALL. Once set, this field must not be altered unless the control block
is no longer needed. This field must be initialized to the symbolic value
XAB$C_ALL (this is done by the $XABALL macro).

8.9

XAB$W_DEQ Field
The default extension quantity (DEQ) field specifies the number (0 to 65,535)
of blocks to be added when VMS RMS automatically extends the area. If you
specify 0, the VMS RMS provides a default extension value.
The value in this field overrides the contents of the default extension quantity
field of the FAB (see Chapter 5).
This field corresponds to the FDL attribute AREA EXTENSION.

8.10

XAB$L_LOC Field
The location (LOC) field contains a numeric value that indicates the beginning
point for area allocation. VMS RMS refers to the location field when
executing a Create or Extend service, but only if the XAB$B_ALN field
specifies an alignment option. The way the XAB$L_LOC field is used
depends on the value specified for the XAB$B_ALN field (a binary options
field). The beginning point for the allocation is determined as follows:
•

If the XAB$B_ALN field XAB$C_CYL option is specified, the location

number is the cylinder number (0 through the maximum cylinder number
on the volume) where the allocation begins.
•

If the XAB$B_ALN field XAB$C_LBN option is specified, the location

number is the logical block number (0 through the maximum number of
blocks on the volume) where the allocation begins.
•

If the XAB$B_ALN field XAB$C_VBN or XAB$C_RFI option is specified,

the location number is the virtual block number (1 through the maximum
number of blocks in the file) where the allocation begins. This applies
only to the Extend service. If the number 0 is specified, or if the number
is omitted during an Extend service, VMS RMS places the file extension
as near to the end of the file as possible.
This field corresponds to the FDL attribute AREA POSITION.

8.11

XAB$L_NXT Field
The next XAB address (NXT) field specifies the symbolic address of the next
XAB in the XAB chain. A value of 0 (the default) indicates that the current
XAB is the last (or only) XAB in the chain.

8-6

Allocation Control XAB (XABALL}
8.12 XAB$W_RFI Field

8.12

XAB$W_RFI Field
The related file identification (RFI) field allows you to position files or areas of
an indexed file close to a specified file.
This field contains the 3-word file identification value of the related file.
A value of 0,0,0 (the default) indicates that the current file is to be used.
Specifying the XAB$B_ALN field XAB$C_RFI option and specifying the
XAB$W_RFI field as 0,0,0 are equivalent to specifying the XAB$B_ALN field
XAB$C_VBN option.
You can view the file identification of a file using the DCL command
DIRECTORY with the /FULL qualifier.
The file is created or extended as near to the specified related file as possible
at the virtual block number specified by the LOC argument.
The XAB$W_RFI field is ignored unless the XAB$B_ALN field is set to
XAB$C_RFI. It is also ignored for DECnet operations.
This field corresponds to the FDL attribute AREA POSITION FILE_ID or
AREA POSITION FILE_NAME.

8.13

XAB$W_VQL Field
The relative volume number (VOL) field indicates the specific member of a
volume set upon which the file is to be allocated.
This field contains an integer in the range 0 through 255. The default is 0,
specifying the "current" member of the volume set.
Note that volume placement will be performed only if an alignment type in
the XAB$B_ALN field is either XAB$C_CYL or XAB$C_LBN (you cannot
specify XAB$C_VBN or XAB$C_RFI alignment types). If the XAB$B_ALN
field contains a value of 0, placement of the file within the volume set will be
at the discretion of the system, regardless of the contents of the XAB$W_VOL
field.
This field corresponds to the FDL attribute AREA VOLUME.

8-7

Date and Time XAB (XABDAT)

The date and time XAB (XABDAT) block provides extended control of the
date and time of the file's creation, revision (update), backup, and expiration.

9.1

Summary of Fields
VMS RMS sets certain values for date and time and returns them in XABDAT
fields for your inspection. You can override these system-supplied values
through the use of an XABDAT as input to a Create service. Note that datetime values are expressed in either absolute (positive) or delta (negative)
format, and several system services are available for date-time conversion
and use (see Example 3-1 in Chapter 3 of this manual and the VMS System

Services Reference Manual).
The symbolic offset, size, FDL equivalent, and a brief description of each
XABDAT field are presented in Table 9-1.
Table 9-1

XABDAT Fields

Field Offset

Size
(Bytes)

FOL Equivalent

Description

XAB$Q_BDT 1

DATE BACKUP

Backup date and time

XAB$B_BLN 2

None

Block length

DA TE CREATION

Creation date and time

None

Type code

XAB$Q_EDT

DA TE EXPIRATION

Expiration date and time

XAB$L_NXT

None

Next XAB address

DA TE REVISION

Revision date and time

FILE REVISION

Revision number

XAB$Q_CDT
XAB$B_COD

XAB$Q_RDT

XAB$W_RVN

1This field cannot be initialized by the $XABDA T macro.

2 This field is statically initialized by the $XABDA T macro to· identify this control block as a

XABDAT.

Table 9-2 describes how the fields of the XABDAT block are used by the
VMS RMS services.

9-1

Date and Time XAB (XABDAT)
9.1 Summary of Fields

Table 9-2

Services and the XABDAT Control Block
XAB$Q_BDT

XAB$Q_CDT

XAB$Q_EDT

Not used

Create

Input

Input 1

Display

Output

Erase

Not used

Service

XAB$Q_RDT,XAB$W_RVN

Extend

Not used

Open

Output

1 The XAB$Q_RDT field for a Create service is superseded by the current date and time on a Close service.

Use the

XABRDT block to specify the XAB$Q_RDT field (see Chapter 15).

The following notes apply to the use of XABDAT fields by VMS RMS services:

If the user specifies the XAB$Q _CDT or XAB$Q _RDT field in the
XABDAT as 0 (either explicitly or by default) and if the specified field is
used as an input field by the service, it is replaced with the current date
and time.

If the Create service is invoked with a FAB that specifies the FAB$L_FOP
field FAB$V_CIF (create-if) option and if the file to be created already
exists, the Create service is processed like an Open service and the fields
listed above are output fields.

Each XABDAT field is described below. Unless indicated otherwise, each field
is supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file access to
other systems, see the VMS Networking Manual.
The format and arguments of the $XABDAT macro and the $XABDAT_
STORE macro are described in Appendix B.

9.2

XAB$Q_BDT Field
The backup date and time (BDT) field contains a 64-bit binary value
expressing the date and time when the file was most recently backed up.
Note that this field is limited to a granularity of 1 second for remote files.
This field corresponds to the FDL attribute DATE BACKUP.

9.3

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABDAT in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_DATLEN (this is done by the $XABDAT macro).

9-2

Date and Time XAB (XABDAT)
9.4 XAB$Q_CDT Field

9.4

XAB$Q_CDT Field
The creation date and time (CDT) field contains a 64-bit binary value
expressing the date and time when the file was created. Note that this
field is limited to a granularity of 1 second for remote files.
This field corresponds to the FDL attribute DATE CREATION.

9.5

XAB$B_COD Field
The type code (COD) field is a static field that identifies this control block
as an XABDAT. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_DAT (this is done by the $XABDAT macro).

9.6

XAB$Q_EDT Field
The expiration date and time (EDT) field contains a 64-bit binary value that
indicates the date and time after which a file residing on a disk device may be
considered for deletion by the system manager. For files residing on magnetic
tape devices, the XAB$Q _EDT field sets the date and time after which you
can overwrite the file. Note that this field is limited to a granularity of 1
second for remote files.
This field corresponds to the FDL attribute DATE EXPIRATION.

9.7

XAB$L_NXT Field
The next XAB address (NXT) field contains the symbolic address of the next
XAB to be used. A value of 0 (the default) indicates that the current XAB is
the last (or only) XAB in the chain.

9.8

XAB$Q_RDT Field
The revision date and time (RDT) field contains a 64-bit binary value
expressing the date and time when the file was last updated. Note that
this field is limited to a granularity of 1 second for remote files.
This field corresponds to the FDL attribute DATE REVISION.

9.9

XAB$W_RVN Field
The revision number (RVN) field contains a numeric value that indicates the
number of times this file was opened for write operations.
This field corresponds to the FDL attribute FILE REVISION.

9-3

1 Q File Header Characteristic XAB (XABFHC}
The file header characteristic XAB (XABFHC) contains information about a file
that is stored in the file header. VMS RMS copies the file characteristics into
this XAB whenever an Open or Display service executes. The XABFHC fields
are then available for you to examine during processing.
Note that for unshared sequential files, or sequential files shared using the
FAB$V_UPI option, the values in the end-of-file block (XAB$L_EBK), first
free byte in the end-of-file block (XAB$W_FFB), and longest record length
(XAB$W_LRL) fields correspond to the values at the time of the last Close or
Flush service.
On a Create service, only the longest record length (XAB$W_LRL) field of this
XAB is used as input, and then only if the record format is not fixed length.
All other fields are used only as output from the VMS RMS services.

10.1

Summary of Fields
The symbolic offset, size, and a brief description of each RAB field are
presented in Table 10-1. Note that many of these fields are also available in
the FAB.
Table 10-1

XABFHC Fields

Field Offset

Size
(bytes)

XAB$B_ATR 1
XAB$B_BKZ

Record attributes; equivalent to FAB$B_RAT

Bucket size; equivalent to FAB$B_BKS

XAB$B_BLN 2
XAB$B_CQD 2
XAB$W_DX0

XAB$L_EBK 1
XAB$W_FFB

Description

Block length

Type code

Default file extension quantity; equivalent to
FAB$W_DEO

End-of-file block

First free byte in the end-of-file block

Default global buffer count

Highest virtual block in the file; equivalent to
FAB$L_ALO

XAB$W_GBC
XAB$L_HBK 1
XAB$B_HSZ 1

XAB$W_LRL 1

Fixed-length control header size; equivalent to
FAB$B_FSZ

Longest record length

1 This field cannot be initialized by the $XABFHC macro.
2 This field

is statically initialized by the $XABFHC macro to identify this control block as a

XABFHC.

10-1

File Header Characteristic XAB (XABFHC)
10.1 Summary of Fields

Table 10-1 (Cont.)

XABFHC Fields
Size
(bytes}

Field Offset
1

Description

Maximum record size; equivalent to FAB$W_
MRS

XAB$L_NXT

Next XAB address

File organization and record format; combines
FAB$B_RFM and FAB$B_ORG

XAB$L_SBN 1

Starting logical block number for the file if it is
contiguous; otherwise this field is 0

XAB$W_
VERLIMIT 1

Version limit for the file

XAB$W_MRZ

XAB$B_RF0

1 This field cannot be initialized by the $XABFHC macro.

Each XABFHC field is described below. There are no FDL equivalents for
the XABFHC fields. Unless indicated otherwise, each field is supported for
DECnet operations using remote files with a VMS system as the remote node.
Note that the words "DECnet operations" in the following descriptions refer
to remote file operations between two VMS systems. See the VMS Networking
Manual for information about the support of VMS RMS options for remote
file access to other systems.
The format and arguments of the $XABFHC macro and the $XABFHC_
STORE macro are described in Appendix B.

10.2

XAB$B_ATR Field
The record attributes (ATR) field indicates the record attributes (special control
information) associated with each record in this file. This field is equivalent
to the FAB$B_RAT field.
This field is a binary options field where each record attribute has a
corresponding bit assignment. Options are identified using mnemonics.
Each option in the field has its own symbolic offset and constant value. For
example, the CR record attribute has the symbolic offset XAB$V_CR and the
mask value XAB$M_CR. The record attribute options are described in the
following list:
Options
XAB$V_BLK
Records do not cross block boundaries in sequential files.
XAB$V_CR
Each record is preceded by a line feed and followed by a carriage return.
XAB$V_FTN
Each record contains a FORTRAN (ASA) carriage return in the first byte.
XAB$V_PRN
Print file format.

10-2

File Header Characteristic XAB (XABFHC)
10.2 XAB$B_ATR Field

For more information about the XAB$B_ATR field, refer to the description of
the FAB$B_RAT field in Chapter 5.

10.3

XAB$B_BKZ Field
The bucket size (BKZ) field specifies the number of blocks in each bucket of
the file. It is equivalent to the FAB$B_BKS (or XAB$B_BKZ) field and is used
only for relative or indexed files.
This field contains a numeric value in the range of 0 to 63.
For more information about the XAB$B_BKZ field, refer to the description of
the FAB$B_BKS field in Chapter 5 and the description of the XAB$B_BKZ
field in Chapter 8.

10.4

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABFHC, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_FHCLEN (this is done by the $XABFHC macro).

10.5

XAB$B_CQD Field
The type code (COD) field is a static field that identifies this control block
as an XABFHC. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_FHC (this is done by the $XABFHC macro).

10.6

XAB$W_DXQ Field
The default file extension quantity (DXQ) field specifies the number of blocks
to be added when a disk file is extended automatically. This automatic
extension occurs whenever your program performs a Put or Write service and
the currently allocated file space is exhausted.
This field is equivalent to the FAB$W_DEQ (or XAB$W_DEQ) field; it
contains a numeric value in the range 0 through 65,535, which is rounded up
to the value of the next cluster boundary.
For more information about the XAB$W_DXQ field, refer to the description of
the FAB$B_DEQ field in Chapter 5 and the description of the XAB$W_DEQ
field in Chapter 8.

10-3

File Header Characteristic XAB (XABFHC)
10. 7 XAB$L_EBK Field

10.7

XAB$L_EBK Field
When you open a file, VMS RMS stores the VBN of the physical block where
the next record will be written in the XAB$L_EBK field. For example, assume
that a file is allocated five physical blocks and that the last record written
to the file is at byte OFF 16 in the file's second physical block. When your
program opens this file, VMS RMS stores the VBN of the second physical
block in XAB$L_EBK and it stores 100 16 in the XAB$W_FFB field.

If the previous block is full when you open the file, VMS RMS stores the
first location ( 000 16 ) of the next block in XAB$W_FFB and the VBN of the
next block in XAB$L _EBK. By way of contrast, in a similar situation RMS-11
stores the last byte ( 200 16 ) of the filled block in the XAB$W_FFB field and
the VBN of the filled block in the XAB$L_EBK field.
The XAB$L_EBK field is meaningful for sequential files only.

10.8

XAB$W_FFB Field
The first free byte in the end-of-file block (FFB) field contains the byte location
in the end-of-file block where the next record will be written. The XAB$W_
FFB field is meaningful for sequential files only.

10.9

XAB$W_GBC Field
The default global buffer count (GBC) field contains the current global buffer
count for this file. For more information about the XAB$W_GBC field, refer
to the description of the FAB$W_GBC field in Chapter 5.
This field is not supported for DECnet operations; it is ignored.

10.10

XAB$L_HBK Field
The highest virtual block (HBK) field contains the virtual block number
currently allocated to this file. It is equivalent to the FAB$L_ALQ field
after a Create, Open, or Display service executes. For sequential files, the
difference between XAB$L_HBK and XAB$L_EBK equals the number of
blocks in the file available for additional records without extending the file.

10.11

XAB$B_HSZ Field
The fixed-length control header size (HSZ) field indicates the length of the
fixed portion for records in the VFC format. It is equivalent to the FAB$B_
FSZ field.
This field contains a numeric value (1 to 255) that indicates, in bytes, the size
of the fixed-length control area. This field is not applicable to indexed files.
For more information about the XAB$B_HSZ field, refer to the description of
the FAB$B_FSZ field in Chapter 5.

10-4

File Header Characteristic XAB (XABFHC)
10.12 XAB$W_LRL Field

10.12

XAB$W_LRL Field
The longest record length (LRL) field contains a numeric value that indicates
the longest record currently in the file, in bytes. This value is meaningful for
sequential files only.

10.13

XAB$W_MRZ Field
The maximum record size (MRZ) field indicates the size of all records in a file
with fixed-length records, the maximum size of variable-length records, the
maximum size of the data area for variable with fixed-length control records,
and the cell size for relative files. It is equivalent to the FAB$W_MRS field.
This field contains a numeric value in the range applicable to the file type and
record format (see Table 5-4), in bytes.
For fixed-length records, the value represents the actual size of each record in
the file.
For variable-length records, the value represents the size of the largest record
that can be written into the file. If the file is not a relative file, a value of 0
is used to suppress record size checking, thus indicating that there is no user
limit on record size.
For variable with fixed-length control records, the value includes only the
data portion; it does not include the size of the fixed control area.
For more information about the XAB$W_MRZ field, refer to the description of
the FAB$W_MRS field in Chapter 5.

10.14

XAB$L_NXT Field
The next XAB address (NXT) field contains the symbolic address of the next
XAB. A value of 0 (the default) indicates that the current XAB is the last (or
only) XAB in the chain.

10.15

XAB$B_RFO Field
The file organization and record format (RFO) field combines the FAB$B_
RFM and FAB$B_ORG fields using an inclusive OR.

10-5

File Header Characteristic XAB (XABFHC)
10.15 XAB$B_RFO Field

Record formats are listed below.
Record Format

Description

FIX

Fixed length

STM

Stream, delimited by FF, VT, LF, or CR LF

STMCR

Stream, delimited by CR

STMLF

Stream, delimited by LF

UDF

Undefined

VAR

Variable length

VFC

Variable length with fixed control area

The file organizations are listed below.
File Organization

Description

IDX

Indexed sequential

REL

Relative

SEO

Sequential

For more information about the XAB$B_RFO field, refer to the description of
the FAB$B_ORG field and the FAB$B_RFM field in Chapter 5.

10.1 6

XAB$L_SBN Field
The starting logical block number (SBN) field contains the starting logical
block number for a contiguous file; if the file is not contiguous, this field
contains 0.

10.17

XAB$W_VERLIMIT Field
The file version limit (VERLIMIT) field contains the version limit for this file.
This value is not available if the file was opened by file ID.
This field is not supported for DECnet operations; it is ignored.

10-6

11 Item List XAB (XABITM)
The item list XAB (XABITM) provides a convenient means for using item list
information to support VMS RMS functions. An item list consists of one or
more entries that can represent either a control function or a sensing function
that can be passed to the application program by way of the VMS RMS
interface.
Within the item list, you may not include a mix of control and sensing
items related to various VMS RMS-supported functions. However, multiple
XABITMs may be used. VMS RMS logically ignores items that are irrelevant
to any particular function while acting on any item that is relevant.
Each entry in the item list addressed by the XABITM is made up of three
longwords and a longword 0 terminates the list. VMS RMS does not validate
the item list. If the item list is invalid, VMS RMS returns a status of RMS$_
XAB in the RAB$L_STS field. Figure 11-1 illustrates the format for each
entry in the item list.
Figure 11-1

Item Descriptor Data Structure

15
item code

0
buffer length

buffer address
return length address
ZK-1705-84

You can locate the item list anywhere within the readable address space for
a process but any buffers required by the related function must be located in
read/write memory.
The format and arguments of the $XABITM macro are defined in Appendix B.
For VMS Version 5.0, the XABITM control block supports enhancements
to network file access functions and enhancements to VMS RMS
performance monitoring functions. Although the benefits derived from
these enhancements are readily apparent, functional details are transparent to
most users.

11-1

Item List XAB (XABITM)
11 .1 Summary of Fields

11.1

Summary of Fields
The symbolic offset, size, and a brief description of each XABITM field are
presented in Table 11-1.
Table 11-1

XABITM Fields

Field Offset

Size
(Bytes)

XAB$B_BLN 1
XAB$B_COD

Description
Block length

Type code

XAB$L _ITEMLIST

Item list address

XAB$B_MODE

Set/ sense control

XAB$L_NXT

Next XAB address

1 This field is statically initialized by the $XABITM macro to identify the control block as an
XABITM.

11 .1 . 1 XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABITM, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_ITMLEN by the $XABITM macro.

11.1 .2 XAB$B_CQD Field
The type code (COD) field is a static field that identifies this control block
as an XABITM. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_ITM by the $XABITM macro.

11 .1 .3 XAB$L_ITEMLIST Field
The item list address (ITEMLIST) field contains the symbolic address of the
item list.

11 .1 .4 XAB$L_MODE Field
The item list mode (MODE) field specifies whether the items in the item list
can be set by the program. It contains either the symbolic value XAB$K_
SETMODE or the symbolic value XAB$K_SENSEMODE (default).

11.1.5 XAB$NXT Field
The next XAB address (NXT) field contains the symbolic address of the next
XAB to be used. A value of 0 (the default) indicates that the current XAB is
the last (or only) XAB in the chain.

11-2

Item List XAB (XABITM)
11.2 Network File Access Items

11.2

Network File Access Items
This section lists and briefly describes the items that support network file
access features.
Network items are effectively ignored for local operations. Although the
application program may include network items in the XAB chain for the
related FAB, VMS RMS does not consider any of the network-specific fields
during local processing. Nor does VMS RMS return remote file contents to
the application program during local file processing.
Table 11-2 lists the entries in the XABITM item list relating to network file
access features together with the buffer size required to store the data and a
brief functional description. Note that although the application program can
sense all of the item values from the VMS RMS interface, it can set only the
following item values:

•
•
•
•
•
•
•
•
•
•
•
Table 11-2

XAB$_NET_BLOCK_COUNT
XAB$_NET_EXTPROT
XAB$_NET_LINK_TIMEOUT
XAB$_NET_LINK_CACHE_ENABLE
XAB$_NET_DATA_CRC_ENABLE
XAB$_UCHAR_CONTIGB
XAB$_UCHAR_ERASE
XAB$_UCHAR_LOCKED
XAB$_UCHAR_NOBACKUP
XAB$_UCHAR_READCHECK
XAB$_UCHAR_WRITECHECK

XABITM Item List

Item

Required
Buffer
Size

XAB$_NET_BUFFER_SIZE

4 bytes

Description
The size of the buffer allocated for DAP messages
between the local and remote node is a negotiated
value that is decided by DAP. This informational item
returns the actual buffer size, in bytes, allocated for
DAP messages. The buffer size is slightly larger than
the limit specified for the records being transferred.

11-3

Item List XAB (XABITM)
11 .2 Network File Access Items

Table 11-2 (Cont.)

XABITM Item List

Item

Required
Buffer
Size

XAB$_NET_BLOCK_CQUNT

4 bytes

Description
This is the value in blocks that the local node wants
to use for buffering messages between itself and the
remote node.
OAP tries to allocate this buffer space at the local
node; however, if the maximum buffer size at the
remote node is smaller, DAP allocates buffer space
based on the smaller value. When the remote system
incorporates VMS/FAL, it allows any size buffer up to
32,767 bytes.
The minimum buffer size for task-to-task network
operations is 4096 bytes.

XAB$_NET_REMOTE_SYSTEM

4 bytes

This informational item returns the identity of the
remote operating system using the symbolic constants
listed in the following chart:

Symbolic Constant

Operating System

XAB$K_RT11

RT-11

XAB$K_RSTS

RSTS/E

XAB$K_RSX 11 S

RSX-11S

XAB$K_RSX 11 M

RSX-11M

XAB$K_RSX 11 D

RSX-110

XAB$K_IAS

IAS

XAB$K_ V AXVMS

VMS

XAB$K_TOPS 10

TOPS-10

XAB$K_TOPS20

TOPS-20

XAB$K_RSX 11 MP

RSX-11 M-PLUS

XAB$K_P_OS

P/OS

XAB$K_ V AXELN

VAXELN

XAB$K_MS_DOS

MS-DOS@

XAB$K_UL TRIX_32

ULTRIX-32

XAB$K_SNA_OS

SNA gateway to IBM®

'.tBiMS-DOS is a trademark of Microsoft Corporation.
®IBM is a registered trademark of International Business Machines, Inc.

11-4

Item List XAB (XABITM)
11 .2 Network File Access Items

Table 11-2 (Cont.)

XABITM Item List

Item
XAB$_NET_REMOTE_FILE_
SYSTEM

XAB$_NET_EXTPROT

Required
Buffer
Size
4 bytes

8 bytes

Description
This informational item returns the identity of the
remote file system using the symbolic constants listed
in the following chart:

Symbolic Constant

File System

XAB$K_RMS 11

RMS-11

XAB$K_RMS20

RMS-20

XAB$K_RMS32

RMS-32

XAB$K_FCS 11

FCS-11

XAB$K_RT 11 FS

RT-11

XAB$K_NQ_FS

No file system present

XAB$K_TOPS20FS

TOPS-20

XAB$K_TOPS 1OFS

TOPS-10

XAB$K_RMS32S

RMS-32 subset (V AXELN)

XAB$K_MS_OOSFS

MS-DOS

XAB$K_UL TRIX32_FS

ULTRIX-32

XAB$K_SNA_FS

SNA gateway to IBM

This item permits the application program to specify
or to sense the extended file protection that is likely
to be mapped to a protection subset supported by the
remote system. The application program implements
extended file protection as part of either a Create or
Close service by specifying the appropriate protection
mask in the related subfield:

Subfield

Protection

XAB$W _SYSTEM_ACC

System access

XAB$W_OWNER_ACC

Owner access

XAB$W _GROUP_ACC

Group access

XAB$W_WORLD_ACC

World access

11-5

Item List XAB (XABITM)
11 .2 Network File Access Items

Table 11-2 (Cont.)

XABITM Item List

Item

Required
Buffer
Size

Description
Each of the protection mask fields provides the
following mask values for further defining access:
Mask Value

Protection Function

XAB$M_RED_ACC

Deny read access

XAB$M_WRT_ACC

Deny write access

XAB$M_EXE_ACC

Deny execute access

XAB$M_OL T_ACC

Deny delete access

XAB$M_APP_ACC

Deny append access

XAB$M_DIR_ACC

Deny directory access

XAB$M_UPD_ACC

Deny update access

XAB$M_CHG_ACC

Deny change protection
access

XAB$M_EXLACC

Deny extend access

Note that not all systems support all of the protection
mask fields.
XAB$_NET_SYSCAP_LOCAL

8 bytes

This informational item permits the applicatin program
to read the network capabilities of the local system by
returning symbolic bit vector values. See Table 11-3
for a description of the network capabilities bit vectors
used by the local and remote systems.

XAB$_NELSYSCAP_REMOTE

8 bytes

This informational item permits the application program
to read the network capabilities of the remote
system by returning symbolic bit vector values. See
Table 11-3 for a description of the network capabilities
bit vectors used by the local and remote systems.

XAB$_NET_DAPVER_LOCAL

5 bytes

This informational item returns the version of OAP on
the local system using five symbolic bytes:

11-6

Symbolic Byte

Version Information

XAB$8_ VER_DAP

OAP protocol version

XAB$B_ VER_ECO

OAP protocol ECO level

XAB$8_ VER_CUS

Customer modification level
of OAP protocol; set to 0 by
DIGITAL

XAB$B_VER_DSV

DIGIT AL software version
(release number)

XAB$8_ VER_CSV

Customer software version
number; set to 0 by
DIGITAL

Item List XAB (XABITM)
11.2 Network File Access Items

Table 11-2 (Cont.)

XABITM Item List

Item

Required
Buffer
Size

Description
The OAP version is 07-01-00-05-00 for VMS
Version 5.0.

XA8$_NET_DAPVER_REMOTE

5 bytes

This informational item returns the version of OAP on
the remote system using five symbolic bytes:

Symbolic Byte

Version Information

XAB$8_ VER_DAP

OAP protocol version

XAB$8_ VER_ECO

OAP protocol ECO level

XAB$8_ VER_CUS

Customer modification level
of OAP protocol; set to 0 by
DIGITAL

XAB$8_ VER_DSV

DIGIT AL software version
(release number)

XAB$B_ VER_CSV

Customer software version
number; set to 0 by
DIGITAL

XAB$_NET_LINK_ TIMEOUT

4 bytes

This item permits the application program to set the
timeout interval for logical link caching. The setting is
passed as the number of seconds used to cache the
logical link. A zero ( 0) setting enables caching until
image rundown. The default interval is 30 seconds.

XA8$_NELDAT A_CRC_ENABLE

4 bytes

This item allows the application program to enable
cyclic redundancy checking at the OAP level. The
symbolic value XAB$K_ENABLE enables CRC checking
at the OAP level (the default state); the symbolic value
XAB$K_DISABLE disables CRC checking at the OAP
level.

XA8$_NET_LINK_CACHE_ENABLE

4 bytes

This item is used to enable or to disable logical link
caching. The symbolic value XAB$K_ENABLE enables
link caching (the default state); the symbolic value
XAB$K_DISABLE disables link caching.

XA8$_UCHAR_BADACL

4 bytes

File's ACL is corrupt.

XA8$_UCHAR_BADBLOCK

4 bytes

File contains bad blocks.

XA8$_UCHAR_CONTIG

4 bytes

File is contiguous.

XA8$_UCHAR_CONTIGB

4 bytes

Keep the file as contiguous as possible.

XAB$_UCHAR_DIRECTORY

4 bytes

File is a directory.

XAB$_UCHAR_ERASE

4 bytes

Erase the file's contents before deleting it.

XA8$_UCHAR_LOCKED

4 bytes

File is deaccess-locked.

XA8$_UCHAR_MARKDEL

4 bytes

File is marked for deletion.

XA8$_UCHAR_NOBACKUP

4 bytes

Do not back up the file.

XAB$_UCHAR_READCHECK

4 bytes

Verify read operations to the file.

XA8$_UCHAR_SPOOL

4 bytes

File is an intermediate spool file.

A8$_UCHAR _ WRITECHECK

4 bytes

Verify write operations to the file.

11-7

Item List XAB (XABITM)
11 .2 Network File Access Items

The system capabilities supported by various DAP implementations are
described using a vector of bits wherein a bit is set if the corresponding
capability is supported. Any attempt to implement a feature at the local
node that is not supported at the remote node is treated as a protocol
error. Table 11-3 describes the bit vectors that VMS RMS uses to return
the networking capabilities for both the local and remote nodes to the calling
program. Capabilities supported by Version 5.0 of VMS are appropriately
footnoted.
Table 11-3

System Networking Capabilities
Capability

Bit Value
XAB$V_CAP_FILALL 1

Allocation of space at file creation
1

Sequential file organization

Relative file organization

XAB$V_CAP_SEQORG
XAB$V_CAP_RELORG

XAB$V_CAP_EXTEND 1
XAB$V_CAP_SEOFIL

Manual file extension

Sequential file access (file transfer mode)

XAB$V_CAP_RANRRN

Random access by relative record number

XAB$V_CAP_RANVBN 1

Random access by virtual block number

XAB$V_CAP_RANKEY

Random access by key value

XAB$V_CAP_RANRFA

Random access by record file address

XAB$V_CAP_IDXORG

Multikeyed indexed file organization

XAB$V_CAP_SWMODE 1

Dynamic switching of access modes

XAB$V_CAP_APPEND 1

Records appended to end of file

XAB$V_CAP_SUBMIT

Command file submission/execution

XAB$V_CAP_MDS

Multiple data streams for each file

XAB$V_CAP_OISPLAY 1
XAB$V_CAP_MSGBLK

Display of file attributes on request

Blocking of OAP messages up to response (less than 256 bytes)

XAB$V_CAP_UNRBLK

Unrestricted blocking of OAP messages

XAB$V_CAP_BIGBLK 1

Blocking of OAP messages up to response (greater than or equal to 256
bytes)

XAB$V_CAP_DAPCRC 1
XAB$V_:_CAP_KEYXAB

OAP message CRC checksum

Key definition XAB message

XAB$V_CAP_ALLX AB 1
XAB$V_CAP_SUMXAB

Allocation XAB message
1

XAB$V_CAP_OIRECTORY

Summary XAB message
1

1 Supported for VMS Version 5.0.

11-8

Directory list operation

Item List XAB (XABITM)
11.2 Network File Access Items

Table 11-3 (Cont.)

System Networking Capabilities

Bit Value

Capability

XAB$V_CAP_ TIMXAB

Date and time XAB message

File protection XAB message

XAB$V_CAP_PROXAB
XAB$V_CAP_FOPSPL

Spool file on Close FOP option

XAB$V_CAP_FOPSCF

Submit command file on Close FOP option

XAB$V_CAP_FOPDL T 1
XAB$V_CAP_SEORAC

Delete file on Close FOP option

Sequential record access

XAB$V_CAP_BITOPT

Bit count option in the FLAGS field

XAB$V_CAP_WARNING

Warning status message and error recovery message exchange

XAB$V_CAP_RENAME 1
XAB$V_CAP_ WILDCARD

File rename operation
1

Wildcard operations (excluding directory)

XAB$V_CAP_GNGOPT

Go/Nogo option in the ACCOPT field

XAB$V_CAP_NAMMSG 1

Name message

XAB$V_CAP_SEGMSG

Segmented OAP messages

XAB$V_CAP_CHGA TTCLS

Changing file attributes on Close using A TT message

XAB$V_CAP_CHGTIMCLS 1

Changing file attributes on Close using TIM message

XAB$V_CAP_CHGPROCLS 1

Changing file attributes on Close using PRO message

XAB$V_CAP_CHGNAMCLS

Changing file attributes on Close using NAM message

XAB$V_CAP_MODATTCRE

Modified attributes returned when file is created

XAB$V_CAP_NAM3PART

Three-part name message format in DISPLAY field of both Access and
Control messages

XAB$V_CAP_CHGATTREN

Changing file attributes on Rename using A TT message

XAB$V_CAP_CHGTIMREN

Changing file attributes on Rename using TIM message

XAB$V_CAP_CHGPROREN
XAB$V_CAP_CTLBLKCNT

XAB$V_CAP_OCTALVER

Changing file attributes on Rename using PRO message
BLKCNT field in Control message
Octal version numbers only in file specifications

1 Supported for VMS Version 5.0.

11.3

VMS RMS Performance Monitoring
This section describes the implementation of VMS RMS performance
monitoring from the VMS RMS interface using a XABITM.
To explicitly obtain VMS RMS performance statistics for a file through the
VMS RMS interface, the application program enables the statistics function
using the XAB$-STAT_ENABLE item. This item may contain either the
symbolic value XAB$K_DISABLE (default) or XAB$K-ENABLE. The XAB$STAT_ENABLE item may be used on $CREATE to initially mark the file
for statistics gathering, or it may be used in $DISPLAY (or implied display)
operations to sense the statistics monitoring state.

11..-.9

Item List XAB (XABITM)
11 .3 VMS RMS Performance Monitoring

You can enable statistics for an existing file from the DCL interface using
the SET FILE command. See the VMS DCL Dictionary for details. For
details about using the Monitor Utility for gathering VMS RMS performance
statistics, see the VMS Monitor Utility Manual.
Example 11-1 illustrates the use of XABITM to enable statistics monitoring:
Example 11-1

Using XABITM to Enable VMS RMS Statistics

ITEMLIST : BLOCK [ITM$S_ITEM+4, BYTE]
INITIAL( REP (ITM$S_ITEM+4) OF (0) )

ITEM_XAB : $XABITM( mode = SETMODE,
itemlist = ITEMLIST ),
ITEM_BUFFER

LONG INITIAL ( XAB$K_ENABLE);

FILE_FAB : $FAB(

XAB = ITEM_XAB,

) ;

ITEMLIST[ITM$W_ITMCOD] = XAB$_STAT_ENABLE;
ITEMLIST[ITM$W_BUFSIZ] = 4;
ITEMLIST[ITM$L_BUFADR] = ITEM_BUFFER;
$CREATE( fab = FILE_FAB ) ;

11-10

1 2 Journaling XAB (XABJNL)
The journaling XAB ($XABJNL) control block supports file journaling
operations. See the VAX RMS Journaling Manual for details.

12-1

. 1 3 Key Definition XAB (XABKEY)
You must provide a key definition XAB (XABKEY) for each key iil an indexed
file in order to define the key's characteristics. Before you create an indexed
file, you must establish the contents of the XABKEY fields for the primary key
and for each alternate key.
When you invoke an Open or Display service for an existing indexed file, you
can use XABKEYs if you want to provide your program with one dr more
of the key definitions specified when the file was created. Alternatively, the
summary XAB (see Chapter 17) provides the number of keys, rtumber of
allocated areas, and the prolog version assigned to the file.

13.1

Summary of Fields
Table 13-1 lists the symbolic offset, size, FDL equivalent, and a brief
description of each XABKEY field.
Table 13-1

XABKEY Fields

Field Offset

Size
(Bytes)

XAB$8_8LN 1
XAB$8_COD

FOL Equivalent

Description

None

Block length

None

Type code

XAB$L_COLNAM

None

Collating sequence name

XAB$L_COLSIZ

None

Collating sequence table size

XAB$L _COL TBL

COLLATING_SEQUENCE

Collating sequence table address

XAB$8_DAN

KEY DATA_AREA

Data bucket area number

XAB$8_DBS 2

None

Data bucket size

XAB$W_DFL

KEY DATA_FILL

XAB$8_DTP

KEY TYPE

Data bucket fill size
Data type of the key

XAB$L_DVB 2

None

First data bucket virtual block number

XAB$8_FLG

KEY 3

Key options flag

KEY INDEX _AREA

Index bucket area number

XAB$B_IAN
2

None

Index bucket size

XAB$W_IFL

KEY INDEX_FILL

Index bucket file size

XAB$L_KNM

KEY NAME

Key name buffer address

XAB$8_LAN

KEY LEVEL 1_INDEX_
AREA

Lowest level of index area munber

XAB$8_LVL 2

None

Level of root bucket

XAB$8_18S

1 This field is statically initialized by the $XABKEY macro to identify this control block as an XABKEY.
2 This field cannot be initialized by the $XABKEY macro.

3 This field contains options; corresponding FDL equivalents are listed in the description of the field.

13-1

Key Definition XAB (XABKEY)
13.1 Summary of Fields

Table 13-1 (Cont.)
Field Offset
XAB$W_MRL
XAB$B_NSG

XABKEY Fields
Size
(Bytes)

FOL Equivalent

Description

None

Minimum record length

None

Number of key segments

XAB$B_NUL

KEY NULL_VALUE

Null key value

XAB$L_NXT

None

Next XAB address

XAB$W_POSn

KEY POSITION and
SEGn_POSITION

Key position, XAB$W_POSO to
XAB$W_POS7

XAB$B_PROLOG

KEY PROLOG

Prolog level

XAB$B_REF 4

KEY n

Key of reference

XAB$L_RVB 2

None

Root bucket virtual block number

XAB$8_SIZn

KEY LENGTH and
SEGn_LENGTH

Key size XAB$B_SIZO to
XAB$B_SIZ7

None

Total key field size

XAB$B_TKS 2

2 This field cannot be initialized by the $XABKEY macro.
4 For BLISS-32, this field is designated XAB$B_KREF.

Each XABKEY field is described below. Unless indicated otherwise, each field
is supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file access to
other systems, see the VMS Networking Manual.
The format and arguments of the $XABKEY macro and the $XABKEY_STORE
macro are defined in Appendix B.

13.2

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABKEY, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. The $XABKEY macro initializes the XAB$B_BLN
field to the symbolic value XAB$C_KEYLEN.

13.3

XAB$B_COD Field
The type code (COD) field is a static field that identifies this control block as
an XABKEY. Once set, this field must not be altered unless the control block
is no longer needed. The $XABKEY macro initializes the XAB$B_COD field
to the symbolic value XAB$C_KEY.

13-2

Key Definition XAB (XABKEY)
13.4 XAB$L_COLNAM Field

13.4

XAB$L_CQLNAM Field
When you invoke the Display service, VMS RMS uses this field to return a
pointer to a memory buffer containing the name of the collating sequence for
this key.
The name buffer is in the form of an ASCII counted string where the first
byte indicates the length of the name and the remaining bytes are the ASCII
representation of the name itself. The maximum length of the buffer is 32
bytes, one byte for the count and 31 bytes for the name.

13.5

XAB$L_CQLSIZ Field
When you invoke the the Display service, VMS RMS returns the size, in
bytes, of the collating sequence used with this key to this field.

13.6

XAB$L_CQLTBL Field
VMS RMS provides you with a way to use alternative (non-ASCII) collating
sequences with indexed file keys. You can define a collating sequence for
each key of reference, yielding, for example, a file sorted in German by one
key, French by another key, and so forth.
This feature is based on the National Character Set Utility, which permits you
to define alternative collating sequences for special characters and to establish
and maintain a library of collating sequences. This eliminates having to
redefine an alternative collating sequence when the application requires it.
See the VMS National Character Set Utility Manual for details.

Note: Key compression and index compression are not permitted with collating
keys.
To access an alternative collating sequence for a key, enter the symbolic
address of the appropriate collating table in the XAB$L _COLTBL field. For
example, you might enter the following:
DST_KEYO:
$XABKEY

COLTBL=FRENCH, - ;symbolic address of French collating table

VMS RMS responds by storing the specified collating table in the initial blocks
of the indexed file immediately following the area descriptors. Collating
tables are typically about one block long.
When you invoke the Display or the Open service, VMS RMS returns the
address of the collating table in this field.
This field corresponds to the FDL attribute COLLATING_SEQUENCE.

13-3

Key Definition XAB (XABKEY}
13. 7 XAB$B_DAN Field

13.7

XAB$B_DAN Field
The data bucket area number (DAN) field contains a numeric value that
identifies the area where the data buckets for this key reside. The number
reflects the value in the XAB$B_AID field of the XABALL for this XAB chain.
The numeric value may range from 0 through 254, but the default is O; that
is, area 0.
When you create a new indexed file or when you use allocation XABs to
define areas (see Chapter 8), you must specify a value for this field to identify
the file area where the data buckets are to reside.
When an XABKEY describes the primary key, the data level of the index
consists of buckets that contain the actual data records of the file. However,
when the key definition describes an alternate key, the data level of the index
consists of buckets in which VMS RMS maintains pointers to the actual data
records.
The XAB$B_DAN field corresponds to the FDL attribute KEY DATA_AREA.

13.8

XAB$B_DBS Field
After an Open or Display service, the data bucket size (DBS) field contains the
size of the data level (level 0) buckets, in virtual blocks, for the key described
by the XAB.

13.9

XAB$W_DFL Field
The data bucket fill size (DFL) field contains a numeric value that indicates
the maximum number of bytes (of data) in a data bucket. The largest possible
fill size is the bucket size, in blocks, multiplied by 512. The default value is
0, which is interpreted by VMS RMS as the maximum available space (that
is, no unused space). If the specified size is not 0, but is less than one-half of
the bucket size (in bytes), then the fill size used is one-half of the bucket size.
When you create an indexed file, you use this field to specify the number
of bytes of data you want in each data level bucket. If you specify a value
that is less than the actual bucket size, the data buckets contain some amount
of free space. At run time, VMS RMS uses the fill size specified when the
file was created only if the RAB$L _ROP (record-processing options) field
RAB$V_LOA option is specified in the RAB; otherwise, VMS RMS fills the
buckets.
When an XABKEY describes the primary key, the XAB$W_DFL field describes
the space in the buckets containing actual user data records. When the
XABKEY describes an alternate key, the XAB$W_DFL field describes the
space in the buckets containing pointers to the user data records.
It is advantageous to use the XAB$W_DFL field if you expect to execute

numerous random Put and Update services on the file after it has been
initially populated. You can minimize the movement of records (bucket
splitting) by specifying less than the maximum bucket fill size when you
create the file. To use the free space reserved in the buckets, programs that
execute Put or Update services on the file should not specify the RAB$L_
ROP field RAB$V_LOA option.

13-4

Key Definition XAB (XABKEY)
13.9 XAB$W_Dfl Field

This field corresponds to the FDL attribute KEY DATA_FILL (which is
expressed as a percentage).

13.10

XAB$8_DTP Field
The XAB$B_DTP field specifies the key data type and the key sort order,
ascending or descending.
In this keyword value field, each key data type option is defined by a
symbolic value. If the key sort order is descending, the letter D is prefixed to
the symbolic value; if the sort order is ascending, the prefix is omitted. For
example, a XAB$B_DTP field having the value XAB$C_DBN2 is an unsigned,
2-byte binary number that is sorted in descending order. On the other hand,
a XAB$B_DTP field having the value XAB$C_BN2 is an unsigned, 2-byte
binary number that is sorted in ascending order.
Only one option can be specified. It is identified by a symbolic constant
value; for example, the STG (string) option has the constant value XAB$C_
STG.
The options for the XAB$B_DTP field are listed in the following chart:
Keyword

Data Type

Sort Order

XAB$C_BN2

Unsigned 2-byte binary

Ascending

XAB$C_DBN2

Unsigned 2-byte binary

Descending

XAB$C_BN4

Unsigned 4-byte binary

Ascending

XAB$C_DBN4

Unsigned 4-byte binary

Descending

XAB$C_BN8

Unsigned 8-byte binary

Ascending

XAB$C_DBN8

Unsigned 8-byte binary

Descending

XAB$C_IN2

Signed 2-byte integer

Ascending

XAB$C_DIN2

Signed 2-byte integer

Descending

XAB$C_IN4

Signed 4-byte integer

Ascending

XAB$C_DIN4

Signed 4-byte integer

Descending

XAB$C_IN8

Signed 8-byte integer

Ascending

XAB$C_DIN8

Signed 8-byte integer

Descending

XAB$C_CQL

Collating key

Ascending

XAB$C_DCOL

Collating key

Descending

XAB$C_PAC

Packed decimal string

Ascending

XAB$C_DPAC

Packed decimal string

Descending

Left-justified string of
unsigned 8-bit bytes

Ascending

XAB$C_DSTG

Left-justified string of
unsigned 8-bit bytes

Descending

XAB$C_STG

1 This is the default value.

The string data type may consist of from one to eight detached key field
segments that collectively make up the key. For more information about
segmented keys, see the descriptions of the XAB$W_POSO through XAB$W_
POS7 field and the XAB$B_SIZO through XAB$B_SIZ7 field.

13-5

Key Definition XAB (XABKEY)
13.10 XAB$B_DTP Field

Integer, binary, and packed decimal key fields must be a contiguous set of
bytes.
The null value (that is, the XAB$V_NUL option in the XAB$B_FLG field is
set) for the integer, binary, collating and packed decimal data types is 0, and
the XAB$B_NUL field is ignored (see XAB$B_FLG and XAB$B_NUL).
The formats of the binary and integer key field data types are presented
below.
Key Type

Format

XAB$C_BN2

LSB at A, MSB at A+ 1

XAB$C_DBN2

LSB at A, MSB at A+ 1

XAB$C_BN4

LSB at A, MSB at A+3

XAB$C_DBN4

LSB at A, MSB at A+3

XAB$C_BN8

LSB at A, MSB at A+7

XAB$C_DBN8

LSB at A, MSB at A+7

XAB$C_IN2

LSB at A, MSB and sign at A+ 1

XAB$C_DIN2

LSB at A, MSB and sign at A+ 1

XAB$C_IN4

LSB at A, MSB and sign at A+3

XAB$C_IN4

LSB at A, MSB and sign at A+3

XAB$C_IN8

LSB at A, MSB and sign at A+7

XAB$C_DIN8

LSB at A, MSB and sign at A+7

The collating key data types are used in conjunction with collating sequences
located in the indexed file prolog. Collating sequences are used with
multinational characters and are specified for each key. Note that key
compression and index compression are not permitted with collating keys.
A packed decimal string is a contiguous sequence of bytes specified by two
attributes: the address (A) of the first byte of the string and a length ( L) that
is the number of digits in the packed decimal. The bytes of a packed decimal
are divided into two 4-bit fields that must contain decimal digits, except for
the first four bits (0 through 3) of the last (highest addressed) byte, which
must contain a sign. The representation for the digits and signs is shown
below.

13-6

Digit or Sign

Decimal Value

Hexadecimal Value

Key Definition XAB (XABKEY)
13.10 XAB$B_DTP Field

Digit or Sign

Decimal Value

Hexadecimal Value

10, 12, 14, or 15

A,C, E,orf
B or D

11 or 13

The preferred sign representation is 12 for plus ( +) and 13 for minus ( - ).
The length ( L) is the number of digits in the packed decimal string (not
counting the sign) and must be in the range 0 through 31. When the
number of digits is even, an extra 0 digit must appear in the last four bits
(4 through 7) of the first byte. Again the length in bytes of the packed
decimal is L/2 + 1. The value of a zero-length packed decimal is O; it contains
only the sign byte, which also includes the extra 0 digit.
The address, A, of the packed decimal specifies the byte containing the most
significant digit in its high order. Digits of decreasing significance are assigned
to increasing byte addresses and from high to low within a byte. Thus, +123
has length 3 and is represented as follows:
4

3
2

I:+I

ZK-873-82

Similarly, -12 has length 2 and is represented as follows:
4

0
2

I:+I
ZK-874-82

This field corresponds to the FDL attribute KEY TYPE.

13.11

XAB$L_DVB Field
After an Open or Display service, the DVB field contains the starting virtual
block number of the first data level bucket for the key described by the XAB.

13-7

Key Definition XAB (XABKEY}
13.12 XAB$B_FLG Field

13.12

XAB$B_FLG Field
The key options flag (FLG) field specifies the following conditions:
•

Whether duplicate keys are permitted in the file

•

Whether a key value can change

•

Whether data is compressed

•

Whether string key options apply

Primary key values cannot change, but alternate key values may change,
depending on application requirements. Primary and alternate keys may be
duplicated depending on the key field and the application. An alternate key
field is more likely than a primary key field to use duplicates.
This field is a binary options field where each key characteristic has a
corresponding bit assignment. Multiple key characteristics can be associated
with each key (multiple bits can be set). Each option in the field has its own
symbolic offset and mask value. For example, the CHG key characteristic has
a symbolic offset of XAB$V_CHG and a mask value of XAB$M_CHG.
When you create an indexed file and are defining a string key, you can
optionally specify the XAB$V_IDX_NCMPR, XAB$V_KEY_NCMPR, and
XAB$V_NUL options.
These are the options for the XAB$B_FLG field:
Options

XAB$V_CHG
The key value within the record in the file can be changed by a program
during an Update service. This option can be specified only for alternate
keys.

This option corresponds to the FDL attribute KEY CHANGES.
XAB$V_DAT_NCMPR
Do not compress data. This option can be specified to override compression
of data for Prolog 3 files for the primary key; that is, when XAB$_REF is 0.

This option corresponds to the FDL attribute KEY DATA_RECORD_
COMPRESSION.
This option is not supported for DECnet operations; it is ignored.
XAB$V_DUP
The key value within the record in the file may have the same key value as
another record (or other records) within the file.

This option corresponds to the FDL attribute KEY DUPLICATES.
XAB$V_IDX_NCMPR
Do not compress index. This option can be specified to override compression
of keys in the index for Prolog 3 files. This option is only valid if a string key
is being defined.

This option corresponds to the FDL attribute KEY INDEX_COMPRESSION
and it is not supported for DECnet operations.

13-8

Key Definition XAB (XABKEY)
13.12 XAB$B_FLG Field

XAB$V_KEV_NCMPR
Do not compress key. This option can be specified to override compression of
each key for Prolog 3 files. For a primary key (XAB$_REF is 0), the primary
keys at the data level are not compressed; for each alternate key (XAB$_REF
is greater than 0), the secondary index data records (SIDRs) that point to the
data record location are not compressed. This option is only valid if a string
key is being defined.
This option corresponds to the FDL attribute KEY DATA_KEY_
COMPRESSION and it is not supported for DECnet operations.
XAB$V_NUL
When set, this bit refers VMS RMS to the XAB$B_NUL field to determine
whether or not you have defined a null character for removing records from
the related alternate index. This option can be specified only for alternate key
indexes using string type keys.
The defaults and combinations of allowing changeable key values (XAB$V_
CHG option) and duplicate key values (XAB$V_DUP option) depend on
whether a primary or alternate key is being defined by this XABKEY. The
allowed combinations and defaults for duplicate and changeable key values
are described below.
Combinations

Primary Key

Alternate Key

XAB$V_CHG and XAB$V_DUP both set

Error

Allowed

XAB$V_CHG set, XAB$V_DUP clear

Error

Allowed

XAB$V_CHG clear, XAB$V_DUP set

Allowed

XAB$V_CHG and XAB$V_DUP both clear

Default

By default, duplicate keys are not allowed for the primary key and its value
cannot change.
If the XABKEY control block is not initialized by the $XABKEY macro, then
the defaults for alternate keys are the same as for primary keys and null key
values are not used. However, if the XABKEY control block is initialized by
the $XABKEY macro, the following defaults apply to alternate keys:

•

Duplicate key values are allowed.

•

Key values can change.

•

Null key values are not allowed.

These defaults are applied only if the entire XAB$B_FLG field is defaulted.
Note that VMS RMS supports alternate indexes that prohibit duplicate key
values but do allow key values to change for Update services. Older versions
of RMS-11 (in contrast to VMS RMS) do not allow this particular combination
of attributes for alternate indexes. This factor should be considered when you
create files with VMS RMS that may also be processed by RMS-11.
This option corresponds to the FDL attribute KEY NULL_KEY.

13-9

Key Definition XAB (XABKEY)
13.13 XAB$B_IAN Field

13.13

XAB$B_IAN Field
The index bucket area number (IAN) field contains a numeric value in the
range 0 through 254, representing an area identification number contained in
the XAB$B_AID field of an XABALL present in the same chain. The default
is 0 (that is, area 0).
When you create an indexed file, you use this argument to specify the area of
the file that the index buckets are to reside in only when both of the following
are true:
•

You are creating a new indexed file.

•

You are using allocation XABs to define areas.

When the XABKEY describes the primary key, the index level of the index
consists of all levels of the tree-structured primary index down to and
including the level containing pointers to the user data records themselves.
However, when the key definition describes an alternate key, the index
level of the index comprises all levels of the tree-structured alternate index
down to, but not including, the level containing buckets in which VMS RMS
maintains pointer arrays describing the user data records. For directions about
how to place the lowest level of the index in a location separate from the
higher levels, see the description of the XAB$B_LAN field.
This field corresponds to the FDL attribute KEY INDEX_AREA.

13.14

XAB$B_IBS Field
After an Open or Display service, the index bucket size (IBS) field contains
the size of the index level (level 1 to n buckets, in virtual blocks, for the key
described by the XAB).

13.15

XAB$W_IFL Field
The index bucket fill size (IFL) field contains a numeric value representing
the maximum number of bytes in an index bucket. The maximum possible
fill size is the bucket size, in blocks, multiplied by 512. The default value
is 0, which is interpreted by VMS RMS as meaning the maximum available
space (that is, no unused space). If the specified size is not 0, but is less than
one-half of the bucket size (in bytes) then the fill size used is one-half of the
bucket size.
When you create an indexed file, you use this argument to specify the
number of bytes you want in each index bucket. If you specify less than
the total possible bucket size, you indicate that the index buckets are to
contain some amount of free space. At run time, VMS RMS uses the fill size
specified at creation time if the LOA option is specified in the RAB$L _ROP
(record-processing options) field of the RAB; otherwise, VMS RMS fills the
buckets.
When an XABKEY describes the primary key, the XAB$W_IFL field describes
the space in the buckets in all levels of the primary index down to and
including the level containing pointers to the user data records. When an
XABKEY describes an alternate key, the XAB$W_IFL field describes the space
in the buckets in all levels of the alternate index down to, but not including,

13-10

Key Definition XAB (XABKEY)
13.15 XAB$W_IFL Field

the level containing buckets in which VMS RMS maintains pointer arrays
describing the user data records.
It is advantageous to use the XAB$W_IFL field if you expect to perform

numerous random Put and Update services on the file after it has been
initially populated. You can minimize the movement of index records (bucket
splitting) by specifying less than the maximum bucket fill size when a file is
created. To use the free space thereby reserved in the buckets, programs that
invoke the Put or Update services for writing to the file should not specify
the RAB$L_ROP field RAB$V_LOA option.
This field corresponds to the FDL attribute KEY INDEX_FILL (which is
expressed as a percentage).

13.16

XAB$L_KNM Field
The key name buffer address (KNM) field contains the symbolic address of a
buffer that is available for assigning a user-specified name to the key being
defined. The name buffer must be at least 32 bytes in length and you may
use any 32-character string you choose to name the key field.
If the default value is taken ( 0 ), VMS RMS assumes no name is to be
assigned to the key. VMS RMS does not use this string but retains it in the
file as part of the key definition information for documentation purposes.

This field corresponds to the FDL attribute KEY NAME.

13.17

XAB$B_LAN Field
The lowest level of index area number (LAN) field contains a numeric value
(0 through 254) representing an area identification number contained in the
XAB$B_AID field of an XABALL present in the same XAB chain. If the
XAB$B_LAN field is not specified (that is, if the value is 0), the value in the
XAB$B_IAN field is used as a default; in other words, the lowest level of the
index occupies the same area of the file as the remainder of the index.
This field permits you to separate the lowest level (level 1) of the index from
all higher levels (levels 2+) of the index in an indexed file; you can use the
XAB$B_LAN field to specify an area of the index wherein the lowest level of
the index resides, separate from the area (or areas) specified by the XAB$B_
IAN field (wherein all other levels of the index reside). See XAB$B_IAN for
additional information.
You can specify the XAB$B_LAN field only when both of the following
conditions exist:
•

You are creating a new indexed file.

•

You are using allocation XABs to define areas.

Note that the area specified by the XAB$B_LAN field must have the same
bucket size as the area specified by the XAB$B_IAN field.
This field corresponds to the FDL attribute KEY LEVELl_INDEX_AREA.

13-11

l(ey Definition XAB (XABKEY)
1; 3.18 XAB$B_LVL Field

13.18

XAB$B_LVL Field
Following an Open or Display service, the level of root bucket (LVL) field
contains the level of the root bucket for the key described by the XAB.

13.1 $

XAB$W_MRL Field
Following an Open or Display service, the minimum record length (MRL)
field contains the minimum record length (in bytes) needed to contain the key
field for the key described by the XAB.
If the key described by the XAB is the primary key (XAB$_REF is 0), then a

record must be equal to or greater than the minimum record length returned
in XAB$W_MRL to be inserted or updated in the file.
If the key described by the XAB is an alternate key (XAB$_REF is greater

than 0), then a record must be equal to or greater than the minimum record
length returned in the XAB$W_MRL field to be recorded in the associated
index for that alternate key.

13.20

>c'AB$B_NSG Field
Following an Open or Display service, the number of key segments (NSG)
field contains the number of key segments that make up the key field for the
key described by the XAB (see the XAB$W_POSO through XAB$W_POS7
field).

13.21

XAB$B_NUL Field
Normally, VMS RMS updates all indexes to reflect the values in the
corresponding key fields of the records written to an indexed file. The
XAB$B_NUL field permits you to instruct VMS RMS not to make an entry
in an alternate index if a record being entered in an indexed file contains a
specified null alternate key value. To specify the XAB$B_NUL field, three
conditions must be satisfied:
•

The XABKEY must define an alternate key.

•

The XAB$B_FLG field XAB$V_NUL option must be set when you create
the file (see XAB$B_FLG).

•

The key data type must be string.

You can use any ASCII character in the null (NUL) field if you are defining a
string-type alternate key. The default null value for string-type alternate keys
is 0 and nonstring keys always use 0 for the null value.
This field corresponds to the FDL attribute KEY NULL_VALUE.

13.22

XAB$L_NXT Field
The next XAB address (NXT) field contains the symbolic address of the next
XAB. A value of 0 (the default) indicates that the current XAB is the last (or
only) XAB in the chain.

1a-12

Key Definition XAB (XABKEY)
13.23 XAB$W_PQSO Through XAB$W_PQS7 Field

13.23

XAB$W_PQSO Through XAB$W_POS7 Field
There are two types of keys, simple keys and segmented keys.
A simple key is made up of one or more contiguous bytes and it may be used
with any data type, including the string data type. For simple keys, the first
byte of the key position field contains a numeric variable whose value relative
to 0 defines the starting position of the key. The remaining bytes contain
zeros.
Segmented keys include two through eight strings of key data (segments) and
can only be used with string data type key fields. The key segments need
not be contiguous nor must they be in a particular order. Key segments may
overlap except for primary keys used with Prolog 3 files. If your application
requires overlapping key segments in a Prolog 3 file, consider using an
alternate segmented key. If you must have a primary key with overlapping
segments, VMS RMS requires you to use either a Prolog 2 or Prolog 1
structure (which it automatically assigns if the XAB$B_PROLOG field is not
specified).
For segmented keys, the first word of the key position field specifies the
starting position of the first segment and each succeeding byte specifies the
starting position of one of the remaining segments. When processing records
that contain segmented keys, VMS RMS regards a segmented key field as a
single, logically contiguous string beginning with the first segment and ending
with the last.
You should note that the XAB$W_POSO through XAB$W_POS7 and the
XAB$B_SIZO through XAB$B_SIZ7 (key size) fields must define the same
number of key position values and key size values.
This field corresponds to the FDL attributes KEY POSITION and SEGn_
LENGTH.

13.24

XAB$B_PROLOG Field
The prolog (PROLOG) field defines the version or structure level of the file
index. It contains a numeric value from 0 through 3.
The XAB$B_PROLOG field is input to the Create service, and it is returned
by the Display and Open services.
This field must only be used to define a primary key.
Prolog 3 is the default prolog level, unless the primary key contains
overlapping segments. VMS RMS examines the key characteristics and
determines the correct prolog structure to apply to the file. If the XAB$B_
PROLOG field is not specified (that is, if the value is 0), the process default
prolog level is examined, then the system default prolog level is used. These
default values are set by the DCL command SET RMS_DEFAULT/PROLOG.
You should not specify a prolog level 1 because VMS RMS decides whether
a Prolog 1 or Prolog 2 file should be created, depending on the key type
defined for the file. If you want to select a prolog level other than Prolog 3,
you should select either 0 or 2.
For more detailed information regarding the options for selecting a specific
prolog level, see the description of the Create service in Part III.

13-13

Key Definition XAB (XABKEY)
13.24 XAB$B_PROLOG Field

This field corresponds to the FDL attribute KEY PROLOG and it is not
supported for DECnet operations; the default prolog in effect at the remote
node is used.

13.25

XAB$B_REF Field
The key of reference (REF) field defines a key as either the primary key or
some alternate key.
Note: For BLISS-32, this field is designated XAB$B_KREF.

This field contains a numeric value in the range 0 through 254. A value of 0
indicates that this is the primary key; a value of 1 indicates the first alternate
key; a value of 2 indicates the second alternate key, and so on. The order of
the XABKEYs is irrelevant.
Note that VMS RMS can process an indexed file with 255 defined keys; each
defined key field, however, has an associated cost in processing and I/O
time. The time required to build and maintain the index for the key field
and the disk storage required to contain the index for each key field should
be considered when you decide whether the field should be an alternate key
field. A file with six to eight defined keys (the primary key and five to seven
alternate keys) should be considered as a maximum; a file with two or three
defined keys is typical.
This field corresponds to the FDL attribute KEY n where n is the number of
the key being defined).

13.26

XAB$L_RVB Field
After an Open or Display service, the root index bucket virtual block number
(RVB) field contains the virtual block number for the root bucket of the index
for the key described by the XAB.

13.27

XAB$B_SIZO Through XAB$B_SIZ7 Field
The key size (SIZ) field defines the length of the key field within each record.
This field contains a numeric value representing the length, in bytes, of the
key within the record. Up to eight values can be assigned; maximum values
depend on the type of key.
The XAB$B_SIZO through XAB$B_SIZ7 field defines the length (in bytes)
of the key whose starting position is defined in the key position field of the
XAB. Two types of keys can be defined: simple and segmented (see the
XAB$W_POSO through XAB$W_POS7 field).
For a simple key, the XAB$B_SIZO through XAB$B_SIZ7 field contains only
one key size value (in XAB$B_SIZO).
For a segmented key, the XAB$B_SIZO through XAB$B_SIZ7 field contains
a key size value for each segment of the key. You should note that the
XAB$B_SIZO through XAB$B_SIZ7 field and the XAB$W_POSO through
XAB$W_POS7 field must contain the same number of key size values and
key position values. VMS RMS associates the first key position value with the
first key size value to define the location and length of the first segment of a
segmented key, and so forth.

13-14

Key Definition XAB (XABKEY)
13.27 XAB$B_SIZO Through XAB$B_SIZ7 Field

When the data type of the key is string, the total size (sum of all sizes) of the
key must be less than 256 bytes.
When the data type of the key is 2-byte integer or 2-byte binary, XAB$B_
SIZO must equal 2 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If
the size is 0, it defaults to 2.
When the data type of the key is 4-byte integer or 4-byte binary, XAB$B_
SIZO must equal 4 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If
the size is 0, it defaults to 4.
When the data type of the key is 8-byte integer or 8-byte binary, XAB$B_
SIZO must equal 8 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If
the size is 0, it defaults to 8.
When the data type of the key is packed decimal, the size specified by
XAB$B_SIZO must be from 1 through 16, and XAB$B_SIZ1 through XAB$B_
SIZ7 must contain 0.
This field corresponds to the FDL attribute KEY LENGTH or KEY SEGn_
LENGTH where n is the number of the segment being defined.

13.28

XAB$8_TKS Field
After an Open or Display service, the total key size (TKS) field contains the
total key size (the sum (in bytes) of XAB$B_SIZO through XAB$B_SIZ7) for
the key described by the XAB.

13-15

1 4 Protection XAB (XABPRO)
The protection XAB (XABPRO) specifies the ownership, accessibility and
protection for a file. Although an XABPRO is typically used as input to
the Create service, you can use it to change the protection of a file when
you execute the Close service if you have write access to the file and have
accessed the file for some type of modification (Put, Update, Delete, or
Truncate).

14.1

Summary of Fields
The symbolic offset, size, FDL equivalent, and a brief description of each
XABPRO field are presented in Table 14-1.
Table 14-1

XABPRO Fields

Field Offset

Size
(Bytes)

FOL Equivalent

XAB$L _ACLBUF

None

Address of buffer that contains ACL

XAB$L_ACLCTX

None

ACL positioning context

XAB$W _ACLLEN

None

Receives the length of an ACL during
an Open or Display service

XAB$W _ACLSIZ

None

Length of buffer containing binary ACEs

XAB$L_ACLSTS

None

System error status for ACL processing

None

Block length

XAB$B_BLN 1

Description

None

Type code

XAB$W_GRP 2

FILE OWNER

Group number of file owner

FILE OWNER

Member number of file owner

FILE MT_PROTECTION

Magnetic tape accessibility

XAB$B_COD

XAB$W_MBM

XAB$B_MT ACC
XAB$L_NXT

None

Next XAB address

XAB$W_PRO

FILE PROTECTION

File protection; contains four separate
fields denoting protection for system,
owner, group, and world

None

File protection options

FILE OWNER

User identification code; contains both
the group and member fields

XAB$B_PROT_OPT
XAB$L_UIC

1This field is statically initialized by the $XABPRO macro to identify this control block as an XABPRO.
2 This field

cannot be initialized by the $XABPRO macro.

14-1

Protection XAB (XABPRO)
14.1 Summary of Fields

Each XABPRO field is described below. Unless indicated otherwise, each field
is supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file access to
other systems, see the VMS Networking Manual.
The format and arguments of the $XABPRO macro and the $XABPRO_
STORE macro are defined in Appendix B.

14.2

XAB$L_ACLBUF Field
The ACL buffer field (ACLBUF) stores the address of a buffer area that
contains an access control list (ACL) for this file. The ACL buffer contains one
or more access control entries (ACE) in binary format. The system processes
the ACL until it encounters an ACE with a length byte value of 0 or until
it reaches the end of the buffer as indicated by XAB$W_ACLSIZ. The ACL
buffer is used as input to a Create service and as output from an Open or
Display service. The address in XAB$L_ACLBUF is used only as input to
these services.
During a Create operation, if the XAB$L_ACLBUF field has a value other
than 0, VAX RMS attempts to create the file using the value in the ACL
buffer. When the XAB$L_ACLBUF field has a value of 0 during a Create
operation, the file has an ACL only if an ACL is specified by the systemwide
defaults. Once a file has been created, the ACL cannot be changed using
VMS RMS.
During an Open or a Display operation, if the XAB$L_ACLBUF field has a
value other than 0, VMS RMS passes this address to the file system. The file
system then fills the user's buffer with the file's ACL (in binary format). If
the entire ACL does not fit into the user's buffer the file system puts only as
many ACEs into the buffer as possible. (See the XAB$L_ACLCTX field for
more information.)
You can convert an ASCII ACL to binary format by using the $PARSE_ACL
system service, and you can convert an ACL from binary format to ASCII
using the $FORMAT_ACL system service. For information about using the
$PARSE_ACL and $FORMAT_ACL services, see the VMS System Services
Reference Manual.
The use of this field for DECnet remote file access is not supported. This field
is ignored during DECnet operations.

14.3

XAB$L_ACLCTX Field
The XAB$L_ACLCTX field is used as a place holder by VMS RMS, and it
is used as an input and output field by VMS RMS during Open and Display
operations when the XAB$L_ACLBUF field has a value other than 0. In
order to read an ACL beginning with the first ACE, the XAB$L_ACLCTX
field must have a value of 0. When the initial Open or Display operation is
complete, VMS RMS fills the XAB$L_ACLCTX field with a value that serves
as a context field, allowing subsequent Open or Display operations that read
the remainder of the ACL (if the entire list of ACEs did not fit into the user's
buffer).

14-2

Protection XAB (XABPRO)
14.3 XAB$L_ACLCTX Field

For example, suppose you perform an Open operation, find that the value of
XAB$W_ACLLEN is greater than the ACL buffer, and then perform Display
operations until all of the ACEs in the ACL have been returned. You can then
reread the entire ACL on subsequent Opens or Displays only if you set the
value of the XAB$ L _ACLCTX field to 0.
The use of this field for DECnet remote file access is not supported. This field
is ignored during DECnet operations.

14.4

XAB$W_ACLLEN Field
The ACL length (ACLLEN) field receives the length (in bytes) of the access
control list for the file during an Open or a Display operation. If the file has
no ACL, the XAB$W_ACLLEN field has a value of 0.
If the file has an ACL that fits in the user's buffer, the value of the XAB$W_
ACLLEN field is equal to the number of bytes in the ACL. Even if the file's
ACL does not fit into the user's buffer, the value of the XAB$W_ACLLEN
field is still equal to the number of bytes in the ACL (not just the length of
that portion that fits into the buffer).

To determine the number of ACL entries that are in the user's buffer, you
must process binary ACEs until you find an ACE with a value of 0 or until
you come to the end of the buffer.
The use of this field for DECnet remote file access is not supported. This field
is ignored during DECnet operations.

14.5

XAB$W_ACLSIZ Field
The ACL buffer size (ACLSIZ) field specifies the length of the user buffer that
contains (or will contain) binary ACEs used as input to a Create service and
as output to an Open or Display service.
VMS RMS passes all information, including the ACL buffer, to and from the
file system using buffered 1/0 operations. VMS RMS limits buffered 1/0
transfers to 512 bytes, excluding the ACL buffer. Therefore, the size of the
ACL buffer plus 512 bytes cannot exceed either the BYTLM quota for the
process or the MAXBUF value for the system.
The use of this field for DECnet remote file access is not supported. This field
is ignored during DECnet operations.

14.6

XAB$L_ACLSTS Field
The ACL error status (ACLSTS) field contains a system error status relating
to the processing of ACLs. A value is returned to this field upon a successful
return from a Create, Open, or Display service.
Whenever you use the XAB$L_ACLBUF, XAB$L_ACLCTX, XAB$W_
ACLLEN, or XAB$W_ACLSIZ fields, be sure to use the following errorhandling guidelines:
•

If the FAB$L_STS field (RO) contains an error status, handle the error in
the usual manner.

14-3

Protection XAB (XABPRO)
14.6 XAB$L_ACLSTS Field

•

If the FAB$L_STS field (RO) contains a success status, then you must
check the value in XAB$L_ACLSTS. If XAB$L_ACLSTS contains a
success status, then the entire operation completed successfully and
no further action is required; if XAB$L_ACLSTS contains an error
status, handle the error appropriately. Note that a value is placed in the
XAB$L_ACLSTS field only when a success status is returned in FAB$L_
STS (RO).

This extra level of error checking is necessary because the success or failure
of reading and writing ACLs is independent of the success or failure of the
whole operation. Thus, in the absence of this additional error checking, it is
possible to create a file successfully even though an ACL error occurred.
This field is relevant only when an ACL is used with a Create service or when
an ACL is returned from an Open or Display service. The use of this field for
DECnet remote file access is not supported, and it is ignored during DECnet
operations.

14.7

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABPRO, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_PROLEN (this is done by the $XABPRO macro).

14.8

XAB$B_CQD Field
The type code (COD) field is a static field that identifies this control block
as an XABPRO. Once set, this field must not be altered unless the control
block is no longer needed. This field must be initialized to the symbolic value
XAB$C_PRO (this is done by the $XABPRO macro).

14.9

XAB$W_GRP Field
The file owner group number (GRP) field contains the half of the XAB$L_
UIC field that defines the group number. Refer to the XAB$L_UIC field
description for additional information. The contents of the XAB$L _UlC field,
rather than the $XABPRO macro, establish the initial value of the XAB$W_
GRP field.
This field corresponds to the FDL attribute FILE OWNER.

14-4

Protection XAB (XABPRO)
14.10 XAB$W_MBM Field

14.10

XAB$W_MBM Field
The file owner member number (MBM) field contains the half of the XAB$L_
UIC field that defines the member number. Refer to the XAB$L _UIC field
description for additional information. The contents of the XAB$L _UIC field,
rather than the $XABPRO macro, establish the initial value of the XAB$W_
MBM field.
This field corresponds to the FDL attribute FILE OWNER.

14.11

XAB$B_MT ACC Field
The magnetic tape accessibility (MTACC) field enables you to access HDRl
labels for ANSI-labeled magnetic tapes, in compliance with ANSI standards.
The value specified in the XAB$B_MTACC field is input to the Create service
and output from the Open and Display services for magnetic tape only.
The character to be inserted in the accessibility field of the HDRl label must
be one of the following:
•

An uppercase letter from A through Z

•

A digit from 0 through 9
(SPACE)
!

%
&
(

)

•

One of the following special characters:

I
'

>
?

Note that if this field is not specified or if the specification is invalid, a space
character is inserted into the HDRl accessibility field.
This field corresponds to the FDL attribute FILE MT_PROTECTION. and it is
not supported for DECnet operations.

14.12

14-5

Protection XAB (XABPRO)
14. 1 3 XAB$W_PRO Field

14.13

XAB$W_PRO Field
The file protection (PRO) field specifies the access privileges granted to the
four classes of users: system, owner, group, and world.
This field consists of four 4-bit subfields; each subfield is a binary options
field where each possible access privilege has a corresponding bit assignment.
The file access privileges must be specified in the following order:
<SYSTEM,OWNER,GROUP,WORLD>
To deny access, set the appropriate bits in the protection word to 1. If you
want to grant access to a specific user class, clear the appropriate bit.
The following list associates each subfield with its symbolic offset:
•

System-XAB$V_SYS

•

Owner-XAB$V_OWN

•

Group-XAB$V_GRP

•

World-XAB$V_WLD

Additionally, each access specification has the following mask values:
•

No read access-XAB$M_NOREAD

•

No write access-XAB$M_NOWRITE

•

No execute access-XAB$M_NOEXE

•

No delete access-XAB$M_NODEL

A user is granted the maximum number of types of access rights for each of
the Classes to which he belongs.
Each access code consists of four bits for each user class, or four subfields
in the word identified by XAB$W_PRO. This field is organized as shown in
Figure 14-1.
Figure 14-1

File Protection Field

12 11

15
world

8 7
group

o-er

system

ZK-872-82

14-6

Protection XAB (XABPRO)
14.13 XAB$W_PRO Field

If you do not explicitly specify file protection when you invoke the Create
service, VMS RMS attempts to determine file protection in the following
order:
1

Using the protection assigned to an existing file of the same name

Using the default file protection of the directory

Using the process-default protection

The following chart provides detailed descriptions of the four user classes:
User Class

Description

System

Specifies access rights for users executing under a system
UIC, that is, users whose group number is less than the value
for a system UIC, which is defined by the system manager
(usually 10 or less).

Owner

Specifies access rights for the owner of the file. A user is
considered the owner of the file only if both the group and
member number fields of the accessing process match the
group and member number fields of the file owner's UIC
stored with the file.

Group

Specifies the access rights for users whose group number
matches the group number field of the file owner.

World

Specifies access rights for all users. World access is used for
granting access to users who are not in the system, owner,
or group classifications.

This field corresponds to the FDL attribute FILE PROTECTION.

14.14

XAB$B_PROT_QPT Field
The ACL file protection (PRQT_OPT) field provides a single option, the
XAB$V_PROPAGATE option, which is used as input during an Enter or
a Rename operation. (During a Rename operation, the protection XAB is
assumed to be attached to FAB2.)
The XAB$B_PROT_OPT field is a binary options field where each file
protection option has a corresponding bit assignment. Options are identified
using mnemonics, and each option has its own symbolic offset and mask
value. For example, the PROP AGATE option has a symbolic offset of
XAB$V_PROPAGATE and a mask value of XAB$M_PROPAGATE.
If the XAB$V_PROPAGATE bit is set in this field during either an Enter or
Rename operation, the file receives new security attributes when the new
directory entry is made. These security attributes follow the same rules as
apply during a Create operation. For example, if a lower version of a new file
exists, the new file inherits the security attributes of the next lower version of
the file. If the XAB$V_PROPAGATE bit is not set, the security attributes of
the new file do not change.

This field is not supported for DECnet operations; it is ignored.

14-7

Protection XAB (XABPRO)
14.15 XAB$L_UIC Field

14.15

XAB$L_UIC Field
The user identification code (UIC) field combines the two XABPRO fields that
define the UIC of the owner of a file: the XAB$W_GRP (group number) and
XAB$W_MBM (member number) fields. Both numbers are octal numbers.
The valid range for a group number is 0 to 37777; the valid range for a
member number is 0 to 177777. Note that the maximum value in each case
(37777 and 177777) is reserved for DIGITAL use only. This field corresponds
to the FDL attribute FILE OWNER.
The symbolic offsets for the group number field and the member number
field respectively are XAB$W_GRP and XAB$W_MBM.
The total user identification field, including both the group and member
number fields, has a symbolic offset of XAB$L _UIC.
Note that if no file protection XAB is provided or if the user identification
field is null for a Create service, VMS RMS determines the owner's UIC using
the following logical order:
1

The owner UIC of an existing version of the file if the creating process
has ownership rights to the previous version.

The owner UIC of the parent directory, if the creating process has
ownership privileges to the parent directory.

The UIC of the creating process.

If you wish to create an output file with a UIC different from your own, you

must have system privilege (SYSPRV).

14-8

1 5 Revision Date and Time XAB (XABRDT)
The revision date and time XAB (XABRDT) specifies the revision date and
time and the revision number when a Close service is invoked for a file. The
XABRDT operates much like the Date and Time XAB (XABDAT) when input
to the Create, Open, or Display services. However, when you gain access to
a file for writing, issuing a Close service for that file causes the revision date
and time to be set from the current date and time and the revision number to
be incremented. Thus, any revision date and time value you specify through
the XAB on a Create service is lost.
You can input the XABRDT to a Close service and cause the file's revision
date and time and revision number to take on the specified values. If you
want to change the revision date and time when you close the file, you must
have write access to the file and have accessed the file for some type of
modification (Put, Update, Delete, or Truncate).

15.1

Summary of Fields
The two XABRDT fields that specify revision information are described below.
•

Revision date and time (XAB$Q _RDT) is a 64-bit binary field that
indicates the date and time at which the file was last updated.

•

Revision number (XAB$W_RVN) indicates how many times this file has
been opened for write operations.

The following list describes how these two XABRDT fields are used by the
VMS RMS file-processing services.
Service

XAB$Q_RDT

XAB$W_RVN

Input

Create

Input

Display

Output

Erase

Not used

Extend

Not used

Open

Output

If you specify a revision date and time of 0, VMS RMS substitutes the current
date and time when you close the file. If the XABRDT is present when you

invoke an Open (or a Display) service, the XAB$Q_RDT field contains the
file's revision date and time value. Because the XAB$Q _RDT field is filled
(not 0), VMS RMS does not substitute the current date and time.
Use the XABRDT block. only to specify a new (nondefault) value for the
XAB$Q _RDT and XAB$W_RVN fields. You must set these fields between
the time you invoke the Open service and the time you invoke the Close
service. If you set the XAB$Q_RDT and XAB$W_RVN fields before you
invoke the Open service, the file's revision date, time and number override

15-1

Revision Date and Time XAB (XABRDT)
15.1 Summary of Fields

the specified values. To determine the contents of the XAB$Q_RDT and
XAB$W_RVN fields, examine the appropriate fields of the XABDAT block.
The symbolic offset, size, FDL equivalent, and a brief description of each
XABRDT field are presented in Table 15-1.
Table 15-1

XABRDT Fields
Size
(Bytes)

FOL Equivalent

Description

XAB$B_BLN 1

None

Block length

None

Type code

Field Offset

XAB$B_COD
XAB$L_NXT

None

Next XAB address

XAB$Q_RDT 2

DA TE REVISION

Revision date and time

FILE REVISION

Revision number

XAB$W_RVN
1 This field

is statically initialized by the $XABRDT macro to identify this control block as a

XABRDT.
2 This field cannot be initialized by the $XABRDT macro; it must be specified before you

invoke the Close service to be used as input to the Close service.

Each XABRDT field is described below. Unless indicated otherwise, each field
is supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS systems. For
information about the support of VMS RMS options for remote file access to
other systems, see the VMS Networking Manual.
The format and arguments of the $XABRDT and $XABRDT_STORE services
are defined in Appendix B.

15.2

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABRDT, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field is initialized to the symbolic value
XAB$C_RDTLEN by the $XABRDT macro.

15.3

XAB$B_CQD Field
The type code (COD) field is a static field that identifies this control block as
an XABRDT. Once set, this field must not be altered unless the control block
is no longer needed. This field is initialized to the symbolic value XAB$C_
RDT by the $XABRDT macro.

15.4

15-2

Revision Date and Time XAB (XABRDT}
15.5 XAB$Q_RDT Field

15.5

XAB$Q_RDT Field
The revision date and time (RDT) field contains a 64-bit binary value
expressing the date and time at which the file was last updated. Note that
this field is limited to a granularity of 1 second for remote files.
This field corresponds to the FDL attribute DATE REVISION.

15.6

15-3

1 6 Recovery Unit XAB (XABRU)
The recovery unit XAB ($XABRU) control block supports the use of recovery
units to assure data file integrity. See the VAX RMS Journaling Manual for
details.

16-1

1 7 Summary XAB (XABSUM)
The summary XAB (XABSUM) can be associated with a FAB at the time a
Create, Open, or Display service is invoked. The presence of this XAB during
these calls allows VMS RMS to return to your program the total number of
keys and allocation areas defined and the version number when the file was
created. Note that an XABSUM is used only with indexed files.

17.1

Summary of Fields
The symbolic offset, size, and a brief description of each XABSUM field are
presented in Table 17-1.
Table 17-1

XABSUM Fields

Field Offset

Size

XAB$B_BLN 1

Byte

Block length

XAB$B_COD 1

Byte

Type code

XAB$B_NOA 2

Byte

Number of allocation areas defined for the file

XAB$B_NQK

Description

Byte

Numbers of keys defined for the file

XAB$L_NXT

Longword

Next XAB address

XAB$W_PVN 2

Word

Prolog version number

1 This field is statically initialized by the $XABSUM macro to identify this control block as
an XABSUM.

2 This field cannot be initialized by the $XABSUM macro.

Each XABSUM field is described below. Unless indicated otherwise, each field
is supported for DECnet operations using remote files with a VMS system as
the remote node. Note that the words "DECnet operations" in the following
descriptions refer to remote file operations between two VMS Version 5.0
systems. See the VMS Networking Manual for information about the support
of VMS RMS options for remote file access to other systems.
The format and arguments of the $XABSUM and $XABSUM_STORE macros
are defined in Appendix B.

17.2

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABSUM, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field is initialized to the symbolic value
XAB$C_SUMLEN by the $XABSUM macro.

17-1

Summary XAB (XABSUM)
17 .3 XAB$B_CQD Field

17.3

XAB$B_CQD Field
The type code (COD) field is a static field that identifies this control block as
an XABSUM. Once set, this field must not be altered unless the control block
is no longer needed. This field is initialized to the symbolic value XAB$C_
SUM by the $XABSUM macro.

17.4

XAB$B_NQA Field
The number of allocation areas (NOA) field indicates the number of allocation
areas defined when the file was created. Refer to Chapter 8 for information
about multiple allocation areas.

17.5

XAB$B_NQK Field
The number of keys (NOK) field indicates the number of keys defined when
the file was created. Refer to Chapter 13 for more information.

17.6

XAB$L_NXT Field
The next XAB address (NXT) field contains the symbolic address of the next
XAB. A value of 0 (the default) indicates that the current XAB is the last (or
only) XAB in the chain.

17.7

XAB$W_PVN Field
The prolog version number (PVN) contains a numeric value that indicates
the prolog number defined when the file was created. For more information
about prolog numbers, refer to Chapter 13.

17-2

1 8 Terminal XAB (XABTRM)
The terminal XAB (XABTRM) allows extended terminal read operations to
occur when a VMS RMS Get service is used fdt a terminal device. Unlike
most other XABs, the XABTRM is associated with a RAB (record stream). The
XABTRM provides information that VMS RMS passes to the terminal driver
to process a user-defined item list that defines the terminal read operation.

18.1

Summary of Fields
The symbolic offset, size, and a brief description of each XABTRM field are
presented in Table 18-1.
Table 18-1

XABTRM Fields

Field Offset

Size
(Bytes)

Description

XAB$B_BLN 1

Block length

XAB$B_COD 1

Type code

XAB$L _ITMLST

Item list address

XAB$W_ITMLST_LEN

Item list length

XAB$L_NXT

Next XAB address

1 This field is statically initialized by the $XABTRM macro to identify this control block as
an XABTRM.

To perform the extended terminal read operation, the following information
is required:
•

In the RAB, the RAB$L _ROP field RAB$V_ETO option must be specified
(set).

•

In the RAB, the RAB$L_XAB field must contain the addre~s of the
XABTRM.

•

In the XABTRM, the XAB$L_ITMLST and XAB$W_ITMLST_LEN fields
must contain the starting address and length of a valid terminal driver
read function item list.

•

The item list must be supplied according to the conventions described
for creating an item list for the terminal driver in the VMS 1/0 Usef's
Reference Manual: Part I in the VMS 1/0 User's Reference Volume.
An item list consists of one or more item list entries, where each item
defines an attribute of the terminal read operation. Instead of defining
terminal read arguments in the RAB, all such arguments (including certain
arguments only available with the item list method) are defined in the

18-~

Terminal XAB (XABTRM)
18.1 Summary of Fields

item list. The following list shows the RAB$L_ROP options related to a
terminal read operation and the equivalent item codes:

RAB$L_RQP
Bit Offset

Item Code

RAB$V_CVT

TRM$_MODIFIERS, bit TRM$M_TM_CVTLOW

RAB$V_PMT

TRM$_PROMPT

RAB$V_PTA

TRM$_MODIFIERS, bit TRM$M_TM_PURGE

RAB$V_RNE

TRM$_MODIFIERS, bit TRM$M_TM_NOECHO

RAB$V_RNF

TRM$_MODIFIERS, bit TRM$M_TM_NOFIL TR

RAB$V_TMO

TRM$_TIMEOUT

Each item code required for the terminal read operation is placed in an
item list along with other required information. Each item code is made
up of three longwords. Note that VMS RMS does not validate the item
list. If the item list is invalid, VMS RMS returns RMS$_QJO status in
the RAB$L _STS field and the specific terminal driver QIO status in the
RAB$L_STV field (see the VMS 1/0 User's Reference Manual: Part l in
the VMS 1/0 User's Reference Volume).
Each XABTRM field is described below. The XABTRM is not supported for
DECnet operations between two VMS systems. Thus, access to XABTRM
fields for DECnet operations is not supported. There are no equivalent FDL
attributes for the XABTRM fields.
The format and arguments of the $XABTRM macro and the $XABTRM_
STORE macro are defined in Appendix B.

18.2

XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length of the
XABTRM, in bytes. Once set, this field must not be altered unless the control
block is no longer needed. This field is initialized to the symbolic value
XAB$C_TRMLEN by the $XABTRM macro.

18.3

XAB$B_COD Field
The type code (COD) field is a static field that identifies this control block as
an XABTRM. Once set, this field must not be altered unless the control block
is no longer needed. This field is initialized to the symbolic value XAB$C_
TRM by the $XABTRM macro.

18.4

XAB$L_ITMLST Field
The item list address (ITMLST) field contains the symbolic address of the item
list that defines the extended terminal read operation.

18-2

Terminal XAB (XABTRM)
18.5 XAB$W_ITMLST_LEN Field

18.5

XAB$W_ITMLST_LEN Field
The item list length (ITMLST_LEN) field contains a numeric value that
indicates the length of the item list, in bytes.

18.6

18-3

VMS RMS Services
Part Ill, VMS RMS Services, lists the format of each VMS RMS service and
describes each service in detail. Each VMS RMS service is documented in
a structured format. See the Introduction to VMS System Routines for a
discussion of the format and how it is used.
Note that the calling format for each service requires a place holder (a
comma) if you omit the first optional argument (err) but include the second
optional argument (sue).

VMS RMS Services
$CLOSE

$CLOSE
The Close service terminates file processing and closes the file. This
service performs an implicit Disconnect service for all record streams
associated with the file.

FORMAT

SYS$CLOSE

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err] [,sue}]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

tab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Close service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-3

VMS RMS Services
$CLOSE

DESCRIPTION

You can invoke the Close service only when no operation is currently under
way (by your process) for the file being processed; that is, when no VMS
RMS requests for the file are outstanding. When this condition is satisfied,
the file can be closed to set the internal file identifier field to 0.
When the Close service is invoked properly, VMS RMS disconnects all RABs
for you, performs the various cleanup procedures (including file option
processing and XAB processing), and closes the file. The only types of XABs
that the Close service processes are the file protection XAB (XABPRO) and
revision date and time XAB (XABRDT). It processes these XABs only if the file
was opened or created for write access.
If a process tries to implement the truncate service when closing a sequential
file, it must have sole write access to the file. If other processes have write

access to the file, it remains accessible until all processes have completed.
If other processes have the file open for read access, VMS RMS defers the

truncation until the final process having read access closes the file.
Table RMS-1 lists the control block fields read as input by the Close service.
Note that if the FAB$V_DLT, FAB$V_SCF, or the FAB$V_SPL bits are set
by the associated Open or Create service, VMS RMS does not act on them
for the Close service. For example, if you open the file and specify that it be
deleted on close by setting the FAB$V_DLT bit, the file is deleted by VMS
RMS when it is closed regardless of the bit's state when the Close service is
invoked.
For additional information on the fields accessed by this service, see Part II.
Table RMS-1

Close Service FAB and XAB Input Fields

Field Name

Option or
XAB Type

Description

FAB$W_IFl 1

Internal file identifier.

FAB$L_FOP

File-processing options.
FAB$V_DLT

Deletes file on close.

FAB$V_RWC

Rewinds a magnetic tape volume.

FAB$V_SCF

Submits a file as a batch job (sequential files
only).

FAB$V_SPL2

Submits a file to the print queue (sequential
files only).

FAB$V_TEF

Truncates data at the end of the file
(sequential files only).

FAB$L_XAB

Next XAB address.
XABPRO

Modifies file protection and ownership.

XABRDT

Modifies revision date and number.

1 This field is required input to the FAB.
2 This field

is not supported for DECnet operations.

Table RMS-2 lists the control block fields written as output by the Close
service.

RMS-4

VMS RMS Services
$CLOSE

Table RMS-2

Close Service FAB and XAB Output Fields

Field Name

Option or
XAB Type

FAB$W_IFI

Internal file identifier (cleared).

FAB$L_STS

Completion status (also returned in register 0).

FAB$L_STV

Status value.

FAB$L_XAB

Next XAB address.
XABRDT

RETURN
VALUES

Description

New revision date and number returned.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_8LN

RMS$_BUG_DAP

RMS$_8USY

RMS$_CCF

RMS$_CDA

RMS$_COD

RMS$_CRC

RMS$_DAC

RMS$_DME

RMS$_DNR

RMS$_EXENQLM

RMS$_FAB

RMS$_1FI

RMS$_1MX

RMS$_MKD

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_PRV

RMS$_SPL

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WBE

RMS$_WER

RMS$_WLK

RMS$_WPL

RMS$_XAB

Note that even though a failure is indicated by the completion status code
value, the file is closed if VMS RMS clears the internal file identifier value
(FAB$W_IFI).

RMS-5

VMS RMS Services
$CONNECT

$CONNECT
The Connect service establishes a record stream by associating and
connecting a RAB with a FAB. You can invoke the Connect service only
for files that are already open.

FORMAT

SYS$CONNECT

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue}]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L _STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Connect service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the Connect service invokes if the
operation is unsuccessful. The err argument is the address of the entry mask
of this user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the Connect service invokes if the
operation is successful. The sue argument is the address of the entry mask of
this user-written completion routine.

RMS-6

VMS RMS Services
$CONNECT

DESCRIPTION

Any number of RABs can be connected to a FAB if the multistream (FAB$V_
MSE) option is selected when the file is opened or created. Each RAB
represents an independent record stream.
When you issue a Connect service, VMS RMS allocates an internal
counterpart for the RAB. This counterpart consists of the internal controls
needed to support the stream, such as record pointers and request status
information. All required I/O buffers are also allocated at this time.
The Connect service also initializes the next record pointer to the first record.
In indexed files, the key of reference establishes the index of the next record
pointer.
If you set the end-of-file (RAB$V_EOF) option in the RAB$L _ROP field
when issuing a Connect service, VMS RMS examines the organization of the
file being processed to determine the end-of-file positioning strategy.

For sequential or relative files, VMS RMS goes to the next record beyond the
last currently existing record in the file. (The next record is inserted at the
logical end of the file, and the service returns RMS$_EOF status in response
to a request for sequential access.)
For indexed files, VMS RMS verifies that the first record inserted is inserted in
the proper sort order. If the record cannot be inserted in the proper sort order
because of user action, VMS RMS returns a sequence error (RMS$_SEQ).
Get services that specify the sequential record access mode (RAB$B_RAC
is RAB$C_SEQ) return an RMS$_EOF status. Get services that specify the
random access mode (RAB$B_RAC is RAB$C_KEY), ignore (turn off) the
end-of-file positioning. Positioning to end-of-file is supported for all indexed
files, regardless of how many indexes the file contains. However, the EOF
positioning is supported only when you access a file by the primary key. If
the specified key of reference is a secondary key, an RMS$_ROP message is
returned.
In most cases, setting the RAB$V_EOF bit guarantees that the next record is
inserted at the logical end of the file. However, if a relative file or an indexed
file is shared by two or more active processes, the following scenario may
develop.
Assume that process A has invoked the Connect service after setting the
RAB$V_EOF bit and is positioned to the end of the file. Before .process A can
do a $PUT, process B inserts a record into the file and changes the current
record position. When process A attempts to do a $PUT into the position
that was formerly the end of the file, the record may be inserted improperly.
It may be inserted either before or after the record inserted by process B,
depending on the respective key values. Or, the $PUT operation may even
fail if the keys have the same value and duplicates are not allowed.
Table RMS-3 lists the control block fields read as input by the Connect
service. For additional information about the fields accessed by this service,
see Part II.

RMS-7

VMS RMS Services
$COl\l.N ECT

Table RMS-3

Connect Service RAB Input Fields

Field Name

Option or
XAB Type

Description

RAB$L_FAB 1

File access block address (required to access
the internal file identifier field, FAB$W_IFI).

RAB$W_IS1 1

Internal stream identifier (must be 0).

RAB$B_KRF

Key of reference (applies only to indexed
files).

RAB$B_MBC 2

Multiblock count (applies only to sequential
files residing on disk devices).

RAB$B_MBF 2

Multibuffer count.

RAB$L_ROP

Record-processing options:
RAB$V_ASY

Asynchronous: performs Connect service
asynchronously.

RAB$V_BIO

Block 1/0: specifies that only block 1/0
operations are permitted. The FAB$B_FAC
field FAB$V_BRO or FAB$V_BIO option must
be specified to the Open or Create service.

RAB$V_EQF 3

End-of-file: positions to the end of the file
upon execution of the Connect service.

RAB$V_RAH 2

Read ahead: allocates at least two buffers
for multibuffering (applies only to sequential
files on disk devices).

RAB$V_WBH 2

Write behind: allocates at least two buffers
for multibuffering (applies only to sequential
files on disk devices).

1This field is a required input to the Connect service.

2This field is not supported for DECnet operations.
3 Refer to text for exceptions.

Table RMS-4 lists the control block fields written as output by the Connect
service.

RMS-8

Table RMS-4

Connect Service RAB Output Fields

Field
Name

Description

RAB$W_ISI

Internal stream identifier.

RAB$L_STS

Completion status code (also returned in Register 0).

RA~$L_STV

Status value.

VMS RMS Services
$CONNECT

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_BLN

RMS$_BUG_OAP

RMS$_CCR

RMS$_COA

RMS$_CRMP

RMS$_0ME

RMS$_FAB

RMS$_GBC

RMS$_1AL

RMS$_1FA

RMS$_1FI

RMS$_KRF

RMS$_MBC

RMS$_NET

RMS$_NETFAIL

RMS$_NQRMAL

RMS$_PENOING

RMS$_RAB

RMS$_RFM

RMS$_RQP

RMS$_RPL

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS-9

VMS RMS Services
$CREATE

$CREATE
The Create service constructs a new file according to the attributes
you specify in the FAB. If any XABs are chained to the FAB, then the
characteristics described in the XABs are applied to the file. This service
performs implicit Open and Display services.

FORMAT

SYS$CREATE

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,{err} {,sue}]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Create service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-10

VMS RMS Services
$CREATE

DESCRIPTION

The Create service first uses the information from the specified FAB. If an
allocation control XAB is present, however, its allocation quantity (XAB$L_
ALQ), allocation options (XAB$B_AOP, only for the XAB$V_CTG and ·
XAB$V_CBT options), bucket size (XAB$B_BKZ), and default extension
quantity (XAB$W_DEQ) fields are used instead of the corresponding fields
of the FAB. When either key definition or allocation XABs are present, they
can be grouped in any order. If a name block (NAM) is also connected to the
FAB, VMS RMS fills in its fields with information about the created file. The
Create service leaves the file opened.
When a search list logical name is used, the file is placed in the first resultant
search list file specification unless the create-if (FAB$V_CIF) option is
specified. If you select the FAB$V_CIF option, VMS RMS searches all search
list file specifications to locate the file. If it finds the file, VMS RMS opens it
rather than create a new file. If VMS RMS does not find the file, it creates a
new file using the first resultant search list file specification.
You do not have to explicitly specify the FAB$V_PUT option when invoking
a Create service because write is the default access mode when you create a
file.
Table RMS-5 lists the control block fields read as input by the Create service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-5

Create Service FAB and XAB Input Fields

Field Name

Option or
XAB Type

Description

FAB$L_ALQ

Allocation quantity; ignored if an
allocation XAB is present.

FAB$B_BKS

Bucket size; ignored if an allocation XAB
is present.

FAB$W_BLS

Block size (applies to magnetic tape
only).

FAB$W_DEQ

Default file extension quantity; ignored if
an allocation XAB is present.

FAB$L_DNA

Default file specification string address.

FAB$B_DNS

Default file specification string size.

FAB$B_FAC

File access.
FAB$V_BIO

Block 1/0 access to file.

FAB$V_BRO

Block or record 1/0 access to file.

FAB$V_DEL
FAB$V_GET

Delete access to file.
1

Read access to file.

FAB$V_PUT 1

Write access to file and explicit file
extension.

FAB$V_TRN

Truncate access to file.

FAB$V_UPD

Update access to file and explicit file
extension.

1 These are the default values supplied by VMS RMS.

RMS-11

VMS RMS Services
$CREATE

Table RMS-5 (Cont.)

Option or
XAB Type

Field Name

Description

File specification string address.

File specification string size.

FAB$L_FNA
FAB$B_FNS

Create Service FAB and XAB Input Fields

FAB$L_FQp

File-processing options.
FAB$V_CBT

Contiguous best try: indicates that the
file is to be allocated contiguously on
a "best effort" basis. If VMS RMS is
unable to allocate the file within three
extents, this bit is switched off by the
Create service. To specify a single
extent, use the FAB$V_CTG option.

FAB$V_CIF

Create-if: opens a file if it already exists
or creates a file if it does not already
exist.

FAB$V_CTG

Contiguous: indicates that the space for
a file is to be allocated contiguously.

FAB$V_CHAN_
MODE3

Assigns the channel access mode.
FAB$V_DFW 3

Deferred write: writing back to the file
from the modified buffer is deferred.
Applies to relative and indexed files
and sequential files opened for shared
access.

FAB$V_DLT

Delete: indicates that the file is to be
deleted when closed.

FAB$V_LNM_
MODE 3

Specifies the logical name translation
access mode.
FAB$V_MXV

Maximize version: indicates that the
created file be given the specific version
number requested or a version number
that is one greater than the highest
version number of an existing file.

FAB$V_NAM 3

Name block inputs: indicates that the
NAM$W_DID and NAM$T_DVI fields
in the specified NAM block are used as
input.

FAB$V_NFS 3

Non-file-structured: indicates that the
accessed volume is to be processed in a
non-file-structured manner.

FAB$V_OFP

Output file parse: specifies that the
resultant file specification string of the
related file, if used, is to provide file
name and file type defaults only.

2 These fields must be specified unless you select the FAB$V_TMD or the FAB$V_TMP

option.
3 This field is not supported for DECnet operations.

RMS-12

VMS RMS Services
$CREATE

Table RMS-5 (Cont.)
Field Name

Create Service FAB and XAB Input Fields

Option or
XAB Type

Description

FAB$V_POS

Current position (applies to magnetic
tapes only).

FAB$V_RCK

Read-check: indicates that transfers
from disk are to be followed by a
read-compare operation.

FAB$V_RWC

Rewind on close (applies to magnetic
tape only).

FAB$V_RWO

Rewind on open (applies to magnetic
tape only).

FAB$V_SCF

Submit command file: indicates that
the file is to be submitted as a batchcommand file to the process default
batch queue (SYS$BA TCH) when the file
is closed (applies to sequential files only).

FAB$V_SPL

Spool: indicates that the file is to be
spooled to the process default print
queue (SYS$PRINT) when the file is
closed (applies to sequential files only).

FAB$V_SQO

Sequential only: indicates that the file
can be processed in a sequential manner
only, usually to enable DECnet-VAX file
transfer.

FAB$V_SUP

Supersede: allows an existing file to be
superseded by a new file of the same
name, type, and version.

FAB$V_TEF

Truncate at end of file: indicates that
the unused space allocated to a file
is deallocated when that file is closed
(applies to sequential files only).

FAB$V_TMD

Temporary marked for delete: indicates
that a temporary file is to be created,
and then deleted when the file is closed.

FAB$V_TMP

Temporary: indicates that a temporary
file is to be created and retained, but no
directory entry is made for this file.

FAB$V_UFQ 3

User file open: indicates that the file is
to be created or opened only (no further
processing of that file by VMS RMS is
allowed).

FAB$V_WCK

Write-check: indicates that transfers
to disk are to be followed by a readcompare operation.

FAB$B_FSZ

Fixed control area size.

FAB$W_GBC 3

Global buffer count for shared files.

3 This field is not supported for DECnet operations.

RMS-13

VMS RMS Services
$CREATE

Table RMS-5 (Cont.)
Field Name

Create Service FAB and XAB Input Fields

Option or
XAB Type

Description

FAB$W_IFI

Internal file identifier (must be 0).

FAB$L_MRN

Maximum record number (applies to
relative files and sequential files having
fixed-length 512-byte records).

FAB$W_MRS

Maximum record size.

FAB$L_NAM

Name block address.

FAB$B_ORG

File organization: sequential (FAB$C_
SEQ 1 ), relative (FAB$C_REL), or indexed
(FAB$C_IDX).

FAB$B_RAT

Record attributes.

FAB$B_RFM

Record format: fixed-length (FAB$C_
FIX), variable-length (FAB$C_ VAR),
VFC (FAB$C_ VFC), stream (FAB$C_
STM), stream with line feed terminator
(FAB$C_STMLF), stream with carriage
return terminator (FAB$C_STMCR), or
unidentified format (FAB$C_UDF 1 ).

FAB$B_RTV 3

Retrieval window size.

FAB$B_SHR

File sharing.
FAB$V_SHRDEL

Allows other users to delete records
from the file.

FAB$V_SHRGET

Allows other users to read the file; also
used with the FAB$V_MSE and FAB$V_
GET bits to specify a read-only global
buffer cache when global buffering is
enabled.

FAB$V_MSE 3

Allows multistream access.

FAB$V_NIL

Prohibits any type of file sharing by other
users.

FAB$V_SHRPUT

Allows other users to write records to
the file and extend it.

FAB$V_SHRUPD

Allows other users to update records in
the file and extend it.

FAB$V_UPI

Allows one or more users write access
to a shared file open for block 1/0
(applies to sequential files only).

FAB$L_XAB

Extended attribute block address.
XABALL

Allocation XAB; see Chapter 8.

XABDAT

Date and time XAB; see Chapter 9.

XABFHC

File header characteristics XAB; see
Chapter 10.

1These are the default values supplied by VMS RMS.

3 This field is not supported for DECnet operations.

RMS-14

VMS RMS Services
$CREATE

Table RMS-5 (Cont.)
Field Name

Create Service FAB and XAB Input Fields

Option or
XAB Type

Description

XABITM

Item list XAB; see Chapter 11.

XABKEY

Key definition XAB; see Chapter 13.

XABPRO

Protection XAB; see Chapter 14.

XABRDT

Revision date and time XAB; see
Chapter 15.

XABSUM

Summary XAB; see Chapter 17.

Table RMS-6 lists the control block fields written as output by the Create
service.
Table RMS-6

Create Service FAB and XAB Output Fields

Field Name

Option or
XAB Type

Description

FAB$L_ALO

Allocation quantity: contains actual number
of blocks allocated.

FAB$B_BKS

Bucket size: applies only to relative and
indexed files. When multiple areas are
defined for an indexed file, the largest
bucket size is returned.

FAB$W_BLS

Device block size (applies to files of
sequential organization only).

FAB$W_DEQ

Default file extension quantity.

FAB$L_DEV

Device characteristics.

FAB$B_FAC

File access.

FAB$L_FOP

File-processing option.
FAB$V_CBT

If this bit is set on input and remains on
as output, it indicates that the file was
allocated within three extents.

FAB$B_FSZ

Fixed-length control area size for VFC
format.

FAB$W_GBC

Global buffer count.

FAB$W_IFI

Internal file identifier.

FAB$L_MRN

Maximum record number.

FAB$W_MRS

Maximum record size.

FAB$B_ORG

File organization.

FAB$B_RAT

Record attributes.

FAB$B_RFM

Record format.

FAB$L_SDC

Secondary device characteristics.

FAB$B_SHR

File sharing.

RMS-15

VMS RMS Services
$CREATE

Table RMS-6 (Cont.)
Field Name

Create Service FAB and XAB Output Fields

Option or
XAB Type

Description

FAB$L_STS

Completion status code (also returned in
register 0).

FAB$L_STV

Status value: contains the 1/0 channel
number if the operation is successful.

FAB$L_XAB

Next XAB field.
XABALL

Allocation XAB; see Chapter 8.

XABDAT

Date and time XAB; see Chapter 9.

XABFHC

File header characteristics XAB; see
Chapter 10.

XABITM

Item list XAB; see Chapter 11.

XABKEY

Key definition XAB; see Chapter 13.

XABPRO

Protection XAB; see Chapter 14.

XABRDT

Revision date and time XAB; see
Chapter 15.

XABSUM

Summary XAB; see Chapter 17.

Use of the NAM Block for Creating Files

Table RMS-7 and Table RMS-8 list the NAM block fields that VMS RMS
uses as input and output for the Create service (provided that the name block
address field (FAB$L_NAM) is specified).
Table RMS-7

Create Service NAM Block Input Fields

Field Name

Option

Description.

NAM$W_DID 1

Directory identification (input only if
the FAB$L_FOP FAB$V_NAM option
is set).

NAM$T_DVl 1

Device identification (input only if the
FAB$L_FOP FAB$V_NAM option is
set).

NAM$L_ESA

Expanded string area address.

NAM$8_ESS

Expanded string area size.

NAM$B_NOP

NAM block options.
NAM$V_PWD

Password: indicates that a password
contained in a DECnet access control
string, if present in a file specification,
is to be left unaltered in the expanded
and resultant strings (instead of being
replaced by the word "password").

1 This field is not supported for DECnet operations.

RMS-16

VMS RMS Services
$CREATE

Table RMS-7 (Cont.)
Field Name

Create Service NAM Block Input Fields

Option

Description.

NAM$V_NOCONCEAL

Do not conceal device name: indicates
that when a concealed device logical
name is present, the concealed device
logical name is to be replaced by the
actual physical device name in the
resultant string.

NAM$L_RLF

Related file NAM block address.
NAM$L_RSA

Related file NAM block resultant string
address.

NAM$B_RSL

Related file NAM block resultant string
length.

NAM$L_FNB

Related file NAM block file name
status bits.

NAM$L_RSA

Resultant string area address.

NAM$B_RSS

Resultant string area size.

Table RMS-8

Create Service NAM Block Output Fields

Field Name

Description

NAM$W_DID 1
NAM$T_DVl

Directory identification.
Device identification.

NAM$B_ESL

Expanded string length. If the NAM$L_ESA field and the
NAM$B_ESS field are nonzero, and you do not select the
FAB$V_NAM option, or if the NAM$W _DID field is clear when
you invoke the Create service, VMS RMS copies the expanded
file specification string to the buffer specified by the NAM$L_
ESA field.

NAM$W_FID 1

File identification.

NAM$L_FNB

File name status bits. This is an output field from the Create
service only if the NAM bit in FAB$L_FOP field is clear, or if
the NAM$W _DID field is clear when you invoke the Create
service.

NAM$B_RSL

Resultant string length. If the NAM$L_RSA field and the
NAM$B_RSS field are both nonzero on input, the resultant file
specification is copied to the buffer specified by NAM$L _RSA.

1This field is not supported for DECnet operations.

Creating Files with the Create-If Option

Note that setting the create-if (FAB$V_CIF) option in the FAB$L_FOP field
specifies that if a new file has the same file specification as an existing file,
VMS RMS opens the existing file and no new file is created. Some fields
in the FAB, such as the file organization (FAB$B_ORG) and record format
(FAB$B_RFM) fields, are input to a Create service, but are output from an
Open service. For example, the indexed file organization could be specified
in the FAB$B_ORG field on a create-if operation. However, if an existing
sequential file has the same file specification as the indexed file that the user
RMS-17

VMS RMS Services
$CREATE

is attempting to create, then the existing file is opened and the FAB$B_ORG
field is set to sequential.
Creating Indexed Files

An indexed file consists of a prolog, with which it begins, and one or more
index structures. VMS RMS supplies the prolog with certain information
about the file, including file attributes.
VMS RMS supports two prolog levels, called Prolog 2 and Prolog 3. Unlike
Prolog 2 files, Prolog 3 files allow for file compression and additional key
types. For compatibility with RMS-11 data files that are transported or copied
(without conversion) between systems, you may want to choose Prolog 2.
If you want to create a Prolog 3 file, you must be sure that records in the
file are not larger than 32,224 bytes and, if the primary key is segmented,

that the segments of the primary key do not overlap (one or more bytes of
the record are used in more than one segment). If the primary key contains
overlapping segments, you can consider using that key as an alternate key
instead of a primary key or you can request (or let VMS RMS assign you) a
Prolog 2 indexed file.
Prolog 3 is the default prolog for VMS RMS, although VMS RMS creates a
Prolog 2 file only if the key characteristics are not compatible with Prolog 3
files. You can, however, override this default by requesting a specific prolog
version. The option you choose in requesting a specific prolog level affects
the behavior of VMS RMS with regard to creating the file and returning error
messages.
If you explicitly request a prolog version using the XABKEY XAB$B_
PROLOG field in an application program, and if other file characteristics

are incompatible with that prolog, then VMS RMS returns an error message
and does not attempt to create the file. For example, if you explicitly specify
Prolog 2 in the XAB$B_PROLOG field and have requested a key type that is
available only with Prolog 3 (such as an 8-byte integer key type), an error is
returned and the file is not created.
However, if a specific prolog version is not explicitly requested in the XAB$B_
PROLOG field, VMS RMS selects the greatest prolog level that can support
the specified key characteristics and does not return an error completion code.
In summary, there are two ways in which you can specify a particular prolog
version:
•

Specify the XAB$B_PROLOG field in an XABKEY block in an application
program, affecting only the file being created.

•

Use the DCL command SET RMS_DEFAULT/PROLOG to change the
process default.

If you do not specify the XAB$B_PROLOG field in your application program,
VMS RMS examines your process defaults to check for prolog information. If

this information is not specified in your process defaults, VMS RMS examines
the system defaults. If no prolog information is specified at the system level,
VMS RMS attempts to create a Prolog 3 file.

RMS-18

VMS RMS Services
$CREATE

You need not be concerned with the distinctions between Prolog 2 and Prolog
1 files. To create an indexed file with a prolog version other than Prolog
3, specify a Prolog 2 file. If all keys in the file are string keys, VMS RMS
provides a default of Prolog 1; in all other cases, Prolog 2 is the default. If
the file contains all string keys and Prolog 2 is requested, VMS RMS attempts
to create a Prolog 1 file only if no binary keys are present.
Note that RMS-11 and previous versions of VMS RMS return error messages
if requested to process Prolog 3 files.
If a failure is indicated, the file may be created, but it may not be opened for

processing, depending on the nature of the failure.

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_ACS

RMS$_ACT

RMS$_AID

RMS$_ALN

RMS$_ALO

RMS$_AOP

RMS$_ATR

RMS$_ATW

RMS$_BKS

RMS$_8KZ

RMS$_8LN

RMS$_8UG

RMS$_8UG_DAP

RMS$_8UG_DDI

RMS$_ CD A

RMS$_CHN

RMS$_ COD

RMS$_CRE

RMS$_CREA TED

RMS$_CRE_STM

RMS$_CRMP

RMS$_DAN

RMS$_DEV

RMS$_DFL

RMS$_DIR

RMS$_DME

RMS$_DNA

RMS$_DNF

RMS$_DNR

RMS$_DTP

RMS$_DVI

RMS$_ENO

RMS$_ENV

RMS$_ESA

RMS$_ESS

RMS$_EXENOLM

RMS$_EXP

RMS$_FAB

RMS$_FEX

RMS$_FLG

RMS$_FLK

RMS$_FNA

RMS$_FNF

RMS$_FNM

RMS$_FOP

RMS$_FSZ

RMS$_FUL

RMS$_GBC

RMS$_1AL

RMS$_1AN

RMS$_18K

RMS$_IFA

RMS$_1FI

RMS$_1FL

RMS$_1MX

RMS$_1QP

RMS$_KNM

RMS$_KSI

RMS$_LAN

RMS$_LNE

RMS$_MRN

RMS$_MRS

RMS$_NAM

RMS$_NET

RMS$_NETFAIL

RMS$_NOD

RMS$_NORMAL

RMS$_NPK

RMS$_0RG

RMS$_POS

RMS$_PRV

RMS$_QUO

RMS$_RAT

RMS$_REF

RMS$_RFM

RMS-19

VMS RMS Services
$CREATE

RMS-20

RMS$_RLF

RMS$_RPL

RMS$_RSS

RMS$_RST

RMS$_RUNDOWN

RMS$_SEG

RMS$_SHR

RMS$_SIZ

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPERSEDE

RMS$_SUPPORT

RMS$_SYN

RMS$_SYS

RMS$_UPI

RMS$_ VER

RMS$_WLK

RMS$_WPL

RMS$_XAB

VMS RMS Services
$DELETE

$DELETE
The Delete service removes an existing record from a relative or indexed
file. You cannot use this service when processing sequential files.

FORMAT

SYS$DELETE

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Delete service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-21

VMS RMS Services
$DELETE

DESCRIPTION

A Delete service always applies to the current record. Therefore, immediately
before invoking the Delete service, you must establish the current record by
issuing a Find or Get service.
Table RMS-9 lists the control block fields read as input by the Delete service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-9

Delete Service RAB Input Fields

Field Name

Option

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_ROP

Record-processing options.
RAB$V_ASY

Asynchronous: performs Delete service
asynchronously.

RAB$V_FDL

Fast delete (applies to indexed files).

Table RMS-10 lists the control block fields written as output by the Delete
service.
Table RMS-10

RETURN
VALUES

RMS-22

Delete Service RAB Output Fields

Field Name

Description

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_BLN

RMS$_BUG

RMS$_BUG_DAP

RMS$_CDA

RMS$_CHK

RMS$_CUR

RMS$_DME

RMS$_DNR

RMS$_FAC

RMS$_FTM

RMS$_IAL

RMS$_1BF

RMS$_1QP

RMS$_1RC

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_NQRMAL

RMS$_PENDING

RMS$_RAB

RMS$_RNL

RMS$_RPL

RMS$_RRV

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_TRE

RMS$_WLK

VMS RMS Services
$DISCONNECT

$DISCONNECT
The Disconnect service breaks the connection between a RAB and a FAB,
thereby terminating a record stream. All system resources, such as 1/0
buffers and data structure space, are deallocated.

FORMAT

SYS$DISCONNECT rab {,[err] {,sue]}

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L _STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for the
Disconnect service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-23

VMS RMS Services
$DISCONNECT

DESCRIPTION

The Close service (see $CLOSE) performs an implied disconnect for all
record streams connected to the FAB. Thus, you need not explicitly issue a
Disconnect service prior to closing the file. However, if more than one RAB
is connected to a single FAB, then you must explicitly disconnect the desired
RAB in order to terminate a particular record stream and leave the others
active.
Table RMS-11 lists the control block fields read as input by the Disconnect
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-11

Disconnect Service RAB Input Fields

Field Name

Description

RAB$W _ISi

Internal stream identifier (required).

RAB$L_ROP

Record-processing option, RAB$V_ASY. Asynchronous:
performs Disconnect service asynchronously.

Table RMS-12 lists the control block fields written as output by the
Disconnect service.
Table RMS-12

RETURN
VALUES

RMS-24

Disconnect Service RAB Output Fields

Field Name

Description

RAB$W_ISI

Internal stream identifier (zeroed).

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_CRC

RMS$_DME

RMS$_DNR

RMS$_1SI

RMS$_NET

RMS$_NETF AIL

RMS$_NORMAL

RMS$_PENDING

RMS$_RAB

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WBE

RMS$_WER

RMS$_WLK

VMS RMS Services
$DISPLAY

$DISPLAY
The Display service retrieves file attribute information about a file and
places this information in fields in the FAB, in XABs chained to the FAB,
and in a NAM block (if one is requested).

FORMAT

SYS$DISPLAY

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err] [,sue}]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for
the Display service call. The fab argument is the address of the FAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-25

VMS RMS Services
$DISPLAY

DESCRIPTION

A file must be open for access by a Create or Open service before the Display
service can be invoked.
VMS RMS places the file attribute information in the corresponding fields of
the FAB and specified XABs. If the FAB$L _NAM field contains a valid NAM
block address, certain NAM block fields are filled in, including the resultant
string, and the NAM$B_NOP options are examined.
Note that the Open and Create services automatically perform an implicit
Display service (see $OPEN, $CREATE).
Table RMS-13 lists the control block fields read as input by the Display
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-13
Field Name

Display Service FAB and ~AM Input Fields
Description

Option

FAB$W_IFI
FAB$L_NAM

Internal file identifier.
1

Name block address.

FAB$L_XAB 1

Extended attribute block address.

NAM$B_NOP

NAM block options.
NAM$V_PWD

NAM$V_NOCONCEAL

Do not conceal device name: indicates
that when a concealed device logical
name is present, the concealed device
logical name is to be replaced by
the actual physical device name (and
directory, if present) in the resultant
string.

1 If you want information about a particular XAB or NAM block, you must pass it to the
Display service as input.

Table RMS-14 lists the control block fields written as output by the Display
service.

RMS-26

Table RMS-14

Display Service FAB, NAM, and XAB Output Fields

Field Name

XAB Type

Description

FAB$L_ALQ

Allocation quantity in blocks.

FAB$B_BKS

Bucket size.

FAB$W_BLS

Block size.

FAB$W_DEQ

Default file extension quantity.

FAB$L_DEV

Device characteristics.

VMS RMS Services
$DISPLAY

Table RMS-14 (Cont.)
Field Name

Display Service FAB, NAM, and XAB Output
Fields

XAB Type

Description

FAB$B_FAC

File access.

FAB$B_FSZ

Fixed control area size.

FAB$W_GBC

Global buffer coum. ·

FAB$L_MRN

Maximum record number.

FAB$W_MRS

Maximum record size.

FAB$B_ORG

File organization.

FAB$B_RAT

Record attributes.

FAB$B_RFM

Record format.

FAB$B_RTV

Retrieval window size.

FAB$B_SHR

File sharing.

FAB$L_STS

Completion status code (also returned in
register 0).

FAB$L_STV

Status value.

FAB$L_XAB

Next XAB address.
XABALL

Allocation XAB; see Chapter 8.

XABDAT

Date and time XAB; see Chapter 9.

XABFHC

File header characteristics XAB; see
Chapter 10.

XABITM

Item list XAB; see Chapter 11.

XABKEY

Key definition XAB; see Chapter 13.

XABPRO

Protection XAB; see Chapter 14.

XABRDT

Revision date and time XAB; see Chapter 15.

XABSUM

Summary XAB; see Chapter 17.

NAM$W_DID

Directory identification.

NAM$T_DVI

Device identification.

NAM$W_FID

File identification.

NAM$L_FNB

File name status bits.

NAM$B_RSL

Resultant string length: indicates the length
of the resultant string that is written into
the buffer whose address is contained in the
NAM$L _RSA field (if the NAM$L _RSA and
NAM$B_RSS fields are nonzero).

RMS-27

VMS RMS Services
$DISPLAY

RETURN
VALUES

RMS-28

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_AID

RMS$_ATR

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_COD

RMS$_DME

RMS$_DNR

RMS$_ESA

RMS$_ESL

RMS$_ESS

RMS$_FAB

RMS$_1FI

RMS$_1MX

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_QK_NOP

RMS$_PLG

RMS$_PRV

RMS$_REF

RMS$_RPL

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_XAB

VMS RMS Services
$ENTER

$ENTER
The Enter service inserts a file name in a directory.

FORMAT

SVS$ENTER

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err] [,sue}}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Enter service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

DESCRIPTION

The Enter service function is performed automatically by the Create service
unless you select the FAB$V_TMP option or the FAB$V_TMD option. The
Enter service, however, allows you to perform this step separately. Note that
the file must be closed before you invoke the Enter service (FAB$W_IFI must
be 0).
When you enter a file name in a directory, no file associated with the FAB
can be open and no wildcard characters can be used.

RMS-29

VMS RMS Services
$ENTER

The Enter service requires many NAM block fields as input. You normally
precede the Enter service with an Open, Create, or Parse service (see $PARSE)
and a Search service (see $SEARCH), specifying the same FAB and NAM
block for each service.
The optional resultant string is moved to the buffer described by the
NAM$L_RSA and NAM$B_RSS fields (only if both these fields are nonzero).
If the file version number of the name string described by the expanded string
length and address fields of the NAM block is omitted or contains a 0, the
Enter service scans the entire directory. It assigns a version number that is
one higher than the highest found (or 1 if none is found).
The Enter service is not supported for DECnet operations with remote files
between two VMS systems.
Table RMS-15 lists the control block fields read as input by the Enter service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-15

Enter Service FAB and NAM Input Fields

Field Name

Description

FAB$W_IFI

Internal file identifier (must be 0).

FAB$L_NAM

Name block address.

NAM$W_DID

Directory identification: identifies the directory in which the
file name is to be entered.

NAM$T_DVl 1

Device identification: identifies the device containing the
directory in which the file name is to be entered.

NAM$L_ESA

Expanded string area address: contains file name, type, and
version to be entered.

NAM$8_ESL
NAM$W_FID

Expanded string length.
1

File identification: identifies the file to be entered into the
directory.

NAM$L_RSA

Resultant string area address.

NAM$8_RSS

Resultant string size.

1This field is not supported for DECnet operations.

Table RMS-16 lists the control block fields written as output by the Enter
service.

RMS-30

Table RMS-16

Enter Service FAB and NAM Output Fields

Field
Name

Description

FAB$L_STS

Completion status code (also returned in register 0).

FAB$L_STV

Status value.

NAM$B_RSL

Resultant string length.

VMS RMS Services
$ENTER

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_BLN

RMS$_ CD A

RMS$_CHN

RMS$_DEV

RMS$_DME

RMS$_DNF

RMS$_DNR

RMS$_DVI

RMS$_ENT

RMS$_ESA

RMS$_ESL

RMS$_FAB

RMS$_FNF

RMS$_1FI

RMS$_NAM

RMS$_NORMAL

RMS$_PRV

RMS$_RSL

RMS$_RSS

RMS$_RST

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WLD

RMS$_WLK

RMS-31

VMS RMS Services
$ERASE

$ERASE
The Erase service deletes a VMS RMS disk file and removes the file's
directory entry specified in the path to the file. If additional directory
entries have been created for this file by the Enter service, you must use
the Remove service to delete them.

FORMAT

SYS$ERASE

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err} [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L _STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Erase service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-32

VMS RMS Services
$ERASE

DESCRIPTION

Using the Erase service to delete a file releases the file's allocated space for
use by another file. The Erase service does not physically remove the data (as
does overwriting or zeroing).
Note that the file must be closed before you invoke the Erase service
(FAB$W_IFI must be zero). You can, however, delete a file that is currently
open, if you issue a Close service and specify the FAB$L_FOP field FAB$V_
DLT option. VMS RMS does not allow you to delete files from magnetic tape
volumes; they must be overwritten.
If a search list logical name is specified, the file is deleted only if it is found in
the first resulting search list file specification.

Table RMS-17 lists the control block fields read as input by the Erase service.
For additional information on the fields accessed by this service, see Part IL
Table RMS-17

Erase Service FAB and NAM Input Fields

Field Name

Option

Description

FAB$L_DNA

Default file specification string address.

FAB$B_DNS

Default file specification string size.

FAB$L_FNA

File specification string address.

FAB$B_FNS

File specification string size.

FAB$L_FOP

File-processing options.
FAB$V_NAM 1

NAM block inputs: allows use of the
NAM$W_DID, NAM$T_DVI, and NAM$W_
FID fields.

FAB$W_IFI

Internal file identifier (must be 0).

FAB$L_NAM

Name block address.

NAM$W_DID 1

Directory identification (input only if the
FAB$L_FOP field FAB$V_NAM bit is set).

NAM$T_DV1 1

Device identification (input only if the
FAB$L_FOP field FAB$V_NAM bit is set).

NAM$L_ESA

Expanded string area address.

NAM$B_ESS

Expanded string area size.

NAM$W_FID 1

File identification (input only if the FAB$L_
FOP field FAB$V_NAM bit is set).

NAM$L_RLF

Related file NAM block address.
NAM$L_RSA

Related file resultant string address.

NAM$B_RSS

Related file resultant string size.

NAM$L_FNB

Related file filename status bits.

1 This field is not supported for DECnet operations.

Table RMS-18 lists the control block fields written as output by the Erase
service. Note that the NAM block fields are used for output only if the name
block address field is specified in the FAB.

RMS-33

VMS RMS Services
$ERASE

Table RMS-18

Erase Service FAB and NAM Output Fields

Field Name

Description

FAB$L_STS

Completion status code (also returned in register 0).

FAB$L_STV
NAM$W_DID

Status value.
1

Directory identification.

NAM$T_DVl 1

Device identification.

NAM$8_ESL

Expanded string length. If the NAM$L _ESA field and the
NAM$8_ESS field are nonzero, and if the FAB$V_NAM bit
is clear or the NAM$W_DID field contains a zero, VMS RMS
copies the expanded file specification string to the buffer
specified by the input NAM$L_ESA field.

NAM$L_FNB

File name status bits.

NAM$8_RSL

Resultant string length (if NAM$L _RSA and NAM$B_RSS are
both nonzero on input, the resultant file specification is copied
to the buffer specified by NAM$L_RSA).

1 This field is not supported for DECnet operations.

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_ACS

RMS$_BLN

RMS$_BUG_DAP

RMS$_BUG_DDI

RMS$_CDA

RMS$_CHN

RMS$_DEV

RMS$_DIR

RMS$_DME

RMS$_DNA

RMS$_DNF

RMS$_DNR

RMS$_DVI

RMS$_ESA

RMS$_ESS

RMS$_FAB

RMS$_FNF

RMS$_FNM

RMS$_1FI

RMS$_10P

RMS$_LNE

RMS$_MKD

RMS$_NAM

RMS$_NET

RMS$_NETFAIL

RMS$_NOD

RMS$_NORMAL

RMS$_PRV

RMS$_QUO

RMS$_RLF

RMS$_RSS

RMS$_RST

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPERSEDE

RMS$_SUPPORT

RMS$_SYN

RMS$_TYP

RMS$_ VER

RMS$_WLK

RMS--34

VMS RMS Services
$EXTEND

$EXTEND
The Extend service increases the amount of space allocated to a VMS
RMS disk file. This service is most useful for extending relative files and
indexed files when you are doing block 1/0 transfers using the Write
service.

FORMAT

SYS$EXTEND

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err] [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Extend service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call· without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-35

VMS RMS Services
$EXTEND

DESCRIPTION

The Extend service is performed automatically as data is written to a file,
regardless of the file's organization. However, when you use block IfO, only
sequential files are automatically extended. Thus, you must use the Extend
service for relative and indexed files when using block 1/0. Also, you may
want to extend a file explicitly for performance reasons, such as placing a
large file extent (an extended part of a file) contiguous with the file.
You must open the file (FAB$W_IFI must not be 0) before you invoke the
Extend service; otherwise, an error occurs. The file sharing field (FAB$B_
FAC) must specify put (FAB$V_PUT) or update (FAB$V_UPD) access to the
file to be extended.
The allocation quantity field (FAB$L_ALQ or XAB$L_ALQ) specifies the
number of blocks that VMS RMS adds to the file. You can indicate other
attributes regarding the manner and location for allocation. For example, you
can indicate that the additional blocks must be allocated contiguously. If you
do specify contiguous space and not enough contiguous space is available, the
operation fails. (This extension is not contiguous with the initial file space.)
If an allocation control XAB is present, its allocation quantity (XAB$L _ALQ)

and allocation options (XAB$B_AOP, XAB$V_CBT and XAB$V_CTG bits
only) fields are used instead of the corresponding fields in the FAB. The
allocation quantity field of the XAB is set to the actual extension size. You
may specify multiple XABs to extend separate areas of indexed files.
Table RMS-19 lists the control block fields read as input by the Extend
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-19
Field Name

Extend Service FAB Input Fields
Description

FAB$L_ALO

Allocation quantity; ignored if an allocation XAB is present.

FAB$L_FOP

File-processing options: checked to see whether the FAB$V_
CTG or FAB$V_CBT bit is set to indicate contiguous allocation
(ignored for allocation XAB).

FAB$W_IFI

Internal file identifier (must not be 0).

FAB$L_XAB

Extended attribute block address. Only an allocation XAB
(XABALL) is processed.

Table RMS-20 lists the control block fields written as output by the Extend
service.
Table RMS-20

RMS-36

Extend Service FAB Output Fields

Field Name

Description

FAB$L_ALO

Allocation quantity: contains the actual extension allocation
value if no allocation XAB is present.

FAB$L_STS

Completion status code (also returned in register 0).

FAB$L_STV

Status value (contains the total number of blocks allocated,
totaled across all allocation XABs).

VMS RMS Services
$EXTEND

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_AID

RMS$_ALN

RMS$_ALQ

RMS$_AQP

RMS$_ATR

RMS$_ATW

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_COD

RMS$_DME

RMS$_EXT

RMS$_FAB

RMS$_FAC

RMS$_FUL

RMS$_1FI

RMS$_1MX

RMS$_10P

RMS$_LEX

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_PLG

RMS$_RPL

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SLJPPORT

RMS$_SYS

RMS$_WBE

RMS$_WER

RMS$_WLK

RMS$_WPL

RMS$_XAB

RMS-37

VMS RMS Services
$FIND

$FIND
The Find service locates a specified record in a file and returns its record
file address in the RAB$W _RFA field of the RAB. The Find service can be
used with all file organizations.

FORMAT

SYS$FIND

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Find service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-38

VMS RMS Services
$FIND

DESCRIPTION

The Find service gives you the following functional capabilities:
•

You can skip records when you are accessing a file sequentially by
making successive invocations of the Find service.

•

You can establish the current record context prior to invoking an Update,
Delete, or Truncate service.

•

You can establish a random access starting point in a. file for subsequent
sequential access operations such as the Get service.

When you follow the Find service with a sequential access operation, such as
the Get service, the current record context is established by the Find service
and the sequential access operation establishes a new sequential access context.
Conversely, when you follow the Find service with a nonsequential access
operation such as a Delete service or an Update service, the sequential access
context remains the same as it was prior to the Find service.
Table RMS-21 lists the control block fields read as input by the Find service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-21

Find Service RAB Input Fields

Field Name

XAB Type

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_KBF

Key buffer address (used only if RAB$B_
RAC field contains RAB$C_KEY or if
RAB$B_RAC contains RAB$C_SEQ and the
RAB$L_RQP field RAB$V_LIM option is
set).

RAB$B_KRF

Key of reference (used only with indexed
files and if RAB$B_RAC contains RAB$C_
KEY).

RAB$B_KSZ

Key size (used only if RAB$B_RAC field
contains RAB$C_KEY or if RAB$B_RAC
contains RAB$C_SEQ and the RAB$L _RQP
field RAB$V_LIM option is set).

RAB$L_PBF 1

Prompt buffer address (applies to terminal
devices only).

RAB$B_PSZ 1

Prompt buffer size (applies to terminal
devices only).

RAB$B_RAC

Record access mode (RAB$C_SEQ,
RAB$C_KEY, RAB$C_RF A) 2 .

RAB$W_RFA

Record file address (used only if RAB$B_
RAC contains RAB$C_RFA).

RAB$L_RQP

Record-processing options.
RAB$V_ASY

Asynchronous: performs Find services
asynchronously.

1 This field is not supported for DECnet operations.

2 The default for the RAB$B_RAC field is RAB$C_SEQ.

RMS-39

VMS RMS Services
$FIND

Table RMS-21 (Cont.)
Field Name

Find Service RAB Input Fields

XAB Type
RAB$V_CVT

Description
1

Convert: changes characters to uppercase
for a Find service to a terminal device.

RAB$V_KGE 3

Key is greater than or equal to compared
value (applies only to indexed files).

RAB$V_KGT 4

Key is greater than compared value (applies
only to indexed files). If neither RAB$V_
KGE nor RAB$V_KGT is specified, a key
equal match is made.

RAB$V_LIM

Limit: the key value described by the KBF
and KSZ fields is to be compared to the
value in the record accessed sequentially.

RAB$V_NLK

No lock: specifies that the record accessed
through the Find service is not to be locked.

RAB$V_NXR

Nonexistent record processing: specifies
that if the record directly accessed through
a Find service does not exist, the service is
to be performed anyway.

RAB$V_PMT 1

Prompt indicates that the contents of the
prompt buffer are to be used as a prompt
for a Find service to a terminal device.

RAB$V_PTA 1

Purge type-ahead buffer: eliminates any
information that may be in the type-ahead
buffer for a Find service to a terminal
device.

RAB$V_RAH 1

Read ahead: used with multiple buffers to
indicate read-ahead operations (sequential
files only).

RAB$V_REA

Lock for read: allows other users read
access to the record.

RAB$V_RLK

Read of locked record allowed: specifies
that a user who locks a record is allowing
the locked record to be read by other
accessors.

RAB$V_RNE 1

Read no echo: indicates that input data
entered on the keyboard is not echoed
(displayed) on the terminal device.

RAB$V_RNF 1

Read no filter: indicates that CTRL/U,
CTRL/R, and DELETE are not to be
considered control commands on terminal
input, but are to be passed to the
application program.

RAB$V_RRL

Read regardless of lock: read the record
even if another stream has locked the
record.

1This field is not supported for DECnet operations.

3 This symbolic offset is logically synonymous with RAB$V_EQNXT.
4 This symbolic offset is logically synonymous with RAB$V_NXT.

RMS-40

VMS RMS Services
$FIND

Table RMS-21 (Cont.)

Find Service RAB Input Fields

XAB Type

Field Name

RAB$V_TM0

Description
1

Timeout: indicates that the contents of
the timeout period field (RAB$B_TMO) is
to be used on a Find request for a locked
record (when the RAB$V_WAT option is
also specified) or for a terminal or mailbox
device.

RAB$V_ULK

Manual unlocking: specifies that a record
cannot be automatically unlocked.

RAB$V_WAT

Wait: if record is locked, wait until it is
available.

RAB$B_TM0 1

Timeout period: indicates the maximum
number of seconds that VMS RMS can use
to complete a Find request.

1 This field is not supported for DECnet operations.

Table RMS-22 lists the control block fields written as output by the Find
service.
Table RMS-22

Find Service RAB Output Fields

Field Name

Description

RAB$L_BKT

Bucket code: set to the relative record number for relative files
accessed sequentially.

RAB$W_RFA

Record file address.

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The record address (RAB$L_RBF) field and the record size (RAB$W_RSZ)
field are undefined after a Find service.

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ANI

RMS$_ATR

RMS$_ATW

RMS$_BES

RMS$_BLN

RMS$_BUG

RMS$_BUG_DAP

RMS$_CDA

RMS$_CHK

RMS$_CONTROLC

RMS$_CONTROL Y

RMS$_DEADLOCK

RMS$_DEL

RMS$_DME
RMS$_EXENQLM

RMS$_DNR

RMS$_EOF

RMS$_FAC

RMS$_FTM

RMS$_1~F

RMS$_10P

RMS$_1RC

RMS$_1SI

RMS$_KBF

RMS$_KEY

RMS$_KRF

RMS$_KSZ

RMS$_MRN

RMS$_NET

RMS-41

VMS RMS Services
$FIND

RMS$_NETFAIL

RMS-42

RMS$_NORMAL

RMS$_QK_ALK

RMS$_QK_DEL

RMS$_QK_LIM

RMS$_QK_RLK

RMS$_QK_RNF

RMS$_QK_RRL

RMS$_QK_WAT

RMS$_PBF

RMS$_PENDING

RMS$_PES

RMS$_PLG

RMS$_RAB

RMS$_RAC

RMS$_REF

RMS$_RER

RMS$_RFA

RMS$_RHB

RMS$_RLK

RMS$_RNF

RMS$_RQP

RMS$_RPL

RMS$_RRV

RMS$_RSA

RMS$_SQO

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_TMO

RMS$_TRE

RMS$_WBE

RMS$_WER

RMS$_WLK

VMS RMS Services
$FLUSH

$FLUSH
The Flush service writes out all modified 1/0 buffers and file attributes
associated with the file. This ensures that all record activity up to the
point at which the Flush service executes is actually reflected in the file.

FORMAT

SYS$FLUSH

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sucJ]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Flush service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-43

VMS RMS Services
$FLUSH

DESCRIPTION

The Flush service is not required at any time, not even with a Close service,
because the Close service performs the Flush functions implicitly.
During asynchronous operations, you must wait for any 1/0 activity to
complete before issuing a Flush service. You can also issue a Flush service
after receiving notification of completion through an asynchronous system
trap (AST).
Table RMS-23 lists the control block fields read as input by the Flush service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-23

Flush Service RAB Input Fields

Field Name

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_ROP

Record-processing option: RAB$V_ASY only. Asynchronous:
performs Flush services asynchronously.

Table RMS-24 lists the control block fields written as output by the Flush
service.
Table RMS-24

RETURN
VALUES

RMS-44

Flush Service RAB Output Fields

Field Name

Description

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Additional status information.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_DME

RMS$_DNR

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_NQRMAL

RMS$_PENDING

RMS$_RAB

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WBE

RMS$_WER

RMS$_WLK

VMS RMS Services
$FREE

$FREE
The Free service unlocks all records that were previously locked for the
record stream.

FORMAT

SYS$FREE

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err} [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Free service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-45

VMS RMS Services
$FREE

DESCRIPTION

The Free service unlocks all records previously locked for the record stream
(see also $RELEASE). If no records are locked for the record stream, VMS
RMS returns a status code of RMS$_RNL.
Table RMS-25 lists the control block fields read as input and written as
output by the Free service. For additional information on the fields accessed
by this service, see Part II.
Table RMS-25
Use

Field
Name

Description

Input

RAB$W_ISI

Internal stream identifier (required).

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

Output

RETURN
VALUES

RMS-46

Free Service RAB Input and Output Fields

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_8LN

RMS$_8UG_DAP

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_PENDING

RMS$_RAB

RMS$_RNL

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

VMS RMS Services
$GET

$GET
The Get service retrieves a record from a file.

FORMAT

SYS$GET rab [,[err] [,sue]}

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L _STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Get service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-47

VMS RMS Services
$GET

DESCRIPTION

The Get service is performed by using one of three possible record access
modes, as specified by the record access (RAB$B_RAC) field. The three
record access modes are sequential (SEQ), which is the default, random by
key (KEY), and random by record file address (RFA).
Relevant Record Access Modes

The sequential access mode is relevant for all file organizations as well as for
all devices. It is the only access mode allowed for nondisk devices, such as
terminals, mailboxes, and magnetic tape devices. In this mode, records are
retrieved from a given file in the same order in which they were written to
that file. This is not the case, however, for records retrieved from indexed
files. Sequential Get services for indexed files return records by key value in
the specified sort order, ascending or descending. The next record's key of
reference for sequential access to indexed files is established by one of the
following services:
•

Connect

•

Rewind (see $REWIND)

•

Find or Get using random access by key

•

Find or Get using random access by RF A

When you use random access by key with any operations related to these
services, the key of reference is established by the key of reference field
(RAB$B_KRF). When you use random access by RFA in conjunction with a
Find or Get service, however, the key of reference is always set to the primary
key.
You can use random access by key to retrieve records by key value. For
relative files and sequential files having fixed-length records, the key value
is the relative record number. For indexed files, the key value depends on
the data type of the specified key of reference. The key value is used to
search the index of the specified key of reference to locate the desired record.
A random access by key also establishes the next record for subsequent
sequential retrieval. This type of access may be used in this way to establish
a starting point for sequential retrieval of records at other than the beginning
of the file.
You can use random access by RFA to retrieve records directly from files
residing on disk devices. However, a record's address can be determined only
if the record has been accessed previously. The Find, Get, and Put services
each return the RFA value as output in the RAB$W_RFA field.
Random access of records in a file is prohibited when you open the file and
select the FAB$V_SQO option; that is, if you specify sequential operations
only.
Input from Stream Format Files

For stream format files, VMS RMS fills the user buffer with data until a
terminator is reached. If the buffer fills before a terminator is encountered,
the remainder of the data preceding the terminator is discarded, and an
RMS$_RTB error is returned. If the terminator for stream format (FAB$B_
RFM contains FAB$C_STM) is not CRLF (carriage return followed by line
feed), the terminator is stored in the buffer following the record and included
in the size of the record.
RMS-48

VMS RMS Services
$GET

Input from Terminal Devices

There are two methods of obtaining input from a terminal using VMS RMS:
1

Using the RAB$L_ROP field to define the terminal input operation.
Certain options applicable to the RAB$L_ROP field are used for terminal
device input, such as whether a prompt is to be displayed and whether
a time limit between characters is enforced. These options may require
certain information to be placed in other fields of the RAB (see Chapter 7).
The maximum buffer size is 512 bytes.

Using an item list to define the terminal input operation in conjunction
with a terminal XAB (XABTRM). The ETO option of the RAB$L_ROP
field must be set and the user must provide an item list in the calling
program, which VMS RMS passes to the terminal driver using the item
list address and length specified in the XABTRM (see Chapter 18). This
method allows use of any terminal input option supported by the terminal
driver, in contrast to the subset of RAB$L_ROP options available using
the other method. The maximum buffer size is 512 bytes.

VMS RMS uses the standard terminator set when performing input operations
from terminal devices. The second longword of the I/O status block used
is returned in the RAB$L_STV field. The terminating character is returned
in the lower word of the status value field (RAB$W_STVO); however, note
that with extended terminal operations, the terminating character is in the
first byte of RAB$W_STVO, not in the entire RAB$W_STVO word. More
information about the second longword of the I/O status block is available in
the VMS I/O User's Reference Manual: Part I in the VMS I/O User's Reference
Volume. The RAB$W_STVO field is device dependent for terminal devices.
The CTRL/Z character terminates the Get service and acts as an end-of-file
marker for VMS RMS. If you enter a CTRL/Z in response to a request for
data, VMS RMS returns the completion status code for end-of-file (RMS$_
EOF). VMS RMS takes the data you enter before the CTRL/Z but the next
Get service returns a single end-of-file error (RMS$_EOF) without accepting
any further input from the device. VMS RMS resumes taking input if you
request a subsequent Get service.
VMS RMS also supports the use of escape sequences from terminal devices
that are accessed locally and have escape sequences enabled. Escape
sequences for a terminal are enabled by the SET TERMINAL command
(described in the VMS DCL Dictionary). Escape sequences are returned in the
record buffer. The record size (RAB$W_RSZ) is the offset within the buffer
(RAB$L_RBF) to the beginning of the escape sequence. The high-order word
of the status value field (RAB$W_STV2) contains the length of the escape
sequence, except for extended terminal operations. In this case, the escape
sequence length is returned in the first byte of RAB$W_STV2, not the entire
RAB$W_STV2 word, and the terminator position is returned in the second
byte of the RAB$W_STV2 word. When a partial escape sequence warning
(RMS$_PES) is returned, the remaining characters in the escape sequence are
returned by the next read request from the terminal.

RMS-49

VMS RMS Services
$GET

Input from Mailbox Devices

Mailboxes may be used to synchronize activity across cooperating processes.
Normally, a Get service from a mailbox device is not completed until a record
is present in the mailbox. When the Get service is completed, the status value
field (RAB$L _STV) contains the process identification (PID) of the process
that put the record into the mailbox. However, if the timeout (TMO) record
option is specified with a value of 0 in the timeout field and if no messages
are present in the mailbox, then the Get service returns an end-of-file error
(RMS$_EOF). This technique assures your process of an immediate return,
whether or not messages are present in the mailbox.
Using the RAB$L_STV Field

The RAB$L_STV field contains additional status information for a number of
situations. When the completion status is a record-too-big warning (RMS$_
RTB), RAB$L_STV contains the total record size. For record-oriented devices
such as terminals and mailboxes, the second longword of the I/O status
block is returned in the RAB$L_STV field, whenever the completion status
(RAB$L_STS) is a success code. The alternate field definitions of RAB$W_
STVO and RAB$W_STV2 are provided to reference the respective low- and
high-order words of the RAB$L_STV field. The record size field (RAB$W_
RSZ) always reports the amount of data returned, regardless of the completion
status (RAB$L_STS). The presence of valid data on error conditions may then
be detected by checking the record size field.
The User Record Area

The Get service always requires the presence of a user record area, as
specified by the user record buffer address (RAB$L_UBF) and user buffer
area size (RAB$W_USZ) fields in the RAB.
For undefined format files, the RAB$W_USZ field defines the amount of data
to be returned on each Get service.
Table RMS-26 lists the control block fields read as input by the Get service.
For additional information on the fields accessed by this service, see Part II.

RMS-50

Table RMS-26

Get Service RAB Input Fields

Field Name

Option or
XAB Type

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_KBF

Key buffer address: used only if the
RAB$B_RAC field contains RAB$C_KEY,
or if the RAB$B_RAC field contains
RAB$C_SEO and you select the RAB$V_
LIM option.

RAB$B_KRF

Key of reference: used only with indexed
files and only if the RAB$B_RAC field
contains RAB$C_KEY.

RAB$B_KSZ

Key buffer size: used only if the RAB$B_
RAC field contains RAB$C_KEY, or if the
RAB$B_RAC field contains RAB$C_SEQ
and you select the RAB$V_LIM option.

VMS RMS Services
$GET

Table RMS-26 (Cont.)

Option or
XAB Type

Field Name
RAB$L_PBF

Get Service RAB Input Fields

Description
Prompt buffer address (applies to
terminal devices only).

RAB$B_PSZ 1

Prompt buffer size (applies to terminal
devices only).

RAB$B_RAC

Record access mode (RAB$C_SEQ,
RAB$C_KEY RAB$C_RFA). 2

RAB$W_RFA

Record file address: used only if the
RAB$B_RAC field contains RAB$C_RF A.

RAB$L_RHB

Record header buffer: used for the
fixed-length control area of VFC records.

RAB$L_ROP

Record-processing options.

RAB$V_ASY

Asynchronous: performs Get services
asynchronously.

RAB$V_CVT 1

Convert: changes characters to
uppercase for a Get service to a terminal
device.

RAB$V_ET0 1

Extended terminal operation: specifies
that an XABTRM and an item list
are used to define the terminal input
operation. If this option is specified, no
other RAB$L_ROP options applicable to
terminal devices can be used.

RAB$V_KGE 3

Search for equal key value or next key
value according to sort order (applies
only to indexed files).

RAB$V_KGT 4

Search for next key value according to
sort order; if neither the RAB$V_KGE
(RAB$V_EQNXT) option nor the RAB$V_
KGT (RAB$V_NXT) option is specified,
VMS RMS looks for a key match.

RAB$V_LIM

Limit: specifies that the key value
described by the RAB$L _KBF field and
the RAB$B_KSZ field is to be compared
with the value in the record accessed
sequentially.

RAB$V_LOC 1

Locate mode: specifies that Get service
record operations use locate mode.

RAB$V_NLK

No lock: specifies that the record
accessed through the Get service is
not to be locked.

1 This field is not supported for DECnet operations.
2 The default for the

RAB$B_RAC field is RAB$C_SEO.

3 This symbolic offset is logically synonymous with RAB$V_EQNXT.
4 This symbolic offset is logically synonymous with RAB$V_NXT.

RMS-51

VMS RMS Services
$GET

Table RMS-26 (Cont.)
Field Name

Get Service RAB Input Fields

Option or
XAB Type

Description

RAB$V_NXR

Nonexistent record processing: specifies
that if the record directly accessed
through a Get service does not exist, the
service is to be performed anyway.

RAB$V_PMT 1

Prompt: indicates that the contents of
the prompt buffer are to be used as a
prompt on a Get service to a terminal
device.

RAB$V_PTA 1

Purge type-ahead: eliminates any
information that may be in the typeahead buffer, on a Get service to a
terminal device.

RAB$V_RAH 1

Read ahead: used with multiple buffers
to indicate read-ahead operations
(sequential files only).

RAB$V_REA

Lock for read: allows other users read
access to the record.

RAB$V_RLK

Read of locked record allowed: specifies
that a user who locks a record for
modification is allowing the locked record
to be read by other accessors.

RAB$V_RNE 1

Read no echo indicates that input data
entered on the keyboard is not echoed
(displayed) on the terminal device.

RAB$V_RNF 1

Read no filter: indicates that CTRL/U,
CTRL/R, and DELETE are not to be
considered control commands on
terminal input, but are to be passed
to the application program.

RAB$V_RRL

Read regardless of lock: read the record
even if another stream has locked the
record.

RAB$V_TM0 1

Timeout: indicates that the content of
the timeout period field (RAB$B_TMO) is
to be used.

RAB$V_ULK

Manual unlocking: specifies that records
cannot be automatically unlocked.

RAB$V_WAT

Wait: if record is locked, wait until it is
available.

1 This field is not supported for DECnet operations.

RMS-52

VMS RMS Services
$GET

Table RMS-26 (Cont.)

Option or
XAB Type

Field Name
RAB$B_TM0

Get Service RAB Input Fields

Description
Timeout period: indicates the maximum
number of seconds that VMS RMS
allows between characters for a Get
service to terminal and mailbox devices
only, or the maximum number of seconds
VMS RMS waits for a locked record
if you specify the RAB$V_TMO and
RAB$V_WAT options in the RAB$L_
ROP field.

RAB$L_UBF

User record buffer address (required).

RAB$W_USZ

User record buffer size (required).
XABTRM 1

RAB$L_XAB

Next XAB address: indicates the address
of an XABTRM control block (the
RAB$L _ROP field RAB$V_ETO option
must be set for an extended terminal
operation).

1 This field is not supported for DECnet operations.

Table RMS-27 lists the control block fields written as output by the Get
service.
Table RMS-27

RETURN
VALUES

Get Service RAB Output Fields

Field Name

Description

RAB$L_BKT

Bucket code: set to the relative record number for relative files
when the record access mode is sequential.

RAB$L_RBF

Record buffer address.

RAB$W_RFA

Record file address.

RAB$W_RSZ

Record size.

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value (contains a terminator character for terminal input
or the record length if the requested record is too large for the
user buffer area).

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ANI

RMS$_BES

RMS$_BLN

RMS$_BUG

RMS$_BUG_DAP

RMS$_CDA

RMS$_CHK

RMS$_CONTROLC

RMS$_CONTROL Y

RMS$_DEADLOCK

RMS$_DEL

RMS$_DME

RMS$_DNR

RMS$_EOF

RMS$_ENQ

RMS$_EXENOLM

RMS$_EXP

RMS-53

VMS RMS Services
$GET

RMS-54

RMS$_FAC

RMS$_FTM

RMS$_10P

RMS$_1RC

RMS$_1SI

RMS$_KBF

RMS$_KEY

RMS$_KRF

RMS$_KSZ

RMS$_MRN

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_QK_ALK

RMS$_IBF

RMS$_QK_DEL

RMS$_QK_LIM

RMS$_QK_RLK

RMS$_QK_RNF

RMS$_QK_RRL

RMS$_QK_WAT

RMS$_PBF

RMS$_PENDING

RMS$_PES

RMS$_PLG

RMS$_RAB

RMS$_RAC

RMS$_RER

RMS$_RFA

RMS$_RHB

RMS$_RLK

RMS$_RNF

RMS$_RQP

RMS$_RPL

RMS$_RRV

RMS$_RSA

RMS$_RTB

RMS$_SQO

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_TMO

RMS$_TNS

RMS$_TRE

RMS$_UBF

RMS$_WBE

RMS$_WER

RMS$_WLK

RMS$_XAB

VMS RMS Services
$NXTVOL

$NXTVOL
The Next Volume service allows you to process the next tape volume in
a multiple volume set. This service applies only to files on magnetic tape
volumes.

FORMAT

SYS$NXTVOL

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]]

cond_value
longword {unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L _STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword {unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Next Volume service call. The rab argument is the address of the RAB
control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-55

VMS RMS Services
$NXTVOL

DESCRIPTION

You use the Next Volume service when you want to proceed to the next
volume in the set before the end of the current volume (EOV label) is reached
on input, or before the end-of-tape (EOT) mark is reached on output. VMS
RMS positions your process to the first file section on the next volume. File
sections occur when a file is written on more than one volume, the portion of
the file on each of the volumes constituting a file section.
When you perform a Next Volume service for input files, VMS RMS responds
as follows.
•

If the current volume is the last volume of the set, VMS RMS reports

end-of-file information.
•

If another file section exists, the next volume is mounted. When

necessary, the current volume is rewound and a request to mount the
next volume is issued to the operator.
•

The header label (HDRl) of the file section on the newly mounted volume
is read. If this is not the volume being sought, the operator is requested
to mount the correct volume.

When you perform a Next Volume service for output files, the following
sequence occurs:
1

The file section on the current volume is closed with the appropriate
end-of-volume labels, and the volume is rewound.

The next volume is mounted.

A file with the same file name and the next higher file section number is
opened for output, and processing continues.

If your program is operating asynchronously, it must wait for any I/O activity

on this volume to complete before issuing a Next Volume service.
The Next Volume service performs a Flush service for write-accessed volumes
(see $FLUSH), thus writing the I/O buffers on the current volume before
creating the next file section. If this is an input-only file, then all records
currently contained in the I/O buffers are lost, and the next Get service
returns the first record on the next volume.
The Next Volume service is not supported for DECnet operations for remote
file access between two VMS systems.
Table RMS-28 lists the control block fields read as input and written as
output by the Next Volume service. For additional information on the fields
accessed by this service, see Part II.

RMS-56

VMS RMS Services
$NXTVOL

Table RMS-28
Use

Field Name

Description

Input

RAB$W_ISI

Internal stream identifier (required).

RAB$L _RQP

Record-processing option, RAB$V_ASY.
Asynchronous only: performs Next Volume service
asynchronously.

RAB$L _STS

Completion status code (also returned in
register 0).

RAB$L_STV

Status value.

Output

RETURN
VALUES

Next Volume Service RAB Input and Output Fields

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_BLN

RMS$_CDA

RMS$_DME

RMS$_DNR

RMS$_DPE

RMS$_10P

RMS$_1SI

RMS$_NQRMAL

RMS$_PENDING

RMS$_RAB

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS-57

VMS RMS Services
$OPEN

$OPEN
The Open service makes an existing file available for processing by your
program. The Open service specifies the type of record access to be used
and determines whether or not the file can be shared. The Open service
also performs an implicit Display service.

FORMAT

SYS$0PEN

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err} [,sue]}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Open service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-58

VMS RMS Services
$OPEN

DESCRIPTION

You must open a file to perform any record operations and most file
operations. If any XABs are chained to the FAB, VMS RMS places the
attribute values in the fields of the appropriate XAB. If you specify a NAM
block in the FAB, the contents of the device, directory, and file identification
fields can be used with the open-by-NAM-block option to open the file. The
NAM block fields are filled in with auxiliary file specification information.
Table RMS-29 lists the control block fields read as input by the Open service.
For additional information on the fields accessed by this service, see Part II.

Table RMS-29

Open Service FAB and XAB Input Fields
Option or
XAB type

Field Name

Description

FAB$V_CHAN _MODE 3

Channel access mode assignment.

FAB$W_DEQ

Default file extension quantity: if
a nonzero value is present in this
field, it applies only to this open of
the file.

FAB$L_DNA

Default file specification string
address.

FAB$B_DNS

Default file specification string size.

FAB$B_FAC

File access field.
FAB$V_BIO

Block 1/0 access.

FAB$V_BRO

Block or record 1/0.

FAB$V_DEL

Delete access.

FAB$V_GET 1

Read access.

FAB$V_PUT

Write access.

FAB$V_TRN

Truncate access.

FAB$V_UPD

Update access.

FAB$L_FNA 2
FAB$B_FNS

File specification string address.

File specification string size.

FAB$L_FOP

File-processing options.
FAB$V_DFW 3

Deferred write: indicates that
writing back to the file from the
modified buffer is deferred (applies
to relative and indexed files only).

FAB$V_DLT

Delete: indicates the file is to be
deleted when it is closed.

FAB$V_NAM 3

Name block inputs: indicates that
the NAM$W_FID, NAM$W_DID,
and NAM$T_DVI fields in the
specified NAM block are to be
used to describe the file.

1This is the default value supplied by VMS RMS.

2 These fields must be specified by the user.

3 This field is not supported for DECnet operations.

RMS-59

VMS RMS Services
$OPEN

Table RMS-29 (Cont.)
Field Name

Open Service FAB and XAB Input Fields
Option or
XAB type
FAB$V_NFS 3

Non-file-structured: indicates that
the accessed volume is to be
processed in a non-file-structured
manner.

FAB$V_QFP

Output file parse: specifies that
the related file resultant file
specification string, if used, is
to provide file name and file type
defaults only.

FAB$V_RCK

Read-check: indicates that transfers
from disk are to be checked by a
followup, read-compare operation.

FAB$V_RWC

Rewind on close (applies to
magnetic tapes only).

FAB$V_RWO

Rewind on open (applies to
magnetic tapes only).

FAB$V_SCF 3

Submit command file: indicates
that the file is to be submitted as a
batch-command file to the process
default batch queue (SYS$BA TCH)
when the file is closed (applies to
sequential files only).

FAB$V_SPL3

Spool: indicates that the file is to
be spooled to the process default
print queue (SYS$PRINT) when the
file is closed (applies to sequential
files only).

FAB$V_SQO

Sequential only: indicates that
the file can be processed in a
sequential manner only.

FAB$V_TEF

Truncate at end of file: indicates
that unused space allocated to a
file is to be deallocated when that
file is closed (applies to sequential
files only).

FAB$V_UF0 3

User file open: indicates the file
is to be opened only (no further
VMS RMS processing of that file is
allowed).

FAB$V_WCK

Write-check: indicates that
transfers to disk are to be followed
by a read-compare operation.

FAB$8_FSZ

Fixed control area size: unit record
devices only.

FA8$W_IFI

Internal file identifier (must be 0).

3 This field is not supported for DECnet operations.

RMS-60

Description

VMS RMS Services
$OPEN

Table RMS-29 (Cont.)

Open Service FAB and XAB Input Fields
Option or
XAB type

Field Name
FA8$V_LNM_MODE

Description

Specifies the logical name
translation access mode.

FA8$L_NAM

Name block address.

FAB$8_RAT

Record attributes; only for process
permanent files with print file
format.

FAB$B_RFM

Record format; unit record devices
only.

FAB$B_RTV 3

Retrieval window size.

FAB$8_SHR

File-sharing field.
FAB$V_SHRDEL

Shared delete access.

FA8$V_SHRGET

Shared read access.

FAB$V_MSE

Multistream access; also used with
the FAB$V_MSE and FAB$V_GET
bits to specify a read-only global
buffer cache when global buffering
is enabled.

FAB$V_NIL

No shared access.

FAB$V_SHRPUT

Shared write access.

FAB$V_SHRUPD

Shared update access.

FAB$V_UPI

Shared write access for block 1/0
(applies to sequential files only).

FAB$L_XAB 4

Extended attribute block address.
Item list XAB; see Chapter 11.

XABITM
3 This field is not supported for DECnet operations.

4 The appropriate XAB must be specified as input if you desire information about that

particular XAB on output from the Open Service.

Table RMS-30 lists the control block fields written as output by the Open
service.

Table RMS-30

Open Service FAB and XAB Output Fields

Field Name

Option or
XAB Type

Description

FA8$L_ALQ

Allocation quantity: contains the highest
numbered block allocated to the file.

FAB$B_BKS

Bucket size (does not apply to sequential
files).

FAB$W_BLS

Device block size (applies only to sequential
files).

FAB$W_DEO

Default file extension quantity.

RMS-61

VMS RMS Services
$OPEN

Table RMS-30 (Cont.)
Field Name

Open Service FAB and XAB Output Fields

Option or
XAB Type

FAB$L_DEV

Device characteristics.

FAB$B_FAC

File access.

FAB$L_FOP

File-processing options.
FAB$V_CBT

Contiguous best try: indicates that the file
is allocated contiguously on a "best effort"
basis.

FAB$V_CTG

Contiguous: indicates that space for the file
is allocated contiguously.

FAB$V_RCK

Read-check: transfers are followed up by a
read-compare operation.

FAB$V_WCK

Write-check: transfers are followed up by a
read-compare operation.

FAB$B_FSZ

Fixed-length control area size (applies only to
VFC records).

FAB$W_GBC

Global buffer count.

FAB$W_IFI

Internal file identifier.

FAB$L_MRN

Maximum record number (for relative files
only).

FAB$W_MRS

Maximum record size.

FAB$8_QRG

File organization.

FAB$B_RAT

Record attributes; used as output field except
for process-permanent files with print file
format.

FAB$8_RFM

Record format.

FAB$L_SDC

Spooling device characteristics.

FAB$B_SHR

File sharing.

FAB$L_STS

Completion status code (also returned in
register 0).

FAB$L_STV

Status value (contains the 1/0 channel
number if the operation is successful).

FAB$L_XAB

Next XAB address.
XABALL

RMS-62

Description

Allocation XAB; see Chapter 8.

XABDAT

Date and time XAB; see Chapter 9.

XABFHC

File header characteristics XAB; see
Chapter 10.

XABITM

Item list XAB; see Chapter 11.

XABKEY

Key definition XAB; see Chapter 13.

XABPRO

Protection XAB; see Chapter 14.

XABRDT

Revision date and time XAB; see Chapter 15.

XABSUM

Summary XAB; see Chapter 17.

VMS RMS Services
$OPEN

Using the Name Block for Opening Files
Table RMS-31 and Table RMS-32 list the NAM block fields (further described
in Chapter 6) used as input and output for the Open service (provided that
the NAM block address field is specified in the FAB).
Table RMS-31

Open Service NAM Block Input Fields

Field Name

Option

Description

NAM$W_DID 1

Directory identification (input only if
the FAB$L _FQP field FAB$V_NAM
option is set).

NAM$T_DV1 1

Device identification (input only if
the FAB$L_FQP field FAB$V_NAM
option is set).

NAM$L_ESA

Expanded string area address.

NAM$8_ESS
NAM$W_FID

Expanded string area size.
1

File identification (input only if the
FAB$L_FOP field FAB$V_NAM
option is set).

NAM$B_NOP

NAM block options.
NAM$V_PWD

Password: indicates that a password
contained in a DECnet access
control string, if present in a file
specification, is to be left unaltered
in the expanded and resultant strings
(instead of being replaced by the
word "password").

NAM$V_NOCONCEAL

Do not conceal device name:
indicates that when a concealed
device logical name is present, the
concealed device logical name is to
be replaced by the actual physical
device name in the resultant string.

NAM$L_RLF

Related file NAM block address.
NAM$B_RSL

Related file NAM block resultant
string length.

NAM$L_RSA

Related file NAM block resultant
string address.

NAM$L _FNB

Related file NAM block file name
status bits.

NAM$L_RSA

Resultant string area address.

NAM$B_RSS

Resultant string area size.

1 This field is not supported for DECnet operations.

RMS-63

VMS RMS Services
$OPEN

Table RMS-32

Open Service NAM Block Output Fields

Field Name

Description

NAM$W_DID 1
NAM$T_DVl

Directory identification.
Device identification.

NAM$B_ESL

Expanded string length. If the NAM$L_ESA and NAM$B_ESS
fields are nonzero, and if the FAB$L_FOP field FAB$V_NAM
option is clear or the NAM$W _DID and NAM$W_FID fields
are 0 on input, the expanded file specification string is copied
to the buffer specified by the NAM$L_ESA field.

NAM$W_FID 1

File identification.

NAM$L_FNB

File name status bits.

NAM$B_RSL

Resultant string length. If the NAM$L_RSA field and the
NAM$B_RSS field are nonzero, and if the FAB$V_NAM bit is
clear or the NAM$W _FID field is zero when you invoke the
Open service, the resultant file specification is copied to the
buffer specified by the NAM$L_RSA field.

1This field is not supported for DECnet operations.

The NAM block file specification string descriptors can be used to identify
individual components of the expanded or resultant file specification. These
fields include the following:
•

NAM$B_NQDE and NAM$L_NQDE

•

NAM$B_DEV and NAM$L_DEV

•

NAM$B_DIR and NAM$L _DIR

•

NAM$B_NAME and NAM$L_NAME

•

NAM$B_TYPE and NAM$L_TYPE

•

NAM$B_VER and NAM$L_VER

For additional information about these descriptors, see Chapter 6.

RETURN
VALUES

RMS-64

The following condition values are described in Appendix A:
RMS$_ACC

RMS$_ACS

RMS$_ACT

RMS$_AID

RMS$_ATR

RMS$_BLN

RMS$_BUG_DAP

RMS$_BUG_DDI

RMS$_CHN

RMS$_COD

RMS$_CRMP

RMS$_DEV

RMS$_DIR

RMS$_DME

RMS$_DNA

RMS$_DNF

RMS$_DNR

RMS$_DVI

RMS$_ENO

RMS$_ENV

RMS$_ESA

RMS$_ESS

RMS$_EXP

RMS$_FAB

RMS$_FLK

RMS$_FNA

RMS$_FNF

RMS$_FNM

RMS$_FQP

RMS$_IFA

VMS RMS Services
$OPEN

RMS$_1FI

RMS$_1MX

RMS$_1RC

RMS$_KNM

RMS$_KSI

RMS$_LNE

RMS$_NAM

RMS$_NET

RMS$_NETFAIL

RMS$_NOD

RMS$_NORMAL

RMS$_QK_NOP

RMS$_QRG

RMS$_PLG

RMS$_PLV

RMS$_PRV

RMS$_QUO

RMS$_RAT

RMS$_REF

RMS$_RLF

RMS$_RPL

RMS$_RSS

RMS$_RST

RMS$_RUNDOWN

RMS$_SHR

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPERSEDE

RMS$_SUPPORT

RMS$_SYN

RMS$_SYS

RMS$_TYP

RMS$_UPI

RMS$_ VER

RMS$_WLK

RMS$_XAB

RMS-65

VMS RMS Services
$PARSE

$PARSE
The Parse service analyzes the file specification string and fills in various
NAM block fields.

FORMAT

SYS$PARSE

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,[err] [,sue]}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Parse service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-66

VMS RMS Services
SPARSE

DESCRIPTION

The functions of the Parse service are performed automatically as part of the
Open, Create, and Erase services. One special purpose of the Parse service is
to prepare the FAB and NAM blocks for wildcard character processing to be
used in the Search service. If wildcard characters, search list logical names,
or a node name are present in the file specification, VMS RMS allocates
internal data structures (including a device channel) to store the context
for subsequent searches. This space is released when the Search service
encounters a no-more-files condition (in which case an RMS$_NMF error
status is returned) or when another Parse service is performed using the same
FAB and NAM blocks. To release this space, use a Parse service that specifies
the NAM$B_NOP field NAM$V_SYNCHK option and sets the FAB$B_DNS
and NAM$L_RLF fields to zero.
Note that the file must be closed before you invoke the Parse service
(FAB$W_IFI must be 0).
By default, the Parse service assigns a channel to the device and does a
lookup of the directory in addition to analyzing the file specification and
filling in the NAM block fields. To request a Parse service without 1/0,
specify the NAM$B_NOP field NAM$V_SYNCHK option. The result of
a Parse service without 1/0 cannot be used as input to subsequent Search
services.
Table RMS-33 and Table RMS-34 list the fields in both the FAB and NAM
block that the Parse service uses as input and output. In addition, the string
component descriptors are filled in by VMS RMS as output from the expanded
string (see Chapter 6).
The expanded file specification string is moved to the buffer described by
the expanded string area address (NAM$L_ESA) and size (NAM$B_ESS)
fields of the NAM block (only if both fields are nonzero). The NAM$L_ESA
and NAM$B_ESS fields must be specified (nonzero) for wildcard character
processing.
Table RMS-33 lists the control block fields read as input by the Parse service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-33
Field Name

Parse Service FAB and NAM Block Input Fields
Option

Description

FAB$L_DNA

Default file specification string.

FAB$B_DNS

Default file specification string size.

FAB$L_FNA

File specification string address.

FAB$B_FNS

File specification string size.

FAB$L_FOP

File-processing option, FAB$V_OFP.
Output file parse: indicates that VMS
RMS uses only the file name and file
type fields of a related file resultant
string whose address is contained in
the NAM$L_RSA field.

FAB$W_IFI

Internal file identifier (must be zero).

FAB$L_NAM

Name block address.

NAM$L_ESA

Expanded string area address.

RMS-67

VMS RMS Services
$PARSE

Table RMS-33 (Cont.)
Field Name

Parse Service FAB and NAM Block Input
Fields

Option

Description

NAM$B_ESS

Expanded string area size.

NAM$B_NOP

NAM block options.
NAM$V_NOCONCEAL

NAM$V_PWD

NAM$V_SYNCHK

Performs Parse service with no 1/0.

NAM$L_RLF

Related file NAM block address.
NAM$L_RSA

Related file NAM block resultant string
area address.

NAM$B_RSL

Related file NAM block resultant string
length.

NAM$L_FNB

Related file NAM block file name
status bits.

Table RMS-34 lists the control block fields written as output by the Parse
service.
Table RMS-34

Parse Service FAB and NAM Block Output Fields

Field Name

Description

FAB$L_DEV

Device characteristics (unless you select the NAM$V_
SYNCHK option).

FAB$L_SDC

Secondary device characteristics (unless you select the
NAM$V_SYNCHK option).

FAB$L_STS

Completion status code (also returned in register 0).

FAB$L_STV

Status value.

NAM$B_DEV

Address of file specification device descriptor.

NAM$L_DEV
NAM$W_DID

Size of file specification device descriptor.
1

Directory identification (unless you select the NAM$V_
SYNCHK option).

NAM$B_DIR

Address of file specification directory descriptor.

NAM$L_DIR

Size of file specification directory descriptor.

1 This field is not supported for DECnet operations.

RMS-68

VMS RMS Services
$PARSE

Table RMS-34 (Cont.)

Parse Service FAB and NAM Block Output
Fields

Field Name

Description

NAM$T_DVl 1

Device identification (unless you select the NAM$V_
SYNCHK option).

NAM$8_ESL

Expanded string length.

NAM$W_FID

File identification (zeroed).

NAM$L_FNB

File name status bits: contains information about the
parse results.

NAM$8_NAME

Address of file specification name descriptor.

NAM$L_NAME

Size of file specification name descriptor.

NAM$8_NODE

Address of file specification node descriptor.

NAM$L_NODE

Size of file specification node descriptor.

NAM$8_RSL

Resultant string length (zeroed).

NAM$8_TYPE

Address of file specification type descriptor.

NAM$L_TYPE

Size of file specification type descriptor.

NAM$B_ VERSION

Address of file specification version descriptor.

NAM$L_VERSION

Size of file specification version descriptor.

NAM$L_WCC

Wildcard context.

1 This field is not supported for DECnet operations.

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_ACS

RMS$_8LN

RMS$_8UG_DDI

RMS$_CDA

RMS$_CHN

RMS$_DEV

RMS$_DIR

RMS$_DME

RMS$_DNA

RMS$_DNF

RMS$_DNR

RMS$_ESA

RMS$_ESS

RMS$_FAB

RMS$_FNA

RMS$_FNM

RMS$_1FI

RMS$_LNE

RMS$_NAM

RMS$_NOD

RMS$_NORMAL

RMS$_QUO

RMS$_RLF

RMS$_RUNDOWN

RMS$_STR

RMS$_SUC

RMS$_SYN

RMS$_TYP

RMS$_ VER

RMS$_WCC

RMS-69

VMS RMS Services
$PUT

$PUT
The Put service inserts a record into a file.

FORMAT

SYS$PUT

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err} [,sue]}
cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L _STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Put service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

DESCRIPTION

RMS-70

The Put service usually adds records to the logical end of a sequential file.
For relative files, it may add records to the logical end of the file or it may
insert new records in cells formerly occupied by deleted records. VMS RMS
directs the Put service where to insert the record using the contents of the
record's primary key field.

VMS RMS Services
$PUT

Inserting Records into Sequential Files

When using sequential record access mode to process sequential files, you
usually insert records at the end of the file only. The records to be inserted
cannot be larger than the maximum length that was specified when the file
was created.
You can use random access by relative record number mode and the update-if
record-processing option (RAB$V_UJF) to insert fixed-length records into a
sequential file residing on a disk device.
VMS RMS also provides for establishing the logical end of the file when two
or more processes are doing shared write operations. For example, assume
that processes A and Bare sharing a sequential file and each process is putting
data into the file. Process A puts a record at the end of the file and intends to
put another record at the new end-of-file location. However, before process A
can put the next record in the file, process B gains access to the file and puts
a record at the end of the file. In order to ensure that the next record from
process A does not overwrite the record just inserted by process B, VMS RMS
updates process A's write pointer to the new end-of-file position. That is, the
location immediately following the location of process B's record.
The truncate-on-put option (RAB$V_TPT) can be used with sequential files.
This option lets you add records at locations other than the logical end of
the file. When you add a record using the truncate-on-put option, the file is
automatically truncated, effectively deleting all data between the new record
(logical end of the file) and the physical end of the file. If you try to use this
option without having truncate access, VMS RMS rejects the operation and
issues a file access error (RMS$_FAC).
For stream format files, VMS RMS writes the contents of the user's buffer into
the file beginning at the current entry position. If the last byte in the buffer
is not a terminator, VMS RMS automatically adds the appropriate terminator.
For stream format, the terminator is CRLF (carriage return character followed
immediately by a line feed character).
Mailboxes may be used to synchronize activity between processes. Usually,
a Put service to a mailbox does not conclude until another accessor reads the
record. If you select the timeout option (RAB$V_TMO) and specify a timeout
period of 0, the Put service does not wait for another accessor to read the
record.
At the conclusion of the Put service, the RAB$L_STV field contains the
process identification (PID) of the process that read the record.
Inserting Records into Relative Files

When processing relative files, you can use either sequential or random access
by key mode. Records cannot be larger than the size specified at file creation
time, and the record's relative record number must not exceed the maximum
record number established for the file. Usually, if the target record cell for
a Put service contains a record, a record-already-exists error (RMS$_REX) is
returned as the completion status (RAB$L_STS). If you specify the update-if
(RAB$V_UIF) record option, VMS RMS overwrites the existing record instead
of returning an error message. If you try to use the update-if option but do
not have update access, VMS RMS rejects the operation and issues a file
access error (RMS$_FAC).

RMS-71

VMS RMS Services
$PUT

Inserting Records into Indexed Files

In an indexed file, you can use sequential access or random access by key
mode. When sequential access is used to insert records, the primary key
value of the record to be inserted must be consistent with the specified sort
order of the file. That is, the key must be greater than or equal to the primary
value of the previous record if ascending sort order is specified. If descending
sort order is specified, the key must be less than or equal to the primary key
value of the previous record.
The records cannot be larger than the size established when the file was
created if a maximum length was specified. Each record written must contain
a primary key, but the records do not have to contain alternate keys. If
alternate keys are partially or completely missing because of the record length
limitation, VMS RMS does not make an entry for the record in the associated
alternate index. Put services to an indexed file do not require a separate key
value or key of reference. By examining the contents of the primary key in
the record, VMS RMS determines where to insert the record.
When inserting a record into an indexed file, VMS RMS compares the key
values in the record with the key values of records previously inserted into
the file to determine whether or not the new record's key value duplicates
any existing key values. If the record duplicates a key value in an index
where duplication is not allowed, VMS RMS rejects the operation with an
RMS$_DUP error code. Where duplicate keys are allowed, VMS RMS inserts
the record.
Records with duplicate keys are inserted in chronological order; that is, VAX
RMS inserts each record having duplicate keys at the end of a "chain" of
identically keyed records so that newer records are stored closer to the end of
the file regardless of sort order.
If you specify the update-if (RAB$V_UIF) option when duplicates are not

allowed on the primary key, VMS RMS overwrites the existing record
with the same primary key value, rather than returning a duplicate record
error (RMS$_DUP). This gives the appearance of an Update service being
performed on the existing record. Alternate key values are modified to reflect
the newly inserted record.
To use the RAB$V_UIF option, you must have update access to the file. If
update access to the file is not permitted, the Put service (which becomes an
Update service when this option is selected) fails, and VMS RMS returns a
file access error (RMS$_FAC).
Be careful when invoking the PUT service with the RAB$V_UIF option and
automatic record locking for a shared file. The Put service, unlike the Update
service, momentarily releases record locks previously applied by a Get or
Find service, until the PUT service is converted into an Update service. This
could allow another record stream to delete or update the record between the
invocation of the Put service and the conversion to an Update service. To
avoid this complication, you should use the Update service instead of the Put
service with the update-if option to update an existing record in a file-sharing
situation.
The record address field (RAB$L_RBF) and the record size field (RAB$W_
RSZ) are required inputs to the Put service, and some Put service options
require additional fields.
A successful Put service returns the record file address (RFA) in the RAB$W_
RFA field.

RMS-72

VMS RMS Services
$PUT

Table RMS-35 lists the control block fields read as input by the Put service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-35

Put Service RAB Input Fields

Field Name

Option or
XAB Type

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_KBF

Key buffer address (used as input only with
random access by relative record number
mode).

RAB$8_KSZ

Key size (used only if RAB$8_RAC is KEY
and the file is a relative file).

RAB$8_RAC

Record access mode (SEO, KEY) 1 .

RAB$L_RBF

Record buffer address.

RAB$L_RHB

Record header buffer (applies only to
variable with fixed control records).

RAB$W_RSZ

Record size.

RAB$L_ROP

Record-processing options.

RAB$V_ASY

Asynchronous: performs Put services
asynchronously.

RAB$V_CC0 2

Cancel CTRL/O: guarantees that terminal
output is not discarded if the operator
enters CTRL/O.

RAB$V_LQA

Load: specifies that buckets are to be
loaded according to the fill size established
at file creation time.

RAB$V_REA 3

Lock for read: allows other users read
access to the record. This is not valid for
relative files.

RAB$V_RLK3

Read of locked record allowed: specifies
that a user who locks a record for
modification is allowing the locked record
to be read by other accessors.

RAB$V_TM0 2

Timeout: indicates that the content of the
timeout period field (RAB$8_TMO) is to be
used.

RAB$V_TPT

Truncate-on-put: specifies that a Put
service with a record accessed sequentially
can occur at any point in the file, truncating
the file at that point.

RAB$V_UIF

Update-if: converts a Put service to a
record that already exists to an Update
service.

The default for the RAB$B_RAC field is RAB$C_SEQ.

2 This field is not supported for DECnet operations.

3 This option is meaningless unless you specify manual unlocking.

RMS-73

VMS RMS Services
$PUT

Table RMS-35 (Cont.)

Put Service RAB Input Fields

Option or
XAB Type

Field Name

Description

RAB$V_ULK

Manual unlocking: specifies that records
cannot be automatically unlocked.

RAB$V_WBH

Write behind: two buffers are allocated to
allow multibuffering.

RAB$V_WAT

Wait: if record is locked, wait until it is
available (applies to relative files).

RAB$B_TM0 1

Timeout period: a value of zero indicates
that VMS RMS should not wait to complete
a Put service (applies to mailbox devices
only).

1 The default for the RAB$B_RAC field

is RAB$C_SEQ.

Table RMS-36 lists the control block fields written as output by the Put
service.
Table RMS-36
Field Name

Put Service RAB Output Fields
Option or
XAB Type

RAB$L_BKT

Description
Bucket code: set to the relative record number
for sequential access to relative files.

RAB$W_RFA

Record file address.

RAB$L_STS

Completion status code (also returned in
register 0).

RAB$L_STV

Status value 1 .

1 On the successful completion of a Put service to a record-oriented device, the RAB$L_
STV field contains the second longword of the 1/0 status block. See the VMS 1/0 User's
Reference Manual: Part I in the VMS 1/0 User's Reference Volume for details on specific
devices.

RETURN
VALUES

RMS-74

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_BLN

RMS$_BUG

RMS$_BUG_DAP

RMS$_CDA

RMS$_CHK

RMS$_CONTROLC

RMS$_CONTROLO

RMS$_CONTROL Y

RMS$_DME

RMS$_DNR

RMS$_DUP

RMS$_ENQ

RMS$_EXT

RMS$_FAC

RMS$_FTM

RMS$_FUL

RMS$_1BF

RMS$_1DX

RMS$_10P

RMS$_1RC

RMS$_1SI

RMS$_KBF

RMS$_KEY

VMS RMS Services
$PUT

RMS$_KSZ

RMS$_MRN

RMS$_NEF

RMS$_NET

RMS$_NETF AIL

RMS$_NQRMAL

RMS$_QK_ALK

RMS$_QK_DUP

RMS$_0K_IDX

RMS$_PENDING

RMS$_PLG

RMS$_RAB

RMS$_RAC

RMS$_RBF

RMS$_RER

RMS$_REX

RMS$_RHB

RMS$_RLK

RMS$_RPL

RMS$_RRV

RMS$_RSA

RMS$_RSZ

RMS$_RVU

RMS$_SEO

RMS$_SQO

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_TRE

RMS$_WBE

RMS$_WER

RMS$_WLK

RMS$_WPL

RMS-75

VMS RMS Services
$READ

$READ
The Read service retrieves a specified number of bytes from a file
(beginning on a block boundary) and transfers them to memory. A Read
service using block 1/0 can be performed on any file organization.

FORMAT

SYS$READ

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sucJJ

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rah
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Read service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-76

VMS RMS Services
$READ

DESCRIPTION

To use the Read service, you must do the following:
1

Supply a buffer area into which VMS RMS is to transfer data (user record
area address field, RAB$L_UBF).

Indicate the number of bytes to be transferred (user record area size field,
RAB$W_USZ).

Indicate the first virtual block number (VBN) for the transfer (bucket
number field, RAB$L_BKT}. If the value for the VBN is 0, the transfer
starts with the block indicated by the NBP (Next Block Pointer).

Table RMS-37 lists the control block fields read as input by the Read service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-37

Read Service RAB Input Fields

Field Name

Description

RAB$L_BKT

Bucket number: must contain the virtual block number of the
first block to read. When this field has a value of 0, then the
next block is read.

RAB$W_ISI

Internal stream identifier.

RAB$L_ROP

Record-processing option, ASY (RAB$V_ASY). Asynchronous:
performs Read services asynchronously.

RAB$L_UBF

User record buffer address. For block 1/0, alignment of the
user's record buffer on a page or at least a quadword boundary
may improve performance.

RAB$W_usz

User record area size: indicates the length of the transfer, in
bytes 1 .

1 Certain devices require that an even number of bytes be transferred. For further details,
see the VMS 1/0 User's Reference Manual: Part I in the VMS 1/0 User's Reference
Volume.

Table RMS-38 lists the control block fields written as output by the Read
service.
Table RMS-38
Field Name

Read Service RAB Output Fields
Description

RAB$L_RBF

Record address.

RAB$W_RFA

Record file address.

RAB$W_RSZ

Record size: indicates the actual number of bytes transferred.

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

RMS-77

VMS RMS Services
$READ

RETURN
VALUES

RMS-78

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_CONTROLC

RMS$_CONTROL Y

RMS$_DME

RMS$_DNR

RMS$_EOF

RMS$_FAC

RMS$_FTM

RMS$_1QP

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_
NORMAL

RMS$_PBF

RMS$_PENDING

RMS$_RAB

RMS$_RER

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_TMO

RMS$_UBF

RMS$_USZ

RMS$_WBE

VMS RMS Services
$RELEASE

$RELEASE
The Release service unlocks the record specified by the contents of the
record file address (RAB$W_RFA) field of the RAB.

FORMAT

SYS$RELEASE

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L _STS.
Symbolic offset RAB$L _STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Release service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-79

VMS RMS Services
$RELEASE

DESCRIPTION

The Release service unlocks a specified record (see also the discussion of the
Free service). If the named record is not locked, VMS RMS returns a status
code of RMS$_RNL.
Table RMS-39 lists the control block fields read as input and written as
output by the Release service. For additional information on the fields
accessed by this service, see Part II.
Table RMS-39

Input
Output

RETURN
VALUES

RMS-80

Release Service RAB Input and Output Fields

Field Name

Description

RAB$W _ISi

Internal stream identifier (required).

RAB$W_RFA

Record file address (required).

RAB$L _STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_8LN

RMS$_BUG_DAP

RMS$_CDA

RMS$_1SI

RMS$_NET

RMS$_NETF AIL

RMS$_NORMAL

RMS$_PENDING

RMS$_RAB

RMS$_RNL

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

VMS RMS Services
$REMOVE

$REMOVE
The Remove service deletes a file name from a directory. It is the reverse
of the Enter service.

FORMAT

SYS$REMOVE

RETURNS

VMS usage:
type:
access:
mechanism:

fab [,{err} {,sue}}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for
the Remove service call. The fab argument is the address of the FAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-81

VMS RMS Services
$REMOVE

DESCRIPTION

The Remove service searches for the first file name that matches the expanded
name string and directory ID in the user's NAM block, and then it deletes
the file name without deleting the actual file. The Remove service is similar
to the Erase service, except that the Erase service also deletes the file after
performing an implicit Remove. Note that you must close the file before
invoking the Remove service (that is, the value of FAB$W_IFI must be 0).
The Remove service accepts wildcard characters and search lists, and it
is usually preceded by a call to the Parse service in order to fill in the
appropriate fields of the NAM block. Because the Remove service returns
the wildcard context field of the NAM block (NAM$L_WCC), the Remove
service can be used on multiple successive calls in order to remove successive
file names that match a wildcard file specification.
Be careful when you mix calls to the Search and Remove services. For
example, assume you invoke the following service sequence:
•

PARSE

•

REMOVE

•

REMOVE

VMS RMS responds by doing the following:
1

Searches for the first file specification that matches the expanded name
string

Searches for and removes the second file specification

Searches for the third file specification

Searches for and removes the fourth file specification

If you want to remove the directory entry of a file and you have that file's
ID, then you can improve the speed of the Remove service by specifying the
NAM bit in the FAB$L_FOP field. In order to do this properly, you must first
parse the name of the file specification (to clear the NAM$W_FID field), place
the correct FID in the NAM block, and then perform the Remove service.

The Remove service is not supported for DECnet operations for remote file
access between two VMS systems.
Table RMS-40 lists the control block fields read as input by the Remove
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-40

Remove Service FAB and NAM Block Input Fields

Field Name

Description

FAB$L_FQP 1

File-processing option, FAB$V_NAM only. NAM block inputs:
indicates that the NAM$W_FID field is used as input.

FAB$W_IFI

Internal file identifier (must be zero).

1This field is not supported for DECnet operations.

RMS-82

VMS RMS Services
$REMOVE

Table RMS-40 (Cont.)
Field Name

Remove Service FAB and NAM Block Input
Fields

Description

FAB$L_NAM

Name block address.

NAM$W_DID

Directory identification; identifies the directory from which the
file is to be removed.

NAM$T_DVl 1

Device identification; identifies the device containing the
directory from which the file is to be removed.

NAM$L_ESA

Expanded string area address specifying the name, type, and
version of the file to be removed.

NAM$B_ESL
NAM$W_FID

Expanded string length.
1

File identification: if nonzero and FAB$L_FOP field FAB$V_
NAM bit is set in the input FAB, the first file in the directory
with this file identification is removed.

NAM$L_FNB

File name status bits (wildcard character bits only).

NAM$L_RSA

Resultant string area address: specifies the name, type, and
version number of the last file removed (required for wildcard
character processing).

NAM$B_RSL

Resultant string length.

NAM$B_RSS

Resultant string area size.

NAM$L_WCC

Wildcard character context value.

1 This field is not supported for DECnet operations.

Table RMS-41 lists the control block fields written as output by the Remove
service.
Table RMS-41

Remove Service FAB and NAM Block Output Fields

Field Name

Description

FAB$L _STS

Completion status code (also returned in register 0).

FAB$L_STV

Status value.

NAM$B_RSL

Resultant string length.

NAM$L_WCC

Wildcard context value.

The resultant string is moved to the buffer described by the NAM$L_RSA
and NAM$B_RSS fields (only if both fields are nonzero on input).

RMS-83

VMS RMS Services
$REMOVE

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_BLN

RMS$_CDA

RMS$_CHN

RMS$_DEV

RMS$_DME

RMS$_DNF

RMS$_DNR

RMS$_DVI

RMS$_ESA

RMS$_ESL

RMS$_FAB

RMS$_FNF

RMS$_1FI

RMS$_NAM

RMS$_NMF

RMS$_NORMAL

RMS$_PRV

RMS$_RMV

RMS$_RSL

RMS$_RSS

RMS$_RST

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WCC

RMS$_WLD

RMS$_WLK

RMS-84

VMS RMS Services
$RENAME

$RENAME
You can use this service to change the name, type, or version of a file, or
to move a file to another directory by changing its directory specification.
However, note that you cannot use this service to move a file to another
device.

FORMAT

SYS$RENAME

RETURNS

VMS usage:
type:
access:
mechanism:

old-fab ,{err] ,{sue} ,new-fab

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

old-fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Rename service call. The old-fab argument is the address of the FAB control
block that specifies the old file name.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-85

VMS RMS Services
$RENAME

new-fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

The new-fab argument is the address of the FAB control block that specifies
the new file name.

Note: If you invoke the Rename service using the $RENAME macro and if
you do not specify arguments, you must construct an additional field
within your argument list to contain the address of the FAB that specifies
the new file name. This additional field is placed in the argument list
following the field for the success completion routine (see Part I), and the
argument count is set to 4.

DESCRIPTION

The Rename service performs the equivalent of two Parse services (old and
new name), a Search service for the old directory, an Enter service to insert
the new file name into the new directory, and a Remove service to delete the
old file name from the old directory.
Note that you must close the file before invoking the Rename service
(FAB$W_IFI must be 0), and no wildcard character specifications are allowed.
You can move a file from one directory to another using this service, but both
directories must be on the same disk device.
If the Rename service is successful, the new directory entry is created and the
old entry is deleted. If the service fails, the old entry remains and the new
entry is deleted.

Table RMS-42 lists the fields in two FABs and two NAM blocks that the
Rename service uses as input and output. In the table, these blocks are called
FABl and NAMl for the old entry, and FAB2 and NAM2 for the new entry.
For output, FAB2 is not used, although it must be in writable memory. To
check or signal the completion codes in FAB$L_STS and FAB$L_STV, use
the first FAB (FABl).
The resultant file specification string for each of the names (old and new) is
placed in the buffer described by the NAM$L_RSA and NAM$B_RSS fields
of the separate NAM blocks (only if both fields are nonzero).
Table RMS-42 lists the control block fields read as input by the Rename
service. For additional information on the fields accessed by this service, see
Part II.

RMS-86

VMS RMS Services
$RENAME

Table RMS-42
Control Block
FAB1 and FAB2

NAM 1 and NAM2

Related file NAM
blocks

Rename Service FAB and NAM Block Input Fields
Field Name

Description

FAB$L_DNA

Default file specification string address.

FAB$B_DNS

Default file specification string size.

FAB$L_FNA

File specification string address.

FAB$B_FNS

File specification string size.

FAB$W_IFI

Internal file identifier (must be zero).

FAB$L_NAM

Name block address.

NAM$L_ESA

Expanded string area address
(must be nonzero).

NAM$B_ESS

Expanded string area size
(must be nonzero).

NAM$L_RLF

Related file NAM block address.

NAM$L_RSA

Resultant string area address.

NAM$B_RSS

Resultant string area size.

NAM$L_RSA

Related file resultant string area address.

NAM$B_RSL

Related file resultant string length.

NAM$L_FNB

Related file name status bits.

Table RMS-43 lists the control block fields written as output by the Rename
service.
Table RMS-43

Rename Service FAB and NAM Block Output Fields

Control Block

Field Name

Description

FAB1

FAB$L_STS

Completion status code (also
returned in register 0).

FAB$L_STV
NAM 1 and NAM2

Status value.

NAM$W_DID
NAM$T_DVl

NAM$B_ESL
NAM$W_FID

Directory identification.
Device identification.
Expanded string length.

File identification.

NAM$L_FNB

File name status bits.

NAM$B_RSL

Resultant string length.

NAM$L_WCC

Wildcard context.

1 This field is not supported for DECnet operations.

RMS-87

VMS RMS Services
$RENAME

RETURN
VALUES

RMS-88

The following condition values are described in Appendix A:
RMS$_ACC

RMS$_BLN

RMS$_BUG_DDI

RMS$_CDA

RMS$_CHN

RMS$_DEV

RMS$_DIR

RMS$_DME

RMS$_DNA

. RMS$_DNF

RMS$_DNR

RMS$_DVI

RMS$_ENT

RMS$_ESA

RMS$_ESS

RMS$_FAB

RMS$FNA

RMS$_FNM

RMS$_1DR

RMS$_1FI

RMS$_LNE

RMS$_NAM

RMS$_NET

RMS$_NETFAIL

RMS$_NMF

RMS$_NORMAL

RMS$_PRV

RMS$_QUO

RMS$_REENT

RMS$_RLF

RMS$_RMV

RMS$_RSS

RMS$_RST

RMS$_RUNDOWN

RMS$_STR

RMS$_SUC

RMS$_SUPPORT

RMS$_SYN

RMS$_SYS

RMS$_TYP

RMS$_ VER

RMS$_WLD

VMS RMS Services
$REWIND

$REWIND
The Rewind service sets the context of a record stream to the first record
in the file. VMS RMS alters the context of the next record to indicate the
first record as being the next record.

FORMAT

SYS$REWIND

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Rewind service call. The rah argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-89

VMS RMS Services
$REWIND

DESCRIPTION

The Rewind service implicitly performs the Flush and Free services, writing
out all 1/0 buffers and releasing all locked records. This service is valid for
all file organizations on disk volumes and for sequential files on tape volumes.
For indexed files, the key of reference field establishes the index to be used
for subsequent sequential accesses. You cannot rewind a unit record device,
such as a card reader, a mailbox, a printer, or a terminal. You cannot rewind
indirectly accessed process-permanent files. Also, you cannot rewind a file
that was opened with the FAB$L_FOP field FAB$V_SQO option set.
Table RMS-44 lists the control block fields read as input by the Rewind
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-44

Rewind Service RAB Input Fields

Field Name

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$B_KRF

Key of reference (used only with indexed files).

RAB$L_ROP

Record-processing option, RAB$V_ASY option only.
Asynchronous: performs a Rewind service asynchronously.

Table RMS-45 lists the control block fields written as output by the Rewind
service.
Table RMS-45

RETURN
VALUES

RMS-90

Rewind Service RAB Output Fields

Field Name

Description

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_BLN

RMS$_BOF

RMS$_BUG_DAP

RMS$_CDA

RMS$_DME

RMS$_DNR

RMS$_DPE

RMS$_10P

RMS$_1SI

RMS$_KRF

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_PENDING

RMS$_QUO

RMS$_RAB

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WBE

RMS$_WER

RMS$_WLK

VMS RMS Services
$SEARCH

$SEARCH
The Search service scans a directory file and fills in various NAM block
fields. This service should be preceded by the Parse service, in order to
initialize the NAM block appropriately.

FORMAT

SYS$SEARCH

RETURNS

VMS usage:
type:
access:
mechanism:

tab [,[err} [,sue}}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset FAB$L_STS.
Symbolic offset FAB$L_STV may contain additional status information.

ARGUMENTS

fab
VMS usage:
type:
access:
mechanism:

fab
longword (unsigned)
modify
by reference

FAB control block whose contents are to be used as indirect arguments for the
Search service call. The fab argument is the address of the FAB control block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage: ast_procedure
type:
procedure entry mask
acc~ss:
call without stack unwinding
mechanism: by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-91

VMS RMS Services
$SEARCH

DESCRIPTION

The basic functions of the Search service and the Parse service are performed
automatically as part of the Open, Create, and Erase services. Note that you
must close the file before invoking the Search service (FAB$W-1FI must be 0).
When called, the Search service scans the directory file specified by the
directory identification (NAM$W_DID) field of the NAM block. It looks for
an entry that matches the file name, type, and version number specified by
the expanded string area address and expanded string length fields. Upon
finding a match, VMS RMS returns the file name, type, and version number
in the buffer described by the resultant string area address and size fields.
VMS RMS also fills in the file identification field to enable a subsequent
open-by-NAM-block operation. You can also use the Search service to obtain
a series of file specifications whose names match a file specification that
contains wildcard characters or search lists.
The resultant file specification string is placed in the buffer described by
the resultant string area address (NAM$L_RSA) and size (NAM$B_RSS)
fields of the NAM block (only if both fields are nonzero). The NAM$L_RSA
and NAM$B_RSS fields must be specified (nonzero) for wildcard character
processing.
Table RMS-46 lists the control block fields read as input by the Search
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-46

Search Service FAB and NAM Block Input Fields

Field Name

Option

FAB$W_IFI

Internal file identifier (must be zero).

FAB$L_NAM
NAM$W_DID

Description

Name block address.
1

Directory identification of the
directory to be searched.

NAM$T_DVl 1

Device identification of device
containing directory to be searched.

NAM$L_ESA

Expanded string area address:
specifies file name, type, and version
of file.

NAM$8_ESL

Expanded string length.

NAM$L_FNB

File name status bits (wildcard
character options only).

NAM$8_NOP

NAM block options.
NAM$V_PWD

Password: indicates that a password
contained in a DECnet access
control string, if present in a file
specification, is to be left unaltered
in the expanded and resultant strings
(instead of being replaced by the
word "password").

1This field is not supported for DECnet operations.

RMS-92

VMS RMS Services
$SEARCH

Table RMS-46 (Cont.)
Field Name

Search Service FAB and NAM Block Input
Fields

Option

Description

NAM$V_NQCONCEAL

Do not conceal device name:
indicates that when a concealed
device logical name is present, the
concealed device logical name is to
be replaced by the actual physical
device name in the resultant string.

NAM$V_SRCHXABS

Performs Display service on
remote files (for output fields, see
description of Display service).

NAM$L_RSA

Resultant NAM block string area
address: specifies name, type, and
version of last file found (required for
wildcard character processing).

NAM$B_RSS

Resultant NAM block string area
size.

NAM$L_WCC

Wildcard character context value.

Table RMS-47 lists the control block fields written as output by the Search
service.
Table RMS-47

Search Service FAB and NAM Block Output Fields

Field Name

Description

FAB$L_STS

Completion status code (also returned in register 0).

FAB$L_STV

Status value.

NAM$B_DEV

Address of file specification device descriptor.

NAM$L_DEV

Size of file specification device descriptor.

NAM$B_DIR

Address of file specification directory descriptor.

NAM$L_DIR

Size of file specification directory descriptor.

NAM$W_FID 1

File identification.

NAM$L_FNB

File name status bits (wildcard status bits only).

NAM$B_NAME

Address of file specification name descriptor.

NAM$L_NAME

Size of file specification name descriptor.

NAM$B_NODE

Address of file specification node descriptor.

NAM$L_NODE

Size of file specification node descriptor.

NAM$B_RSL

Resultant string length.

NAM$B_TYPE

Address of file specification type descriptor.

NAM$L_TYPE

Size of file specification type descriptor.

NAM$8_ VERSION

Address of file specification version descriptor.

1 This field is not supported for DECnet operations.

RMS-93

VMS RMS Services
$SEARCH

Table RMS-47 (Cont.)

RETURN
VALUES

RMS-94

Search Service FAB and NAM Block Output
Fields

Field Name

Description

NAM$L_ VERSION

Size of file specification version descriptor.

NAM$L_WCC

Wildcard character context value.

The following condition values are described in Appendix A:
RMS$_ACS

RMS$_BLN

RMS$_CHN

RMS$_DEV

RMS$_DME

RMS$_DNF

RMS$_DNR

RMS$_DVI

RMS$_ESA

RMS$_ESL

RMS$_FAB

RMS$_FND

RMS$_FNF

RMS$_1FI

RMS$_NAM

RMS$_NET

RMS$_NETFAIL

RMS$_NMF

RMS$_NORMAL

RMS$_NQV ALPRS

RMS$_PRV

RMS$_RSL

RMS$_RSS

RMS$_RST

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WCC

VMS RMS Services
$SPACE

$SPACE
The Space service lets you space (skip) a tape file forward or backward a
specified number of blocks.

FORMAT

SYS$SPACE

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Space service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-95

VMS RMS Services
$SPACE

DESCRIPTION

The Space service is intended primarily for use with magnetic tape files; the
tape is skipped forward or backward the number of blocks specified in the
bucket number field. (The size of each block on any tape is specific to that
tape and is defined on the tape itself, not by VMS or VMS RMS.) If the value
in this field is positive, the tape skips forward; if the value is negative, the
tape skips backward. For disk files, the next block pointer (NBP) is updated
to reflect the new sequential operation position.
Table RMS-48 lists the control block fields read as input by the Space service.
For additional information on the fields accessed by this service, see Part II.

Table RMS-48

Space Service RAB Input Fields

Field Name

Description

RAB$L_BKT

Bucket code: indicates the number of blocks to space forward
(positive value) or backward (negative value).

RAB$W_ISI

Internal stream identifier.

RAB$L_ROP

Record-processing option, RAB$V_ASY only. Asynchronous:
performs Space services asynchronously.

Table RMS-49 lists the control block fields written as output by the Space
service.

Table RMS-49
Field Name

RETURN
VALUES

RMS-96

Space Service RAB Output Fields
Description

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value (the absolute number of blocks actually skipped;
the value is always positive).

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_BLN

RMS$_BQF

RMS$_BUG_DAP

RMS$_CDA

RMS$_DME

RMS$_DNR

RMS$_DPE

RMS$_EOF

RMS$_1QP

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_PENDING

RMS$_RAB

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WBE

VMS RMS Services
$TRUNCATE

$TRUNCATE
The Truncate service removes records from the end of a sequential file.

FORMAT

SYS$TRUNCATE

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err] [,sue]}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Truncate service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

DESCRIPTION

You can only truncate a sequential file that is open for exclusive access. The
file-sharing (FAB$B_SHR) field must be set or defaulted to NIL, and the file
access (FAB$B_FAC) field must specify a truncate access (FAB$V_TRN).

RMS-97

VMS RMS Services
$TRUNCATE
The Truncate service deletes the record indicated as the current record, and all
following records. You can only use this service immediately after successful
execution of a Get or Find service (thereby setting the context of the current
record).
VMS RMS declares the logical end of file to be the starting record position
for the truncation and then uses the end of file to establish the context of the
next record. You can then add records to the file by issuing successive Put
services.
Table RMS-50 lists the control block fields read as input by the Truncate
service. For additional information on the fields accessed by this service, see
Part IL
Table RMS-50

Truncate Service RAB Input Fields

Field Name

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_ROP

Record-processing option, RAB$V_ASY only. Asynchronous:
performs Truncate services asynchronously.

Table RMS-51 lists the control block fields written as output by the Truncate
service.
Table RMS-51

RETURN
VALUES

Field Name

Description

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_CUR

RMS$_DEADLOCK

RMS$_DME

RMS$_DNR

RMS$_DPE

RMS$_FAC

RMS$_10P

RMS$_1SI

RMS$_NET

RMS$_NETF AIL

RMS$_NORMAL

RMS$_PENDING

RMS$_RAB

RMS$_RER

RMS$_RSA

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_WBE

RMS$_WER

RMS$_WLK

RMS-98

Truncate Service RAB Output Fields

VMS RMS Services
$UPDATE

$UPDATE
The Update service allows you to modify the contents of an existing
record in a file residing on a disk device.

FORMAT

SYS$UPDATE

RETURNS

VMS usage:
type:
access:
mechanism:

rab [,[err} [,sue]}

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Update service call. The rab argument is the address of the RAB control
block.

err
VMS usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-99

VMS RMS Services
$UPDATE

DESCRIPTION

The record to be updated by the Update service must first be locked by this
stream, using either a Find or Get service. When updating a record, you must
use move mode (not locate mode); that is, you must supply a buffer.
The record length for sequential files cannot change. For relative files with
variable-length or variable with fixed-length control records, the length of the
replacement record can be different from the length of the original record, but
cannot be larger than the maximum size you set when you created the file.
For stream format files, the Update service functions in the same manner as
the Put service, with one exception. When using the Update service, you do
not have to set the RAB$L_ROP field RAB$V_TPT option to update data in
the middle of a file.
For indexed files, the length of the replacement record written by the Update
service may be different from the original record but RMS does not permit
you to change the primary key. Each replacement record must be large
enough to contain a complete primary key, but it does not have to contain all
alternate keys.
If an alternate key is partially or completely missing in the replacement

record, the key must have the characteristic that the values can change; this is
also true if the replacement record contains a key that was not present in the
original record.
Update operations to an indexed file do not require a key value or key of
reference. Before writing the record, VMS RMS compares the key values
(primary and alternate) in the replacement record with the key values of the
original record already existing in the file. This comparison takes the defined
characteristics of each key into account. For example, if a particular key is not
allowed to change, VMS RMS rejects the operation with an RMS$_CHG error
code if the replacement record contains an altered value in the associated key.
Similarly, this comparison determines whether the replacement record would
result in the presence of duplicate key values among records of the file. If
duplicates would occur, VMS RMS verifies the defined characteristics for the
keys being duplicated. If duplicates are not allowed for a particular key, VMS
RMS rejects the operation with an RMS$_DUP error code. If duplicates are
allowed, VMS RMS performs the operation.
Subsequent sequential operations on a given index retrieve records with
identical key values in the order in which the records were written.
Table RMS-52 lists the control block fields read as input by the Update
service. For additional information on the fields accessed by this service, see
Part II.
Table RMS-52
Field Name

RMS-100

Update Service RAB Input Fields
Option

Description

RAB$W_ISI

Internal stream identifier (required).

RAB$L_RBF

Record buffer address.

RAB$L_RHB

Record header buffer (applies only to variable
with fixed control records).

RAB$L_ROP

Record-processing options.

VMS RMS Services
$UPDATE

Table RMS-52 (Cont.)
Field Name

Update Service RAB Input Fields

Option

Description

RAB$V_ASY

Asynchronous: performs Update services
asynchronously.

RAB$V_WBH

Write-locked: two buffers are allocated to
allow multibuffering.

RAB$W_RSZ

Record size (required).

Table RMS-53 lists the control block fields written as output by the Update
service.
Table RMS-53

RETURN
VALUES

Update Service RAB Output Fields

Field Name

Option

RAB$W_RFA

Record file address.

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value.

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_8LN

RMS$_8UG

RMS$_BUG_OAP

RMS$_CDA

RMS$_CHG

RMS$_CHK

RMS$_CUR

RMS$_0ME

RMS$_0NR

RMS$_0UP

RMS$_ENO

RMS$_EXP

RMS$_FAC

RMS$_FTM

RMS$_1BF

RMS$_10X

RMS$_10P

RMS$_1RC

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_0K_OUP

RMS$_0K_IOX

RMS$_PENDING

RMS$_PLG

RMS$_RAB

RMS$_RBF

RMS$_RER

RMS$_RHB

RMS$_RNL

RMS$_RPL

RMS$_RRV

RMS$_RSA

RMS$_RSZ

RMS$_RVU

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_SYS

RMS$_TRE

RMS$_WBE

RMS$_WER

RMS$_WLK

RMS$_WPL

RMS-101

VMS RMS Services
$WAIT

$WAIT
The Wait service suspends image execution until an asynchronous record
service completes. Upon completion of the service, VMS RMS returns
control to your program at the point following the Wait service call.

FORMAT

SYS$WAIT

RETURNS

VMS usage:
type:
access:
mechanism:

rab

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rab
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Wait service call. The rab argument is the address of the RAB control
block. It can be either the RAB whose 1/0 request is in progress or some
other RAB.

DESCRIPTION

The Wait service takes no arguments to define entry points for user-written
completion routines; the completion routines are specified by the service
being awaited.
Any completion routines specified on the operation being awaited are
declared as ASTs before VMS RMS returns control. They are executed
before the WAIT service completes unless ASTs are disabled. Completion
routines are always executed as asynchronous system traps (ASTs).
Table RMS-54 lists the control block fields read as input and written as
output by the Wait service. For additional information on the fields accessed
by this service, see Part II.
Table RMS-54
Use

Field
Name

Description

Input

RAB$W_ISI

Internal stream identifier (required).

RAB$L_STS

Status completion code.

RAB$L_STS

Completion status code (also returned in register 0).

Output

RMS-102

Wait Service RAB Input and Output Fields

VMS RMS Services
$WAIT

RETURN
VALUES

The following condition values are described in Appendix A:
RMS$_BLN

RMS$_CDA

RMS$_1SI

RMS$_RAB

RMS$_STR

RMS$_SUC

RMS$_NORMAL

The VMS RMS completion status codes for the Wait service are determined by
the VMS RMS service being awaited, unless the address of the RAB specified
for the wait is different from that specified for the awaited operation. In this
case, RMS$_NORMAL is returned.

RMS-103

VMS RMS Services
$WRITE

$WRITE
The Write service transfers a user-specified number of bytes (beginning
on a block boundary) to a VMS RMS file of any file organization.

FORMAT

SVS$WRITE

RETURNS

VMS usage:
type:
access:
mechanism:

rab /,[err} [,sue]]

cond_value
longword (unsigned)
write only
by value

The value returned in RO is also returned in symbolic offset RAB$L_STS.
Symbolic offset RAB$L_STV may contain additional status information.

ARGUMENTS

rab
VMS usage:
type:
access:
mechanism:

rah
longword (unsigned)
modify
by reference

RAB control block whose contents are to be used as indirect arguments for
the Write service call. The rab argument is the address of the RAB control
block.

err
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level error completion routine that the service invokes if the operation
is unsuccessful. The err argument is the address of the entry mask of this
user-written completion routine.

sue
VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST-level success completion routine that the service invokes if the operation
is successful. The sue argument is the address of the entry mask of this
user-written completion routine.

RMS-104

VMS RMS Services
$WRITE

DESCRIPTION

You specify the number of bytes to be written by the Write service in the
record size (RAB$W_RSZ) field of the RAB and the address of the buffer for
the transfer in the record address (RAB$L_RBF) field. In the bucket number
(RAB$L_BKT) field, you indicate the virtual block number of the first block
to be written; if this number is 0, the transfer starts with the block indicated
by the NBP.
A sequential file is automatically extended if you write a block past the end
of the currently allocated space when using block If O (or record I/O). For
sequential files, VMS RMS maintains a logical end of file to correspond to the
last block and highest byte written within the block. For relative and indexed
files, you must use the Extend service when using block I/O.
Table RMS-55 lists the control block fields read as input by the Write service.
For additional information on the fields accessed by this service, see Part II.
Table RMS-55
Field Name

Write Service RAB Input Fields
Option

Description

RAB$L_BKT

Bucket number: must contain the virtual block
number of the first block to be written.

RAB$W_ISI

Internal stream identifier.

RAB$L_RBF

Record buffer address. For block 1/0,
alignment of the user's record buffer on a
page or at least a quadword boundary may
improve performance.

RAB$L_ROP

Record-processing options.
RAB$V_ASY

Asynchronous: performs Write services
asynchronously.

RAB$V_TPT

Truncate on Put: specifies that a Write service
truncate the file after the transferred data.

RAB$W_RSZ

Record size: indicates the transfer length, in
bytes. 1

1 Certain devices require that an even number of bytes be transferred. For further details,
see the VMS 1/0 User's Reference Volume.

Table RMS-56 lists the control block fields written as output by the Write
service.
Table RMS-56

Write Service RAB Output Fields

Field Name

Description

RAB$W_RFA

Record file address.

RAB$L_STS

Completion status code (also returned in register 0).

RAB$L_STV

Status value: contains the actual number of bytes transferred if
an end-of-file error occurs.

RMS-105

VMS RMS Services
$WRITE

RETURN
VALUES

RMS-106

The following condition values are described in Appendix A:
RMS$_ACT

RMS$_ATR

RMS$_ATW

RMS$_BLN

RMS$_BUG_DAP

RMS$_CDA

RMS$_CQNTROLC

RMS$_CONTROLO

RMS$_CONTROLY

RMS$_DME

RMS$_DNR

RMS$_EOF

RMS$_EXT

RMS$_FAC

RMS$_FTM

RMS$_FUL

RMS$_10P

RMS$_1SI

RMS$_NET

RMS$_NETFAIL

RMS$_NORMAL

RMS$_PENDING

RMS$_RAB

RMS$_RBF

RMS$_RSA

RMS$_RSZ

RMS$_STR

RMS$_SUC

RMS$_SUP

RMS$_SUPPORT

RMS$_WBE

RMS$_WER

RMS$_WLK

VMS RMS Completion Status Codes

This appendix includes two tables: one is a listing of VMS RMS completion
status codes ordered by the hexadecimal coding, and the other is a more
descriptive listing ordered alphabetically. See Part III for a listing of the status
codes applicable to individual VMS RMS services.
This appendix lists completion status codes for the RMS Journaling product
and some of the completion status codes for the SNA VMS Data Transfer
Facility but does not provide details. See the VAX RMS Journaling Manual
for an explanation of RMS Journaling status codes and the DECnet /SNA VMS
Data Transfer Facility User's Guide for details of the SNA VMS Data Transfer
Facility completion status codes. VMS RMS completion status error codes
generally fall into one of four groups:
•

Programming errors

•

Program design errors

•

System environment errors

•

Opera tor/ user errors

Here is a brief description of each group:
Error Group
Programming Errors
These errors are caused by incorrect programming and are usually detected
during the early stages of developing and debugging a program that uses
VMS RMS. Typical examples are missing values for required fields, referring
to a RAB instead of a FAB, invalid address for a buffer, and so forth. This
type of error is generally self-explanatory and usually requires only a minor
change to the program.
Program Design Errors
These errors are caused by more subtle errors that may rarely occur,
particularly if asynchronous record I/O, multistreamed sharing, or shared
files are involved. These errors may occur long after a program has been
in use and could require either a major program revision or the addition of
substantial error recovery code to handle the error conditions. Record-lock
errors, resource-exhaustion errors, and record-stream-currently-active errors
are typical progam design errors.
System Environment Errors
These errors include hardware errors and VMS RMS or other system software
errors that are not caused by your program. You may need to add substantial
defensive error-handling code or you may be able to run the program again
without error.
Operator/User Errors
These errors include errors by the user of the program, such as not mounting
a device before running the program, or typing an invalid file specification.
As with system environment errors, you may need to add substantial

A-1

VMS RMS Completion Status Codes

defensive error-handling code or simply reprompt the user for the correct
information or user action.
These are conditions in which completion status codes may not be returned
as expected:
•

The completion status codes that apply to the Close service do not include
errors introduced by the FAB$V_SCF option and the FAB$V_SPL option.
If the request is serviced successfully, then a success completion code is
returned, even if the request is found to be in error by the job controller
process.

•

The Wait service has unique errors. This service can return any status
code of the awaited operation.

•

Errors associated with output operations may not necessarily be reported
as the status of a particular operation because modified 1/0 buffers are
not always written out immediately. Such errors are reported as the
status of a subsequent operation, which may be an input, output, or
control operation.

Procedures for signaling VMS RMS completion status codes are discussed
in Chapter 2 for VAX languages other than VAX MACRO. VAX MACRO
users should refer to Chapter 3 and the example programs in Chapter 4 for
information on signaling VMS RMS errors. Note that certain errors may not
be signaled using the FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_
STV fields; these are denoted below and in Chapter 2.
A description of each completion status code is listed in this appendix. When
an error description indicates that the STV field should be examined for a
secondary status code, this usually indicates a non-VMS RMS completion
status (such as an ACP completion status). Non-VMS RMS errors are not
described in this document; see the VMS System Messages and Recovery

Procedures Reference Volume.
Please note that when you submit an SPR, you should also provide a
magnetic tape copy of the file causing the error.
When using the debugger, use the debug command EXAMINE/CONDITION
to view the message corresponding to the value in RO or the STS field or the
STV field. For example, you can view the error codes in the STS and STV
fields of the FAB at symbolic address (label) MYFAB when debugging a VAX
MACRO program by entering the following commands:
DBG> EXAMINE/CONDITION MYFAB+FAB$L_STS
DBG> EXAMINE/CONDITION MYFAB+FAB$L_STV

For additional information about the debugger, see the VMS Debugger Manual.
Table A-1 lists the codes by hexadecimal values and includes a very brief
description of each code. Table A-2 is ordered alphabetically and provides
more detailed descriptions of the codes.

A-2

VMS RMS Completion Status Codes

Table A-1

Completion Status Hexadecimal Values and Codes

Hex Value

Status Code

Message Text

00010001
00010001
00010609
00010611
00010619
00010631
00010651
00010679
00018009
00018011
00018019
00018021
00018029
00018031
00018039
00018041
00018049
00018051
00018059
00018061
00018069
00018071
00018198
000181AO
000181A8
00018180
000181B8
000181CO
000181C8
0001825A
00018262
00018272
0001827A
00018282
0001828A
00018292
0001829A
000182A2

RMS$_SUC

Normal successful completion (same as RMS$_NORMAL)

RMS$_NORMAL

Normal successful completion (same as RMS$_SUC)

RMS$_CONTROLO

Operation completed under CTRL/O

RMS$_CONTROLY

Operation completed under CTRL/Y

RMS$_CREA TED

File did not exist-was created

RMS$_SUPERSEDE

Created file superseded existing version

RMS$_CONTROLC

Operation completed under CTRL/O

RMS$_FILEPURGED

Created file deleted oldest version

RMS$_PENDING

Asynchronous operation not yet completed

RMS$_QK_DUP

Record inserted had duplicate key

RMS$_QK_IDX

Index update error occurred

RMS$_QK_RLK

Record locked but read anyway

RMS$_QK_RRL

Record locked against read but read anyway

RMS$_KFF

Known file found

RMS$_QK_ALK

Record is already locked

RMS$_QK_DEL

Deleted record successfully accessed

RMS$_QK_RNF

Nonexistent record successfully accessed

RMS$_QK_LIM

Retrieved record exceeds specified key value

RMS$_QK_NOP

XAB not filled in for block 1/0

RMS$_QK_WAT

Record locked after wait

RMS$_CRE_STM

File created in stream format

RMS$_QK_RULK

See the VAX RMS Journaling Manual for details.

RMS$_BOF

Beginning of file detected

RMS$_RNL

Record not locked

RMS$_RTB

nnn-byte record too large for user's buffer

RMS$_TMO

Timeout period expired

RMS$_TNS

Terminator not seen

RMS$_BES

Bad escape sequence

RMS$_PES

Partial escape sequence

RMS$_ACT

File activity precludes operation

RMS$_DEL

RFA-accessed record deleted

RMS$_DNR

Device not ready, not mounted, or unavailable

RMS$_EQF

End of the file detected

RMS$_FEX

File already exists, not superseded

RMS$_FLK

File currently locked by another user

RMS$_FNF

File not found

RMS$_PRV

Insufficient privilege or file protection violation

RMS$_REX

Record already exists

A-3

VMS RMS Completion Status Codes

Table A-1 (Cont.)

Completion Status Hexadecimal Values and Codes

Hex Value

Status Code

Message Text

000182AA
00018282
000182BA
000182C2
000182CA
000182D2
000182DA
000182E2
000182EA
000182F2
0001830A
0001831A
00018322
0001832A
00018332
0001833A
00018342
0001834A
00018352
0001835A
000183EC
000183F4
000183FC
00018404
0001840C
00018414
0001841C
00018424
0001842C
00018434
0001843C
00018444
0001844C

RMS$_RLK

Target record currently locked by another stream

00018454
0001845C
00018464

A-4

RMS$_RNF

Record not found

RMS$_WLK

Device currently write-locked

RMS$_EXP

File expiration date not yet reached

RMS$_NMF

No more files found

RMS$_SUP

Network operation not supported; DAP code = nnnn

RMS$_RSA

Record stream currently active

RMS$_CRC

Network DAP level CRC check failed

RMS$_WCC

Invalid wild card context (WCC) value

RMS$_IDR

Invalid directory rename operation

RMS$_NQV ALPRS

$SEARCH operation not preceded by valid $PARSE

RMS$_RUH

See the VAX RMS Journaling Manual for details.

RMS$_JND

See the VAX RMS Journaling Manual for details.

RMS$_BADPHASE

See the VAX RMS Journaling Manual for details.

RMS$_TOWDR

See the VAX RMS Journaling Manual for details.

RMS$_NEXDR

See the VAX RMS Journaling Manual for details.

RMS$_1NVDRMSG

See the VAX RMS Journaling Manual for details.

RMS$_RU_ACTIVE

See the VAX RMS Journaling Manual for details.

RMS$_UNKRUFAC

See the VAX RMS Journaling Manual for details.

RMS$_LIMBO

See the VAX RMS Journaling Manual for details.

RMS$_DTFCDDREC

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_AID

Invalid area ID = n

RMS$_ALN

Alignment options error for area ID = n

RMS$_ALQ

Invalid allocation quantity (negative, or 0 on $EXTEND)

RMS$_ANI

Not ANSI D format

RMS$_AOP

Allocation options error for area ID = n

RMS$_BKS

Bucket size too large (F AB)

RMS$_BKZ

Inconsistent bucket size for area ID = n

RMS$_BLN

Invalid block length for control block (RAB/FAB)

RMS$_BUG

Internal RMS error condition detected

RMS$_BUG_DDI

Invalid default directory

RMS$_BUG_DAP

Data Access Protocol error detected; OAP code= nnnn

RMS$_BUG_RU_
ACTIVE

See the VAX RMS Journaling Manual for details.

RMS$_BUG_RURECERR

See the VAX RMS Journaling Manual for details.

RMS$_BUG _FLUSH_
JNL_FAILED

See the VAX RMS Journaling Manual for details.

RMS$_BUG_RU_
ABORT_FAIL

See the VAX RMS Journaling Manual for details.

VMS RMS Completion Status Codes

Table A-1 (Cont.)

Completion Status Hexadecimal Values and Codes

Hex Value

Status Code

Message Text

0001848C
00018494
0001849C
000184A4
000184AC
000184B4
000184BC
000184C4
000184CC
000184D4
000184DC
000184E4
000184EC
000184F4
000184FC
00018504
0001850C
00018514
0001851C
00018524
0001852C
00018534
0001853C
00018544
00018554
0001855C
00018564
0001856C
00018574
0001857C
00018584
0001858C
00018594
0001859C
000185A4
000185AC
000185B4
000185BC

RMS$_BUSY

User structure (FAB/RAB) still in use

RMS$_CCR

Cannot connect RAB

RMS$_CHG

Invalid key change in $UPDATE (CHG not set)

RMS$_CHK

Bucket format check failed for VBN =nnnn

RMS$_COD

Invalid or unsupported type field in XAB at nnnn

RMS$_CUR

No current record (operation not preceded by $GET /$FIND)

RMS$_DAN

Invalid data area number for key = n

RMS$_DEV

Error in device name or inappropriate device type for operation

RMS$_DIR

Error in directory name

RMS$_DME

Dynamic memory exhausted

RMS$_DNA

Invalid default file name string address

RMS$_DTP

Invalid key data type for key = n

RMS$_DUP

Duplicate key detected (DUP not set)

RMS$_DVI

Invalid device ID value in NAM block

RMS$_ESA

Invalid expanded string address

RMS$_ESS

Expanded string area too small

RMS$_FAB

Invalid FAB or FAB not accessible

RMS$_FAC

Record operation not permitted by specified file access (FAC)

RMS$_FLG

Invalid key definition flags for key = n

RMS$_FNA

Invalid file name string address

RMS$_FNM

Error in file name

RMS$_FSZ

Invalid fixed control header size

RMS$_FOP

Invalid file options

RMS$_FUL

Device full (insufficient space for allocation)

RMS$_1AN

Invalid index area number for key = n

RMS$_1DX

Index not initialized

RMS$_1FI

Invalid internal file identifier (IFI) value

RMS$_1MX

Invalid duplicate XAB or nondense XAB at nnnn

RMS$_10P

Operation invalid for file organization or device

RMS$_1RC

Illegal record encountered; VBN or record number = nnnn

RMS$_1SI

Invalid internal stream identifier (ISi) value

RMS$_KBF

Invalid key buffer

RMS$_KEY

Invalid record number key or key value

RMS$_KRF

Invalid key-of-reference for $GET /$FIND

RMS$_KSZ

Invalid key size for $GET /$FIND

RMS$_LAN

Invalid lowest-level-index area number for key = n

RMS$_RUNDOWN

Operation invalid during RMS rundown

RMS$_LNE

Logical name translation count exceeded

A-5

VMS RMS Completion Status Codes

Table A-1 (Cont.)

Completion Status Hexadecimal Values and Codes

Hex Value

Status Code

Message Text

000185C4

RMS$_DTFCVT

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

000185CC

RMS$_MRN

Invalid maximum record number or record number exceeds
MRN

000185EC

RMS$_DTFQUASYN

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

00018504

RMS$_MRS

Invalid maximum record size

0001850C

RMS$_NAM

Invalid NAM block or NAM block not accessible

000185E4

RMS$_NEF

Not positioned to EOF on $PUT (sequential organization only)

000185F4

RMS$_NOO

Error in node name

000185FC

RMS$_NPK

No primary key defined for indexed file

0001860C

RMS$_0RG

Invalid file organization value

00018614

RMS$_PBF

Invalid prompt buffer

0001861C

RMS$_PLG

Error detected in file's prolog (reconstruct file)

00018624

RMS$_POS

Invalid key position (greater than MRS) for key = n

0001862C

RMS$_DTFQUA VAL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

00018634

RMS$_QUO

Error in quoted string

0001863C

RMS$_RAB

Invalid RAB or RAB not accessible

00018644

RMS$_RAC

Invalid record access mode

0001864C

RMS$_RAT

Invalid record attributes

00018654

RMS$_RBF

Invalid record buffer

0001865C

RMS$_RFA

Invalid record file address in RAB

00018664

RMS$_RFM

Invalid record format

0001866C

RMS$_RHB

Invalid record header buffer

00018674

RMS$_RLF

Invalid related NAM block

0001867C

RMS$_ROP

Invalid record options

00018684

RMS$_RRV

Invalid RRV record encountered

0001868C

RMS$_RVU

Error updating RRVs, some paths to data may be lost

00018694

RMS$_RSS

Invalid resultant string size

0001869C

RMS$_RST

Invalid resultant string address

000186A4

RMS$_RSZ

Invalid record size

000186AC

RMS$_SEQ

Primary key out of sequence (SEQ access)

000186B4

RMS$_SHR

Invalid file-sharing (SHR) options

000186BC

RMS$_SIZ

Invalid key size for key = n

000186C4

RMS$_SQO

Operation not sequential (SQQ set)

000186CC

RMS$_DTFSESEST

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

00018604

RMS$_SYN

File specification syntax error

0001860C

RMS$_TRE

Error in index tree

000186E4

RMS$_TYP

Error in file type

000186EC

RMS$_UBF

Invalid user buffer address

A-6

VMS RMS Completion Status Codes

Table A-1 (Cont.)
Hex Value

000186F4
000186FC
00018704
0001870C
00018714
0001871C
00018724
0001872C
00018734
0001873C
00018744
0001874C
00018754
0001875C
00018764
0001876C
00018774
0001877C
00018784
0001878C
00018794
000187AC
00018784
000187BC
000187C4
000187CC
000187D4
000187DC
000187E4
000187F4
000187FC
00018804
0001880C
00018814
0001881C
00018824
00018824

Completion Status Hexadecimal Values and Codes

Status Code

Message Text

RMS$_USZ

Invalid user buffer size

RMS$_ VER

Error in version number

RMS$_XNF

Required XAB not found

RMS$_XAB

Invalid XAB or XAB not accessible at nnnn

RMS$_ESL

Invalid expanded string length

RMS$_DTFSESTE R

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_ENV

Support for RMS service call or feature not present

RMS$_PLV

Unsupported prolog version

RMS$_MBC

Invalid multiblock count

RMS$_RSL

Invalid resultant string length

RMS$_WLD

Invalid wildcard operation

RMS$_NET

Network operation failed at remote node; DAP code = nnnn

RMS$_1BF

Illegal bucket format in VBN = nnnn

RMS$_REF

Invalid key-of-reference = n

RMS$_1FL

Index bucket fill size larger than bucket size for key = n

RMS$_DFL

Data bucket fill size larger than bucket size for key = n

RMS$_KNM

Key name buffer not accessible for key

RMS$_1BK

LAN bucket size not equal to IAN bucket size for key = n

RMS$_KSI

Index bucket cannot hold two keys for key-of-reference = n

RMS$_LEX

Invalid $EXTEND for area n containing an unused extent

RMS$_SEG

Overlapping segments or segmented key must be string for
key= n

RMS$_ UPI

UPI not set when sharing and BIO or BRO set

RMS$_ACS

Error in access control string

RMS$_STR

User structure (FAB/RAB) became invalid during operation

RMS$_FTM

Network file transfer mode precludes operation (SQQ set)

RMS$_GBC

Invalid global buffer count

RMS$_DEADLOCK

Deadlock detected

RMS$_EXENOLM

Exceeded enqueue quota

RMS$_JOP

See the VAX RMS Journaling Manual for details.

RMS$_JNS

See the VAX RMS Journaling Manual for details.

RMS$_NRU

See the VAX RMS Journaling Manual for details.

RMS$_1FF

Invalid file attributes for requested file access

RMS$_DTFTRA TBL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFUNSTYP

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFVERMIS

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFACC

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTF ACC

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

A-7

VMS RMS Completion Status Codes

Table A-1 (Cont.)

Completion Status Hexadecimal Values and Codes

Hex Value

Status Code

Message Text

00018826

RMS$_BOGUSCOL

Invalid or inaccessible collating table

00018834

RMS$_ERRREADCOL

Error encountered while trying to read collating table

00018836

RMS$_ERRWRITECOL

Error encountered while trying to write collating table

00018854

RMS$_DTFCRE

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

00018864

RMS$_NQTSAMEJNL

See the VAX RMS Journaling Manual for details.

0001885C

RMS$_DELJNS

See the VAX RMS Journaling Manual for details.

0001C002

RMS$_ACC

ACP file access failed

0001COOA

RMS$_CRE

ACP file create failed

0001C012

RMS$_DAC

ACP file deaccess failed during $CLOSE

0001C01A

RMS$_ENT

ACP enter function failed

0001C022

RMS$_EXT

ACP file extend failed

0001C02A

RMS$_FND

ACP file or directory lookup failed

0001C032

RMS$_MKD

ACP could not mark file for deletion

0001C03A

RMS$_DPE

Device positioning error

0001C042

RMS$_SPL

Spool or submit of command file failed on $CLOSE

0001C04A

RMS$_DNF

Directory not found

0001C052

RMS$_RUF

See the VAX RMS Journaling Manual for details.

0001C05A

RMS$_WRT JNL_AIJ

See the VAX RMS Journaling Manual for details.

0001C062

RMS$_ WATJNL _BIJ

See the VAX RMS Journaling Manual for details.

0001C072

RMS$_ WAT JNL _RUJ

See the VAX RMS Journaling Manual for details.

0001C07A

RMS$_RRF

See the VAX RMS Journaling Manual for details.

0001COCC

RMS$_ATR

File attributes read error

0001COD4

RMS$_ATW

File attributes write error

0001CODC

RMS$_CCF

Cannot close file

0001COE4

RMS$_CDA

Cannot deliver AST

0001COEC

RMS$_CHN

Assign channel system service request failed

0001COF4

RMS$_RER

File read error

0001COFC

RMS$_RMV

ACP remove function failed

0001C104

RMS$_RPL

Error detected while reading prolog

0001C10C

RMS$_SYS

010 system service request failed

0001C114

RMS$_WER

File write error

0001C11C

RMS$_WPL

Error detected while writing prolog

0001C124

RMS$_1FA

Illegal file attributes detected (file header corrupted)

0001C12C

RMS$_WBE

Error on write behind

0001C134

RMS$_ENQ

ENO system service request failed

0001C13C

RMS$_NETF AIL

Network operation failed at remote node

A-8

VMS RMS Completion Status Codes

Table A-1 (Cont.)

Completion Status Hexadecimal Values and Codes

Hex Value

Status Code

Message Text

0001C144
0001C14C
0001C154
0001C15C
0001C164
0001C16C
0001C174
0001C17C
0001C18C
0001C194

RMS$_SUPPORT

Network operation not supported

RMS$_CRMP

CRMPSC system service failed to map global buffers

RMS$_DTFCFGFIL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_REENT

File could not be renamed and recovery failed; file has been lost

RMS$_ACC_RUJ

See the VAX RMS Journaling Manual for details.

RMS$_TMR

SETIMR system service request failed

RMS$_ACC_AIJ

See the VAX RMS Journaling Manual for details.

RMS$_ACC_BIJ

See the VAX RMS Journaling Manual for details.

RMS$_DTFDEFFIL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFREGFIL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

Table A-2

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_ACC

File access error; the STV field contains an ACP error code. Take corrective
action appropriate to the STV status code.

RMS$_ACS

Error in access control string of the node name.

RMS$_ACC_AIJ

See the VAX RMS Journaling Manual for details.

RMS$_ACC_BIJ

See the VAX RMS Journaling Manual for details.

RMS$_ACC_RUJ

See the VAX RMS Journaling Manual for details.

RMS$_ACT

File activity precludes operation; operation attempted during other file 1/0.
Modify the source program to detect and respond to this condition.

RMS$_AID

Bad area identification number field in allocation XAB; the STV field contains the
area ID.

RMS$_ALN

Invalid alignment boundary type in allocation XAB; the STV field contains the
area ID.

RMS$_ALQ

Incorrect allocation quantity; the value exceeds the maximum allowed (Create
service) or exceeds the maximum allowed or is equal to zero (Extend service).

RMS$_ANI

Records in a magnetic tape file are not ANSI D format.

RMS$_AOP

Invalid allocation option in allocation XAB; the STV field contains the area ID.

RMS$_ATR

Read error on file header; the STV field contains an ACP error code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_ATW

Write error on file header; the STV field contains an ACP error code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_BADPHASE

See the VAX RMS Journaling Manual for details.

RMS$_BES

Bad escape sequence (terminals only, warning). Modify the source program to
detect and recognize this condition or reenter the input specifying the correct
escape sequence.

RMS$_BKS

Invalid bucket size in FAB or inconsistent record length. The bucket size
specified in the FAB is larger than 63. If the bucket size is specified as zero, the
maximum record size is too large.

A-9

VMS RMS C0.mpletion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_BKZ

Invalid bucket size in the allocation XAB; the STV field contains the area ID.

RMS$_BLN

Invalid value in block length field; this completion code is not available in the
FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_STV fields.

RMS$_BOF

Beginning of file detected (warning); you invoked the Rewind service or Space
service at the beginning of the file. The STV field contains the number of blocks
spaced. You may need to modify the source program to detect and respond to
this condition.

RMS$_BOGUSCOL

Either the collating sequence is missing, is inaccessible to RMS, or is in a format
that RMS cannot interpret. This situation is typically created by an application
program error. Verify that a valid NCS sequence is available to RMS.

RMS$_BUG

Internal VMS RMS error detected. Submit an SPR.

RMS$_BUG_DAP

Data Access Protocol error. Submit an SPR.

RMS$_BUG_DDI

Invalid default directory. Submit an SPR.

RMS$_BUG _FLUSH_
JNL_FAILED

See the VAX RMS Journaling Manual for details.

RMS$_BUG_
RUCRECERR

See the VAX RMS Journaling Manual for details.

RMS$_8UG_RU_
ABORT_FAIL

See the VAX RMS Journaling Manual for details.

RMS$_BUG _RU_
ACTIVE

See the VAX RMS Journaling Manual for details.

RMS$_BUSY

FAB or RAB cannot be used because either a prior operation needs to complete
before VMS RMS can use the FAB or RAB for the requested operation, or the
user illegally called VMS RMS from executive mode at AST level or from kernel
mode and interrupted another VMS RMS operation. Use multiple 1/0 streams or
use the Wait service as necessary. This completion code is not available in the
FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_STV fields.

RMS$_CCF

For the $CLOSE service, an output file could not be closed successfully; user
buffer identifies the file by its device ID and file ID.

RMS$_ CCR

Cannot connect RAB; process has specified either a nonexistent or inaccessible
RAB. This usually results from one of the following actions:
•

The program tried to do block 1/0 (setting RAB$V_BIO in RAB$L_ROP) with
multistreaming (setting FAB$V_MSE bit in FAB$B_SHR).

•

The program tried to connect to multiple RABs to a FAS without first setting
the FAB$V_MSE bit in the FAB$8_SHR field.

•

The program tried to use multistreaming with file access across DECnet.

RMS$_CDA

Cannot deliver AST; the STV field contains the STS value of the operation. The
AST limit quota for the process has probably been exhausted. You need to
increase the quota or decrease the level of AST activity. Take corrective action
for the actual operation based on the STV value.

RMS$_CHG

The process tried to change a key value in a file that does not have the key
change option.

A-10

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_CHK

Index file bucket check byte mismatch; the bucket has been corrupted. The STV
field contains the VBN of the bucket. This error can be caused by any of the
following conditions:
•

The combination of a disk backed up using standalone BACKUP and files
with the /NOBACKUP qualifier

•

Inadvertent modification of the file using block 1/0 or non-VMS RMS
programs

•

Hardware, VMS RMS, or other system software errors

Try to recreate the rest of the file. If the problem recurs and appears to be
caused by VMS RMS or system software, submit an SPR.
RMS$_CHN

Channel assignment failure; the STV field contains a system error code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_CQD

Invalid type code in XAB; the STV field contains the XAB address.

RMS$_CONTROLC

Operation completed under CTRL/C; terminal 1/0 may have been truncated
(success).

RMS$_CONTROLO

Operation completed under CTRL/0; terminal output may have been truncated
(success).

RMS$_CONTROLY

Operation completed under CTRL/Y; terminal 1/0 may have been truncated
(success).

RMS$_CRC

Network OAP level CRC failed on Close. The network link may be experiencing
hardware errors. Retry the operation.

RMS$_CRE

ACP file creation failed. The STV field contains an ACP error code. Take
corrective action appropriate to the STV status code.

RMS$_CREA TED

File created with the FAB$V_CIF (create-if) option because the file was not
found. If the file is found, it is opened (not created) and RMS$_NORMAL is
returned (success).

RMS$_CRE_STM

File created in stream format (success).

RMS$_CRMP

For the Connect service, the requested number of global buffers is unobtainable;
no global sections or an insufficient number of global pages or global page file
entries were available to grant the requested number of global buffers. Reduce
the number of global buffers requested in the FAB$W _GBC field and retry
the Connect service, or wait until an orderly shutdown of the system can be
arranged and increase the appropriate system generation parameters, then retry
the operation.

RMS$_CUR

No current record; operation not immediately preceded by a successful Get or
Find service.

RMS$_DAC

ACP file deaccess failed during Close. The file was deaccessed. The STV field
contains an ACP error code. Take corrective action appropriate to the STV
status code.

RMS$_DAN

Invalid data area number in key definition XAB; the STV field contains the key
number.

RMS$_DEADLOCK

The VMS lock manager detected a deadlock. Modify the source program, if
necessary.

A-11

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_DEL

RFA-accessed record deleted; the program attempted to access a previously
deleted record. Modify the source program, if necessary.

RMS$_DELJNS

See the VAX RMS Journaling Manual for details.

RMS$_DEV

Bad device or inappropriate device type for operation.

RMS$_DFL

Data bucket fill size larger than bucket size specified in the key definition XAB;
the STV field contains the key number.

RMS$_DIR

Error in directory name; the directory name specified incorrectly. For example, a
directory or subdirectory name exceeded 39 characters in length, or the use of
a logical name resulted in more than one directory name in the file specification.
Verify the syntax of either the directory name in the file specification or the
logical name, if applicable.

RMS$_DME

Dynamic memory exhausted. Occurs only if the related 1/0 segment in the
control region is full and the file is either a direct access process-permanent file
or the user has disallowed the use of the program region for 1/0 buffers to RMS.

RMS$_DNA

Invalid default file specification string address.

RMS$_DNF

Directory not found; specified directory name does not exist on the specified
device. Verify that the device and directory are specified correctly. Create
the directory on that device or use a different directory. When performing an
Open service, consider using a search list logical name if the same file exists in
multiple device/directory locations. The STV field contains a system error code.
Take corrective action appropriate to the STV status code.

RMS$_DNR

Device not ready, not mounted, or unavailable. Make sure that the volume is
physically loaded, that the device is ready, and that the DCL command MOUNT
has been completed successfully. Check that the correct controller is set on the
drive. Retry the operation.

RMS$_DPE

Device positioning error; magnetic tape improperly positioned. Examine the
RAB$L_STV field for secondary status information; take corrective action
appropriate to this information. Retry the operation. If this error persists, it may
indicate a system software or hardware failure. Contact your system operator
or manager.

RMS$_DTFACC

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFCDDREC

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFCFGFIL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFCRE

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFCVT

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFDEFFIL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFQUASYN

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFQUA VAL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFREGFIL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFSESEST

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFSESTER

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFTRA TBL

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTFUNSTYP

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

A-12

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_DTFVERMIS

See the DECnet/SNA VMS Data Transfer Facility User's Guide.

RMS$_DTP

Invalid data type in key definition XAB; the STV field contains the key number.

RMS$_DUP

Duplicate key detected; key definition XAB key option flag not set to allow
duplicate key values.

RMS$_DVI

Invalid device identification in the NAM block.

RMS$_ENQ

Lock manager system service failed; the STV field contains a $ENO system
service error code. Take corrective action appropriate to the STV status code,
if possible.

RMS$_ENT

ACP enter function failed. The STV field contains an ACP error code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_ENV

Environment error; support for the VMS RMS service or selected option is not
present in system.

RMS$_EOF

For Find or Get services, end of the file detected; the program attempted to read
beyond the last record in the file. If necessary, modify the source program to
detect and respond to the condition.
For a Read (block 1/0) service, end of the file detected. Checking for the logical
end of the file is performed only for sequential file organization. If an RMS$_EQF
error occurs, it implies that the first virtual block number specified is at or past
the end of the file. If the RMS$_EOF error occurs during a transfer, the record
size field is set to the number of bytes before the logical end of the file. For
relative or indexed file organization, this status code indicates an attempt to read
past the end of the currently allocated space.
For a Write service (block 1/0), end of the file detected for a sequential file;
implies that the file could not be extended. Determine whether sufficient disk
space is available on the disk device in use (use the DCL command SHOW
DEVICE). If you do not have enough space, purge or delete files that are no
longer needed; then retry the operation.

RMS$_ERRREADCOL

An 1/0 error occurred when the program tried to read the file's collating
sequence. This is typically due to a hardware problem; otherwise, submit
an SPR.

RMS$_ERRWRITECOL

An 1/0 error occurred when the program tried to write the sequence to the file.
This is usually due to a hardware problem; otherwise, submit an SPR.

RMS$_ESA

Invalid expanded string area address in NAM block.

RMS$_ESL

Invalid expanded string length in NAM block.

RMS$_ESS

Expanded string area too short.

RMS$_EXENOLM

Exceeded process enqueue limit. Reduce the number of locks held at one time
and retry, or have the system manager increase this limit for your process. Log
out and log in, and then retry the operation.

RMS$_EXP

File expiration date not yet reached; tried to overwrite magnetic tape files. If the
file can be overwritten, remount the volume using the /OVERRIDE=EXPIRATION
qualifier. (You must be the volume owner or have VOLPRO privilege to overwrite
a volume.) Otherwise, use a different volume.

RMS$_EXT

ACP file extend failed. The STV field contains an ACP error code. Take
corrective action appropriate to the STV status code, if possible.

A-13

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_FAB

Invalid FAB; block identifier field incorrect. This completion code is not available
in the FAB$L_STS/FAB$L_STV fields.

RMS$_FAC

Operation not allowed by the value set in the FAB$B_FAC field. For the Extend
service, verify that the FAB$B_FAC field specifies put or update access for the
file to be extended. Modify the source program if necessary.

RMS$_FEX

File already exists, not superseded; the program attempted to create or rename
a file with the same file specification as an existing file. Choose a different file
specification; delete the existing file (if a new file is to be created). For the
Create service, consider using the FAB$L_FOP field FAB$V_SUP option to
request that an existing file be superseded.

RMS$_FILEPURGED

This informational message indicates that the newly created file version
exceeded the maximum number of versions allowed for the file; therefore,
the oldest version is deleted.

RMS$_FLG

Invalid combination of values in key XAB$B_FLG field; the STV field contains
the key number. (Example: XAB$V_CHG or XAB$V_NUL for primary key.)

RMS$_FLK

File currently locked by another user; the program attempted to create or open
a file that is currently being accessed by another user, and the file was not
accessed for sharing. Wait until the other user deaccesses the file and retry the
operation.

RMS$_FNA

Invalid file specification string address in FAB.

RMS$_FND

ACP file or directory lookup failed; error occurred during a directory search. The
STV field contains an ACP error code. Take corrective action appropriate to the
STV status code, if possible.

RMS$_FNF

File not found. Check the file specification and verify that the device, directory,
file name, and file type are correct. If a logical name was specified, verify that
the current equivalence name assigned to the logical name is correct. Verify that
the correct volume is mounted and that the file was not inadvertently deleted.

RMS$_FNM

Syntax error in file name.

RMS$_FOP

Invalid file-processing options.

RMS$_FSZ

Invalid fixed control area size in FAB (equal to 1 for print files).

RMS$_FTM

Network OAP file transfer mode does not permit operation.

RMS$_FUL

Device full; cannot create or extend file.

RMS$_GBC

Invalid global buffer count.

RMS$_1AL

Invalid argument list. Applies to the SYS$RMSRUNDWN, SYS$SETDFPROT,
and SYS$SETDDIR services. See the VMS System Services Reference Manual.

RMS$_1AN

Invalid index area number in key definition XAB; the STV field contains the key
number.

RMS$_1BF

Invalid bucket format; STV contains bucket VBN. Submit an SPR.

RMS$_1BK

Bucket size of lowest level of index area number (XAB$B_LAN) not equal to that
of specified index area number (XAB$B_IAN field) in key definition XAB; the
STV field contains the key number.

RMS$_1DR

Invalid directory rename operation; attempted to rename a directory file into
a directory tree that contained the directory file. The directory would then be
inaccessible.

A-14

VMS RMS Completion Status Codes

Table A-2 (Cont.)
Status Code

Descriptions of VMS RMS Completion Status Codes
Description

RMS$_1DX

Index not initialized; internal VMS RMS error. Submit an SPR.

RMS$_IFA

Invalid file attributes; file header corrupted. Check the STV field for additional
information. Take corrective action appropriate to the STV status code, if
present.

RMS$_1FF

Invalid file attributes for requested access. Usually, this occurs when attempting
to open an ANSI magnetic tape file for write access and the file has a nonzero
value for its buffer offset value. VMS RMS does not allow the creation of a
magnetic tape file with a nonzero buffer offset. You can, however, access such
a file for read and write operations if you specify block 1/0.

RMS$_1FI

Invalid internal file identifier in FAB; file already closed or not open (Close or
Connect services), file already open or not closed (Create service), file not open
(Display and Extend services), or file already open (other services).

RMS$_1FL

Index bucket fill size larger than bucket size specified in key definition XAB; the
STV field contains the key number.

RMS$_1MX

More than one XAB of the same type or nondense XAB is present for the file;
the STV field contains the XAB address.

RMS$-_INVDRMSG

See the VAX RMS Journaling Manual for details.

RMS$_10P

Invalid operation attempted; operation is one of following: ( 1) block 1/0
when record 1/0 access, ( 2) record 1/0 when block 1/0 access, ( 3) rewind of
process-permanent file, ( 4) inappropriate device type or file organization.

RMS$_1RC

Invalid record encountered in file or invalid byte count field or control byte field
contained in that record; the STV field contains the virtual block number for
sequential and indexed files or the relative record number for relative files of the
corrupted record. This error can be caused by the following conditions:
•

The combination of a disk backed up using standalone BACKUP and files
with the /NOBACKUP qualifier

•

Inadvertent modification of files by block 1/0 or non-VMS RMS programs

•

Hardware errors, VMS RMS errors, or other system software errors.

For sequential and indexed files, try to recreate the rest of the file. For relative
files, reinsert the bad record with the Put service using the RAB$L_ROP field
RAB$V_UIF option. If this does not solve the problem, submit an SPR.
RMS$_1SI

Invalid internal stream identifier in RAB; record stream already connected
(Connect service) or was not connected (other services).

RMS$_JND

See the VAX RMS Journaling Manual for details.

RMS$_JNS

See the VAX RMS Journaling Manual for details.

RMS$_JOP

See the VAX RMS Journaling Manual for details.

RMS$_KBF

Invalid key buffer address.

RMS$_KEY

Invalid record key for random operation to a relative file or invalid packed
decimal key for an indexed file.

RMS$_KFF

Known file found; this code is reserved for DIGITAL usage only.

RMS$_KNM

Invalid key name buffer address in key definition XAB; the STV field contains
the key number.

RMS$_KRF

Invalid key of reference in RAB$B_KRF field.

A-15

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_KSI

The size of the index buckets specified for the key must be large enough to hold
at least two key values: the STV value contains the key of reference.

RMS$_KSZ

Key size not equal to 4 (relative file) or key size too large (indexed file).

RMS$_LAN

Invalid index lowest-level-bucket area number in key definition XAB; the STV
field contains the key number.

RMS$_LEX

Attempted to extend area containing an unused extent.

RMS$_LNE

Logical name error; an error was detected in file name processing. Usually this
is caused by exceeding the maximum logical name translation count, typically
when the equivalence string for a logical name is identical to the name itself.
This error can also indicate a fatal error in logical name translation, or invalid
syntax for a process-permanent file equivalence string.

RMS$_MBC

Invalid multiblock count. Must not be greater than 127.

RMS$_MKD

ACP could not mark file for deletion. The STV field contains an ACP error code.
Take corrective action appropriate to the STV status code, if possible.

RMS$_MRN

Invalid value for maximum record number (negative) or relative key greater than
maximum record number.

RMS$_MRS

Invalid value for maximum record size.

RMS$_NAM

Invalid or inaccessible NAM block.

RMS$_NEF

Attempted to use the Put service to a sequential file not positioned to the end
of the file.

RMS$_NET

Network operation failed at remote node; the STV field contains a OAP code.
Take corrective action appropriate to the STV status code, if possible.

RMS$_NETFAIL

Network operation failed at remote node; the STV field contains an FAL status
code. Take corrective action appropriate to the STV status code, if possible.

RMS$_NMF

No more files found; the directory or volume set does not contain any more files
that meet the file specification (wild card operation). This is the normal status to
indicate the end of a wildcard search operation. Modify the source program, if
necessary, to detect and respond to this condition.

RMS$_NOD

Node name error.

RMS$_NORMAL

Operation successful (synonym for RMS$_SUC, success).

RMS$_NOV ALPRS

Search service not preceded by a Parse service. Correct the source program to
invoke the Parse service before invoking the Search service.

RMS$_NPK

No primary key defined in key definition XAB when creating an indexed file.

RMS$_QK_ALK

Record is already locked; the program attempted to lock a previously locked
record. No action is usually required, although this can depend on application
requirements (success).

RMS$_QK_DEL

Deleted record successfully accessed; a previously deleted record was read
successfully. No action is usually required, although this can depend on
application requirements (success).

RMS$_QK_DUP

Record inserted had duplicate key; the record was inserted successfully and had
one or more key values that duplicated the values of other records (success).

A-16

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_0K_IDX

Index update error occurred; the record was inserted successfully but an error
occurred on index update, which could cause slow access to that record
using that key path. Examine the value of the VMS RMS error in the RAB$L_
STV field. Take corrective action appropriate to the STV status code. File
reorganization is recommended (success).

RMS$_0K_LIM

Retrieved record exceeds specified key value; the retrieved record exceeds the
specified key value when the RAB$L_ROP RAB$V_LIM option was specified. It
was read successfully. No action is usually required, although this can depend
on application requirements (success).

RMS$_LIMBO

See the VAX RMS Journaling Manual for details.

RMS$_NEXDR

See the VAX RMS Journaling Manual for details.

RMS$_NOTSAMEJNL

See the VAX RMS Journaling Manual for details.

RMS$_NRU

See the VAX RMS Journaling Manual for details.

RMS$_0K_NOP

XAB not filled in for block 1/0; operation executed successfully when block
1/0 access was specified. One or more XABALL or XABKEY blocks were not
filled. No action is usually required, although this can depend on application
requirements (success).

RMS$_QK_RLK

Record locked but read anyway; the retrieved record was locked but was read
successfully. No action is required (success).

RMS$_QK_RNF

Nonexistent record successfully accessed; a nonexistent record was read
successfully. No action is required (success).

RMS$_0K_RRL

Record locked against read, but read anyway; a record locked against reading
was read successfully. No action is required (success).

RMS$_0K_RULK

See the VAX RMS Journaling Manual for details.

RMS$_QK_WAT

Record locked after wait; the retrieved record was locked but has been read
successfully after a wait period. No action is required (success).

RMS$_0RG

Unknown file organization.

RMS$_PBF

Invalid prompt buffer address.

RMS$_PENDING

An asynchronous operation was initiated but is not yet completed; no action is
required (success).
Partial escape sequence (terminals only, warning); the user buffer was filled
before a complete escape sequence was entered. The remainder of the escape
sequence is returned with the next input operation. Increase the size of the
user buffer to allow escape sequences or modify the program, if necessary, to
recognize and respond to this condition.

RMS$_PLG

Error in file prolog; file is corrupted.

RMS$_PLV

Prolog version unsupported.

RMS$_PQS

Invalid key position (greater than MRS) in key definition XAB; the STV field
contains the key number.
Insufficient privilege or file protection violation; the current process is denied
access because of the file protection. Check the access rights associated
with the file and change them if needed. If you are not the file owner or have
insufficient privilege, request that the file owner change the protection.

RMS$_QUO

Error in quoted string.

A-17

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_RAB

Not a valid RAB; block identifier field incorrect. This completion code is not
available in the RAB$L_STS/RAB$L_STV fields.

RMS$_RAC

Invalid value in record access mode field of RAB.

RMS$_RAT

Record attributes invalid in FAB.

RMS$_RBF

Invalid record address.

RMS$_REENT

An attempt to use the ACP enter function for new file specification failed after
the old file specification was removed, making it impossible to reenter the file
specification. Examine the STV field for additional information. The file could
not be renamed and recovery failed; the file has been lost.

RMS$_REF

Invalid key of reference in XAB; key of reference was greater than number in file
or equal to 255.

RMS$_RER

File read error; the STV field contains a system error code. Take corrective
action appropriate to the STV status code, if possible.

RMS$_REX

Record already exists; while inserting a record into a relative file using random
access mode, the specified record number is the same as an existing record; the
new record was not written over the existing record. Note the condition. Modify
the source program, if necessary, to detect and respond to this condition. You
may want to specify the RAB$L_ROP field RAB$V_UIF option.

RMS$_RFA

Invalid record file address contained in RAB.

RMS$_RFM

Invalid record format.

RMS$_RHB

Invalid or inaccessible record header buffer.

RMS$_RLF

Invalid or inaccessible related file block, or user has exceeded the limit of 255
related file name blocks, or related file name blocks are linked circularly.

RMS$_RLK

Target record currently locked by another stream; the requested record cannot
be accessed. Modify the source program, if necessary, to detect and respond
to this condition.

RMS$_RMV

ACP remove operation failed. The STV field contains an ACP error code. Take
corrective a<:tion appropriate to the STV status code, if possible.

RMS$_RNF

Record not found; the requested record in an indexed or relative file either was
never written or was deleted. Modify the source program, if necessary, to
detect and respond to this condition.

RMS$_RNL

Record not locked (warning); no records were locked for this record stream
when the operation was invoked. If necessary, modify the source program.

RMS$_ROP

Invalid record option.

RMS$_RPL

Error while reading prolog; the STV field contains an ACP error code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_RRF

See the VAX RMS Journaling Manual for details.

RMS$_RRV

Invalid RRV record encountered in indexed file; file may be corrupted.

RMS$_RSA

Record stream currently active (asynchronous operations); operation attempted
while an 1/0 request was outstanding for this record stream.

RMS$_RSL

Resultant string length field of NAM block invalid.

RMS$_RSS

Resultant string area size is too small.

RMS$_RST

Invalid resultant string area address in NAM block.

A-18

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_RSZ

Invalid record size.

RMS$_RTB

Record too large for user's buffer (warning); the record just returned was too
large for the user buffer provided. The RAB$L_STV field contains the size of
the record; the returned record is truncated to the size of the user buffer. Modify
the source program by increasing the size of the user buffer. You can determine
the size of the largest record in a file using the DCL command ANALYZE/RMS_
FILE or by examining the contents of the XABFHC field XAB$W _LRL after
opening the file with the XABFHC chained to the FAB.

RMS$_RUF

See the VAX RMS Journaling Manual for details.

RMS$_RUH

See the VAX RMS Journaling Manual for details.

RMS$_RU_ACTIVE

See the VAX RMS Journaling Manual for details.

RMS$_RUH

See the VAX RMS Journaling Manual for details.

RMS$_RVU

Error while updating RRVs; some paths to data may be lost. File reorganization
is strongly recommended.

RMS$_RUNDOWN

Operation invalid during RMS rundown.

RMS$_SEG

Segmented key for key data type other than string. The STV field contains the
key of reference.

RMS$_SEO

Primary key of record to be written is not equal to or greater than key of
previous record and RAB$B_RAC field is set to RAB$V_SEO.

RMS$_SHR

Invalid value in the file-sharing field of FAB. This condition can be caused by
attempting to access a sequential file that cannot be shared. (Only relative files,
indexed files, and sequential files with 512-byte fixed-length records can be
shared.)

RMS$_SIZ

Invalid key size specified in key definition XAB XAB$B_SIZO through XAB$B_
SIZ7 field; specified size exceeds maximum record size, not equal to defined
length on binary and integer key data types, greater than 16 for packed decimal
key data type, or equal to 0 for string or packed decimal. The STV field contains
the key of reference.

RMS$_SPL

Spool or submit command file option to a Close service failed; the STV field
contains a system error code. Take corrective action appropriate to the STV
status code.

RMS$_SQO

Operation not sequential; file was opened with FAB$L_FQP field FAB$V_SQO
option, random access is not permitted.

RMS$_STR

User structure (FAB/RAB) became invalid during the execution of a file or record
operation. This completion code is not available in the FAB$L_STS/FAB$L_
STV or RAB$L_STS/RAB$L_STV fields.

RMS$_SUC

Operation successful (synonym for RMS$_NORMAL).

RMS$_SUP

Network operation not supported; the STV field contains a OAP code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_SUPERSEDE

Created file supersedes existing version of same file; no action is required
(success).

RMS$_SUPPORT

Network operation not supported; the STV field contains a FAL/DAP status
code. Take corrective action appropriate to the STV status code, if possible.

RMS$_SYN

Syntax error in file specification.

A-19

VMS RMS Completion Status Codes

Table A-2 (Cont.)

Descriptions of VMS RMS Completion Status Codes

Status Code

Description

RMS$_SYS

Error in system 010 directive; the STV field contains the girective or 010 status
code. Take corrective action appropriate to the STV status code, if possible.

RMS$_TMO

Timeout period expired (terminal input, locked record, or mailbox devices,
warning); the Find, Get, or Read service did not complete. For terminal and
mailbox devices, the characters (if any) received before the timeout period
expired are discarded. For disk record operations, the requested record was
locked for the entire timeout period and was not read. Modify the source
program, if necessary, to detect this condition and retry the requested service.

RMS$_TMR

SETIMR system service request failed.

RMS$_TNS

Terminator not seen (terminals only; warning); the terminal Get service
terminated when the user buffer was filled to capacity, before a terminator
sequence was encountered. Subsequent Get services can retrieve additional
characters from that input line, including the terminator character sequence,
which is not in the current user buffer. Modify the source program to detect
and respond to this situation or provide a user buffer large enough to contain an
entire input line including the terminator character sequence.

RMS$_TOWDR

See the VAX RMS Journaling Manual for details.

RMS$_TRE

Index tree error; file is corrupted.

RMS$_TYP

Error in file type.

RMS$_UBF

Invalid user record buffer address.

RMS$_UNKRUFAC

See the VAX RMS Journaling Manual for details.

RMS$_UPI

The FAB$B_SHR field FAB$V_UPI option not set when file sharing FAB$L_FOP
field FAB$V_BIO or FAB$V_BRO option was set.

RMS$_USZ

Invalid user record area size.

RMS$_ VER

Error in version number.

RMS$_WBE

Error writing behind; the STV field contains a system error code. Take
corrective action appropriate to the STV status code, if possible.

RMS$_WCC

Invalid wildcard context value. Verify that the NAM block has not been
inadvertently modified between VMS RMS service calls.

RMS$_WER

File write error; the STV field contains a system error code. Take corrective
action appropriate to the STV status code, if possible.

RMS$_WLD

Invalid wildcard operation.

RMS$_WLK

Device currently write-locked when write access was attempted. Verify the
status of the device; reset the write-lock switch, if necessary. Notify the system
operator if the error cannot be corrected.

RMS$_WPL

Error while writing prolog; the STV field contains an ACP or system error code.
Take corrective action appropriate to the STV status code, if possible.

RMS$_WRT JNL_AIJ

See the VAX RMS Journaling Manual for details.

RMS$_WRTJNL_BIJ

See the VAX RMS Journaling Manual for details.

RMS$_ WRTJNL _RUJ

See the VAX RMS Journaling Manual for details.

RMS$_XAB

Not a valid XAB, not readable or writable, invalid code or length; the STV field
contains the XAB address.

RMS$_XNF

Could not locate XAB needed for this operation. Modify the source program
to include the XAB and specify the address of the XAB in the FAB$L_XAB or
RAB$L_XAB field.

A-20

RMS Control Block Macros

This appendix lists the format of each VMS RMS control block macro and
includes special syntax notes that differ from the rules provided in Part I.
Note that in this appendix the use of the term "macro" refers to a VAX
MACRO macro.

B-1

VMS RMS Control Block Macros
$FAB

$FAB
The $FAB macro allocates storage for a FAB and initializes certain FAB
fields with defaults and user-specified values. No value is returned for this
assembly-time operation.

FORMAT

$FAB

ALO= allocation-quantity,
BKS = bucket-size,
BLS =block-size,
CHAN_MODE =channel-access-mode
CTX = user-context-value,
DEQ = extension-quantity,
DNA = default-filespec-address,
DNM=<filespec>,
DNS = default-filespec-string-size,
FAC=<BIO BRO DEL GET PUT TRN UPD>,
FNA = filespec-string-address,
FNM = <filespec> ,
FNS = filespec-string-size,
<CBT CIF CTG DFW DL T
MXV NAM NEF NFS OFP
FOP= POS RCK RWC RWO SCF
SPL SQQ SUP TEF TMD
TMPUFO WCK>,
FSZ =header-size,
GBC =global-buffer-count,
LNM_MODE =logical-name-translationaccess-mode,
MRN = maximum-record-number,
MRS= maximum-record-size,
NAM= nam-address,
ORG= {

~{i_ } ,
SEQ

RAT= {

~~LK FTN> } ,
PRN

B-2

VMS RMS Control Block Macros
$FAB

FIX
STM
STMCR
RFM= STMLF
UDF
VAR
VFC
RTV = window-size,
SHR = <DEL GET MSE NIL PUT UPD UPI> ,
XAB = xab-address

ARGUMENTS

For a description of the control block fields that correspond to the $FAB
macro arguments, see Chapter 5. In some cases, specific default values are
assigned automatically when you omit an argument. If there is no specific
default, VMS RMS uses a default value of 0.
Arguments fall into three categories: values, addresses, and keywords. Rules
applicable to these argument categories are described in Chapter 3.
Note that multiple arguments can be specified for the FAC, FOP, RAT, and
SHR keywords, but the arguments must be enclosed within left angle ( <)
and right angle(> ) brackets. The DNM and FNM arguments must also be
delimited by these signs.
The DNM and FNM arguments contain ASCII characters and have no
corresponding field in the FAB. If the DNM argument is present, VMS RMS
places its appropriate address and size in the FAB$L_DNA and FAB$B_
DNS fields. Similarly, if the FNM argument is present, VMS RMS places its
appropriate address and size in the FAB$L_FNA and FAB$B_FNS fields.

B-3

VMS RMS Control Block Macros
$FAB_STORE

$FAB_STORE
The $FAB_STORE macro moves user-specified values into fields of the
specified FAB. The expanded $FAB_STORE code executes at run time
on a previously initialized (allocated) FAB, in contrast to the $FAB macro,
which initializes the FAB at assembly time. The $FAB~STORE macro must
reside in a code program section.

FORMAT

$FAB_STORE

tab= tab-address,
ALQ =#allocation-quantity,
BKS =#bucket-size,
BLS =#block-size,
CHAN_MODE = #channel-access-mode
CTX = user-context-value,
DEQ =#extension-quantity,
DNA = default-filespec-address,
DNS = #default-filespec-string-size,
FAC= <BIO BRO DEL GET PUT TRN
UPD>,
FNA = filespec-string-address,
FNS = #filespec-string-size,
<CBT CIF CTG DFW DL T
MXV NAM NEF NFS OFP
FOP= POS RCK RWC RWO SCF
SPL SQQ SUP TEF TMD
TMPUFO WCK>,
FSZ =#header-size,
GBC =#global-buffer-count,
LNM_MODE = #logical-nametranslation-access-mode,
MRN = #maximum-record-number,
MRS= #maximum-record-size,
NAM= nam-address,
ORG=

{~ft_ },
SEQ

RAT={~~LKFTN> },
PRN

B-4

VMS RMS Control Block Macros
$FAB_STORE
FIX
STM
STMCR
RFM= STMLF
UDF
VAR
VFC
RTV =#window-size,
SHR =<DEL GET MSE NIL PUT UPD
UPI>
XAB = xab-address
I

ARGUMENTS

For a description of the control block fields that correspond to the $FAB_
STORE macro arguments, see Chapter 5.
Arguments fall into several categories: values, addresses, keywords, and
the address of the control block to receive the specified arguments. Rules
applicable to these argument categories for the control block store macros are
described in Chapter 3.
The FAB argument £ab-address is required for the $FAB_STORE macro and
is not present for the $FAB macro. Conversely, the DNM argument filespec
and FNM argument default-filespec are not available for the $FAB_STORE
macro, although you can use the DNA/DNS and FNA/FNS arguments to
specify file specifications at run time.
Note that RO is usually used by the $FAB_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-5

VMS RMS Control Block Macros
$NAM

$NAM
The $NAM macro allocates storage for a NAM block and initializes certain
NAM fields with default values and user-specified values. No value is
returned for this assembly-time operation.

FORMAT

$NAM

ARGUMENTS

For a description of the control block fields that correspond to the $NAM
macro arguments, see Chapter 6.

ESA =expanded-string-address,
ESS = expanded-string-size,
_ <NOCONCEAL PWD
NOP- SRCHXABS SYNCHK>,
RLF = related-file-nam-block-address,
RSA = resultant-string-address,
RSS =resultant-string-size

Arguments fall into three categories: values, addresses, and keywords. Rules
applicable to these argument categories are described in Chapter 3.
Note that multiple arguments can be specified for the NOP keyword, but
the arguments must be enclosed within left angle ( <) and right angle (> )
brackets.

B-6

VMS RMS Control Block Macros
$NAM_STORE

$NAM_STORE
The $NAM_STORE macro moves user-specified values into fields of the
specified NAM block. The expanded $NAM_STORE code executes at
run time on a previously initialized (allocated) NAM block, in contrast to
the $NAM macro, which initializes a NAM block at assembly time. The
$NAM_STORE macro must reside in a code program section.

FORMAT

$NAM_STORE

NAM= nam-address,
DID= #directory-identification,
DVI =#device-identification,
ESA = expanded-string-address,
ESS =#expanded-string-size,
FID =#file-identification,
_ <NOCONCEAL PWD
NOP- SRCHXABS SYNCHK>
RLF = related-file-nam-block-address,
RSA =resultant-string-address,
RSS = #resultant-string-size
I

ARGUMENTS

For a description of the control block fields that correspond to the $NAM_
STORE macro arguments, see Chapter 6.
Arguments fall into several categories: values, addresses, keywords, and
the address of the control block to receive the specified arguments. Rules
applicable to these argument categories for the control block store macros are
described in Chapter 3.
The NAM argument nam-address is required for the $NAM_STORE macro
and is not present for the $NAM macro. Also, the $NAM_STORE argument
fields below are not available for the $NAM macro.
•

The DID argument directory-identification sets the NAM$W_DID field,
which is a 3-word field used when the FAB$L_FOP field FAB$V_NAM
option is set. This argument is usually specified by its symbolic address.
If a register is used to contain a value for the NAM$W_DID field, do
not use Rl2, because two contiguous registers must be used to contain
the value of this 3-word field. Note that you cannot use the byte, word,
or longword displacements for an offset, or for indexed or deferred
addressing.

•

The DVI argument device-identification sets the NAM$T_DVI field,
which is a 16-byte field used when the FAB$L_FOP field FAB$V_NAM
option is set. This argument must be passed by its symbolic address. A
register must not be specified to contain a value for this argument.

B-7

VMS RMS Control Block Macros
$NAM_STORE

•

The FID argument file-identification sets the NAM$W_FJD field, which
is a 3-word field used when the FAB$L_FOP field FAB$V_NAM option
is set. This argument is specified by its symbolic address. If a register
is used to contain a value for the NAM$W_FID field, do not use Rl2,
because two contiguous registers must be used to contain the value of
this 3-word field. Note that you cannot use the byte, word, or longword
displacements for an offset, or for indexed or deferred addressing.

Note that RO is usually used by the $NAM_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-8

VMS RMS Control Block Macros
$RAB

$RAB
The $RAB macro allocates storage for a RAB and initializes certain RAB
fields with defaults and user-specified values. You cannot use this macro
within a sequence of executable instructions. No value is returned for this
assembly-time operation.

FORMAT

$RAB

BKT =bucket-code-number,
CTX =user-context-value,
FAB =tab-address,
KBF = key-buffer-address,
KRF = key-of-reference-number,
KSZ =key-size,
MBC = multiblock-count-number,
MBF = multibuffer-count-number,
PBF =prompt-buffer-address,
PSZ =prompt-buffer-size,
RAC= {

~~~ } ,

SEQ
RBF = record-buffer-address,
RHB= record-header-buffer-address,
<ASY BIO CCO CVT EOF EQNXT
ETO FOL KGE KGT UM LOA
ROP =LOG NLK NXR NXT PMT PTA
RAH REA RLK RNE RNF RRL
TMO TPT UIF ULK WAT WBH>,
RSZ =record-size,
TMO = time-out-number-of-seconds,
UBF = user-record-buffer-address,
USZ =user-record-buffer-size,
XAB = xab-address

B-9

VMS RMS Control Block Macros
$RAB

ARGUMENTS

For a description of the control block fields that correspond to the $RAB
macro arguments, see Chapter 7. In some cases, specific default values are
assigned automatically when you omit an argument. These specific defaults
are noted in the text that explains each field in Chapter 7. If there is no
specific default, VMS RMS uses a default value of 0.
Arguments fall into three categories: values, addresses, and keywords. Rules
applicable to these argument categories are described in Chapter 3.
Note that multiple arguments can be specified for the ROP keyword, but
the arguments must be enclosed within left angle ( <) and right angle
(> ) brackets. Note too that the arguments KGE and EQNXT are logically
synonymous, as are the arguments KGT and NXT.

B-10

VMS RMS Control Block Macros
$RAB_STORE

$RAB_STORE
The $RAB_STORE macro moves user-specified values into fields of the
specified RAB. The expanded $RAB_STORE code executes at run time
on a previously initialized (allocated) RAB, in contrast to the $RAB macro,
which initializes the RAB at assembly time. The $RAB_STORE macro
must reside in a code program section.

FORMAT

$RAB_STORE

RAB= rah-address,
BKT =#bucket-code-number,
CTX = user-context-value,
FAB= tab-address,
KBF = key-buffer-address,
KRF = #key-of-reference-number,
KSZ = #key-size,
MBC = #multiblock-count-number,
MBF = #multibuffer-count-number,
PBF =prompt-buffer-address,
PSZ =#prompt-buffer-size,

RAC={~~~},

SEQ
RBF =record-buffer-address,
RFA =#record-file-address,
RHB= record-header-buffer-address,
<ASY BIO
CVT
EOF EQNXT ETO FOL
KGE KGT LIM LOA
ROP = LOC NLK NXR NXT
PMT PTA RAH REA
RLK RNE RNF RRL
TMO TPT UIF ULK
WATWBH>,
RSZ =#record-size,
TMO = #time-out-number-ofseconds,
UBF = user-record-buffer-address,
USZ = #user-record-buffer-size,
XAB = xab-address

CCO

B-11

VMS RMS Control Block Macros
$RAB_STORE

ARGUMENTS

For a description of the control block fields that correspond to the $RAB_
STORE macro arguments, see Chapter 7.
Arguments fall into several categories: values, addresses, keywords, and
the address of the control block to receive the specified arguments. Rules
applicable to these argument categories for the control block store macros are
described in Chapter 3.
The RAB argument rab-address is required for the $RAB_STORE macro
and is not present for the $RAB macro. Also, the RFA argument recordfile-address is a value (not an address), and it is not available for the $RAB
macro. The value for the 3-word RAB$W_RFA field must be set before each
RFA record access.
This argument is specified by its symbolic address. If a register is used to
contain a value for the RAB$W_RFA field, do not use R12, because two
contiguous registers must be used to contain the value of this 3-word field.
Note that you cannot use the byte, word, or longword displacements for an
offset, or for indexed or deferred addressing.
Note that multiple arguments can be specified for the ROP keyword, but
the arguments must be enclosed within left angle ( <) and right angle
(> ) brackets. Note too, that the arguments KGE and EQNXT are logically
synonymous as are the arguments KGT and NXT.
Note that RO is usually used by the $RAB_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-12

VMS RMS Control Block Macros
$XABALL

$XABALL
The $XABALL macro allocates and initializes an XABALL, which allows
extended control of file disk space allocation, both for initial allocation and
later extension. No value is returned for this assembly-time operation.

FORMAT

$XABALL

ARGUMENTS

For a description of the control block fields that correspond to the $XABALL
macro arguments, see Chapter 8.

AID= area-identification-number,
ANY
CYL
ALN= LBN
RF/
VBN
ALO= allocation-quantity,
AOP=<CBTCTG
HRDONC>,
BKZ =bucket-size,
DEQ = extension-quantity,
LOC =location-number,
NXT = next-xab-address,
RF/= <f(1 ), f(2), f(3)> ,
VOL = volume-number

Arguments fall into three categories: values, addresses, and keywords. Rules
applicable to these argument categories are described in Chapter 3.
Note that multiple arguments can be specified for the AOP keyword, but
the arguments must be enclosed within left angle ( <) and right angle (> )
brackets.

B-13

VMS RMS Control Block Macros
$XABALL_STORE

$XABALL_STORE
The $XABALL_STORE macro moves user-specified values into fields of
the specified XABALL. The expanded $XABALL _STORE code executes
at run time on a previously initialized (allocated) XABALL, in contrast to
the $XABALL macro, which initializes an XABALL at assembly time. The
$XABALL_STORE macro must reside in a code program section.

FORMAT

$XABALL_STORE

ARGUMENTS

For a description of the control block fields that correspond to the $XABALL _
STORE macro arguments, see Chapter 8.

XAB = xaball-address,
AID= #area-identification-number,
ANY
CYL
ALN= LBN
RF/
VBN
ALO = #allocation-quantity,
AOP=<CBTCTG
HRDONC>,
BKZ =#bucket-size,
DEQ = #extension-quantity,
LOG= #location-number,
NXT = next-xab-address,
RF/= #related-file-identification,
VOL = #volume-number

Arguments fall into several categories: value, address, keyword, and the
address of the control block to receive the specified arguments. Rules
applicable to these argument categories for the control block store macros
are described in Chapter 3.
The XAB argument xaball-address is required for the $XABALL _STORE
macro and is not present for the $XABALL macro. Also, the RFI argument
related file identification sets the XAB$W_RFI field, which is a 3-word field
used when the XAB$B_ALN field XAB$V_RFI option is set. This argument
is usually specified by its symbolic address. If a register is used to contain
a value for the XAB$W_RFI field, do not use Rl2, because two contiguous
registers must be used to contain the value of this 3-word field. Note that
you cannot use the byte, word, or longword displacements for an offset, or
for indexed or deferred addressing.
Note that RO is usually used by the $XABALL_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-14

VMS RMS Control Block Macros
$XABDAT

$XABDAT
The $XABDAT macro allocates and initializes an XABDAT. No value is
returned for this assembly-time operation.

FORMAT

$XABDAT

ARGUMENTS

For a description of the control block fields that correspond to the $XABDAT
macro arguments, see Chapter 8.

EDT= date-time,
NXT = next-xab-address

Rules applicable to arguments are described in Chapter 3.

B-15

VMS RMS Control Block Macros
$XABDAT_STORE

$XABDAT_STORE
The $XABDA T_STORE macro moves user-specified values into fields of
the specified XABDA T. The expanded $XABDA T_STORE code executes
at run time on a previously initialized (allocated) XABDA T, in contrast to
the $XABDA T macro, which initializes an XABDA T at assembly time. The
$XABDAT_STORE macro must reside in a code program section.

FORMAT

$XABDAT_STORE

ARGUMENTS

For a description of the control block fields that correspond to the $XABDAT_
STORE macro arguments, see Chapter 8.

XAB = xabdat-address,
CDT= #creation-date-time,
EDT= #expiration-date-time,
ROT= #revision-date-time,
RVN =#revision-number,
NXT = next-xab-address

The CDT argument creation-date-time sets the XAB$Q _CDT field,
which is a quadword field. However, if a register is used to contain a
literal value for the XAB$Q_CDT field, do not use Rl2, because two
contiguous registers must be used to contain the value of this quadword
field.

•

The EDT argument expiration-date-time sets the XAB$Q _EDT field,
which is a quadword field. The rules for the other time fields (see above)
also apply to this one.

•

The RDT argument revision-date-time sets the XAB$Q _CDT field,
which is a quadword field. The rules for the other time fields (see above)
also apply to this one.

Note that RO is usually used by the $XABDAT_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-16

VMS RMS Control Block Macros
$XABFHC

$XABFHC
The $XABFHC macro allocates and initializes an XABFHC. No value is
returned for this assembly-time operation.

FORMAT

$XABFHC

ARGUMENTS

For a description of the control block fields that correspond to the $XABFHC
macro arguments, see Chapter 10.

NXT = next-xab-address

Rules applicable to arguments are described in Chapter 3.

B-17

VMS RMS Control Block Macros
$XABFHC_STORE

$XABFHC_STORE
The $XABFHC_STORE macro moves user-specified values into fields of
the specified XABFHC. The expanded $XABFHC_STORE code executes
at run time on a previously initialized (allocated) XABFHC, in contrast to
the $XABFHC macro, which initializes an XABFHC at assembly time. The
$XABFHC_STORE macro must reside in a code program section.

FORMAT

$XABFHC_STORE

ARGUMENTS

For a description of the control block fields that correspond to the $XABFHC_
STORE macro arguments, see Chapter 10.

XAB = xabfhc-address,
NXT = next-xab-address

B-18

VMS RMS Control Block Macros
$XABITM

$XABITM
The $XABITM macro allocates and initializes an XABITM. No value is
returned for this assembly-time operation.

FORMAT

$XABITM

ARGUMENTS

For a description of the control block fields that correspond to the $XABITM
macro arguments, see Chapter 11.

ITEMLIST =item-list-address,
MODE= { sensemode } ,
setmode
NXT = next-xab-address

Rules applicable to arguments are described in Chapter 3.
ITEMLIST defaults to 0 but a valid pointer must be specified when you use a
$XABITM macro. MODE defaults to sensemode.

B-19

VMS RMS Control Block Macros
$XABKEY

$XABKEY
The $XABKEY macro allocates and initializes an XABKEY. No value is
returned for this assembly-time operation.

FORMAT

B-20

$XABKEY

COL TBL =collating-table-address,
DAN= data-bucket-area-number,
DFL =data-bucket-fill-size,
BN2
DBN2
BN4
DBN4
BNB
DBNB
IN2
DIN2
DTP= IN4
DIN4
/NB
DINB
COL
DCOL
PAC
DPAC
STG
DSTG
<CHG DAT_NCMPR DUP
FLG = IDX_NCMPR
KEY_NCMPR NUL> ,
/AN= index-bucket-area-number,
/FL =index-bucket-file-size,
KNM =key-name-buffer-address,
LAN= lowest-level-index-area-number,
NUL = null-key-value,
NXT = next-xab-address,
POS=<position, ... >,
PROLOG = prolog-level,
REF= key-of-reference-value,
S/Z =<size, ... >

VMS RMS Control Block Macros
$XABKEY

ARGUMENTS

For a description of the control block fields that correspond to the $XABKEY
macro arguments, see Chapter 13.
Arguments fall into three categories: values, addresses, and keywords. Rules
applicable to these argument categories are described in Chapter 3.
Multiple arguments can be specified for the FLG keyword, but the arguments
must be enclosed within left angle ( <) and right angle (> ) brackets.
Defaults are applied to the XAB$B_FLG field only if no FLG argument is
specified. Consider the following:
KEY_1:

$XABKEY REF = 1, POS = 0, SIZ = 10

This line specifies the key for alternate index 1. Therefore the macro defaults
the XAB$B_FLG field to allow duplicates and changes (the default for
alternate keys). However, if an FLG argument is explicitly specified, the
results are different, as shown below.
KEY_2:

$XABKEY REF = 1, POS = 0, SIZ = 10, FLG = CHG

In this case, the CHG bit is set in the XAB$B_FLG field and the DUP bit
remains clear, to disallow duplicates on this key.
Depending on whether the key being defined is simple or segmented, you
would use one of the following two formats for the POS and SIZ arguments:
POS = position

SIZ = size

or
POS ~positionO, ... ,position7>

SIZ ~sizeO, ... ,size7>

You must include the angle brackets for multiple argument key positions and
sizes.

B-21

VMS RMS Control Block Macros
$XABKEV_STORE

$XABKEV_STORE
The $XABKEY_STORE macro moves user-specified values into fields of
the specified XABKEY. The expanded $XABKEY_STORE code executes
at run time on a previously initialized (allocated) XABKEY, in contrast to
the $XABKEY macro, which initializes the XABKEY at assembly time. The
$XABKEY_STORE macro must reside in a code program section.

FORMAT

B-22

$XABKEV_STORE

XAB = xabkey-address,
COL TBL =#collating-table-address,
DAN= #data-bucket-area-number,
DFL =#data-bucket-fill-size,
BN2
DBN2
BN4
DBN4
BNB
DBNB
IN2
DIN2
DTP= IN4
DIN4
/NB
DINB
COL
DCOL
PAC
DPAC
STG
DSTG
<CHG DAT_NCMPR
FLG = DUP IDX_NCMPR
KEY_NCMPR NUL> ,
/AN= #index-bucketarea-number,
/FL =#index-bucket-fill-size,
KNM = key-name-bufferaddress,
LAN= #lowest-level-indexarea-number,
NUL =#null-key-value,
NXT = next-xab-address,

VMS RMS Control Block Macros
$XABKEV_STORE

POS = <position, ... > ,
PROLOG = #prolog-Jevel,
REF= #key-of-reference-value,
SJZ=<size, ... >

ARGUMENTS

For a description of the control block fields that correspond to the $XABKEY_
STORE macro arguments, see Chapter 13.
Arguments fall into several categories: values, addresses, keywords, and
the address of the control block to receive the specified arguments. Rules
applicable to these argument categories for the control block store macros are
described in Chapter 3.
The XAB argument xabkey-address is required for the $XABKEY_STORE
macro and is not present for the $XABKEY macro. The POS and SIZ
arguments can be either symbolic addresses or a list of up to eight
values, where each value must be preceded by a number sign ( # ), and
the entire list must be enclosed within left angle and right angle brackets
( <#value, ... ,#value> ). The number of POS and SIZ values must be equal.
Alternatively, each POS and SIZ value can be specified as an argument, using
the following form:
POSO

#value, POS1

#value,

POS7

#value

SIZO

#value, SIZ1

#value,

SIZ7

#value

Note that RO is usually used by the $XABKEY_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-23

VMS RMS Control Block Macros
$XABPRO

$XABPRO
The $XABPRO macro allocates and initializes an XABPRO. No value is
returned for this assembly-time operation.

FORMAT

$XABPRO

ARGUMENTS

For a description of the control block fields that correspond to the $XABPRO
macro arguments, refer to Chapter 14.

AGLBUF= AGL-buffer-address,
AGLGTX=<AGL-context>,
AGLSIZ =AGL-buffer-size,
MTAGG =magnetic-tapeaccessibility,
NXT = next-xab-address,
PRO= <system, owner,
group, world> ,
PROT_OPT=<PROPAGATE>,
UIG=<group, member>

Rules applicable to arguments are described in Chapter 3.
For the MTACC argument, an ASCII radix indicator is required. For example,
the letter Z is entered as the accessibility character with the following macro
expression:
$XABPRO

MTACC = ~A/Z/

In this example, the circumflex (A) followed by an uppercase A (A A) indicates
that ASCII text follows. The two slashes ( / /) delimit the ASCII text. VMS
RMS converts all lowercase characters to uppercase. No other modification is
made.
For the PRO argument, the angle brackets are required syntax, and each
user class must be separated from the others by a comma. When you omit a
class to use the default protection, you must retain the comma to indicate the
omission, unless no other class follows.
To allow all system users read and write access, use the default file protection
for the file owner (by omission), allow group users read access, and use the
default for world users, you would specify <RW,,R> . You may specify all,
some, or none of the access characters and place multiple characters in any
order, for each user class.

B-24

VMS RMS Control Block Macros
$XABPRO

Here is a listing of the user classes together with the letters used to represent
them:
•

R-read access

•

W-write access

•

E-execu te access

•

D-delete access

The absence of a code specifies that the access associated with the code is
denied to the user.
A user is granted the maximum number of access rights for each of the classes
to which he belongs.
For the UIC argument, the value for the group item must be in the range
of 0 to 37777; the value for the member item must from 0 to 177777. Note
that the maximum values (37777 and 177777) are reserved for DIGITAL use
only. The group number and member number must be enclosed within angle
brackets, placed in the order <group,member> , and be separated by a
comma. Each number is interpreted as an octal number.

B-25

VMS RMS Control Block Macros
$XABPRO_STORE

$XABPRO_STORE
The $XABPRO_STORE macro moves user-specified values into fields of
the specified XABPRO. The expanded $XABPRO_STORE code executes
at run time on a previously initialized (allocated) XABPRO, in contrast to
the $XABPRO macro, which initializes an XABPRO at assembly time. The
$XABPRO_STORE macro must reside in a code program section.

FORMAT

$XABPRO_STORE

ARGUMENTS

For a description of the control block fields that correspond to the $XABPRO_
STORE macro arguments, see Chapter 14.

XAB = xabpro-address,
AGLBUF =AGL-buffer-address,
AGLGTX=#<AGL-context>,
AGLSIZ =#AGL-buffer-size,
MTAGG = #magnetic-tapeaccessibility,
NXT = next-xab-address,
PRO=< system, owner,
group, world> ,
PROT_OPT=<PROPAGATE>,
UIG = #uic-value

The PRO argument (file protection) can be either a symbolic address
or a list of keyword values. If you specify a list of keywords, it
must be enclosed within left angle ( <) and right angle (> ) brackets
and the number sign ( # ) must be omitted; for example, PRO =
<RWED,RWED,R,R>.

•

The VIC argument (group,member) can be either a symbolic address
or a list of two data values. If the data values are constants, they must
be specified with an octal radix without a preceding number sign ( # ).
This argument can be passed by its symbolic address or by using a VAX
MACRO expression.

Note that RO is usually used by the $XABPRO_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-26

VMS RMS Control Block Macros
$XABRDT

$XABRDT
The $XABRDT macro allocates and initializes an XABRDT. No value is
returned for this assembly-time operation.

FORMAT

$XABRDT

ARGUMENTS

For a description of the control block fields that correspond to the $XABRDT
macro argument, see Chapter 15.

NXT= next-xab-address

Rules applicable to arguments are described in Chapter 3.

B-27

VMS RMS Control Block Macros
$XABRDT_STORE

$XABRDT_STORE
The $XABRDT_STORE macro moves user-specified values into fields of
the specified XABRDT. The expanded $XABRDT_STORE code executes
at run time on a previously initialized (allocated) XABRDT, in contrast to
the $XABRDT macro, which initializes the XABRDT at assembly time. The
$XABRDT_STORE macro must reside in a code program section.

FORMAT

$XABRDT_STORE

ARGUMENTS

For a description of the control block fields that correspond to the $XABRDT_
STORE macro arguments, see Chapter 15.

XAB = xabrdt-address,
ROT= #revision-date-time,
RVN =#revision-number,
NXT = next-xab-address

Arguments fall into several categories: values, addresses, keywords, and
the address of the control block to receive the specified arguments. Rules
applicable to these argument categories for the control block store macros are
described in Chapter 3.
The XAB argument xabrdt-address is required for the $XABRDT_STORE
macro and is not present for the $XABRDT macro. Also, the RDT argument
revision-date-time and RVN argument revision-number are not present
in the $XABRDT macro. The RDT argument revision-date-time is usually
passed by its symbolic address. However, if a register is used to contain a
value for the XAB$Q _RDT field, do not use R12, because two contiguous
registers must be used to contain the· value of this quadword field.
Note that RO is usually used by the $XABRDT_STORE macro; thus, RO is not
preserved and does not contain a return status.

B-28

VMS RMS Control Block Macros
$XABSUM

$XABSUM
The $XABSUM macro allocates and initializes an XABSUM. No value is
returned for this assembly-time operation.

FORMAT

$XABSUM

ARGUMENTS

For a description of the control block fields that correspond to the $XABSUM
macro argument, see Chapter 17.

NXT= next-xab-address

Rules applicable to arguments are described in Chapter 3.

B-29

VMS RMS Control Block Macros
$XABSUM_STORE

$XABSUM_STORE
The $XABSUM_STORE macro moves user-specified values into fields of
the specified XABSUM. The expanded $XABSUM_STORE code executes
at run time on a previously initialized (allocated) XABSUM, in contrast to
the $XABSUM macro, which initializes the XABSUM at assembly time.
The $XABSUM_STORE macro must reside in a code program section.

FORMAT

$XABSUM _STORE

ARGUMENTS

For a description of the control block fields that correspond to the
$XABSUM_STORE macro arguments, see Chapter 17.

XAB = xabsum-address,
NXT = next-xab-address

B-30

VMS RMS Control Block Macros
$XABTRM

$XABTRM
The $XABTRM macro allocates and initializes an XABTRM. No value is
returned for this assembly-time operation.

FORMAT

$XABTRM

ARGUMENTS

For a description of the control block fields that correspond to the $XABTRM
macro arguments, see Chapter 18.

ITMLST =item-list-address,
ITMLST_LEN= item-list-length,
NXT = next-xab-address

Rules applicable to arguments are described in Chapter 3.

B-31

VMS RMS Control Block Macros
$XABTRM_STORE

$XABTRM_STORE
The $XABTRM_STORE macro moves user-specified values into fields of
the specified XABTRM. The expanded $XABTRM_STORE code executes
at run time on a previously initialized (allocated) XABTRM, in contrast to
the $XABTRM macro, which initializes an XABTRM at assembly time. The
$XABTRM_STORE macro must reside in a code program section.

FORMAT

$XABTRM_STORE

ARGUMENTS

For a description of the control block fields that correspond to the
$XABTRM_STORE macro arguments, see Chapter 18.

XAB = xabtrm-address,
ITMLST = item-list-address,
ITMLST_LEN= #item-list-length,
NXT = next-xab-address

B-32

Index
Argument (cont'd.)

A
Access
modes• 1-1
run-time options• 1-2
Access control list
See ACL
Access control list buffer field
See XAB$L_ACLBUF field
Access control list buffer size field
See XAB$W _ACLSIZ field
Access control list context field
See XAB$L_ACLCTX field
Access control list error status field
See XAB$L_ACLSTS field
Access control list length field
See XAB$W _ACLLEN field
Access specification
list of mask values• 14-6
ACE (access control list)
VMS RMS limitation• 14-2
ACL (access control list)
conversion methods• 14-2
use with VMS RMS control block• 14-2
Actual offset value
avoiding use of• 2-4
Alignment boundary type field
See XAB$B_ALN field
Allocation control extended address block
See XABALL block
Allocation options field
See XAB$B_AOP field
Allocation quantity field
See FAB$L_ALO field
Area allocation quantity field
See XAB$L _ALO field
Area default extension quantity field
See XAB$W_DEO field
Area identification number (AID)
program example• 4-8
Area identification number field
See XAB$B_AID field
Argument
delimiters• 3-10

initialization and control block store macros•

3-8
passing• 1-2
separator• 3-6
specifying as run-time values• 3-9
to FAB• 1-2
to RAB• 1-4
Argument keyword
delimiting for service• 3-10
Argument list
count field• 2-5
description• 2-4
error routine address field• 2-5
new FAB address field• 2-5
passing to service• 3-10
success routine address field• 2-5
ASCII character
delimiting in control block fields• 3-6, 3- 7
Asynchronous 1/0 option
See FAB$V_ASY
See RAB$V_ASY option
Asynchronous operation
contrasted with synchronous operation• 2- 7
using RO• 2-5

B
Backup date and time field
See XAB$Q_BDT field
BID field
See Block identifier field
BLN field
See Block length field
Block boundary option
See FAB$V_BLK option
Block code field
See XAB$B_COD field
Block 1/0
additional services that use• 4-23
applicable services• 4-23
description• 4-23
how to execute• 4-24
how to specify for relative and indexed files•

4-24

lndex-1

Index

Block 1/0 (cont'd.)
program example• 4-25
requirements for mixing with record 1/0 • 4-23
restrictions to• 4-23
services • 3-5
specifying• 4-23
use of NBP for sequential files• 4-25
with multiple record streams• 4-25
with record 1/0 processing• 4-25
Block 1/0 execution
contrasted with record 1/0 execution• 4-24
Block 1/0 option
See FAB$V_BIO option
See RAB$V_BIO option
Block identifier field
See FAB$B_BID field
See NAM$B_BID field
See RAB$B_BID field
Block length field

Bucket size field
See FAB$B_BKS field
Bucket size field in allocation XAB
See XAB$B_BKZ field
Bucket size field in file header characteristics XAB
See XAB$B_BKZ field
Bucket split
minimizing• 13-4
BYTLM quota
limiting size of user's ACL buffer• 14-3

c
Caller access mode• 5-5
Calling sequence• 2-4
Calling services• 1-1
Cancel CTRL/O option

See NAM$B_BLN field
Block length field in allocation XAB

See RAB$V_CCO option
Carriage return option

See XAB$B_BLN field
Block length field in date and time XAB
See XAB$B_BLN field
Block length field in file access block

See FAB$V_CR option
CDT argument• B-16
Channel access mode protection option• 5-5
Channel access mode subfield
See FAB$V_CHAN_MODE

See FAB$B_BLN field
Block length field in file header characteristics XAB
See XAB$B_BLN field
Block length field in item list XAB
See XAB$B_BLN field
Block length field in key XAB
See XAB$B_BLN field
Block length field in protection XAB
See XAB$B_BLN field
Block length field in record access block
See RAB$B_BLN field
Block length field in revision date and time XAB
See XAB$B_BLN field
Block length field in summary XAB
See XAB$B_BLN field
Block length field in terminal XAB
See XAB$B_BLN field
Block or record 1/0 option
See FAB$V_BRO option
Bucket boundary
file organization considerations• 5-4
Bucket code field
See RAB$L _BKT field

lndex-2

See FAB$V_CHAN_MODE subfield
CHG (change) option
in XAB$B_FLG field• B-2 1
Close service
condition values• RMS-5
See also Completion status codes
contrasted with Disconnect service• 4-5
control block input fields• RMS-4
control block output fields• RMS-4
function• 4-1
introduction• 4-1
limitations with XABs • RMS-4
use restrictions• RMS-4
Collating key data type• 13-6
Collating sequence name field
See XAB$L _COLNAM field
Collating sequence size field
See XAB$L _COLSIZ field
Collating sequence table field
See XAB$L _COL TBL field
Comment separator• 3-6
Completion routine
condition for AST execution • 3-11
service macro arguments• 3-11

Index

Completion status code
description• 2-5, A-9 to A-20
errors for inaccessible control block condition•
2-6
handling• 3-12
hexadecimal values• A-2 to A-9
listing conditions when not returned• A-2
severity codes• 2-6
testing• 2-5
Completion status code field
use with debugger• A-2
Completion status code field in FAB
See FAB$L _STS field
Completion status code field in RAB
See RAB$L _STS field
Completion status code value field
use with debugger• A-2
Completion status field
See also FAB$L _STS field
as alternative to use of RO• 2-4
for signaling errors• 2-6
Completion status value field
as alternative to use of RO• 2-4
for signaling errors• 2-6
Completion status value field in FAB
See FAB$L _STV field
Completion status value field in RAB
See RAB$L _STV field
Condition value
See Completion status code
Connect service• RMS-6
comparing positioning for various file
organizations• RMS-7
condition values• RMS-9
connecting record stream• 4-4
control block input fields• RMS- 7
control block output fields • RMS-8
program example• 4-12
use with multiple keys• 4-12
Contiguous best try option
See FAB$V_CBT option
Contiguous option
See also FAB$V_CTG option
See FAB$V_CTG option
Continuation character• 3-6
Control block
dual purpose• 1-4
field name conventions• 2-2
for extended attributes• 1-3
for file name operations• 1-3

Control block (cont'd.)
for file services• 1-2
for record services• 1-4
macro names• 3-2
requirements for valid default values• 1-4
symbolic bit offset• 2-4
symbolic constant (keyword) value• 2-4
symbolic naming exceptions• 2-3
symbolic offsets• 2-2
types of macros• 3-1
use restrictions• 2-1
use with VAX languages• 2-1
Control block store macro
description• 3-1
example• 3-9
placement guidelines• 3-8
requirement for number sign• 3-8
use of RO• 3-8
Control routine• 4-27
CONVERT command• 4-9
Convert option
See RAB$V_CVT option
CREA TE/FDL command• 4-9
Create-if option• 4-1
See also FAB$V_CIF option
$CREA TE macro• 3-10
Create service• RMS-1 O
condition values• RMS-19
contrasted with Open service• 4-1
control block input fields• RMS-11
control block output fields• RMS-1 5
function• 4-1
handling search list• RMS-11
invoking • 4-1
program example• 4-2
prolog level • RMS-1 8
using the create-if option • RMS-1 7
using the NAM block• RMS-16
using to create indexed files• RMS-18
XAB override in various fields• RMS-11
Creation date and time field
See XAB$Q_CDT field
CTRL/Z
using as end-of-file marker• RMS-49
using to terminate Get service• RMS-49
Current position option
See FAB$V_POS option

lndex-3

Index

D
DAP (data access protocol)• 1-1
Data access protocol
See DAP
Data bucket area number (DAN)
program example• 4-8
Data bucket area number field
See XAB$B_DAN field
Data bucket fill size (DFL)
program example• 4-8
Data bucket fill size field
See XAB$W _DFL field
Data bucket size field
See XAB$B_DBS field
Data level
comparing for primary and alternate keys• 13-4
Data type of key field
See XAB$B_DTP field
Date and time extended address block
See XABDA T block
Debugger
use with completion status codes• A-2
DEC Multinational Character Set
using•2-7
DECnet remote file access
specifying maximum record size• 5-22
Default extension quantity field
See FAB$W_DEQ field
Default file extension quantity field in XABFHC
See XAB$W_DXQ field
Default file specification string address field
See FAB$L _DNA field
Default file specification string size field
See FAB$B_DNS field
Default global buffer count field
See XAB$W _GBC field
Deferred write option
See FAB$V_DFW option
Delete on close option
See FAB$V_DLT option
Delete service• RMS-21
condition values• RMS-22
See also Completion status codes
control block input fields• RMS-22
control block output fields• RMS-22
program example• 4-19
requirements• RMS-22
use restrictions• RMS-2 1

lndex-4

Delete service option
See FAB$V_DEL option
Delete sharing option
See FAB$V_SHRDEL option
Delimiter
using in control block arguments• 3-5, 3-6,
3-7
$DEVDEF macro
source of DEV field bit definitions• 5-7
Device characteristics field
See FAB$L_DEV field
Device identification field
See NAM$T_DVI field
Device name address descriptor
See NAM$L _DEV descriptor
Device name address field
See NAM$L _DEV field
Device name length field
See NAM$B_DEV field
Device name size descriptor
See NAM$B_DEV descriptor
Directory address descriptor
See NAM$L_DIR descriptor
Directory identification field
See NAM$W_DID
Directory name length address field
See NAM$L_DIR field
Directory name length field
See NAM$B_DIR field
Directory size descriptor
See NAM$B_DIR descriptor
Disconnect service• RMS-23
condition values• RMS-24
See also Completion status codes
control block input fields• RMS-24
control block output fields• RMS-24
program example• 4-12
using with multiple RABs • RMS-24
Disk cluster boundary
determining allocation quantity• 5-3
Display service• RMS-25
condition values• RMS-28
control block input fields• RMS-26
control block output fields• RMS-26
requirements• RMS-26
DNA (default name address) argument• B-5
DNM (default name) argument• B-3
DNM (default name) field• 4-3

Index

DNM (default name) keyword
specifying FAB$L _DNA and FAB$B_DNS fields
from VAX MACRO• 5-9
DNS (default name size) argument• B-5
DUP (duplicate) option
in XAB$B_FLG field• B-21
Duplicate key
examples• 7-8
incompatibility between VMS RMS and RMS-11
•13-9
insertion order• RMS-72
retrieving records • 7-8

E
EDT argument• B-16
End-of-file field in XABFHC
See XAB$L _EBK field
End-of-file mark
positioning for user file open option• 5-18
End-of-file option
See RAB$V_EOF option
End-of-file positioning• RMS-7
Enter service• RMS-29
condition values• RMS-31
control block input fields• RMS-30
control block output fields• RMS-30
requirement for NAM block fields• RMS-30
Erase service• RMS-32
alternative• RMS-33
condition values• RMS-34
See also Completion status codes
control block input fields• RMS-33
control block output fields• RMS-33
requirements for using• RMS-33
use restriction• RMS-33
Error
recommended method for signaling• 2-6
Error completion routine• 2-5
Error status code• 2-6
from invalid control blocks• 2-6
Escape sequence
using from terminal devices• RMS-49
ETO (extended terminal operation) option •
RMS-49
Event flag
for synchronous operations• 2-7
Executive-mode (PSL$C_EXEC) constant
for FAB$V_CHAN_MQDE • 5-5

Expanded string
requesting• 6-2
Expanded string area address (ESA)
program example• 4-12
Expanded string area address field
See NAM$L _ESA field
Expanded string length field
See NAM$B_ESL field
Expanded string size field
See NAM$B_ESS field
Expiration date field
See XAB$Q_EDT field
Extended attribute block
See XAB block
Extended attribute block address field
See FAB$L_XAB field
See RAB$L _XAB field
Extended terminal operation option
See RAB$V_ETO option
Extend service• RMS-35
condition values• RMS-37
control block input fields• RMS-36
control block output fields• RMS-36
invoking • 5-11
requirements• RMS-36
use restriction• RMS-36
XAB overrides• RMS-36

F
FAB$B_ACMODES
See FAB$V_CHAN_MODE and FAB$V_LNM_
MODE
FAB$B_BID field • 5-3
FAB$B_BKS field • 5-3
considerations for calculating• 5-4
default logic• 5-4
limitation for RMS-11 • 5-3
performance considerations• 5-4
requirements for RMS-11 compatibility• 5-5
selecting default size for indexed files• 5-4
variations for XABs • 5-4
FAB$B_BLN field• 5-4
FAB$B_DNS field• 5-9, B-3
specifying default file specification• 5-2
FAB$B_F AC field• 5-9
comparing with FAB$B_SHR field• 5-9
for specifying sharing options• 4-1
interdependency with FAB$B_SHR field• 5-27

lndex-5

Index

FAB$B_FAC field (cont'd.)
options• 5-10
use with FAB$B_SHR • 5-10
FAB$B_FNS field• 5-12
specifying primary file specification• 5-2
FAB$B_FSZ field • 5-18
FAB$B_ORG field• 5-23
options• 5-23
use by various services• 5-23
FAB$B_RAT field• 5-23
default logic• 5-23
options• 5-23
FAB$B_RFM field• 5-25
keywords• 5-25
options• 5-25
FAB$B_RTV field• 5-26
FAB$B_SHR field• 5-27
comparing option names with file access option
names• 5-27
conflict with FAB$B_FAC field• 5-27
default logic• 5-27
for specifying sharing options• 4-1
interdependency with FAB$B_FAC field• 5-27
option naming convention• 5-27
options• 5-28
FAB$C_FIX option• 5-25
FAB$C_STMCR option• 5-25
FAB$C_STMLF option• 5-26
FAB$C_STM option• 5-25
FAB$C_UDF option• 5-26
FAB$C_VAR option• 5-26
FAB$C_VFC option• 5-26
FAB$L_ALO field• 5-3
as output field • 5-3
functional variations for XABs • 5-3
setting at run time• 3-5
use with Create service• 5-3
use with Extend service• 5-3
use with Open service• 5-3
FAB$L_CTX field• 5-6
FAB$L _DEV field • 5-7
bits listed• 5-7
FAB$L_DNA field• 5-8, 5-9, B-3
components listed• 5-9
specifying default file specification• 5-2
FAB$L_FNA field• 5-11
specifying primary file specification• 5-2
FAB$L _FOP field • 5-12
options• 5-13
FAB$L_MRN field• 5-21
consequence of exceeding• 5-21

lndex-6

FAB$L_NAM field• 5-23
FAB$L_SDC field• 5-27
comparing with FAB$L_DEV field• 5-27
FAB$L_STS field• 5-29
handling for ACL error status• 14-3
FAB$L_STV field• 5-29
examples of using• 3-12
for invoking SYS$010 • 5-18
for total number of blocks allocated• RMS-36
with 1/0 channel• RMS-16
FAB$L_XAB field• 5-29
FAB$V_ASY option• 5-14
use restriction• 5-14
FAB$V_BIO option• 5-10
how used to specify 1/0 type• 4-24
FAB$V_BLK option• 5-23
FAB$V_BRO option
use for sharing files• 5-28
FAB$V_CBT option• 5-13
precedence over FAB$V_CTG option• 5-14
FAB$V_CHAN_MODE option
list of values• 5-5
setting from MACRO• 5-6
FAB$V_CIF option• 5-15
precedence over FAB$V_SUP option• 5-15
FAB$V_CR option• 5-24
restriction against use with FAB$V_FTN and
FAB$V_PRN options• 5-23
FAB$V_CTG option• 5-14
subordinate to FAB$V_CBT option• 5-14
FAB$V_DEL option• 5-10
for enabling Delete service• 4-20
FAB$V_DFW option• 5-14
exception to use of global buffers• 5-19
FAB$V_DL T option• 5-16
qualified use by Close service• RMS-4
use with FAB$V_SCF or FAB$V_SPL option•
5-16
FAB$V_FTN option• 5-24
restriction against use with FAB$V_CR and
FAB$V_PRN options• 5-23
FAB$V_GET option•5-10, 5-28
use with block 1/0 operations•5-10, 5-11
FAB$V_LNM_MODE option
values listed• 5-20
FAB$V_LNM_MQDE subfield• 5-20
FAB$V_MSE option• 5-28
enabling multiple RABs • RMS-7
for overriding the FAB$V_UPI option• 5-29
requirement for read-only buffer cache• 5-20,
5-28

Index

FAB$V_MSE option (cont'd.)
use with other options• 5-28
FAB$V_MXV option• 5-15
FAB$V_NAM option• 5-16
FAB$V_NEF option• 5-17
FAB$V_NFS option• 5-18
relationship to CHAN_MODE subfield• 5-5
FAB$V_NIL option• 5-28
effect on specifying user file open option• 5-18
precedence over other options• 5-28
requirement for block 1/0 • 4-23
FAB$V_OFP option• 5-16
FAB$V_POS option• 5-17
subordinate to FAB$V_RWO option• 5-17,
5-18
FAB$V_PRN option• 5-24
restriction against use with FAB$V_FTN and
FAB$V_CR options• 5-23
FAB$V_PUT option• 5-11, 5-28
use with block 1/0 operations• 5-10
FAB$V_RCK option• 5-15
restricted use• 5-1 5
FAB$V_RWC option• 5-17
FAB$V_RWO option• 5-17
precedence over FAB$V_PQS option• 5-17,
5-18
FAB$V_SCF option• 5-16
qualified use by Close service• RMS-4
use restriction• 5-16
FAB$V_SHRDEL option• 5-28
FAB$V_SHRGET option
requirement for read-only buffer cache• 5-20,
5-28
FAB$V_SPL option• 5-16
qualified use by Close service• RMS-4
FAB$V_SQO option• 5-14
prohibiting random access• RMS-48
FAB$V_SUP option• 5-16
subordinate to FAB$V_CIF option• 5-15
FAB$V_SYNCSTS option• 5-15
FAB$V_TEF option• 5-14
restriction to sequential files• 5-14
FAB$V_TMD option•5-17
inhibiting automatic Create• RMS-29
precedence over FAB$V_TMP option• 5-17
FAB$V_TMP option• 5-1 7
inhibiting automatic Create• RMS-29
subordinate to FAB$V_TMD option• 5-1 7
FAB$V_ TRN option
in file access field• 5-11
requirement for truncate-on-put operation•
7-17

FAB$V_UFO option• 5-18
effect on internal structures• 5-20
relationship to CHAN_MODE subfield• 5-5
FAB$V_UPD option• 5-11 , 5-28
requirement for implementing update-if option•
7-17
requirement for Update service• 4-22
FAB$V_UPI option• 5-28
reqirement for setting• 5-29
requirement for block 1/0 • 4-23
requirement for user file open option • 5-18
FAB$V_WCK option• 5-15
restricted use• 5-1 5
FAB$W _BLS field• 5-5
limitation• 5-5
setting• 5-5
FAB$W_DEQ field• 5-4, 5-6
default logic• 5-6
overriding default• 5-7
FAB$W_GBC field• 5-19
as output• 5-19
changing• 5-19
clearing• 5-19
overriding default• 5-19
FAB$W_IFI field• 5-20
FAB$W_MRS field• 5-21
as output• 5-22
program example• 4-4
summary• 5-22
use with fixed-length records• 5-2 1
use with variable-length records• 5-21
FAB (file access block)• 5-1
argument categories• 1-2
description• 1-2
requirements for• 5-2
summary of fields• 5-1
$FAB macro• 8-2
argument categories• 8-3
$FAB_STORE macro• 8-4
argument categories• 8-5
FAB argument requirement• 8-5
run-time arguments• 8-5
FAC field
See FAB$B_FAC field
Fast delete option
See RAB$V_FDL option
FDL$PARSE • 4-9
FDL$RELEASE • 4-9
FOL Editor
as alternative to multiple XABs in example• 4-9

lndex-7

Index

Field length
identifier in symbolic name• 2-3
File
characteristics argument for FAB • 1-2
organizations• 1-1
specification argument for FAB • 1-2
File access block
See FAB
File access block address field
See RAB$L _FAB field
File access field
See FAB$B_FAC field
File component descriptor
address field• 6-3
example• 6-4
field value logic• 6-3
list of• 6-3
size field • 6-3
suggested use of• 6-4
File Definition Language Editor
See FDL Editor
File extension
using Extend service• RMS-36
File header characteristic extended address block
See XABFHC
See XABFHC block
File identification field
See NAM$W _FID field
File name address descriptor
See NAM$L_NAME descriptor
File name address field
See NAM$L_NAME field
File name length field
See NAM$B_NAME field
File name size descriptor
See NAM$B_NAME descriptor
File name status field
See NAM$L _FNB field
File name string
component parts• 4-9
File name string address( FAB$L_FNA) field
how used to specify file name string• 4-9
File name string size (FAB$B_FNS) field
how used to specify file name size• 4-9
File organization and record format field
See XAB$B_RFO field
File organization field
See FAB$B_ORG field
File owner group number field
See XAB$W_GRP field

lndex-8

File owner group number field (cont'd.)
in XABPRO field• 14-4
File owner member number field
See XAB$W_MBM field
File positioning
effect on shared files• RMS- 7
File-processing
services listed • 3-3
File-processing option
as service output• 5-12
categories listed• 5-12
naming convention• 5-12
File-processing options field
See FAB$L _FOP field
File protection extended address block
See XABPRO block
File protection field
See XAB$W_PRO field
File protection option field
See XAB$B_PROT_OPT field
File section
defining in context of multiple volumes•
RMS-56
File sharing
features• 1-1
File sharing field
See FAB$B_SHR field
File specification
component descriptors• 6-2
default requirements• 4-9
how handled by Search service• 4-9
parsing • RMS-66
File specification address
See FAB$L_FNA field
File specification size
See FAB$B_FNS field
File specification string address• 4-9
File specification string size• 4-9
File type address descriptor
See NAM$L _TYPE descriptor
File type address field
See NAM$L _TYPE field
File type length field
See NAM$B_TYPE field
File type size descriptor
See NAM$B_TYPE descriptor
File version address descriptor
See NAM$L _VER descriptor
File version address field
See NAM$L _VER field

Index

File version length field
See NAM$B_VER field
File version limit field
See XAB$W _ VERLIMIT field
File version size descriptor
See NAM$B_VER descriptor
Fill level
comparing primary key and alternate keys•
13-10
Find service• RMS-38
capabilities• RMS-39
condition values• RMS-4 1
control block input fields• RMS-39
control block output fields• RMS-4 1
First data bucket start virtual block number field
See XAB$L_DVB field
First free byte field
See XAB$W _FFB field
Fixed-length control area size field
See FAB$B_FSZ field
Fixed-length header control size field
See XAB$B_HSZ field
Fixed-length record format option
See FAB$C_FIX option
Flush service• RMS-43, RMS-44
condition values• RMS-44
See also Completion status codes
control block input fields• RMS-44
control block output fields• RMS~44
FNA argument• B-5
FNM argument• B-3
FNM keyword
for specifying FAB$L_FNA and FAB$B_FNS
fields from VAX MACRO• 5-11
FNS argument• B-5
FORTRAN carriage control option
See FAB$V_FTN option
FORTRAN carriage control option list• 5-24
Free service• RMS-45
condition values• RMS-46
control block input and output fields• RMS-46

G
$GET macro
program example• 4-16
Get option
See FAB$V_GET option

Get service• RMS-4 7, RMS-53
applicable access modes• RMS-48
condition values• RMS-53
See also Completion status codes
control block input fields• RMS-50
control block output fields• RMS-53
requirement for user record area• RMS-50
returning terminator character for terminal
input• RMS-49
return status for various file access methods•
RMS-7
using input from mailbox devices• RMS-50
using stream input• RMS-48
using terminal input• RMS-48
using the RAB$L _STV field for additional status
information• RMS-50
Get sharing option
See FAB$V_GET sharing option
Global buffer• 5-19
determining number of• 5-20
Global buffer count field
See FAB$W_GBC field

H
HDR1 labels
accessing from XAB$B_MT ACC field• 14-5
Highest virtual block field
See XAB$L _HBK field

I
1/0 mode
how to switch for sequential files• 4-24
procedure for delaying decision until stream
connection• 4-24
when mode switching allowed• 4-24
Index bucket area number (IAN)
program example• 4-8
Index bucket area number field
See XAB$B_IAN field
Index bucket fill size (IFL)
program example• 4-8
Index bucket fill size field
See XAB$W _IFL field
Index bucket size field
See XAB$B_IBS field

lndex-9

Index

Indexed file

Initialization macro (cont'd.)

block allocation • 8-3
bucket size for multiple areas• RMS-15
composition• RMS-18
creating• RMS-18
creating with multiple-key• 4-5
default bucket size• 5-3
determinating key value• RMS-48
determining keys and areas• 17-1
determining key size• 7-4
determining maximum record size• 5-21
determining number of buffers• 7-6
establishing index• RMS-7
example of processing duplicate keys• 7-8
example of specifying• 3-5
fast delete option • 7-1 5
identifying data area• 13-4
inhibiting index update• 13-12
initial extent quantity• 5-3
inserting records with Put service• RMS- 71
invoking Get and Find services for• 7-4
key of reference• 7-3
methods of accessing records• 7-5
options• 7-10
positioning area• 8-7
PROLOG selection• RMS-19
restriction against VFC format• 5-18
restriction to changing primary key• RMS-100
separating index levels• 13-11
setting bucket size• 5-4
size of data bucket• 13-4
specifying bucket size• 8-5
specifying index area• 13-10
specifying index bucket size• 13-10
string key options• 13-8
update-if option • 7-1 7
use of areas in • 4-8
use of end-of-file option• RMS-7
verifying sort order• RMS-7
with allocation options• 5-14
with collating sequences• 13-3
with deferred-write option• RMS-12
with Get service• RMS-48
with XABKEY • 13-1
Index level
comparing primary key and alternate keys•
13-10
Initialization macro
advantages described• 3-7
example• 3-5
functions• 3-1

multiple bit field• 3-5
placement guidelines• 3-7
using• 3-6
Inserting record
program example• 4-16
Internal file identifier field
See FAB$W_IFI field
Internal stream identifier field
See RAB$W_ISI field
10$M _NQW modifier
for Get and Put services• 7-14
Item list • 18-1
guidelines for supplying• 18-1
Item list address field
See XAB$L _ITEMLIST field
See XAB$L _ITMLST field
Item list extended address block
See XABITM block
Item list length field
See XAB$W_ITMLST_LEN field

J
Journaling extended address block
See XABJNL block

K
Key
defining as simple or segmented• 13-13
determining match method• 7-5
example of finding and deleting a record• 4-20
example of updating a record• 4-21
selecting path • 4-12
size restriction for string type• 13-15
types of matches• 7-5
Key buffer address field
See RAB$L _KBF field
Key definition extended address block
See XABKEY block
Key greater than
See RAB$V_NXT option
Key greater than or equal
See RAB$V_EQNXT option
Key name buffer address field
See XAB$L _KNM field

lndex-10

Index

Key of reference
establishing • RMS-48
Key of reference field
See RAB$B_KRF field
See XAB$_REF field
Key option
comparing primary and alternate keys• 13-8
Key options flag field
See XAB$B_FLG field
Key position field
See XAB$W_POSO through XAB$W_POS7
field
Key size field
See RAB$B_KSZ field
See XAB$B_SIZO through XAB$B_SIZ7 field
Key string buffer
program example• 4-16
Key string descriptor
program example• 4-16
Key string length
program example• 4-16

L
Length field
using to indicate constant (keyword) value• 2-4
using to indicate mask or bit offset• 2-3
Level of root bucket field
See XAB$B_L VL field
LIB$GET_INPUT
example of use in program• 4-12
LIB$PUT_OUTPUT
example of use in program• 4-12
LIB$SIGNAL (or LIB$STOP)
using to signal errors• 2-6
Limit option
See RAB$V_LIM option
Load option
See RAB$V_LOA option
Locate mode
comparing with move mode for buffer handling•
7-15
Locate mode option
See RAB$V_LOC option
Location field in XABALL
See XAB$L_LOC field
Lock record for read option

Lock record for write option
See RAB$V_RLK
Logical name translation
requirements for parsing• 4-9
Logical name translation access mode subfield
See FAB$V_LNM_MODE subfield
Longest record length field
See XAB$W _LRL field
Lowest level of index area number field
See XAB$B_LAN field

M
Macro
applicable VAX MACRO syntax rules• 3-5
arguments for service completion routines•
3-11
capabilities listed• 4-1
control block initialization• 3-1
library location• 3-2
names and control blocks• 3-2
naming conventions• 3-2
rules applicable to programming• 3-6
service• 3-1
using •3-6
Macro field
example of initializing• 3-5
setting at run time• 3-5
Magnetic tape accessibility field
See XAB$B_MT ACC field
Manual unlock option
See RAB$V_ULK option
MAXBUF system parameter
limiting size of user's ACL buffer• 14-3
Maximum record number field
See FAB$L _MRN field
Maximum record size
default value for remote file access• 5-22
Maximum record size field
See FAB$W_MRS field
Maximum record size field in XABFHC
See XAB$W_MRZ field
Maximum version option
See FAB$V_MXV option
Minimum record length field
See also XAB$W _MRL field
in XABKEY • 13-12

See RAB$V_REA option

lndex-11

Index

Mixed 1/0
precautions listed• 4-24
Mode field in XABITM
See XAB$L _MODE field
Mode switching
when permitted• 4-24
Multiblock count field
See RAB$B_MBC field
Multibuffer count field
See RAB$B_MBF field
Multinational Character Set
See DEC Multinational Character Set
Multiple argument
delimiting in control block fields• 3-5, 3-7
specifying in control block fields• B-3
Multiple key
example of use with Close service• 4-12
performance cost of using• 13-14
recommended number• 13-14
Multiple-key indexed file
creating• 4-5
Multiple record stream
with block 1/0 • 4-25
Multistream access option
See FAB$V_MSE option

N
NAM$B_BID field• 6-4
NAM$B_BLN field• 6-4
NAM$B_DEV descriptor• 6-3
NAM$B_DEV field• 6-4
NAM$B_DIR descriptor• 6-3
NAM$B_DIR field• 6-5
NAM$B_ESL field• 6-5
NAM$B_ESS field• 6-5
NAM$B_NAME descriptor• 6-3
NAM$B_NAME field• 6-7
NAM$B_NODE descriptor• 6-3
NAM$B_NODE field • 6-7
NAM$B_NOP field• 6-7
options listed• 6-8
NAM$B_RSL field • 6-9, RMS-63
NAM$B_RSS field • 6-9
NAM$B_TYPE descriptor• 6-3
NAM$B_TYPE field• 6-9
NAM$B_VER descriptor• 6-3
NAM$B_VER field•6-10
NAM$L _DEV descriptor• 6-3

lndex-12

NAM$L _DEV field• 6-4
NAM$L _DIR descriptor• 6-3
NAM$L _DIR field• 6-5
NAM$L _ESA field • 6-5
NAM$L_FNB field• 6-6, RMS-63, RMS-87
NAM$L _FNB status bit
listing• 6-6
NAM$L _NAME descriptor• 6-3
NAM$L _NAME field• 6-7
NAM$L _NODE descriptor• 6-3
NAM$L _NODE field • 6-7
NAM$L _RLF field• 6-8
NAM$L_RSA field• 6-9, RMS-63
NAM$L _TYPE descriptor• 6-3
NAM$L _TYPE field• 6-9
NAM$L _VER descriptor• 6-3
NAM$L _VER field• 6-10
NAM$L _wee field • 6-1 o
returned by Remove service• RMS-82
NAM$T_DVI field• 6-5
NAM$V_CNCL_DEV bit• 6-6
NAM$V_CONCEAL field• RMS-26, RMS-63
NAM$V_OIR_L VLS bit• 6-6
NAM$V_EXP_DEV bit• 6-6
NAM$V_EXP_DIR bit• 6-6
NAM$V_EXP_NAME bit• 6-6
NAM$V_EXP_TYPE bit• 6-6
NAM$V_EXP_VER bit• 6-6
NAM$V_GRP_MBR bit• 6-6
NAM$V_HIGHVER bit• 6-6
NAM$V_LOWVER bit• 6-6
NAM$V_NOCONCEAL option• 6-8, RMS-16,
RMS-68
NAM$V_NODE bit• 6-6
NAM$V_PPF bit• 6-6
NAM$V_PWD field• RMS-26, RMS-63, RMS-68
NAM$V_PWD option• 6-8, RMS-16
NAM$V_QUOTED bit• 6-6
NAM$V_ROOT_DIR bit• 6-7
NAM$V_SEARCH_LIST bit• 6-7
NAM$V_SRCHXABS option• 6-8
NAM$V_SYNCHK option• 6-8, RMS-68
use with Parse service• 5-7
using for Parse service without 1/0 • RMS-67
NAM$V_WILDCARD bit• 6-7
NAM$V_WILD_GRP bit•6-7
NAM$V_WILD_MBR bit•6-7
NAM$V_WILD_NAME bit•6-7
NAM$V_WILD_SFD 1 bit• 6-7
NAM$V_WILD_TYPE bit• 6-7
NAM$V_WILD_UFD bit•6-7

Index

NAM$V_WILD_ VER bit• 6-7
NAM$W_DID field• 6-4
NAM$W _FID field• 6-6
NAM (name block)
summary of fields• 6-1
using from higher-level language• 6-2
using from VAX MACRO• 6-2
NAM (name block) option
See FAB$V_NAM option
Name block
See NAM
Name block address field
See FAB$L _NAM field
Name block options field
See NAM$B_NOP field
Naming convention
macros•3-2
services • 3-3
$NAM macro• B-6
argument categories• B-6
$NAM_STORE macro•B-7
argument categories• B-7
comparing with $NAM macro• B-7
NAM$T_DVI argument• B-7
NAM$W _DID argument• B-7
NAM$W_FID argument• B-7
requirements• B-7
NBP (next block pointer)
default for block transfer• 7-2
for block 1/0 • 4-25
functions listed• 4-25
NETWORK_BLOCK_COUNT qualifier
for specifying maximum record size• 5-22
Next block pointer
See NBP
Next key
See RAB$V_NXT option
Next or equal key option
See RAB$V_EQNXT option
Next Volume service• RMS-55
condition values• RMS-5 7
control block input and output fields• RMS-56
flush logic• RMS-56
input logic sequence• RMS-56
output logic sequence• RMS-56
requirements for using• RMS-56
Node name address descriptor
See NAM$L_NODE descriptor
Node name address field
See NAM$L_NODE field

Node name length field
See NAM$B_NODE field
Node name size descriptor
See NAM$B_NODE descriptor
No lock option
See RAB$V_NLK option
Nonexistent record option
See RAB$V_NXR option
Non-file-structured option
See FAB$V_NFS option
NOP field
specifying multiple values• B-6
No sharing option
See FAB$V_NIL option
Not end-of-file option
See FAB$V_NEF option
Null character field
See XAB$B_NUL field
Number of allocation areas field
See XAB$B_NOA field
Number of key segments field
See XAB$B_NSG field
Number of keys field
See XAB$B_NOK field
Number sign ( #)
requirement for in control store macro• 3-8

0
$OPEN macro
expansion of• 3-10
for invoking the open service• 4-1
using in example• 3-10, 3-11
Open service• RMS-58
condition values• RMS-64
contrasted with Parse and Search services•

4-10
control block input fields• RMS-59
control block output fields• RMS-61
function• 4-1
invoking• 4-4
NAM input fields• RMS-63
NAM output fields• RMS-63
program example• 4-2
requirements for using • RMS-59
Option
specifying by symbolic bit offset• 2-3

lndex-13

Index

Optional argument

Prompt buffer size field

to service• 3-11
Output file parse option

See RAB$B_PSZ field
Prompt option

See FAB$V_OFP option
Output record buffer address field

See RAB$V_PMT option
Protection extended address block
See XABPRO block
Purge type-ahead option

See RAB$L_RBF field

p
Packed decimal byte
structure for key type• 13-6
Packed decimal string
as key type• 13-6
$PARSE macro
for processing wild card characters• 4-10
Parse service• RMS-66, RMS-67
condition values• RMS-69
control block input fields• RMS-67
control block output fields• RMS-68
preparing for file search• 4-9
preparing for wildcard character processing•
RMS-67
program example• 4-9
requirements for using• RMS-67
Path to file
file specification string address• 4-9
file specification string size• 4-9
Performance
improving with SHR argument• 4-14
Print format option
See FAB$V_PRN option
Print format options for VFC records with 2-byte
control area• 5-25
Program
using wild card characters• 4-12
Program execution mode
using to call services• 2-7
Program interface• 2-1
Programming language
using control blocks with• 2-1
Programming rules• 3-6
Prolog field
See XAB$B_PROLOG field
Prolog level • RMS-18
Prolog version number field
See XAB$W _PVN field
Prompt buffer address field
See RAB$L_PBF field

lndex-14

See RAB$V_PT A option
$PUT macro
program example• 4-1 6
Put service• RMS-70
condition values• RMS-7 4
See also Completion status codes
control block input fields• RMS-73
control block output fields• RMS-7 4
inserting records by sort order• RMS- 7 2
inserting records into indexed files• RMS-71
inserting records into relative files• RMS- 71
inserting records into sequential files• RMS-71
inserting records with duplicate keys• RMS-7 2
record locking caution• RMS-72
record-processing options• 7-16
requirements for using• RMS- 7 2
update-if logic• RMS-72
using RAB$V_TPT option• RMS-71
using RAB$V_UIF option• RMS-71
using with mailboxes• RMS- 71
using with stream format files• RMS-71
Put service option
See FAB$V_PUT option
Put sharing option
See FAB$V_PUT sharing option

R
RO
use by control block store macros• 3-8
use in asynchronous operations• 2-5
RAB (record access block)
summary of fields• 7-1
RAB$B_BID field• 7-2
RAB$B_BLN field• 7-3
RAB$B_KRF field• 7-4
for selecting key path • 4-12
for various services• 7-4
RAB$B_KSZ field• 7-4
DECnet requirement• 7-4
key size compared to data types• 7-4
shared offset• 7-4

Index

RAB$B_KSZ field (cont'd.)
use with limit option• 7-13
use with search key• 7-12, 7-14
RAB$B_MBC field• 7-5
default logic• 7-5
performance benefit• 7-6
use restriction• 7-5, 7-6
RAB$B_MBF field• 7-6
default logic• 7-6
performance benefit• 7-6
use restriction• 7-6
use with read-ahead option• 7-16
use with write-behind option• 7-16
values for various organizations• 7-6
RAB$B_PSZ field• 7-7
shared offset• 7-7
RAB$B_RAC field• 7-7
options• 7-7
use restriction • 7-7
RAB$B_TMO field
use with RAB$V_TMO option for mailbox
service• 7-14
RAB$B_TMO field• 7-2 1
for various record functions• 7-21
requirement for RAB$V_TMO option• 7-21
use with timeout option for terminal operation •
7-19
RAB$C_KEY option• 7-8
RAB$C_RF A option • 7-8
RAB$C_SEQ option• 7-7
RAB$L _BKT field
as output• 7-2
use with block 1/0 • 7-2
RAB$L_CTX field• 7-3
RAB$L _F AB field• 7-3
RAB$L _KBF field• 7-3
shared offset• 7-3
use with limit option• 7-13
use with RAB$B_KSZ field• 7-4
use with search key•7-12, 7-14
RAB$L_PBF field• 7-7
requirement for carriage control• 7-7
RAB$L_RBF field•4-4, 7-8
RAB$L_RHB field• 7-9
buffer size compatibility with FAB$B_FSZ • 7-9
default logic• 7-9
use by various services• 7-9
use restriction • 7-9
RAB$L _ROP field• 7-10
options listed • 7-10
specifying key match method• 7-5

RAB$L _STS field• 7-20
RAB$L_STVO field
for returning terminating character• RMS-49
RAB$L _STV field • 7-20
alternate access to• 7-20
for returning 1/0 status block• RMS-49
for returning 1/0 status block from Put service•
RMS-74
for returning PIO from Put service• RMS-71
for returning process identification (PIO)•
RMS-50
for returning record length• RMS-53
using with Get service• RMS-50
RAB$L_UBF field• 7-21
buffer logic• 7-2 1
RAB$L_XAB field• 7-22
requirement for using XABTRM • 18-1
RAB$V_ASY option• 7-11, 7-14
use restriction• 7-1 5
RAB$V_BIO option• 7-11
RAB$V_CCO option• 7-18
RAB$V_CVT option• 7-19
RAB$V_EOF option• 7-12
RAB$V_EQNXT option• 7-12
examples• 7-13
specifying key match method • 7-5
RAB$V_ETO option
requirement for using XABTRM • 18-1
RAB$V_FOL option• 7-15
use restriction• 7-1 5
RAB$V_KGE option
See RAB$V_EQNXT option
See RAB$V_NXT option
RAB$V_LIM option• 7-13
RAB$V_LQA option• 7-13
determining fill size• 13-10
example of use• 4-8
use restriction• 13-4, 13-11
RAB$V_LOC option• 7-15
use restriction• 7-1 5
RAB$V_NLK option• 7-17
precedence over RAB$V_ULK option• 7-17
RAB$V_NXR option• 7-17
output from Get service • 7-1 7
relevant completion codes• 7-17
use restriction• 7-1 7
RAB$V_NXT option• 7-14
examples• 7-14
specifying key match method• 7-5
RAB$V_PMT option• 7-19
RAB$V_PT A option• 7-19

lndex-15

Index

RAB$V_RAH option• 7-12, 7-15
default logic• 7-16
use restriction• 7-16
RAB$V_REA option• 7-17
use restriction • 7-17
RAB$V_RLK option• 7-18
precedence over RAB$V_REA option• 7-18
RAB$V_RNE option• 7-19
RAB$V_RNF option• 7-19
RAB$V_RRL option• 7-18
RAB$V_SYNCSTS option • 7-16
RAB$V_TMO option
for immediate mailbox service• 7-14
RAB$V_TMO option• 7-14, 7-18, 7-19
RAB$V_TPT option• 7-16
use restriction • 7-16
using with Put service• RMS- 71
RAB$V_UIF option• 7-17
effects on Put service• 7-1 7
use restriction for indexed files• 7-17
using with Put service• RMS-7 1
RAB$V_ULK option• 7-18
subordinate to RAB$V_NLK option• 7-18
RAB$V_WAT option• 7-18, 7-19
precedence over other options• 7-19
use with the RAB$V_TMO option• 7-18
RAB$V_WBH option•7-12, 7-16
default logic• 7-16
use restriction • 7-16
RAB$W_ISI field• 7-3
RAB$W_RFA field• 7-9
additional symbolic offsets• 7-9
as argument to $RAB_STORE macro• B-12
example• 7-9
guidelines for using• 7-9
RAB$W_RSZ field• 4-4, 7-20
for various services• 7-20
operational notes listed• 7-20
RAB$W_STVO offset
alternate access to RAB$L _STV • 7-20
RAB$W _STV2 field
for returning length of escape sequence•
RMS-49
RAB$W_STV2 offset
alternate access to RAB$L_STV • 7-20
RAB$W_USZ field• 7-21
recommended value• 7-21
use with block 1/0 • 7-22
RAB$_ V_ WAT option
use with timeout option for record locking•
7-18

lndex-16

RAB (record access block)
arguments• 1-4
described in context of example• 4-4
description • 1-4
general description• 7-1
summary of fields• 7-1
$RAB macro• B-9
argument categories• B-10
$RAB_STORE macro• B-11
argument categories• B-12
comparing with $RAB macro• B-11
requirements• B-12
RF A argument• B-12
ROT (revision-date-time) argument• B-16
Read ahead option
See RAB$V_RAH option
Read check option
See FAB$V_RCK option
Read-no-echo option
See RAB$V_RNE option
Read no filter option
See RAB$V_RNF option
Read regardless of lock option
See RAB$V_RRL option
Read service • RMS- 7 6
condition values• RMS-78
control block input fields• RMS-77
control block output fields• RMS-77
requirements for using• RMS-77
Record
formats • 1-1
requirements for reading or writing in a file•
4-12
Record access block
See RAB
Record access field
See RAB$B_RAC field
Record attribute field
See FAB$B_RA T field
Record attributes field in XABFHC
See XAB$B_A TR field
Record buffer field
See RAB$L _RBF field
Record file address field
See RAB$W_RFA field
Record format field
See FAB$B_RFM field
Record header buffer field
See RAB$L _RHB field
Record 1/0
how to execute• 4-24

Index

Record locking record-processing options• 7-1 7
Record-processing
services listed• 3-3
Record-processing macro
format example • 3-12
Record-processing option
for Connect service• 7-10
Record-processing options field
See RAB$L_RQP field
Record size field
See RAB$W_RSZ field
Record stream
in the context of a RAB• 7-1
Recovery unit extended address block
See XABRU block
Recovery unit XAB
See XABRU block
Register
saving when making call• 2-4
Register 0
See RO
Related file identification field
See XAB$W _RFI field
Related file identification field in XABALL
See XAB$W_RFI field
Related file NAM block address field
See NAM$L_RLF field
Relative file
buffer requirement• 7-6
defining cell size• 5-2 1
description of relative record number• 7-5
determining record length• 5-21
establishing highest record number• 5-21
nonexistent record processing• 7-1 7
omitting initial prezeroing • 4-23
random access• 7-3
record size limit• 5-21
RFA value• 7-9
specifying bucket size• 8-5
specifying cell size• 10-5
Relative file field
record access• 7-2
Relative volume number field
See XAB$W _VOL field
Release service• RMS-79, RMS-80
condition values• RMS-80
control block input and output fields• RMS-80
Remove service• RMS-8 1, RMS-82
caution against mixing with Search service•
RMS-82
comparing with Erase service• RMS-82

Remove service (cont'd.)
condition values• RMS-84
control block input fields• RMS-82
control block output fields• RMS-83
improving performance• RMS-82
requirements for using• RMS-82
use with wildcard characters and search lists•
RMS-82
Rename service• RMS-85, RMS-86
alternative to specifying arguments to
$RENAME macro• RMS-8(?
condition values• RMS-88
control block input fields• RMS-86
control block output fields• RMS-87
exception in argument list• 2-5
format • 3-11
indicating successful completion• 4-16
program example• 4-14
requirements for using • RMS-86
Reserved event flag
use of• 2-7
Restriction
to calling services• 2-7
Resultant string
requesting• 6-2
Resultant string area address field
See NAM$L_RSA field
Resultant string area size field
See NAM$B_RSS field
Resultant string length field
See NAM$B_RSL field
Retrieval window size field
See FAB$B_RTV field
Retrieving record
program example• 4-16
Revision date and time extended address block
See XABRDT block
Revision date and time field
See XAB$Q _RDT field
Revision number field
See XAB$W _RVN field
Rewind on close option
See FAB$V_RWC option
Rewind on open option
See FAB$V_RWO option
Rewind service• RMS-89, RMS-90
condition values• RMS-90
control block input fields• RMS-90
control block output fields• RMS-90
use restriction• RMS-90
RMS$_QK_LIM success status code• 7-13

lndex-17

Index

RMS-11
block identifier field limitation • 5-3
$RMSDEF macro
access to symbolic offset names• 2-2
RMS_OFNBC system parameter
for specifying default network block count•
5-22
Root index bucket virtual block field
See XAB$L_RVB field
Run-time
access options• 1-2
implementation of services• 4-1
information • 1-4
processing environment• 2-1

s
Search
synonyms• 7-1 2
Search list
as alternative to using wildcard characters•
4-10
using with Remove service• RMS-82
$SEARCH macro
for processing wildcard characters• 4-10
Search service• RMS-91 , RMS-92
condition values• RMS-94
control block input fields• RMS-92
control block output fields• RMS-93
example of completion code handling• 4-12
program example• 4-9
requirement for Parse service• 4-9
using with wildcard characters and search lists•
RMS-92
Search string translation
requirements for parsing• 4-9
Secondary device characteristics field
See FAB$L _SOC field
Segmented key• 13-13
restriction against overlapping• 13-13
Separator
in symbolic name• 2-3
Sequential only option
See FAB$V_SQO option
Service
allowable program execution modes• 2-7
block 1/0 • 3-5
calling example• 3-11
invoking at run time• 3-1

lndex-18

Service (cont'd.)
naming conventions• 3-3
passing argument list to• 3-10
Service macro
description• 3-1
for creating and processing files• 4-1
format•3-10, 3-11
format rules• 3-11
types• 3-12
Services
restrictions to calling• 2-7
SET FILE command
for changing global buffer count value• 5-19
SET RMS_OEFAULT command• 7-6
to limit default extension quantity• 5-6
Set system failure exception mode
See SYS$SETSFM
Severity code
in completion status code field• 2-6
S field in symbolic offset
for specifying field length• 2-3
Shared access
requirement to specify• 4-1
Shared file
end-of-file positioning• RMS-7
SHR field
See FAB$B_SHR field
Sign representation
preference for key type coding• 13-7
Simple key• 13-13
Sort order
establishing• 7-5
Space service• RMS-95
condition values• RMS-96
control block input fields• RMS-96
control block output fields• RMS-96
Spool file option
See FAB$V_SPL option
Starting logical block number field
See XAB$L _SBN field
Stream record format option
See FAB$C_STM option
Stream record format with carriage return option
See FAB$C_STMCR option
Stream record format with line feed option
See FAB$C_STMLF option
STS (status) field
See also Completion status field
See also FAB$L _STV field
contents• 2-6

Index

STV (status value) field

SYS$FIND

See also Completion status value field
contents • 2-6
Submit command file option

See Find service
SYS$FLUSH

See FAB$V_SCF option
Success completion routine• 2-5
Summary extended address block

See Flush service
SYS$FREE
See Free service
SYS$GET

See XABSUM block
Summary XAB
for key information• 13-1
Supersede existing file option

See Get service
SYS$LIBRARY:STARLET.MLB
as source of macros • 1-1
SYS$NXTVOL

See FAB$V_SUP option
Supervisor-mode (PSL$C_SUPER) constant
for FAB$V_CHAN_MODE • 5~5
Symbol definition macro
description• 3-1
using•3-7
Symbolic address
use in locating start of control block• 3-7
Symbolic bit offset
use in specifying options• 2-3
Symbolic naming exception
control block• 2-3
Symbolic offset
control block• 2-4
format• 2-2
use in locating control block fields• 2-2
Synchronous status option

See Next Volume service
SYS$0PEN

See FAB$V_SYNCSTS option
See RAB$V_SYNCSTS option
SYS$BINTIM • 3-10
SYS$CLOSE
See Close service
SYS$CONNECT
See Connect service
SYS$CREATE
See Create service
SYS$DELETE
See Delete service
SYS$DISCONNECT
See Disconnect service
SYS$DISPLA Y
See Display service
SYS$ENTER
See Enter service
SYS$ERASE
See Erase service
SYS$EXTEND
See Extend service

See Open service
SYS$PARSE
See Parse service
SYS$PUT
See Put service
SYS$QIO
for additional processing• 5-18
use in 1/0 operation• 2-7
SYS$READ
See Read service
SYS$RELEASE
See Release service
SYS$REMOVE
See Remove service
SYS$RENAME
See Rename service
noting format difference• 3-11
SYS$REWIND
See Rewind service
SYS$SEARCH
See Search service
SYS$SETSFM
use in signaling errors• 2-6
SYS$SPACE
See Space service
SYS$TRUNCATE
See Truncate service
SYS$UPDATE
See Update service
SYS$WAIT
See Wait service
SYS$WRITE
See Write service
SYSPRV privilege
requirement for creating files with different UIC •
14-8

lndex-19

Index

System service exception• 2-6
System service exception generation
disabling• 2-6

Type code field in revision date and time XAB
See XAB$B_COD field
Type code field in summary XAB
See XAB$B_COD field
Type code field in terminal XAB
See XAB$B_COD field

Temporary file delete option
See FAB$V_TMD option
Temporary file option

See FAB$V_ TMP option
Terminal device record-processing option• 7-18
Terminal extended address block
See XABTRM block
Terminal read operation
RAB$L_ROP field options• 18-2
T field in symbolic offset
for specifying varying field length• 2-3
Timeout field
See RAB$B_TMO field
Timeout option
See RAB$V_TMO option
Total key size field

UIC (user identification code)
delimiting in control block fields• 3-7
Undefined record format option

See XAB$B_TKS field
Truncate at end-of-file option
See FAB$V_TEF option
Truncate-on-put option
See RAB$V_TPT option
Truncate option
See FAB$V_TRN option
Truncate service• RMS-97
condition values• RMS-98
See also Completion status codes
control block input fields• RMS-98
control block output fields• RMS-98
use restriction• RMS-97
Type code field in allocation XAB
See XAB$B_COD field
Type code field in date and time XAB
See XAB$B_COD field
Type code field in file header characteristics XAB
See XAB$B_COD field
Type code field in item list XAB
See XAB$B_COD field
Type code field in key XAB
See XAB$B_COD field
Type code field in protection XAB
See XAB$B_COD field

lndex-20

See FAB$C_UDF option
Update-if option
See RAB$V_UIF option
Update service• RMS-99, RMS-100
comparing with Put service for stream format
files• RMS-100
condition values• RMS-101
control block input fields• RMS-100
control block output fields• RMS-101
invoking• 5-11
program example• 4-20
requirements for using• RMS-100
using with indexed files• RMS-100
Update sharing option
See FAB$V_UPD option
User context field
See RAB$L _CTX field
User-entered reply
as used in example for selecting key path• 4-12
User file-open option
See FAB$V_UFO option
User identification code field
See XAB$L _UIC field
User-mode (PSL$C_USER) constant
for FAB$V_CHAN_MODE • 5-5
User process interlock option
See FAB$V_UPI option
User prompt string
program example• 4-16
User record buffer address field
See RAB$L _UBF field
User record buffer size field
See RAB$W _USZ field

Index

v
Variable-length format option
See FAB$C_VAR option
Variable-length record
guidelines for specifying• 5-21
VAX language
use with control blocks• 2-1
VAX MACRO
See Macro
VAX Procedure and Condition Handling Standard
for calling services• 3-3
VFC record format option
See FAB$C_ VFC option

w
$WAIT macro
format difference• 3-12
Wait option
See RAB$V_WAT option
Wait service• RMS-102
condition values• RMS-103
control block input and output fields• RMS-102
Wildcard character
use with Remove service• RMS-82
use with Search service• 4-10
Wildcard context field
See NAM$L_WCC field
Wildcard substitution
specifying NAM$L_RSA field• 6-9
Write-behind option
See RAB$V_WBH option
Write check option
See FAB$V_WCK option
Write service• RMS-104, RMS-105
condition values• RMS-106
control block input fields• RMS-105
control block output fields• RMS-105

x
XAB$B_AID field• 8-2
XAB$B_ALN field• 8-2

XAB$B_AOP field• 8-3
options• 8-4
XAB$B_A TR field• 10-2
options• 10-2
XAB$B_BKZ field
as output• 8-5
default logic• 8-5
determining bucket size• 8-5
in allocation XAB (XABALL) • 8-4
in file header characteristics allocation XAB
(XABFHC) • 10-3
RMS-11 restriction• 8-5
size requirements for multiple index areas• 8-5
XAB$B_BLN· field
in allocation XAB (XABALL) • 8-5
in date and time XAB (XABDA T) • 9-2
in file header characteristics XAB (XABALL) •

10-3
in item list XAB (XABITM) • 11-2
in key XAB (XABKEY) • 13-2
in protection XAB (XABPRO) • 14-4
in revision date and time XAB (XABRDT) • 15-2
in summary XAB (XABSUM) • 17-1
in terminal XAB (XABTRM) • 18-2
XAB$B_CQD field
See also COD field
in allocation XAB (XABALL) • 8-5
in date and time XAB (XABDA T) • 9-3
in file header characteristics XAB (XABFHC) •
10-3
in item list XAB (XABITM) • 11-2
in key XAB (XABKEY) • 13-2
in protection XAB (XABPRO) • 14-4
in revision date and time XAB (XABRDT) • 15-2
in summary XAB (XABSUM) • 17-1
in terminal XAB (XABTRM) • 18-2
XAB$B_DAN field• 13-4
requirement for• 13-4
XAB$B_DBS field• 13-4
XAB$B_DTP field• 13-5
data formats• 13-6
data type restrictions• 13-5
options• 13-5
use with search key•7-13, 7-14
value prefixes for sorting• 13-5
XAB$B_FLG field• 13-8, B-21
option allowable combinations listed• 13-9
options• 13-8
XAB$B_HSZ field• 10-4
use restriction• 10-4

lndex-21

Index

XAB$B_IAN field• 13-10
conditional usage• 13-10
indicating index level• 8-5
XAB$B_IBS field• 13-10
XAB$B_LAN field• 13-11
indicating index level• 8-5
relationship to XAB$B_AID field• 13-11
requirement for compatibility with XAB$B_IAN
field• 13-11
use restriction• 13-11
XAB$B_L VL field• 13-12
XAB$B_MT ACC field• 14-5
default logic• 14-5
valid character codes• 14-5
XAB$B_NOA field• 17-2
XAB$B_NOK field• 17-2
XAB$B_NSG field• 13-1 2
XAB$B_NUL field• 13-12
use restrictions• 13-1 2
XAB$B_PROLOG field• 13-13
default logic• 13-13
service usage• 13-13
use restriction• 13-13
XAB$B_PROT_OPT field • 14-7
XAB$B_RFO field• 10-5
values listed• 10-6
XAB$B_SIZO through XAB$B_SIZ7 field• 13-14
default logic• 13-15
requirement for compatibility with XAB$W _
POSO through XAB$W _POS7 field• 13-14
with segmented key• 13-14
with simple key• 13-14
XAB$B_TKS field• 13-15
XAB$C_ALLEN value• 8-5
XAB$C_ALL value• 8-6
XAB$C_DA TLEN value• 9-2
XAB$C_DA T value• 9-3
XAB$C_FHCLEN value• 10-3
XAB$C_FHC value• 10-3
XAB$C_ITMLEN value• 11-2
XAB$C_ITM value• 11-2
XAB$C_KEYLEN value• 13-2
XAB$C_KEY value• 13-2
XAB$C_PROLEN value• 14-4
XAB$C_PRO value• 14-4
XAB$C_RDTLEN value• 15-2
XAB$C_RDT value• 15-2
XAB$C_SUMLEN value• 17-1
XAB$C_SUM value• 17-2
XAB$C_TRMLEN value• 18-2
XAB$C_TRM value• 18-2

lndex-22

XAB$L_ACLBUF field• 14-2
determining value for Create service• 14-2
determining value for Open and Display service•
14-2
handling ACE• 14-2
XAB$L_ACLCTX field• 14-2, 14-3
XAB$L _ACLSTS field• 14-3
error handling guidelines• 14-3
use restriction• 14-4
XAB$L_ALQ • 8-3
XAB$L _COLNAM field• 13-2
XAB$L_COLSIZ field• 13-3
XAB$L_COL TBL field• 13-3
XAB$L_DVB field• 13-7
XAB$L _EBK field• 10-3
XAB$L_HBK field• 10-4
comparing with FAB$L _ALO field• 10-4
XAB$L_ITEMLIST field• 11-2
XAB$L _ITMLST field• 18-2
requirement for valid terminal driver• 18-1
XAB$L _KNM field• 13-11
XAB$L_LOC field• 8-6
determining value• 8-6
requirement for alignment option• 8-6
XAB$L_MODE field• 11-2
XAB$L_NXT field
in XABALL • 8-6
in XABDAT • 9-3
in XABFHC • 10-5
in XABKEY• 13-12
in XABPRO • 14-5
in XABRDT • 15-2
in XABSUM • 17-2
in XABTRM • 18-3
XAB$L _RVB field• 13-14
XAB$L _SBN field• 10-6
XAB$L_UIC field• 14-4, 14-8
combining the XAB$W_GRP and XAB$W_
MBM fields• 14-8
order of determining value• 14-8
setting XAB$W _GRP field• 14-4
setting XAB$W _MBM field• 14-5
XAB$NXT field
in XABITM • 11-2
XAB$Q_BDT field• 9-2
XAB$Q_CDT field• 9-2
XAB$Q_EDT field• 9-3
XAB$Q_RDT field• 9-3, 15-2
XAB$V_BLK option• 10-2
XAB$V_CBT option• 8-4

Index

XAB$V_CHG option• 13-8
use restriction • 13-8
XAB$V_CR option• 10-2
XAB$V_CTG option• 8-4
XAB$V_DAT_NCMPR option• 13-8
XAB$V_DUP option• 13-8
XAB$V_FTN option• 10-2
XAB$V_HRD option• 8-4
use restrictions• 8-4
XAB$V_IDX _NCMPR option• 13-8
use in defining string keys• 13-8
use restriction• 13-8
XAB$V_KEY_NCMPR option• 13-8
use in defining string keys• 13-8
use restriction• 13-9
XAB$V_NUL option• 13-9
setting for various data types• 13-6
use in defining string keys• 13-8
use restriction • 13-9
with XAB$B_NUL field• 13-9
XAB$V_ONC option• 8-4
XAB$V_PRN option• 10-2
XAB$V_PROP AGATE option• 14-7
XAB$W _ACLLEN field• 14-3
determining value• 14-3
limitation• 14-3
XAB$W _ACLSIZ field• 14-3
limitations imposed by MAXBUF • 14-3
limitations imposed by user's BYTLM quota•
14-3
XAB$W _DEQ field• 8-6
XAB$W _DFL field • 13-4
advantages of using • 13-4
comparing for primary and alternate keys• 13-4
determining value• 13-4
use with RAB$V_LOA option• 7-13
XAB$W _DXQ field in XABFHC • 10-3
XAB$W _FFB field • 10-4
XAB$W _GBC field in XABFHC • 10-4
XAB$W _GRP field• 14-4
XAB$W _IFL field• 13-10
advantages of using• 13-11
XAB$W_ITMLST_LEN field• 18-2
requirement for valid terminal driver• 18-1
XAB$W_LRL field• 10-4
use restriction • 10-5
XAB$W _MBM field• 14-5
XAB$W _MRL field• 13-12
comparing primary key and alternate keys•
13-12

XAB$W _MRZ field in XABFHC • 10-5
determining value• 10-5
XAB$W_PQSO through XAB$W_POS7 field•
13-12
requirement to be compatible with XAB$B_
SIZO through XAB$B_SIZ7 field• 13-13
XAB$W_PRO field• 14-6
default logic• 14-7
organization• 14-6
required ordering of arguments• 14-6
subfield offsets• 14-6
user classes• 14-7
XAB$W_PVN field• 17-2
XAB$W _RFI field• 8-7
as argument to $XABALL _STORE macro•
B-14
requirement for XAB$C_RFI • 8-7
specifying • 8-7
XAB$W_RVN field•9-3, 15-3
XAB$W_VERLIMIT field in XABFHC• 10-6
XAB$W _VOL field• 8-7
use restriction• 8-7
XAB$_REF field• 13-14
XAB (extended attribute block)
description• 1-3
naming conventions for FAB • 1-3
naming conventions for RAB• 1-4
program example• 4-8
types• 1-3
XABALL block• 1-3, 8-1
relationship to FAB fields• 8-1
summary of fields• 8-1
$XABALL macro• B-13
argument categories• B-13
$XABALL_STORE macro• B-14
argument categories• B-14
comparing with $XABALL macro• B-14
requirements• B-14
XABDA T block• 9-1
brief description• 1-3
summary of fields• 9-1
value selection logic• 9-2
$XABDA T macro• B-15
$XABDAT_STORE macro• B-16
argument categories• B-16
argument variations• B-16
example of use• 3-9
requirements• B-16
XABFHC block• 10-1
brief description• 1-3
summary of fields• 10-1

lndex-23

Index

XA8FHC block (cont'd.)
use exception• 10-1
values for shared sequential files• 10-1
$XA8FHC macro• 8-17
$XA8FHC_STORE macro• 8-18
argument categories• 8-18
requirements• 8-18
XA81TM block• 11-1
brief description• 1-3
summary of fields• 11-1
$XA81TM macro• 8-19
XA8JNL block• 12-1
brief description • 1-3
XA8KEY block• 13-1
brief description• 1-3
data type options• 13-5
default logic• 13-9
summary of fields• 13-1
XAB$W _MRL field• 13-12
$XABKEY macro• B-20, B-21
argument categories• B-21
position and size options• B-21
$XABKEY_STORE macro• 8-22
argument categories• B-23
requirements• B-23
XABPRO block• 14-1
brief description• 1-3
summary of fields• 14-1
XAB$B_BLN field• 14-4
XAB$W _GRP field• 14-4
$XABPRO macro• B-24
ASCII radix indicator requirement in MT ACC
argument• B-24
describing UIC argument• B-25
example of MT ACC argument• B-24
listing user classes• B-25
XA8$W_PRO field requirements• 8-24

lndex-24

$XABPRO_STORE macro• 8-26
argument categories• B-26
argument exceptions to general rules• B-26
requirements• B-26
XABRDT block• 15-1
brief description • 1-3
comparing with XABDA T • 15-1
default logic• 15-1
service use of XAB$Q_RDT and XAB$W_RVN
fields• 15-1
summary of fields• 15-1
use restriction• 15-1
$XABRDT macro• B-27
$XABRDT_STORE macro• B-28
argument categories• B-28
$XABRDT_STORE macro (cont'd.)
requirements• B-28
XABRU block• 16-1
brief description • 1-3
XABSUM block• 17-1
brief description • 1-3
summary of fields• 17-1
use restriction• 17-1
$XABSUM macro• B-29
$XABSUM_STORE macro• B-30
argument categories• B-30
requirements• B-30
XABTRM block• 18-1
brief decription • 1-4
requirements to use• 18-1
summary of fields• 18-1
$XABTRM macro• B-3 1
$XABTRM_STORE macro• B-32
argument categories• B-32
requirements• B-32

Reader's Comments

VMS Record
Management Services
Reference Manual
AA-LA83A-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.

Name/Title

Dept.

Company

Date

Mailing Address
Phone

--;;~t;;~~:ld

Here ~d Ta~ ------------------~lllr-------~~~~~~--in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1.. 1.1 ... 1.11 .. 1
- - Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Reader's Comments

VMS Record
Management Services
Reference Manual
AA-LA83A-TE

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Name/Title

Dept.
Date

Company
Mailing Address
Phone

__ ~o;~t;~~~:d Hen ~d -----------------~Tlllf-------~~~~;~--Tape

in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1•• 1.1 ... 1.11 .. 1
- - Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -