[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual

OpenVMS Record Management Services Reference Manual

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.

© Compaq Computer Corporation 1999. All rights reserved.

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.

Related Documents

The following documents contain information related to this reference manual:

For additional information on the Open Systems Software Group (OSSG) products and services, access the following OpenVMS World Wide Web address:


http://www.openvms.digital.com 

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:


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


1This 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:

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:

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

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.

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:


Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4523PRO.HTML