Contention Exit Processing

The contention exit can specify that the following actions be taken to resolve contention by setting indicators for one or more resource requests in the CEPL:

Grant requests that are pending with or without changes to the requested state, user data, and/or record data.
Deny requests that are pending.
Regrant an owned resource with changed state, user data, record data.
Keep a request pending.
Direct XES to run the notify exit of selected users who own the resource.

If the contention exit returns to XES with a mixture of grants, regrants, or notify exit processing to be done, the system processes grants, regrants, and denys first, followed by notify exit processing.

The following describes what actions the contention exit can take.

Grant a request that is pending
The contention exit can grant any pending resource request by setting the grant indicator (CEPLEGRANT) in the corresponding CEPL entry. While granting the request, the contention exit might also change the ownership attributes originally requested by modifying the grant/regrant area in the CEPL entry.
XES processes the grant request and any record data entry updates that might have been specified on the original IXLLOCK OBTAIN request. If XES is unable to grant the request (for example, it attempted to grant a request that required a record data entry to be created and there were no entries available), XES proceeds as follows:
- XES returns failing return and reason codes to the issuer of the IXLLOCK request.
- XES presents no new requests for the resource to the contention exit until:
  - All the requested actions (grants, regrants, denys) from the previous invocation of the exit have been processed.
  - The updated resource request queue is presented to the contention exit with the reason that an attempt to grant a request (as instructed by the previous invocation of the contention exit) has failed. The connector(s) whose request(s) have failed will be represented on the resource request queue with the ownership attributes that applied prior to the new request. This implies the following:
    - If the request that failed was an attempt to gain ownership of a resource that the requestor did not currently own (for example, an IXLLOCK OBTAIN request), then the updated resource request queue will not contain an entry for this connector. Any subsequent requests by this connector to alter or release the resource (including those that were outstanding at the time of failure) will be failed with return and reason codes indicating that the specified resource is not owned or pending ownership. These subsequent requests are not presented to the contention exit.
    - If the request that failed was an attempt by a requestor to update the ownership attributes of a resource that it currently owns (for example, an IXLLOCK ALTER request against an owned resource), then the connector will be represented on the resource request queue with the ownership attributes that applied prior to the failed attempt to update.
Deny a request that is pending
The contention exit can deny a pending resource request by setting the deny indicator (CEPLEDENY) in the corresponding CEPL entry.
Note that the contention exit can not deny a request from a connector to release its ownership of a resource (IXLLOCK RELEASE). XES will ignore any attempt by a connector to deny this type of request.
- Denying a request for a resource that is not currently owned (IXLLOCK OBTAIN) results in the request being removed from the resource request queue. If the requestor had issued any subsequent requests to alter or release the resource whose ownership has been denied, XES fails the subsequent requests with return and reason codes indicating that the specified resource is not owned. These subsequent requests are not presented to the contention exit.
- Denying a request to update a currently owned resource (IXLLOCK ALTER) results in the corresponding update being cancelled. The entry remains on the resource request queue in its previous ownership state.
While a request being denied results in the requestor's ownership status not being updated as requested, any modifications made to the requested user data (CEPLEGUDATA) by the contention exit will be presented to the requestor as part of request completion. For instance, the contention exit may deny a request and also update the user data field to include a value indicating why the request was denied. The requestor, upon being informed of the request being denied, could potentially take some action based on the value in the changed user data.
Regrant an owned resource
The contention exit can regrant a resource by setting the regrant indicator (CEPLEREGRANT) in the appropriate CEPL. The state and/or user data can be changed on a regrant; record data cannot be updated on a regrant. XES allows only owned resources to be regranted. The connector whose ownership has been updated is informed through its complete exit.
- Regranting a resource that is currently owned results in the state (CEPLEGSTATE) and/or user data (CEPLEGUDATA) being updated.
- Regranting a resource that is owned and pending update results in the “owned” state and/or user data being updated, but the pending request remains unaffected. For example, the contention exit may encounter an entry which represents a connector as an owner of a resource with a pending request to update its ownership status (IXLLOCK ALTER). If the exit specifies to regrant the owner's interest in the resource, the owned status will be updated and the pending IXLLOCK ALTER request will remain pending.
Special Note about the Regrant Function: Be aware that using the regrant function to downgrade a connector's ownership of a resource to be less restrictive introduces the possibility of an integrity exposure. This exposure could occur as the result of an asynchronous process (namely, the contention exit) modifying the serialization that was originally acquired by a connector to make an update without first informing that connection that its ownership status is being changed. Specifically, in the period between the time that the contention exit indicates to regrant the connector's ownership status and the time that the affected connector is able to be informed of the change (and subsequently take actions based on this), an update of a shared resource without the proper serialization could occur. If an application's locking protocol requires the contention exit to modify the attributes of owned resources in this manner, it should consider using the notify function.
Keep a request pending
The contention exit can choose neither to grant nor to deny a pending resource request. However, be aware of the following when leaving a request pending on the queue:
- The request can be superseded (replaced on the resource request queue) by a more recent request from the connector.
- The request will be granted when the resource request queue ceases to be in contention.
- The request might also be granted by actions taken on a subsequent invocation of the contention exit.
Direct XES to run notify exits
The contention exit can direct XES to run the notify exit of selected resource owners by setting the invoke notify exit indicator (CEPLENOTIFY) in the appropriate CEPL entry. Keep in mind that XES processes requests to grant, regrant, and deny requests before it handles requests to run the notify exits of selected users. Therefore, the resource request queue presented to the notify exits (in the NEPL) will contain any updates resulting from these prior actions. If a failure occurs while performing one of these prior actions (for instance, a grant fails), XES returns to the contention exit to report the failure and cancels the requests to run any notify exits.
When directed to run the notify exit of selected users, XES proceeds as follows:
- The resource request queue (in the form of the notify exit parameter list, NEPL) is presented to the notify exits of owners specified by the managing user's contention exit.
- No new requests for the resource are processed until:
  - All the indicated notify exits have completed processing,
  - XES updates the resource request queue to reflect the changes (if any) made in the notify exits and presents them to the contention exit, and
  - The contention exit indicates that no more notify exits are to be given control.
    Note that if the contention exit indicates that notify exits are again to be given control, then processing resumes with notify exit scheduling for the indicated notify exits.