Handling a Connection's Abnormal Termination

The topics below describe how the system handles the following types of connection termination.

Connector's system terminates
Connector's address space terminates
Connector's task terminates
An address space other than the connector's address space terminates with outstanding IXLCACHE, IXLLIST, or IXLRT operations. (The connector remains active.)
A task other than the connector's task terminates with outstanding IXLCACHE, IXLLIST, or IXLRT operations. (The connector remains active.)

Note:

The connector that requests XES services must provide abnormal termination processing for a connection by establishing end-of-task (EOT)/end-of-memory (EOM) resource managers. XES assumes that the connector is the owner of any storage passed to an XES service, specifically IXLCACHE, IXLLIST, and IXLRT.
If the connector is not the owner of the storage passed to XES, then the connector must provide an address space termination resource manager for handling cases where the owner of the storage terminates. The address space termination resource manager must invoke IXLPURGE to break any XES-established storage binds before allowing the storage to be cleaned up.
When a recovery exit receives control while its subsystem or system component is suspended by an IXLLIST, IXLCACHE, IXLRT, or IXLFCOMP request, the recovery exit must issue IXLPURGE to complete or purge the request. The recovery exit must do this prior to deleting any storage passed as input to XES and prior to looking at the answer area to determine the status of the request.
In certain instances, XES must quiesce the activity of user exits in order to perform cleanup processing. For example, when a user disconnects or abnormally terminates, XES will force to completion any user exits executing on behalf of that user by issuing a PURGEDQ against the appropriate units of work. Note that if a connector terminates while a rebuild is in progress, any exits pertaining to both the original and the new structures will be forced to completion. In addition to forcing the currently executing user exits to completion, XES will also prevent any new invocations of these exits by cancelling any events that are pending presentation.
A user exit must be sensitive to conditions that can occur as a result of actions taken by XES and must be able to handle these as appropriate. For example, if a user exit has suspended itself, when the PURGEDQ is issued the system abends the user exit's unit of work with a retryable X'47B' abend and gives control to the user exit's recovery routine. (Note that although the recovery routine can retry, the user exit can not re-suspend itself because the system will fail any request to suspend a unit of work that has been the target of a PURGEDQ.) If the recovery routine percolates back to the system, its associated connection is terminated.

Case 1. Connector's System Terminates

When a connector's system terminates, another system in the sysplex performs the clean-up processing.

The system notifies all peer connections through the Disconnected or Failed connection event that is presented to each peer connector's event exit.
All peer connections must respond to the Disconnected or Failed Connection event. When the system has received all event exit responses, the connection is placed in either the undefined state or the failed-persistent state.
- Undefined state
  1) The failed connection specified CONDISP=DELETE on the connection, or
  
  2) The failed connection specified CONDISP=KEEP on the connection and at least one peer connection responded that the connection should be released.
- Failed-persistent state
  The failed connection specified CONDISP=KEEP on the connection and all peer connections responded that the connection should not be released.
The system disconnects all connections owned by the terminated system when all responses are received. For each connection, the system must clean up all structure-specific resources, such as castout locks and registered interest for a cache structure. See Handling Resources for a Disconnection for a list of resources that are cleaned up when the failed connection is detached from the coupling facility structure.
At this point, the structure might be deallocated if the structure has a STRDISP of DELETE and there are no more defined connections.

Case 2. Connector's Address Space Terminates

When a connector's address space terminates, the connector's end-of-memory resource manager receives control in the master address space. The resource manager must perform storage clean-up before turning control over to the XES resource manager for additional processing.

Connector Resource Manager Processing
The EOM resource manager must clean up all storage associated with outstanding coupling facility requests, specifically the storage buffers associated with IXLCACHE, IXLLIST, and IXLRT. Note that no input storage buffers are provided for IXLLOCK. Use the IXLPURGE service to purge the outstanding requests and ensure that there are no XES-established binds to the storage associated with the request. At the completion of IXLPURGE processing, control returns to the end-of-memory resource manager with all storage binds broken. Processing after invoking IXLPURGE differs according to whether the request was asynchronous or synchronous.
- Asynchronous request
  Request-related storage can be released without waiting for notification of request completion. Because the connector's address space is terminated, request completion notification cannot be scheduled.
- Suspended Synchronous request
  The following processing normally occurs for an IXLLIST, IXLCACHE, or IXLRT request:
  - The answer area is initialized with IxlRsnCodeUnknown reason code prior to performing the request.
  - The answer area is updated with the request results when the request is completed. The answer area is updated while running under the requestor's unit of work with addressability from the connector's and requestor's address spaces.
  Request-related storage for requests initiated with the home address space equal to the connector's address space can be released without waiting for notification of request completion. The requestor can no longer run.
  
  Request-related storage for requests initiated with the home address space not equal to the connector's address space are handled by the recovery routine of the requestor. If the connector's address space has terminated, the requestor can observe the IxlRsnCodeUnknown reason code in the answer area. However, if the answer area storage is in the connector's address space, the answer area will not be addressable. For the answer area to be addressable during termination processing when a connector's address space terminates, the answer area storage must be in common storage.
XES Resource Manager Processing
At the completion of processing by the connector's resource manager, the XES resource manager continues the clean-up processing.
- XES invokes IXLPURGE to release any additional storage binds. XES uses the STOKEN of the terminating address space as input to IXLPURGE.
- XES notifies all peer connections about the termination by invoking their event exits with the Disconnection or Failed connection event.
- All peer connections must respond to the Disconnected or Failed Connection event. When the system has received all event exit responses, the connection is placed in either the undefined state or the failed-persistent state.
  - Undefined state
    1) The failed connection specified CONDISP=DELETE on the connection, or 2) The failed connection specified CONDISP=KEEP on the connection and at least one peer connection responded that the connection should be released.
  - Failed-persistent state
    The failed connection specified CONDISP=KEEP on the connection and all peer connections responded that the connection should not be released.
- XES disconnects a connection owned by the terminating address space from the structure when all responses are received. For each connection, all structure-specific resources such as local vectors, castout locks, etc. are cleaned up. See Handling Resources for a Disconnection for resources associated with each structure type.
- At this point, the structure might be deallocated if the structure has a STRDISP of DELETE and there are no more defined connections.

Case 3. Connector's Task Terminates

When a connector's task terminates, the connector's end-of-task resource manager receives control running under the failing task. The resource manager must perform storage clean-up before turning control over to the XES resource manager for additional processing.

Connector Resource Manager Processing
The connector's end-of-task resource manager must clean up all storage associated with outstanding coupling facility requests, specifically the storage buffers associated with IXLCACHE, IXLLIST, and IXLRT. Note that no input storage buffers are provided for IXLLOCK. Use the IXLPURGE service to purge the outstanding requests and ensure that there are no XES-established binds to the storage associated with the request. At the completion of IXLPURGE processing, control returns to the end-of-task resource manager with all storage binds broken. IXLPURGE processing differs according to whether the request was asynchronous or synchronous.
- Asynchronous request
  Request-related storage cannot be deleted until the connector is notified about each request's completion. The connection is still active and therefore, request completion notification will be scheduled normally (either through posting an ECB or driving the complete exit). Issue IXLFCOMP to obtain the results of asynchronous request tokens. If necessary, invoke IXLFCOMP before invoking IXLPURGE.
- Suspended Synchronous request
  The requestor's recovery routine receives control for a suspended request running under the connector's task. Prior to this, the XES recovery routine received control and attempted to complete the request. The request recovery routine must issue IXLPURGE to ensure that the request is complete.
  
  The system resumes a suspended request associated with a task other than the connector's task and returns a return code that indicates whether the request was purged or completed. The system resumes the suspended task whether the suspended task's home address space is equal to the connector's address space or not.
XES Resource Manager Processing
At the completion of processing by the connector's resource manager, the XES resource manager continues the clean-up processing.
- XES invokes IXLPURGE to release any additional storage binds. XES uses the TTOKEN of the terminating task as input to IXLPURGE.
- XES notifies all peer connections about the termination by invoking their event exits with the Disconnection or Failed connection event.
- All peer connections must respond to the Disconnected or Failed connection event. When the system has received all event exit responses, the connection is placed in either the undefined state or the failed-persistent state.
  - Undefined state
    1) The failed connection specified CONDISP=DELETE on the connection, or 2) The failed connection specified CONDISP=KEEP on the connection and at least one peer connection responded that the connection should be released.
  - Failed-persistent state
    The failed connection specified CONDISP=KEEP on the connection and all peer connections responded that the connection should not be released.
- XES disconnects a connection owned by the terminating task from the structure when all responses are received. For each connection, all structure-specific resources such as local vectors, castout locks, etc. are cleaned up. See Handling Resources for a Disconnection for resources associated with each structure type.
- At this point, the structure might be deallocated if the structure has a STRDISP of DELETE and there are no more defined connections.

Case 4. An Address Space Other Than the Connector's Address Space Terminates with Outstanding IXLCACHE, IXLLIST, or IXLRT Operations. The connection remains active.

When an address space other than the connector's terminates, the connector's end-of-memory resource manager receives control in the master address space. The resource manager must perform storage clean-up before turning control over to the XES resource manager for additional processing.

Connector Resource Manager Processing
The connector's end-of-memory resource manager must clean up all storage associated with outstanding coupling facility requests, specifically the storage buffers associated with IXLCACHE, IXLLIST, and IXLRT. Note that no input storage buffers are provided for IXLLOCK. Use the IXLPURGE service to purge the outstanding requests and ensure that there are no XES-established binds to the storage associated with the request. At the completion of IXLPURGE processing, control returns to the end-of-memory resource manager with all storage binds broken. IXLPURGE processing differs according to whether the request was asynchronous or synchronous.
- Asynchronous request
  When IXLPURGE completes, the complete exit and ECB notifications complete normally for asynchronous requests. Issue IXLFCOMP to obtain the results of asynchronous token requests. Once IXLPURGE completes, the system does not suspend an IXLFCOMP request because the outstanding request has already been purged and therefore is complete. Request-related storage cannot be deleted until all processing for the request has been completed.
  
  Note: In order to issue IXLFCOMP, the requestor must be running with the primary address space equal to the connector's primary address space and have the same addressability as when the asynchronous request was initially issued.
- Suspended synchronous request
  For IXLLIST, IXLCACHE, and IXLRT requests, XES initializes the answer area mapped by the appropriate macro, IXLYLAA, IXLYCAA, or IXLYRTAA, with the IxlRsnCodeUnknown reason code prior to performing the request. When the request completes, XES updates the answer area with the request results, while running under the requestor's unit of work and with addressability to the connector's and the requestor's address spaces. If the requestor's address space has terminated, the requestor observes the IxlRsnCodeUnknown reason code in the answer area.
XES Resource Manager Processing
At the completion of processing by the connector's resource manager, the XES resource manager continues the clean-up processing.
- XES invokes IXLPURGE to release any additional storage binds. XES uses the STOKEN of the terminating address space as input to IXLPURGE.

Case 5. A Task Other Than the Connector's Task Terminates with Outstanding IXLCACHE, IXLLIST, or IXLRT Operations. The connection remains active.

When a task other than the connector's task terminates, the connector's end-of-task resource manager receives control running under the failing task. The resource manager must perform storage clean-up before turning control over to the XES resource manager for additional processing.

Connector Resource Manager Processing
The connector's end-of-task resource manager must clean up all storage associated with outstanding coupling facility requests, specifically the storage buffers associated with IXLCACHE, IXLLIST, and IXLRT. Note that no input storage buffers are provided for IXLLOCK. Use the IXLPURGE service to purge the outstanding requests and ensure that there are no XES-established binds to the storage associated with the request. At the completion of IXLPURGE processing, control returns to the end-of-task resource manager with all storage binds broken. IXLPURGE processing differs according to whether the request was asynchronous or synchronous.
- Asynchronous request
  When the IXLPURGE request completes, if the connector is still active, request completion notification is scheduled normally (either through posting an ECB or driving the complete exit). Issue IXLFCOMP to obtain the results of asynchronous token requests. Once IXLPURGE completes, the system does not suspend an IXLFCOMP request because the outstanding request has already been purged and therefore is complete. Request-related storage cannot be deleted until all processing for the request has been deleted.
  
  Note: In order to issue IXLFCOMP, the requestor must be running with the primary address space equal to the connector's primary address space and have the same addressability as when the asynchronous request was issued initially.
- Suspended synchronous request
  For IXLLIST, IXLCACHE, and IXLRT requests suspended at the time of the failure, the XES recovery routine receives control and attempts to complete the request. When the requestor's recovery routine receives control, the connector must issue IXLPURGE in order to ensure that the request is complete.
XES Resource Manager Processing
At the completion of processing by the connector's resource manager, the XES resource manager continues the clean-up processing.
- XES invokes IXLPURGE to release any additional storage binds. XES uses the TTOKEN of the terminating task as input to IXLPURGE.