Routing transactions dynamically

This section refers to the dynamic routing of transactions initiated from user terminals or by eligible terminal-related EXEC CICS START commands.

When you define transactions to CICS®, you can describe them as "remote" or "local". Local transactions are always executed in the terminal-owning region; remote transactions can be routed to other regions connected to the terminal-owning region by MRO or APPC (LUTYPE6.2) ISC links.

You can select both the system to which the transaction is to be routed and the transaction’s remote name dynamically, rather than when the transaction is defined to CICS. To do this you must use a dynamic routing program. The CICS-supplied default routing program is called DFHDYP. Its source-level code is supplied in assembler-language, COBOL, PL/I, and C versions. You can write your own program in any of these languages, using the default program as a model.

Dynamic transactions

When you want to route transactions dynamically, you must define them with the value DYNAMIC(YES). (The default value is DYNAMIC(NO).) You must also supply values for both the remote and the local options. This allows CICS to select the appropriate values when the transaction is routed, and to ignore those values that are not needed. For information about defining transactions for dynamic transaction routing, see the CICS Intercommunication Guide.

When the dynamic routing program is invoked

For transactions initiated from user terminals or by eligible terminal-related EXEC CICS START commands, CICS invokes the dynamic routing program as follows:

Figure 45 shows the points at which the dynamic routing program is invoked.

Figure 45. When the dynamic routing program is invoked
 The picture shows a rectangle, representing the requesting region. Within the requesting region, five labels indicate the points at which the dynamic routing program is invoked:   Route selection Notification Route selection error Transaction/link request termination Transaction abend

Information passed to the dynamic routing program

The CICS relay program, DFHAPRT, passes information to the dynamic routing program by means of a communications area. The communications area contains fields that are mapped by the DSECT DFHDYPDS, and is described in detail in Parameters passed to the dynamic routing program. For transaction routing, some of the data passed to the dynamic routing program in the communications area are:

The communications area DSECT contains comments to describe the information passed.

The dynamic routing program can accept these values, or change them, or tell CICS not to continue routing the transaction. The values used depend on the function being performed; that is, some values may be ignored.

The information passed to the dynamic routing program indicates whether the transaction is being routed dynamically or statically. If the transaction is being routed dynamically, the dynamic routing program can change the SYSID or netname to determine where the transaction is to run.

Sometimes, the dynamic routing program may be invoked for transactions that are routed statically. This happens if a transaction defined as DYNAMIC(YES) is initiated by automatic transaction initiation (ATI)--for example, by the expiry of an interval control start request--but the transaction is ineligible for dynamic routing. In this case, the dynamic routing program is called only to notify it of where the transaction is going to run. It cannot change the remote system name, and any changes it makes to the SYSID or NETNAME fields in the communications area are ignored.

For transactions that are run remotely, either because they are defined as remote or because they are dynamically routed to a remote CICS region, CICS monitoring is informed of the SYSID of the remote CICS region. For transactions that the dynamic routing program routes locally, the monitoring field is set to nulls.

Changing the target CICS region

The communications area passed to the dynamic routing program initially contains the system identifier (sysid) and netname of the default CICS region to which the transaction is to be routed. These are derived from the value of the REMOTESYSTEM option of the installed transaction definition. If the transaction definition does not specify a REMOTESYSTEM value, the sysid and netname passed are those of the local CICS region.

The dynamic routing program can change the sysid and netname. If it does so when it is invoked for route selection, the region to which the transaction is routed is determined as follows:

If the NETNAME specified is invalid, or cannot be found, SYSIDERR is returned to the dynamic routing program--which may deal with the error by returning a different SYSID or NETNAME--see If the system is unavailable or unknown.

If the routing program changes the SYSID or NETNAME when it is invoked for notification, the changes have no effect.

Using a common transaction definition in the TOR

The recommended method is to use a single, common definition for all remote transactions that are to be dynamically routed. The name of the common definition is specified on the DTRTRAN system initialization parameter. You can use the REMOTESYSTEM option of the common definition to specify a default AOR to which transactions are to be routed. For information about defining remote transactions for dynamic transaction routing, see the CICS Intercommunication Guide.

Important

To route a transaction defined by the DTRTRAN definition, your dynamic routing program must set the DYRDTRRJ field of the communications area to 'N' (the default is 'Y'). If you leave DYTDTRRJ set to 'Y', the transaction is rejected.

You can test the DYRDTRXN field to check if the transaction passed to your routing program is defined by the DTRTRAN definition. Figure 46 contains skeleton code for routing transactions defined by DTRTRAN.

Figure 46. Example pseudocode to route transactions defined by DTRTRAN
  if DYRDTRXN='Y' then         /* Is DYP invoked because of DTRTRAN */
  do                           /* .. Yes                            */
    Call Find_AOR(sysid)       /*    Select the SYSID of the AOR    */
    if rc=0 then               /*    Is AOR available?              */
    do                         /*    .. Yes                         */
      DYRRETC=RETCOD0          /*       Set OK Return Code          */
      DYRSYSID=sysid           /*       Set the sysid               */
      DYRDTRRJ='N'             /*       Don't reject DTRTRAN defns  */
      ...                      /*       Set other commarea fields   */
    end                        /*                                   */
    else                       /*    .. No                          */
      ...                      /*       AOR unavailable logic       */
  end                          /*                                   */
 

Changing the program name

For transactions defined as DYNAMIC, on invocation of the routing program the DYRLPROG field in the communications area contains the name of the initial program associated with the transaction to be routed. If you decide to route the transaction locally, you can use this field to specify an alternative program to be run. For example, if all remote CICS regions are unavailable and the transaction cannot be routed, you may want to run a program in the local CICS terminal-owning region to send an appropriate message to the user.

Telling CICS whether to route or terminate a transaction

When the routing program is invoked for routing, it can choose whether the transaction should be routed or terminated. If you want the transaction to be routed, whether you have changed any values or not, return a zero value to CICS in field DYRRETC of the communications area. When you return control to CICS with return code zero, CICS first compares the returned SYSID with its own local SYSID:

If you want to terminate the transaction with a message or an abend, set a return code of X'8' (or any other non-zero return code other than X'4').

If you want to terminate the transaction without issuing a message or abend, set a return code of X'4'.

Warning:
Setting a return code of X'4' for APPC transaction routing leads to unpredictable results, and should be avoided.

Returning a value in DYRRETC has no effect when the routing program is invoked for notification or at termination of the transaction.

If the system is unavailable or unknown

The dynamic routing program is invoked again if the remote system name that you specify on the route selection call is not known or is unavailable. When this happens, you have a choice of actions:

A count of the times the routing program has been invoked for routing purposes for this transaction is passed in field DYRCOUNT. Use this count to help you decide when to stop trying to route the transaction.

Invoking the dynamic routing program at end of routed transactions

If you want your dynamic routing program to be invoked again when the routed transaction has completed, you must set the DYROPTER field in the communications area to 'Y' before returning control to CICS. You might want to do this, for example, if you are keeping a count of the number of transactions currently executing on a particular CICS region. However, during this reinvocation, the dynamic routing program should update only its own resources. This is because, at this stage, the final command to the terminal from the application program in the AOR may be pending, and the dynamic routing program is about to terminate.

Invoking the dynamic routing program on abend

If you have set DYROPTER to 'Y', and the routed transaction abends, the dynamic routing program is invoked again to notify it of the abend. You could use this invocation to initiate a user-defined program in response to the transaction abend.

If the routed transaction abends, the DFHAPRT program in the TOR:

  1. Passes back a response to the CICS transaction manager indicating that a transaction abend has occurred
  2. If the dynamic routing program requested to be reinvoked at termination of the transaction (by setting DYROPTER to 'Y' when invoked for routing), reinvokes the dynamic routing program
  3. Returns to CICS transaction manager.

Modifying the initial terminal data

The dynamic routing program should not perform an EXEC CICS RECEIVE or an EXEC CICS GDS RECEIVE command, because this prevents the routed-to transaction from obtaining the initial terminal data.

The CICS relay program, DFHAPRT, places a copy of the user’s initial terminal input into a separate buffer. This information includes SNA presentation services headers for APPC mapped and unmapped conversations. A pointer to this buffer (DYRBPNTR), and its length (DYRBLGTH), are provided in the communications area passed from DFHAPRT to the dynamic routing program.

Note that:

Because the transaction profile has not been queried at this point, uppercase translation has not been performed on the input data unless UCTRAN(YES) is specified on the TYPETERM definition.

Sometimes you may want to modify the initial data input by the user. (It may be necessary to do this if, for example, you change the ID of the remote transaction, using field DYRTRAN of the communications area.) To modify the input data, your routing program should, when invoked for route selection:

  1. Copy the input data pointed to by DYRBPNTR into a named variable, of length DYRBLGTH
  2. Modify the data in the named variable
  3. Use the INPUTMSG option of the EXEC CICS RETURN command to make the modified data available to the application program.

For guidance information about using INPUTMSG on EXEC CICS RETURN commands, see the other methods described in the CICS Application Programming Guide. For programming information about the INPUTMSG option, see the CICS Application Programming Reference manual.

Note:
If, after modifying the input data, the dynamic routing program is reinvoked because an error occurs in routing to the selected transaction, it should "remember" that it has modified the original user-input.

Modifying the application’s communications area

Sometimes you may want to modify the routed application’s communications area. For example, if your routing program changes the ID of the remote transaction, it may also need to change the input communications area passed to the routed application. Field DYRACMAA of the routing program’s communications area enables you to do this; it is a pointer to the application’s communications area.

Start of changeSee also Modifying the application’s containers.End of change

Receiving information from a routed transaction

If your dynamic routing program chooses to be reinvoked at the end of a routed transaction, it can obtain information about the transaction by monitoring its output communications area and output TIOA.

Monitoring the output communications area

A routed transaction can pass information back to the dynamic transaction routing program in its output communications area. When invoked at transaction termination, your routing program can examine the output communications area (pointed to by DYRACMAA). The following is an example of how this facility could be used:

Start of changeSee also Modifying the application’s containers.End of change

Monitoring the output TIOA

When invoked at transaction termination, your routing program can examine the copy of the routed transaction’s output TIOA pointed to by DYRBPNTR. This can be useful, for example, to guard against the situation where one AOR in a CICSplex develops software problems. These may be reported by means of a message to the end user, rather than by a transaction abend. If this happens, the routing program is unaware of the failure and cannot bypass the AOR that has the problem. By reading the output TIOA, your routing program can check for messages indicating specific kinds of failure, and bypass any AOR that is affected.

Some processing considerations

Unit of work considerations

Depending on the terminal type, the CICS relay program, the dynamic routing program, and the routed transaction may constitute a single unit of work. Any protected resources owned by the dynamic routing program could therefore be affected by the syncpoint activity of the routed transaction. This means that these resources may be committed or backed out inadvertently by the routed transaction. If you want to avoid this, you have to define the routing program’s resources as unprotected rather than protected.

Related tasks
Routing DPL requests dynamically
Routing bridge requests dynamically
Routing by user ID
Naming your dynamic routing program
Testing your dynamic routing program
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
Parameters passed to the dynamic routing program
Dynamic transaction routing sample programs

7.
For information about the IBM CICS Interdependency Analyzer for z/OS, see the CICS Interdependency Analyzer for z/OS User's Guide and Reference.

[[ Contents Previous Page | Next Page Index ]]