[an error occurred while processing this directive]
Software  >  OpenVMS Systems > Documentation > 731final > 4523

HP OpenVMS Systems Documentation
Content starts here

OpenVMS Record Management Services Reference Manual

Previous Contents Index

7.22 RAB$L_STS Field

RMS sets the completion status code (STS) field together with the success or failure status codes for a record operation before returning control to your program. For an asynchronous operation that has been initiated but not yet completed, this field is 0. When the operation is complete, the field is updated with the completion status. See Chapter 2 for additional details about signaling RMS status codes. Potential error codes for specific operations are listed with their descriptions in Part 3.

7.23 RAB$L_STV Field

The completion status value (STV) field communicates additional completion information to your program, on the basis of the type of operation and the contents of the completion status code field. For additional information on the RAB$L_STS and RAB$L_STV fields, see Part 1.

The RAB$L_STV field can be accessed using alternate symbolic offsets; RAB$W_STV0 is the location of the first word and RAB$W_STV2 is the location of the second word within RAB$L_STV.

7.24 RAB$B_TMO Field

The timeout (TMO) field indicates the maximum number of seconds, in the range 0 to 255, that RMS should wait for an operation to conclude. If the operation does not conclude within the specified timeout period, RMS returns an error status code.

To use this field, you must also specify the RAB$V_TMO record-processing option.

For a Get service using a terminal device, this value specifies the number of seconds to wait between the characters being typed. If you specify 0 along with RAB$V_TMO, the current contents of the type-ahead buffer are returned.

When you use a wait-on-record lock (RAB$V_WAT) with a Get, Find, or Put service, this value specifies the maximum number of seconds for RMS to wait for the record to become available.

Note that if the RAB$B_TMO field contains a value of 0 and RAB$V_TMO is set when you invoke either a Get or Put service to a mailbox device, the operation terminates immediately, rather than waiting for another process. For example, if you invoke the Put service to a mailbox device with the RAB$B_TMO field clear, the Put service does not wait for the receiving process to get the record.

This field corresponds to the FDL attribute CONNECT TIMEOUT_PERIOD and it is not supported for DECnet for OpenVMS operations.

7.25 RAB$L_UBF Field

The user record buffer address (UBF) field indicates the location of a record or block buffer.

Note
When you invoke the Get service, RMS takes control of the record buffer and can modify it. RMS returns the record size and only guarantees the contents from where it accessed the record to the completion of the record.
This field contains the symbolic address of a work area (buffer) within your program. The size of this buffer must be defined in the RAB$W_USZ (user record area size) field.

When you invoke a Get service, this field must contain the buffer address, regardless of the record transfer mode (locate or move). This option also applies when you invoke the Read service for block I/O. However, a Put or Write service never needs a user buffer.

7.26 RAB$W_USZ Field

The user record buffer size (USZ) field indicates the length (1 through 65,535 bytes) of the user record buffer (RAB$L_UBF).

The user record buffer should be large enough to contain the largest record in the file. If the buffer is not large enough to accommodate a record obtained by a Get service operation, RMS moves as much of the record as possible into the buffer and returns a warning status code.

The value in this field specifies the transfer length, in bytes, for block I/O operations with a Read service and for a Get service to UDF (undefined) format sequential files.

7.27 RAB$L_XAB Field

The extended attribute block address (XAB) field contains the symbolic address of a XAB control block that you want to use when performing an operation such as a Get service for a terminal device. A value of 0 (the default) indicates no XABs for this record stream.

For certain record operations, you can associate XABs with a RAB to convey additional attributes about an operation. (See Section 1.2.2 for the description of a XAB.)

Chapter 8
64-Bit Record Access Block (RAB64)

On an Alpha system, the 64-bit record access block (RAB64) is an extension of the RAB (described in Chapter 7) that allows OpenVMS Alpha users to use 64-bit addresses for the following I/O buffers:

  • UBF (user record buffer)
  • RBF (record buffer)
  • RHB (fixed-length record header buffer; fixed portion of VFC record format)
  • KBF (key buffer containing the key value for random access)

RAB64 has fields corresponding to all the RAB fields, plus seven additional fields to accommodate 64-bit addressing.

8.1 Summary of Fields

The additional fields in the extended RAB64 data structure are summarized at the beginning of Table 8-1 and are described in this chapter. All the other RAB64 fields are exactly like their RAB counterparts described in Chapter 7, unless noted otherwise in this chapter.

Table 8-1 gives the symbolic offset, the size, the RAB cross-reference, and a brief description for each RAB64 field.

Table 8-1 RAB64 Fields
Field Offset Size
(Bytes) 		RAB Cross-Reference Description
Alpha-Only RAB64 Fields Described in this Chapter1:
RAB64$Q_CTX 8 None User context (64-bit)
RAB64$PQ_KBF 8 None Key buffer 64-bit address
RAB64$PQ_RBF 8 None Record buffer 64-bit address
RAB64$PQ_RHB 8 None Record header buffer 64-bit address
RAB64$Q_RSZ 8 None Record buffer size
RAB64$PQ_UBF 8 None User record buffer 64-bit address
RAB64$Q_USZ 8 None User record buffer size
       
RAB64 Fields Equivalent to RAB Fields Described in Chapter 7:
RAB64$B_BID 2 1 See RAB$B_BID in Section 7.2 Block identifier
RAB64$L_BKT 4 See RAB$L_BKT in Section 7.3 Bucket code
RAB64$B_BLN 3 1 See RAB$B_BLN in Section 7.4 Block length
RAB64$L_CTX 4 See RAB$L_CTX in Section 7.5 User context
RAB64$L_FAB 4 See RAB$L_FAB in Section 7.6 File access block address
RAB64$W_ISI 4 2 See RAB$W_ISI in Section 7.7 Internal stream identifier
RAB64$L_KBF 4 See RAB$L_KBF in Section 7.8 Key buffer address
RAB64$B_KRF 1 See RAB$B_KRF in Section 7.9 Key of reference
RAB64$B_KSZ 1 See RAB$B_KSZ in Section 7.10 Key size
RAB64$B_MBC 1 See RAB$B_MBC in Section 7.11 Multiblock count
RAB64$B_MBF 1 See RAB$B_MBF in Section 7.12 Multibuffer count
RAB64$L_PBF 4 See RAB$L_PBF in Section 7.13 Prompt buffer address
RAB64$B_PSZ 1 See RAB$B_PSZ in Section 7.14 Prompt buffer size
RAB64$B_RAC 1 See RAB$B_RAC in Section 7.15 Record access mode
RAB64$L_RBF 4 See RAB$L_RBF in Section 7.16 Record buffer address
RAB64$W_RFA 6 See RAB$W_RFA in Section 7.17 Record file address
RAB64$L_RHB 4 See RAB$L_RHB in Section 7.18 Record header buffer address
RAB64$L_ROP 4 See RAB$L_ROP in Section 7.19 Record-processing options
RAB64$W_ROP_2 2 See RAB$W_ROP_2 in Section 7.20 Extended record-processing options
RAB64$W_RSZ 2 See RAB$W_RSZ in Section 7.21 Record buffer size
RAB64$L_STS 4 4 See RAB$L_STS in Section 7.22 Completion status code
RAB64$L_STV 4 4 See RAB$L_STV in Section 7.23 Status value
RAB64$W_STV0 5 2 See RAB$L_STV in Section 7.23 Low-order word status value
RAB64$W_STV2 5 2 See RAB$L_STV in Section 7.23 High-order word status value
RAB64$B_TMO 1 See RAB$B_TMO in Section 7.24 Timeout period
RAB64$L_UBF 4 See RAB$L_UBF in Section 7.25 User record buffer address
RAB64$W_USZ 2 See RAB$W_USZ in Section 7.26 User record buffer size
RAB64$L_XAB 4 See RAB$L_XAB in Section 7.27 Next XAB address
1None of these fields have FDL equivalents.
2The $RAB64 macro statically initializes this field to identify this control block as a RAB.
3The $RAB64 macro statically initializes this field to identify this control block as a RAB64. If the user initializes this field, it must be initialized to RAB64$C_BLN64.
4This field cannot be initialized by the $RAB64 macro.
5Alternate definition of RAB64$L_STV field.

The RAB64 $PQ_ fields can hold either 64-bit addresses or 32-bit addresses sign-extended to 64-bits. Therefore, you can use these fields in all applications whether or not you are using 64-bit addresses.

If your application already uses RAB fields, only minimal source code changes are required to use 64-bit RMS support. The RAB64 64-bit counterpart to a 32-bit address field is used only if the following two conditions exist:

  • The RAB64$B_BLN field has been initialized to RAB64$C_BLN64.
  • The 32-bit address cell in the 32-bit portion of the RAB64 contains -1 .

Because the RAB64 is an upwardly compatible version of the RAB, RMS allows you to use the RAB64 wherever you can use a RAB. For example, a RAB64 can be used in place of a RAB as the first argument passed to any of the RMS record or block I/O services.

While RMS allows you to use the RAB64 wherever you can use a RAB, some source languages may impose other restrictions. Consult the documentation for your source language for more information.

DECnet for OpenVMS support for RAB64 fields is identical to support described for RAB fields in Chapter 7.

The format and arguments of the $RAB64 macro and the $RAB64_STORE macro are described in Appendix A.

8.2 RAB64$Q_CTX Field

This Alpha-only, 8-byte field is a 64-bit extension of the user context field and serves the same purpose as RAB$L_CTX (see Section 7.5 for details). The only difference between these fields, other than size, is that there is no corresponding FDL attribute for RAB64$Q_CTX.

8.3 RAB64$PQ_KBF Field

This Alpha-only, 8-byte field is a key buffer 64-bit address field that serves the same purpose as RAB$L_KBF (see Section 7.8 for details). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.

To use this field: Put a -1 in this field: Use this size field:
RAB64$PQ_KBF RAB64$L_KBF RAB64$B_KSZ

8.4 RAB64$PQ_RBF Field

This Alpha-only, 8-byte field is a record buffer 64-bit address field that serves the same purpose as RAB$L_RBF (see Section 7.16 for details). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.

To use this field: Put a -1 in this field: Use this size field: Put a 0 in this field:
RAB64$PQ_RBF RAB64$L_RBF RAB64$Q_RSZ RAB64$W_RSZ

For most record I/O service requests, there is an RMS internal buffer between the device and the user's data buffer. The one exception occurs with the RMS service $PUT. If the device is a unit record device and it is not being accessed over the network, RMS passes the address of the user record buffer to the $QIO system service. If you inappropriately specify a record buffer allocated in 64-bit address space for a $PUT service to a unit record device that does not support 64-bit address space (for example, a terminal), the $QIO service returns error status SS$_NOT64DEVFUNC. RMS returns error status RMS$_SYS with SS$_NOT64DEVFUNC as the secondary status value in RAB64$L_STV.

8.5 RAB64$PQ_RHB Field

This Alpha-only, 8-byte field is a record header buffer 64-bit address field that serves the same purpose as RAB$L_RHB (see Section 7.18 for details). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.

To use this field: Put a -1 in this field: Use this size field:
RAB64$PQ_RHB RAB64$L_RHB FAB$B_FSZ

8.6 RAB64$Q_RSZ Field

This Alpha-only, 8-byte field is an extended record size field that serves the same purpose as RAB$W_RSZ (see Section 7.21 for details). Use this field whenever you use the RAB64$PQ_RBF field.

The buffer size maximum for the RMS block I/O service $WRITE has been increased from 65535 bytes to 2**31-1 bytes for OpenVMS Alpha users, with two exceptions:

  • For RMS journaling, a journaled $WRITE service is restricted to the current maximum (65535 minus 99 bytes of journaling overhead). An RSZ error is returned (RAB$L_STS) if the maximum is exceeded.
  • Magnetic tape is still limited at the device driver level to 65535 bytes.

8.7 RAB64$PQ_UBF Field

This Alpha-only, 8-byte field is a user record buffer 64-bit address field that serves the same purpose as RAB$L_UBF (see Section 7.25 for details). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.

To use this field: Put a -1 in this field: Use this size field: Put a 0 in this field:
RAB64$PQ_UBF RAB64$L_UBF RAB64$Q_USZ RAB64$W_USZ

8.8 RAB64$Q_USZ Field

This Alpha-only, 8-byte field is an extended user record buffer size field that serves the same purpose as RAB$W_USZ (see Section 7.26 for details). Use this field whenever you use the RAB64$PQ_UBF field.

The buffer size maximum for the RMS block I/O service $READ has been increased from 65535 bytes to 2**31-1 bytes for OpenVMS Alpha users, with one exception:

  • Magnetic tape is still limited at the device driver level to 65535 bytes.

Previous Next Contents Index