Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

The reverse-search option includes a performance caching optimization to improve performance when retrieving successive previous records. To take advantage of this feature, specify full key sizes (RAB$B_KSZ) and select the RAB$V_NXT search option.

Miscellaneous Options

RAB$V_CDK

During RMS $GET operations, the CDK option allows applications to look ahead for indexed file records with keys that duplicate the current key of reference. If the RAB$V_CDK bit is set, and a record with a duplicate key is detected during a successful $GET operation, RMS returns an alternate success status, RMS$_OK_DUP. Note that this does not guarantee access to the record with the duplicate key. For example, if the record is in a shared file, another accessor may delete the record before your application can access it.

RAB$V_TMO

Timeout; in addition to its use for terminals and preventing delays due to record locks (described later), the RAB$V_TMO option serves a special purpose for mailbox devices. If specified in combination with a timeout value of 0 (RAB$B_TMO), Get and Put services to mailbox devices use the IO$M_NOW modifier. Doing so causes the operation to complete immediately, instead of synchronizing with another cooperating writer or reader of the mailbox.

This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE and is not supported for DECnet for OpenVMS operations.

See the OpenVMS I/O User's Reference Manual for a further discussion of mailboxes.

Performance Options

RAB$V_ASY

Asynchronous; indicates that this I/O operation is to be performed asynchronously. When you specify RAB$V_ASY, you pass the address of the RAB as an argument to the AST routine. RMS returns control to your program as soon as an I/O operation is initiated, even though that operation might not yet be completed. This option is normally used with the Wait service to synchronize with operation completion.

The RAB$V_ASY option corresponds to the FDL attribute CONNECT ASYNCHRONOUS.

RAB$V_FDL

Fast delete; this option reduces the time required to delete records in indexed files when you are using duplicate alternate keys. The saving in time is achieved by temporarily avoiding the processing needed to eliminate pointers from alternative indexes to the record. However, there is a cost associated with this option. First, the structural linkage from the alternate indexes remains in place but has no utility; therefore, a certain amount of space is wasted. Second, if the program tries to access the deleted record from an alternate index, RMS traverses the linkage, finds the record no longer exists, and then generates a "nonexistent record" error message that the program must process.

You should take the fast delete option only if the immediate saving in time is of greater benefit to you than the associated costs in space and overhead.

This option corresponds to the FDL attribute CONNECT FAST_DELETE.

RAB$V_LOC

Locate mode; under specified conditions, you have the option of specifying locate mode instead of move mode, which is the default method of buffer handling. In locate mode, your program accesses records directly in an I/O buffer, thus eliminating the overhead of moving records between I/O buffers and application program buffers.

The RAB$V_LOC option activates locate mode. RMS supports the locate mode option for the Get service only and ignores requests for the option if one of the following conditions exists:

- Record crosses one or more block boundaries
- The FAB$B_FAC field FAB$V_UPD option is set
- Process-permanent files are accessed indirectly
- Records are compressed (applies to indexed Prolog 3 files only)
- Global buffers
- Multistreaming

In move mode, RMS transfers individual records between I/O buffers and the application's program buffer. When the application program invokes a Get service, RMS reads a block or set of blocks (for sequential files) or a bucket (for relative and indexed files) into an I/O buffer. It then selects the desired record from the I/O buffer and moves it into the program-specified location. Locate mode eliminates the last step by accessing the record directly in the I/O buffer.

This option corresponds to the FDL attribute CONNECT LOCATE_MODE. It is not supported for DECnet for OpenVMS operations, which always use move mode.

RAB$V_RAH

Read-ahead; used with multiple local buffers to indicate read-ahead operations. RMS issues I/O requests as soon as possible when a local buffer is needed. When the first local buffer is filled, the I/O operation takes place for the first local buffer as the second local buffer receives the next record; the second local buffer soon becomes filled and the next record is read into the first local buffer as the I/O operation for the second local buffer occurs. The system does not have to wait for I/O completion, which permits an overlapping of input and computing. Read ahead is ignored for unit record device I/O and is supported only for the nonshared sequential file organization. If the RAB$V_RAH option is specified when the multibuffer count (specified by RAB$B_MBF or by the XAB$_MULTIBUFFER_COUNT XABITM) is 0, two local buffers are allocated to allow multibuffering. If two or more local buffers are specified, multibuffering is allowed regardless of what was specified to the Connect service. Conversely, if a buffer count of 1 is specified, multibuffering is disabled regardless of what was specified to the Connect service.

This option corresponds to the FDL attribute CONNECT READ_AHEAD and it is not supported for DECnet for OpenVMS operations.

RAB$V_SYNCSTS

When you select this option, RMS returns the success status RMS$_SYNCH if the requested service completes its task immediately. The most common reason for not completing a task immediately is that the task involves I/O operations. If the service completes synchronously (that is, it has not returned to caller's execution mode prior to completion), RMS returns RMS$_SYNCH as the completion status in R0, stores the true completion status (success or failure) in RAB$L_STS, and does not deliver an AST.

The status RMS$_SYNCH is returned in R0 only. Refer to the RAB$L_STS field for the actual success status or failure status of the task.

The RAB$V_SYNCSTS option should be used in conjunction with the RAB$V_ASY option.

RAB$V_WBH

Write-behind; used with multiple local buffers. When one local buffer is filled, the next record is written into the next local buffer while the I/O operation takes place for the first local buffer. The system does not have to wait for I/O completion, which allows for an overlapping of computing and output. Write-behind is ignored for unit record devices. This option is implemented only for the nonshared sequential file organization. If the RAB$V_WBH option is specified when the multibuffer count (specified by RAB$B_MBF or by the XAB$_MULTIBUFFER_COUNT XABITM) is 0, two local buffers are allocated to allow multibuffering. If two or more local buffers are specified, multibuffering is allowed regardless of what was specified to the Connect service. Conversely, if you specify a multibuffer count of 1, RMS disables multibuffering regardless of what was specified to the Connect service.

This option corresponds to the FDL attribute CONNECT WRITE_BEHIND and it is not supported for DECnet for OpenVMS operations.

Put Service Options

RAB$V_TPT

Truncate-on-put; specifies that a Put or Write service using sequential record access mode can occur at any point in the file, truncating the file at that point. The end-of-file mark is set to the position immediately following the last byte written.

Truncating a file deletes all records beyond the point of truncation. In a shared environment, the application must ensure proper interpretation of a truncate operation. The process must have specified truncate access by setting the FAB$V_TRN option in the FAB$B_FAC field when the file was opened or created.

This option applies only to sequential files and corresponds to the FDL attribute CONNECT TRUNCATE_ON_PUT.

RAB$V_UIF

Update-if; indicates that if a Put service is invoked for a record that already exists in the file, the operation is converted to an Update. This option is necessary to overwrite (as opposed to update) an existing record in relative and indexed files. Indexed files using this option must not allow duplicates on the primary key. The process must have specified Update access by setting the FAB$V_UPD option in the FAB$B_FAC field when the file was opened or created.

When using this option with shared files and automatic record locking, you should be aware that the Put service, unlike the Update service, briefly releases record locks until it is determined that an Update should take place. At that point, the record is relocked for the Update operation. Note that during the time the Put operation is being converted into an Update operation, it is possible that another record stream could update or delete the record.

This option corresponds to the FDL attribute CONNECT UPDATE_IF.

Record Locking Options

This section describes the record-processing options related to controlling record locking. Except as noted, these options apply to all file organizations and can be selected for each operation.

RAB$V_NLK

Do not lock record; specifies that the record accessed through a Get or Find service is not to be locked. The RAB$V_NLK option takes precedence over the RAB$V_ULK option.

This option corresponds to the FDL attribute CONNECT NOLOCK.

RAB$V_NXR

Nonexistent record processing; specifies that if the record directly accessed through a Get or Find service does not exist (was never inserted into the file or was deleted), the service is to be performed anyway. For a Get service, the previous contents of a deleted record are returned. The processing of a deleted record returns a completion status code of RMS$_OK_DEL, and the processing of a record that never existed returns RMS$_OK_RNF.

This option applies only to relative files and it corresponds to the FDL attribute CONNECT NONEXISTENT_RECORD.

RAB$V_REA

Lock record for read; specifies that the record is to be locked for a read operation for this process, while allowing other accessors to read the record (but not to modify the record). Use this option only when you do not want the file to be modified by any subsequent activities. Use the RAB$V_RLK option to allow possible subsequent modification of the file.

This option corresponds to the FDL attribute CONNECT LOCK_ON_READ.

RAB$V_RLK

Lock record for write; specifies that a user who locks a record for modification is allowing the locked record to be read by other accessors. If both RAB$V_RLK and RAB$V_REA are specified, the RAB$V_REA option is ignored. The RAB$V_NLK option takes precedence over all others.

This option corresponds to the FDL attribute CONNECT LOCK_ON_WRITE.

RAB$V_RRL

Read regardless of lock; read the record even if another stream has locked the record. This option allows the reader some control over access. If a record is locked against all access and this bit is set for either a Find or Get service request, the record is returned without a lock for all three file organizations. The returned status, however, varies, depending on the file organization:

- The service returns RMS$_SUC for sequential files.
- The service returns alternate success status, RMS$_OK_RRL, for relative and indexed files.

For relative and indexed file applications, the RMS$_OK_RRL status has the added value of indicating when the record is returned without a lock.

This option corresponds to the FDL attribute CONNECT READ_REGARDLESS.

RAB$V_TMO

Timeout; specifies that if the RAB$V_WAT option was specified, the RAB$B_TMO field contains the maximum time value, in seconds, to be allowed for a record input wait caused by a locked record. If the timeout period expires and the record is still locked, RMS aborts the record operation with the RMS$_TMO completion status. Note that the maximum time allowed for a timeout is 255 seconds. Other functions of the RAB$V_TMO option are listed under Miscellaneous Options.

This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE and it is not supported for DECnet for OpenVMS operations.

RAB$V_ULK

Manual unlocking; prohibits RMS from automatically unlocking records. Instead, once locked (through a Get, Find, or Put service), a record must be specifically unlocked by a Free or Release service. The RAB$V_NLK option takes precedence over the RAB$V_ULK option.

This option corresponds to the FDL attribute CONNECT MANUAL_UNLOCKING.

RAB$V_WAT

Wait; if the record is currently locked by another stream, wait until it is available. This option can be used with the RAB$V_TMO option to limit waiting periods to a specified time interval.

This option corresponds to the FDL attribute CONNECT WAIT_FOR_RECORD.

Terminal Device Options

This section describes the record-processing options related to terminal devices. These options map directly into equivalent modifiers to the QIO function code. For a further discussion of their effects, see the OpenVMS I/O User's Reference Manual. These options can be selected for each operation.

RAB$V_CCO

Cancel CTRL/O; guarantees that terminal output is not discarded if the operator presses Ctrl/O.

This option corresponds to the FDL attribute CONNECT TT_CANCEL_CONTROL_O and it is not supported for DECnet for OpenVMS operations.

RAB$V_CVT

Convert; changes characters to uppercase on a read from a terminal.

This option corresponds to the FDL attribute CONNECT TT_UPCASE_INPUT and it is not supported for DECnet for OpenVMS operations.

RAB$V_ETO

Extended terminal operation; indicates presence of a terminal XAB (XABTRM) to describe terminal input using extended terminal characteristics. Note that if this option is specified, all other RAB$L_ROP options specific to terminal devices are ignored (including the RAB$V_TMO option).

This option is not supported for DECnet for OpenVMS operations.

RAB$V_PMT

Prompt option; indicates that the contents of the prompt buffer are to be used as a prompt for reading data from a terminal (see RAB$L_PBF field).

This option corresponds to the FDL attribute CONNECT TT_PROMPT and it is not supported for DECnet for OpenVMS operations.

RAB$V_PTA

Purge type-ahead; eliminates any information that might be in the type-ahead buffer on a read from a terminal.

This option corresponds to the FDL attribute CONNECT TT_PURGE_TYPE_AHEAD and it is not supported for DECnet for OpenVMS operations.

RAB$V_RNE

Read no echo; indicates that input data is not echoed (displayed) on the terminal as it is entered on the keyboard.

This option corresponds to the FDL attribute CONNECT TT_READ_NOECHO and it is not supported for DECnet for OpenVMS operations.

RAB$V_RNF

Read no filter; indicates that CTRL/U, CTRL/R, and DELETE are not to be considered control commands on terminal input but are to be passed to the application program.

This option corresponds to the FDL attribute CONNECT TT_READ_NOFILTER and it is not supported for DECnet for OpenVMS operations.

RAB$V_TMO

Timeout; for terminal operations, indicates that the content of the RAB$B_TMO field is to be used to determine the number of seconds allowed between characters received during terminal input. If the timeout period expires, RMS returns an error status (see RAB$B_TMO). Other functions of the RAB$V_TMO option are listed under Miscellaneous Options and Record Locking Options.

This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE and is not supported for DECnet for OpenVMS operations.

## 7.20 RAB$W_ROP_2 Field

The RAB$W_ROP_2 field is the symbolic offset for an extension to the RAB's record-processing options (RAB$L_ROP) field. This field specifies which of the extended record options are to be implemented for an application.

The ROP_2 field is a 16-bit field in which each extended record-processing option has a corresponding bit assignment to let you specify multiple options (multiple bits can be set) when applicable.

Table 7-5 lists the options alphabetically and their associated symbols. You may specify all these symbols, which facilitate common code, in applications that execute on either platform. The functionality for the RAB$V_NQL option is not implemented on the VAX platform.

The ROP_2 field was implemented on the Alpha platform with OpenVMS V7.2--1H1, on the VAX platform with OpenVMS V7.3. The ROP_2 field and its options are not supported for DECnet for OpenVMS operations and have no corresponding FDL attributes.

Table 7-5 ROP_2 Record Processing Options
Option | Symbolic Offset
--- | ---
No Query Locking | RAB$V_NQL
No Deadlock Wait | RAB$V_NODLCKWT
No Deadlock Blocking | RAB$V_NODLCKBLK

Options

This section describes the options available for the RAB$W_ROP_2 field.

RAB$V_NQL

No Query Locking. Applications wishing to read records without any consideration for record locking (see the description of the no query record locking option in the Guide to OpenVMS File Applications) may use this option for read ($get/$find) operations, and avoid the processing associated with record locking calls to the lock manager. This option is applicable to record processing for both local and global buffers and to all three file organizations (sequential, relative, and indexed).

This option takes precedence over all other record locking options (see the RAB$L_ROP field in this section). You can set this option for each record operation for a $get or $find. You should set it only if the current read ($get or $find) operation is not followed by either an $update or a $delete.

This option is implemented on the Alpha platform and is ignored on the VAX platform.

RAB$V_NODLCKWT

No Deadlock Wait. RMS uses the distributed lock manager for record locking. The lock manager provides deadlock detection. The lock manager allows an application to control deadlock detection with regard to particular locks using LCK$V_NODLCKWT (see the OpenVMS System Services Reference Manual: A--GETUAI). By selecting this option, you request RMS to specify LCK$V_NODLCKWT in its record locking requests for the application. You can set the option for each record operation for a $get or $find. This option is implemented on both VAX and Alpha platforms.

RAB$V_NODLCKBLK

No Deadlock Blocking. RMS uses the distributed lock manager for record locking. The lock manager provides deadlock detection. The lock manager allows an application to control deadlock detection with regard to particular locks using LCK$V_NODLCKBLK (see the OpenVMS System Services Reference Manual: A--GETUAI). By selecting this option, you request RMS to specify LCK$V_NOLCKBLK in its record locking requests for the application. You can set the option for each record operation for a $get or $find. This option is implemented on both VAX and Alpha platforms.

## 7.21 RAB$W_RSZ Field

The record size (RSZ) field contains the size, in bytes, of the record to which the record buffer address (RAB$L_RBF) field points. For a Write service, the range is 1 through 65,535. For a Put or Update service, the range is 0 to the maximum value shown in Table 4-4. The record size field specifies the size of a record that a Put or Update service can write, or the number of bytes that a Write (block I/O) service can write. The Update service requires the record size field only if the file contains variable-length records or VFC records.

On input from a file, RMS sets this field to indicate the length, in bytes, of the record that a Get service transfers or that a Read service (block I/O) reads.

Three notes apply to this field:

- After a Get service, RMS places the record size in the RAB$W_RSZ field. On a Read service, RMS sets the RAB$W_RSZ field to the number of bytes actually transferred.
- For variable with fixed-length control records, RMS does not include the size of the fixed control area in the RAB$W_RSZ field.
- For block I/O operations, some devices require that an even number of bytes be transferred. No user action is required because RMS automatically rounds the number of transfers up to an even number.

## 7.22 RAB$L_STS Field

RMS sets the completion status code (STS) field together with the success or failure status codes for a record operation before returning control to your program. For an asynchronous operation that has been initiated but not yet completed, this field is 0. When the operation is complete, the field is updated with the completion status. See Chapter 2 for additional details about signaling RMS status codes. Potential error codes for specific operations are listed with their descriptions in Part 3.

## 7.23 RAB$L_STV Field

The completion status value (STV) field communicates additional completion information to your program, on the basis of the type of operation and the contents of the completion status code field. For additional information on the RAB$L_STS and RAB$L_STV fields, see Part 1.

The RAB$L_STV field can be accessed using alternate symbolic offsets; RAB$W_STV0 is the location of the first word and RAB$W_STV2 is the location of the second word within RAB$L_STV.

Previous | Next | Contents | Index

| privacy and legal statement |
4523PRO_012.HTML