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.
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:
- If the XISCONA exit program is not active, CICS queues
the request when necessary.
- 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.
- 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:
- Stipulate that queuing is never to be used. This is the simplest
way to code the exit, and avoids complexities of tuning. It should
be effective if you define enough contention winner sessions to handle
the peak transaction load for the connection. If you suppress all
queuing, you must specify AUTOCONNECT(YES) on the SESSIONS definition,
because the queuing mechanism no longer binds sessions for you.
With
this approach, a danger arises if you base your estimate of required
sessions on average conditions and the transaction load subsequently
varies widely; when CICS cannot use queuing to cope with
the variation, users may suffer transaction abends when there is no
significant problem in the resource-owning region.
- Examine the number of requests currently in the queue. The program
could, for example, stop queuing when the number exceeds 120%
of the maximum number of sessions. You could use this approach to
cope with intermittent stoppages in the resource-owning region.
You
could use a table of thresholds for the connections in your system,
with values determined from previous experience of queuing problems.
Alternatively, you could use the EXEC CICS interface in a separate
program to inquire about the state of the connection, and pass the
information in a work area to the XISCONA exit program.
- Examine the type of request and the resource being accessed (which
can be discovered by examining the request parameter list). The program
could, for example, reject file read requests but queue file updates.
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:
- The general format of statistics records is described in CICS statistics record format.
- For a list of statistics record-types and their associated copy
books, see Figure 106.
- 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.
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:
- The remote system is not in service.
- A connection to the remote system cannot be established.
- No sessions are immediately available, and your XISCONA exit program
has specified that the request is not to be queued in the issuing
region.
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.
"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 ]]