Guide to OpenVMS File Applications

Document revision date: 19 July 1999

Order Number: AA--PV6PC--TK

January 1999

This document is intended for application programmers and designers who write programs that use OpenVMS RMS files.

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 Digital 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, DEC, DECdirect, DECnet, DECwindows, Digital, Micro/RSX, OpenVMS, PATHWORKS, RSX-11, RSX-11M, RSX-11M-PLUS, VAX, VAX DOCUMENT, VAX MACRO, VAXcluster, VMS, VMScluster, and the Compaq logo.

The following is a third-party trademark:

PostScript is a registered trademark of Adobe Systems Incorporated.

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

ZK4506

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 is intended for applications programmers and designers who create or maintain application programs that use RMS files.

You may also read this document to gain a general understanding of the file- and record-processing options available on an OpenVMS system.

Document Structure

This guide contains 10 chapters, one appendix, and a glossary.

Chapter 1 provides general information on file, disk, and magnetic tape concepts and brief overviews of available media, RMS, FDL, and resource requirements.
Chapter 2 describes the file organizations and record access modes to help you choose the correct file organization for your application.
Chapter 3 discusses general performance considerations and specific decisions you can make in the design of your application.
Chapter 4 describes procedures necessary to create files, populate files with records, and protect files.
Chapter 5 describes file specifications and the procedures needed to use them.
Chapter 6 describes the rules of file specification parsing and advanced file specification use. Information about rooted directories is also provided.
Chapter 7 describes file sharing and buffering, including record locking and the use of global buffers.
Chapter 8 describes aspects of record processing, including record access modes; synchronous and asynchronous record operations; and retrieving, inserting, updating, and deleting records.
Chapter 9 describes how to specify run-time options and summarizes the run-time options available when a file is opened and closed and when records are retrieved, inserted, updated, and deleted.
Chapter 10 describes procedures needed to maintain properly tuned files, with the emphasis on efficiently maintaining indexed files.
Appendix A describes the algorithms used by the Edit/FDL utility.
The Glossary provides definitions of terms that are commonly used in this guide.

Associated Documents

The reader should be familiar with the information in the following documents:

The OpenVMS User's Manual describes the use of the operating system for a general audience.
Programmers should be familiar with the appropriate documentation for the high-level language in which the application will be written.
System managers should be familiar with the OpenVMS System Manager's Manual, a task-oriented guide to managing an OpenVMS system.

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 881-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, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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 required elements; you must choose one of the options listed.

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

Chapter 1
Introduction

This chapter illustrates how basic data management concepts are applied by the OpenVMS Record Management Services (OpenVMS RMS), referred to hereafter as RMS. RMS is the data management subsystem of the operating system. In combination with OpenVMS operating systems, RMS allows efficient and flexible storage, retrieval, and modification of data on disks, magnetic tapes, and other devices. RMS may be implemented through the File Definition Language (FDL) interface or through high-level language, program-specific processing options. Although RMS supports devices such as line printers, terminals, and card readers, the purpose of this guide is to introduce you to RMS record keeping on magnetic tape and disk.

In contrast to magnetic tape storage, disk storage allows faster data access while providing the same virtually limitless storage capacity. Disks provide faster access because the computer can locate files and records selectively without first searching through intervening data. This faster access time makes disks the most appropriate medium for online file processing applications.

1.1 File Concepts

The following file concepts are discussed in this manual:

Files
Records
Fields
Bytes and bits
Access modes
Record formats
Maximum RMS file size

A computer file is an organized collection of data stored on a mass storage volume and processed by a central processing unit (CPU). Data files are organized to accommodate the processing of data within the file by an application program. The basic unit of electronic data processing is the record. A record is a collection of related data that the application program processes as a functional entity. For example, all the information about an employee, such as name, street address, city, and state, constitutes a personnel record. Records are made up of fields, which are sets of contiguous bytes. For example, a person's name or address might be a field. A byte is a group of binary digits (bits) that are used to represent a single character. You can also think of a field or an item as a group of bytes in a record that are related in some way.

The records in a file must be formatted uniformly. That is, they must conform to some defined arrangement of the record fields including the field length, field location, and the field data type (character strings or binary integers, for instance). To process file data, an application must know the arrangement of the record fields, especially if the application intends to modify existing records or to add new records to the file.

The file organization is the manner in which data is recorded within a file, typically using either fixed-length or variable-length records. The file organization, together with the applicable storage medium, determines what techniques are used to access data. Currently, RMS supports two methods of record access: sequential access and direct access. Direct access includes relative access (using the relative position of a record) and indexed access (using an indexing key within the record). See Table 1-1 for more information about record access methods.

Table 1-1 Record Access Methods
Access Method Description

Sequential Access Records are stored or retrieved one after another starting at a particular point in the file and continuing in order through the file.

Relative Record Number Access Records are stored and retrieved by relative record number or by file address. Records occupy cells of equal length, and each cell is assigned a relative record number, which represents the cell's position relative to the beginning of the file.

Record File Address Access When a record is accessed directly by its file address, the distinction is made by its unique location in the file; that is, its record file address (RFA).

Indexed Access Indexed file records are stored and retrieved by a key in the data record. The desired records are usually accessed directly and then retrieved sequentially in sorted order using a key embedded in the record.

**Table 1-1 Record Access Methods**
Access Method	Description
Sequential Access	Records are stored or retrieved one after another starting at a particular point in the file and continuing in order through the file.
Relative Record Number Access	Records are stored and retrieved by relative record number or by file address. Records occupy cells of equal length, and each cell is assigned a relative record number, which represents the cell's position relative to the beginning of the file.
Record File Address Access	When a record is accessed directly by its file address, the distinction is made by its unique location in the file; that is, its record file address (RFA).
Indexed Access	Indexed file records are stored and retrieved by a key in the data record. The desired records are usually accessed directly and then retrieved sequentially in sorted order using a key embedded in the record.

The record format refers to the way all records in a file appear physically on the recording surface of the storage medium and is defined in terms of record length. Table 1-2 describes the four record formats supported by RMS.

Table 1-2 Record Formats
Record Format Description

Fixed length All records are the same length.

Variable length Records vary in length. Each record is prefixed with a count byte that contains the number of bytes in the record. The count byte may be either MSB- or LSB-formatted.

Variable record length with
fixed-length control Records do not have to be the same length, but each includes a fixed-length control field that precedes the variable-length data portion.

Stream Records are delimited by special characters or character sequences called terminators. Records with stream format are interpreted as a continuous sequence, or stream, of bytes. The carriage return and the line feed characters are commonly used as terminators.

**Table 1-2 Record Formats**
Record Format	Description
Fixed length	All records are the same length.
Variable length	Records vary in length. Each record is prefixed with a count byte that contains the number of bytes in the record. The count byte may be either MSB- or LSB-formatted.
Variable record length with fixed-length control	Records do not have to be the same length, but each includes a fixed-length control field that precedes the variable-length data portion.
Stream	Records are delimited by special characters or character sequences called terminators. Records with stream format are interpreted as a continuous sequence, or stream, of bytes. The carriage return and the line feed characters are commonly used as terminators.

When you design a file, you specify the file storage medium and the file and record characteristics directly through your application program or indirectly using an appropriate utility. Chapter 2 outlines RMS file organization, record access modes, and record characteristics in detail.

After RMS creates the file, the application program must consider these record characteristics when storing, retrieving, and modifying records. See Chapter 4 for information about creating files, populating files with records, and protecting files. See Chapter 8 for information about record processing, including record access modes; synchronous and asynchronous record operations; and retrieving, inserting, updating, and deleting records.

The maximum size of an RMS file has no built-in limitation other than the 32-bit virtual block number (VBN). In terms of blocks, a single file is limited to a VBN that must be described in 32 bits. So the maximum size of an RMS file is about 4.2 billion (4,294,967,295) blocks. In terms of bytes, this is equivalent to 2 terabytes.

1.2 Disk Concepts

This section describes disk concepts as an aid to understanding how a disk may be configured to enhance data access for improved performance. Disk structures may be defined as either logical or physical and the two types interact with each other to some degree. That is, you cannot manipulate a logical structure without considering the effect on a corresponding physical structure.

RMS disk files reside on Files--11 On-Disk Structure (ODS) disks. Files--11 is the name applied to the disk structures supported by the operating system. Files--11 disk structures are further characterized as being either on-disk structures or CD-ROM volume and file structures. The Files--11 structure is a hierarchical organization of files, their data, and the directories needed to gain access to them. The OpenVMS file system implements the Files--11 on-disk structure and provides random access to the files located on the disk or CD-ROM. Users can read from and write to disks; they can only read from CD-ROMs.

On-disk structures include Levels 1, 2, and 5. (Levels 3 and 4 are internal names for ISO and High Sierra CD formats.) ODS-1 and ODS-2 structures have been available on OpenVMS systems for some time. Beginning with OpenVMS Version 7.2--EFT2 on Alpha systems, you can also specify ODS-5 to format disks.

Table 1-3 compares the characteristics of file structures that are available on OpenVMS Version 7.2--EFT1 systems.

Table 1-3 File Structure Options on OpenVMS Systems
Structure Disk or CD Description

ODS-1 Both VAX only; use for RSX compatibility: RSX--11M, RSX--11D, RSX--11M--PLUS, and IAS operating systems.

ODS-2 Both Use to share data between VAX and Alpha with full compatibility; default disk structure of the OpenVMS operating system.

ODS-5 Both Alpha only ¹; superset of ODS-2; use when working with systems like NT that need expanded character sets or directories deeper than ODS-2.

ISO 9660 CD CD ISO format files: read by systems that do not have ODS-2 capability such as PCs, NT systems, and MACs.

Dual format CD Single volume with both ISO 9660 CD and Files-11 CD formats. Files are accessible to both formats, whose directories might point to the same data.

Foreign Both A structure that is not related to a Files--11 structure. When you specify a foreign structure, you make the contents of a volume known to the system, but the system makes no assumptions about its file structure. The application is responsible for supplying a structure.

**Table 1-3 File Structure Options on OpenVMS Systems**
Structure	Disk or CD	Description
ODS-1	Both	VAX only; use for RSX compatibility: RSX--11M, RSX--11D, RSX--11M--PLUS, and IAS operating systems.
ODS-2	Both	Use to share data between VAX and Alpha with full compatibility; default disk structure of the OpenVMS operating system.
ODS-5	Both	Alpha only ¹; superset of ODS-2; use when working with systems like NT that need expanded character sets or directories deeper than ODS-2.
ISO 9660 CD	CD	ISO format files: read by systems that do not have ODS-2 capability such as PCs, NT systems, and MACs.
Dual format	CD	Single volume with both ISO 9660 CD and Files-11 CD formats. Files are accessible to both formats, whose directories might point to the same data.
Foreign	Both	A structure that is not related to a Files--11 structure. When you specify a foreign structure, you make the contents of a volume known to the system, but the system makes no assumptions about its file structure. The application is responsible for supplying a structure.

¹You can mount ODS-5-enabled volumes on VAX systems, but you cannot access ODS-5-specific features on a VAX system.

Table 1-4 compares the specific characteristics of Files--11 On-Disk Structure (ODS) Levels 1, 2, and 5.

Table 1-4 Comparison of ODS-1, ODS-2, and ODS-5
Characteristic ODS-1 (VAX only) ODS-2 ODS-5

File names 9.3 39.39 238 bytes, including the dot. For Unicode, that is 119 characters including the dot.

Character set Uppercase alphanumeric Uppercase alphanumeric plus hyphen (-), dollar sign ($), and underscore (_) ISO Latin-1, Unicode

File versions 32,767 limit; version limits are not supported 32,767 limit; version limits are supported. 32,767 limit; version limits are supported.

Directories No hierarchies of directories and subdirectories; directory entries are not ordered ¹ Alpha: 255 ²
VAX: 8 (with rooted logical, 16) Alpha: 255
VAX: 8 (with rooted logical, 16)

System disk Cannot be an ODS-1 volume Can be an ODS-2 volume Cannot be an ODS-5 volume

OpenVMS Cluster access Local access only; files cannot be shared across a cluster Files can be shared across a cluster Files can be shared across a cluster. However, only computers running OpenVMS Version 7.2--EFT1 or later can mount ODS-5 disks. VAX computers running Version 7.2--EFT1 or later can see only files with ODS-2 style names.

Disk Unprotected objects Protected objects Protected objects

Disk quotas Not supported Supported Supported

Multivolume files and volume sets Not supported Supported Supported

Placement control Not supported Supported Supported

Caches No caching of file header blocks, file identification slots, or extent entries Caching of file header blocks, file identification slots, and extent entries Caching of file header blocks, file identification slots, and extent entries

Clustered allocation Not supported Supported Supported

Backup home block Not supported Supported Supported

Protection code E E means "extend" for the RSX--11M operating system but is ignored by OpenVMS E means "execute access" E means "execute access"

Enhanced protection features (for example, access control lists) Not supported Enhanced protection features supported Enhanced protection features supported

RMS journaling Not supported Supported Supported

**Table 1-4 Comparison of ODS-1, ODS-2, and ODS-5**
Characteristic	ODS-1 (VAX only)	ODS-2	ODS-5
File names	9.3	39.39	238 bytes, including the dot. For Unicode, that is 119 characters including the dot.
Character set	Uppercase alphanumeric	Uppercase alphanumeric plus hyphen (-), dollar sign ($), and underscore (_)	ISO Latin-1, Unicode
File versions	32,767 limit; version limits are not supported	32,767 limit; version limits are supported.	32,767 limit; version limits are supported.
Directories	No hierarchies of directories and subdirectories; directory entries are not ordered ¹	Alpha: 255 ² VAX: 8 (with rooted logical, 16)	Alpha: 255 VAX: 8 (with rooted logical, 16)
System disk	Cannot be an ODS-1 volume	Can be an ODS-2 volume	Cannot be an ODS-5 volume
OpenVMS Cluster access	Local access only; files cannot be shared across a cluster	Files can be shared across a cluster	Files can be shared across a cluster. However, only computers running OpenVMS Version 7.2--EFT1 or later can mount ODS-5 disks. VAX computers running Version 7.2--EFT1 or later can see only files with ODS-2 style names.
Disk	Unprotected objects	Protected objects	Protected objects
Disk quotas	Not supported	Supported	Supported
Multivolume files and volume sets	Not supported	Supported	Supported
Placement control	Not supported	Supported	Supported
Caches	No caching of file header blocks, file identification slots, or extent entries	Caching of file header blocks, file identification slots, and extent entries	Caching of file header blocks, file identification slots, and extent entries
Clustered allocation	Not supported	Supported	Supported
Backup home block	Not supported	Supported	Supported
Protection code E	E means "extend" for the RSX--11M operating system but is ignored by OpenVMS	E means "execute access"	E means "execute access"
Enhanced protection features (for example, access control lists)	Not supported	Enhanced protection features supported	Enhanced protection features supported
RMS journaling	Not supported	Supported	Supported

¹RSX--11M, RSX--11D, RSX--11M--PLUS, and IAS systems do not support subdirectories and alphabetical directory entries.
²Prior to OpenVMS Version 7.2, RMS limited directory levels to 8 or 16.

Contents

Index

privacy and legal statement

4506PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-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 required elements; you must choose one of the options listed.
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 type	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.