HP OpenVMS Systems Documentation
OpenVMS Record Management Services Reference Manual
7.11 RAB$B_MBC Field
The multiblock count (MBC) field applies only to sequential disk file operations. This field specifies the number of blocks, in the range of 0 through 127, to be allocated to each process (local) I/O buffer and, correspondingly, the number of blocks of data to be transferred in each I/O unit. If you do not specify this field, or if you specify the value 0, RMS uses the process default for the multiblock count. If the process default is 0, RMS uses the system default, and if the system default is 0, RMS assigns each local buffer one block.
The use of the RAB$B_MBC field optimizes data throughput for sequential operations, and does not affect the structure of the file. It reduces the number of disk accesses for record operations, resulting in faster program execution. However, the extra buffering increases memory requirements.
Note that the RAB$B_MBC field is not used with block I/O. With multiblocks, the number of blocks in an I/O unit is fixed by the multiblock count, whereas in block I/O operations the number of blocks being transferred is specified by the program.
This field corresponds to the FDL attribute CONNECT MULTIBLOCK_COUNT
and it is not supported for DECnet for OpenVMS operations.
The multibuffer count (MBF) field indicates the number (0 to 255) of process (local) I/O buffers you want RMS to allocate when you invoke the Connect service for a record stream.
If this field is not specified or is set to 0, and if the XAB$_MULTIBUFFER_COUNT XABITM is not implemented, RMS uses the process default for the particular file organization and device type. If the process default is also 0, the system default for the particular file organization and device type applies. If the system default is 0, RMS allocates the record stream one local buffer. However, if you specify either the read-ahead option or the write-behind option, RMS allocates at least two buffers.
RMS allocates at least one local buffer for sequential and relative files and at least two buffers for indexed files, unless the file is to be processed with block I/O operations only. Multiple local buffers can be used efficiently to overlap I/O time with compute time, particularly in read-ahead or write-behind processing (see RAB$L_ROP for information on these options), and to increase use of the local buffers (as compared to disk I/O) when performing random processing.
Note that the RAB$B_MBF field is not used when block I/O access is specified with the Open, Create, or Connect services because no local buffers are required.
This field corresponds to the FDL attribute CONNECT MULTIBUFFER_COUNT
and it is not supported for DECnet for OpenVMS operations.
The prompt buffer address (PBF) field points to a character string to be used as a prompt for terminal input. Note that the RAB$L_PBF field has the same offset as the RAB$B_KBF (key buffer address) field but, because the fields are used in mutually exclusive operations, no conflict is presented.
This field contains the symbolic address of the buffer containing the prompt character string. If you select the RAB$V_PMT option of the RAB$L_ROP field when you invoke a Get service, RMS outputs this character string to the terminal before the Get service begins its task.
To perform any carriage control on the terminal, you must insert the appropriate carriage control characters into this character string.
This field is not supported for DECnet for OpenVMS operations; it is
The prompt buffer size (PSZ) field indicates the size of the prompt character string to be used as a terminal prompt. This field contains the size, in bytes, in the range of 0 to 255.
Note that the RAB$B_PSZ field has the same offset as the RAB$B_KSZ (key buffer size) field but no conflict is presented because the fields are used in mutually exclusive operations.
This field is not supported for DECnet for OpenVMS operations; it is
The record access mode (RAC) field indicates the method of retrieving or inserting records in the file; that is, whether records are read (or written) sequentially, directly, or by record file address. Only one access method can be specified for any single record operation, but you can change the record access mode between record operations.
The RAB$B_RAC field is a keyword value field in which each record access mode has a symbolic offset. Options are identified using mnemonics. Each access mode in the RAB$B_RAC field has its own symbolic constant. For example, the SEQ (sequential record) access mode has the symbolic constant RAB$C_SEQ.
7.16 RAB$L_RBF Field
When a program invokes a service that writes records to a file, the output record buffer address (RBF) field contains the symbolic address of the buffer that holds the record to be written. The record size field (RAB$W_RSZ) specifies the size of the record buffer.
When you invoke the Get or Read service, RMS sets this field to the
address of the record just read from the file; you do not need to
initialize this field. The record's address can be based on whether the
program specifies locate mode (RAB$V_LOC). For locate mode, the address
can be within an RMS buffer; otherwise, the address is in the user
buffer (RAB$L_UBF) provided by the program.
The record file address (RFA) field comprises three words that define the physical disk address (not symbolic address) of the current record.
After the successful execution of a record or block I/O operation, RMS sets the RAB$W_RFA field to the address of the record acted on by the operation. This address provides an unambiguous means of directly locating this same record at some later time but is meaningful for disk files only.
You can store the contents of the RAB$W_RFA field for future use. When you want to retrieve the record again, merely restore the saved contents of the field, set the record access mode to random by RFA, and invoke a Get or Find service.
7.18 RAB$L_RHB Field
The fixed-length record header buffer (RHB) field contains the symbolic address of the record header buffer, which RMS uses only when processing VFC records.
For a Get service, RMS strips the fixed control area portion of the record and places it in the buffer whose address is specified in this field. For Put or Update services, RMS writes the contents of the specified buffer to the file as the fixed control area portion of the record.
If this field is not specified, RMS assumes the absence of a record header buffer. When no record header buffer exists, the fixed control area is discarded for a Get service, zeroed for a Put service, and left unchanged for an Update service.
The size of the fixed control area is defined in the FAB, using the
FAB$B_FSZ field. You must ensure that the buffer size described in the
RAB$L_RHB field is equal to the value specified by the FAB$B_FSZ field.
RAB$L_ROP is the symbolic offset for the RAB's record-processing options (ROP) field. This field specifies which of the various optional record operations are to be implemented for the program.
The ROP is a 32-bit field in which each record-processing option has a corresponding bit assignment to let you specify multiple options (multiple bits can be set), when applicable. Each option has a unique symbolic offset and a unique mask value but you need only specify the appropriate 3-letter mnemonic when coding a function. For example, the end-of-file option is assigned symbolic offset RAB$V_EOF, but to specify the option, you use the following MACRO statement:
The record-processing option bits are never affected by record management services.
Table 7-2 lists the options alphabetically by category.
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.
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.
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.
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.
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 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 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.
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.