Dynamic routing of inbound requests in a terminal handler

When the terminal handler of a service provider pipeline is one of the CICS®-supplied SOAP message handlers, the target application handler program specified in container DFHWS-APPHANDLER is, in some cases, eligible for dynamic routing. All pipeline processing before the application handler program is always performed locally in the CICS region that received the SOAP message.

The transaction that runs the target application handler program is eligible for routing when one of the following conditions is true:
  • The transaction under which the pipeline is processing the message is defined as DYNAMIC or REMOTE. This transaction is defined in the URIMAP that is used to map the URI from the inbound SOAP message.
  • A program in the pipeline has changed the contents of container DFHWS-USERID from its initial value.
  • A program in the pipeline has changed the contents of container DFHWS-TRANID from its initial value.
  • A WS-AT SOAP header exists in the inbound SOAP message.

In all the preceding scenarios, a task switch occurs during the pipeline processing. The second task runs under the transaction specified in the DFHWS-TRANID container. This task switch provides an opportunity for dynamic routing to take place, but only if MRO is used to connect the CICS regions together. In addition, the CICS region that you are routing to must support channels and containers.

The routing only takes place if the TRANSACTION definition for the transaction named in DFHWS-TRANID specifies one of the following sets of attributes:
DYNAMIC(YES)
The transaction is routed using the distributed routing model, in which the routing program is specified in the DSRTPGM system initialization parameter.
DYNAMIC(NO) REMOTESYSTEM(sysid)
The transaction is routed to the system identified by sysid.

For more information about the routing of web service requests, see technote: Routing of provider mode CICS Web services.

For applications deployed with the CICS web services assistant, there is a second opportunity to dynamically route the request, at the point where CICS links to the users program. The request is then routed using the dynamic routing model, in which the routing program is specified in the DTRPGM system initialization parameter. Eligibility for routing is determined, in this case, by the characteristics of the program. If you are using a channel and containers when linking to the program, you can only dynamically route the request to CICS regions that are at V3.1 or higher. If you are using a COMMAREA, this restriction does not apply.

When a 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 can, however, be statically routed from the target region to a third region.