![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
In the following text, each of the options is described under its symbolic offset. For example, the asynchronous option is described under RAB$V_ASY.
Block I/O; specifies that only block I/O operations are to occur, when mixed record I/O and block I/O operations are allowed. This option is meaningful only if the FAB$B_FAC FAB$V_BRO option was specified when the file was opened (by a Create or Open service). When the RAB$V_BIO option is set for the Connect service, only block I/O operations are allowed for this record stream. When the RAB$V_BIO option is clear for the Connect service, only record I/O operations are allowed when accessing a relative or indexed file and mixed (block I/O and record I/O) operations are allowed for sequential files. This option corresponds to the FDL attribute CONNECT BLOCK_IO.
End-of-file; indicates that RMS is to position the record stream to the end of the file for the connect record operation only. An application program sets the EOF bit when it requires append access to a file. Append access provides a convenient way of positioning the data entry pointer to point to the end of file in order to append records. Shared append access is supported only for sequential files. Unshared append access is supported for sequential, relative, and indexed file organizations.
This option corresponds to the FDL attribute CONNECT END_OF_FILE.
Read ahead and write behind; see explanation under Performance Options.
Note that search operations have limited application with relative files. See the Guide to OpenVMS File Applications for details.
Indexed file options can be enabled or disabled during any record operation.
RMS supports four search key options, two forward search and two reverse search, using combinations of the three search bits shown in the following table.
| Search Option | Definition |
|---|---|
| RAB$V_EQNXT | Return the next record having a key value equal to, or greater than, the current key of reference, according to the specified sort order. |
| RAB$V_NXT | Return the next record having a key value greater than the current key of reference, according to the specified sort order. |
| RAB$V_REV | When used with either of the first two options, reverses the search direction, that is, searches toward the beginning of the file. |
When you select the RAB$V_EQNXT option and ascending sort order, RMS returns the next record having a key value equal to or greater than the value specified by the RAB$L_KBF and RAB$B_KSZ fields. If you specify descending sort order, RMS returns the next record that contains a key value equal to or less than the value specified by the RAB$L_KBF and RAB$B_KSZ fields. In either case, the file is searched in the forward direction (toward the end of the file) unless the reverse search key option is selected.
Sort order is established in the data type field (symbolic offset XAB$B_DTP) of the associated XABKEY when the file is created. |
If the program specifies a RAB$V_EQNXT search and a record with a key value identical to the search key is found, RMS returns the record regardless of sort order.
If the program specifies a reverse search by setting the RAB$V_EQNXT bit and the RAB$V_REV bit, RMS reverses the search direction, searching toward the beginning of the file.
Table 7-3 provides the search results for both ascending and descending sort order in a file that has records containing one of three index keys ("B", "K", and "Q"), and three keys of reference ("A", "K", and "Z"). For example, assume the current key of reference is "Z", the sort order is ascending, and the program is looking for the next record having a key that is greater than the key of reference. In this case, RMS returns RNF (record not found) because there are no records that have a key greater than "Z" in the file.
| Current Key of Reference | ||||
|---|---|---|---|---|
| Resultant Search Option |
Sort Order | "A" | "K" | "Z" |
| NXT | Ascending | "B" | "Q" | RNF |
| Descending | RNF | "B" | "Q" | |
| EQNXT | Ascending | "B" | "K" | RNF |
| Descending | RNF | "K" | "Q" | |
| REV + NXT | Ascending | RNF | "B" | "Q" |
| Descending | "B" | "Q" | RNF | |
| REV + EQNXT | Ascending | RNF | "K" | "Q" |
| Descending | "B" | "K" | RNF | |
If neither a RAB$V_EQNXT search nor a RAB$V_NXT search is specified, an exact key match is required unless a generic key match is specified. (See the description of the RAB$B_KSZ bit.)
This option corresponds to the FDL CONNECT attribute KEY_GREATER_EQUAL.
This bit is logically synonymous with the RAB$V_EQNXT option and is described under RAB$V_EQNXT.
This bit is logically synonymous with the RAB$V_NXT option and is described under RAB$V_NXT.
This option is supported for indexed files only. It permits you to use RMS as a limit sensor when accessing a file sequentially. When the RAB$V_LIM bit is set, the key value defined by the RAB$L_KBF and RAB$B_KSZ fields (limit key value) is compared to the key value in each record as it is accessed. When a record is accessed that has a key value different from the limit key value, RMS returns the RMS$_OK_LIM success status code.
This option corresponds to the FDL attribute CONNECT KEY_LIMIT.
This option is supported for indexed files only. It specifies that RMS is to load buckets according to the fill size established at file creation time. The bucket fill size is established in the XAB$W_DFL and XAB$W_IFL fields of the key definition XAB. If the LOA option is not specified, RMS ignores the established bucket fill size; that is, buckets are completely filled.
This option corresponds to the FDL attribute CONNECT FILL_BUCKETS.
If you select the RAB$V_NXT option and ascending sort order, RMS returns the next record that has a key value greater than the value specified by the RAB$L_KBF and RAB$B_KSZ fields. If descending sort order is specified, RMS returns the next record having a key value less than the value specified by the RAB$L_KBF and RAB$B_KSZ fields. In either case, the file is searched in the forward direction (toward the end of the file) unless the reverse search key option is selected.
If you specify neither RAB$V_NXT nor RAB$V_EQNXT, an exact key match is required.
Sort order is established in the data type XAB$B_DTP field of the associated XABKEY when the file is created. |
The RAB$V_REV option reverses the direction of the search when used with either of the forward search key options in random keyed access only. Sequential access still proceeds forward only, according to the sort order.
In all cases, you specify search key options symbolically, using the mask bits in the RAB$L_ROP field of the RAB structure. Table 7-4 identifies the results of all combinations of the REV, EQNXT, and NXT bits.
| Search Result | REV | EQNXT | NXT |
|---|---|---|---|
| Equal (default) | 0 | 0 | 0 |
| Greater-than or equal | 0 | 1 | 0 |
| Greater-than (next) | 0 | 0 | 1 |
| RMS$_ROP error | 0 | 1 | 1 |
| RMS$_ROP error | 1 | 0 | 0 |
| Less-than or equal | 1 | 1 | 0 |
| Less than (previous) | 1 | 0 | 1 |
| RMS$_ROP error | 1 | 1 | 1 |
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.
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.
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. 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).
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4523PRO_011.HTML | ||