![[Compaq]](../../images/hp.gif)
![[Go to the documentation home page]](../../images/buttons/hp_bn_site_home.gif)
![[How to order documentation]](../../images/buttons/hp_bn_order_docs.gif)
![[Help on this site]](../../images/buttons/hp_bn_site_help.gif)
![[How to contact us]](../../images/buttons/hp_bn_comments.gif)
![[OpenVMS documentation]](../../images/hp_ovmsdoc_sec_head.gif)
| Document revision date: 15 July 2002 | |
|
|
|
|
|
|
| Previous | Contents | Index |
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:
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.
| 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. |
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 );
.
.
.
|
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.
| 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 |
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:
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 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:
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.
| Field | Description |
|---|---|
| XAB$V_FILE_CONTENTS |
Can have one of the following values:
|
| XAB$V_FLUSH_ON_CLOSE | Must have the value XAB$K_FLUSH. 1 |
You can set the caching option by supplying a set mode XAB$_CACHING_OPTIONS XABITM when you do the following:
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.
12.10 POSIX-Compliant Access Dates (Alpha Only)
To support POSIX-compliant file timestamps on ODS--5 disks, file attributes have been extended to include the following three access dates:
The XABITM SENSEMODE interface can be used with the following item codes on $OPEN or $DISPLAY operations to sense each of these three access dates:
Sensing these dates requires that access date support be enabled on the ODS-5 volume. (See the DCL SET VOLUME/VOLUME_CHARACTERISTICS command in the OpenVMS DCL Dictionary: N--Z.)
A SETMODE can be used with a $CLOSE operation with any of these item codes to update these dates regardless of the volume setting. A user may inhibit the update of the access dates by using the XAB$_NORECORD XABITM.
Each of these item codes requires a quadword buffer.
If a SENSEMODE using any of these item codes is requested for a non-ODS--5 file, a zero is returned. A SETMODE using any of these item codes for a non-ODS--5 file will be ignored.
These items are ignored for DECnet operations. If a SENSEMODE is attempted for any of these items, the user buffer is left unchanged.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4523PRO_017.HTML | ||