Troubleshooting
Problem
You want to use a URIMAP with the EXEC CICS INVOKE WEBSERVICE command in order to be able to specify cipher suites for a given Web service endpoint. You might also want to control the URI in a declarative resource based fashion, specify a certificate label, or want the ability to ENABLE or DISABLE the URI. However, the INVOKE WEBSERVICE command does not have a URIMAP option.
Cause
The EXEC CICS INVOKE WEBSERVICE command takes an optional URI as a parameter. If this parameter is not set then the URI that was documented in the Web Services Description Language (WSDL) is used. There is no way to specify a CICS URIMAP resource on this application programming interface (API) prior to CICS Transaction Server for z/OS (CICS TS) V4.1. This is a problem if you want to define a list of cipher suites to associate with a specific URI.
Resolving The Problem
In CICS TS V4.1, the EXEC CICS INVOKE WEBSERVICE command has been improved to allow the application to specify a client mode URIMAP. The mechanism described below continues to function in CICS TS V4.1 and higher, but it is recommended that you make use of the improved API instead.
In CICS TS V3.2, an EXEC CICS INVOKE WEBSERVICE command causes CICS to search through the set of currently installed URIMAPs for a Client mode URIMAP that matches the URI of the remote Web service. If a match is found then the URI specific characteristics stored in that URIMAP are used when establishing a connection to the remote Web service. This capability is new in CICS TS V3.2 and addresses a limitation in CICS TS V3.1.
For example, if there are specific ciphers defined then they are used when establishing a remote Secure Sockets Layer (SSL) or Transport Layer Security (TLS) based socket connection. If a certificate label is specified then it is used when establishing an SSL client certified connection. If the URIMAP is DISABLED then the connection to the remote Web service is refused.
Note: You might need to apply the PTFs for APARs PK49879 and PK66064 to CICS TS V3.2.
How to identify the URI used for a Web service
Every Web service is exposed at an end-point URI. This end-point should be stored in the WSDL document that describes the service. You can discover the URI either by locating it in the WSDL document, or by querying it from the associated WEBSERVICE resource. If CICS knows the URI to use then it will be visible in the 'Endpoint' attribute of the WEBSERVICE resource.
How to create a client mode URIMAP
The CICS TS V3.2 information center contains advice on creating client mode URIMAPs in the section entitled Creating a URIMAP definition for an HTTP request by CICS as an HTTP client.
How to change the URI for a remote Web service through a CICS resource
Another common requirement is to use URIMAPs in order to provide a resource based level of indirection for a URI. For example, you might want to change the target of an INVOKE WEBSERVICE request from a test system to a production system by changing the content of a URIMAP resource. It is possible to achieve this in CICS TS V3.2 (and CICS TS V3.1) if you make use of the EXEC CICS INQUIRE URIMAP() system programming interface (SPI) command. The results returned from this SPI method can be combined to form a URI suitable for use with the INVOKE WEBSERVICE command.
At CICS TS V4.1 (and higher) it is easier to achieve this requirement by referencing a URIMAP resource by name.
Product Synonym
CICS/TS CICS TS CICS Transaction Server
Was this topic helpful?
Document Information
Modified date:
15 June 2018
UID
swg21264638