Document revision date: 30 March 2001

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.

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

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

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.

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.

The allocation control XAB (XABALL) provides additional control over file or area space allocation on disk devices in order to optimize performance. In the following descriptions, the terms file and area are synonymous for sequential and relative files because these file organizations are limited to a single area (Area 0).

9.1 Summary of Fields

When RMS uses a XAB to create or extend an area, the following XABALL fields duplicate and take precedence over associated fields in the related FAB:

• The allocation quantity (ALQ) field, XAB$L_ALQ, overrides FAB$L_ALQ
• The bucket size (BKZ) field, XAB$B_BKZ, overrides FAB$B_BKS
• The default extension quantity (DEQ) field, XAB$W_DEQ, overrides FAB$W_DEQ
• The XAB$V_CBT and XAB$V_CTG options of the allocation options field, XAB$B_AOP, override the FAB$V_CBT and FAB$V_CTG options of the file-processing options field, FAB$L_FOP

When opening a file or displaying a file's attributes, RMS outputs appropriate information to your program using these fields.

The symbolic offset, the size, the FDL equivalent, and a brief description of each XABALL field are presented in Table 9-1.

Table 9-1 XABALL Fields

Field Offset	Size (Bytes)	FDL Equivalent	Description
XAB$B_AID	1	AREA n	Area identification number
XAB$B_ALN	1	AREA POSITION 1	Alignment boundary type
XAB$L_ALQ	4	AREA ALLOCATION	Allocation quantity
XAB$B_AOP	1	AREA 1	Allocation options
XAB$B_BKZ	1	AREA BUCKET_SIZE	Bucket size
XAB$B_BLN 2	1	None	Block length
XAB$B_COD 2	1	None	Type code
XAB$W_DEQ	2	AREA EXTENSION	Default extension quantity
XAB$L_LOC	4	AREA POSITION	Location
XAB$L_NXT	4	None	Next XAB address
XAB$W_RFI	6	AREA POSITION FILE_ID or FILE_NAME	Related file identifier
XAB$W_VOL	2	AREA VOLUME	Related volume number

Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations on 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.

9.2 XAB$B_AID Fields

RMS uses the area identification number (AID) field to determine which area within a file is supported by this XAB. Note that sequential and relative files are limited to area 0.

The area is identified by a numeric value in the range 0 through 254 (default is 0) and is most appropriate for use with index files having multiple areas allocated.

This field corresponds to the FDL attribute AREA n, where n indicates the area number.

9.3 XAB$B_ALN Field

The alignment boundary type (ALN) field gives you several options for aligning the allocated area. RMS uses this field in conjunction with the XAB$L_LOC field and with the XAB$W_RFI field to provide precise positioning control of the area or area extension.

The XAB$B_ALN field is a keyword value field in which an alignment boundary option is defined by a symbolic constant value. For example, the cylinder boundary option has a symbolic constant value of XAB$C_CYL.

Note that if no value is defined for this field, RMS assumes the XAB$C_ANY option (no additional positioning control desired). Additional positioning control is not supported for DECnet for OpenVMS operations.

The XAB$B_ALN field corresponds to the FDL attribute AREA POSITION.

Options

XAB$C_ANY

Any allocation; specifies that no positioning control over the area is desired. If this option is selected, the XAB$L_LOC and XAB$W_RFI fields are ignored.

This option corresponds to the FDL attribute AREA POSITION NONE.

XAB$C_CYL

Specifies that the area boundary begin at the cylinder number identified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION CYLINDER.

XAB$C_LBN

Specifies that the area boundary begin at the logical block number identified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION LOGICAL.

XAB$C_RFI

This option is used only for extending an area. It specifies that the area extension begin as close as possible to the file identified by the related-file-identification field (XAB$W_RFI), and that the extent begin with the VBN specified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION FILE_ID or AREA POSITION FILE_NAME. If you try to use this option with DECnet for OpenVMS operations, RMS replaces it with the XAB$C_ANY option.

XAB$C_VBN

This option applies to area extension only. It specifies that the area extension begin as close as possible to the virtual block number identified by the location field XAB$L_LOC.

This option corresponds to the FDL attribute AREA POSITION VIRTUAL.

	privacy and legal statement
4523PRO_013.HTML