Using an XISQUE global user exit program
When the exit is enabled, your XISQUE global user exit program is able to check on the state of allocate queues for IPCONNs in the local system. The parameter list passed to the exit program on invocation provides data about a specific allocate request and IPCONN.
Using the information passed in the parameter list, your global user exit program can decide (based on queue length, for example) whether CICS® is to queue the allocate request. Your program communicates its decision to CICS by setting one of the following return codes:
- UERCAQUE
- CICS is to queue the allocate request.
The total number of allocate requests currently queued against the connection is provided in field ISR_CURRENT_QUEUED_ALLOCATES of the IPCONN statistics record, which is addressed by the UEPCONST exit-specific parameter. See DSECT DFHISRDS for details.
CICS also passes to the exit program, in field UEPQUELM, the value of the QUEUELIMIT option of the IPCONN resource definition. If the queue limit has not been reached, you can return control to CICS with return code UERCAQUE.
- UERCAPUR
- CICS is to reject the allocate request, return
SYSIDERR to the application program, and leave the existing queue
unchanged.
If the number of queued allocate requests has reached the limit set on the QUEUELIMIT option of the IPCONN definition, you can request that CICS rejects the request. However, you should first check whether the state of the link is satisfactory. This means checking that the rate of allocation of sessions is acceptable. Use the time the queue was started, the current time, and the total number of allocates processed since the queue began, to determine the rate at which CICS is processing requests. The relevant fields are: UEPSAQTS and UEPSACNT.
To determine whether CICS is allocating requests for sessions on this IPCONN at an acceptable rate, you can compare the calculated time with either of the following:- The value of the MAXQTIME option of the IPCONN resource definition, which is passed in the UEPEMXQT exit-specific parameter.
- Some other preset time value.
- UERCAKLL
- Reject this request, purge all other allocate requests queued
on this IPCONN, and send an information message to the operator console.
If the queue limit has been reached and the performance of allocate processing is below the acceptable limits defined in your user exit program, you can purge all queued allocate requests by specifying return code UERCAKLL.
UERCAKLL also causes CICS to:- Return SYSIDERR to all application programs waiting on the purged allocate requests.
- On subsequent calls to your XISQUE exit program, set the UEPFLAG parameter to UEPRC8 to indicate that UERCAKLL was returned previously to purge the queue.
Purging a queue that is causing congestion in the flow of tasks frees task slots that are needed to prevent the system becoming clogged. The more you allow a session queue to grow, the more likely you are to reach the task ceiling set by the MAXT parameter, and then cause a queue of incoming tasks in the local region that cannot be attached.
If a queue has been purged previously (with UERCAKLL) but there are no queued requests currently, check the number of sessions freed since the queue was last purged. This number is in UEPSARC8. If no sessions have been freed on this IPCONNsince the queue was last purged, the problem that caused the purge previously has not been resolved, and this request should be rejected with UERCAPUR.
If the UEPSARC8 parameter shows that sessions are being freed, you should use UERCAQUE to resume queuing of requests. If you return with UERCAQUE in this case, CICS issues an information message to the console to signal that queuing has been resumed.
- UERCNORM
- CICS is to resume normal processing on the connection,
including queuing of requests.
Use UERCNORM when the exit is invoked after a successful allocate following the suppression of queuing.