HP OpenVMS Systems Documentation
Content starts here

Guide to OpenVMS File Applications
Previous Contents Index

9.2.4 Record Access Options

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.
1Indicates an option that can be specified for each record-processing operation. For more information, see Section 9.3.

9.2.6 Options for Data Reliability

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
1Indicates an option that can be specified for each record-processing operation. For more information, see Section 9.3.

9.2.9 Options for Magnetic Tape Processing

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

9.3 Summary of Record Operation Options

This section briefly describes the options associated with the record retrieval services (Find and Get), the record insertion service (Put), the record modification service (Update), and the record deletion service (Delete).

9.3.1 Record Retrieval Options

The Find and Get services (or the equivalent language statements) can be used to locate and retrieve a record.

The options associated with the Find and Get services are summarized in the following table. These options can be set for each Find or Get service if the program can access the appropriate RAB control block fields. The RAB control block fields are preset by connect-time values or defaults and as a result of previous service calls.

Option Description
Asynchronous record
processing 		Specifies that record I/O for this record stream is done asynchronously.
  • FDL: CONNECT ASYNCHRONOUS
  • RMS: RAB$L_ROP RAB$V_ASY
Do not lock record Directs RMS not to lock the record for ensuing operations.
  • FDL: CONNECT NOLOCK
  • RMS: RAB$L_ROP RAB$V_NLK
Key buffer Specifies key buffer that must contain the desired record's key when you are locating or reading records randomly.
  • FDL: None
  • RMS: RAB$L_KBF
Key equal or next Returns the first record with a key value equal to the specified key when you are 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 you specify ascending sort order. When you specify descending sort order, RMS returns the record with the next lower key value.
  • FDL: CONNECT KEY_GREATER_EQUAL
  • RMS: RAB$L_ROP RAB$V_EQNXT
Next key Returns the record with the next higher key value when you specify ascending sort order when you are locating or reading records. When you specify descending sort order, RMS returns the record with the next lower key value.
  • FDL: CONNECT KEY_GREATER_THAN
  • RMS: RAB$L_ROP RAB$V_NXT
Key of reference Specifies which key is used for current record stream for indexed files with multiple keys.
  • FDL: CONNECT KEY_OF_REFERENCE
  • RMS: RAB$B_KRF
Key size Specifies that all or part of the key be used when you are using a string key to locate or read records.
  • FDL: None
  • RMS: RAB$B_KSZ
Limit key Directs RMS, when locating or reading records sequentially, to return an alternate success status if the record key exceeds the specified key.
  • FDL: CONNECT KEY_LIMIT
  • RMS: RAB$L_ROP RAB$V_LIM
Locate mode Specifies the locate mode, instead of the move mode. Applies to the Get service only.
  • FDL: CONNECT LOCATE_MODE
  • RMS: RAB$L_ROP RAB$V_LOC
Lock nonexistent
record 		Indicates that RMS is to lock the record position at the location of the following record operation, regardless of whether a record exists at that location. Applies only to relative files.
  • FDL: CONNECT NONEXISTENT_RECORD
  • RMS: RAB$L_ROP RAB$V_NXR
Lock for read Locks record for reading and allows other readers (but no writers).
  • FDL: CONNECT LOCK_ON_READ
  • RMS: RAB$L_ROP RAB$V_REA
Lock for write Locks record for writing and allows other readers (but no writers).
  • FDL: CONNECT LOCK_ON_WRITE
  • RMS: RAB$L_ROP RAB$V_RLK
Manual locking Allows you to control record locking and unlocking manually.
  • FDL: CONNECT MANUAL_LOCKING
  • RMS: RAB$L_ROP RAB$V_ULK
Read ahead Improves performance at the expense of additional memory for I/O buffers. For sequential access to sequential files only.
  • FDL: CONNECT READ_AHEAD
  • RMS: RAB$L_ROP RAB$V_RAH
Read regardless Reads the specified record regardless of whether it is locked by another user.
  • FDL: CONNECT READ_REGARDLESS
  • RMS: RAB$L_ROP RAB$V_RRL
Record access Specifies the way records are accessed: sequentially, randomly by key (indexed files), by record number (relative files), or randomly by RFA.
  • FDL: None
  • RMS: RAB$B_RAC values,
    RAB$C_SEQ, RAB$C_KEY,
    RAB$C_RFA
RFA Specifies the address of the desired record when records are accessed randomly by RFA (RAB$B_RAC contains RAB$C_RFA). This value is also returned by Find and Get services regardless of the type record access used.
  • FDL: None
  • RMS: RAB$W_RFA
Record header buffer Contains the symbolic address of the record header buffer that contains the fixed portion of a VFC record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_RHB
Timeout period Specifies a timeout period after which an error is returned when you choose the wait-if-locked option. The number of seconds is specified by the CONNECT TIMEOUT_PERIOD or RAB$B_TMO field to eliminate a potential deadlock.
  • FDL: CONNECT TIMEOUT_PERIOD
  • RMS: RAB$L_ROP RAB$V_TMO and
    RAB$B_TMO
User buffer address Specifies the address of the user buffer that receives the record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_UBF
User buffer size Specifies the maximum length of the user record buffer. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_USZ
Wait if locked Specifies that if the record is locked, RMS must wait until it is available; also allows use of the wait-timeout-period option.
  • FDL: CONNECT WAIT_FOR_RECORD
  • RMS: RAB$L_ROP RAB$V_WAT

9.3.2 Put Service Options

The Put service (or equivalent language statement) adds a record to the file.

The options associated with the Put service are summarized in the following table. These options can be set for each Put service if the program can access the appropriate RAB control block fields. The RAB control block fields are preset by connect-time values or defaults and as a result of previous service calls.

Option Description
Asynchronous record
processing 		Specifies that record I/O for this record stream is done asynchronously.
  • FDL: CONNECT ASYNCHRONOUS
  • RMS: RAB$L_ROP RAB$V_ASY
Key buffer Specifies key buffer that must contain the desired record's relative record number when adding records randomly to a relative file.
  • FDL: None
  • RMS: RAB$L_KBF
Key size Specifies a field that must have a value of 4 (the default value provided by RMS) when adding records to a relative file using random record access.
  • FDL: None
  • RMS: RAB$B_KSZ
Load buckets Fills the buckets to the level specified when the file is created. The default is that buckets fill completely before a bucket split occurs.
  • FDL: CONNECT FILL_BUCKETS
  • RMS: RAB$L_ROP RAB$V_LOA
Read allowed Allows the locked record being written to be read.
  • FDL: CONNECT LOCK_ON_WRITE
  • RMS: RAB$L_ROP RAB$V_RLK
Record access Specifies the way records are added, sequentially according to ascending key value or relative record number, randomly by key (indexed files) or by record number (relative files), or randomly by RFA.
  • FDL: None
  • RMS: RAB$B_RAC values,
    RAB$C_SEQ, RAB$C_KEY,
    RAB$C_RFA
Record header buffer Contains the symbolic address of the record header buffer that contains the fixed portion of a VFC record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_RHB
Record buffer
address 		Specifies the address of the record buffer that contains the record to be written.
  • FDL: None
  • RMS: RAB$L_RBF
Record buffer size Specifies the size of the record contained in the record buffer to be written.
  • FDL: None
  • RMS: RAB$L_RBZ
Timeout period Specifies a timeout period after which an error is returned when you choose the wait-if-locked option. The number of seconds is specified by the CONNECT TIMEOUT_PERIOD or the RAB$B_TMO field to eliminate a potential deadlock.
  • FDL: CONNECT TIMEOUT_PERIOD
  • RMS: RAB$L_ROP RAB$V_TMO and
    RAB$B_TMO
Truncate on Put Specifies that the file is truncated at the record being added. Requires sequential record access and only applies to sequential files.
  • FDL: CONNECT TRUNCATE_ON_PUT
  • RMS: RAB$L_ROP RAB$V_TPT
Update-if Turns the Put service into an update operation if the record already exists in the file. Care must be taken when using this option with shared files and automatic record locking (see Section 8.1). When using this option with indexed files, note that the file must not allow duplicates for the primary key. This option can only be used when random record access has been specified.
  • FDL: CONNECT UPDATE_IF
  • RMS: RAB$L_ROP RAB$V_UIF
Write-behind Improves performance at the expense of additional memory for I/O buffers. Requires sequential record access and only applies to sequential files.
  • FDL: CONNECT WRITE_BEHIND
  • RMS: RAB$L_ROP RAB$V_WBH

Previous Next Contents Index