IBM SC34-6814-04 - Manual (Page 661)

Figure 63 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 execute the START request locally.
Changing the target CICS region
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 request 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” on page 640.
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.
Telling CICS whether to route the request
When the routing program is invoked for routing, if you want the request 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:
v If the sysids are the same CICS executes the request locally.
v If the two sysids are not the same, CICS routes the request to the remote CICS
region.
If you want CICS to reject the START request, return a non-zero value. The EXEC
CICS START command receives a SYSIDERR condition, with a RESP2 value
indicating that the START request has been rejected by the routing program.
Route selection
Notification
Route selection error
Routing attempt complete
Requesting/routing region
Transaction initiation
Transaction termination
Transaction abend
Target region
Figure 63. When and where the distributed routing program is invoked
Chapter 18. Writing a distributed routing program 639