|
HP OpenVMS Systems Documentation |
|
OpenVMS Record Management Services Reference Manual
7.24 RAB$B_TMO FieldThe 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.
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.
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.
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
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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:
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 |
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 |
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:
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 |
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:
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:
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.
| 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.
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.
| Previous | Next | Contents | Index |