Traditional routing of transactions started by ATI

Important

This section describes the "traditional" method of routing transactions that are started by automatic transaction initiation (ATI). Wherever possible, you should use the enhanced method described in Routing transactions invoked by START commands. However, you cannot use the enhanced method to route:

For these cases, you must use the "traditional" method described in this section.

Automatic transaction initiation is the process whereby a transaction request made internally within a CICS system or systems network leads to the scheduling of the transaction. ATI requests result from:

EXEC CICS START commands
A START command causes CICS interval control to initiate a transaction after a specified period of time (which may be zero) has elapsed.
Transient data queues
A transient data queue can be defined so that a transaction is automatically initiated when the number of records on the queue reaches a specified level.

CICS transaction routing allows an ATI request for a transaction owned by a particular CICS system to name a terminal that is owned by another, connected system. For example, in Figure 17, an application in AOR1 issues a START request for transaction TRAA to be attached to terminal PRT1.

Although the original ATI request occurs in the AOR, it is sent by CICS to the TOR for execution. So, in the example, AOR1 sends the START request to TOR1 to be executed. In the TOR, the ATI request causes the relay program to be initiated, in conjunction with the specified terminal (PRT1 in the example).

The user transaction in the application-owning region is then accessed in the manner described for terminal-initiated transaction routing. Associated with the request is an automatic initiate descriptor (AID) that specifies the names of the remote transaction (TRAA) and system (AOR1).

For static transaction routing, the terminal-owning region (TOR1) must find a transaction definition that specifies REMOTESYSTEM(AOR1) and REMOTENAME(TRAA); if it cannot, the request fails. 7

For dynamic transaction routing, when DYNAMIC(YES) is coded on the transaction definition, the dynamic routing program is invoked but cannot reroute the request, because the remote system name is taken from the AID. 7

Figure 17. ATI-initiated transaction routing
 The picture illustrates the scenario described in the preceding text. It shows a terminal-owning region (TOR1) and an application-owning region (AOR1). Several terminals are connected to TOR1, including one named PRT1. On TOR1, transaction TRAA is defined as owned by AOR1; terminal PRT1 is defined as a local terminal. On AOR1, transaction TRAA is defined as local; terminal PRT1 is defined as owned by TOR1. On AOR1, a program issues an EXEC CICS START TRANSID(TRAA) TERMID(PRT1) command. Because terminal PRT1 is defined as remote, AOR1 ships the request to the terminal-owning region, TOR1. On TOR1, CICS initiates transaction routing; the CICS relay transaction establishes a link between terminal PRT1 and transaction TRAA on AOR1.

ATI requests are queued in the application-owning region if the link to the terminal-owning region is not available, and subsequently in the terminal-owning region if the terminal is not available.

The overall effect is to create a "single-system" view of ATI as far as the application-owning region is concerned; the fact that the terminal is remote does not affect the way in which ATI appears to operate.

In the application-owning region, the normal rules for ATI apply. The transaction can be initiated from a transient data queue, when the trigger level is reached, or on expiry of an interval control start request. Note particularly that, for transient data initiation, the transient data queue must be in the same system as the transaction. Transaction routing does not enable transient data queue entries to initiate remote transactions.

Shipping terminals for automatic transaction initiation

A CICS system, CICA, can cause an ATI request to be executed in another CICS system, CICB, in several ways. For example:

  1. CICA can function-ship a START request to CICB.
  2. CICA can function-ship WRITEQ requests for a transient data queue owned by CICB, which eventually triggers.
  3. CICA can instigate routing to a transaction in CICB, which then issues a START or writes to a transient data queue.

If the ATI request has a terminal associated with it, CICB searches its resources for a definition for that terminal. If it finds that the terminal is remote, it sends the ATI request to the system that is specified in the REMOTESYSTEM option of the terminal definition. Remember that a terminal-related ATI request is executed in the TOR.

Terminal-not-known condition

Important

The "terminal-not-known condition" frequently occurs, as the example in this section explains, because a terminal-related START command is issued in the terminal-owning region and function-shipped to the application-owning region, where the terminal is not yet defined. If you are able to use the enhanced routing method described in Routing transactions invoked by START commands, a START command issued in a TOR is not function-shipped to the AOR; thus the "terminal-not-known" condition does not occur.

To ensure correct functioning of cross-region ATI, you could define your terminals to all the systems on the network that need to use them. However, you cannot do this if you are using autoinstall. (For information about using autoinstall, see the CICS Resource Definition Guide.) Autoinstalled terminals are unknown to the system until they log on, and you rely on CICS to ship terminal definitions to all the systems where they are needed. (See Shipping terminal and connection definitions.) This works when routing from a terminal to a remote system, but there are cases where a system cannot process an ATI request, because it has not been told the location of the associated terminal.

The example shown in Figure 18 should make this clear:

  1. The operator at terminal T1 selects the menu transaction M1 on CICA.
  2. The menu transaction M1 runs and the operator selects a function that is implemented by transaction X1 in CICB.
  3. Transaction M1 issues the command:
    EXEC CICS START
         TRANSID(X1)
         TERMID(T1)
    and exits.
  4. Because X1 is defined as a remote transaction owned by CICB, CICA function-ships the START command to CICB.
  5. CICB now processes the START command and, in doing so, tries to discover which region owns T1, because this is the region that has to execute the ATI request resulting from the START command.
  6. Only if a definition of T1, resulting from an earlier routed transaction, is present can CICB determine where to send the ATI request. Assuming no such definition exists, the interval control program rejects the START request with TERMIDERR.

Figure 18. Failure of an ATI request in a system where the termid is unknown
 The picture illustrates the preceding text. It shows a terminal-owning region, CICA, connected to an AOR, CICB. On CICA, terminal T1 and the menu transaction, M1, are defined as local resources; transaction X1 is defined as owned by CICB. On CICB, transaction X1 is defined as local. There are no terminals defined. On CICA, the menu transaction M1 issues an EXEC CICS START TRANSID(X1) TERMID(T1) command. Seeing that X1 is owned by CICB, CICA function-ships the request to CICB. On CICB, the CICS interval control program issues a TERMIDERR error, because CICB has no knowledge of terminal T1.
The global user exits XICTENF and XALTENF

You, as user of the system, know how this routing problem could be solved, and CICS gives you a way of communicating your solution to the system. The two global user exits XICTENF and XALTENF have been provided. XICTENF is driven when interval control processes a START command and discovers the associated termid is not defined to the system. XALTENF is driven from the terminal allocation program also when the termid is not defined.

The terminal allocation program schedules requests resulting both from the eventual execution of a START command and from the transient data queue trigger mechanism. This means that a START command could result in an invocation of both exits.

The program you provide to service one or both of these global user exits has access to a parameter list containing this information:

On exit from the program, you tell CICS whether the terminal exists and, if it does, you supply either the netname or the sysid of the TOR. CICS sends the ATI request to the region you specify. As a result, the terminal definition is shipped from the TOR to the AOR, and transaction routing proceeds normally.

There is therefore a solution to the problem shown in Figure 18. It is necessary only to write a small exit program that returns the CICS-supplied parameters unchanged and sets the return code for ‘netname returned’.

The events that follow are shown in Figure 19:

  1. The interval control program accepts the START command and signals acceptance to the issuing system if this is required.
  2. After the specified interval has expired, or immediately if no interval was specified, the terminal allocation program tries to schedule the ATI request. It finds no terminal defined and takes the exit XALTENF, which again supplies the required netname.
  3. The ATI request is shipped to CICA. CICA allocates a relay transaction, establishes a transaction routing link to transaction X1 in CICB, and ships a copy of the terminal definition for T1 to CICB.

Figure 19. Resolving a ‘terminal not known’ condition on a START request
 The picture illustrates the preceding text. It shows a terminal-owning region, CICA, connected to an AOR, CICB. On CICA, terminal T1 and the menu transaction, M1, are defined as local resources; transaction X1 is defined as owned by CICB. On CICB, transaction X1 is defined as local. There are no terminals defined. On CICA, the menu transaction M1 issues an EXEC CICS START TRANSID(X1) TERMID(T1) command. Seeing that X1 is owned by CICB, CICA function-ships the request to CICB. On CICB, the CICS interval control program, finding that it has no knowledge of terminal T1, drives the XICTENF global user exit. The exit program returns the netname CICA. The CICS terminal allocation program drives the XALTENF global user exit, which also returns the netname CICA. Now that it knows the owner of terminal T1, CICB ships the request to CICA, the terminal-owning region, for routing. CICA allocates a relay transaction, establishes a transaction routing link to transaction X1 in CICB, and ships a copy of the terminal definition for T1 to CICB.

The example in Figure 19 shows only one of many possible configurations. From this elementary example, you can see how to approach a solution for the more complex situations that can arise in multiregion networks.

Resource definition

You do not have to be using autoinstalled terminals to make use of the exits XICTENF and XALTENF. The technique also works with CEDA-installed terminals, if they are defined with SHIPPABLE(YES) specified.

It is important that, although there is no need to have all terminal definitions in place before you operate your network, all links between systems must be fully defined, and remote transactions must be known to the systems that want to use them.

Note:
The ‘terminal not known’ condition can arise in CICS terminal-allocation modules during restart, before any global user exit programs have been enabled. If you want to intervene here too, you must enable your XALTENF exit program in a first-phase PLTPI program (for programming information about PLTPI programs, see the CICS Customization Guide). This applies to both warm start and emergency start.
Important

The XICTENF and XALTENF exits can be used only if there is a direct link between the AOR and the TOR. In other words, the sysid or netname that you pass back to CICS from the exit program must not be for an indirectly connected system.

The exit program for the XICTENF and XALTENF exits

How your exit program identifies the TOR from the parameters supplied by CICS can only be decided by reference to your system design. In the simplest case, you would hand back to CICS the netname of the system that originated the START request. In a more complex situation, you may decide to give each terminal a name that reflects the system on which it resides.

For programming information about the exit program, see the CICS Customization Guide. A sample program is also available in the DFHXTENF member of library CICSTS31.CICS.SDFHSAMP.

Shipping terminals for ATI from multiple TORs

Consider the following network setup:

  1. You have an application-owning region that is connected to two or more terminal-owning regions (TORs) that use the same, or a similar, set of terminal identifiers.
  2. One or more of the TORs issues EXEC CICS START requests for transactions in the AOR.
  3. The START requests are associated with terminals.
  4. You are using shippable terminals, rather than statically defining remote terminals in the AOR.

Now consider the following scenario:

Terminal-owning region TORB issues an EXEC CICS START request for transaction TRANB, which is owned by region AOR1. It is to be run against terminal T1. Meanwhile, terminal T1 on region TORA has been transaction routing to AOR1; a definition of T1 has been shipped to AOR1 from TORA. When the START request arrives at AOR1, it is shipped to TORA, rather than TORB, for transaction routing from terminal T1.

Figure 20 illustrates what happens.

Figure 20. Function-shipped START request started against an incorrect terminal. Because a shipped definition of terminal T1 (owned by TORA) is installed on AOR1, the START request received from TORB is shipped to TORA, for routing, rather than to TORB.
 The picture shows two terminal-owning regions, TORA and TORB, and an application-owning region, AOR1. Both TORs own a terminal called T1. AOR1 owns transactions TRANA and TRANB. Three data flows are shown. First, terminal T1 on TORA runs TRANA on AOR1, by means of transaction routing. A terminal definition for T1 on TORA is shipped to AOR1. Next, a program on TORB issues an EXEC CICS START TRANSID(TRANB) TERMID(T1) request. The request is function-shipped to the application-owning region, AOR1. Finally, AOR1 ships the START request to the terminal-owning region, for routing from T1. Unfortunately, because AOR1 has a definition of terminal T1 on TORA, the request is shipped to the wrong TOR, TORA rather than TORB,

There are two ways to prevent this situation:

  1. This is the preferred method.

    Use the enhanced routing method described in Routing transactions invoked by START commands. A terminal-related START command issued in the terminal-owning region is not function-shipped to the AOR; thus it cannot be shipped back to the wrong TOR. Instead, the START executes directly in the TOR, and the transaction is routed as if it had been initiated from a terminal.

    A definition of the terminal is shipped to the AOR, and the autoinstall user program is called. Your autoinstall user program can then allocate an alias termid in the AOR, to avoid a conflict with the previously installed remote definition. Terminal aliases are described in topic Terminal aliases. For information about writing an autoinstall program to control the installation of shipped definitions, see the CICS Customization Guide.

  2. Use this method if you cannot use the enhanced routing method.

    Code YES on the FSSTAFF system initialization parameter in the AOR. This ensures that, when a START request is received from a terminal-owning region, and a shipped definition for the terminal named on the request is already installed in the AOR, the request is always shipped back to a TOR, for routing, across the link it was received on, irrespective of the TOR referenced in the remote terminal definition. (The only exception to this is if the START request supplies a TOR_NETNAME and a remote terminal with the correct TOR_NETNAME is located; in which case, the request is shipped to the appropriate TOR.)

    If the TOR to which the START request is returned is not the one referenced in the installed remote terminal definition, a definition of the terminal is shipped to the AOR, and the autoinstall user program is called. Your autoinstall user program can then allocate an alias termid in the AOR, to avoid a conflict with the previously installed remote definition.

    For full details of the FSSTAFF system initialization parameter, see the CICS System Definition Guide.

ATI and generic resources

An AOR can issue an EXEC CICS START request against a terminal that is owned by a VTAM® generic resource, without knowing the member of the generic resource group to which the terminal is currently logged on. For details of using ATI with generic resources, see Using ATI with generic resources.

Related concepts
Introduction to CICS dynamic routing
Overview of transaction routing
Terminal-initiated transaction routing
Allocation of remote APPC connections
The relay program
Basic mapping support (BMS)
Defining indirect links for transaction routing
Related tasks
Routing transactions invoked by START commands
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

7.
We are talking here of "traditional" routing of transactions started by START commands. To find out how to use the ROUTABLE option of the transaction definition to specify enhanced routing, see Routing transactions invoked by START commands.

[[ Contents Previous Page | Next Page Index ]]