Session queue management sample exit program for IPIC connections: DFH$XISQ

DFH$XISQ is a sample XISQUE 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 of the IPCONN resource definition.

About DFH$XISQ

If the XISQUE 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 IPCONN definition are passed to the XISQUE exit program, which can change the way in which these parameters are used.

The program uses the exit-specific parameters passed by CICS to determine the state of the IPCONN and to request the appropriate action, as follows:

  1. The IPCONN 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, 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 DFHZCaaaa 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.

    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 and CICS to issue message DFHZCbbbb.

Prerequisites for DFH$XISQ

The sample program uses DSECT object DFHXIQDS to map the area addressed by UEPISDATA. DFHXIQDS is supplied in the CICSTS54.CICS.SDFHMAC library.

Extending DFH$XISQ

The sample exit program does not control the queue length. This kind of enhancement is what you might want to add to your own exit program.

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.