Document revision date: 30 March 2001

## Guide to OpenVMS File Applications

Previous | Contents | Index

## Chapter 9
Run-Time Options

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

### 9.2.1 File Access and Sharing Options

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.

1Indicates an option that can be specified for each record-processing operation. For more information, see Section 9.3.

### 9.2.2 File Specifications

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

1Indicates an option that can be specified for each record-processing operation. For more information, see Section 9.3.

Previous | Next | Contents | Index

| privacy and legal statement |
4506PRO_025.HTML