Document revision date: 19 July 1999 | |
Previous | Contents | Index |
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:
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 |
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:
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.
|
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.
|
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.
|
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.
|
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.
|
Default extension
quantity |
Specifies the number of blocks to be allocated to a file when more
space is needed.
|
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.
|
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.
|
Locate mode 1 |
Allows the use of locate mode, not move mode, when reading records. See
Section 7.3.
|
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.
|
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.
|
Read-ahead 1 |
Alternates buffer use between two buffers when reading sequential
files. See Chapter 2.
|
Retrieval window
size |
Specifies the number of entries in memory for retrieval windows, which
corresponds to the number of extents for a file.
|
Sequential access
only |
Indicates that a sequential file may only be accessed sequentially.
|
Write-behind 1 |
Alternates buffer use between two buffers when writing to sequential
files. See Chapter 2.
|
Previous | Next | Contents | Index |
privacy and legal statement | ||
4506PRO_024.HTML |