Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual

The revision date and time (RDT) field contains a 64-bit binary value representing the date and time when the file was last revised. The Open and Display services use this field to read the revision date and time. The Create service uses this field to set the revision date and time. However, a subsequent Close service overrides the value set by the Create service by using the value in the XAB$Q_RDT field of the XABRDT.

If the application program specifies this field as 0 (either explicitly or by default), the Create service uses the current date and time as the revision date and time. Note that this field is limited to a granularity of 1 second for remote files.

This field corresponds to the FDL attribute DATE REVISION.

10.9 XAB$W_RVN Field

The revision number (RVN) field contains a numeric value that indicates the number of times this file was opened for write operations.

This field corresponds to the FDL attribute FILE REVISION.

10.10 XAB$Q_RCD Field (VAX Only)

On VAX systems, the XAB$Q_RCD (RCD) field contains a 64-bit binary value expressing the date and time that the file was recorded.

This field is applicable only to ISO 9660 files and has no corresponding FDL attribute.

10.11 XAB$Q_EFF Field (VAX Only)

On VAX systems, the XAB$Q_EFF (EFF) field contains a 64-bit binary value expressing the date and time when the file information may be used. If no value is specified in this field, the data may be used immediately.

This field is applicable only to ISO 9660 files and has no corresponding FDL attribute.

The file header characteristic XAB (XABFHC) contains file header information that is output by the Open service and the Display service. The Create service can output information in this XAB when it opens an existing file through use of the Create-if option.

The only input field is the longest record length (XAB$W_LRL) field. The Create service uses this field when it creates a sequential file that does not use a fixed-length record format.

Note that, for unshared sequential files or sequential files shared using the FAB$V_UPI option, the values in the end-of-file block (XAB$L_EBK), first free byte in the end-of-file block (XAB$W_FFB), and longest record length (XAB$W_LRL) fields correspond to the values at the time of the last Close or Flush service.

11.1 Summary of Fields

The symbolic offset, size, and a brief description of each RAB field are presented in Table 11-1. Note that many of these fields are also available in the FAB.

Table 11-1 XABFHC Fields

Field Offset	Size (Bytes)	Description
XAB$B_ATR 1	1	Record attributes; equivalent to FAB$B_RAT
XAB$B_BKZ 1	1	Bucket size; equivalent to FAB$B_BKS
XAB$B_BLN 2	1	Block length
XAB$B_COD 2	1	Type code
XAB$W_DXQ 1	2	Default file extension quantity; equivalent to FAB$W_DEQ
XAB$L_EBK 1	4	End-of-file block
XAB$W_FFB 1	2	First free byte in the end-of-file block
XAB$W_GBC 1	2	Default global buffer count
XAB$L_HBK 1	4	Highest virtual block in the file; equivalent to FAB$L_ALQ
XAB$B_HSZ 1	1	Fixed-length control header size; equivalent to FAB$B_FSZ
XAB$W_LRL 1	2	Longest record length
XAB$W_MRZ 1	2	Maximum record size; equivalent to FAB$W_MRS
XAB$L_NXT	4	Next XAB address
XAB$B_RFO 1	1	File organization and record format; combines FAB$B_RFM and FAB$B_ORG
XAB$L_SBN 1	4	Starting logical block number for the file if it is contiguous; otherwise this field is 0
XAB$W_VERLIMIT 1	2	Version limit for the file

There are no FDL equivalents for the XABFHC fields. Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations on files at remote OpenVMS systems. See the DECnet for OpenVMS Networking Manual for information about the support of RMS options for remote file access to other systems.

11.2 XAB$B_ATR Field

The record attributes (ATR) field indicates the record attributes (special control information) associated with each record in this file. This field is equivalent to the FAB$B_RAT field.

This field is a binary options field where each record attribute has a corresponding bit assignment. Options are identified using mnemonics. Each option in the field has its own symbolic offset and constant value. For example, the CR record attribute has the symbolic offset XAB$V_CR and the mask value XAB$M_CR. The record attribute options are described in the following list.

Options

XAB$V_BLK

Records do not cross block boundaries in sequential files.

XAB$V_CR

Each record is preceded by a line feed and followed by a carriage return.

XAB$V_FTN

Each record contains a FORTRAN (ASA) carriage return in the first byte.

XAB$V_PRN

Print file format.

For more information about the XAB$B_ATR field, refer to the description of the FAB$B_RAT field in Section 4.27.

11.3 XAB$B_BKZ Field

The bucket size (BKZ) field specifies the number of blocks in each bucket of the file. It is equivalent to the FAB$B_BKS (or XAB$B_BKZ) field and is used only for relative or indexed files.

This field contains a numeric value in the range of 0 to 63.

For more information about the XAB$B_BKZ field, refer to the description of the FAB$B_BKS field in Section 4.5 and the description of the XAB$B_BKZ field in Section 9.6.

11.4 XAB$B_BLN Field

The block length (BLN) field is a static field that defines the length of the XABFHC, 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 XAB$C_FHCLEN (this is done by the $XABFHC macro).

11.5 XAB$B_COD Field

The type code (COD) field is a static field that identifies this control block as a XABFHC. 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 XAB$C_FHC (this is done by the $XABFHC macro).

11.6 XAB$W_DXQ Field

The default file extension quantity (DXQ) field specifies the number of blocks to be added when a disk file is extended automatically. This automatic extension occurs whenever your program performs a Put or Write service and the currently allocated file space is exhausted.

This field is equivalent to the FAB$W_DEQ (or XAB$W_DEQ) field; it contains a numeric value in the range 0 through 65,535, which is rounded up to the value of the next cluster boundary.

For more information about the XAB$W_DXQ field, refer to the description of the FAB$W_DEQ field in Section 4.10 and the description of the XAB$W_DEQ field in Section 9.9.

11.7 XAB$L_EBK Field

When you open a file, RMS stores the VBN of the physical block where the next record will be written in the XAB$L_EBK field. For example, assume that a file is allocated five physical blocks and that the last record written to the file is at byte 0FF _16 in the file's second physical block. When your program opens this file, RMS stores the VBN of the second physical block in XAB$L_EBK and it stores 100_16 in the XAB$W_FFB field.

If the previous block is full when you open the file, RMS stores the first location ( 000_16 ) of the next block in XAB$W_FFB and the VBN of the next block in XAB$L_EBK. By way of contrast, in a similar situation RMS-11 stores the last byte ( 200_16 ) of the filled block in the XAB$W_FFB field and the VBN of the filled block in the XAB$L_EBK field.

The XAB$L_EBK field is meaningful for sequential files only.

11.8 XAB$W_FFB Field

The first free byte in the end-of-file block (FFB) field contains the byte location in the end-of-file block where the next record will be written. The XAB$W_FFB field is meaningful for sequential files only.

11.9 XAB$W_GBC Field

The default global buffer count (GBC) field contains the current global buffer count for this file. For more information about the XAB$W_GBC field, refer to the description of the FAB$W_GBC field in Section 4.19.

This field is not supported for DECnet for OpenVMS operations; it is ignored.

11.10 XAB$L_HBK Field

The highest virtual block (HBK) field contains the virtual block number currently allocated to this file. It is equivalent to the FAB$L_ALQ field after a Create, Open, or Display service executes. For sequential files, the difference between XAB$L_HBK and XAB$L_EBK equals the number of blocks in the file available for additional records without extending the file.

11.11 XAB$B_HSZ Field

The fixed-length control header size (HSZ) field indicates the length of the fixed portion for records in the VFC format. It is equivalent to the FAB$B_FSZ field.

This field contains a numeric value (1 to 255) that indicates, in bytes, the size of the fixed-length control area. This field is not applicable to indexed files.

For more information about the XAB$B_HSZ field, refer to the description of the FAB$B_FSZ field in Section 4.18.

11.12 XAB$W_LRL Field

The longest record length (LRL) field contains a numeric value that indicates the longest record currently in the file, in bytes. This value is meaningful for sequential files only. If you specify the XAB$W_MRZ field, the LRL field takes the same value as the XAB$W_MRZ field.

11.13 XAB$W_MRZ Field

The maximum record size (MRZ) field indicates the size of all records in a file with fixed-length records, the maximum size of variable-length records, the maximum size of the data area for variable with fixed-length control records, and the cell size for relative files. It is equivalent to the FAB$W_MRS field.

This field contains a numeric value in the range applicable to the file type and record format (see Table 4-4), in bytes.

For fixed-length records, the value represents the actual size of each record in the file.

For variable-length records, the value represents the size of the largest record that can be written into the file. If the file is not a relative file, a value of 0 is used to suppress record size checking, thus indicating that there is no user limit on record size.

For variable with fixed-length control records, the value includes only the data portion; it does not include the size of the fixed control area.

For more information about the XAB$W_MRZ field, refer to the description of the FAB$W_MRS field in Section 4.24.

11.14 XAB$L_NXT Field

The next XAB address (NXT) field contains the symbolic address of the next XAB. A value of 0 (the default) indicates that the current XAB is the last (or only) XAB in the chain.

11.15 XAB$B_RFO Field

The file organization and record format (RFO) field combines the FAB$B_RFM and FAB$B_ORG fields using an inclusive OR.

The following table lists the record formats.

Record Format	Description
FIX	Fixed length
STM	Stream, delimited by FF, VT, LF, or CR LF
STMCR	Stream, delimited by CR
STMLF	Stream, delimited by LF
UDF	Undefined
VAR	Variable length
VFC	Variable length with fixed control area

The following table lists the file organizations.

File Organization	Description
IDX	Indexed sequential
REL	Relative
SEQ	Sequential

For more information about the XAB$B_RFO field, refer to the description of the FAB$B_ORG field and the FAB$B_RFM field in Section 4.28.

11.16 XAB$L_SBN Field

The starting logical block number (SBN) field contains the starting logical block number for a contiguous file; if the file is not contiguous, this field contains 0.

11.17 XAB$W_VERLIMIT Field

The file version limit (VERLIMIT) field contains the version limit for this file. This value is not available if the file was opened by file ID.

This field is not supported for DECnet for OpenVMS operations; it is ignored.

The item list XAB (XABITM) provides a convenient means for using item list information to support RMS functions. Each XABITM points to an item list that includes one or more entries representing either a set function or a sense function that can be passed to the application program by way of the RMS interface.

Because the mode field in a XABITM can be used to either set or sense the items in the list, you cannot use a single XABITM to both set and sense a particular function. However, you may use multiple XABITMs, some for setting functions and other for sensing functions. RMS logically ignores items that are irrelevant to any particular function while acting on any item that is relevant.

Each entry in the item list includes three longwords, and a longword 0 terminates the list. See Figure 12-1. Note the field "Return length address" in Figure 12-1 is ignored for Set Mode. Also note that RMS does not validate the item list. If the item list is invalid, RMS indicates that the XABITM is not valid by returning the invalid XAB status (RMS$_XAB) in the RAB$L_STS field.

Figure 12-1 Item Descriptor Data Structure

The XABITM control block currently supports the following functions:

• Enhancements to network file access functions
• Passing of file user characteristic information
• Enhancements to RMS performance monitoring functions
• Support for compound documents
• Specifying the number of local buffers
• Expiration date and time suppression
• Support for file size in heterogeneous environments

The symbolic offset, the size, and a brief description of each XABITM field are presented in Table 12-1.

Table 12-1 XABITM Fields

Field Offset	Description
XAB$B_BLN 1	Block length
XAB$B_COD 1	Type code
XAB$L_ITEMLIST	Item list address
XAB$B_MODE	Set/sense control
XAB$L_NXT	Next XAB address

The block length (BLN) field is a static field that defines the length of the XABITM, 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 XAB$C_ITMLEN by the $XABITM macro.

12.1.2 XAB$B_COD Field

The type code (COD) field is a static field that identifies this control block as a XABITM. 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 XAB$C_ITM by the $XABITM macro.

12.1.3 XAB$L_ITEMLIST Field

The item list address (ITEMLIST) field contains the symbolic address of the item list.

12.1.4 XAB$B_MODE Field

The item list mode (MODE) field specifies whether the items in the item list can be set or sensed by the program. It contains either the symbolic value XAB$K_SETMODE or the symbolic value XAB$K_SENSEMODE (default).

12.1.5 XAB$L_NXT Field

The next XAB address (NXT) field contains the symbolic address of the next XAB to be used. A value of 0 (the default) indicates that the current XAB is the last (or only) XAB in the chain.

12.2 Network File Access Items (XAB$_NET_... and XAB$_CAP_...)

This section lists and briefly describes the items that support network file access features.

Network items are effectively ignored for local operations. Although the application program may include network items in the XAB chain for the related FAB, RMS does not consider any of the network-specific fields during local processing. Nor does RMS return remote file contents to the application program during local file processing.

Table 12-2 lists the entries in the XABITM item list relating to network file access features together with the buffer size required to store the data and a brief functional description. Note that although the application program can sense all of the item values from the RMS interface, it can set only the following item values:

• XAB$_NET_BLOCK_COUNT
• XAB$_NET_EXTPROT
• XAB$_NET_LINK_TIMEOUT
• XAB$_NET_LINK_CACHE_ENABLE
• XAB$_NET_DATA_CRC_ENABLE

Table 12-2 XABITM Item List

Item Value	Description
XAB$_NET_BUFFER_SIZE	The size of the buffer allocated for DAP messages between the local and remote node is a negotiated value that is decided by DAP. This informational item returns the actual buffer size, in bytes, allocated for DAP messages. The buffer size is slightly larger than the limit specified for the records being transferred. A 4-byte buffer is needed to store the net buffer size.
XAB$_NET_BLOCK_COUNT	This is the value in blocks that the local node wants to use for buffering messages between itself and the remote node. DAP tries to allocate this buffer space at the local node; however, if the maximum buffer size at the remote node is smaller, DAP allocates buffer space based on the smaller value. When the remote system incorporates the file access listener, it allows any size buffer up to 32,767 bytes. The minimum buffer size for task-to-task network operations is 4096 bytes. A 4-byte buffer is needed to store the net block count.
XAB$_NET_REMOTE_SYSTEM	This informational item returns the identity of the remote operating system. A 4-byte buffer is needed to store the symbolic constants representing the remote system identities listed in the following table: Symbolic Constant Operating System XAB$K_RT11 RT-11 XAB$K_RSTS RSTS/E XAB$K_RSX11S RSX-11S XAB$K_RSX11M RSX-11M XAB$K_RSX11D RSX-11D XAB$K_IAS IAS XAB$K_VAXVMS VMS XAB$K_TOPS10 TOPS--10 XAB$K_TOPS20 TOPS--20 XAB$K_RSX11MP RSX-11M-PLUS XAB$K_P_OS P/OS XAB$K_VAXELN VAXELN XAB$K_MS_DOS MS--DOS XAB$K_ULTRIX_32 ULTRIX--32 XAB$K_SNA_OS SNA gateway to IBM
XAB$_NET_REMOTE_FILE_SYSTEM	This informational item returns the identity of the remote file system. A 4-byte buffer is needed to store the symbolic constants listed in the following table: Symbolic Constant File System XAB$K_RMS11 RMS-11 XAB$K_RMS20 RMS--20 XAB$K_RMS32 RMS-32 XAB$K_FCS11 FCS--11 XAB$K_RT11FS RT-11 XAB$K_NO_FS No file system present XAB$K_TOPS20FS TOPS--20 XAB$K_TOPS10FS TOPS--10 XAB$K_RMS32S RMS-32 subset (VAXELN) XAB$K_MS_DOSFS MS--DOS XAB$K_ULTRIX32_FS ULTRIX--32 XAB$K_SNA_FS SNA gateway to IBM
XAB$_NET_EXTPROT	This item permits the application program to specify or to sense the extended file protection that is likely to be mapped to a protection subset supported by the remote system. An 8-byte buffer is needed to store protection mask specification. The application program implements extended file protection as part of either a Create or Close service by specifying the appropriate protection mask in the related subfield: Subfield Protection XAB$W_SYSTEM_ACC System access XAB$W_OWNER_ACC Owner access XAB$W_GROUP_ACC Group access XAB$W_WORLD_ACC World access
	Each of the protection mask fields provides the following mask values for further defining access: Mask Value Protection Function XAB$M_RED_ACC Deny read access XAB$M_WRT_ACC Deny write access XAB$M_EXE_ACC Deny execute access XAB$M_DLT_ACC Deny delete access XAB$M_APP_ACC Deny append access XAB$M_DIR_ACC Deny directory access XAB$M_UPD_ACC Deny update access XAB$M_CHG_ACC Deny change protection access XAB$M_EXT_ACC Deny extend access
	Note that not all systems support all of the protection mask fields.
XAB$_NET_SYSCAP_LOCAL	This informational item permits the application program to read the network capabilities of the local system by returning symbolic bit vector values. An 8-byte buffer is needed to store the symbolic bit vector values. See Table 12-3 for a description of the network capabilities bit vectors used by the local and remote systems.
XAB$_NET_SYSCAP_REMOTE	This informational item permits the application program to read the network capabilities of the remote system by returning symbolic bit vector values. An 8-byte buffer is needed to store the symbolic bit vector values. See Table 12-3 for a description of the network capabilities bit vectors used by the local and remote systems.
XAB$_NET_DAPVER_LOCAL	This informational item returns the version of DAP on the local system using five symbolic bytes, thus requiring a 5-byte buffer: Symbolic Byte Version Information XAB$B_VER_DAP DAP protocol version XAB$B_VER_ECO DAP protocol ECO level XAB$B_VER_CUS Customer modification level of DAP protocol; set to 0 by Compaq XAB$B_VER_DSV Compaq software version (release number) XAB$B_VER_CSV Customer software version number; set to 0 by Compaq
XAB$_NET_DAPVER_REMOTE	This informational item returns the version of DAP on the remote system using five symbolic bytes: Symbolic Byte Version Information XAB$B_VER_DAP DAP protocol version XAB$B_VER_ECO DAP protocol ECO level XAB$B_VER_CUS Customer modification level of DAP protocol; set to 0 by Compaq XAB$B_VER_DSV Compaq software version (release number) XAB$B_VER_CSV Customer software version number; set to 0 by Compaq
XAB$_NET_LINK_TIMEOUT	This item permits the application program to set the timeout interval for logical link caching. The setting is passed as the number of seconds used to cache the logical link. A zero (0) setting enables caching until image rundown. The default interval is 30 seconds. A 4-byte buffer is needed to store the timeout interval value.
XAB$_NET_DATA_CRC_ENABLE	This item allows the application program to enable cyclic redundancy checking at the DAP level. The symbolic value XAB$K_ENABLE enables CRC checking at the DAP level (the default state); the symbolic value XAB$K_DISABLE disables CRC checking at the DAP level.
XAB$_NET_LINK_CACHE_ENABLE	This item is used to enable or to disable logical link caching. The symbolic value XAB$K_ENABLE enables link caching (the default state); the symbolic value XAB$K_DISABLE disables link caching. A 4-byte buffer is required.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4523PRO_014.HTML