HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

These fields can be used to replace the FAB$L_FNA and FAB$L_FNS fields in the FAB. Using these NAML fields allows you to specify a default name string longer than the 255 bytes allowed by FAB$B_FNS.

RMS uses the NAML$L_LONG_FILENAME and NAML$L_LONG_FILENAME_SIZE fields in place of the FAB$L_FNA and FAB$L_FNS fields if FAB$L_FNA contains -1 and FAB$B_FNS contains 0.

The following illustrates this procedure.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_NAME points to the start of the file name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_NAME_SIZE, RMS fills this field with the length, in bytes, of the file name pointed to by NAML$L_LONG_NAME, not including the type field nor the period separating the name from the type.

6.18 NAML$L_LONG_NODE and NAML$L_LONG_NODE_SIZE Fields

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAM$L_LONG_NODE points to the start of the node name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_NODE_SIZE, RMS fills this field with the length, in bytes, of the node name pointed to by NAML$L_LONG_NODE, including the :: delimiter. Note that if this is not a DECnet file specification, NAML$L_LONG_NODE_SIZE will be 0.

6.19 NAML$L_LONG_RESULT Field

The resultant string area address field contains the symbolic address of a buffer in your program to receive the resultant file specification string. The NAML$L_LONG_RESULT_ALLOC field must also be specified to obtain a resultant file specification string.

This string is the fully specified name of the file that results from the resolution of all system defaults, including version numbers and wildcard character substitution in the expanded file name string. You must specify this field for wildcard processing.

The NAML$L_LONG_RESULT field's corresponding short field, NAML$L_RSA, can be specified as well, but a separate buffer should be allocated for it.

6.20 NAML$L_LONG_RESULT_ALLOC Field

The resultant string area allocation size field defines the size of the user-allocated buffer whose address is contained in the NAML$L_LONG_RESULT field.

This field contains a numeric value representing the size, in bytes, of the user buffer that will receive the resultant file specification string, in the range of 0 through 4095.

The symbolic value NAML$C_MAXRSS defines the maximum possible length of a resultant file specification string.

6.21 NAML$L_LONG_RESULT_SIZE Field

The resultant string size contains the length, in bytes, of the resultant file specification string returned in the buffer whose address is in the NAML$L_LONG_RESULT field.

6.22 NAML$L_LONG_TYPE and NAML$L_LONG_TYPE_SIZE Fields

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_TYPE points to the start of the file type, including the dot separating it from the name, within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_TYPE_SIZE, RMS fills this field with the length, in bytes, of the file type pointed to by NAML$L_LONG_TYPE.

6.23 NAML$L_LONG_VER and NAML$L_LONG_VER_SIZE Fields

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_VER points to the start of the file version, including the semicolon separating it from the type, within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_VER_SIZE, RMS fills this field with the length, in bytes, of the file version pointed to by NAML$L_LONG_VER.

6.24 NAML$L_OUTPUT_FLAGS Field

The output flags field contains additional status bits returned by RMS.

The NAML$L_OUTPUT_FLAGS field contains the following flags.

The user context field contains any user-selected value, up to 8 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 file I/O completion routine in your program that the file access block (FAB) is passed to, since the FAB$L_NAM provides a link to this name block.

The record access block (RAB) defines run-time options for a record stream and for individual operations within a predefined record stream context. After you connect the file to a record stream and associate the record stream with a FAB, you use the RAB fields to specify the next record you want to access and to identify appropriate record characteristics.

Table 7-1 gives the symbolic offset, the size, the FDL equivalent, and a brief description of each RAB field.

Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations using files at remote OpenVMS systems. For information about the support of RMS options for remote file access to other systems, see the DECnet for OpenVMS Networking Manual.

The format and arguments of the $RAB macro and the $RAB_STORE macro are described in Appendix A.

7.2 RAB$B_BID Field

The block identifier (BID) field is a static field that identifies the block as a RAB. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic offset value RAB$C_BID (this is done by the $RAB macro).

7.3 RAB$L_BKT Field

The bucket code (BKT) field is used with records in a relative file and when performing block I/O.

This field contains a relative record number or a numeric value representing the virtual block number to be accessed.

For relative files, the relative record number of the record acted upon (or which produced an error) is returned to the RAB$L_BKT field only after the completion of a sequential operation. That is, RMS returns the relative record number when you set the record access mode for sequential access (RAB$B_RAC is RAB$C_SEQ) on the execution of a Get, Put, or Find service.

Before performing block I/O on disk devices, this field must contain the virtual block number (VBN) of the first block you want to read or write. For all other devices, this field is not used. If you specify a VBN of 0, RMS begins the block transfer at the block pointed to by the next block pointer (NBP). (The NBP is an internal pointer maintained by RMS; it is described in Section B.3.12.)

This field is also input to the Space service to specify the number of blocks to be spaced forward or backward.

This field corresponds to the FDL attribute CONNECT BUCKET_CODE.

7.4 RAB$B_BLN Field

The block length (BLN) field is a static field that defines the length of the RAB, in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value RAB$C_BLN (this is done by the $RAB macro).

7.5 RAB$L_CTX Field

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.