Routing non-terminal-related START requests

This section describes how to use a distributed routing program to dynamically route non-terminal-related EXEC CICS START requests.

Which requests can be dynamically routed?

For a non-terminal-related START request to be eligible for dynamic routing, all of the following conditions must be met:

If the request is fully eligible for dynamic routing, the distributed routing program is invoked for routing. The START request is function-shipped to the target region returned by the routing program.

Notes:
  1. If the request is ineligible for enhanced routing, the distributed routing program is not invoked. Unless the SYSID option of the START command specifies a remote region explicitly, the START request is function-shipped to the target region named in the REMOTESYSTEM option; if REMOTESYSTEM is not specified, the START executes locally.
  2. If the request is eligible for enhanced routing but not for dynamic routing (the transaction may, for example, be defined as DYNAMIC(NO)) the distributed routing program is invoked for notification only--it cannot route the request. Unless the SYSID option of the START command specifies a remote region explicitly, the START request is function-shipped to the target region named in the REMOTESYSTEM option; if REMOTESYSTEM is not specified, the START executes locally.

"Daisy-chaining" is not supported. That is, once a non-terminal-related START request has been dynamically routed to a target region it cannot be dynamically routed from the target to a third region, even though the transaction is defined as ROUTABLE(YES) and DYNAMIC(YES). The transaction may, however, be statically routed from the target region to a third region.

For definitive information about which non-terminal-related START requests are eligible for dynamic routing, see the CICS Intercommunication Guide.

When the distributed routing program is invoked

For non-terminal-related START requests that are eligible for enhanced routing, CICS invokes the distributed routing program at the following points:

On the routing region:12
  1. Either of the following:
    • For routing the request.
    • For notification of a statically-routed request. This occurs when a transaction defined as ROUTABLE(YES) is eligible for enhanced routing but not for dynamic routing because one or both of the following applies:
      • The transaction definition specifies DYNAMIC(NO).
      • The SYSID option of the START command names a remote region explicitly.

      The routing program is not able to route the request. 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 request to the target region.

    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.

On the target region:
These invocations occur only if the target region is CICS TS OS/390®, Version 1 Release 3 or later and the routing program on the routing region has specified that it should be reinvoked on the target region:
  1. When the transaction associated with the request starts on the target region.
  2. If the transaction ends successfully.
  3. If the transaction abends.

Figure 51 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.

Figure 51. 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

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.

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:

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.

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

If an error occurs in route selection--for example, if the sysid returned by the distributed routing program is unavailable or unknown--the routing program is invoked again. When this happens, you have a choice of actions:

  1. You can try to route the request to a different target region, by changing the sysid, and issuing a return code of ‘0’ in DYRRETC.

    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.

  2. You can tell CICS not to continue trying to route the request, by issuing a non-zero return code in DYRRETC.

Using the XICERES exit to check the availability of resources on the target region

You can use an XICERES global user exit program to check that all resources required by the started transaction are available on the target region.

To use the XICERES exit, both the routing region and the target region must support the "resource unavailable" condition (RESUNAVAIL). All the following support the "resource unavailable" condition:

The XICERES exit is invoked, if enabled, on the target region before CICS processes a dynamically-routed START request.

If, for example, the transaction to be started is disabled on the target region, or a required file is missing, your exit program can give the distributed routing program the opportunity to route the request to a different region. To do this, it should set a return code of UERCRESU. This causes CICS to:

  1. Return a RESUNAVAIL condition on the EXEC CICS START command executed by the mirror on the target region. (This condition is not returned to the application program.)
  2. Set the DYRERROR field of the routing program’s communications area to 'F'--resource unavailable.
  3. Reinvoke the routing program, on the routing region, for route selection failure--see If an error occurs in route selection.

For information about writing an XICERES global user exit program, see The XICERES global user exit.

If a required resource is unavailable on the target region, but the XICERES exit is unavailable or disabled (or is enabled but does not set the UERCRESU return code), the client program receives an error response.

Invoking the distributed routing program on the target region

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:

This is effective only if the target region is CICS TS OS/390, Version 1 Release 3 or later.

Each time it is invoked on the target region, the routing program could update a count of transactions 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.

Related concepts
Differences between the distributed and dynamic routing interfaces
Related tasks
Routing BTS activities
Routing method requests for enterprise beans and CORBA stateless objects
Routing by user ID
Dealing with an abend on the target region
Some processing considerations
Naming your distributed routing program
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
Parameters passed to the distributed routing program
Distributed transaction routing sample programs

12.
For non-terminal-related START requests, the routing region--the region which routes the request--is always the requesting region, the region on which the START request is issued.

[[ Contents Previous Page | Next Page Index ]]