Document revision date: 19 July 1999

The user context (CTX) field contains any user-selected value, up to four bytes long. This field is devoted exclusively to your use. RMS makes no use of the contents of this field; therefore, you can set any value you want in this field. For example, you could use this field to communicate with a completion routine in your program.

This field corresponds to the FDL attribute CONNECT CONTEXT.

7.6 RAB$L_FAB Field

The file access block address (FAB) field contains the symbolic address of the FAB for the file. Before you invoke the Connect service, you must set this field to indicate the address of the FAB associated with the open file.

7.7 RAB$W_ISI Field

The internal stream identifier (ISI) field associates the RAB with a corresponding FAB. RMS sets this field after the execution of a Connect service. A Disconnect service clears this field. This field should not be altered.

7.8 RAB$L_KBF Field

The key buffer address (KBF) field contains the symbolic address of the buffer containing the key value for random access. Note that the RAB$B_KBF field has the same offset as the RAB$L_PBF (prompt buffer address) field, but no conflict is presented because the fields are used in mutually exclusive operations.

When the RAB$B_RAC (record access mode) field specifies random access by key value, this field provides the address of a buffer that contains the key of the desired record. The key is the relative record number in files that are organized for relative access or in files organized for sequential access containing fixed-length records. In indexed files, the key value in RAB$L_KBF is used with the index specified in the key of reference field (RAB$B_KRF) to randomly access the desired record. Note that although a collating key affects the stored order for records, the collating value does not govern record lookups. For example, a collating sequence may assign the same ordering for the keys "dog" and "DOG". However, both keys do not have the same access (lookup) value. Therefore, when doing lookups, a program should specify either the specific key value or a range of values that includes the uppercase and lowercase combinations of the key. See the Guide to OpenVMS File Applications for more information about accessing indexed records.

Before you invoke the Get or Find service for doing random access in an indexed file, you place the address of the location containing the specified key value in the RAB$L_KBF field. The size of this key value must be specified in the RAB$B_KSZ field. During execution of the Get or Find service, RMS uses the specified key value for searching an index (which you specify using the RAB$B_KRF field) to locate the desired record. The type of match, that is, exact, generic, approximate, or approximate generic, is determined by examining the RAB$B_KSZ field in combination with selected search bits in the RAB$L_ROP field.

7.9 RAB$B_KRF Field

The key of reference (KRF) field specifies the key or index (primary, first alternate, and so on) to which the operation applies. The RAB$B_KRF field is applicable to indexed files only.

This field contains a numeric value representing the key path to records in a file. The value 0, the default, indicates the primary key. The values 1 through 254 indicate alternate keys.

When your program invokes a Get or Find service in random access mode, the key of reference specifies the index to search for a match on the key value that is described by the RAB$L_KBF and RAB$B_KSZ fields. When your program invokes a Connect or Rewind service, the key of reference identifies the index in the file of the next record in the stream. The next record is important when records are retrieved sequentially.

Note that although a collating key affects the stored order for records, the collating value does not govern record lookups. For example, a collating sequence may assign the same ordering for the keys "dog" and "DOG". However, both keys do not have the same access (lookup) value. Therefore, when doing lookups, a program should specify either the specific key value or a range of values that includes the uppercase and lowercase combinations of the key. See the Guide to OpenVMS File Applications for more information about accessing indexed records. This field corresponds to the FDL attribute CONNECT KEY_OF_REFERENCE.

7.10 RAB$B_KSZ Field

The key size (KSZ) field contains a numeric value equal to the size, in bytes, of the record key pointed to by the RAB$L_KBF field.

Note that the RAB$B_KSZ field has the same offset as the RAB$B_PSZ (prompt buffer size) field but no conflict is presented because the fields are used in mutually exclusive operations.

For indexed files, the size of the key depends on the key data type:

• For string data-type keys, a value from 1 through the size of the key field can be used.

  Note The string data-type keys include STRING, DSTRING, COLLATED, and DCOLLATED keys.

  If the specified size is less than the size of the key field, then only the leftmost characters of each key are used for comparison.
• For numeric key data types, a value of 0 causes RMS to use the key data type defined at file creation to determine the key size. A nonzero value is checked against the defined size, and an error is returned if they are not equal.

Note that for DECnet for OpenVMS operations, the RAB$B_KSZ field must be explicitly specified as a nonzero value because the key data type information might not be available to RMS at the local node.

The size of the relative record number of a record in a relative file or a sequential file with fixed-length records is a longword, positive, integer value; therefore, the key size is 4. For relative record numbers, the default value of 0 causes a key size of 4 to be used. For DECnet for OpenVMS operations, however, the RAB$B_KSZ field must be explicitly specified as 4 for relative files.

With indexed files, the size of key values in bytes of an indexed file can be from 1 to 255 bytes.

A program can access indexed file records directly in one of four ways:

• By an exact match
• By an approximate match
• By a generic match
• By a combination of approximate and generic matches

• To specify an exact match, do the following:
  • Set a value in the RAB$B_KSZ field equal to the number of bytes in the key.
  • Reset the appropriate search bit, RAB$V_EQNXT or RAB$V_NXT.
  • Specify the search direction by doing the following:
    • For a forward search (toward the end of the file), be sure that the RAB$V_REV bit is not set.
    • For a reverse search (toward the beginning of the file), set the RAB$V_REV bit.

  Note Compaq recommends the use of the mask designator (M) in specifying the equal or next and the next search options because it is more universally applicable, especially for high-level languages. Using mask designators, you can specify multiple options in a single instruction. See the description of the reverse search option in RAB$V_REV.

• To specify an approximate match, do the following:
  • Set a value in the RAB$B_KSZ field equal to the number of bytes in the key.
  • Specify the type of match by doing the following:
    • If you want to match on a record having either an equal key value or the next key value (greater for ascending sort order, less for descending sort order) set the RAB$V_EQNXT bit.

      Note Sort order is established in the data type (XAB$B_DTP) field of the associated XABKEY when the file is created.

    • If you want to match on a record having the next value and to ignore equal key values, set the RAB$V_NXT bit.
  • Specify the search direction by doing the following:
    • For a forward search (toward the end of the file), be sure that the RAB$V_REV bit is not set.
    • For a reverse search (toward the beginning of the file), set the RAB$V_REV bit.
• To specify a generic match, do the following:
  • Set a value in the RAB$B_KSZ field equal to the number of leading bytes in the key you want to match on.
  • Reset the appropriate search bit, RAB$V_EQNXT or RAB$V_NXT
  • Specify the search direction by doing the following:
    • For a forward search (toward the end of the file), be sure that the RAB$V_REV bit is not set.
    • For a reverse search (toward the beginning of the file), set the RAB$V_REV bit.
• To specify an approximate generic match, do the following:
  • Set a value in the RAB$B_KSZ field equal to the number of leading bytes in the key you want to match on.
  • Specify the type of match by doing the following:
    • If you want to match on a record having a generic key value equal to the specified generic key value or the next generic key value, set the RAB$V_EQNXT bit.
    • If you want to match on a record having the next generic key value but to ignore equal generic key values, set the RAB$V_NXT bit.
  • Specify the search direction by doing the following:
    • For a forward search (toward the end of the file), be sure that the RAB$V_REV bit is not set.
    • For a reverse search (toward the beginning of the file), set the RAB$V_REV bit.

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.

Table 7-2 Record Processing Options

Option	Symbolic Offset
Connect Service Options
Block I/O	RAB$V_BIO
End of file	RAB$V_EOF
Read ahead	RAB$V_RAH
Write behind	RAB$V_WBH
Indexed File Options
Key greater than or equal	RAB$V_EQNXT (or RAB$V_KGE)
Limit	RAB$V_LIM
Load	RAB$V_LOA
Key greater than	RAB$V_NXT (or RAB$V_KGT)
Reverse search	RAB$V_REV
Miscellaneous Options
Check for duplicate key	RAB$V_CDK
Timeout	RAB$V_TMO
Performance Options
Asynchronous	RAB$V_ASY
Fast delete	RAB$V_FDL
Locate mode	RAB$V_LOC
Read ahead	RAB$V_RAH
Synchronous status	RAB$V_SYNCSTS
Write behind	RAB$V_WBH
Put Service Options
Truncate on put	RAB$V_TPT
Update-if	RAB$V_UIF
Record Locking Options
Do not lock	RAB$V_NLK
Nonexistent record	RAB$V_NXR
Lock for read	RAB$V_REA
Lock for write	RAB$V_RLK
Ignore read lock	RAB$V_RRL
Timeout	RAB$V_TMO
Manual unlock	RAB$V_ULK
Wait to lock	RAB$V_WAT
Terminal Device Options
Cancel CTRL/O	RAB$V_CCO
Convert	RAB$V_CVT
Extended operation	RAB$V_ETO
Prompt	RAB$V_PMT
Purge type-ahead	RAB$V_PTA
Read, no echo	RAB$V_RNE
Read, no filter	RAB$V_RNF
Timeout	RAB$V_TMO

	privacy and legal statement
4523PRO_010.HTML