Managing Cache Structure Utilization

The cache structure is allocated with a fixed amount of storage. This storage can be subdivided into directory entries and data elements. If an IXLCACHE request requires that an object be available but none is, a “structure-full” condition occurs. When the structure becomes full, you will no longer be able to perform a number of IXLCACHE functions. Affected functions could include:

The ability to create a new cache entry.
The ability to update an existing cache entry, regardless of whether its size would increase, decrease, or remain the same.

The system returns counts of the objects allocated in the structure in the connect answer area (IXLYCONA). The values reflect the state of the structure at the time of the connect.

CONACACHECHGDIRENTRYCOUNT — Approximate number of changed directory entries in use
CONACACHEDIRENTRYCOUNT — Approximate number of directory entries supported by the structure
CONACACHECHGDIRELEMENTCOUNT — Approximate number of changed data elements in use
CONACACHEMAXELEMENTCOUNT — Approximate maximum number of data elements supported by the structure.

Taking action to alleviate the storage problem before the structure becomes full is especially critical because the CONACACHEDIRENTRYCOUNT and CONACACHEMAXELEMENTCOUNT values are only approximate. As a result, you could receive a return code indicating that the structure is full even though the answer area counts of in-use entries or elements that are changed (and therefore cannot be reclaimed by the coupling facility) are below the limits indicated in the CONA.

A reason for the CONA counts being approximate is that the coupling facility at times uses some of the structure's objects for its own processing. Those objects are not included in your “in-use” counts.

Another result of the CONA counts being approximate is that the IXLCACHE request of one connector might be rejected due to a structure full condition while a subsequent request by a different connector might succeed. Alternatively, a request by a connector might be rejected while a subsequent request by the same connector might succeed. Furthermore, deleting a cache entry when the structure is full might not result in the immediate availability of the storage for the directory entry or data elements. As a result, your request could fail if you attempt to create an entry of the same size as the one you deleted.

Applications using the cache structure are responsible for managing structure utilization. The system does not prevent the structure from becoming full nor take any automatic action to remedy the condition. Therefore, IBM® recommends that you take steps to correct a storage shortage before your application is affected. To do so, you need to consider the following:

How to detect when the structure is becoming full
How full you will permit the structure to become before you take remedial action
How the storage shortage will be corrected.