Note:
None of the exits in the VTAM® working-set module is available for advanced
program-to-program communication (APPC, or LUTYPE6.2) links.
- When invoked
- After an input event.
- Exit-specific parameters
-
- UEPTCTTE
- Address of the terminal control table terminal entry (TCTTE). The TCTTE
can be mapped using the DSECT DFHTCTTE.
- UEPTIOA
- Address of the terminal input/output area (TIOA). Your exit program
should not change the address. The TIOA can be mapped using the DSECT DFHTIOA.
However, fields TIOASAL and TIOASCA are not programming
interfaces.
- Return codes
-
- UERCNORM
- Continue processing.
- XPI calls
- All can be used. However, we do not
recommend that you use a GETMAIN call to obtain terminal-class storage for
use as a replacement TIOA. This is because there are several internal pointers
to the TIOA, and if any one of these is not updated the application may experience
problems.
- When invoked
- Before an output event.
- Exit-specific parameters
-
- UEPTCTTE
- Address of the terminal control table terminal entry (TCTTE). The TCTTE
can be mapped using the DSECT DFHTCTTE.
- UEPTIOA
- Address of the terminal input/output area (TIOA). Your exit program
should not change the address. The TIOA can be mapped using the DSECT DFHTIOA.
However, fields TIOASAL and TIOASCA are not programming
interfaces.
Note:
In certain circumstances--for example, when XZCOUT is invoked
before the send of a NULL RU--UEPTIOA contains zeroes.
- Return codes
-
- UERCNORM
- Continue processing.
- XPI calls
- All can be used. However, we do not
recommend that you use a GETMAIN call to obtain terminal-class storage for
use as a replacement TIOA. This is because there are several internal pointers
to the TIOA, and if any one of these is not updated the application may experience
problems.
- When invoked
- Before a message is broken into RUs.
- Exit-specific parameters
-
- UEPTCTTE
- Address of the terminal control table terminal entry (TCTTE). The TCTTE
can be mapped using the DSECT DFHTCTTE.
- UEPTIOA
- Address of the terminal input/output area (TIOA). Your exit program
should not change the address. The TIOA can be mapped using the DSECT DFHTIOA.
However, fields TIOASAL and TIOASCA are not programming
interfaces.
- Return codes
-
- UERCNORM
- Continue processing.
- XPI calls
- All can be used. However, we do not
recommend that you use a GETMAIN call to obtain terminal-class storage for
use as a replacement TIOA. This is because there are several internal pointers
to the TIOA, and if any one of these is not updated the application may experience
problems.
You can use the XZIQUE exit to control the number of queued requests for
sessions on intersystem links (allocate queues).
Note:
There are several methods that you can use to control the
length of intersystem queues. For a description of the various methods, see the CICS® Intercommunication Guide.
The XZIQUE exit enables you detect queuing problems (bottlenecks) early.
It extends the function provided by the XISCONA global user exit (introduced
in CICS/ESA 3.3 and described in topic Intersystem communication program exits XISCONA and XISLCLQ), which is invoked only for function shipping and DPL requests. XZIQUE is invoked for transaction routing, asynchronous processing, and
distributed transaction processing requests, as well as for function shipping
and DPL. Compared with XISCONA, it receives more detailed information
on which to base its decisions.
XZIQUE enables allocate requests to be queued or rejected, depending on
the length of the queue. It also allows a connection on which there is a bottleneck
to be terminated and then re-established.
Interaction with the XISCONA exit
There is no interaction between the XZIQUE and XISCONA global user exits.
If you enable both exits, XISCONA and XZIQUE could both be invoked for
function shipping and DPL requests, which is not recommended. You should
ensure that only one of these exits is enabled. Because of it provides more
function and greater flexibility, it is recommended that you use XZIQUE rather
than XISCONA.
If you already have an XISCONA global user exit program, you could possibly
modify it for use at the XZIQUE exit point.
When the XZIQUE exit is invoked
The XZIQUE global user exit is invoked, if it is enabled, at the following
times:
Using an XZIQUE global user exit program
When the exit is enabled, your XZIQUE global user exit program is able
to check on the state of the allocate queue for a particular connection in
the local system. Information is passed to the exit program in a parameter
list, that is structured to provide data about non-specific allocate requests,
or requests for specific modegroups, depending on the session request. Non-specific
allocate requests are for MRO, LU6.1, and APPC sessions that do not specify
a modegroup.
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 means of
one of the return codes CICS provides. These are:
- UERCAQUE
- This return code indicates that CICS is to queue the allocate request.
The total number of allocate requests queued against the connection is provided
in field A14ESTAQ of the system entry statistics (for all non-specific allocates)
or A20ESTAQ of the mode entry statistics (for specific modegroup allocates).
See DSECTs DFHA14DS or DFHA20DS for details. CICS passes to the exit program, in the exit
specific parameter UEPQUELIM, the QUEUELIMIT parameter from the connection
definition.
If the limit has not been reached, you can return control
to CICS with return code UERCAQUE.
- UERCAPUR
- This return code indicates that CICS is to reject the allocate request and
return SYSIDERR to the application program, but leave the existing queue unchanged.
If the number of queued allocate requests has reached the limit set on the
QUEUELIMIT parameter for the connection, 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 for non-specific allocate requests; and UEPMAQTS and UEPMACNT
for specific modegroup requests.
To determine whether CICS is allocating
requests for sessions on this connection at an acceptable rate, you can compare
the calculated time with either of the following:
- The parameter from the connection definition, MAXQTIME, which is passed
in the exit specific parameter UEPEMXQT
- Some other preset time value.
If the processing time using this kind of formula is acceptable, return
control to CICS with return code UERCAPUR to purge only this request.
- UERCAKLL or UERCAKLM
- These return codes indicate that you want CICS to deal with the request as follows:
- UERCAKLL--reject this request, purge all other queued allocate requests
on this connection, and send an information message to the operator console.
- UERCAKLM--reject this request, purge all other queued modegroup allocate
requests on this connection, and send an information message to the operator
console.
If the queue limit has been reached
but the performance of allocate processing against the queue is below the
acceptable limits defined in your user exit program, you can return control
to CICS as follows:
- For non-specific allocate requests, use return code UERCAKLL. UERCAKLL
also returns SYSIDERR to all application programs waiting on the purged allocate
requests. CICS sets the UEPFLAG parameter to UEPRC8 on subsequent calls to your
XZIQUE exit program to indicate that UERCAKLL was returned previously to purge
the queue.
- For specific modegroup allocate requests, use return code UERCAKLM. UERCAKLM
also returns SYSIDERR to all application programs waiting on the purged allocate
requests. CICS sets the UEPFLAG parameter to UEPRC12 on subsequent calls to your
XZIQUE exit program to indicate that UERCAKLM 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. Note that some internal CICS requests (such as those for the LU services model transactions CLS1,
CLS2, and CLS3) are not purged by return codes UERCAKLL and UERCAKLM.
If a queue has been purged previously (with UERCAKLL or UERCAKLM) but there
are no queued requests currently, check the number of successful allocates
since the queue was last purged. For non-specific allocate requests, this
number is in UEPSARC8, and for specific modegroup requests, this number is
in UEPMAR12. If no requests of this type have been allocated on this connection
since 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 or UEPMAR12 parameters show that allocates are being
processed, 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.
Note:
The address of the system entry statistics record, UEPCONST,
is supplied for both non-specific and specific modegroup allocate requests.
The address of the modegroup statistics record, UEPMODST, is set to zeros
for non-specific allocate requests. This address is supplied only if the request
is for a specific modegroup.
If the exit is invoked after a successful allocate following the suppression
of queuing, you can use the following return code:
- UERCNORM
- This return code indicates that CICS is to resume normal processing on the
link, including queuing of requests.
Statistics fields in DFHA14DS and DFHA20DS
There are some statistics fields that your XZIQUE global user exit program
can use to control queues.
A14EALRJ
Each time an XZIQUE global user exit program returns with a request to
reject a request, CICS increments a new field in the system entry connection
statistics. This is A14EALRJ (allocate rejected) in DSECT DFHA14DS. This field
is provided to help you to tune the queue limit. Normally, if the number of
sessions and the queue limit defined for a link are correctly balanced, and
there has been no abnormal congestion on the link, the A14EALRJ should be
zero. If the rejected allocates field is non-zero it probably indicates that
some action is needed.
A14EQPCT and A20EQPCT
Each time an XZIQUE global user exit program returns with a request to
purge a queue, CICS increments a new field in either the system entry
or mode entry connection statistics. These fields are:
- A14EQPCT
- The count of the number of times the queue has been purged for the connection
as a whole.
- A20EQPCT
- The count of the number of times the mode group queue has been purged.
For detailed information about statistics fields, what they contain and
how they are updated, see the CICS Performance Guide.
Exit XZIQUE
- When invoked
- Whenever:
- An allocate request for a session is about to be queued
- An allocate request succeeds following previous suppression of queuing.
- Exit-specific parameters
-
- UEPZDATA
- Address of the 70-byte area containing the information listed below.
This area is mapped by the DSECT in copybook DFHXZIDS.
- Area addressed by UEPZDATA
-
- UEPSYSID
- The 4-byte SYSID of the connection.
- UEPREQ
- A 2-byte origin-of-request code, which can have the following values:
- TR
- Transaction routing
- FS
- Function shipping (includes distributed program link)
- AL
- Other kinds of intercommunication (for example, distributed transaction
processing (DTP) or CPI Communications).
- UEPREQTR
- The 4-byte identifier of the requesting transaction (applicable only
when the origin-of-request code is FS or AL).
- UEPTRAN
- The 4-byte identifier of the transaction being routed (applicable only
when origin of request is TR).
- UEPFLAG
- A 1-byte flag indicating whether a return code 8 or return code 12 was
issued last time the exit was invoked.
- UEPRC8
- The exit program returned control to CICS on the previous invocation with return
code 8.
- UEPRC12
- The exit program returned control to CICS on the previous invocation with return
code 12.
- UEPPAD
- A 1-byte padding field.
- UEPFSPL
- Address of the 10-byte function shipping parameter list.
- UEPCONST
- Address of the 158-byte system entry statistics record (this can be
mapped using DSECT DFHA14DS).
- UEPMODST
- Address of the 84-byte modegroup statistics record for the modegroup
specified in the relevant CICS profile. This field applies only to APPC connections
for a specific allocate. For LU61, IRC, or non-specific APPC allocates, it
contains zero.
The statistics record can be mapped using DSECT DFHA20DS.
The modegroup name field (A20MODE) may contain blanks. The record is followed
by a fullword of X'FFFFFFFF'.
- UEPSTEX
- A 6-byte area containing additional current statistics for APPC that
are not already in the modegroup statistics record (DFHA20DS). For specific allocates, the numbers refer to the specified modegroup only.
For non-specific allocates, they refer to the whole connection--that
is, they are the totals of each modegroup.
The 6-byte area contains:
- UEPEBND
- A halfword binary field containing the number of bound sessions
- UEPEWWT
- A halfword binary field containing the number of contention winners
with tasks
- UEPELWT
- A halfword binary field containing the number of contention losers with
tasks.
- UEPEMXQT
- A halfword binary field containing the maximum queuing time specified
for the connection (MAXQTIME on the CONNECTION resource definition).
- UEPMDGST
- Address of a set of 84-byte modegroup statistics records--one for
each user modegroup for the connection. This field applies only to APPC connections
for a non-specific allocate. For LU61, IRC, and APPC specific allocates, it
contains zero.
Each statistics record can be mapped using DSECT DFHA20DS.
The modegroup name field (A20MODE) may contain blanks. The end of the set
of records is indicated by a fullword of X'FFFFFFFF'.
Non-specific allocates data:
The
following three fields contain data relating to MRO, LU6.1, and non-specific
APPC allocates:
- UEPSAQTS
- A double-word binary field containing the time stamp from the TCT system
entry indicating the time the queue of non-specific requests was started.
- UEPSACNT
- A half-word binary field containing the number of all non-specific allocates
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 a result of a UEPCAKLL return code to CICS.
Specific allocates data:
The
following three fields contain data relating to specific modegroup allocates.
They are applicable only when UEPMODST is non-zero (that is, it contains the
address of the relevant modegroup statistics).
- UEPMAQTS
- A double-word binary field containing the time stamp from the TCT mode
entry indicating the time that the modegroup queue was started for this specific
modegroup.
- UEPMACNT
- A half-word binary field containing the number of all specific allocates
for this modegroup processed since the queue was started (see UEPMAQTS for
the start time).
- UEPMAR12
- A half-word binary field containing the number of modegroup sessions
freed since the queue was last purged as a result of a UEPCAKLL return code
to CICS.
- UEPQUELM
- A half-word binary field containing the queue limit specified for this
connection (QUEUELIMIT on the CONNECTION definition).
- Return codes
- In the case of an allocate that is about to be queued, use one of the
following:
- UERCAQUE
- Queue the allocate request.
- UERCAPUR
- Reject the allocate request with SYSIDERR.
- 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.
- UERCAKLM
- Reject this allocate request for the modegroup and return SYSIDERR.
Purge all other queued allocate requests for the modegroup specified on this
allocate request and send an information message to the operator console.
Retry the modegroup after an interval.
- UERCPURG
- Task purged during XPI call.
In the case of a successful allocate following the use of UERCAKLL
or UERCAKLM, on a previous invocation of the exit, use one of the following:
- UERCNORM
- Resume normal operation of the link or modegroup.
- UERCPUR
- Reject the allocate request with SYSIDERR.
- XPI calls
- All can be used.
The functions of your XZIQUE exit should be designed:
- To control of the number of tasks (and the amount of associated resource)
that are waiting in a queue for a free intersystem session. Waiting tasks
can degrade the performance of the local system.
- To detect poor response from the receiving (remote) system and to notify
the operator (or automatic operations program).
- To cause CICS to issue a message when the link resumes normal operation.
The XZIQUE global user exit parameter list is designed to support these
objectives.
Design considerations
The information passed at XZIQUE is designed to enable your XZIQUE global
user exit program to:
- Avoid false diagnosis of problems on the connection by distinguishing
poor response times from a complete bottleneck
- Ensure that a link resumes normal operation quickly and without operator
intervention once any problem in a remote system is resolved.
Some guidance on the use of IRC/ISC statistics
CICS adds an entry for unsatisfied allocate requests to the following
queues:
- Non-specific (generic) allocate queue
- All non-specific allocate requests are queued in this single queue. CICS makes the total number of entries in this queue available in the system
entry statistics field A14ESTAQ, to which your global user exit program has
access by means of the address of the system entry statistics, which is passed
in UEPCONST.
- Specific modegroup allocate queues
- Specific allocate requests are queued in the appropriate modegroup queue--one
queue for each specific modegroup name. CICS makes the total number of entries in
all these queues available, as a single total, in the mode entry statistics
field A20ESTAQ, to which your global user exit program has access by means
of the address of the mode entry statistics, which is passed in UEPMODST.
Sample exit program design
A sample XZIQUE exit program is provided with CICS Transaction Server for z/OS®, Version 3 Release 1 as a base for you
to design your own global user exit program. It is called DFH$XZIQ,
and is supplied in the CICSTS31.CICS.SDFHSAMP library. The DSECT used by the sample
program to map the area addressed by UEPZDATA is called DFHXZIDS, and this
is supplied in the CICSTS31.CICS.SDFHMAC library.
As supplied, the sample exit program implements the same basic function
as described for the QUEUELIMIT and MAXQTIME parameters on the connection
resource definition. If the XZIQUE exit is not enabled, CICS uses these
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.
Overview of the sample exit program
The program uses the exit-specific parameters passed by CICS to determine
the state of the connection, and to request the appropriate action, as follows:
- 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.
- 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.
- 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.
- 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.
- 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 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.
Extensions to the sample program
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 something you might want to add to
your own exit program if your applications request specific modegroups via
the allocate command (or via 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.
[[ Contents Previous Page | Next Page Index ]]