Cache Structure Allocation and Connection

Before each user can use the cache structure, the user needs to issue the IXLCONN macro to connect the user's instance or image of the application to the structure. When the first user connects to the cache structure, the system allocates resources for the structure and assigns structure characteristics. The coupling facility resource management (CFRM) policy defines the names of cache structures to the systems in the sysplex. The CFRM policy also defines, among other structure characteristics, the maximum amount of coupling facility storage that you can allocate to a structure.

Note: If the amount of storage requested for the structure is not available, the system allocates as much storage as is available and issues messages to indicate how much storage has been allocated.
When the user connects to a cache structure, the user identifies the structure by name. The name must be defined in the active CFRM policy. If a structure by that name is already allocated, the system connects the user to the structure. If the structure has not been allocated and the user wishes to allocate the structure, and if coupling facility resources are available, the system allocates coupling facility resources for the structure, connects the first user to the structure, and assigns attributes for the structure and the connection specified on the IXLCONN macro. Once a structure is defined, other users can connect to the structure.
  • Defining Structure and Connection Characteristics for Cache
    Characteristics that the user can specify on the IXLCONN macro for the structure include:
    • Structure disposition
    • Structure size
    • Amount of storage available for the directory and for data expressed as a ratio of directory entries-to-data elements
    • Maximum number of data elements per data entry and the data element size
    • Whether the structure supports adjunct areas
    • Maximum number of storage classes and cast-out classes available to the structure
    • Whether the structure supports user data field (UDF) queues for each cast-out class for the structure (requires CFLEVEL=5 or higher).
    • Whether the structure supports the logical grouping of name classes. Name classes can be used in conjunction with the NAMECLASSMASK specified on IXLCONN for more efficient use of some cache requests (requires CFLEVEL=7 or higher). See Using Name Classes in a Coupling Facility for additional information.

    Structure characteristics remain fixed for the life of the cache structure (that is, as long as the structure remains allocated.) Whenever a user connects to a previously existing cache structure, the user cannot change the structure characteristics. However, a user is able to change some of the structure characteristics by rebuilding or altering the structure. For information, see the IXLCONN and IXLREBLD macros.

    Characteristics that the user can specify on the IXLCONN macro for the connection to a cache structure include:
    • Connection name
    • Connection disposition
    • Size of the local cache vector
    • Start of changeCross-invalidation operation mode processing (synchronous or asynchronous) for local cache cross-invalidations generated by commands issued by the connectionEnd of change

    With the exception of the size of the local vector, connection characteristics remain fixed for the life of the connection (that is, as long as the user remains connected to the structure). Other users can connect to an existing structure and define their own connection characteristics. To change the vector size, users can issue the IXLVECTR at any time during the connection.

    For more information about defining a CFRM policy and about allocating and connecting to a cache structure, see:
  • Specifying the Appropriate CFLEVEL

    When you connect to a cache structure, you should be aware of your application's CFLEVEL requirements. Different levels of coupling facility control code (CFCC) support different coupling facility functions. For example, if your application is going to use the IXLALTER service to change the structure size, you should specify CFLEVEL=1 or higher on your IXLCONN invocation.

  • Defining the Local Cache Vector

    When you connect to a cache structure, one of the characteristics you specify is the length of the local cache vector. The local cache vector is a mechanism for determining if your locally cached data is valid. Each cache structure user must have a local cache vector allocated. The user of IXLCACHE services needs one vector entry for each local cache buffer. Or, put another way, the vector length needs to be the same as the maximum number of data items that you intend to have concurrently available in your private storage.

    The amount of storage available for local cache vectors is finite. Therefore, you need to define a vector length that is only as large as the length you actually need. If you need to change the storage for the vector (for example, at some point you might need to keep track of more or fewer data items), you can use the IXLVECTR macro to increase or decrease the size of the vector.

For More Information

For more information about local cache vectors and the IXLVECTR macro, see Maintaining Data Consistency. For information about the IXLVECTR macro keywords, see Using the IXLVECTR Macro.