Writing a distributed routing program

You can use the CICS-supplied default distributed routing program, DFHDSRP, as a model when writing your own distributed routing program.

For general information about user-replaceable programs, and specific information about how to write a distributed routing program, see Writing a distributed routing program.

When your routing program is called

For processes and activities started by RUN ASYNCHRONOUS commands, your distributed routing program is called at various points on the requesting region and on the target region.

On the requesting region:
  1. Either of these activities:
    • For routing the activity. This routing occurs when the transaction associated with the activity is defined as DYNAMIC(YES).
    • For notification of a statically routed activity. This notification occurs when the transaction associated with the activity is defined as DYNAMIC(NO). The routing program is not able to route the activity. It could, however, do other things.
  2. If an error occurs in route selection. For example, if the target region returned by the routing program on the route selection call is unavailable. This gives the routing program the opportunity to specify an alternate target. This process iterates until the routing program selects a target that is available or sets a non-zero return code.
  3. After CICS has tried (successfully or unsuccessfully) to route the activity to the target region.

    This invocation signals that (unless the requesting region and the target region are one and the same) the responsibility of the requesting region for the 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.

On the target region:
These invocations occur only if the routing program on the requesting region has specified that it must be called again on the target region:
  1. When the activation starts on the target region (that is, when the transaction that implements the activity starts).
  2. If the routed activation (transaction) ends successfully.
  3. If the routed activation (transaction) abends.

Figure 1 shows the points at which the distributed routing program is called, and the region on which each invocation occurs. The "target region" is not necessarily remote - it could be the local (requesting) region, if the routing program chooses to run the activity locally.

Figure 1. When and where the distributed routing program is called
The picture shows two rectangles, one representing the requesting region and the other the target region. Within the requesting region, four labels indicate the points at which the distributed routing program is called: Route selectionNotificationRoute selection errorRouting attempt completeWithin the target region, three labels indicate the points at which the distributed routing program is called: Transaction initiationTransaction terminationTransaction abend

When it is called on the target region for transaction initiation, termination, or abend, the routing program can update a count of BTS activities that are currently running on that region. When it is called on the requesting region for route selection, the routing program can use the counts maintained by all the regions in the routing set (including itself) as input to its routing decision. This routing decision requires that all the regions in the BTS-set have access to a common data store on which the counts are stored. For further details, see Writing a distributed routing program.

Restrictions on the routing program

The distributed routing program runs outside a unit of work environment. Therefore your program must not alter any recoverable resources or issue file control or temporary storage requests.



dfhp9c0076.html | Timestamp icon Last updated: Sunday, 4 June 2017