Description

The IXLALTER service allows an authorized program, not necessarily a connected user of a structure, to start or stop the structure alter process. Structure alter is a non-disruptive process to expand or contract the size of a structure, to reapportion the structure's entry-to-element ratio, and to change the percentage of structure storage that is set aside for event monitor controls (EMCs).

The structure to be altered must be allocated in a coupling facility that supports structure alter, that is, a coupling facility with CFLEVEL=1 or higher. For keyed list structures containing EMCs in a coupling facility with CFLEVEL=3, you can alter the size or the entry-to-element ratio of the structure, but the EMC storage percentage will not change. For keyed list structures containing EMCs in a coupling facility with CFLEVEL=4 or higher, you can also alter the EMC storage percentage.

A structure alter can be done only if all connectors to the structure allow structure alter (indicated by specifying ALLOWALTER=YES on IXLCONN). At connect time, connectors can also specify whether changing the entry-to-element ratio and EMC storage percentage is permitted (RATIO=YES or NO). If a change is permitted, the connector can also indicate the minimum threshold levels for entries, elements, and EMC storage (MINENTRY, MINELEMENT, MINEMC). These minimum threshold levels indicate the percent of entries, elements, and EMC storage that must be available when the structure alter completes.

MINENTRY and MINELEMENT
For list structures, this is the percent of “in-use” entries and/or elements; for cache structures, this is the percent of “in-use and changed” entries and/or elements.
MINEMC
For keyed list structures in a coupling facility with CFLEVEL=4 or higher, this is the percent of “currently-in-use” EMCs.

A structure alter request will not be accepted for:

A structure that is already in the rebuild or alter process.
A structure that is in a user-managed or system-managed duplexing rebuild but not in the Duplex Established phase.
A structure that has structure objects in storage-class memory or has augmented space other than fixed augmented space in use.

If a structure is in user-managed duplexing rebuild processing, the alter is automatically applied to both structure instances serially. The primary (old) structure is altered first, with corresponding Alter Begin and Alter End events. After the Alter End is delivered for the primary structure, alter begins for the secondary (new) structure, also with its corresponding Alter Begin and Alter End events. The alter events indicate which of the structures is currently being altered. The system will not allow you to start a subsequent alter request for the structure until both instances of the structure have completed the current alter process.

If a structure is in system-managed duplexing rebuild processing, the alter is applied to both structure instances serially, with the primary (old) structure being altered first followed by the alter of the secondary (new) structure. However, only one set of Alter Begin and Alter End events are delivered. The Alter Begin event is delivered at the start of alter processing for the primary structure; the Alter End event is delivered at the end of alter processing for both instances of the structure.

Alter processing ends when:

The target size, ratio, or EMC storage percentage is satisfied, either completely or to the extent possible based on available coupling facility resources. (When no more progress can be made toward attaining requested targets, IXLALTER processing ends.)
A stop alter request is received (either a SETXCF command or an IXLALTER request to stop the alter). This does not apply to structures in the Duplex Established phase of a system-managed duplexing rebuild. While an alter of a structure in the Duplex Established phase of system-managed duplexing rebuild is in progress, the system will reject an attempt to stop the alter with either message IXC531I (for SETXCF) or return code IXLRSNCODEDUPALTER (for IXLALTER).
A structure or coupling facility failure occurs. If the SP 5.2 or higher systems in the sysplex all fail or lose connectivity to the coupling facility in which the structure resides, alter processing ends when the first SP 5.2 or higher system regains connectivity to the coupling facility.
A structure rebuild request is received, except when the alter processing is for a structure in the Duplex Established phase of user-managed or system-managed duplexing rebuild. In that case, the system does not accept the structure rebuild request, and the alter processing continues.
A request to stop duplexing rebuild is received while the structure is being altered in the Duplex Established phase. Alter processing depends on which structure instance is to be kept and which is being deallocated, and on the amount of alter processing that has been performed or remains to be performed. If the alter of the duplexed structure has already completely processed the structure that is to be kept in simplex mode, then the alter processing is finished and the system issues the Alter End event. If there is still alter processing either in progress against, or not yet performed against, the structure that is to be kept, then the alter processing continues against the simplex structure after duplexing is switched or stopped. When that alter processing against the simplex structure completes, the system issues the Alter End event.
The coupling facility migrates structure objects into storage-class memory.

When the alter processing is complete, all active connectors are notified of the completion through their event exit.

The security administrator may be using RACF® or another security product to restrict the use of installation coupling facility structures. If so, ensure that you are authorized to issue the IXLALTER macro for the structure.