Routing transactions invoked by START commands

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:

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

Advantages of the enhanced method

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.

Terminal-related START commands

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:

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.
 The picture shows the scenario described in the preceding text. A CICS TS 1.3 or later TOR is connected to four CICS TS 1.3 or later AORs, AOR1 through AOR4. The link between the TOR and AOR1 is MRO or APPC parallel-sessions. The links between the TOR and AOR2 through AOR4 are MRO or APPC single- or parallel-sessions. A terminal-related transaction, TRAN1, is defined as ROUTABLE(YES) in AOR1 and as DYNAMIC(NO) REMOTESYSTEM(AOR3) in the TOR. A program on AOR1 issues an EXEC CICS START TRANSID(TRAN1) TERMID(T1) request. CICS ships the request to the terminal-owning region, TOR, for routing. TOR routes the request to AOR3. AOR1 is the requesting region. TOR is the routing region. AOR3 is the target region.

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).
 The picture shows the scenario described in the preceding text. A CICS TS 1.3 or later TOR is connected to four CICS TS 1.3 or later AORs, AOR1 through AOR4. The link between the TOR and AOR1 is MRO or APPC parallel-sessions. The links between the TOR and AOR2 through AOR4 are MRO or APPC single- or parallel-sessions. A terminal-related transaction, TRAN1, is defined as ROUTABLE(YES) in AOR1 and as DYNAMIC(YES) in the TOR. A program on AOR1 issues an EXEC CICS START TRANSID(TRAN1) TERMID(T1) request. CICS ships the request to the terminal-owning region, TOR, for routing. In the TOR, the dynamic routing program runs and routes the request to AOR3. AOR1 is the requesting region. TOR is the routing region. AOR3 is the target region.

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):

  1. The START executes in the TOR.
  2. 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.

Figure 23. Static routing of a terminal-related START command issued in a TOR, using the enhanced method. The TOR and the target region are both CICS TS OS/390, Version 1 Release 3 or later. The TOR and the target region are connected by an MRO or APPC (single- or parallel-session) link. The transaction definition in the TOR specifies DYNAMIC(NO) and ROUTABLE(YES). The REMOTESYSTEM option names the AOR to which the transaction is to be routed.
 The picture shows the scenario described in the preceding text. A CICS TS 1.3 or later TOR is connected to four CICS TS 1.3 or later AORs, AOR1 through AOR4. The links between the TOR and the AORs are MRO or APPC single- or parallel-sessions. A terminal-related transaction, TRAN1, is defined as DYNAMIC(NO) ROUTABLE(YES) REMOTESYSTEM(AOR3) in the TOR. A program on the TOR issues an EXEC CICS START TRANSID(TRAN1) TERMID(T1) request. CICS routes the request to AOR3. TOR is the requesting and routing region. AOR3 is the target region.

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.

Figure 24. Dynamic routing of a terminal-related START command issued in a TOR. The TOR and the target region are both CICS TS OS/390, Version 1 Release 3 or later. The TOR and the target region are connected by an MRO or APPC (single- or parallel-session) link. The transaction definition in the TOR specifies both DYNAMIC(YES) and ROUTABLE(YES).
 The picture shows the scenario described in the preceding text. A CICS TS 1.3 or later TOR is connected to four CICS TS 1.3 or later AORs, AOR1 through AOR4. The links between the TOR and the AORs are MRO or APPC single- or parallel-sessions. A terminal-related transaction, TRAN1, is defined as DYNAMIC(YES) ROUTABLE(YES) in the TOR. A program on the TOR issues an EXEC CICS START TRANSID(TRAN1) TERMID(T1) request. The dynamic routing program runs on the TOR and routes the request to AOR3. TOR is the requesting and routing region. AOR3 is the target region.

Non-terminal-related START commands

For a non-terminal-related START request to be eligible for enhanced routing, all of the following conditions must be met:

In addition, if the request is to be routed dynamically:

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:

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:
  1. 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.
  2. 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:
  1. 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.
  2. 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.
  3. Start of change

    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
    End of change
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:

  1. 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.
  2. 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:
    1. Checks:
      1. That it has been invoked for a CANCEL command.
      2. That the SYSID option was not specified on the command.
      3. That the identifier of the request to be canceled does not begin with 'DF'. ('DF' indicates a request issued internally by CICS.)
      4. 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.

    2. Instructs CICSPlex SM to:
      1. Search every CICS region that it knows about for an interval control request with the identifier (REQID) specified on the CANCEL command.
      2. 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.

Related concepts
Introduction to CICS dynamic routing
Overview of transaction routing
Terminal-initiated transaction routing
Traditional routing of transactions started by ATI
Allocation of remote APPC connections
The relay program
Basic mapping support (BMS)
Defining indirect links for transaction routing
Related tasks
Using the routing transaction (CRTE)
System programming for transaction routing
Defining remote resources for transaction routing
Application programming for CICS transaction routing
Related reference
Appendix A. Intercommunication rules and restrictions checklist

8.
See the list of conditions for START commands to be eligible for enhanced routing.

[[ Contents Previous Page | Next Page Index ]]