Document revision date: 30 March 2001

## Guide to OpenVMS File Applications

Previous | Contents | Index

    version number =
    [(generation number - 1) * 100] + generation version-number + 1

Version numbers larger than 32,767 are divided by 32,768; the integer remainder becomes the version number.

On output, the generation number is derived from the version number with this calculation:

    generation number = [(version number - 1)/100] + 1

If there is a remainder after the version number is divided by 100, the remainder becomes the generation version number. It is not added to 1 to form the generation number.

Creation Date and Expiration Date Fields

The creation date field contains the date the file is created. The expiration date field contains the date the file expires. The system interprets the expiration date of the first file on a volume as the date that both the file and the volume expire. The creation and expiration dates are stored in the Julian format. This 6-character format (#YYDDD) permits the # symbol to consist of either an ASCII space or an ASCII zero, with the YYDDD consisting of a year and day value. If an ASCII space is indicated, it is assumed that 1900 is added to the two digit year value; if an ASCII zero is indicated, it is assumed that 2000 is added to the two digit year value. For the YYDDD part of the format, only dates are relevant for these fields; time is always returned as 00:00:00:00.

OpenVMS V5.1-1 and later versions implement the ASCII zero to the previously existing ASCII space per the ANSI X3.27--1987 standard, making them year 2000 ready. This ANSI standard is believed to be valid through the year 2100.

OpenVMS versions prior to V5.1-1 have known problems initializing and mounting magnetic tapes in the year 2000 and later.

By default, the current date is written to both the creation and expiration date fields when you create a file. Because the expiration date is the same as the creation date, the file expires on creation and you can overwrite it immediately. If the expiration date is a date that is later than the creation date and if the files you want to overwrite have not expired, you must specify the /OVERRIDE=EXPIRATION qualifier with the INITIALIZE or MOUNT command.

To write dates other than the defaults in the date fields in this label, specify the creation date field (CDT) and the expiration date field (EDT) of the RMS date and time extended attribute block (XABDAT).

When you do not specify a creation date, RMS defaults the current date to the creation date field. To specify a zero creation date, you must specify a year before 1900. If you specify a binary zero in the date field, the system will write the current date to the field.

For details on the XABDAT, see the OpenVMS Record Management Services Reference Manual.

Accessibility Field

The contents of this field are described in Section 1.3.1.5.

Implementation Identifier Field

The implementation identifier field specifies, using ASCII "a" characters, an identification of the implementation that recorded the Volume Header Label Set.

##### 1.3.1.6.2 HDR2 Label

The HDR2 label describes the record format, maximum record size, and maximum block size of a file.

Record Format Field

The record format field specifies the type of record format the file contains. The operating system supports two record formats: fixed length (F) and variable length (D). When files contain record formats that the system does not support, it cannot interpret the formats and classifies them as undefined.

Fixed-length records are all the same length. No indication of the record length is required within the records because either the HDR2 label defines the record length or you specify the record length with the /RECORDSIZE qualifier. A fixed-length record can be a complete block, or several records can be grouped together in a block.

Fixed-length blocked records are padded to a multiple of 4 records. Variable-length records are padded to the block size. If a block is not filled, it will be padded with circumflex characters (^). The standard does not allow records containing only circumflexes; the system will interpret this as padding, not data.

Figure 1-11 shows a block of fixed-length records. Each record has a fixed length of 50 bytes. All six records are contained in a 300-byte block. The records are blocked---that is, grouped together as one entity---to increase processing efficiency; when records are blocked, you can access many of them with one I/O request. The block size should be a multiple of the record size.

Figure 1-11 Blocked Fixed-Length Records

The size of a variable-length record is indicated by a record control word (RCW). The RCW consists of four bytes at the beginning of each record. A variable-length record can be a complete block, or several records can be grouped together in a block.

Two variable-length records are shown in Figure 1-12. The first consists of 54 bytes, including the RCW. The second consists of 112 bytes, including the RCW. The records are contained in a 166-byte block.

Do not use system-dependent record formats on volumes used for information interchange. OpenVMS system-dependent formats are stream and variable with fixed-length control (VFC).

Figure 1-12 Variable-Length Records

Block Length Field

The block length field denotes the maximum size of the blocks. According to the ANSI magnetic tape standard, valid block sizes range from 18 to 2048 bytes. However, the operating system allows you to specify a smaller or larger block size by using the /BLOCKSIZE qualifier with the MOUNT command. To specify the block size using RMS, see the BLS field in the file access block (FAB) in the OpenVMS Record Management Services Reference Manual. When you specify a block size outside the ANSI magnetic tape standard range, the volume may not be processed correctly by other systems that support the ANSI magnetic tape standards.

Record Length Field

The record length field denotes either the size of fixed-length records or the maximum size of variable-length records in a file. Valid RMS record sizes vary, depending on the record format. The range for fixed-length records is 1 to 65,534 bytes; the range for variable-length records is 4 to 9,999 bytes, including the 4-byte RCW. Therefore, the maximum length of the data area of a variable-length record is 9,995 bytes. To comply with ANSI magnetic tape standards, the record size should not be larger than the maximum block size of 2,048 bytes, even though OpenVMS systems allow larger record sizes (when the block size is larger).

For volumes containing files that do not have HDR2 labels, you must specify MOUNT/RECORDSIZE=n at mount time. The variable n denotes the record length in bytes. Files without HDR2 labels were created by a system that supports only level 1 or 2 of the ANSI standard for magnetic tape labels and file structure. Records should be fixed length because this is the only record format that either level supports. If you do not specify a record size, each block will be considered a single record.

Implementation-Dependent Field

The implementation-dependent field contains two 1-character subfields that describe how the operating system interprets record format and form control.

The first subfield, character position 16, denotes whether the RMS attributes are in this label or the HDR3 label. If character position 16 contains a space, the RMS attributes are in the HDR3 label; if it contains any character other than a space, character position 16 is the first byte of the RMS attributes in the HDR2 label. The attributes appear in character positions 16 through 36 and 38 through 50.

The second subfield, the form control field at character position 37, specifies the form control that defines the carriage control applied to records within a file. Possible values supported for RMS magnetic tape volumes are listed below.

A | First byte of record contains Fortran control characters.
M | The record contains all form control information.
space | Line-feed/carriage-return combination is to be inserted between records when the records are written to a carriage-control device, such as a line printer or terminal. If form control is not specified when a file is created, this is the default.

Buffer-Offset Length Field

For implementations that support buffer offsets, the buffer-offset length field indicates the length of information that prefixes each data block. The magnetic tape file system supports the input of buffer offset, which means that the buffer-offset length obtained from the HDR2 label (when reading the file) is used to determine the actual start of the data block. The magnetic tape file system does not support the writing of a buffer offset.

Note that, if you open a file for append or update access and the buffer-offset length is nonzero, the open operation will not succeed.

##### 1.3.1.6.3 HDR3 Label

The HDR3 label describes the RMS file attributes. For RMS operations, data in the HDR3 label supersedes data in the HDR2 label.

Although the HDR3 label usually exists for every file on an ANSI magnetic tape volume, there are two situations when this label will not be written. The first is when an empty dummy file is created during volume initialization; no HDR3 label is written because the empty file does not require RMS attributes. The second is when you specify MOUNT/NOHDR3 at mount time. You should use the /NOHDR3 qualifier when you create files on volumes that will be interchanged to systems that do not process HDR3 labels correctly.

The RMS attributes describe the record format of a file. These attributes are converted from 32 bytes of binary values to 64 bytes of ASCII representations of their hexadecimal equivalents for storage in the HDR3 label.

##### 1.3.1.6.4 HDR4 Label

The HDR4 label contains the remainder of an OpenVMS file name that would not fit in the HDR1 file identifier field.

#### 1.3.1.7 Trailer Labels

The operating system supports two sets of trailer labels: end-of-file (EOF) and end-of-volume (EOV). A trailer label is written for each header label.

EOF and EOV labels are identical to their file header label counterparts except that:

- The label identifier field (characters 1-3) contains EOF or EOV.
- The block count field (characters 55-60) in the EOF1 and EOV1 labels contains the number of data blocks in the file section.

The particular label that OpenVMS systems write depends on whether a file extends beyond a volume. If a file terminates within the limits of a volume, EOF labels are written to delimit the file (see Figure 1-7). If a file extends across volume boundaries before terminating, EOV labels are written, indicating that the file continues on another volume (see Figure 1-8).

## 1.4 Using Command Procedures to Perform Routine File and Device Operations

Many of the operations that you perform on disk and magnetic tape media are routine in nature. Therefore, you will find it worthwhile to take the time to identify those tasks that you routinely perform at your particular site. Once you have isolated those tasks, you can design command procedures to assist you in performing them.

For example, if you are a system manager or an operator, you must frequently perform data integrity tasks such as backing up media. You could enter all of the commands, parameters, and qualifiers required to back up your media each time that you perform the backup operation, or you can write a single command procedure (containing that set of commands, qualifiers, and parameters) that, when executed, would also perform the backup operation.

In order to familiarize yourself with the syntax used to design and execute command procedures, see the OpenVMS User's Manual.

## 1.5 Volume Protection

The system protects data on disk and tape volumes to make sure that no one accesses the data accidentally or without authorization. For volumes, the system provides protection at the file, directory, and volume levels. For tape volumes, the system provides protection at the volume level only.

In addition to protecting the data on mounted volumes, the system provides device protection coded into the home block of the disks and tapes. See Section 1.2 for more information.

In general, you can protect your disk and tape volumes with user identification codes (UICs) and access control lists (ACLs). The standard protection mechanism is UIC-based protection. Access control lists permit you to customize security for a file or a directory.

UIC-based protection is determined by an owner UIC and a protection code, whereas ACL-based protection is determined by a list of entries that grant or deny access to specified files and directories.

Note You cannot use ACLs with magnetic tape files.

When you try to access a file that has an ACL, the system uses the ACL to determine whether or not you have access to the file. If ACL does not explicitly allow or refuse you access or if the file has no ACL, the system uses the UIC-based protection to determine access. (See the OpenVMS Guide to System Security for additional information about system security.)

For detailed information about protecting your files, directories, or volumes, see Section 4.4.

## 1.6 RMS (Record Management Services)

OpenVMS Record Management Services (OpenVMS RMS or simply RMS) is the file and record access subsystem of the OpenVMS operating systems. RMS allows efficient and flexible data storage, retrieval, and modification for disks, magnetic tapes, and other devices.

You can use RMS from low-level and high-level languages. If you use a high-level language, it may not be easy or feasible to use the RMS services directly because you must allocate control blocks and access fields within them. Instead, you can rely on certain processing options of your language's input/output (I/O) statements or upon a specialized language provided as an alternative to using RMS control blocks directly, the File Definition Language (FDL).

If you use a low-level language, you can either use record management services directly, or you may use FDL.

### 1.6.1 File Definition Language (FDL)

FDL is a special-purpose language you can use to specify file characteristics. FDL is particularly useful when you are using a high-level language or when you want to ensure that you create properly tuned files. Properly tuned files can be created from an existing file or from a new design for a file. The performance benefits of properly tuned files can greatly affect application and system performance, especially when using large indexed files.

FDL allows you to use all of the creation-time capabilities and many of the run-time capabilities of RMS control blocks, including the file access block (FAB), the record access block (RAB), and the extended attribute blocks (XABs).

For more information about FDL, see Section 4.1.2.

### 1.6.2 RMS Data Structures

RMS control blocks generally fall into two groups: those pertaining to files and those pertaining to records.

To exchange file-related information with file services, you use a control block called a file access block (FAB). You use the FAB to define file characteristics, file specifications, and various run-time options. The FAB has a number of fields, each identified by a symbolic offset value. For instance, the allocation quantity for a file is specified in a longword-length field having a symbolic offset value of FAB$L_ALQ. FAB$L_ALQ indicates the number of bytes from the beginning of the FAB to the start of the field.

To exchange record-related information with RMS, you use a control block called a record access block (RAB). You use the RAB to define the location, type, and size of the input and output buffers, the record access mode, certain tuning options, and other information. The symbolic offset values for the RAB fields have the prefix RAB$ to differentiate them from the values used to identify FAB fields. The RAB symbolic offset values have the same general format, where the letter following the dollar sign indicates the field length and the letters following the underscore are a mnemonic for the field's function. For example, the multibuffer count field (MBF) specifies the number of local buffers to be used for I/O and has the symbolic offset value RAB$B_MBF. The value of RAB$B_MBF is equal to the number of bytes from the beginning of the RAB to the start of the field.

Where applicable, RMS uses control blocks called extended attribute blocks (XABs), together with FABs and RABs, to support the exchange of information with RMS. For example, a Key Definition XAB specifies the characteristics for each key within an indexed file. The symbolic offset values for XAB fields have the common prefix XAB$.

For more information about RMS control blocks, see Chapter 4.

### 1.6.3 Record Management Services

Because RMS performs operations related to files and records, services generally fall into one of two groups:

- Services that support file processing. These services create and access new files, access (or open) previously created files, extend the disk space allocated to files, close files, get file characteristics, and perform other functions related to the file.
- Services that support record processing. These services get (extract), find (locate), put (insert), update (modify), and delete (remove) records and perform other record operations.

For more information about the various services, see Chapter 7 and Chapter 8.

## 1.7 RMS Utilities

The following are RMS file-related utilities:

- The Analyze/RMS_File utility
- The Convert utility
- The Convert/Reclaim utility
- The Create/FDL utility
- The Edit/FDL utility

These utilities let you design, create, populate, maintain, and analyze data files that can use the full set of RMS create-time and run-time options. They help you create efficient files that use a minimum amount of system resources, while decreasing I/O time.

For more information about the record management utilities, see the OpenVMS Record Management Utilities Reference Manual.

### 1.7.1 The Analyze/RMS_File Utility

With the Analyze/RMS_File utility (ANALYZE/RMS_FILE), you can perform five functions:

- Inspect and analyze the internal structure of an RMS file
- Generate a statistical report on the file's structure and use
- Interactively explore the file's internal structure
- Generate an FDL file from an RMS file
- Generate a summary report on the file's structure and use

ANALYZE/RMS_FILE is particularly useful in generating an FDL file from an existing data file that you can then use with the Edit/FDL utility (also called the FDL editor) to optimize your data files. Alternatively, you can provide general tuning for the file without the FDL editor.

To invoke the Analyze/RMS_File utility, use the following DCL command line format:

`ANALYZE/RMS_FILE filespec[,...]`

The filespec parameter lets you select the data file you want to analyze.

For more information about the Analyze/RMS_File utility, refer to Chapter 10 of this manual and the OpenVMS Record Management Utilities Reference Manual.

### 1.7.2 The Convert Utility

The Convert utility (CONVERT) copies records from one or more files to an output file, optionally changing the record format and file organization to that of the output file. 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.

CONVERT is particularly useful in the tuning cycle of a file. After you have analyzed and optimized the file, you can use CONVERT to create a new file having the new, optimized characteristics and to copy the records in the old file to the new file. You can also use CONVERT to reformat an indexed file that has had many record insertions or deletions.

To invoke the Convert utility, use the following DCL command line format:

`CONVERT input-filespec[,...] output-filespec`

Use the input-filespec parameter to specify the file or files you want to convert, and use the output-filespec parameter to specify a destination file for the converted records.

Figure 1-13 shows how CONVERT creates data files and loads them with converted records from an input file.

Figure 1-13 Using CONVERT to Create a Data File

For more information about the Convert utility, refer to Chapter 4 and the OpenVMS Record Management Utilities Reference Manual.

### 1.7.3 The Convert/Reclaim Utility

The Convert/Reclaim utility reclaims empty buckets in Prolog 3 indexed files so that new records can be added to them. A bucket is a storage structure that RMS uses to build and process files.

The Convert/Reclaim utility does an "in-place" reorganization of the file in contrast to the Convert utility, which creates a new file from the old file. For this reason, the Convert/Reclaim utility is more appropriate for large disk files where space is limited. Before using the Convert/Reclaim utility, be sure to back up the file.

For more information about the Convert/Reclaim utility, see Chapter 4 of this manual and the OpenVMS Record Management Utilities Reference Manual.

Previous | Next | Contents | Index

| privacy and legal statement |
4506PRO_003.HTML