HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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.

For shared sequential file operations, the first accessor of the file uses the RAB$B_MBC field to establish the global buffer size for all subsequent accessors.

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.

7.12 RAB$B_MBF Field

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.

7.13 RAB$L_PBF Field

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 ignored.

7.14 RAB$B_PSZ Field

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 ignored.

7.15 RAB$B_RAC Field

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.

The RAB$B_RAC field is not applicable to block I/O operations and there is no corresponding FDL attribute for this field.

Options

RAB$C_SEQ

Indicates sequential record access mode (the default); it can be specified with any type of file organization.

Records read from (or written to) sequential files are accessed in chronological order. That is, older records are accessed before newer records.

Records read sequentially from indexed files are accessed by the key of reference according to the key's sort order. Where records have duplicate keys, older records are read before newer records, regardless of the key's sort order.

For example, assume an ascending key indexed file with four 2-byte records (A1, B1, B2, C1), where the key is the first byte of each record. When processed sequentially, the records are encountered in the following order:

A1 B1 B2 C1

Here, records B1 and B2 have the duplicate key B, but record B1 was inserted chronologically before record B2 and, therefore, is encountered before B2 when the program is reading records sequentially.

If this file is reorganized as a descending-key indexed file, the records are encountered in the following order:

C1 B1 B2 A1

Note that the chronological order of insertion for the two records with duplicate keys is maintained without regard to sort order.

When records are written sequentially to indexed files, RMS verifies that the key value of each successive record is ordered correctly with respect to the key value in the previously written record. For example, with a descending key of reference, RMS ensures that the key value of the third record written is less than the value of the second record.

RAB$C_KEY

Indicates random access by key. For relative files and sequential files on disk with fixed-length records, random access is by relative record number. Indexed files are accessed directly by specifying the appropriate value for the key of reference.

RAB$C_RFA

Indicates random access by record file address; used for all disk file organizations.

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.

7.17 RAB$W_RFA Field

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.

The following rules apply to RFA access:

• There are two additional names for portions of this field: RAB$L_RFA0 is the offset of the first of three words; RAB$W_RFA4 is the offset of the last word.
• RFA values remain valid for a record in a sequential file as long as the record is within the space defined by the logical file; that is, until the file is truncated to a point before the record.
• RFA values remain valid for a record in a relative file for the life of the file; that is, until the file is reorganized, using the Convert utility, or deleted.
• With an indexed file, RFA values remain valid until the file is reorganized, using the Convert utility, or deleted. Note that the Convert/Reclaim utility partially reorganizes a file while maintaining RFA values.

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.

7.19 RAB$L_ROP 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:

ROP=EOF

The record-processing option bits are never affected by record management services.

This section describes the seven types of record-processing options alphabetically by functional category:

• Connect service options
• Indexed file options
• Miscellaneous options
• Performance options
• Put service options
• Record locking options
• Terminal device options

Table 7-2 lists the options alphabetically by category.

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.

Connect Service Options

RAB$V_BIO

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.

RAB$V_EOF

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.

RAB$V_RAH, RAB$V_WBH

Read ahead and write behind; see explanation under Performance Options.

Indexed File 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.

RAB$V_EQNXT

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.

RAB$V_KGE

This bit is logically synonymous with the RAB$V_EQNXT option and is described under RAB$V_EQNXT.

RAB$V_KGT

This bit is logically synonymous with the RAB$V_NXT option and is described under RAB$V_NXT.

RAB$V_LIM

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.

RAB$V_LOA

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.

RAB$V_NXT

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.

RAB$V_REV

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.

• RAB$V_REV + RAB$V_EQNXT---This combination of search key options searches toward the beginning of the file and returns records having either the same key value as the current key of reference, or a key value less than the current key of reference, according to the specified sort order.
• RAB$V_REV + RAB$V_NXT---This combination of search key options searches toward the beginning of the file and returns records having a key value less than the current key of reference, according to the specified 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.