Document revision date: 15 July 2002

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

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

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

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

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

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.

	privacy and legal statement
4506PRO_005.HTML