This section describes the preferred method of routing transactions
that are invoked by EXEC CICS® START commands. For convenience,
we shall call the method described in this section the enhanced method.
The enhanced method supersedes the "traditional" method described
in Traditional routing of transactions started by ATI. Note, however, that the enhanced method
cannot be used to route:
- Some transactions that are invoked by EXEC CICS START commands
- Transactions invoked by the trigger-level on a transient data
queue.
In these cases, the "traditional" method must be used.
To specify that a transaction, if it is invoked by an EXEC CICS
START command, is to be routed by the enhanced method described in
this section, define the transaction as ROUTABLE(YES)
in the requesting region (the region in which the START command
is issued).
There are several advantages in using the enhanced method, where
possible, rather than the "traditional" method:
- Dynamic routing
- Using the "traditional" method, you cannot route the
started transaction dynamically. (For example, if the transaction
on a terminal-related START command is defined as DYNAMIC(YES) in
the terminal-owning region, your dynamic routing program is invoked
for notification only--it cannot route the transaction.)
Using
the enhanced method, you can route the started transaction dynamically.
- Efficiency
- Using the "traditional" method, a terminal-related START
command issued in a TOR is function-shipped to the AOR that owns the
transaction. The request is then shipped back again, for routing from
the TOR.
Using the enhanced method, the two hops to the AOR and
back are missed out. A START command issued in a TOR executes directly
in the TOR, and the transaction is routed without delay.
- Simplicity
- Using the "traditional" method, when a terminal-related
START command issued in a TOR is function-shipped to the AOR that
owns the transaction the "terminal-not-known" condition may
occur if the terminal is not defined in the AOR.
Using the enhanced
method, because a START command issued in a TOR is not function-shipped
to the AOR, the "terminal-not-known" condition does not occur.
The START command executes in the TOR directly, and the transaction
is routed just as if it had been initiated from a terminal. If the
terminal is not defined in the AOR, a definition is shipped from the
TOR.
For
a transaction invoked by a terminal-related START command to be eligible
for the enhanced routing method, all of the
following conditions must be met:
- The START command must be a member of the subset of eligible START
commands--that is, it must meet all the following conditions:
The START
command specifies the TERMID option, which names the terminal associated
with the current task.
The principal
facility of the task that issues the START command is a terminal.
This is not the case if, for example, the
program that issues the START command was linked-to by DPL; in this
case, the principal facility is the intersystem session.
- The principal facility of the task that issues the START command
is not a surrogate Client virtual terminal.
- The SYSID option of the START command does not specify the name
of a remote region. (That is, the remote region on which the transaction
is to be started must not be specified explicitly.)
- The requesting region, the TOR, and the target region must all
be CICS Transaction Server for OS/390®, Version 1 Release 3 or later.
Note:
The requesting region and the
TOR may be the same region.
- The requesting region and the TOR (if they are different) must
be connected by either of the following:
- An MRO link
- An APPC parallel-session link.
- The TOR and the target region must be connected by either of the
following:
- An MRO link.
- An APPC single- or parallel-session link. If an APPC link is used,
at least one of the following must be true:
- Terminal-initiated transaction routing has previously taken place
over the link. (The terminal-initiated transaction routing enables
the TOR to determine whether or not the target region is a CICS Transaction Server for OS/390, Version 1 Release 3
or later system, and therefore eligible for enhanced routing.)
- CICSPlex® SM is being used for routing.
- The transaction definition in the requesting region must specify
ROUTABLE(YES).
- If the requesting region and the TOR are different, the transaction
definition in the requesting region must not specify the REMOTESYSTEM
option. If the requesting region and the TOR are the same region,
you may use REMOTESYSTEM in the transaction definition for static
routing.
- If the transaction is to be routed dynamically, the transaction
definition in the TOR must specify DYNAMIC(YES).
Important:
When considering which START-initiated transactions are
candidates for dynamic routing, you need to take particular care if
the START command specifies any of the following options:
- AT, AFTER, INTERVAL, or TIME. (That is, there is a delay before
the START is executed.)
- QUEUE.
- REQID.
- RTERMID.
- RTRANID.
You need to understand how each of the options of the START
command is being used; whether, for example, it affects the set of
regions to which the transaction can be routed.
START commands issued in an AOR
If a terminal-related START command is issued in an AOR, it is
shipped to the TOR that owns the terminal named in the TERMID option.
The START executes in the TOR.
Static routing
The transaction definition in the AOR specifies ROUTABLE(YES).
The transaction definition in the TOR specifies DYNAMIC(NO). The dynamic
routing program is not invoked. If the transaction is eligible for
enhanced routing, 8 it is routed
to the AOR named in the REMOTESYSYEM option of the transaction definition
in the TOR. If REMOTESYSTEM is not specified, the transaction executes
locally, in the TOR.
Note:
If the transaction is ineligible for enhanced routing,
it is handled in the "traditional" way described in
Traditional routing of transactions started by ATI--that is, CICS tries to route it back to the
originating AOR for execution. If the REMOTESYSTEM option of the transaction
definition in the TOR names a region other than the originating AOR,
the request fails.
Figure 21 shows the requirements for using the enhanced
method to statically route a transaction that is initiated by a terminal-related
START command issued in an AOR.
Figure 21. Static routing of a terminal-related START command issued in an AOR, using the enhanced method. The requesting region, the TOR, and the target region
are all CICS TS OS/390, Version 1 Release 3 or later. The requesting region and the TOR
are connected by an MRO or APPC parallel-session link. The TOR and
the target region are connected by an MRO or APPC (single- or parallel-session)
link. The transaction definition in the requesting region specifies
ROUTABLE(YES). The transaction definition in the TOR specifies DYNAMIC(NO).
The REMOTESYSTEM option names the AOR to which the transaction is
to be routed.
Dynamic routing
Dynamic routing models
Dynamic routing of transactions invoked by terminal-related START
commands uses the "hub" routing model described in The "hub" model.
The transaction definition in the AOR specifies ROUTABLE(YES).
The transaction definition in the TOR specifies DYNAMIC(YES). The
dynamic routing program is invoked in the TOR. If the transaction
is eligible for enhanced routing, the routing program can reroute
the transaction to an alternative AOR--that is, to an AOR other
than that in which the START was issued.
Note:
If the transaction is ineligible for enhanced routing,
the dynamic routing program is invoked for notification only--it
cannot reroute the transaction. The transaction is handled in the "traditional"
way--that is, it is routed back to the originating AOR for execution.
Figure 22 shows the requirements for dynamically routing
a transaction that is initiated by a terminal-related START command
issued in an AOR.
Figure 22. Dynamic routing of a terminal-related START command issued in an AOR. The
requesting region, the TOR, and the target region are all CICS TS OS/390, Version 1 Release 3
or later. The requesting region and the TOR are connected by an MRO
or APPC parallel-session link. The TOR and the target region are connected
by an MRO or APPC (single- or parallel-session) link. The transaction
definition in the requesting region specifies ROUTABLE(YES). The transaction
definition in the TOR specifies DYNAMIC(YES).
START commands issued in a TOR
Static routing
The transaction definition in the TOR specifies ROUTABLE(YES) and
DYNAMIC(NO). The dynamic routing program is not invoked. If the transaction
is eligible for enhanced routing (see the list of conditions for START commands to be eligible for enhanced routing):
- The START executes in the TOR.
- The transaction is routed to the AOR named in the REMOTESYSYEM
option of the transaction definition. If REMOTESYSTEM is not specified,
the transaction executes locally, in the TOR.
Note:
If the transaction is ineligible for enhanced routing,
the START request is handled in the "traditional" way described
in
Traditional routing of transactions started by ATI--that is, it function-shipped to the
AOR named in the REMOTESYSTEM option of the transaction definition.
If REMOTESYSTEM is not specified, the START executes locally, in the
TOR.
Figure 23 shows the requirements for using the enhanced
method to statically route a transaction that is initiated by a terminal-related
START command issued in a TOR.
Dynamic routing
Dynamic routing models
Dynamic routing of transactions invoked by terminal-related START
commands uses the "hub" routing model described in The "hub" model.
The transaction definition in the TOR specifies ROUTABLE(YES) and
DYNAMIC(YES). The dynamic routing program is invoked. If the transaction
is eligible for enhanced routing, the START is executed in the TOR,
and the routing program can route the transaction.
Note:
If the transaction is ineligible for enhanced routing,
the dynamic routing program is invoked for notification only--it
cannot route the transaction. The START request is handled in the "traditional"
way--that is, it is function-shipped to the AOR named in the
REMOTESYSTEM option of the transaction definition in the TOR. If REMOTESYSTEM
is not specified, the START executes locally, in the TOR.
Figure 24 shows the requirements for dynamically routing
a transaction that is initiated by a terminal-related START command
issued in a TOR.
For a non-terminal-related START request to be eligible for enhanced
routing, all of the following conditions must
be met:
- The requesting region is CICS Transaction Server for OS/390, Version 1 Release 3 or later.
Note:
In
order for the distributed routing program to be invoked on the target region as well as on the requesting region,
the target region too must be CICS Transaction Server for OS/390, Version 1 Release 3 or later. (For information about
the points at which the distributed routing program is invoked, see the CICS Customization Guide.)
- The requesting region and the target region are connected by either
of the following:
- An MRO link.
- An APPC single- or parallel-session link. If an APPC link is used,
and the distributed routing program is to be invoked on the target
region, at least one of the following must be true:
- Terminal-initiated transaction routing has previously taken place
over the link. (The terminal-initiated transaction routing enables
the requesting region to determine whether or not the target region
is a CICS Transaction Server for OS/390, Version 1 Release 3 or later system.)
- CICSPlex SM is being used for routing.
- The transaction definition in the requesting region specifies
ROUTABLE(YES).
In addition, if the request is to be routed dynamically:
- The transaction definition in the requesting region must specify
DYNAMIC(YES).
- The SYSID option of the START command must not specify the name
of a remote region. (That is, the remote region on which the transaction
is to be started must not be specified explicitly.)
Important:
When considering which
START-initiated requests are candidates for dynamic routing, you need
to take particular care if the START specifies any of the following
options:
- AT, AFTER, INTERVAL(non-zero), or TIME. That is, there is a delay
before the START is executed.
If there is a delay, the interval
control element (ICE) created by the START request is kept in the
requesting region with a transaction ID of CDFS. The CDFS transaction
retrieves any data specified by the user and reissues the START request
without an interval. The request is routed when the ICE expires, based
on the state of the transaction definition and the sysplex at that
moment.
- QUEUE.
- REQID.
- RTERMID.
- RTRANID.
You need to understand how these options are being used;
whether, for example, they affect the set of regions to which the
request can be routed.
Static routing
The transaction definition in the requesting region specifies ROUTABLE(YES)
and DYNAMIC(NO). If the START request is eligible for enhanced routing
(see above), the distributed routing program--that is, the program
specified on the DSRTPGM system initialization parameter--is
invoked for notification of the statically-routed request.
Notes:
- The distributed routing program differs from the dynamic routing
program, in that it is invoked--for eligible non-terminal-related
START requests where the transaction is defined as ROUTABLE(YES)--even
when the transaction is defined as DYNAMIC(NO). The dynamic routing
program is never invoked for transactions defined as DYNAMIC(NO).
This difference in design means that you can use the distributed routing
program to assess the effect of statically-routed requests on the
overall workload.
- If the request is ineligible for enhanced routing, the distributed
routing program is not invoked.
Dynamic routing
Dynamic routing models
Dynamic routing of non-terminal-related START requests uses the
distributed routing model described in The distributed model.
The transaction definition in the requesting region specifies ROUTABLE(YES)
and DYNAMIC(YES). If the request is eligible for enhanced routing,
the distributed routing program is invoked for routing. The START
request is function-shipped to the target region returned by the routing
program.
Notes:
- If the request is ineligible for enhanced routing, the distributed
routing program is not invoked. Unless the SYSID option specifies
a remote region explicitly, the START request is function-shipped
to the AOR named in the REMOTESYSTEM option of the transaction definition
in the requesting region; if REMOTESYSTEM is not specified, the START
executes locally, in the requesting region.
- If the request is eligible for enhanced routing, but the SYSID
option of the START command names a remote region, the distributed
routing program is invoked for notification only--it cannot route
the request. The START executes on the remote region named on the
SYSID option.
If you intend
to route from CICS TS for z/OS, Version 3.1 to a CICS Transaction Server for OS/390, Version 1 Release 3 region (or vice versa),
you must ensure that the PTF for CICS APAR PQ 75814 is applied to CICS Transaction Server for OS/390, Version 1 Release 3.
If
you use CICSPlex SM for routing, the PTFs for each of the following CICSPlex SM
APARs must be applied to each relevant CICSPlex SM release:
- CICSPlex SM Version 1 Release 4
- PQ80891
- CICSPlex SM Version 2 Release 2
- PQ80893
- CICSPlex SM Version 2 Release 3
- PQ81235

Canceling interval control requests
To cancel a previously-issued START, DELAY, or POST interval control
request, you use the CANCEL command. The REQID option specifies the
identifier of the request to be canceled. If the request is due to
execute on a remote region, you can use the SYSID option to specify
that the CANCEL command is to be shipped to that region.
START and DELAY requests can be canceled only before any interval
specified on the request has expired. If a START request is dynamically
routed, it is kept in the local region until the interval expires,
and can therefore be canceled by a locally-issued CANCEL command on
which the SYSID option is unnecessary. However, in a distributed
routing environment (in which each region can be both a requesting
region and a target region), there may be times when you have no way
of knowing to which region to direct a CANCEL command. For example,
you might want to cancel a DELAY request which could have been issued
on any one of a set of possible regions. To resolve a situation like
this:
- Issue a CANCEL command on which the REQID option specifies the
identifier of the request to be canceled, and the SYSID option is
not specified. The command executes locally.
- Use an XICEREQ global user exit program based on the CICS-supplied
sample program, DFH$ICCN. Your exit program is invoked before the
CANCEL command is executed. DFH$ICCN:
- Checks:
- That it has been invoked for a CANCEL command.
- That the SYSID option was not specified on the command.
- That the identifier of the request to be canceled does not begin
with 'DF'. ('DF' indicates a request issued internally
by CICS.)
- That the name of the transaction that issued the CANCEL command
does not begin with 'C'--that is, that the transaction
is not a CICS internal transaction, nor a CICS-supplied transaction
such as CECI.
If one or more of these conditions are not met--for example,
if it was invoked for a RETRIEVE command--DFH$ICCN does nothing
and returns.
- Instructs CICSPlex SM to:
- Search every CICS region that it knows about for an interval control
request with the identifier (REQID) specified on the CANCEL command.
- On each region, cancel the first request (with the specified identifier)
that it finds. Note that:
- Requests may be canceled on more than one region.
- If a particular region contains more than one request with the
specified identifier, only the first request found by CICSPlex SM is canceled.
- You must ensure that CICSPlex SM has UPDATE access to the transaction
ID of the transaction associated with the CANCEL request.
Note:
For full details of DFH$ICCN’s processing,
see the comments in the sample program.
For details of the CANCEL command, see the CICS Application Programming Reference
manual. For general information about how to write an XICEREQ
global user exit program, see the CICS Customization Guide.
[[ Contents Previous Page | Next Page Index ]]