|
HP OpenVMS Systems Documentation |
|
OpenVMS Record Management Services Reference Manual
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. 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. 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. 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. 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. 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:
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. 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. 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. 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. 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. 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. 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. No lock (query locking); requests that RMS take out a lock to probe for status and immediately release the lock without holding it for synchronization. If the lock is not granted (exclusive lock held) and the read-regardless (RAB$V_RRL) option is not set, the record access fails with an RMS$_RLK status. Otherwise, the record is returned with one of the following success or alternate success statuses:
When only the RAB$V_NLK option is specified, record access can be denied. When both the RAB$V_NLK and RAB$V_RRL options are specified, an application can guarantee the return of any record with a success or alternate success status. If you do not require a lock and do not need one of the alternate success statuses returned to indicate whether the record would have been blocked, then consider using the RAB$V_NQL record stream (RAB$W_ROP_2) option or the FAB$V_NQL file (FAB$B_SHR) option to avoid the locking overhead. 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. 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. 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. Read regardless of lock; read the record even if another stream has locked the record (see discussion for RAB$V_NLK option). 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:
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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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.
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.
This section describes the options available for the RAB$W_ROP_2 field. 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:
This option is applicable to record processing for all three file applications (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. 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 this record stream. You can set the option for each record operation for a $get or $find. This option is implemented on both VAX and Alpha platforms.
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 this record stream. You can set the option
for each record operation for a $get or $find. This option is
implemented on both VAX and Alpha platforms.
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:
|