MRO and APPC session queue management sample exit program: DFH$XZIQ

DFH$XZIQ is a sample XZIQUE exit program that you can use as a base to design your own global user exit program. It implements the same basic function provided by the QUEUELIMIT and MAXQTIME parameters on the connection resource definition.

About DFH$XZIQ

If the XZIQUE exit is not enabled, CICS® uses the QUEUELIMIT and MAXQTIME parameters to control the existence and length of the queue of allocate requests. If you enable the exit, the parameters from the connection definition are passed to your XZIQUE global user exit program, which can change the way in which these parameters are used.

The exit program also demonstrates how to control allocate requests for a particular modegroup, based on the same QUEUELIMIT and MAXQTIME parameters.

DFH$XZIQ uses the exit-specific parameters passed by CICS to determine the state of the connection and to request the appropriate action, as follows:

  1. The connection is operating normally; a queue may exist, but is of short length.

    In this case, the exit program returns with UERCAQUE to indicate that CICS is to queue the request.

  2. The response from the partner system is slower than the rate of requests demands, and the queue length has grown to the limit specified on the QUEUELIMIT parameter. The partner system is still operating normally, but is overloaded.

    In this case, the exit program returns with UERCAPUR to indicate that CICS is to purge the request.

  3. The queue has reached the limit specified by the QUEUELIMIT parameter, and requests that join the queue are expected to take longer to be satisfied than the time defined by the MAXQTIME parameter. (The estimated time for a request to complete is calculated by dividing the number of successful requests since the queue first formed by the time elapsed since it formed. These statistics are passed to the exit in the parameter list.)
    These criteria are used to determine that the connection is not operating correctly, and that continued queuing of tasks is not helpful. In this case:
    • The exit returns with UERCAKLL requesting CICS to purge all queued user requests from the connection. The SYSIDERR condition is returned to the application program.
    • CICS issues message DFHZC2300 to warn that a connection is not performing as expected.
  4. The queue has been purged as a result of a previous invocation of the global user exit program, there are still no free sessions, and the request is about to be queued.

    In this case, the exit program returns with UERCAPUR to indicate that CICS is to purge the request. This also leaves the UEPRC8 flag set.

  5. The queue has been purged as a result of a previous invocation of the global user exit program. A new allocate request has been received and is about to be allocated because a session has become free.

    CICS invokes the exit program to enable it to indicate that normal processing can continue.

    In this case, the exit program returns with UERCNORM to indicate that CICS is to continue processing normally. This also causes the UEPRC8 flag to be unset following this invocation, and causes CICS to issue message DFHZC2301.

The sample program also monitors the length of queues for modegroup-specific allocate requests and controls these—in the same way as the queue for the whole connection—using the QUEUELIMIT parameter and MAXQTIME parameters.

If both UEPRC8 and UEPRC12 are set, UERCNORM is required twice to resume normal operation. The UEPRC8 condition is reset first in this case.

Prerequisites for DFH$XZIQ

DFH$XZIQ uses DSECT object DFHXZIDS to map the area addressed by UEPZDATA. DFHXZIDS is supplied in the CICSTS54.CICS.SDFHMAC library.

Extending DFH$XZIQ

The sample exit program does not attempt to control the queue length, or detect poor response for a particular modegroup differently from the whole connection. This kind of enhancement is what you might want to add to your own exit program if your applications request specific modegroups through the allocate command or through a transaction profile and you think it would be useful to control the modegroups individually.

You can also use more complex decisions (such as adding time delays to lessen the risk of false diagnosis) to decide when to issue the return codes that purge the queue, and allow queuing to restart.