Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

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.

## 12.9 Extended File Cache (XAB$_CACHE_OPTIONS) (Alpha Only)

The ODS-2 and ODS-5 volumes of the Files-11 file system can use a caching technique to improve performance. In using caching, the file system keeps a copy of data that it recently read from disk in an area of memory called a cache. When an application reads data, for example, the file system checks whether the data is in its cache. The file system only issues an I/O to read the data from disk if the data is not in the cache. Caching improves read performance, because reading data from cache memory is much faster than reading it from disk.

The extended file cache (XFC) is a virtual block cache, which caches both data and image files, and is available only on Alpha Systems. The extended file cache allows you to specify the following caching options:

- Write-through caching
- No caching

You can control the files that the Extended File Cache option caches by setting and showing the current caching option. This is described in the following section.

Setting and Showing the Current Caching Option

When you access a file, you can specify the caching option that you would like for the current process. If you want the file to be cached, select write-through caching. This is the default. The write-through cache allows an application to write data to a file and straight through to disk. When this occurs, the application waits until the disk I/O is done and the data is on the disk.

The current caching option is stored in the XAB$_CACHING_OPTIONS XABITM, which has the following structure.

Table 12-6 shows the fields and gives a description of XAB$_CACHING_OPTIONS XABITM.

Table 12-6 XAB$_CACHING_OPTIONS XABITM
Field | Description
--- | ---
XAB$V_FILE_CONTENTS | Can have one of the following values: XAB$K_NOCACHING XAB$K_WRITETHROUGH
XAB$V_FLUSH_ON_CLOSE | Must have the value XAB$K_FLUSH. 1

1Note that this must be set. It is required for future enhancements.

You can set the caching option by supplying a set mode XAB$_CACHING_OPTIONS XABITM when you do the following:

- When you create a file using SYS$CREATE
- When you open an existing file using SYS$OPEN

If you do not supply a XABITM or, if you supply a XABITM whose value is zero (0), the file system uses the value in the file's caching attribute.

If another process on your computer is accessing the file, and you ask for write-through caching, your request is ignored if the file's current caching option is no caching. When more than one process is accessing a file on a single node, the most restrictive caching option takes effect on that node. Write-through caching is least restrictive; no caching is most restrictive.

When more than one node in an OpenVMS Cluster is accessing a file, its caching option may be different on different nodes. It may be write-through on one node and no caching on another.

To show the caching option, supply a sense mode XABITM on a call to SYS$DISPLAY.

Previous | Next | Contents | Index

| privacy and legal statement |
4523PRO_016.HTML