Using a CICS distributed routing program

This section describes some of the things you need to consider if you decide to write your own distributed routing program.

How the distributed routing program relates to the dynamic routing program

The two CICS®-supplied user-replaceable programs for dynamic routing complement each other.

The dynamic routing program, DFHDYP
Can be used to route:
The distributed routing program, DFHDSRP
Can be used to route:

The two routing programs:

  1. Are specified on separate system initialization parameters.
  2. Are passed the same communications area. (Certain fields that are meaningful to one program are not meaningful to the other.)
  3. Are invoked at similar points--for example, for route selection, route selection error, and (optionally) at termination of the routed transaction or program-link request.

Together, these three factors give you a good deal of flexibility. You could, for example, do any of the following:

  1. Use different user-written programs for dynamic and distributed routing.
  2. Use the same user-written program for both dynamic and distributed routing.
  3. Use a user-written program for dynamic routing and the CICSPlex® SM routing program for distributed routing, or vice versa.

The distributed routing program differs from the dynamic routing program in several important ways:

  1. The dynamic routing program is invoked only if the resource (the transaction or program) is defined as DYNAMIC(YES). The distributed routing program, on the other hand, is invoked (for eligible non-terminal-related START requests, BTS activities, and method requests for enterprise beans and CORBA stateless objects) even if the associated transaction is defined as DYNAMIC(NO)--though it cannot route the request. This means that the distributed routing program is better able to monitor the effect of statically-routed requests on the relative workloads of the target regions.
  2. Because the dynamic routing program uses the hierarchical "hub" routing model--one routing program controls access to resources on several target regions--the routing program that is invoked at termination of a routed request is the same that was invoked for route selection.

    The distributed routing program, on the other hand, uses the distributed model, which is a peer-to-peer system--the routing program itself is distributed. The routing program that is invoked at initiation, termination, or abend of a routed transaction is not the same program that was invoked for route selection--it is the routing program on the target region.

  3. The distributed routing program is invoked at more points than the dynamic routing program. Figure 54 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs.

Writing a distributed routing program

You can use the CICS-supplied default distributed routing program, DFHDSRP, as a model when writing your own version. For general information about user-replaceable programs, and specific information about how to write a distributed routing program, see the CICS Customization Guide.

When your routing program is invoked

For processes and activities started by RUN ASYNCHRONOUS commands, your distributed routing program is invoked at the following points:

On the requesting region:
  1. Either of the following:
    • For routing the activity. This occurs when the transaction associated with the activity is defined as DYNAMIC(YES).
    • For notification of a statically-routed activity. This 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 requesting region’s responsibility 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 should be reinvoked 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 54 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 (requesting) region, if the routing program chooses to run the activity locally.

Figure 54. When and where the distributed routing program is invoked
 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 invoked:   Route selection Notification Route selection error Routing attempt complete Within the target region, three labels indicate the points at which the distributed routing program is invoked:   Transaction initiation Transaction termination Transaction abend

When it is invoked 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 invoked 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 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 the CICS Customization Guide.

Restrictions on the routing program

Because the distributed routing program executes outside a unit of work environment, your program must not:

Related concepts
The scope of a BTS-set
Dynamic routing of BTS activities
Sysplex support in BTS
Related tasks
Creating a BTS-set
Using CICSPlex SM with BTS
Writing a distributed routing program
[[ Contents Previous Page | Next Page Index ]]