Overview of Structure Alter Processing

Structure alter is a non-disruptive process to connectors to the structure being altered. The structure alter function requires the following combination of hardware and software support:

The structure alter function requires a coupling facility with CFLEVEL=1 or higher. You must add one or more coupling facilities with CFLEVEL=1 or higher to the structure's preference list in the CFRM policy. This enables XES to allocate the structure in a coupling facility that supports structure alter.
Note that event monitor controls are supported only for keyed list structures allocated in a coupling facility of CFLEVEL=3 or higher. For this type of structure:
- When allocated in a coupling facility of CFLEVEL=3, only the size and the entry-to-element ratio can be altered.
- When allocated in a coupling facility of CFLEVEL=4 or higher, the size, entry-to-element ratio, and the percentage of EMC storage can be altered.
The structure alter function requires that MVS™ SP 5.2 or higher be running on all systems on which applications plan to use the function. All connectors to the structure must have specified ALLOWALTER=YES on the IXLCONN macro.

Limiting the Scope of Structure Alter

Connectors that specify ALLOWALTER=YES have the ability to limit the changes that can be made to a structure during structure alter processing.

The RATIO keyword indicates whether the connector allows the entry-to-element ratio to be changed. Specifying RATIO=NO prevents changes to the entry-to-element ratio and also prevents the structure from being contracted to less than its minimum size. The entry-to-element ratio could change if the structure were reduced in size to less than its minimum.
The RATIO keyword also indicates whether the connector allows the percentage of EMC storage to be changed. Specifying RATIO=NO prevents changes to the percentage of EMC storage.

See Specifying the Structure Size for information about how the size of a structure is determined.
The MINENTRY and MINELEMENT keywords allow the connector to specify minimum threshold levels for entries and elements allocated in the structure. The MINEMC keyword allows the connector to specify the minimum threshold level of EMCs allocated in the structure. The values specified for MINENTRY, MINELEMENT, and MINEMC are percentage values, used by the system when a structure alter is initiated either to contract a structure or to reapportion the structure's ratio of entries to elements or its percentage of storage available for allocation of EMCs.
- The values specified for MINENTRY and MINELEMENT are percentage values of entries and elements that are to be available at the completion of structure alter processing — for a list structure, the percentage of “currently in-use” entries and elements and for a cache structure, the percentage of “currently in-use and changed” entries and elements. The connector thus is able to maintain a buffer of available entries and elements for subsequent use.
- The value specified for MINEMC is a percentage value of EMCs that are to be available at the completion of structure alter processing — for a keyed list structure, the percentage of “currently-in-use” EMCs. The connector thus is able to maintain a buffer of available EMCs for subsequent use.
If the reapportionment of the structure would decrease the amount of storage available for entries, elements, or EMCs, the MINENTRY, MINELEMENY, and MINEMC values are used to prevent the alter from making the structure unusable to the application. If the alter processing tries to contract or reapportion more free space than specified by these percentage values, the system stops the alter.

The system does not use the MINENTRY, MINELEMENT, or MINEMC values during requests to expand the structure or during reapportion requests that will increase the amount of storage available for the particular set of entries, elements, or EMCs.

Determining a Structure's Composite Values

Before performing a structure alter, XES determines “composite values” for a structure, based on structure attributes specified at connect time. The composite values provide a limit on how the system can alter the structure. Each connection can specify an ALLOWALTER, RATIO, MINENTRY, MINELEMENT, and MINEMC value, and each connection could specify different values. XES merges the values from each connection. XES determines the most restrictive requirements and uses these as the composite values to limit the changes to the structure for the structure alter request.

For instance:

If any connection specifies ALLOWALTER=NO, the alter request is rejected.
If any connection specifies RATIO=NO, a request to change the entry-to-element ratio or percentage of EMC storage is rejected.
For MINENTRY, MINELEMENT, and MINEMC values, the most restrictive value is the highest percentage of in-use elements that must be available upon completion of structure alter. Therefore, the highest percentage value set by any connection is used to limit the structure alter request.