HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

Order Number: AA--PV6RE--TK

June 2002

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.3 and OpenVMS VAX Version, 7.3

Software Version: OpenVMS Alpha Version, 7.3--1
OpenVMS VAX Version, 7.3

Compaq Computer Corporation
Houston, Texas

COMPAQ, the Compaq logo, Alpha, OpenVMS, Tru64, VAX, VMS, and the DIGITAL logo are trademarks of Compaq Information Technologies Group, L.P., in the U.S. and/or other countries.

Motif, OSF/1, and UNIX are trademarks of The Open Group in the U.S. and/or other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK4523

The Compaq OpenVMS documentation set is available on CD-ROM.

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. Please send comments to either of the following addresses:

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

How To Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation:

http://www.openvms.compaq.com/

Conventions

In this manual, any reference to OpenVMS is synonymous with Compaq 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.
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 choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
\|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold text	This typeface represents the introduction of a new term. It also represents 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 type 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

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

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