This section describes how to use a distributed routing program to dynamically route CICS® business transaction services (BTS) processes and activities. It assumes that you have read the introduction to the distributed routing of BTS processes and activities in the CICS Business Transaction Services manual.
Not all activations of BTS processes and activities can be routed.
Processes and activities that are activated asynchronously with the requestor--by means of a RUN ASYNCHRONOUS command--can be routed either dynamically or statically.
Processes and activities that are activated synchronously with the requestor--by means of a RUN SYNCHRONOUS or LINK command--are always run locally. They cannot be routed, neither dynamically nor statically. A RUN SYNCHRONOUS or LINK command issued against an activity whose associated transaction is defined as DYNAMIC(YES), or as residing on a remote region, results in the activity being run locally.
Thus, to be eligible for dynamic routing:
"Daisy-chaining" is not supported. That is, once a BTS activity has been routed to a target region it cannot be re-routed from the target to a third region, even though its associated transaction is defined as DYNAMIC(YES).
For BTS processes and activities started by RUN ASYNCHRONOUS commands, CICS invokes the distributed routing program at the following points:
This invocation signals that (unless the routing region and the target region are one and the same) the routing region’s responsibility for this transaction has been discharged. The routing program might, for example, use this invocation to release any resources that it has acquired on behalf of the transaction.
Figure 48 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs. Note that the "target region" is not necessarily remote--it could be the local (routing) region, if the routing program chooses to run the activity locally.
The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the process or activity is to be routed. This is derived from the value of the REMOTESYSTEM option of the installed transaction definition on the routing region. If REMOTESYSTEM is not specified, the sysid passed is that of the local CICS region.
When it is invoked for route selection, the distributed routing program can change the target region by changing the value in DYRSYSID.
If the specified sysid is invalid, or cannot be found, SYSIDERR is returned to the distributed routing program--which may deal with the error by returning a different sysid--see If an error occurs in route selection.
If the routing program changes the sysid when it is invoked for notification, routing complete, transaction initiation, transaction termination, or abend, the change has no effect.
When the routing program is invoked for routing, if you want the process or activity 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 CICS to treat the request as unserviceable, return a non-zero value. For information about unserviceable requests, see the CICS Business Transaction Services manual.
Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend.
If an error occurs in route selection--for example, if the sysid returned by the distributed routing program is unavailable or unknown--the distributed routing program is invoked again. When this happens, you have a choice of actions:
If this region too is unavailable, the routing program is again invoked for a route selection error. A count of the times the routing program has been invoked for routing purposes for this request is passed in field DYRCOUNT. Use this count to help you decide when to stop trying to route the request.
Sometimes, perhaps because of a transaction affinity, it is essential that an activity should execute on a particular target region, and on no other. If this is the case, and the target region is unavailable, classify the request as unserviceable. Instead of reinvoking the routing program for a route selection error, CICS:
If one of these attempts is successful, CICS issues message DFHSH0108. The routing program is invoked on the routing region for "routing attempt complete", and, if specified, on the target region for "transaction initiation".
The route selection, notification, route selection error, and routing complete invocations of the distributed routing program all occur on the routing region. If the routing program wants to be re-invoked on the target region, it must set the DYROPTER field in the communications area to 'Y'. It must do this on its initial (route selection or notification) invocation--and again, if it is reinvoked for a route selection error.
If the routing program sets DYROPTER to 'Y', it is re-invoked on the target region:
Each time it is invoked on the target region, the routing program could update a count of BTS activities that are currently running on that region. When it is invoked for routing, the routing program could use the counts maintained by all the regions in the routing set (including itself) as input to its routing decision. This requires that each region in the routing set has access to a common data set on which the counts are recorded.