Document revision date: 19 July 1999

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

12.3 File User Characteristics Items (XAB$_UCHAR_...)

This section describes the use of the XABITM to pass ODS-2 file information outside the RMS interface level in contrast to the file header information (see Chapter 11) which is used internally by the record management system. The information in this XABITM is independent of any record management system or database management system.

Table 12-4 lists the file user information you can include in a XABITM. You can sense all of the functions listed in the table using either $OPEN or $DISPLAY, but you can set only the following functions using a XABITM:

• XAB$_UCHAR_CONTIGB
• XAB$_UCHAR_ERASE
• XAB$_UCHAR_LOCKED
• XAB$_UCHAR_NOBACKUP
• XAB$_UCHAR_NOMOVE
• XAB$_UCHAR_NOSHELVABLE
• XAB$_UCHAR_READCHECK
• XAB$_UCHAR_WRITECHECK

You can only set these functions when you use the $CREATE operation for a new file. The buffer associated with the item code must contain the symbolic value XAB$K_ENABLE and the XAB$B_MODE field must contain the symbolic value XAB$K_SETMODE.

You cannot enable or disable these functions for an existing file using the XABITM interface; you can only enable or disable these functions for an existing file from the DCL interface using the SET FILE command. See the OpenVMS DCL Dictionary for details.

None of these functions are supported for DECnet operations; they are ignored. The user buffer is left unchanged.

Table 12-4 File User Characteristics

Item	Description
XAB$_UCHAR_BADACL	File's ACL is corrupt.
XAB$_UCHAR_BADBLOCK	File contains bad blocks.
XAB$_UCHAR_CONTIG	File is contiguous.
XAB$_UCHAR_CONTIGB	Keep the file as contiguous as possible.
XAB$_UCHAR_DIRECTORY	File is a directory.
XAB$_UCHAR_ERASE	Erase the file's contents before deleting it.
XAB$_UCHAR_LOCKED	File is deaccess-locked.
XAB$_UCHAR_MARKDEL	File is marked for deletion.
XAB$_UCHAR_NOBACKUP	Do not back up the file.
XAB$_UCHAR_NOCHARGE	Do not charge file space.
XAB$_UCHAR_NOMOVE	Disable movefile operations on the file.
XAB$_UCHAR_NOSHELVABLE	File is not shelvable.
XAB$_UCHAR_PRESHELVED	File is shelved but also kept online.
XAB$_UCHAR_READCHECK	Verify read operations to the file.
XAB$_UCHAR_SHELVED	File is shelved.
XAB$_UCHAR_SPOOL	File is an intermediate spool file.
XAB$_UCHAR_WASCONTIG	File was (and should be) contiguous.
XAB$_UCHAR_WRITEBACK	File may be write-back cached.
XAB$_UCHAR_WRITECHECK	Verify write operations to the file.

12.4 RMS Performance Monitoring (XAB$_STAT_ENABLE)

This section describes the implementation of performance monitoring from the RMS interface using a XABITM.

To explicitly obtain performance statistics for a file through the RMS interface, the application program enables the statistics function using the XAB$_STAT_ENABLE item. This item may be used with a $OPEN or $DISPLAY operation to sense the statistics monitoring state. You can only set the statistics function when you use a $CREATE operation to create a new file. The buffer associated with the item code must contain the symbolic value XAB$K_ENABLE and the XAB$B_MODE field must contain the symbolic value XAB$K_SETMODE.

You cannot enable or disable this function for an existing file using the XABITM interface. You can only enable or disable this function for an existing file from the DCL interface using the SET FILE command. See the OpenVMS DCL Dictionary for details.

For details about using the Monitor utility for gathering performance statistics, see the OpenVMS System Manager's Manual.

This option is not supported for DECnet operations; it is ignored. The user buffer is left unchanged.

Example 12-1 illustrates the use of XABITM to enable statistics monitoring.

Example 12-1 Using XABITM to Enable RMS Statistics

. . . ITEMLIST : BLOCK [ITM$S_ITEM+4, BYTE] INITIAL( REP (ITM$S_ITEM+4) OF (0) ), ITEM_XAB : $XABITM( mode = SETMODE, itemlist = ITEMLIST ), ITEM_BUFFER : LONG INITIAL ( XAB$K_ENABLE); FILE_FAB : $FAB( . . . XAB = ITEM_XAB, . . . ); ITEMLIST[ITM$W_ITMCOD] = XAB$_STAT_ENABLE; ITEMLIST[ITM$W_BUFSIZ] = 4; ITEMLIST[ITM$L_BUFADR] = ITEM_BUFFER; $CREATE( fab = FILE_FAB ); . . .

12.5 Compound Document Support (XAB$_..._SEMANTICS)

The term compound documents refers to files that can contain a number of integrated components including text, graphics, and scanned images. To support the use of text in compound documents, RMS implements the file attribute, stored semantics. The value of the stored semantics attribute is called the file tag, and it specifies how file data is to be interpreted.

RMS support for compound documents requires that compound document files be tagged. You can tag a file from the RMS interface by using the Create service in conjunction with a $XABITM macro, and you can sense the tagged status of a file using a $XABITM macro. Tagged file support involves the use of the two item codes shown in Table 12-5. Each of these item codes requires buffers up to 64 bytes long.

Table 12-5 Tag Support Item Codes

Item	Function
XAB$_STORED_SEMANTICS	Defines the file semantics established when the file is created
XAB$_ACCESS_SEMANTICS	Defines the file semantics desired by the accessing program

The entries XAB$_STORED_SEMANTICS and XAB$_ACCESS_SEMANTICS in the item list can represent either a control (set) function or a monitor (sense) function that can be passed to RMS from the application program by way of the RMS interface. You can use the symbolic value XAB$K_SEMANTICS_MAX_LEN, representing the tag length, to allocate buffer space for sensing and setting stored semantics for the file.

Within any one $XABITM, you can activate either the set function or the sense function for the XAB$_STORED_SEMANTICS and XAB$_ACCESS_SEMANTICS items because a common field (XAB$B_MODE) determines which function is active. If you want to activate both the set function and the sense function for either or both items, you must use two $XABITM control blocks, one for setting the functions and one for sensing the functions.

12.6 Specifying the Number of Local Buffers (XAB$_MULTIBUFFER_COUNT)

This section describes how to use the item list XAB to specify up to 32,767 local buffers. Prior to implementation of the XAB$_MULTIBUFFER_COUNT XABITM, you could only specify up to 127 local buffers for a record stream from the RMS interface using the RAB multibuffer count field (RAB$B_MBF). When you use the multibuffer count XABITM, the value specified overrides any value that resides in the RAB$_MBF for the related record stream.

The XAB$_MULTIBUFFER_COUNT XABITM requires a 4-byte buffer to store the value specifying the number of local buffers. Before you increase the size of the local buffer pool, your current memory management parameters should be considered because excessively large buffer pools can introduce additional paging that reduces performance.

This option is not supported for DECnet operations; it is ignored.

You cannot sense the value stored in the XAB$_MULTIBUFFER_COUNT XABITM, and any attempt to sense this value leaves the user buffer unchanged.

12.7 Expiration Date and Time Suppression

The file system, in conjunction with parameters established through the DCL interface (see the SET VOLUME command in the OpenVMS DCL Dictionary), gives users the capability to determine whether the contents of a data file have grown stale and whether the file is a candidate for less costly and less accessible storage, typically archived tape.

The file system determines whether a file has grown stale by evaluating the Expiration Date and Time flag. This value should reflect real file activity; that is, it should indicate when a file is no longer being actively used for informational purposes. The flag should not be affected by maintenance functions or for any function that does not involve data access.

This capability is also available to all user application programs through the RMS interface using the XAB$_NORECORD XABITM.

12.7.1 XAB$_NORECORD XABITM

When an application program reads data from a disk file or writes data to a disk file, the $CLOSE service updates the Expiration Date and Time value to the current date and time. This effectively pushes back the expiration date and time to reflect user interest in the file.

When the user program accesses a file for maintenance or monitoring purposes, it should use the XAB$_NORECORD XABITM as an input to the appropriate file service to inhibit the update of the Expiration Date and Time field and thereby maintain the true expiration status of the file. For example, the DCL command DIRECTORY/FULL uses the XAB$_NORECORD XABITM when it opens files to access prolog data containing key information. In this case, DIRECTORY displays prolog information but does not display or modify the file data and therefore should not modify the Expiration Date and Time.

Maintenance utilities should also consider using this XABITM. For example, a disk defragmentation utility should not affect the expiration status of a disk file because the file is not accessed for informational purposes, but rather for maintenance purposes.

The XAB$_NORECORD XABITM uses a 4-byte buffer to set the NORECORD flag to logic 1 using the symbol XAB$_ENABLE. Any other value in this XABITM buffer returns an RMS$_XAB error. An application cannot disable this option because the ODS-2 ACP does not support disabling the option when it is selected on a $OPEN or $CREATE.

This option is not supported for DECnet operations; it is ignored.

12.7.2 Application

The XAB$_NORECORD function can be enabled on input to the $CLOSE, $OPEN, and $CREATE services. However, Compaq recommends using the XAB$_NORECORD XABITM with the $OPEN service instead of with the $CLOSE service in order to insure that the Expiration Date and Time flag is updated should the file deaccess or should a close occur because of process deletion or RMS rundown.

The XAB$_NORECORD XABITM can also be used when the $CREATE service opens an existing file through the Create-if option and the user does not want to change the Expiration Date. When the XAB$_NORECORD XABITM is used on a $CREATE that creates a file, it disables the update on the subsequent $CLOSE but does not prevent initialization of the Expiration Date and Time on the file creation in the ACP.

An application typically senses the XAB$_NORECORD XABITM to determine if the XABITM was specified on a previous $OPEN or $CREATE option or if it is specified by the current RMS operation. The XAB$_NORECORD can be sensed on output from RMS for the $OPEN, $CREATE, $DISPLAY, and $CLOSE services.

12.8 File Length Hint (XAB$_FILE_LENGTH_HINT)

The file length hint is a pair of quadword integer fields (16 bytes) as follows:

1. Record count (bytes 0-7): the number of data records written to the file using record I/O ($PUT).
2. User data byte count (bytes 8-15): the total number of user data bytes in the file (excluding any overhead bytes added by RMS).

For sequential files with a record format of variable (VAR) or variable with fixed control (VFC) on an ODS-5 volume, RMS will maintain the file hint, provided:

• The file is written only using unshared RMS record I/O.
• The file does not have journaling enabled.
• The contents of the fields are valid when the file is opened.

The XAB$_FILE_LENGTH_HINT item code may be used with an item list XAB on $OPEN or $DISPLAY operations to sense the file length hint values. A SETMODE may be used with a $CLOSE operation to set the file length hint counts. The SETMODE will override any counts that RMS may be concurrently maintaining.

The XAB$_FILE_LENGTH_HINT XABITM requires a 16-byte buffer for the two quadwords. These fields are maintained as a set: either both fields are valid or invalid.

The most significant (sign) bit of each quadword is used to indicate whether the associated count is valid. A sequential file with VAR or VFC format that is created on an ODS-5 volume, had any data added to it using RMS record I/O ($PUTs) and has met the conditions indicated above should have valid counts. If, however, at some point in time, some data are written to a file using RMS block I/O, for example, then the sign bits will be set on file deaccess to indicate the counts are invalid. The last count maintained in each field is retained as a hint of what its last valid value was, but the sign bit being set indicates it is stale.

If these fields have never been modified by RMS for a file on an ODS-5 volume, then the contents of each quadword will be 8 bytes of 0xFF. For example, after a file originally created and maintained on an ODS-2 volume is converted from ODS-2 format to ODS-5 format, these fields will contain 8 bytes of 0xFF.

The counts in these fields are invalidated if a truncate-on-put is done, except if the truncate is to zero.

The utility ANALYZE/RMS_FILE has an /UPDATE_HEADER function that can be used to revalidate the counts in these fields.

If a SENSEMODE using this item code is requested for a non-ODS-5 file, the contents returned for each quadword will be 8 bytes of 0xFF. A SETMODE using this item code for a non-ODS-5 file will be ignored.

The file length hint is not supported for DECnet operations; it is ignored. If a SENSE is attempted, 8 bytes of 0xFF will be returned to the user buffer for each quadword.

	privacy and legal statement
4523PRO_015.HTML