Document revision date: 30 March 2001

## Guide to OpenVMS File Applications

Previous | Contents | Index

#### 2.1.2.2 Variable-Length Record Format

When you specify the variable-length record format, each record is as long as the data within it requires, except that all records are padded to an even number of bytes. The number of bytes is encoded in a 2-byte count field prefixed to the record.

The field may be coded in either LSB (least significant byte) or MSB (most significant byte) format.

The count field for each record begins on an even-byte boundary and contains the number of bytes in the record. RMS builds the count field from information in your program and treats it separately from the associated record data field.

RMS uses the following types of variable-length record formats:

V (LSB) format | Applies to variable-length records in disk files. RMS prefixes the data portion of each variable-length V (LSB) record with a 2-byte, binary count field in LSB format that specifies the length of the record in bytes, excluding the count field itself.
V (MSB) format | Applies to variable-length records in disk files. RMS prefixes the data portion of each record with a 2-byte, binary count field in MSB format that specifies the length of the record in bytes, excluding the count field itself.
D format | Applies to variable-length records in tape files. To comply with the American National Standard X3.27-1978 (Level 3), Magnetic Tape Labels and Record Formats for Information Interchange, RMS stores a 4-byte decimal count field before the data field of each record on a magnetic tape volume. In contrast to V-format records, the count field is considered as part of the record; but before returning the count, RMS adjusts it to include only the length of the record data.

When you create a file of variable-length records, specify the value (in bytes) of the largest record permitted in the file.

If you take the block span option (the default), the maximum variable-length record size is 32767 bytes. If you specify no block spanning, the maximum variable-length record size is 510 bytes. For additional information about selecting the block span option, see the OpenVMS Record Management Services Reference Manual.

Any attempt to store a record containing more bytes than the specified value results in an error. If you specify a value of 0, any length record can be stored; however, you must consider the bucket capacity limitation defined for relative and indexed files.

Figure 2-6 compares fixed-length record formats and variable-length record formats as they apply to sequential files. Each format shows a portion of a file that contains three records. The comparable record in each format contains the same number of bytes. The first record has 8 bytes, the second, 16, and the third, 24. For the fixed-length record format, the record length is set at 32 bytes. Therefore, RMS considers all 32 bytes to be used.

Figure 2-6 Comparison of Fixed- and Variable-Length Records

Clearly, variable-length records can save space; but if records are updated in place, you should consider trading off some space efficiency for update flexibility. All records in a relative file are in fixed-length cells. Here, variable-length records do not save space; in fact, the two count-field bytes prefixing each record actually consume additional space.

In the indexed file organization, the capacity of the data bucket and the maximum record size limit record length.

#### 2.1.2.3 Variable-Length with Fixed-Length Control Field (VFC) Record Format

VFC records are similar to variable-length records except that a fixed-length control field is prefixed to the variable-length data portion. Unlike variable-length records, VFC records cannot be used in indexed files.

When you create a file for VFC records, you must specify the value (in bytes) of the longest record permitted in the file. If you accept the block span option (the default), the maximum VFC record size is 32767 bytes, less the number of bytes in the fixed-length control field. If you specify no block spanning, the maximum VFC record size is 510 bytes, less the number of bytes in the fixed-length control field. For additional information about selecting the block span option, see the OpenVMS Record Management Services Reference Manual.

Any attempt to store a record containing more bytes than the specified value results in an error. If you specify a value of 0, any length record can be stored.

You must also specify the value in bytes of the fixed-length control field. The fixed-length control field lets you include within the record additional data that may have no direct relationship to the other contents of the record. For example, the fixed-length control field may contain line-sequence numbers for every record in the file. The program does not use the line-sequence numbers, but they are helpful in locating records during file editing.

At the VAX MACRO level, you establish the length of the control field for VFC records using the FAB$B_FSZ field in the FAB. The Open, Create, and Display services provide the control field length in the XAB$B_HSZ field of the File Header Characteristic XAB. For more information, see the OpenVMS Record Management Services Reference Manual.

When writing a VFC record to a file, RMS merges the fixed-length control field with the variable-length record data and prefixes the merged record with the count field. Figure 2-7 shows how RMS writes a VFC record to a file.

Figure 2-7 Writing a VFC Record to a File

When RMS reads a VFC record, it uses the count field to determine the overall length of the record, and it uses the appropriate file attribute to determine the length of the control field. After subtracting the control-field length from the overall record length, RMS uses the result to separate the data from the control information. It then processes the data and stores the control information in a designated storage area for program use, if applicable. See Figure 2-8.

Figure 2-8 Retrieving a VFC Record

#### 2.1.2.4 Stream Record Format

There are four variations of stream record format. Special characters or character sequences called terminators delimit the records in files using the first three variations:

STREAM_CR | This variation uses a carriage return as the terminator.
STREAM_LF | This variation uses a line feed as the terminator.
STREAM | This variation ignores leading zeros and uses a terminator from a limited set of special characters: the line feed (LF), the carriage-return/line-feed combination (CR/LF), the form feed (FF), or the vertical tab (VT).
UNDEFINED | This variation has no terminator. The length of each record is determined by the size of the user buffer (maximum 65,535 bytes), or the end-of_file.

RMS supports the stream record format for sequential files on disk devices only. In a stream-formatted file, RMS treats the data as a continuous stream of bytes, without control information. Stream records are always permitted to span block boundaries.

## 2.2 File Organization Concepts

The terms file organization and access mode are closely related, but they are distinct from each other, nonetheless.

You establish the physical arrangement of records in the file---the file organization---when you create it. The organization of a file cannot be changed unless you use a utility conversion routine (such as the Convert utility) to create the file again with a different organization. Note that the Convert utility processes relative files by sequentially reading records from the input file, then writing them to the output file. As a result, the relative record numbers (RRN) change when the input file contains deleted or unused records.

One of the file attributes you specify before creating a file is how records are inserted into it and subsequently retrieved from it---the access mode.

The terms file organization and access mode are sometimes confused because they share common elements. That is, files are organized sequentially, relative to some reference value, or by keyed index value. Similarly, a file may be accessed sequentially, relative to some reference value, or by using a keyed index value. The following sections emphasize the distinctions between the types of file organization.

Table 2-2 lists important features of each file organization.

Table 2-2 File Organization Characteristics
Characteristics | Sequential | Relative | Indexed
--- | --- | --- | ---
Medium
Disk | Yes | Yes | Yes
Magnetic tape | Yes | No 1 | No 1
Unit record 2 | Yes | No | No
Record Formats
Fixed-length | Yes | Yes | Yes
Variable-length | Yes | Yes | Yes
VFC (disk only) | Yes | Yes | No
Stream (disk only) | Yes | No | No
Undefined (disk only) | Yes | No | No
Overhead Per Record
| 0, 1, or 2 bytes 3 | 1 or 3 bytes 4 | 7 to 13 bytes 5
Record Operations
Connect | Yes | Yes | Yes
Delete | No | Yes | Yes
Disconnect | Yes | Yes | Yes
Find | Yes | Yes | Yes
Flush | Yes | Yes | Yes
Free | Yes | Yes | Yes
Get | Yes | Yes | Yes
Rewind | Yes | Yes | Yes
Truncate | Yes | No | No
Update (disk only) | Yes | Yes | Yes
Put | Yes | Yes | Yes
I/O Unit
| 1 or more blocks | Bucket | Bucket
I/O Techniques
Deferred write | Normal mode | Selectable | Selectable
Multiblock count | Yes | Bucket size | Bucket size
Multiple access streams | Yes | Yes | Yes
Multiple buffers | Yes | Yes | Yes
Access sharing | Read/write | Read/write | Read/write
Other features | Block-spanning records | Maximum record number | Areas

1Although these file organizations are not compatible with magnetic tape operations, you may use magnetic tape to transport the files.
2Unit record devices include printers, terminals, card readers, mailboxes, and so forth.
3Fixed-length records and records with undefined format use no overhead; stream records use either 1 or 2 bytes of overhead; variable-length and VFC records use 2 bytes of overhead.
4Fixed-length records use 1 byte of overhead; variable-length records and VFC records use 3 bytes of overhead; extra overhead applies to each cell.
5Prolog 1 and Prolog 2 fixed-length records use 7 bytes of overhead. Prolog 1 and Prolog 2 variable-length records use 9 bytes of overhead. For Prolog 3, fixed-length records use 9 bytes of uncompressed overhead, and variable-length records use 11 bytes of uncompressed overhead. For key compression, add 2 bytes of overhead.

The next three sections describe file organizations.

### 2.2.1 Sequential File Organization

RMS supports the sequential file organization for all device types. It is the only organization supported for nondisk devices.

In sequential file organization, records are arranged one after the other in the order in which they are stored. For example, the fourth record is between the third and fifth records, as illustrated in Figure 2-9.

Figure 2-9 Sequential File Organization

You cannot insert new records between existing records because no physical space separates them. Therefore, you can only add records to the current end of the file, that is, immediately following the most recently added record. For the same reason, you cannot add to the length of an existing record when updating it.

Some advantages and disadvantages of the sequential file organization are outlined in Table 2-3.

Table 2-3 Sequential File Organization: Advantages and Disadvantages
Advantages | Disadvantages
--- | ---
Simplest organization | To get a particular record, most higher-level languages must access all the records before it---no random access by key. 1
Minimum overhead on disk | Interactive processing is awkward; operator must wait as the program searches for a record.
Allows block spanning | You can add records only to the end of the file.
Optimal if application accesses all records on each run |
Most versatile format: exchange data with systems other than RMS; compatible with ANSI magnetic tape format |
No restrictions on the type of storage media; the file is portable |
Random access by key available on fixed-format disk sequential files |

1This restriction does not apply to disk sequential files with fixed-length record format. Records in such files can be stored and retrieved using random access by key, depending on language capabilities.

### 2.2.2 Relative File Organization

The relative file organization allows sequential and random access of records on disk devices only.

Note Although relative files are not supported for magnetic tape operations, magnetic tape can be used to transport relative files.

In fact, relative files provide the fastest random access, and they require fewer tuning considerations.

A relative file consists of a series of fixed-length record positions (or cells) numbered consecutively from 1 to n that enables RMS to calculate the record's physical position on the disk. The number, referred to as the relative record number, indicates the record cell's position relative to the beginning of the file.

RMS uses the relative record number as the key value to randomly access records in a relative file. The preferred method of tracking relative record numbers is to assign them based on some numeric field within the record, for example, the account number.

See Section 2.1.1.2 for a description of random access by key.

Each record in the file may be randomly assigned to a specific cell. For example, the first record may be assigned the first cell and the second record may be assigned the third cell, leaving the second cell empty. Unused cells and cells from which records have been deleted may be used to store new records.

Figure 2-10 illustrates the relative file organization.

Figure 2-10 Relative File Organization

In a relative file, the actual length of the individual records may vary (that is, different size records can be in the same file) up to the limits imposed by the specified cell length. For example, think of a relative file configured as shown in Figure 2-11.

Note that because the records are variable-length records, each is prefixed by 3 bytes: the 2-byte count field (described in Section 2.1.2.2) and a 1-byte field that indicates whether or not the cell is empty (a delete flag). These bytes are used only by RMS---you need not be concerned with them, except when planning the file's space requirements.

Figure 2-11 Variable-Length Records in Fixed-Length Cells

Some advantages and disadvantages of relative file organization are outlined in Table 2-4.

Table 2-4 Relative File Organization: Advantages and Disadvantages
Advantages | Disadvantages
--- | ---
Random access in all languages | Restricted to disk devices.
Allows deletions | File contains a cell for each cell number between first and last record in file; limits data density.
Allows random Get and Put operations | Program must know relative record number or RFA before it can randomly access the data; no generic access as in indexed file organization.
Random and sequential access with low overhead | Interactive access can be awkward if you do not access records by relative record number.
Can be write-shared | You can only insert records into unused record cells, but you can update existing records.
| RMS does not allow duplicate relative record numbers.
| The space taken up by each record is as long as the maximum record size.

### 2.2.3 Indexed File Organization

The indexed file organization allows sequential and random access of records on disk devices only. This type of file organization lets you store data records in an index structure ordered by the primary key and retrieve data using index structures ordered by primary or alternate keys. The alternate index structures do not contain data records; instead, they contain pointers to the data records in the primary index.

For example, an indexed file may be ordered in ascending sort order by the primary key "employee number." However, you may want to set up additional (alternate) indexes for retrieving records from the file. Typically, you might set up an alternate index in descending sort order by each employee's social security number.

Note The physical location of records in an indexed file is transparent to your program because RMS controls record placement.

In addition to the indexes, each indexed file includes a prolog structure that contains information about the file, including file attributes. RMS currently supports three distinct prologs---Prolog 1, Prolog 2 and Prolog 3---but RMS normally creates a Prolog 3 indexed file. However, you can specify a previous prolog version, typically for compatibility with RMS--11.

Previous | Next | Contents | Index

| privacy and legal statement |
4506PRO_005.HTML