Description

IXLCONN allows you to allocate and connect to a structure in the coupling facility or to connect to an already allocated structure. The first user to allocate the structure defines the structure attributes. Subsequent users can connect to the allocated structure but cannot change the structure attributes established when the structure was allocated. All connectors, whether the first or subsequent, are informed of the structure attributes through the connect answer area, mapped by IXLYCONA. It is the connector's responsibility to check the structure attributes to verify their acceptability.

Providing Structure Information
Structure attributes include a structure name (STRNAME), a structure disposition (STRDISP), and a structure type (TYPE).
- You identify the structure to which you want to connect by name (STRNAME). For connections to be successful, structure names must be defined in the active CFRM policy, and the system on which you are running must be able to access the CFRM couple data set that contains the active CFRM policy. The system on which you are running also must have connectivity to a coupling facility that is in the preference list of the structure, as defined in the active CFRM policy.
- STRDISP determines whether the structure remains allocated when all users have disconnected from the structure.
- TYPE indicates the kind of structure — a cache, list, or lock structure. You can specify one of these types on an IXLCONN request. A set of attributes specific to each structure type allows you to define structure characteristics (for example, the size of data entries for a cache or list, or the number of lock users).
Providing Connection Information
You also must specify certain information about the connection on IXLCONN, such as the connection disposition (CONDISP), an event exit (EVENTEXIT), and an answer area (ANSAREA) and length (ANSLEN).
- CONDISP determines whether a connection can enter a failed-persistent state which, in the event of a connection failure, would allow you to reconnect to the structure, if possible. Users can specify a connect name (CONNAME) on IXLCONN that they can use to reconnect to the structure if they fail, enter a failed-persistent state, and are subsequently restarted.
- EVENTEXIT specifies the name of the event exit. The event exit gets control whenever an event about the structure or a connection to the structure (such as a failure of the connection) occurs. The system reports an event to the event exit of each connected user. Users establish protocols to process these events.
- IXLCONN returns information about the structure and the connection in an area specified by ANSAREA. Included in this area is a connect token (CONTOKEN) that uniquely identifies the connection within the sysplex. After you have connected to a structure, you specify the CONTOKEN returned from IXLCONN on structure requests like IXLCACHE, IXLLIST, IXLLSTC, IXLLSTE, IXLLSTM, or IXLLOCK, as appropriate to the type of structure to which you've connected.
When initially connecting to a structure, you have the option of specifying how long SVC dump holds serialization for a structure when a dump for the connected structure occurs (ACCESSTIME). You also can specify the level of coupling facility that your application desires (CFLEVEL) as well as the minimum CFLEVEL required (MINCFLEVEL).
Providing Modification Information
Your connection can support rebuilding the structure (ALLOWREBLD) and altering the structure (ALLOWALTER). If the connection is to a cache structure, your connection might also support duplexing the structure (ALLOWDUPREBLD).
- Structure rebuild is a process intended for planned reconfiguration and recovery scenarios, in which connectors to a structure allocate another structure with the same name and rebuild data (if applicable) into the new structure.
- Structure alter is a process that allows a structure's size, entry-to-element ratio, and, if applicable, percent of structure storage allocated to event monitor controls to be changed. For changes to structure size and entry-to-element ratio, structure alter requires that the structure be allocated in a coupling facility with CFLEVEL=1 or higher. For event monitor control related changes, the list structure must be allocated in a coupling facility with CFLEVEL=3 or higher for a change in size and entry-to-element ratio, or in a coupling facility with CFLEVEL=4 or higher for a change to the percentage of event monitor controls, and the connector(s) must be running on a system with the appropriate level of system upgrades.
- Duplexing rebuild is a process that allows duplexing of a cache structure to be managed by the structure's connectors.
Starting with OS/390® Release 8, your connection can also support the use of system-managed processes (ALLOWAUTO). When a process is system-managed, the system (as opposed to the connectors) performs some, if not all, of the significant steps in the process. Release 8 provides system-managed rebuild processing. Its primary use is in a planned reconfiguration scenario, for example when moving structures from one coupling facility to another. Even when an application does not support user-managed rebuild (ALLOWREBLD=NO), system-managed rebuild can be used to accomplish the movement of the structures.

Starting with OS/390 Release 10, the installation can specify through its CFRM policy that system-initiated alter processing is requested for a structure. ALLOWAUTOALT(YES) in the CFRM policy indicates that when the structure reaches a specified percent-full threshold, the system is to automatically begin alter processing to relieve the structure storage shortage and also the reclaiming criterion.

IBM® recommends that connectors support the structure alter process (ALLOWALTER=YES) because it allows the installation to specify the automatic alter function for the structure. The system then can monitor and tune the structure size and ratios as needed, within the bounds provided by the installation.

IBM also recommends that connectors that support system-managed processes (ALLOWAUTO=YES) should also support the structure alter process (ALLOWALTER=YES). This gives the system the greatest flexibility in allocating new structures during system-managed processes and provides the other benefits that go along with structure alter in general.

The security administrator may have controlled the use of installation structures through the use of RACF® or another security product. If so, ensure that you are authorized to issue the IXLCONN macro for the structure.

For information about connection services, see z/OS MVS Programming: Sysplex Services Guide.