Intersystem communication program exits XISCONA and XISLCLQ

The two exits in the intersystem communication program allow you to control the length of intersystem queues.

Note:
There are several methods that you can use to control the length of intersystem queues. For a description of the available methods, see the CICS® Intercommunication Guide.

The XISCONA exit

Important

It is recommended that you use the XZIQUE exit, in the VTAM® working-set module, to control the length of intersystem queues, rather than XISCONA. (XZIQUE is described in topic XZIQUE exit for managing intersystem queues.) XZIQUE provides more functions, and is of more general use than XISCONA (it is driven for function shipping, DPL, transaction routing, and distributed transaction processing requests, whereas XISCONA is driven only for function shipping and DPL). If you enable both exits, XZIQUE and XISCONA could both be driven for function shipping and DPL requests, which is not recommended.

If you already have an XISCONA exit program, you may be able to modify it for use at the XZIQUE exit point.

The purpose of XISCONA is to help you prevent the performance problems that can occur when function shipping or DPL requests awaiting free sessions for a connection are queued in the issuing region. The exit permits you to control the number of outstanding ALLOCATE requests by allowing you to reject any function shipping or DPL request that would otherwise be queued.

Function shipping and DPL requests for a resource-owning region are queued by default if all bound contention winner 4 sessions are busy, so that no sessions are immediately available. If the resource-owning region is unresponsive (for example, if it is a file-owning region, it may be waiting for a system journal to be archived), the queue can become so long that the performance of the issuing region is severely impaired. Further, if the issuing region is an application-owning region, its impaired performance can spread back to the terminal-owning region.

To control the queuing of function shipping and DPL requests, use the XISCONA exit to tell CICS, whenever a session cannot be allocated immediately, whether to queue the request, or to return ‘SYSIDERR’ to the application. The exit works like this:

  1. If the XISCONA exit program is not active, CICS queues the request when necessary.
  2. If the exit program is active, it is invoked only if all bound contention winner sessions are in use. For other failures (for example, ‘Mode name not found’ or ‘Out of service’), CICS bypasses the exit and returns to the application.
  3. If it is invoked, your exit program must decide whether or not to queue the request by analyzing the statistics provided through the user exit parameter list. Your exit program could:
    Note:
    Because a failure of the exit program could affect system availability, it is recommended that you make the logic of your program as simple as possible, thus reducing the possibility of errors.

There are some problems that XISCONA cannot solve. For example, if you have specified both a large number of sessions and a large value for MXT, CICS may develop the short-on-storage (SOS) condition before XISCONA is invoked because there are no further sessions available.

The sample XISCONA global user exit program, DFHXIS

Note that there is a CICS-supplied sample exit program, DFHXIS, that shows one way of limiting the queue of ALLOCATE requests, based on the information passed to the program. For more information about the sample global user exit programs, see Sample global user exit programs.

Exit XISCONA

When invoked
When a function shipping or DPL request is about to be queued because all bound contention winner sessions to the remote region are in use.
Note:
For DPL requests that are routed dynamically, the dynamic routing program is invoked before XISCONA. If there are no free sessions the routing program may choose not to queue a DPL request; in these circumstances, XISCONA is not invoked. For information about the dynamic routing of DPL requests, see the CICS Intercommunication Guide.
Exit-specific parameters
UEPISPCA
Address of a parameter list containing the following fields. You can map the parameter list using the DSECT DFHXISDS.
UEPCONST
Address of the Connection statistics record.

Connection statistics records are of type STICONSR (STID value 52). Your exit program can map the record using the DSECT DFHA14DS. See notes.

UEPMODST
Address of the Mode Entry statistics record, or zero. A Mode Entry statistics record is built only if:
  • The connection-type is LU6.2 (see field UEPCONTY).
  • The profile DFHCICSF (which is always used for function shipping) defines a specific MODENAME to be used in the allocation of LU6.2 sessions.

Mode Entry statistics records are of type STICONMR (STID value 76). Your exit program can map the record (if present) using the DSECT DFHA20DS.

UEPEIPPL
Address of the request parameter list.
UEPCONTY
A 1-byte field indicating the connection-type. Possible values are:
UEPMRO (X'80')
Request for an MRO connection
UEPLU6 (X'40')
Request for an LU6.1 connection
UEPLUC (X'20')
Request for an LU6.2 connection.
UEPNETNM
An 8-character field containing the NETNAME for the connection- that is, the identifier (applid) of the remote CICS region or system.
Notes:
  1. The general format of statistics records is described in CICS statistics record format.
  2. For a list of statistics record-types and their associated copy books, see Figure 106.
  3. For a description of the fields in Connection and Mode Entry statistics records, see the CICS Performance Guide.
Return codes
UERCAQUE
Queue the request. This is the default.
UERCAPUR
Do not queue the request, unless local queuing is possible.
XPI calls
All can be used.
Important

There is no ‘UERCNORM’ return code at this exit point, because the exit is invoked after a failure. The choice is whether or not to take the system default action of queuing the request.

The XISLCLQ exit

XISLCLQ enables you to specify what action to take after a function shipping request fails to allocate a session with a remote system for one of the following reasons:

Note that this exit is invoked only if the request to be shipped is of type EXEC CICS START NOCHECK. For EXEC CICS requests other than those with the NOCHECK option (which is only available on START commands) the ‘SYSIDERR’ condition is raised in the application program.

You can use the exit to specify whether or not the failed request is to be locally queued, to be executed when the connection is reestablished.

Exit XISLCLQ

When invoked
After a function shipping request of type EXEC CICS START NOCHECK has failed because the remote system is not in service, a connection to the remote system cannot be established, or no sessions are immediately available, and your XISCONA exit program has specified that the request is not to be queued in the issuing region.
Exit-specific parameters
UEPISPP
Address of a parameter list that contains:
UEPTCTSE
Address of the relevant terminal control table system entry. The TCT system entry can be mapped using the DSECT DFHTCTTE.
UEPXXTE
Address of the local transaction name, or 0 if SYSID was specified in the command.
Note:
Your program can use the transaction manager XPI call INQUIRE_TRANDEF to obtain details of the local transaction (see The INQUIRE_TRANDEF call).
UEPPLIST
Address of the parameter list for the command.
Note:
No DSECT is provided for the above parameter list. You have to code your own DSECT to access the named fields.
Return codes
UERCSYS
Take the system action. This is determined by the value of the LOCALQ attribute in the local TRANSACTION definition for the remote transaction:
LOCALQ(YES)
The request is queued locally.
LOCALQ(NO)
‘SYSIDERR’ is returned to the application program.
UERCQUE
Queue the request locally (overriding the LOCALQ(NO) attribute, if specified).
UERCIGN
Override the LOCALQ(YES) attribute, if specified, and return with ‘SYSIDERR’.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
Important

There is no ‘UERCNORM’ return code at this exit point, because the exit is invoked after a failure. The choice is whether to take the system default action or to handle the error in some other way.

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

4.
"Contention winner" is the terminology used for LU6.2 connections. The XISCONA exit applies also to MRO and LU6.1 connections: in these, the SEND sessions (defined in the session definitions) are used first for ALLOCATE requests; when all SEND sessions are in use, queuing starts.

[[ Contents Previous Page | Next Page Index ]]