Document revision date: 15 July 2002

As described in Chapter 4 and Chapter 6, the program should specify the specification for the file being opened (or created) and can also specify default file specifications. The file specifications are summarized in the following table:

File Specification	Description
Primary	Specifies the file specification to be used to locate the desired file(s). If any components of a file specification are omitted, RMS applies defaults but you should specify the primary file specification. FDL: FILE NAME RMS: FAB$L_FNA and FAB$B_FNS
Default	Specifies the default file specification to be used to fill any missing components not provided by the primary file specification. After applying these defaults, if any components are still missing, additional defaults are applied. FDL: FILE DEFAULT_NAME RMS: FAB$L_DNA and FAB$B_DNS
Related	Specifies a related file specification that is used to provide additional defaults when a related file is used. If the device or directory components are missing, RMS provides default values from the process-default device (SYS$DISK) and the current process-default directory. FDL: None RMS: FAB$L_NAM and NAM$L_RLF

9.2.3 File Performance Options

A number of run-time options that open files and connect record streams can collectively improve application performance. Such options include the buffering options discussed in Chapter 7.

Two run-time performance options not discussed previously are particularly important when adding records to a file: extension size and window size.

9.2.3.1 Extension Size

If you intend to add records to the file, specify a reasonable default extension size to reduce the number of times the file is extended.

Use the Edit/FDL utility to calculate the correct extension size. The Edit/FDL utility uses your responses to assign an optimum value for the FDL attribute FILE EXTENSION. With multiple area files, the Edit/FDL utility assigns optimum values to the AREA EXTENSION attributes.

If you do not specify an extension size, RMS computes the size; however, this size may not be optimum.

If you decide to create an FDL file for defining an indexed file without using EDIT/FDL, you can approximate the value of the EXTENSION attributes. You do this by multiplying the number of records per bucket by the number of records that you intend to add to the file during a given period of time.

To see the current default extension size, use the DCL command SHOW RMS_DEFAULT. To set the default buffer count, use the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY=n, where n is the number of blocks per extension. The corresponding field is FAB$W_DEQ.

9.2.3.2 Window Size

If the file is extended repeatedly, the extensions may be scattered on the disk. Each extension is called an extent---a pointer to each extent resides in the file header. For retrieval purposes, the pointers are gathered together in a structure called a window. The default window size is 7 pointers, but you can establish the window size to contain as many as 127 pointers. You can also set the window size to --1, which makes a window that is just large enough to map the entire file.

When you access an extent whose pointer is not in the current window, the system has to read the file header and fetch the appropriate window. This is called a window turn, and it requires an I/O operation.

Window size is a run-time option. Many high-level languages include a clause that sets window size when a file is opened.

You can set the window size (FAB$B_RTV field) at run time with a VAX MACRO subroutine or with the FDL attribute FILE WINDOW_SIZE.

You can increase the default window size for a specific volume by using the DCL commands MOUNT and INITIALIZE. However, using additional window pointers increases system overhead. The window size is charged to your buffered I/O byte count quota, and indiscriminate use of large windows may result in exceeding the buffered I/O byte count quota or may exhaust the system's nonpaged dynamic memory.

You can use the Backup utility (BACKUP) to avoid having too many extents. When you restore a file, BACKUP tries to write the file in one section of the disk. Although BACKUP does not necessarily create a contiguous copy of the file, it does reduce the number of extents. If you are regularly backing up the file, the number of extents is probably reasonable. For more information about BACKUP, see the OpenVMS System Manager's Manual.

Where disk space is available, you can reduce the number of extents by creating a new, contiguous version of the file using either the Convert utility (CONVERT) or the DCL command COPY/CONTIGUOUS. If neither of these conditions apply, a larger window size is the only option to use. For file maintenance information, see Chapter 10.

9.2.3.3 Summary of Performance Options

The following table summarizes the run-time open and connect options that may affect performance:

Option	Description
Asynchronous record processing 1	Specifies that record I/O for this record stream is done asynchronously. See Section 8.7. FDL: CONNECT ASYNCHRONOUS RMS: RAB$L_ROP RAB$V_ASY
Deferred-write 1	Allows records to be accumulated in a buffer and written only when the buffer is needed or when the file is closed. For use by all except nonshared sequential files. See Chapter 3. FDL: FILE DEFERRED_WRITE RMS: FAB$L_FOP FAB$V_DFW
Default extension quantity	Specifies the number of blocks to be allocated to a file when more space is needed. FDL: FILE EXTENSION RMS: FAB$W_DEQ
Fast delete 1	Postpones certain internal operations associated with deleting indexed file records until the record is accessed again. This allows records to be deleted rapidly but may affect the performance of subsequent accessors reading the file. FDL: CONNECT FAST_DELETE RMS: RAB$L_ROP RAB$V_FDL
Global buffer count	Specifies whether global buffers are used and the number to be used if the record stream is the first to connect to the file. See Section 7.3. FDL: CONNECT GLOBAL_BUFFER_COUNT RMS: FAB$W_GBC
Locate mode 1	Allows the use of locate mode, not move mode, when reading records. See Section 7.3. FDL: CONNECT LOCATE_MODE RMS: RAB$L_ROP RAB$V_LOC
Multiblock count	Allows multiple blocks to be transferred into memory during a single I/O operation (for sequential files only). See Chapter 3 and Section 7.3. FDL: CONNECT MULTIBLOCK_COUNT RMS: RAB$B_MBC
Number of buffers	Enables the use of multiple buffers for the buffer cache when used with indexed and relative files; when used with sequential files, enables the use of multiple buffers for the read-ahead and write-behind options. See Section 7.3. FDL: CONNECT MULTIBUFFER_COUNT RMS: RAB$B_MBF
Read-ahead 1	Alternates buffer use between two buffers when reading sequential files. See Chapter 2. FDL: CONNECT READ_AHEAD RMS: RAB$L_ROP RAB$V_RAH
Retrieval window size	Specifies the number of entries in memory for retrieval windows, which corresponds to the number of extents for a file. FDL: FILE WINDOW_SIZE RMS: FAB$B_RTV
Sequential access only	Indicates that a sequential file may only be accessed sequentially. FDL: FILE SEQUENTIAL_ONLY RMS: FAB$L_FOP FAB$V_SQO
Write-behind 1	Alternates buffer use between two buffers when writing to sequential files. See Chapter 2. FDL: CONNECT WRITE_BEHIND RMS: RAB$L_ROP RAB$V_WBH

You can specify the record access for a record stream as sequential, random by key or record number, or random by RFA. (See Section 8.1.) The selected record access can be changed for each record processing operation. These options can be set using the RAB$B_RAC field, values RAB$C_SEQ, RAB$C_KEY, and RAB$C_RFA.

9.2.5 Options for Adding Records

When adding records to a file, consider the open and connection options in the following table:

Option	Description
Default extension quantity 1	See Section 9.2.3.
Deferred-write 1	See Section 9.2.3.
End-of-file	After the record stream is connected, the record context is positioned to the end of the file. FDL: CONNECT END_OF_FILE RMS: RAB$L_ROP RAB$V_EOF
Retrieval window size 1	See Section 9.2.3.
Revision data	The revision date and time and the revision number can be specified to be a value other than the actual revision date and time and revision number when the file is closed. These options must be set while the file is open and thus cannot be set using FDL. FDL: Does not apply RMS: Revision Date and Time XAB
Truncate on Put 1	When using sequential record access for sequential files only, the record to be written is the last record in the file, and RMS truncates the file just beyond that record. FDL: CONNECT TRUNCATE_ON_PUT RMS: RAB$L_ROP RAB$V_TPT
Update-if 1	If you set this option and your program tries to replace an existing record while adding records randomly to a file, RMS modifies the existing record instead of replacing it. When using this option for indexed files, note that the file must not allow duplicates for the primary key. Use this option carefully with a shared file (see Section 8.1). FDL: CONNECT UPDATE_IF RMS: RAB$L_ROP RAB$V_UIF
Write-behind 1	See Section 9.2.3.

The following table lists the run-time file open options that apply to data reliability:

Option	Description
Read-check	Specifies that transfers from volumes are to be checked by a read-compare operation, which effectively doubles the amount of disk I/O performed. This option is not available for all devices (see the OpenVMS Record Management Services Reference Manual.) FDL: FILE READ_CHECK RMS: FAB$L_FOP FAB$V_RCK
Write-check	Specifies that transfers to volumes are to be checked by a read-compare operation, which effectively doubles the amount of disk I/O performed. This option is not available for all devices (see the OpenVMS Record Management Services Reference Manual). FDL: FILE WRITE_CHECK RMS: FAB$L_FOP FAB$V_WCK

9.2.7 Options for File Disposition

The run-time file open options that apply to file disposition are listed in the following table. These options can only be selected while the file is open.

Option	Description
Delete on close	Deletes the file when it is closed. FDL: CONNECT DELETE_ON_CLOSE RMS: FAB$L_FOP FAB$V_DLT
Submit command file	Submits a sequential file as a batch command procedure to SYS$BATCH when you close the file. FDL: FILE SUBMIT_ON_CLOSE RMS: FAB$L_FOP FAB$V_SCF
Spool on close	Prints a sequential file on SYS$PRINT when you close the file. FDL: FILE PRINT_ON_CLOSE RMS: FAB$L_FOP FAB$V_SPL

9.2.8 Options for Indexed Files

The following table lists the run-time options that apply to indexed file processing. For more information about processing indexed files, refer to Section 8.4.3.

Option	Description
Fast delete 1	Postpones certain internal operations associated with deleting indexed file records until the record is accessed again. This allows records to be deleted rapidly, but it may degrade the performance of processes that read the file later. FDL: CONNECT FAST_DELETE RMS: RAB$L_ROP RAB$V_FDL
Key equal or next 1	Returns the first record with a key value equal to the key you specified when locating or reading records. If RMS does not find a record with an equal key value, it returns the record with the next higher key value when ascending sort order is specified. When descending sort order is specified, RMS returns the next record with the next lower key value. FDL: CONNECT KEY_GREATER_EQUAL RMS: RAB$L_ROP RAB$V_EQNXT
Next key 1	Returns the record with the next higher key value when you specify ascending sort order when locating or reading records. When you specify descending sort order, RMS returns the next record with the next lower key value. If you do not specify either this option or the equal-or-next-key option, RMS tries for a key match. FDL: CONNECT KEY_GREATER_THAN RMS: RAB$L_ROP RAB$V_NXT
Key of reference	Permits you to specify which key to use for the current record stream when you process an indexed file with multiple keys. FDL: CONNECT KEY_OF_REFERENCE RMS: RAB$B_KRF
Key buffer 1	Specifies key buffer that must contain the selected record's key when you are locating or reading records randomly. FDL: None RMS: RAB$L_KBF
Key size 1	Specifies that only a portion of the key be used to locate the selected record when you are locating or reading records with a string data-type key. FDL: None RMS: RAB$B_KSZ
Limit key 1	Returns an alternate success status if the record key exceeds the specified key when you are locating or reading records sequentially. FDL: CONNECT KEY_LIMIT RMS RAB$L_ROP RAB$V_LIM
Load buckets 1	Uses the fill factor specified when the file was created. When you are adding records to an index file. By default, RMS fills buckets completely. FDL: CONNECT FILL_BUCKETS RMS: RAB$L_ROP RAB$V_LOA

The run-time file open and close options that apply to magnetic tape processing are listed in the following table:

Option	Description
Not end-of-file	Adds a record to a location other than at the end of the file. FDL: FILE MT_NOT_EOF RMS: FAB$L_FOP FAB$V_NEF
Current position	Positions the tape to the location immediately following the most recently closed file when you select this option when creating a file. FDL: FILE MT_CURRENT_POSITION RMS: FAB$L_FOP FAB$V_POS
Rewind on Open	Directs that the tape volume be rewound before it opens or creates the file. The rewind-on-open option overrides the current-position option. FDL: FILE MT_OPEN_REWIND RMS: FAB$L_FOP FAB$V_RWO
Rewind on Close	Directs that the tape volume be rewound before it closes the file. FDL: FILE MT_CLOSE_REWIND RMS: FAB$L_FOP FAB$V_RWC

9.2.10 Options for Nonstandard File Processing

The following table lists the run-time file open options that apply to nonstandard file processing:

Option	Description
Non-file-structured	Use this option when you want to process data from volumes created on systems other than Compaq systems. FDL: FILE NON_FILE_STRUCTURED RMS: FAB$L_FOP FAB$V_NFS
User file open	Use this option if you want to use RMS only to open the file and you intend to access the contents of the file using Queue I/O Request system service calls. The system returns the I/O channel number in the FAB$L_STV field. FDL: FILE USER_FILE_OPEN RMS: FAB$L_FOP FAB$V_UFO

	privacy and legal statement
4506PRO_026.HTML