Exit XISQUE
The XISQUE global user exit is called, if it is enabled, when CICS® attempts to acquire a session and no free session is available, or when an allocate request finds a free session after queuing has previously been suppressed. Exit-specific parameters, return codes, and XPI call information are explained.
- When called
- The XISQUE exit is called under these circumstances:
- CICS tries to acquire a
session on an IPIC connection
to a remote system and no free session is available. It is called
whether or not you have specified the QUEUELIMIT option on the IPCONN
definition and whether or not the limit has been exceeded. Requests for IPIC sessions occur when one of the following requests or commands is used across an IPIC connection:
- A distributed program link (DPL) request
- A START or CANCEL command
- A transaction routing request
- A function shipping file control, transient data, or temporary storage request
- An IPIC allocate request succeeds in finding a free session, after the queue on the IPIC connection has been purged by a previous call of the exit program. In this case, your exit program can indicate that CICS is to continue processing normally, resuming queuing when necessary.
- CICS tries to acquire a
session on an IPIC connection
to a remote system and no free session is available. It is called
whether or not you have specified the QUEUELIMIT option on the IPCONN
definition and whether or not the limit has been exceeded.
- Exit-specific parameters
-
- UEPISDATA
- Address of the 78-byte area. This area is
mapped by the DSECT in copybook DFHXIQDS.Area addressed by UEPISDATA:
- UEPREQ
- A 2-byte origin-of-request code, which can have the following
value:
- AL
- Other kinds of intercommunication (for example, STARTs).
- FS
- Function shipping and distributed program link
- TR
- Transaction routing
- UEPIPCNM
- The 8-byte name of the IPCONN.
- UEPREQTR
- The 4-byte identifier of the requesting transaction.
- UEPFLAG
- A 1-byte flag indicating whether a return code 8 was issued the
last time the exit was called.
- UEPRC8
- The exit program returned control to CICS on the previous call with return code 8.
- UEPFSPL
- Address of the 10-byte parameter list for the DPL request.
- UEPCONST
- Address of the 504-byte IPCONN statistics record. This record can be mapped using DSECT DFHISRDS.
- UEPEMXQT
- A halfword binary field containing the maximum queuing time, MAXQTIME, specified in the IPCONN resource definition.
- UEPSAQTS
- A double-word binary field containing the time stamp from the installed IPCONN resource definition, indicating the time that the queue of allocate requests was started.
- UEPSACNT
- A half-word binary field containing the number of allocate requests processed since the queue was started. See UEPSAQTS for the start time.
- UEPSARC8
- A half-word binary field containing the number of sessions freed since the queue was last purged as the result of an UEPCAKLL return code.
- UEPQUELM
- A half-word binary field containing the queue limit, QUEUELIMIT, specified in the IPCONN resource definition.
- Return codes
- In the case of an allocate that is about to be queued, use one
of the following return codes:
- UERCAQUE
- Queue the allocate request.
- UERCAKLL
- Reject this allocate request with SYSIDERR. Purge all other queued allocate requests and send an information message to the operator console. CICS also returns SYSIDERR to all application programs waiting on the purged allocate requests.
- UERCAPUR
- Reject the allocate request with SYSIDERR.
- UERCPURG
- Task purged during XPI call.
In the case of a successful allocate following the use of UERCAKLL on a previous call of the exit, you can use a normal return code (UERCNORM) or use the SYSIDERR return code (UERCAPUR):- UERCNORM
- Resume normal operation of the IPCONN.
- UERCAPUR
- Reject the allocate request with SYSIDERR.
- XPI calls
- All can be used.
- API and SPI calls
- None can be used.