Document revision date: 30 March 2001

Use the INSTALL command LIST to display information about known images.

The information displayed with the /FULL qualifier of the LIST command can help you determine if installing an image is worth the expense.

How to Perform This Task

1. Invoke INSTALL by entering the following command:

   $ INSTALL

2. To display a list of all known images and their attributes, enter the LIST command. To display attributes for a specific image, specify the name of the image as follows:

   LIST file-spec

   
   For example:

   INSTALL> LIST LOGINOUT

3. To display complete information about a specific image, including the number of accesses, the number of concurrent accesses, and the number of global sections created, specify the /FULL qualifier as follows:

   LIST/FULL file-spec

Example

The following example displays complete information about the installed image LOGINOUT.EXE, including the number of accesses, the number of concurrent accesses, and the number of global sections created:

$ INSTALL INSTALL> LIST/FULL LOGINOUT DISK$VMS551:<SYS2.SYSCOMMON.SYSEXE>.EXE LOGINOUT;2 Open Hdr Shar Prv Entry access count = 36366 Current / Maximum shared = 1 / 10 Global section count = 3 Privileges = CMKRNL SYSNAM LOG_IO ALTPRI TMPMBX SYSPRV INSTALL>

17.9.13 Defining Logical Names for Shareable Image Files

If a shareable image is not located in SYS$SHARE, you must define a logical name for that image in order to run an executable image linked against it. For example, if the file specification for STATSHR is SYS$SHARE:STATSHR.EXE, no logical name is necessary. But if you put STATSHR in SYS$DEVICE:[TEST], you must define STATSHR as a logical name before running an executable image that calls it. The logical name must be the same one that was used as the input file specification for the shareable image when it was linked (this is the same name used in installation). For example:

$ DEFINE STATSHR SYS$SYSDEVICE:[TEST]STATSHR

By redefining the logical name of a shareable image, you can replace that shareable image with another without requiring the calling executable image to relink. For example, the following statement redefines the file name STATSHR. It becomes the logical name of the shareable image SYS$SYSDEVICE:[MAIN]STATSHR.EXE for executable images calling STATSHR.

$ DEFINE STATSHR SYS$SYSDEVICE:[MAIN]STATSHR

The INSTALL command REMOVE removes a known file entry for an image and deletes any global sections created when the image was installed. Note that a volume cannot be dismounted while any known file entries are associated with it. To dismount a volume, you must delete all known images associated with it. You must also wait for all processes using those images to exit. Use the DCL command SHOW DEVICES/FILES to determine the status of the files.

For more information about the INSTALL command DELETE, refer to the INSTALL section of the OpenVMS System Management Utilities Reference Manual.

This chapter describes how to manage the Extended File Cache (XFC) (Alpha only) and the Virtual I/O Cache (VIOC). These are the caches that the Files-11 file system uses to cache data for ODS-2 and ODS-5 volumes.

Information Provided in This Chapter

This chapter describes the following tasks:

Task	Section
Disabling caching clusterwide	Section 18.3
Mounting a volume with caching disabled	Section 18.4
Managing the Extended File Cache (Alpha Only)	Section 18.5
Managing the Virtual I/O Cache	Section 18.6

This chapter explains the following concepts:

Concept	Section
Caching	Section 18.1
File system data caches	Section 18.2

18.1 Understanding Caching

The Files-11 file system uses a technique called caching to improve performance. It keeps a copy of data that it has recently read from disk or written to disk in an area of memory called a cache.

When an application reads data, the file system checks whether the data is in its cache. It issues an I/O to read the data from disk only if the data is not in the cache.

Caching improves read performance. Reading data from memory (from the cache) is much faster than reading it from disk.

There are several levels of caching in both the hardware I/O subsystem and in OpenVMS. In general, more levels of caching result in better response time in accessing data.

18.2 Understanding File System Data Caches

For ODS-2 and ODS-5 volumes, the Files-11 file system has several caches. It has metadata caches for file metadata such as file headers, and a data cache for file data. It can use one of two system-wide data caches, as follows:

File System Data Cache	Description
Virtual I/O Cache (VIOC)	This is the original data cache, and is available on VAX and Alpha.
Extended File Cache (XFC)	This data cache is available on OpenVMS Alpha Version 7.3 and later, and is available only on OpenVMS Alpha. It provides better performance and more capability than VIOC. XFC is the default cache on OpenVMS Alpha Version 7.3 and later.

This chapter describes how to manage the data caches. For information on managing the metadata caches, see the OpenVMS Performance Management. Note that RMS makes use of local and global buffers that can perform data caching. By default, this caching is not enabled. You can manipulate the RMS local and global buffers to affect I/O performance. For information on managing the RMS local and global buffers, see the Guide to OpenVMS File Applications. Note also that the modified page list is a type of cache; that is, if a process references a page that is on the modified page list, the page is placed back into the working set of the process and is not output to disk.

Both XFC and VIOC are virtual block caches that maintain consistent data within an OpenVMS Cluster. They cache both data files and image files. The data caches are write-through caches; when an application writes data to a file, the data is written straight through to disk. The application has to wait until the disk I/O completes and the data is on disk.

In an OpenVMS Cluster, different nodes can use different data caches. This allows mixed architecture clusters to benefit from XFC. OpenVMS Alpha nodes can use either XFC or VIOC. OpenVMS VAX nodes can use only VIOC, as described in Section 18.5.6.

XFC improves I/O performance and contains the following features that are not available with VIOC:

• Read-ahead caching
• Automatic resizing of the cache
• Larger maximum cache size
• No limit on the number of closed files that can be cached
• Control over the maximum size of I/O that can be cached
• Control over whether cache memory is static or dynamic

At system startup, the value of a static system parameter controls whether the file system uses a data cache, and if so, which data cache it uses (XFC or VIOC). The system parameter depends on the operating system, as shown in the following table:

Operating System	System Parameter	Enabled	Disabled
OpenVMS Alpha	VCC_FLAGS	1 or 2 (default) +	0
OpenVMS VAX	VBN_CACHE_S	1 (default)	0

In an OpenVMS Cluster, if file system data caching is disabled on one node, it is disabled throughout the cluster. The other nodes in the cluster cannot use XFC or VIOC until that node leaves the cluster or reboots with VCC_FLAGS or VBN_CACHE_S set to a non-zero value. You can use the DCL command SHOW MEMORY to determine whether caching is enabled.

To disable caching clusterwide, follow these steps on any node in your OpenVMS Cluster:

1. Set the appropriate system parameter (VCC_FLAGS or VBN_CACHE_S) to 0, using MODPARAMS.DAT.
2. Run AUTOGEN to ensure that other system parameters allow for the new value. This is not essential, but it is advisable.
3. Reboot the system to make the new value effective.

To prevent the file system from caching data on a particular volume, such as a database volume, use the MOUNT /NOCACHE command to mount the volume with caching disabled.

If you are using XFC in an OpenVMS Cluster, mounting a volume /NOCACHE is easier than using SET FILE /CACHING_ATTRIBUTE to set the caching attribute of all the files in the volume to no caching (see Section 18.5.3). Using MOUNT /NOCACHE ensures the minimum caching overhead. Note that the MOUNT/NOCACHE command also disables XQP caching.

Example

This example mounts a database volume labeled ORACLE_VOL1 with caching disabled:

$ MOUNT DUA100: ORACLE_VOL1 /NOCACHE /SYSTEM

18.5 Managing XFC (Alpha Only)

This section describes how to manage XFC, which is available only on OpenVMS Alpha. It describes the following tasks.

Task	Section
Controlling the size of the cache	Section 18.5.1
Controlling the maximum cached I/O size	Section 18.5.2
Disabling caching for a file	Section 18.5.3
Disabling read-ahead caching	Section 18.5.4
Monitoring performance	Section 18.5.5
Using in a mixed architecture OpenVMS Cluster	Section 18.5.6

18.5.1 Controlling the Size of the Cache

This section describes how to control the minimum and maximum size of XFC

XFC is held in virtual memory in S2 space and automatically shrinks and grows, depending on your I/O workload and how much spare memory is available on your system. S2 space is a 64-bit address space, so the cache can grow to very large sizes when required.

As your I/O workload increases, the cache automatically grows, but never to more than the maximum size. And when your applications need memory, the cache automatically shrinks, but never to less than the minimum size.

18.5.1.1 Controlling the Minimum Cache Size

The minimum size of XFC is controlled by the value of the VCC$MIN_CACHE_SIZE entry in the reserved memory registry. VCC$MIN_CACHE_SIZE specifies the amount of memory in megabytes (MB) that is allocated to XFC at system startup. The cache never shrinks below this size. This memory is never released.

Checking the Minimum Size

To check the minimum size of XFC, use the Sysman utility command SHOW MEMORY /RESERVED. For example:

$ SHOW MEMORY /RESERVED System Memory Resources on 11-MAY-2000 15:50:25.64 Memory Reservations (pages): Group Reserved In Use Type VCC$MIN_CACHE_SIZE --- 1536 1536 Allocated Total (400.00 Mb reserved) 1536 1536

Setting a Minimum Size

By default, the reserved memory registry does not contain an entry for VCC$MIN_CACHE_SIZE, so no memory is allocated to XFC at system startup. However, XFC allocates a small amount of memory to maintain overall system throughput. The amount of memory allocated varies according to the size of your machine.

To set a minimum size, follow these steps:

1. Use the Sysman utility's RESERVED_MEMORY ADD command to add an entry for VCC$MIN_CACHE_SIZE. For example, to set the minimum size to 300MB:

   $ RUN SYS$SYSTEM:SYSMAN SYSMAN> RESERVED_MEMORY ADD VCC$MIN_CACHE_SIZE /SIZE=300 /ALLOCATE - _SYSMAN> /NOGLOBAL_SECTION /NOZERO /NOPAGE_TABLE

   
   You must use all the qualifiers shown in this example. For best performance, set the minimum size to a multiple of 4MB.
   Note that if you are doing this on a NUMA type machine, where you want to allocate reserved memory in different RADs, you may choose to use the following commands (rather than those above) to set the minimum size:

   $ RUN SYS$SYSTEM:SYSMAN SYSMAN> RESERVED_MEMORY ADD VCC$MIN_CACHE_SIZE /SIZE=300 /ALLOCATE - _SYSMAN> /NOGLOBAL_SECTION /NOZERO /NOPAGE_TABLE/RAD=0 SYSMAN> RESERVED_MEMORY EXTEND VCC$MIN_CACHE_SIZE /SIZE=500 /ALLOCATE - _SYSMAN> /NOGLOBAL_SECTION /NOZERO /NOPAGE_TABLE/RAD=1

2. Run AUTOGEN to ensure that other system parameters allow for the new value. This is not essential, but it is advisable.
3. Reboot the system to make the new value effective.
   During startup, if the system does not have enough memory to allocate the specified minimum size, no memory is allocated to XFC and its minimum size is set to 0MB.

Changing the Minimum Size

To change the minimum size of XFC, follow these steps:

1. Use the Sysman utility's RESERVED_MEMORY MODIFY command to modify the existing entry for VCC$MIN_CACHE_SIZE. For example, to change the minimum size to 360MB:

   $ RUN SYS$SYSTEM:SYSMAN SYSMAN> RESERVED_MEMORY MODIFY VCC$MIN_CACHE_SIZE /SIZE=360 /ALLOCATE - _SYSMAN> /NOGLOBAL_SECTION /NOZERO

   
   You must use all the qualifiers shown in this example. For best performance, remember to set the minimum size to a multiple of 4MB.

2. Run AUTOGEN to ensure that other system parameters allow for the new value. This is not essential, but it is advisable.
3. Reboot the system to make the new value effective.
   During startup, if the system does not have enough memory to allocate the specified minimum size, no memory is allocated to XFC and its minimum size is set to 0MB.

To control the maximum size of XFC, use the dynamic system parameter VCC_MAX_CACHE. It specifies the size in megabytes.

By default, VCC_MAX_CACHE is --1, which means that at system startup, the maximum size of XFC is set to 50 percent of the physical memory on the system. For example, if the system has 2GB of physical memory, its maximum size is set to 1GB.

Note that the maximum size specified by VCC_MAX_CACHE does not include the memory that XFC consumes indirectly via the OpenVMS lock manager.

The value of VCC_MAX_CACHE at system startup sets an upper limit for the maximum size of XFC. You cannot increase the maximum size beyond that value.

For example, VCC_MAX_CACHE is 60 at system startup, so the maximum size is initially set to 60MB. You then set VCC_MAX_CACHE to 40, which decreases the maximum size to 40MB. If XFC is bigger than 40MB, it gradually shrinks to 40MB. You then set VCC_MAX_CACHE to 80, but the maximum size is only increased to 60MB, the value set at system startup. You cannot increase the maximum size beyond the value set at system startup.

If VCC_MAX_CACHE is less than the minimum size specified by the value of the VCC$MIN_CACHE_SIZE entry in the reserved memory registry, then during system startup, VCC_MAX_CACHE is ignored and the maximum size of XFC is set to the same value as the minimum size. In this case, XFC has a fixed size and cannot shrink or grow.

Example

This example changes the maximum size of XFC to 50MB:

$ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE CURRENT SYSGEN> SET VCC_MAX_CACHE 50 SYSGEN> WRITE ACTIVE

18.5.1.3 Enabling a Static Cache Size

On larger machines, XFC may be somewhat limited by the default size of the modified page list. In general, the modified page list can be considered a 1 to 1 correspondence data cache. XFC is a many to one cache; that is, in general, a cached page is accessed by many users. On large memory systems, AUTOGEN usually sets MPW_HILIMIT to a very large value. This may mean that there are not enough free pages for the memory management subsystem to give to XFC.

You can force XFC to have a minimum number of pages as specified in Setting a Minimum Size. You can also permanently allocate memory just for XFC, which prevents any overhead caused by the dynamic allocation and deallocation routines (similar in operation to VIOC). To do this, set system parameter VCC_MAX_CACHE to be equal to the memory reservation specified by VCC$MIN_CACHE_SIZE.

For example, if your system has 128GB of memory, you may find that by dedicating 8GB of memory to XFC, your cache hit rates and overall response time is consistently good. For example:

$ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE CURRENT SYSGEN> SET VCC_MAX_CACHE 8000 SYSGEN> WRITE ACTIVE $ RUN SYS$SYSTEM:SYSMAN SYSMAN> RESERVED_MEMORY ADD VCC$MIN_CACHE_SIZE /SIZE=8000 /ALLOCATE - _SYSMAN> /NOGLOBAL_SECTION /NOZERO /NOPAGE_TABLE/RAD=0

18.5.2 Controlling the Maximum Cached I/O Size

The dynamic system parameter VCC_MAX_IO_SIZE controls the maximum size of I/O that can be cached by XFC. This parameter specifies the size in blocks. By default, it is 128.

Example

This example changes the maximum size of I/O that can be cached by XFC to 1,000 blocks:

$ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE CURRENT SYSGEN> SET VCC_MAX_IO_SIZE 1000 SYSGEN> WRITE ACTIVE

This series of commands affects I/Os to volumes currently mounted on the local node, as well as to volumes mounted in the future. After you enter these commands, XFC does not cache I/Os that are bigger than 1,000 blocks. The SHOW MEMORY /CACHE /FULL command provides a histogram of I/O sizes that can provide guidelines for efficient parameter setting.

18.5.3 Disabling Caching for a File

To prevent XFC to from caching a particular file, such as a database file, set the caching attribute of the file to no caching.

The caching attribute of a file is the default caching option that is used by XFC when an application accesses the file without specifying which caching option it wants to use. The caching option can be either write-through caching or no caching.

If you want a file to be cached, set its caching attribute to write-through (the default). If you don't want a file to be cached, set its caching attribute to no caching.

Use...	To...
SET FILE /CACHING_ATTRIBUTE=keyword +	Set the caching attribute of a file or directory
DIRECTORY /CACHING_ATTRIBUTE or DIRECTORY /FULL	Show the caching attribute of a file or directory
DIRECTORY /SELECT=CACHING_ATTRIBUTE=(keyword[,...]) +	Show all the files and directories that have a particular caching attribute

XFC does not cache directories. The caching attribute of a directory controls only how the caching attribute is inherited by new files and subdirectories created in the directory:

• When you create a new directory or file, it inherits its caching attribute from its parent directory.
• When you create a new version of an existing file, the new file inherits its caching attribute from the highest version of the existing file.

Examples

• This example sets the caching attribute to no caching for all the files in and under the directory [SMITH.BORING].
  The first SET FILE command sets the attribute for the directory to make sure that all files and subdirectories subsequently created in it inherit the attribute. The second SET FILE command sets the attribute for all existing files and directories in and under the directory.

  $ SET FILE DISK$USERS:[SMITH]BORING.DIR;1 /CACHING_ATTRIBUTE=NO_CACHING $ SET FILE DISK$USERS:[SMITH.BORING...]*.*;* /CACHING_ATTRIBUTE=NO_CACHING

• This example uses the DIRECTORY command's /CACHING_ATTRIBUTE qualifier to show the caching attribute of MYFILE.TXT:

  $ DIRECTORY MYFILE.TXT /CACHING_ATTRIBUTE Directory DISK$USERS:[SMITH] MYFILE.TXT;1 Write-through Total of 1 file.

• This example shows all the files in the volume DISK$USERS that have a caching attribute of no caching.

  $ DIRECTORY DISK$USERS:[000000...]*.* /SELECT=CACHING_ATTRIBUTE=NO_CACHING

	privacy and legal statement
6017PRO_077.HTML