Document revision date: 15 July 2002

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

You can store the item list anywhere within process readable address space, but any buffers required by the related function must be in read/write memory.

The format and arguments of the $XABITM macro are defined in Appendix A.

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.

The system capabilities supported by various DAP implementations are described using a vector of bits wherein a bit is set if the corresponding capability is supported. Any attempt to implement a feature at the local node that is not supported at the remote node is treated as a protocol error. Table 12-3 describes the bit vectors that RMS uses to return the networking capabilities for both the local and remote nodes to the calling program.

Table 12-3 System Networking Capabilities

Bit Value	Capability
XAB$V_CAP_FILALL	Allocation of space at file creation
XAB$V_CAP_SEQORG	Sequential file organization
XAB$V_CAP_RELORG	Relative file organization
XAB$V_CAP_EXTEND	Manual file extension
XAB$V_CAP_SEQFIL	Sequential file access (file transfer mode)
XAB$V_CAP_RANRRN	Random access by relative record number
XAB$V_CAP_RANVBN	Random access by virtual block number
XAB$V_CAP_RANKEY	Random access by key value
XAB$V_CAP_RANRFA	Random access by record file address
XAB$V_CAP_IDXORG	Multikeyed indexed file organization
XAB$V_CAP_SWMODE	Dynamic switching of access modes
XAB$V_CAP_APPEND	Records appended to end of file
XAB$V_CAP_SUBMIT	Command file submission/execution
XAB$V_CAP_MDS	Multiple data streams for each file
XAB$V_CAP_DISPLAY	Display of file attributes on request
XAB$V_CAP_MSGBLK	Blocking of DAP messages up to response (less than 256 bytes)
XAB$V_CAP_UNRBLK	Unrestricted blocking of DAP messages
XAB$V_CAP_BIGBLK	Blocking of DAP messages up to response (greater than or equal to 256 bytes)
XAB$V_CAP_DAPCRC	DAP message CRC checksum
XAB$V_CAP_KEYXAB	Key definition XAB message
XAB$V_CAP_ALLXAB	Allocation XAB message
XAB$V_CAP_SUMXAB	Summary XAB message
XAB$V_CAP_DIRECTORY	Directory list operation
XAB$V_CAP_TIMXAB	Date and time XAB message
XAB$V_CAP_PROXAB	File protection XAB message
XAB$V_CAP_FOPSPL	Spool file on Close FOP option
XAB$V_CAP_FOPSCF	Submit command file on Close FOP option
XAB$V_CAP_FOPDLT	Delete file on Close FOP option
XAB$V_CAP_SEQRAC	Sequential record access
XAB$V_CAP_BITOPT	Bit count option in the FLAGS field
XAB$V_CAP_WARNING	Warning status message and error recovery message exchange
XAB$V_CAP_RENAME	File rename operation
XAB$V_CAP_WILDCARD	Wildcard operations (excluding directory)
XAB$V_CAP_GNGOPT	Go/Nogo option in the ACCOPT field
XAB$V_CAP_NAMMSG	Name message
XAB$V_CAP_SEGMSG	Segmented DAP messages
XAB$V_CAP_CHGATTCLS	Changing file attributes on Close using ATT message
XAB$V_CAP_CHGTIMCLS	Changing file attributes on Close using TIM message
XAB$V_CAP_CHGPROCLS	Changing file attributes on Close using PRO message
XAB$V_CAP_CHGNAMCLS	Changing file attributes on Close using NAM message
XAB$V_CAP_MODATTCRE	Modified attributes returned when file is created
XAB$V_CAP_NAM3PART	Three-part name message format in DISPLAY field of both Access and Control messages
XAB$V_CAP_CHGATTREN	Changing file attributes on Rename using ATT message
XAB$V_CAP_CHGTIMREN	Changing file attributes on Rename using TIM message
XAB$V_CAP_CHGPROREN	Changing file attributes on Rename using PRO message
XAB$V_CAP_CTLBLKCNT	BLKCNT field in Control message
XAB$V_CAP_OCTALVER	Octal version numbers only in file specifications

	privacy and legal statement
4523PRO_016.HTML