Defining remote resources for transaction routing

CICS® transactions can be routed to remote regions either statically or dynamically. A transaction that is to be routed may be started in a variety of ways. For example:

The resources you need to define are:

Defining terminals for transaction routing

The information in this section applies only to terminal-related transaction routing--that is, to the routing of:

CICS transaction routing enables a "terminal" that is owned by one CICS system (the terminal-owning region) to be connected to a transaction that is owned by another CICS system (the application-owning region). The terminal- and application-owning regions must be connected either by MRO or by an APPC link.

Most of the terminal and session types supported by CICS are eligible for transaction routing. However, the following terminals are not eligible, and cannot be defined as remote resources:

Both the terminal and the transaction must be defined in both CICS systems, as follows:

  1. In the terminal-owning region:
    1. The terminal must be defined as a local resource (or must be autoinstallable).
    2. The transaction must be defined as a remote resource if it is to be initiated from a terminal or by ATI.
  2. In the application-owning region:
    1. The terminal must be defined as a remote resource (unless a shipped terminal definition will be available; see Shipping terminal and connection definitions).
    2. The transaction must be defined as a local resource.

If transaction routing requests are to be "daisy-chained" across intermediate systems, the rules that have just been stated still apply. In addition, both the terminal and the transaction must be defined as remote resources in the intermediate CICS systems. If you are using non-VTAM® terminals, you also need to define indirect links to the TOR on the AOR and the intermediate systems (see Defining indirect links for transaction routing).

Transactions are defined by resource definition online (RDO).

VTAM terminals are also defined by RDO, but for non-VTAM terminals you must use macro-level definition.

Defining remote VTAM terminals

This section tells you how to define remote VTAM terminals using RDO. However, you do not have to define the terminal on the application-owning region. Instead, you can arrange for a suitable definition to be shipped from the terminal-owning region when it is required. This method is described in Shipping terminal and connection definitions.

Remote VTAM terminals are defined by means of a DEFINE TERMINAL command on which:

Only a few of the various terminal properties need be specified for a remote terminal definition. They are:

Figure 59. Defining a remote VTAM terminal (transaction routing)
DEFINE
 TERMINAL(trmidnt)
 GROUP(groupname)
Terminal identifiers
 TYPETERM(terminal-type)
 NETNAME(netname_of_terminal)
 REMOTESYSTEM(sysidnt_of_next_system)
 REMOTESYSNET(netname_of_TOR)
 REMOTENAME(trmidnt_on_TOR)

The TYPETERM referenced by a remote terminal definition can be a CICS-supplied version for the particular terminal type, or one defined by a DEFINE TYPETERM command. If you are defining a TYPETERM that will be used only for remote terminals, you can ignore the session properties, the paging properties, and the operational properties. You can also ignore BUILDCHAIN in the application features.

Defining remote APPC connections

Remote single-session APPC terminals can be defined by means of TERMINAL and TYPETERM definitions, as described for VTAM terminals in the previous section.

For remote parallel-session APPC systems and devices, you must define a remote connection, as shown in Figure 60. A SESSIONS definition is not required for a remote connection.

Figure 60. Defining a remote APPC connection (transaction routing)
DEFINE
 CONNECTION(sysidnt_of_device)
 GROUP(groupname)
Connection identifiers
 NETNAME(netname_of_device)
Remote attributes
 REMOTESYSTEM(sysidnt_of_next_system)
 REMOTESYSNET(netname_of_TOR)
 REMOTENAME(sysidnt_of_device_on_TOR)
Connection properties
 ACCESSMETHOD(VTAM)
 PROTOCOL(APPC)

Sharing terminal and connection definitions

In some circumstances, two or more CICS systems can share a common CICS system definition (CSD) file. (For information about sharing a CSD, see the CICS System Definition Guide.) If the local and remote systems share a CSD, you need define each terminal and APPC connection only once.

A terminal must be fully defined by means of DEFINE TERMINAL, and must have an associated TYPETERM definition, just like a local terminal definition. In addition:

When such a terminal is installed on the terminal-owning region, a full, local, terminal definition is built. On any other system, a remote terminal definition is built.

Similarly, an APPC connection must be fully defined by means of DEFINE CONNECTION, and must have one or more associated SESSIONS definitions. In addition, the REMOTESYSNET option should specify the netname of the TOR, and the REMOTESYSTEM option the sysidnt by which the TOR knows itself. When such a connection is installed on the terminal-owning region, a full, local, connection definition is built. On any other system, a remote connection definition is built, and the SESSIONS definition is ignored.

Note:
The links you define between systems on the transaction routing path that share common terminal (or connection) definitions must be given the same name. That is, the CONNECTION definitions must be given the name that you specify on the REMOTESYSTEM option of the common TERMINAL definitions.

Shipping terminal and connection definitions

If you are using VTAM terminals on your terminal-owning region, you can arrange for a terminal definition to be shipped from the terminal-owning region to the application-owning region whenever it is required. If you use this method, you need not define the terminal on the application-owning region.

When a remote transaction is invoked from a shippable terminal, the request that is transmitted to the application-owning region is flagged to show that a shippable terminal definition is available. If the application-owning region already has a valid definition of the terminal (which may have been shipped previously), it ignores the flag. Otherwise, it asks for the definition to be shipped.

Shipped terminal definitions are propagated to the connected CICS system using the ISC or MRO sessions providing the connection. When a terminal definition is shipped to another region, the TCTUA is also shipped, except when the principal facility is an APPC parallel session. When a routed transaction terminates, information from the TCTTE and the TCTUA is communicated back to the region that owns the terminal.

Note:
APPC connection definitions and APPC terminal definitions are always shippable; no special resource definition is required.

Terminal definitions can be shipped across intermediate systems. If you use shippable terminals and there is more than one possible path from the AOR to the TOR, you may want to specify the preferred path by defining indirect links to the TOR on the AOR and the intermediate systems (see Defining indirect links for transaction routing).

When a shipped definition is to be installed on an intermediate or application-owning region, the autoinstall user program is invoked in that region. If the name of the shipped definition clashes with that of a remote terminal or connection already installed on the region, CICS assigns an alias to the shipped definition, and passes the alias to the autoinstall user program. (Terminal aliases are described in topic Terminal aliases.) CICS-generated aliases for shipped terminals and connections are recognizable by their first character, which is always '{'. Their remaining three characters can have the values 'AAA' through '999'. Your autoinstall user program can accept a CICS-generated alias, override it, or reject the install. Note that it can also specify an alias for a shipped definition when there is no clash with an installed remote definition.

You need to consider assigning aliases to shipped definitions if, for example, you have two or more terminal-owning regions that use similar sets of terminal identifiers for transaction routing to the same AOR. For information about writing an autoinstall user program to control the installation of shipped terminals, see the CICS Customization Guide.

Shipping terminals for ATI requests

If you require a transaction that is started by ATI to acquire a remote terminal, you normally statically define the terminal to the AOR and any intermediate systems. You do this because, for example, specifying a remote terminal for an intrapartition transient data queue (see Defining intrapartition transient data queues) does not cause a terminal definition to be shipped from the remote system. However, if a shipped terminal definition has already been received, following a previous transaction routing request, the terminal is eligible for ATI requests.

However, if the TOR and AOR are directly connected, CICS does allow you to cause terminal definitions to be shipped to the AOR to satisfy ATI requests. If you enable the user exit XALTENF in the AOR, CICS invokes this exit whenever it meets a "terminal-not-known" condition. The program you code has access to parameters, giving details of the origin and nature of the ATI request. You use these to decide the identity of the region that owns the terminal definition you want CICS to ship for you. A similar user exit, XICTENF, is available for start requests that result from EXEC CICS START.

Remember that XALTENF and XICTENF can be used to ship terminal definitions only if there is a direct link between the TOR and the AOR. See Shipping terminals for automatic transaction initiation for more information.

If you function ship START requests from a terminal-owning region to the application-owning region, you may need to consider using the FSSTAFF (function-shipped START affinity) system initialization parameter. See Shipping terminals for ATI from multiple TORs for more details.

A better way of handling terminal-related START requests is to use the enhanced routing methods described in Routing transactions invoked by START commands. If the START request is issued in the TOR, it is not function-shipped to the AOR: thus the "terminal-not-known" cannot occur; nor do you need to use FSSTAFF to prevent the transaction being started against the "wrong" terminal. Instead, the START executes directly in the TOR, and the transaction is routed as if it had been initiated from a terminal. If you are using shippable terminals, a terminal definition is shipped to the AOR if required.

Defining terminals as shippable

To make a terminal definition eligible for shipping, you must associate it with a TYPETERM that specifies SHIPPABLE(YES):

Figure 61. Defining a shippable terminal (transaction routing)
DEFINE
  TERMINAL(trmidnt)
  GROUP(groupname)
  AUTINSTMODEL(YES|NO|ONLY)
  AUTINSTNAME(name)
  TYPETERM(TRTERM1)
  .
  .
DEFINE
  TYPETERM(TRTERM1)
  .
  .
  SHIPPABLE(YES)

This method can be used for any VTAM terminal. It is particularly appropriate if you use autoinstall in the TOR.

Terminal definitions that have been shipped to an application-owning region eventually become redundant, and must be deleted from the AOR (and from any intermediate systems between the TOR and AOR). For information about this, see Efficient deletion of shipped terminal definitions.

Defining remote non-VTAM terminals

Start of changeNon-VTAM terminals must be defined using resource definition macros: you cannot use RDO.End of change

Note:
Start of change
CICS TS for z/OS, Version 3.1 does not directly support the Telecommunication Access Method (TCAM). However, TCAM is supported indirectly: that is, terminals connected by TCAM/DCB (not TCAM/ACB) to a pre-CICS TS for z/OS Version 3.1 TOR can use transaction routing to gain access to a CICS TS for z/OS, Version 3.1 AOR. Thus, you can define remote (but not local) TCAM terminals to a CICS TS for z/OS, Version 3.1 system.

Start of changeCICS TS for z/OS, Version 3.1 does not support the Basic Telecommunication Access Method (BTAM) at all, even indirectly. Thus, you cannot define remote BTAM terminals.End of change

End of change

A remote non-VTAM terminal requires a full terminal control table entry in the remote system (TOR), and a terminal control table entry in the local system (AOR) that contains sufficient information about the terminal to enable CICS to perform the transaction routing. Data set control information and line information is not required for the definition of a remote terminal.

Non-VTAM terminal definitions are not shippable.

Using resource definition macros, you can define remote non-VTAM terminals in either of two ways:

  1. By means of DFHTCT TYPE=REMOTE macros
  2. By means of normal DFHTCT TYPE=TERMINAL macros preceded by a DFHTCT TYPE=REGION macro

Both methods allow the same terminal definitions to be used to generate the required entries in both the local and the remote system.

Definition using DFHTCT TYPE=REMOTE

The format of the DFHTCT TYPE=REMOTE macro is reproduced here for ease of reference.

Figure 62. Defining a remote non-VTAM terminal (transaction routing)
DFHTCT   TYPE=REMOTE
    ,ACCMETH=access-method
    ,SYSIDNT=name-of-CONNECTION-to-TOR
    ,TRMIDNT=name
    ,TRMTYPE=terminal-type
    [,ALTPGE=(lines,columns)]
    [,ALTSCRN=(lines,columns)]
    [,ALTSFX=number]
    [,DEFSCRN=(lines,columns)]
    [,ERRATT={NO|([LASTLINE][,INTENSIFY]
    [,{BLUE|RED|PINK|GREEN|TURQUOISE|YELLOW
       |NEUTRAL}]
    [,{BLINK|REVERSE|UNDERLINE}])}]
    [,FEATURE=(feature[,feature],...)]
    [,LPLEN={132|value}]
    [,PGESIZE=(lines,columns)]
    [,RMTNAME={name-specified-in-TRMIDNT|name}]
    [,STN2980=number]
    [,TAB2980={1|value}]
    [,TCTUAL=number]
    [,TIOAL={value|(value1,value2)}]
    [,TRMMODL=numbercharacter]
    TCAM SNA Only
    [,BMSFEAT=([FMHPARM][,NOROUTE][,NOROUTEALL]
        [,OBFMT][,OBOPID])]
    [,HF={NO|YES}]
    [,LDC={listname|(aa[=nnn],bb[=nnn],cc[=nnn],...)
    [,SESTYPE=session-type]
    [,VF={NO|YES}]

SYSIDNT specifies the name of the connection to the terminal-owning region. If there is no direct link to the TOR, SYSIDNT must specify the name of an indirect link (see Defining indirect links for transaction routing).

Sharing terminal definitions
Start of change TCAM terminals

This section applies to all supported types of non-VTAM terminals except TCAM. CICS TS for z/OS, Version 3.1 does not support local TCAM terminals and therefore no local definitions are built.

End of change

With the exception of SYSIDNT, the operands of DFHTCT TYPE=REMOTE form a subset of those that can be specified with DFHTCT TYPE=TERMINAL. Any of the remaining operands can be specified. They are ignored unless the SYSIDNT operand names the local system, in which case the macro becomes equivalent to the DFHTCT TYPE=TERMINAL form.

A single DFHTCT TYPE=REMOTE macro can therefore be used to define the same terminal in both the local and the remote systems. A typical use of this method of definition is shown in Figure 63.

Figure 63. Typical use of DFHTCT TYPE=REMOTE macro
  Local System CICL                  Remote System CICR
        AOR                                 TOR        

DFHSIT TYPE=                       DFHSIT TYPE= 
       SYSIDNT=CICL                       SYSIDNT=CICR
                                                      
DFHTCT TYPE=INITIAL,               DFHTCT TYPE=INITIAL,
       ACCMETH=NONVTAM,                   ACCMETH=NONVTAM,
       SYSIDNT=CICL,                      SYSIDNT=CICR,
       .                                  .            
       .                                  .            
                                                       
DFHTCT TYPE=REMOTE,                DFHTCT TYPE=REMOTE,
       SYSIDNT=CICR                       SYSIDNT=CICR
       TRMIDNT=aaaa,                      TRMIDNT=aaaa,
       TRMTYPE=3277,                      TRMTYPE=3277,
       TRMMODL=2,                         TRMMODL=2,  
       ALTSCRN=(43,80)                    ALTSCRN=(43,80)
       .                                   .          
       .                                   .          
DFHTCT TYPE=FINAL                  DFHTCT TYPE=FINAL  

In Figure 63, the same terminal definition is used in both the local and the remote systems.

In the local system, the fact that the terminal sysidnt differs from that of the local system (specified on the DFHTCT TYPE=INITIAL macro) causes a remote terminal entry to be built. In the remote system, the fact that the terminal sysidnt is that of the remote system itself causes the TYPE=REMOTE macro to be treated exactly as if it were a TYPE=TERMINAL macro.

Note:
Start of change
For TCAM terminals, no local terminal definitions are built.
End of change
Note:
For this method to work, the CONNECTION from the local system to the remote system must be given the name of the sysidnt by which the remote system knows itself (CICR in the example).

The terminal identification is "aaaa" in both systems.

Definition using DFHTCT TYPE=REGION

If you use the DFHTCT TYPE=REGION macro, you can define remote terminals in the same way as local terminals, using DFHTCT TYPE=SDSCI, TYPE=LINE, and TYPE=TERMINAL macros.

The definitions must, however, be preceded by a DFHTCT TYPE=REGION macro, which has the following form:

DFHTCT   TYPE=REGION
         ,SYSIDNT={name-of-CONNECTION-to-TOR|LOCAL}

SYSIDNT specifies the name of the connection to the terminal-owning region. If there is no direct link to the TOR, SYSIDNT must specify the name of an indirect link (see Defining indirect links for transaction routing).

Sharing terminal definitions

If SYSIDNT does not name the local system, only the information required to build a remote terminal entry is extracted from the succeeding definitions. DFHTCT TYPE=SDSCI and TYPE=LINE definitions are ignored. Parameters of TYPE=TERMINAL definitions that are not part of the TYPE=REMOTE subset are also ignored.

A return to local system definitions is made by using DFHTCT TYPE=REGION,SYSIDNT=LOCAL.

A typical use of this method of definition is shown in Figure 64.

Figure 64. Typical use of DFHTCT TYPE=REGION macro
 Terminal-Owning Region        Application-Owning Region

   DFHTCT TYPE=INITIAL,           DFHTCT TYPE=INITIAL,
          SYSIDNT=TERM,                  SYSIDNT=TRAN,
          ACCMETH=NONVTAM                ACCMETH=NONVTAM
          .                              .

                                  DFHTCT TYPE=REGION,
                                         SYSIDNT=TERM

   COPY TERMDEFS                  COPY TERMDEFS

                                  DFHTCT TYPE=REGION,
                                         SYSIDNT=LOCAL

   DFHTCT TYPE=FINAL              DFHTCT TYPE=FINAL



In Figure 64, the same copy book of terminal definitions is used in both the terminal-owning region and the application-owning region.

Start of changeIn the terminal-owning region, local terminal entries are built.

Note:
Start of change
For TCAM terminals, no local terminal definitions are built.
End of change
End of change

In the application-owning region, the fact that the sysidnt specified in the TYPE=REGION macro differs from the sysidnt specified in the DFHTCT TYPE=INITIAL macro causes remote terminal entries to be built.

Local and remote names for terminals

CICS uses a unique identifier for every terminal that is involved in transaction routing. The identifier is formed from the applid (netname) of the CICS system that owns the terminal and the terminal identifier specified in the terminal definition on the terminal-owning region.

If, for example, the applid of the CICS system is PRODSYS and the terminal identifier is L77A, the fully-qualified terminal identifier is PRODSYS.L77A.

The following rules apply to all forms of hard-coded remote terminal definitions:

Providing the netname of the TOR

You must always ensure that the remote terminal definition allows CICS to access the netname of the TOR. In the following examples, it is assumed that the applid of the terminal-owning region is PRODSYS.

Figure 65. Identifying a terminal-owning region
VTAM terminal definition   
DEFINE TERMINAL             DEFINE CONNECTION(PD1)     Direct link
REMOTESYSTEM(PD1)           NETNAME(PRODSYS)           to TOR
.                           .
.                           .
VTAM terminal definition
DEFINE TERMINAL             DEFINE CONNECTION(NEXT)    No direct
REMOTESYSTEM(NEXT)          NETNAME(INTER1)            link to TOR
REMOTESYSNET(PRODSYS)
.                           .
.                           .
Non-VTAM terminal definition (method 1)
DFHTCT TYPE=REMOTE,        DEFINE CONNECTION(PD1)      Direct link
SYSIDNT=PD1,               NETNAME(PRODSYS)            to TOR
.                          .
.                          .
Non-VTAM terminal definition (method 2)
DFHTCT TYPE=REGION,        DEFINE CONNECTION(PD1)      Direct link
SYSIDNT=PD1                NETNAME(PRODSYS)            to TOR
.                          .
.                          .
Non-VTAM terminal definition (method 1)
DFHTCT TYPE=REMOTE,        DEFINE CONNECTION(REMT)     No direct
SYSIDNT=REMT,              NETNAME(PRODSYS)            link to TOR
                           ACCESSMETHOD(INDIRECT)
                           INDSYS(NEXT)
DFHTCT TYPE=TERMINAL,
. 
               
Terminal aliases

The name by which a terminal is known in the application-owning region is usually the same as its name in the terminal-owning region. You can, however, choose to call the remote terminal by a different name (an alias) in the application-owning region.

You have to provide an alias if the terminal-owning region and the application-owning region each own a terminal with the same name; you cannot have a local terminal definition and a remote terminal definition with the same name. (Nor can you have two remote terminal definitions (for terminals on different remote regions) with the same name.)

If you use an alias, you must also specify the "real" name of the terminal as its remote name, as follows:

Figure 66. Local and remote names for remote terminals
 The picture shows a terminal-owning region and an application-owning region. The TOR owns a terminal named L77A, and has a local definition of it, with TRMIDNT=L77A. The AOR also owns a terminal named L77A, and has a local definition of it, with TRMIDNT=L77A. The AOR also has a remote definition of terminal L77A owned by the TOR. The remote definition specifies a TRMIDNT of R77A and a REMOTENAME of L77A.

You specify the remote name in the REMOTENAME option of DEFINE TERMINAL or the RMTNAME operand of DFHTCT TYPE=REMOTE.

Defining transactions for transaction routing

This section discusses the definition of transactions that may be invoked by transaction routing. It applies to all forms of transaction routing.

The general form of the CEDA DEFINE command for a transaction is shown in Figure 67.

Figure 67. The CEDA DEFINE TRANSACTION options
  DEFINE
    TRANSACTION(name)
    GROUP(groupname)
    PROGRAM(name)
    TWASIZE(0|value)
    PROFILE(DFHCICST|name)
    PARTITIONSET(name)
    STATUS(ENABLED|DISABLED)
    PRIMEDSIZE(00000|value)
    TASKDATALOC(BELOW|ANY)
    TASKDATAKEY(USER|CICS)
    STORAGECLEAR(NO|YES)
    RUNAWAY(SYSTEM|value)
    SHUTDOWN(DISABLED|ENABLED)
    ISOLATE(YES|NO)
REMOTE ATTRIBUTES
    DYNAMIC(NO|YES)
    REMOTESYSTEM(name)
    REMOTENAME(local-name|remote-name)
    TRPROF(DFHCICSS|name)
    LOCALQ(NO|YES)
    ROUTABLE(NO|YES)
SCHEDULING
    PRIORITY(1|value)
    TCLASS(NO|value)
    TRANCLASS(DFHTLC00|name)
ALIASES
    ALIAS(name)
    TASKREQ(value)
    XTRANID(value)
    TPNAME(name)
    XTPNAME(name)
RECOVERY
    DTIMOUT(NO|value)
    INDOUBT(BACKOUT|COMMIT|WAIT)
    RESTART(NO|YES)
    SPURGE(NO|YES)
    TPURGE(NO|YES)
    DUMP(YES|NO)
    TRACE(YES|NO)
SECURITY
    RESSEC(NO|YES)
    CMDSEC(NO|YES)
    EXTSEC(NO|YES)
    TRANSEC(01|value)
    RSL(00|value|Public)

The way in which a transaction is selected for local or remote execution is determined by the remote attributes that are specified in the transaction definition. 15 There are three possible cases:

  1. The remote attributes specify DYNAMIC(NO), and the REMOTESYSTEM name is either blank or the sysid of the local system.

    In this case, the transaction is executed locally, and transaction routing is not involved.

  2. The remote attributes specify DYNAMIC(NO), and the REMOTESYSTEM name differs from the sysid of the local system.

    In this case, the transaction is routed to the system named in the REMOTESYSTEM option. This is known as static transaction routing. 16

  3. The remote attributes specify DYNAMIC(YES).

    In this case, the decision about where to execute the transaction is taken by your dynamic or distributed routing program. See Two routing programs.

    Note:
    Exceptions to this rule are transactions initiated by EXEC CICS START commands that are ineligible for enhanced routing. For example, if one of these transactions is defined as DYNAMIC(YES), your dynamic routing program is invoked but cannot route the transaction. See Routing transactions invoked by START commands.

The name in the TRANSACTION option is the name by which the transaction is invoked in the local region. TASKREQ can be specified if special inputs, such as a program attention (PA) key, program function (PF) key, light pen, magnetic slot reader, or operator ID card reader, are used.

If there is a possibility that the transaction will be executed locally, the definition must follow the normal rules for the definition of a local transaction. In particular, the PROGRAM option must name a user program that will be installed in the local system. When the transaction is routed to another system, the program associated with it is always the relay program DFHAPRT, irrespective of the name specified in the PROGRAM option.

The PROFILE option names the profile that is to be used for communication between the terminal and the relay transaction (or the user transaction if the transaction is executed locally). For remote execution, the TRPROF option names the profile that is to be used for communication on the session between the relay transaction and the remote transaction-owning system. Information about profiles is given under Defining communication profiles.

When a transaction will always be routed to a remote system, so that the transaction executed in the local system is always the relay transaction, you might want to specify some options for control of the relay transaction:

The method you use to define transactions for routing may differ, depending on whether the transactions are to be statically or dynamically routed.

Static transaction routing

There are two methods of defining transactions that are to be statically routed.

Using separate local and remote definitions

You create a remote definition for the transaction, and install it on the requesting region: the REMOTESYSTEM option must specify the name of the target region (or the name of an intermediate system, if the request is to be "daisy-chained"). You install separate remote definitions for the transaction on any intermediate systems: the REMOTESYSTEM option must specify the name of the next system in the routing chain. You create a local definition for the transaction, and install it on the target region: the REMOTESYSTEM option must be blank, or specify the name of the target region.

If the transaction may be initiated by an EXEC CICS START command, check whether you can use the enhanced routing method described in Routing transactions invoked by START commands. If enhanced routing is possible, define the transaction as ROUTABLE(YES) in the region in which the START will be issued.

If two or more systems along the transaction-routing path share the same CSD, the transaction definitions should be in different groups.

Using dual-purpose definitions

You create a single transaction definition, which is shared between the requesting region and the target region (and possibly between intermediate systems too, if "daisy chaining" is involved). The REMOTESYSTEM option specifies the name of the target region.

If the transaction may be initiated by an EXEC CICS START command, check whether you can use the enhanced routing method described in Routing transactions invoked by START commands. If enhanced routing is possible, specify the single definition as ROUTABLE(YES).

When the definition is installed on each system, the local CICS compares its SYSIDNT with the REMOTESYSTEM name. If they are different (as in the requesting region), a remote transaction definition is created. If they are the same (as in the target region), a local transaction definition is installed.

It is recommended that, for static transaction routing, you use this method wherever possible. Because you have only one set of CSD records to maintain, it provides savings in disk storage and time. However, you can use it only if your systems share a CSD. For information about sharing a CSD, see the CICS System Definition Guide.

Dynamic transaction routing

There are three methods of defining transactions that are to be dynamically routed.

Note:
Using dual-purpose definitions (on which the REMOTESYSTEM option specifies the default target region) is a fourth possible method, but is not recommended for transactions that are to be dynamically routed. This is because the DYNAMIC(YES) attribute on the shared definition causes the dynamic routing program to be invoked unnecessarily in the target region, after the transaction has been routed.
Using separate local and remote definitions

This method is as described under Static transaction routing. It is the recommended method for transactions that may be initiated by terminal-related EXEC CICS START commands.

For dynamic routing of a transaction initiated by a START command, you must define the transaction as ROUTABLE(YES) in the region in which the START command is issued.

Using identical definitions

This is the recommended method for transactions that:

These types of transactions are routed using the distributed routing model, which is a peer-to-peer system--each region can be both a requesting/routing region and a target region. Therefore, the transactions should be defined identically in each participating region. The regions may or may not be able to share a CSD--see the CICS System Definition Guide.

On each TRANSACTION definition:

Note that the "identical definitions" method differs from the "dual-purpose definitions" method in several ways:

Using a single transaction definition in the TOR

This is the recommended method for terminal-initiated transactions. Using it, in the TOR (and in any intermediate systems) you install only one transaction definition that specifies DYNAMIC(YES). This single definition provides a set of default attributes for all transactions that are dynamically routed. The name of the common definition is that specified on the DTRTRAN system initialization parameter. The default name is CRTX, which is the name of a CICS-supplied transaction definition that is included in the CSD group DFHISC.

If, at transaction attach, CICS cannot find an installed resource definition for a user transaction identifier (transid), it attaches a transaction built from the user transaction identifier and the set of attributes taken from the common transaction definition. (If the transaction definition specified on the DTRTRAN parameter is not installed, CICS attaches the CICS-supplied transaction CSAC. This sends message DFHAC2001--"Transaction ‘tranid’ is unrecognized"--to the user’s terminal.) Because the common transaction definition specifies DYNAMIC(YES), CICS invokes the dynamic transaction routing program to select a target application-owning region and, if necessary, name the remote transaction.

In the target AOR, you install a local definition for each dynamically-routed transaction.

If you use this method for all your terminal-initiated transactions:

This greatly simplifies the task of managing resource definitions.

It is recommended that you create your own common transaction definition for dynamic routing, using CRTX as a model. The attributes specified on the CRTX definition are shown in Figure 68.

Figure 68. Main attributes of the CICS-supplied CRTX transaction
  DEFINE
    TRANSACTION(CRTX)
    GROUP(DFHISC)
    PROGRAM(########)
    TWASIZE(00000)
    PROFILE(DFHCICST)
    STATUS(ENABLED)
    TASKDATALOC(ANY)
    TASKDATAKEY(CICS)
REMOTE ATTRIBUTES
    DYNAMIC(YES)
    REMOTESYSTEM()
    REMOTENAME()
    TRPROF(DFHCICSS)
    ROUTABLE(NO)
RECOVERY
    DTIMOUT(NO)
    INDOUBT(BACKOUT)
    RESTART(NO)
    SPURGE(YES)
    TPURGE(YES)

The key parameters of this transaction definition are described below:

DYNAMIC(YES)
This is required for a dynamic transaction routing definition that is specified on the DTRTRAN system initialization parameter. You can change the other parameters when creating your own definition, but must specify DYNAMIC(YES).
PROGRAM(########)
The CICS-supplied default transaction specifies a dummy program name, ########. If your dynamic transaction routing program allows a transaction to run in the local region, and its definition specifies the dummy program name, CICS is unlikely to find such a program, causing a "program-not-found" condition.

You are recommended to specify the name of a program that you want CICS to invoke whenever the transaction:

You can use the local program to issue a suitable response to a user’s terminal in the event that the dynamic routing program decides it cannot route the transaction to a remote system.

TRANSACTION(CRTX)
The name of the CICS-supplied dynamic transaction routing definition. Change this to specify your own transaction identifier.
RESTART(NO)
This attribute is forced for a routed transaction.
REMOTESYSTEM
You can code this to specify a default AOR for transactions that are to be dynamically routed.
ROUTABLE(NO)
This attribute relates to the enhanced routing of transactions initiated by EXEC CICS START commands.

Specifying ROUTABLE(YES) means that, if the transaction is the subject of an eligible START command, it will be routed using the enhanced routing method described in Routing transactions invoked by START commands. You are recommended to:

By reserving the common definition for use with transactions that are started from user-terminals, you prevent transactions that are initiated by terminal-related START commands from being dynamically routed "by accident".

Related concepts
Overview of transaction routing
Which remote resources need to be defined?
Local and remote names for resources
Related tasks
Application programming for CICS transaction routing
Defining remote resources for function shipping
Defining remote resources for DPL
Defining remote resources for asynchronous processing
Defining remote resources for DTP
Defining local resources

15.
We ignore here the special case of an EXEC CICS START command that uses the SYSID option to name the remote region on which the transaction is to run. A remote region named explicitly on a START command takes precedence over one named on the transaction definition.
16.
The REMOTESYSTEM option must name a direct link to another system (not an indirect link nor a remote APPC connection).

[[ Contents Previous Page | Next Page Index ]]