VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE

Note:
None of the exits in the VTAM® working-set module is available for advanced program-to-program communication (APPC, or LUTYPE6.2) links.

Exit XZCIN

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.

Exit XZCOUT

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.

Exit XZCOUT1

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.

XZIQUE exit for managing intersystem queues

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:

  1. The parameter from the connection definition, MAXQTIME, which is passed in the exit specific parameter UEPEMXQT
  2. 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:

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:

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:
  1. An allocate request for a session is about to be queued
  2. 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.

Designing an XZIQUE global user exit program

The functions of your XZIQUE exit should be designed:

  1. 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.
  2. To detect poor response from the receiving (remote) system and to notify the operator (or automatic operations program).
  3. 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:

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:

  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:

  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 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.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]