Document revision date: 30 March 2001

## Guide to OpenVMS File Applications

Order Number: AA-PV6PD-TK

## April 2001

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.2 and OpenVMS VAX Version 7.2

Software Version: OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, AlphaServer, VAX, VMS, the Compaq logo Registered in U.S.
and Patent and Trademark Office.

Alpha, OpenVMS, PATHWORKS, DECnet, and DEC are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.

UNIX and X/Open are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be the 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.

## Related Documents

Related reference information is available in the following documents:

- The OpenVMS Record Management Utilities Reference Manual contains information about the record management utilities including the Analyze/RMS_File utility, the Convert and Convert/Reclaim utilities, and the File Definition Language, which includes the Create/FDL utility and the Edit/FDL utility.
- The OpenVMS DCL Dictionary contains information (with examples) about using DCL commands that define system or process defaults, set file protection, or define logical names.
- The OpenVMS Record Management Services Reference Manual contains information about calling OpenVMS record management services (RMS) directly and about the control block options that are available. This book also describes the RMS control blocks that define arguments for service calls performed through language statements or directly from application programs.
- The OpenVMS Utility Routines Manual contains information about calling FDL routines and Convert routines. It also includes appropriate programming examples.
- Programmers using DECnet for OpenVMS software to access remote files may need to consult the DECnet for OpenVMS Networking Manual to determine what types of operations are supported for remote files on operating systems other than OpenVMS systems. Information on accessing remote files on an OpenVMS system can be obtained from the description of the appropriate FDL attributes in the OpenVMS Record Management Utilities Reference Manual and the description of the appropriate control block fields in the OpenVMS Record Management Services Reference Manual.

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

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

## 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

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

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

If you need help deciding which documentation best meets your needs, call 800-282-6672.

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

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.

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; 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 | Default disk structure of the OpenVMS operating system; use to share data between VAX and Alpha with full compatibility.
ODS-5 | Both | Alpha only 1; 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.

1You 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 1 | Alpha: 255 2 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.

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

Next | Contents | Index

| privacy and legal statement |
4506PRO.HTML