OpenVMS Record Management Services Reference Manual

Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual

Contents

Index

This option is not supported for DECnet for OpenVMS operations.

RAB$V_PMT

Prompt option; indicates that the contents of the prompt buffer are to be used as a prompt for reading data from a terminal (see RAB$L_PBF field).

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

RAB$V_PTA

Purge type-ahead; eliminates any information that might be in the type-ahead buffer on a read from a terminal.

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

RAB$V_RNE

Read no echo; indicates that input data is not echoed (displayed) on the terminal as it is entered on the keyboard.

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

RAB$V_RNF

Read no filter; indicates that CTRL/U, CTRL/R, and DELETE are not to be considered control commands on terminal input but are to be passed to the application program.

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

RAB$V_TMO

Timeout; for terminal operations, indicates that the content of the RAB$B_TMO field is to be used to determine the number of seconds allowed between characters received during terminal input. If the timeout period expires, RMS returns an error status (see RAB$B_TMO). Other functions of the RAB$V_TMO option are listed under Miscellaneous Options and Record Locking Options.

This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE and is not supported for DECnet for OpenVMS operations.

7.20 RAB$W_RSZ Field

The record size (RSZ) field contains the size, in bytes, of the record to which the record buffer address (RAB$L_RBF) field points. For a Write service, the range is 1 through 65,535. For a Put or Update service, the range is 0 to the maximum value shown in Table 4-4. The record size field specifies the size of a record that a Put or Update service can write, or the number of bytes that a Write (block I/O) service can write. The Update service requires the record size field only if the file contains variable-length records or VFC records.

On input from a file, RMS sets this field to indicate the length, in bytes, of the record that a Get service transfers or that a Read service (block I/O) reads.

Three notes apply to this field:

After a Get service, RMS places the record size in the RAB$W_RSZ field. On a Read service, RMS sets the RAB$W_RSZ field to the number of bytes actually transferred.
For variable with fixed-length control records, RMS does not include the size of the fixed control area in the RAB$W_RSZ field.
For block I/O operations, some devices require that an even number of bytes be transferred. No user action is required because RMS automatically rounds the number of transfers up to an even number.

7.21 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.22 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.23 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.24 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.25 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.26 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 Chapter¹:

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 ² 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 ³ 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 ⁴ 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_RSZ 2 See RAB$W_RSZ in Section 7.20 Record buffer size

RAB64$L_STS ⁴ 4 See RAB$L_STS in Section 7.21 Completion status code

RAB64$L_STV ⁴ 4 See RAB$L_STV in Section 7.22 Status value

RAB64$W_STV0 ⁵ 2 See RAB$L_STV in Section 7.22 Low-order word status value

RAB64$W_STV2 ⁵ 2 See RAB$L_STV in Section 7.22 High-order word status value

RAB64$B_TMO 1 See RAB$B_TMO in Section 7.23 Timeout period

RAB64$L_UBF 4 See RAB$L_UBF in Section 7.24 User record buffer address

RAB64$W_USZ 2 See RAB$W_USZ in Section 7.25 User record buffer size

RAB64$L_XAB 4 See RAB$L_XAB in Section 7.26 Next XAB address

**Table 8-1 RAB64 Fields**
Field Offset	Size (Bytes)	RAB Cross-Reference	Description
Alpha-Only RAB64 Fields Described in this Chapter¹:
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 ²	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 ³	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 ⁴	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_RSZ	2	See RAB$W_RSZ in Section 7.20	Record buffer size
RAB64$L_STS ⁴	4	See RAB$L_STS in Section 7.21	Completion status code
RAB64$L_STV ⁴	4	See RAB$L_STV in Section 7.22	Status value
RAB64$W_STV0 ⁵	2	See RAB$L_STV in Section 7.22	Low-order word status value
RAB64$W_STV2 ⁵	2	See RAB$L_STV in Section 7.22	High-order word status value
RAB64$B_TMO	1	See RAB$B_TMO in Section 7.23	Timeout period
RAB64$L_UBF	4	See RAB$L_UBF in Section 7.24	User record buffer address
RAB64$W_USZ	2	See RAB$W_USZ in Section 7.25	User record buffer size
RAB64$L_XAB	4	See RAB$L_XAB in Section 7.26	Next XAB address

¹None of these fields have FDL equivalents.
²The $RAB64 macro statically initializes this field to identify this control block as a RAB.
³The $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.
⁴This field cannot be initialized by the $RAB64 macro.
⁵Alternate 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

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

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

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.20 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.24 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

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

Contents

Index

Legal

 
4523PRO_012.HTML

OpenVMS Record Management Services Reference Manual

7.21 RAB$L_STS Field

Chapter 864-Bit Record Access Block (RAB64)

8.7 RAB64$PQ_UBF Field

Chapter 8
64-Bit Record Access Block (RAB64)