Designing Your Application to Exploit the Coupling Facility

The process of designing your application to exploit a coupling facility involves the following tasks. If you plan to use more than one structure, you need to perform the tasks listed below for each structure.

Select the type of coupling facility structure that fits your application.
Study the attribute options for the structure and the functions provided by its associated sysplex services. These functions should include those provided by a particular coupling facility level (CFLEVEL).
Determine:
- The way your application will exploit the structure and its functions
- How you will organize your data in the structure
- The structure attributes you require
- The structure size you require.
Address issues such as serialization that relate to the shared use of the structure among multiple users. A coupling facility offers several ways to establish and maintain locking protocols for resources; these include actual locks as well as user-defined fields (such as the version number field in each list structure entry) that could be used to provide serialization.
Understand timing issues relating to asynchronous processing of multiple, concurrent requests.
Understand the events about which your application will be notified and decide how your application will respond to each event. When you connect to a structure, you provide the address of an event exit you have coded. Your event exit gets control from the system to receive information about an event. Events generally relate to a change in user, structure, or coupling facility status or to an error condition.
Understand the exits you must code for the structure you are planning to use and decide what processing they should perform when they receive control. Sysplex services rely heavily on application-provided exits, to allow decision-making for critical events to be tailored to the application. Exits can also be used to receive notification of asynchronous request completion.
Determine how your application will respond when a structure becomes full. The size of a structure in a coupling facility with CFLEVEL=1 or higher can be altered in its current location or the structure can be rebuilt with a larger size in another location.
Plan whether your application will support system-managed processes (for example, rebuild).
Plan how your application will monitor and control structure utilization, and how it will decide when to rebuild or change the size of the structure to increase capacity.
Plan how your application will implement peer recovery, restart recovery, or both, in the event of:
- User failure
- Connectivity failure
- Coupling facility structure failure.
For peer recovery, XES services notify peer users when a user fails. Peer users can perform recovery, clean up resources, and decide whether the failed user will be permitted to reconnect to the structure.

For restart recovery, XES services enable users to re-establish connection to a structure after a failure.
Document the following requirements in your application's installation instructions:
- The number and types of structures needed
- The structure sizes and attributes
- Whether the structures should be distributed across multiple coupling facilities, and if so, how they should be distributed. For optimum performance and availability, installations should spread coupling facility structures across multiple coupling facilities
- Whether any structures cannot share the same coupling facility, for capacity, performance or availability reasons. Make the necessary coupling facility resource management (CFRM) policy exclusion list recommendations for such structures.
- Whether any structures have CFLEVEL requirements. Make the necessary CFRM policy preference list recommendations for such structures.
- Whether the structure can be rebuilt or have its size altered.

The topics following this overview of sysplex services for data sharing are intended to help you to address these design considerations. However, certain design decisions are application-specific, so it is not always possible to recommend a particular approach or protocol.