Guide to OpenVMS File Applications

Document revision date: 15 July 2002

Order Number: AA--PV6PE--TK

June 2002

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

Revision/Update Information: This manual supersedes the Guide to OpenVMS File Applications, 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 and VMS are trademarks of Compaq Information Technologies Group, L.P. in the U.S. and/or other countries.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the U.S. and/or other countries.

Motif, OSF/1, UNIX, and X/Open 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.

ZK4506

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

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

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.

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 of 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. Users can read from and write to disks. They can read from CD-ROMs and if they have a CD-Recordable (CD-R or CD-RW) drive, they can write (or burn) their own 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 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 and later 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 Default disk structure of the OpenVMS operating system; use to share data between VAX and Alpha with full compatibility.

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

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	Default disk structure of the OpenVMS operating system; use to share data between VAX and Alpha with full compatibility.
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 Macintoshes.
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 Levels
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 Levels**
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.

Note

Future enhancements to OpenVMS software will be based primarily on structure levels 2 and 5; therefore, structure level 1 volumes might be further restricted in the future. However, Compaq does not intend for ODS-5 to become the default OpenVMS file structure. The principal use of ODS-5 will be when OpenVMS is a server for other systems (such as Windows NT) that have extended file names.

The default disk structure is Files--11 ODS-2. VAX systems also support Files--11 ODS-1 from earlier operating systems ¹ to ensure compatibility among systems.

Note

¹ Earlier operating systems include the RSX--11M, RSX--11D, RSX--11M--PLUS, and Micro/RSX systems.

Contents

Index

privacy and legal statement

4506PRO.HTML

Internet	openvmsdoc@compaq.com
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.
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.