OpenVMS Record Management Services Reference Manual

Document revision date: 19 July 1999

Order Number: AA--PV6RC--TK

January 1999

This reference manual contains general information intended for use in any OpenVMS programming language, as well as specific information on writing programs that use OpenVMS Record Management Services (OpenVMS RMS).

Revision/Update Information: This manual supersedes the OpenVMS Record Management Services Reference Manual, OpenVMS Alpha Version 7.1 and OpenVMS VAX Version 7.1

Software Version: OpenVMS Alpha Version 7.2
OpenVMS VAX Version 7.2

Compaq Computer Corporation
Houston, Texas

January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Bookreader, Compaq, DECdirect, DECthreads, DECwindows, DIGITAL, Digital UNIX, MSCP, OpenVMS, PDP-11, RMS-11, RSTS/E, RSX-11M, RSX-11M-PLUS, RSX-11S, RT-11, RX01, RX02, TOPS-10, TOPS-20, VAX, VAX MACRO, VAXcluster, VMS, OpenVMS Cluster, and the Compaq logo.

The following are third-party trademarks:

IBM is a registered trademark of International Business Machines Corporation.

MS--DOS is a registered trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.

All other trademarks and registered trademarks are the property of their respective holders.

ZK4523

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

Intended Audience

This document describes OpenVMS Record Management Services (RMS) control blocks and services for programmers.

Document Structure

This document consists of three parts and two appendixes.

Part 1 contains general information in three sections:
- Chapter 1 introduces the reader to RMS functions and associated control blocks.
- Chapter 2 discusses the RMS program interface that applies to using any OpenVMS programming language.
- Chapter 3 describes to advanced high-level language programmers how to use RMS macros.
Part 2 describes the RMS control blocks and their associated fields, in Chapter 4 through Chapter 19. This information is intended for a programmer using any programming language.
Part 3 describes the record management services, including the control block fields accessed by each service. This information is intended for a programmer using any programming language.
Appendix A contains the formats and associated usage notes for the RMS control block initialization and store macros used by VAX MACRO programmers.
Appendix B describes the VAX MACRO programming interface, and how to use RMS macros. This appendix also provides additional descriptions implementing groups of record management services, together with appropriate VAX MACRO example programs.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

In this manual, any reference to OpenVMS is synonymous with DIGITAL OpenVMS.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

The following conventions are used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.

{|} In command format descriptions, vertical bars separating items inside braces indicate that you choose one, none, or more than one of the options.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text Monospace text indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Part 1
OpenVMS RMS---General Information

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

Argument passing
Control blocks
Symbols defined by RMS
Invoking RMS services

Chapter 1
Introduction to RMS

This section presents an overview of the general functions available through RMS. It also briefly describes the record management services and related control blocks.

1.1 RMS Functions

RMS is a set of generalized services that assist application programs in processing and managing files and their contents. OpenVMS languages may invoke these services using appropriate macros stored in system libraries using the OpenVMS calling standard. Record management services are system services identified by the entry point prefix SYS$ followed by three or more characters; but the SYS prefix is omitted in the corresponding VAX MACRO macro name. 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 3.

Table 1-1 describes the functions of each service, including the service entry point name and its corresponding VAX MACRO macro name.

Table 1-1 Record Management Services
Service Name Macro Name Description

File Processing and File Naming Macros

SYS$CLOSE $CLOSE Terminates file processing and disconnects all record streams previously associated with the file

SYS$CREATE $CREATE Creates and opens a new file

SYS$DISPLAY $DISPLAY Returns the opened file's attributes to the application program

SYS$ENTER ¹ $ENTER Enters a file name into a directory

SYS$ERASE $ERASE Deletes a file and removes its directory entry

SYS$EXTEND $EXTEND Allocates additional space to a file

SYS$OPEN $OPEN Opens an existing file and initiates file processing

SYS$PARSE $PARSE Parses a file specification

SYS$REMOVE ¹ $REMOVE Removes a file name from a directory but does not actually delete the file data; compare this with the $ERASE macro

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 the specified record, establishes it as the current record and returns the record's RFA to the application program

SYS$FLUSH $FLUSH Writes (flushes) modified I/O buffers and file attributes to the disk before closing a file

SYS$FREE $FREE Unlocks all records previously locked by the record stream

SYS$GET $GET Retrieves a record from a file

SYS$NXTVOL ¹ $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 Establishes the first file record as the current record

SYS$TRUNCATE $TRUNCATE Truncates a sequential file

SYS$UPDATE $UPDATE Deletes and rewrites (updates) an existing file record

SYS$WAIT $WAIT Awaits the completion of an asynchronous record operation

Block I/O Processing Macros

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

**Table 1-1 Record Management Services**
Service Name	Macro Name	Description
File Processing and File Naming Macros
SYS$CLOSE	$CLOSE	Terminates file processing and disconnects all record streams previously associated with the file
SYS$CREATE	$CREATE	Creates and opens a new file
SYS$DISPLAY	$DISPLAY	Returns the opened file's attributes to the application program
SYS$ENTER ¹	$ENTER	Enters a file name into a directory
SYS$ERASE	$ERASE	Deletes a file and removes its directory entry
SYS$EXTEND	$EXTEND	Allocates additional space to a file
SYS$OPEN	$OPEN	Opens an existing file and initiates file processing
SYS$PARSE	$PARSE	Parses a file specification
SYS$REMOVE ¹	$REMOVE	Removes a file name from a directory but does not actually delete the file data; compare this with the $ERASE macro
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 the specified record, establishes it as the current record and returns the record's RFA to the application program
SYS$FLUSH	$FLUSH	Writes (flushes) modified I/O buffers and file attributes to the disk before closing a file
SYS$FREE	$FREE	Unlocks all records previously locked by the record stream
SYS$GET	$GET	Retrieves a record from a file
SYS$NXTVOL ¹	$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	Establishes the first file record as the current record
SYS$TRUNCATE	$TRUNCATE	Truncates a sequential file
SYS$UPDATE	$UPDATE	Deletes and rewrites (updates) an existing file record
SYS$WAIT	$WAIT	Awaits the completion of an asynchronous record operation
Block I/O Processing Macros
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

¹This service is not supported for network operations involving file access between remote OpenVMS systems.

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

RMS provides a variety of disk file organizations, record formats, and record access modes from which you can select the appropriate processing techniques for your application. 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 RMS record access modes permit you to access records sequentially, directly by key value, directly by relative record number, or directly by record file address (RFA). RMS also provides a means of performing block I/O operations for users with certain performance-critical applications (such applications may require user-defined file organizations or record formats, or both).

RMS ensures safe and efficient file sharing by providing:

Multiple file access modes to match file sharing with file operations
Automatic record locking in applicable file access modes that ensures data integrity during record updates
Optional buffer sharing to minimize I/O operations when multiple processes access the same file

RMS also enforces the security requirements of a multiuser system with potential multinode access by restricting file access to one or more user types and a list of user names.

For systems that support network capabilities, 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.2 Passing Arguments to RMS

RMS flexibility requires application programs to pass a multitude of arguments to RMS services for doing common operations such as file creation and file access. To minimize the 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 a record management service. The only argument required for most services is the symbolic address of the appropriate data control block.

1.2.1 Record Management Services and Control Blocks

Because RMS operates on files and records, its services generally belong to 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, RMS provides two types of control blocks:

Control blocks that provide file-related arguments to file services
Control blocks that provide record-related arguments to record services

1.2.2 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; the following list briefly introduces each category.

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

The two types of optional control blocks that can supplement or supersede the information in the FAB are the extended attribute block (XAB, pronounced "zab") and the NAM or NAML block.

A XAB usually supersedes and supplements the file characteristics specified in the associated FAB, and multiple XABs may 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 when the files were backed up, created, and expired. It also provides the time and date for file revisions 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)---on VAX systems, 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 HDR1 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 closing a file.
Recovery unit XAB (XABRU)---on VAX systems, supports the use of recovery units to assure data file integrity.
Summary XAB (XABSUM)---stores additional file characteristics associated with an indexed file.

Contents

Index

privacy and legal statement

4523PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[\|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
{\|}	In command format descriptions, vertical bars separating items inside braces indicate that you choose one, none, or more than one of the options.
bold text	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace text indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.