Document revision date: 19 July 1999

This chapter describes the way you specify run-time options and summarizes the run-time options available to you when opening files, connecting record streams, processing records, and closing files. The run-time options that apply to record processing and to opening and closing a file can usually be preset by file-open and record stream connection values. Some options can be selected after you open a file and connect a record stream.

Note that run-time options discussed in previous sections are only summarized in this chapter. Most of the material in this chapter relates to options not previously described in this document.

9.1 Specifying Run-Time Options

This section describes the way you use the Edit/FDL utility to specify run-time options that are available to your program through the FDL$PARSE and FDL$RELEASE routines. It also describes the use of language statements and OpenVMS RMS (hereafter referred to as RMS) to specify control block values.

You select RMS options by setting appropriate values in RMS control blocks within the data portion of your program. In many cases, you can select these values by using keywords available to you in the language OPEN statement for your application or by taking suitable default values. The values may be selected using keywords in your record and file description statements or they may be selected directly within the OPEN statement.

If your application is written in a language that does not provide keywords for the various features, you can usually select the options using the File Definition Language (FDL).

Predefined FDL attributes can be supplied to your program at run time using the FDL$PARSE routine. This routine also returns the address of the record access block (RAB) to let your program subsequently change RAB values. Some RAB options are not available in FDL and can be set only by directly accessing RAB fields and subfields at run time. To invoke options after record stream connection, your program must have direct access to RMS control block fields using the address of the RAB and symbolic offsets into it.

9.1.1 Using the Edit/FDL Utility

You can use the Edit/FDL utility to specify run-time attributes, such as adding a CONNECT attribute that is used to set a control block value when the FDL$PARSE and FDL$RELEASE routines are called by your program. These attributes preset the values available for opening a file and connecting a record stream.

The following original FDL file was created with the Edit/FDL utility:

IDENT "19-JUL-1994 14:57:37 OpenVMS FDL Editor" SYSTEM SOURCE VMS FILE ORGANIZATION indexed RECORD CARRIAGE_CONTROL carriage_return FORMAT variable SIZE 0 AREA 0 ALLOCATION 8283 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 2070 AREA 1 ALLOCATION 18 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 18 KEY 0 CHANGES no DATA_AREA 0 DATA_FILL 100 DATA_KEY_COMPRESSION yes DATA_RECORD_COMPRESSION yes DUPLICATES no INDEX_AREA 1 INDEX_COMPRESSION yes INDEX_FILL 100 LEVEL1_INDEX_AREA 1 PROLOG 3 SEG0_LENGTH 9 SEG0_POSITION 0 TYPE string

Because the Edit/FDL utility does not include run-time attributes, you must add them to the FDL definition. You can specify run-time attributes by specifying the ACCESS, CONNECT and SHARING attributes. For example, if you want to add the CONNECT secondary attribute LOCK_ON_WRITE, you use the EDIT/FDL ADD command. This is illustrated in Example 9-1.

Example 9-1 Specifying Run-Time Attributes

OpenVMS FDL Editor Add to insert one or more lines into the FDL definition Delete to remove one or more lines from the FDL definition Exit to leave the FDL Editor after creating the FDL file Help to obtain information about the FDL Editor (1) Invoke to initiate a script of related questions Modify to change existing line(s) in the FDL definition Quit to abort the FDL Editor with no FDL file creation Set to specify FDL Editor characteristics View to display the current FDL Definition (2) Main Editor Function (Keyword)[Help] : ADD Legal Primary Attributes ACCESS attributes set the run-time access mode of the file AREA x attributes define the characteristics of file area x CONNECT attributes set various VMS RMS run-time options DATE attributes set the data parameters of the file FILE attributes affect the entire VMS RMS data file (3) JOURNAL attributes set the journaling parameters of the file KEY y attributes define the characteristics of key y RECORD attributes set the non-key aspects of each record SHARING attributes set the run-time sharing mode of the file SYSTEM attributes document operating system-specific items TITLE is the header line for the FDL file (4) Enter Desired Primary (Keyword)[FILE] : CONNECT Legal CONNECT Secondary Attributes ASYNCHRONOUS yes/no NOLOCK yes/no BLOCK_IO yes/no NONEXISTENT_RECORD yes/no BUCKET_CODE number READ_AHEAD yes/no CONTEXT number READ_REGARDLESS yes/no END_OF_FILE yes/no TIMEOUT_ENABLE yes/no FAST_DELETE yes/no TIMEOUT_PERIOD number FILL_BUCKETS yes/no TRUNCATE_ON_PUT yes/no KEY_GREATER_EQUAL yes/no TT_CANCEL_CONTROL_O yes/no (5) KEY_GREATER_THAN yes/no TT_PROMPT yes/no KEY_LIMIT yes/no TT_PURGE_TYPE_AHEAD yes/no KEY_OF_REFERENCE number TT_READ_NOECHO yes/no LOCATE_MODE yes/no TT_READ_NOFILTER yes/no LOCK_ON_READ yes/no TT_UPCASE_INPUT yes/no LOCK_ON_WRITE yes/no UPDATE_IF yes/no MANUAL_UNLOCKING yes/no WAIT_FOR_RECORD yes/no MULTIBLOCK_COUNT number WRITE_BEHIND yes/no MULTIBUFFER_COUNT number (6) Enter CONNECT Attribute (Keyword)[-] : LOCK_ON_WRITE (7) CONNECT LOCK_ON_WRITE (8) Enter value for this Secondary (Yes/No)[-] : YES Resulting Primary Section (9) CONNECT LOCK_ON_WRITE yes (10) Press RETURN to continue (^Z for Main Menu)

The following list describes the callouts used in Example 9-1:

1. This menu is the Main Editor Function menu. It displays the Edit/FDL utility commands you can use.
2. The ADD command displays the Legal Primary Attributes menu.
3. The Legal Primary Attributes menu shows the primary attributes. You can either add a new primary attribute or add a secondary attribute to an existing primary attribute. Initially, the FILE primary attribute is the default.
4. The selection of the CONNECT primary attribute displays the Legal CONNECT Secondary Attributes. You could similarly select the ACCESS, FILE, or SHARING options instead of the CONNECT primary attribute to display the Legal Secondary Attributes for the selected primary attribute.
5. This menu shows all the CONNECT secondary attributes you can add to your FDL file.
6. Select the proper CONNECT secondary attribute (in this case, LOCK_ON_WRITE).
7. The Edit/FDL utility verifies that you have selected the secondary attribute.
8. Enter the value that you want the secondary attribute to have (for instance, yes).
9. The Edit/FDL utility verifies the value for the secondary attribute you have chosen.
10. Return to the main menu. If you choose to add another secondary attribute, you will notice that CONNECT is now the default.

The FDL file containing the CONNECT primary attribute with the WRITE_BEHIND secondary attribute is shown in the following example:

IDENT "19-JUL-1994 14:57:37 OpenVMS FDL Editor" SYSTEM SOURCE VMS FILE ORGANIZATION indexed RECORD CARRIAGE_CONTROL carriage_return FORMAT variable SIZE 0 CONNECT WRITE_BEHIND yes AREA 0 ALLOCATION 8283 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 2070 AREA 1 ALLOCATION 18 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 18 KEY 0 CHANGES no DATA_AREA 0 DATA_FILL 100 DATA_KEY_COMPRESSION yes DATA_RECORD_COMPRESSION yes DUPLICATES no INDEX_AREA 1 INDEX_COMPRESSION yes INDEX_FILL 100 LEVEL1_INDEX_AREA 1 PROLOG 3 SEG0_LENGTH 9 SEG0_POSITION 0 TYPE string

9.1.2 Using Language Statements and RMS

Language statements such as OPEN may contain keywords, clauses, or other modifiers that correspond to the run-time attributes that are appropriate for opening files, connecting record streams, processing records, and closing files. Some languages use system-defined procedures in place of keywords and clauses. Some languages allow you to call a user-supplied routine (USEROPEN or USERACTION) to set control block values before opening the file.

For example, a user routine could be coded in VAX MACRO to take advantage of control block store macros. (For an example of a VAX BASIC USEROPEN routine, see Example 5-2.) Consult the corresponding language documentation for additional information.

With VAX MACRO, RMS control block macros allow you to establish control block values at assembly time and at run time using the same control block. (The assembly-time macros are placed in a data section of the program; the run-time macros are placed in a code section of the program.) Using VAX MACRO, control blocks are allocated within the program space at assembly time, and it may not be necessary to use the run-time macros because the program can move values to the control block fields using the instruction set. Other languages, however, may not allocate the control blocks within program storage.

If your program has access to the starting location of the control block (a record access block, for instance), the VAX MACRO assembly-time control block macro or the corresponding symbol definition (DEF) macro provides your program with certain symbolic offsets (symbols) that can be used to locate and identify the various fields in the control block. Some languages provide a means of making these symbols available to your program.

For additional information about using the control block macros and control block fields, refer to the OpenVMS Record Management Services Reference Manual.

9.2 Options Related to Opening and Closing Files

Before your program can access the records in a file, it must open the file and connect a record stream. When it finishes processing records and no longer requires access to that file, your program should close the file.

The options available for opening files, connecting record streams, and closing files include file access and file sharing options, file specification options, performance options, record access options, and options for:

• Adding records
• Acting on the file after it is closed (file disposition)
• Using indexed files
• Using magnetic tapes
• Performing nonstandard record processing
• Maintaining data reliability

As described in Chapter 7, the program must declare the desired file-access and file-sharing values before opening an existing file or creating a new file and must specify record-locking and buffering strategies when the file is opened. These options are summarized in the next table:

Option	Description
File access	Specifies the record operations that the current process performs: reading records, locating records, deleting records, adding new records, updating records, accessing blocks, and truncating the file. (For additional information, see Section 7.1.) You specify the file access values using the FDL ACCESS primary attribute or the FAB$B_FAC field.
File sharing	Specifies the types of record operations that the current process allows other file accessors to perform: reading records, locating records, deleting records, adding new records, and updating records. You can also use file sharing to enable the current process to use multiple record streams (or ensure a read-only global buffer cache), operate on the file without record interlocking, or disallow all other accessors from accessing the file. You specify file sharing values using the SHARING primary attribute or the FAB$B_SHR field.
Record locking	Allows you to provide record locking for a shared file under user control. By default, RMS automatically locks records, depending on the file access and file sharing values specified. (For additional information, see Section 7.2.) You specify the record locking values using the CONNECT primary attribute or using the record-processing options (RAB$L_ROP) field 1.

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

	privacy and legal statement
4506PRO_024.HTML