Routing provider mode CICS web services

You would like to route provider mode CICS® web services requests between CICS terminal owning regions (TORs) and application owning regions (AORs). You might also want to run the workload under a different transaction or user ID than the default. For the configuration of this environment, you would like to know what options are available. You do not want your application programs to run in the TOR.

There are two opportunities to route workload during the processing of a provider mode CICS web services request. However, there are certain limitations and provisos that must be considered. There are also two opportunities to set the transaction identifier that the workload runs under.

There are several stages to the processing of a provider mode web services request, each of which offers certain opportunities to change the transaction and the user ID under which the workload runs, or allows routing decisions to be made. These processing stages can be loosely thought of as being associated with the following resources in CICS:
  • The URIMAP
  • The PIPELINE
  • The WEBSERVICE

You can use any combination of the described techniques to achieve your desired behavior.

The URIMAP

The URIMAP resource is used to associate specific web services with their URIs. When a SOAP message arrives in CICS, a URIMAP lookup is performed. If a URIMAP is found that matches the URI from the incoming SOAP message, then CICS will use this resource to determine which PIPELINE to use to process the SOAP message.

Two significant fields that exist in the URIMAP are the TRANSACTION and the USERID fields. These fields specify the transaction ID to run the PIPELINE processing under and the user ID to use when attaching this transaction. There are subsequent opportunities to change both of these prior to the application running. If you do not specify these values, CICS will default to using CPIH as the transaction ID (assuming an HTTP based transport mechanism) and will use the region's default user ID. If the SOAP message arrives in CICS over an MQSeries® transport, then the default transaction ID is CPIQ. This transaction is always started in the same region as the URIMAP processing and cannot be routed to a different CICS region.
Note: If you use Transport Layer Security (TLS, also referred to as SSL) to sign and encrypt your SOAP messages, then the request might already be being processed under a user ID other than the default. A user ID might be associated with the certificate used to sign the SOAP message, in which case this alternative user ID will already be in effect.

The URIMAP allows you to specify the transaction ID and user ID statically based on the URI. If you need the ability to set them dynamically based on the content of the SOAP messages, review the PIPELINE section below.

If you create your URIMAP resources automatically during a PIPELINE scan operation, you can specify the values to be used for the TRANSACTION and USERID URIMAP fields when you create your WSBind files. Parameters for this purpose apply to DFHWS2LS and DFHLS2WS called TRANSACTION and USERID. If you are able to pick values for these parameters at the time that the WSBind file is created, it is worth specifying them. If you are unable to do this, you might decide to create URIMAP resources manually or to rely on the PIPELINE processing described below.

The PIPELINE

The processing that occurs within the PIPELINE can be both sophisticated and complex. For most uses, it is easier to route workload during the WEBSERVICE processing. You could consider skipping this section for now and returning if the WEBSERVICE processing information below is insufficient for your requirements.

The transaction that performs the PIPELINE processing (usually CPIH) is attached locally in the same region that performed the URIMAP processing as there is an affinity between the PIPELINE and the transport mechanism. The transaction is even attached locally if the associated resource definition is defined as either Remote or Dynamic.

With the exception of the Application Handler program, any PIPELINE handler programs that are invoked during the PIPELINE processing will also run locally regardless of the program definitions you have supplied.

The Application Handler program interacts directly with the application program. Both static and dynamic routing of the Application Handler program are possible. Dynamic routing occurs if MRO connections are used and a context switch occurs. When a context switch occurs under certain conditions (see context switch for details), a separate task is started under a new Unit of Work (UOW), which drives the CICS Distributed Routing user-exit allowing for customized routing decisions to be made. You might use CICSPlex® SM to make the routing and work-load balancing decisions for you.

You might specify an alternative user ID and transaction to process the Application Handler program than those currently in effect. This is done by populating either the DFHWS-TRANID container or the DFHWS-USERID container. Any handler program that runs as part of the PIPELINE can change one or both of these values. The handler programs have access to the entire contents of the SOAP messages and can make their decisions on a per-message basis. For example, the CICS supplied WS-Security handler program can place a value in the DFHWS-USERID container if WS-Security is in use.

The WEBSERVICE

When a provider mode WSBind file is created using the web services assistants, the PGMNAME parameter must be specified. This parameter identifies the name of the application PROGRAM that implements the web service. CICS performs a Distributed Program Link (DPL) to this PROGRAM after converting the SOAP message into data structures suitable for the application to use. The application program can be hosted in another CICS region such as an AOR.

The DPL causes the CICS Dynamic Routing user-exit to be driven and allows customized routing decisions to be made. You can use CICSPlex SM (CPSM) to make the routing and work-load balancing decisions for you. Both static and dynamic routing are possible and normal DPL considerations do apply.

The part of CICS that performs this DPL is the CICS supplied Application Handler called DFHPITP. DFHPITP runs under the same Userid and Transaction that were in effect after the PIPELINE processing completed. By default the transaction identifier will still be CPIH, unless you have changed it using one of the mechanisms described above. Your application program will run under the same transaction and user ID that DFHPITP is using.

Details on the CICS resource definitions required for the DPL routing model and methods of specifying the name of the remote transaction ID for a DPL can be found in section DPL routing of IBM Redbooks: CICS Web Services Workload Management and Availability (SG24-7144-01).

In most scenarios, it is simpler to use this DPL to implement routing of provider mode web services than to make changes during the PIPELINE processing as described above.

If you do not use WEBSERVICE resources to implement web services in CICS, you will not be using DFHPITP as the Application Handler, in which case your own Application Handlers can make use of DPLs if you want them to do so.