Troubleshooting
Problem
You would like to route provider mode CICS Web services requests between CICS Transaction Server for z/OS (CICS TS) terminal owning regions (TORs) and application owning regions (AORs). You might also want to run the workload under a different transaction or userid than the default. You have experienced difficulty in configuring this environment, or would like to know the options that are available. You do not want your application programs to run in the TOR.
Cause
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. The necessary information is available in the CICS Information Center, but you may be having difficulty finding it all.
Resolving The Problem
The following information has been added to the CICS TS documentation under topic Routing provider mode CICS Web Services so this document will be removed from the web sometime soon.
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 Userid 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 following techniques to achieve your desired behavior:
The URIMAP The PIPELINE The WEBSERVICEYou can use any combination of the following 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 TRANSID to run the PIPELINE processing under and the USERID 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 then CICS will default to using 'CPIH' as the TRANSID (assuming an HTTP based transport mechanism) and will use the region's default USERID. If the SOAP message arrives in CICS over an MQSeries transport then the default TRANSID 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 USERID other than the default. A USERID might be associated with the certificate used to sign the SOAP message, in which case this alternative USERID will already be in effect.
The URIMAP allows you to specify the TRANSID and USERID statically based on the URI. If you need the ability to set them dynamically based on the content of the SOAP messages then you should see the PIPELINE section below.
If you create your URIMAP resources automatically during a PIPELINE scan operation then you can specify the values to be used for the Transaction and Userid URIMAP fields when you create your WSBind files. APAR PK23547 for CICS TS V3.1 added parameters to both DFHWS2LS and DFHLS2WS for this purpose called 'TRANSACTION' and 'USERID'. No APARs are required for CICS TS V3.2 or later. If you are able to pick values for these parameters at the time that the WSBind file is created then it is worth specifying them. If you are unable to do this then 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.
Any PIPELINE handler programs, with one exception, that are invoked during the PIPELINE processing will also run locally regardless of the program definitions you have supplied. The exception to this rule is the 'Application Handler'. This program interacts directly with the application program and can be routed remotely, but only if:
- MRO connections are used
- A task switch occurs (see below)
If these conditions are met then the CICS Distributed Routing user-exit is driven which allows for customized routing decisions to be made. Prior to CICS TS V3.1, the only parts of CICS that caused the Distributed Routing user-exit to be used were the Enterprise Java Beans (EJB) and Business Transaction Services (BTS) runtimes. As such the Distributed Routing user-exit might be new to you. You might use CICSPlex SM (CPSM) to make the routing and work-load balancing decisions for you.
You might specify an alternative Userid and Transaction to process the Application Handler program under than is 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. If the values of these containers are not changed then the Application Handler program will run under the current Transaction (usually CPIH) and the current Userid.
Under certain conditions a task switch occurs. This involves a second task being started under a new Unit Of Work. It is this task switch that triggers the distributed routing opportunity. The conditions under which a new task are started are:
- The contents of the DFHWS-TRANID container are changed, or
- The contents of the DFHWS-USERID container are changed, or
- (CICS TS V3.2 only) The current transaction is defined as either Dynamic or Remote, or
- (CICS TS V3.2 only) The SOAP message contains an Application Response Measurement (ARM) correlator.
If you do not change the contents of either the DFHWS-TRANID or the DFHWS-USERID containers then the Application Handler will run under the current Transaction and Userid. If a task switch does not occur then the Application Handler will continue to run under the current task in the local region.
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 Userid 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 4.3.2 DPL routing of the IBM Redbooks publication 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 then you will not be using DFHPITP as the Application Handler. In which case, your own Application Handlers can make use of DPLs if you wish them to do so.
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 then you will not be using DFHPITP as the Application Handler. In which case, your own Application Handlers can make use of DPLs if you wish them to do so.
Related Information
[{"Type":"SW","Line of Business":{"code":"LOB70","label":"Z TPS"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSGMGV","label":"CICS Transaction Server"},"ARM Category":[{"code":"a8m0z00000007gPAAQ","label":"CICS Transaction Server-\u003EWeb Services"}],"ARM Case Number":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"5.2.0;5.3.0;5.4.0;5.5.0;5.6.0"}]
Product Synonym
CICS/TS CICS TS CICS Transaction Server
Was this topic helpful?
Document Information
Modified date:
05 January 2026
UID
swg21252179