Knowledge Collection: Web services for CICS



This Knowledge Collection is a focused compilation of links to documents for Web services for CICS Transaction Server for z/OS (CICS TS) 3.1, 3.2, 4.1, 4.2, 5.1, and 5.2.


Knowledge Collections are navigation aids that organize content to help users quickly find relevant information. Knowledge Collections are not designed to be an all-inclusive list of all documents dealing with the specific theme.

If you do not find your solution in the list, you can click on Web services to see all items for this component. You can also search for known problems on the CICS TS Support page or use the MustGather document to collect the necessary documentation to work with support.

Click on the following links to see Web services material related to the specific topics:


If you are new to Web services, you might want to start by looking at the Information Center under Getting started with web services.

IBM MedicaCenter is another resource for CICS TS education, including CICS Web services.

The following resources indicate if they were written for a particular release of CICS TS. The content is generally applicable to later versions, however they have not been updated to include any new functionality of later versions.

  1. Technical Exchange Webcasts (recorded):
    CICS Web Services Part 1 - Development (V3.1, V3.2, and V4.1)
    CICS Web Services Part 2 - Deployment (V3.1, V3.2, and V4.1)
    CICS Web services structure and debugging (V3.1 and V3.2)
    CICS Web Services - Open mic (V3.2)
    Extending SOA and CICS with Web 2.0 (V3.1 and V3.2)
    CICS Web Services - Problems and Pitfalls (V3.1 and V3.2)
    Understanding Urimaps, Pipelines and Webservices for CICS (V3.2)
    Continuing to put the S in SOA (V3.2)

  2. Technical presentations:
    Web services in CICS TS - Technical Overview (V3.1)
    CICS Web services Part 1 - Build Time Component (V3.1)
    CICS Web services capabilities (V3.1)
    Web services for the systems programmer (V3.1, V3.2, and V4.1)

  3. IBM Redbooks publications:
    Considerations for CICS Web Services Performance (V3.2)
    Securing CICS Web Services
    Implementing CICS Web Services (V3.1 and V3.2)
    CICS Web Services Workload Management and Availability (V3.2)
    SOAP Message Size Performance Considerations - Redpaper (V3.1)
    Securing Access to CICS Within an SOA (V3.1)
    Architecting Access to CICS within an SOA (V3.1)
    Application development for CICS Web services (V3.1)
    Developing Web Services Using CICS, WMQ, and WMB (V3.1)

How To

  1. Understanding SOAP Fault messages sent from CICS
    When CICS is used to host Web services, there are various conditions that can result in an error response being returned to the remote client process. These error messages are called 'Fault' messages. You want to know, what is the structure of the SOAP Fault messages sent from a CICS Web service in provider mode?

  2. Parsing SOAP fault messages in CICS TS
    You would like to parse a SOAP fault message from within an application in CICS TS. You can use the new XML parsing application programming interface (API) command TRANSFORM to parse SOAP V1.1 fault messages. If you want to process SOAP V1.2 fault messages then a similar approach can be used.

  3. SOAP Content-type header considerations in CICS
    There are a number of changes that have occurred in CICS Transaction Server for z/OS (CICS TS) regarding SOAP content-type headers, and you are looking for an explanation of some of these.

  4. Performance problem with CICS Web Services
    You are analyzing performance data from CICS Web transactions and notice that the response time is longer than you expect. This item explains how you can improve your response time by setting NODELAYACKS on the TCPCONFIG statement in the TCP/IP PROFILE.

  5. Input and Output SOAP containers are empty after upgrading to CICS TS 3.1 or later
    You have upgraded to CICS Transaction Server for z/OS (CICS TS) V3.1, or later, and you find that your SOAP input and output containers are empty. This item explains that CICS requires the Content-Length header on all inbound HTTP/1.1 messages that have a message body.

  6. How to read WSDL. A bottom up approach
    If you need to write a Web services application based on a Web services Description Language (WSDL) document perhaps the two most important pieces of information you need to know about are the input and output parameters. Faced with a WSDL document for the first time can be a bit daunting. How do you easily locate the bits of information that you are interested in without having to understand all the other information present?

  7. Managing variable cardinality SOAP elements
    When using CICS as a web service provider you can be faced with having to handle a WSDL element with variable cardinality, such as:
    <s:element name="sample_element" type="s:string" minOccurs="0" maxOccurs="unbounded" /> When this is translated by the Web services assistant it appears as a single structure within a C header file such as:
    struct Sample_Element
    char Sample_Element??(255??);
    How can you programmatically access all elements in the structure?


CICS family SupportPacs provide you with a range of downloadable code and documentation that complements the CICS family of products. The following SupportPacs are related to Web services and available at no charge:

CA8K: CICS TS for z/OS: Delivering Atom feeds from CICS
CA1P: Web services samples for use with CICS TS
CA1N: CICS TS - Support for the WebSphere Service Registry and Repository
CA71: CICS Web Services Assistant for Windows
CS04: CICS TS for z/OS WSBind File Display and Change Utility
CA8J: Generate Basic Authentication headers for a CICS HTTP client

For a list of other SupportPacs for CICS, see CICS SupportPacs.

Data Conversion

  1. Diagnosing data conversion errors
    This section of the CICS Information Center will explain some common reasons for data conversion errors, and provide ways to diagnose and solve them.


  1. Diagnosing DFHPI0602 messages and PlisaxaRC SOAP Fault messages
    You send a SOAP message to CICS. CICS issues the following message to report a problem parsing the XML, but you have difficulty knowing how to fix the problem:

    DFHPI0602 The CICS SOAP handler failed to parse a message. The parser error code is error_code. The DFHPIEP return code is return_code. The error was found at offset 'offset' into the message.

  2. Invalid ' ' was found when installing the pipeline
    You are unable to install the pipeline. You receive errors indicating that an invalid ' ' was found.

  3. WSDIR parameter on CEDA DEFINE PIPELINE will not accept data
    You are running CICS Transaction Server and are trying to define a PIPELINE. You entered CEDA DEF PIPE(EXPIPE04) GROUP(PIPE) at a terminal. The CEDA panel that you received back would not allow you to update the WSDIR field. Instead of the usual ==> for the field, you saw:

    You were able to define the pipeline using the DFHCSDUP utility, but after doing so, you cannot update the WSDIR field.

  4. Pipeline definition installs in a disabled status
    You install a PIPELINE definition within CICS and it installs successfully but in a disabled status. When you try to Enable the definition, using the CEMT transaction, it continues to indicate a Disabled status. The CEMT screen displays "ERROR" when you try to enable the definition. PF 9 does not present any additional error messages. You receive message DFHPI0706, indicating PIPELINE resolution failed because it cannot be determined if this is a requester or provider pipeline.


  1. Routing of provider mode CICS Web services
    You would like to route provider mode CICS Web services requests between 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.

  2. DFHWB0723 Response 4 Reason 5 trying to run a WEBSERVICE in CICS
    You are running CICS Transaction Server and receive the following message when trying to call a new webservice:

    DFHWB0723 CWXN The CICS Web analyzer program returned an error response.
    Program name: ARPCWSA. RESPONSE: 4. REASON: 5. Host IP address:xx.xx.xx.xx
    Client IP address: xx.xx.xx.xx TCPIPSERVICE: HTTPNSSL

    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.


  1. COBOL sample code for xsd:choice in mapping level 2.2 and higher
    You are using DFHWS2LS (or DFHSC2LS) to process a WSDL document that contains xsd:choice constructs. At mapping level 2.2 and above DFHWS2LS generates a set of enumerated structures to represent the available options. You would like to know, how can you write a COBOL program to work with these structures?

  2. Performance problems with the CICS Web services assistants
    The CICS Web services assistants (DFHWS2LS and DFHLS2WS) run too slowly and consume excessive amounts of CPU time. You think the length of time it takes to generate a WSBind file is a significant factor in the length of time it takes you to create a CICS Web service. You might also experience OutOfMemory conditions.

  3. DFHLS2WS fails with SIGNAL 29 and RC 137
    You are running the Web services assistant program DFHLS2WS in a CICS Transaction Server for z/OS region. You use this program to transform your language structure to a Web service binding file and a Web service description (WSDL) document. DFHLS2WS fails with a signal 29 and a return code 137.

  4. Customization of generated WSDL using DFHLS2WS
    You use DFHLS2WS to Web service enable existing CICS application programs using CICS Transaction Server for z/OS. You want to avoid the requirement to edit the generated WSDL document by hand in order to correct information. For example, the URI that is indicated for the Web service or the version of SOAP that is used.

  5. SOAP address location contains my-server:my-port
    You are developing a Web services provider application using WebSphere Studio Enterprise Developer (WSED) V5.1.2 as the client. You generated the Web Service Definition Language (WSDL) file using DFHLS2WS. In the WSDL file, the SOAP address location is not updated with your CICS server:port name. It contains my-server:my-port. You would like to know if there a mechanism to update this field using DFHLS2WS.

  6. IEBGENER abends due to over length lines
    You experience problems when copying files from HFS using IEBGENER as part of the DFHWS2LS or DFHLS2WS utility. IEBGENER abends because the HFS source file contains lines with content that is too long for the SYSOUT DCB when copying from HFS to the DD statement.

    DFHWS2LS and DFHLS2WS both specify a SYSOUT DCB with logical record length of 1024 characters. You experience the problem when the stdout or stderr streams from the USS process contain any lines of text longer than this.

  7. Support for white space and variable length values in CICS Web services
    You are either Web service enabling an existing CICS application, or creating a new Web service provider or requester application. You have a requirement to send potentially large volumes of variable length data as part of your SOAP messages. For example, if you have a field whose content might vary from zero length to 1Mb then you do not want to have padding characters for the entire 1Mb in each SOAP message you send from CICS.

WS Security

  1. zSeries cryptographic hardware required to exploit WS-Security capability
    You would like to know the appropriate zSeries cryptographic hardware required to exploit Web Services (WS) Security capability in CICS. This capability relies upon the z/OS Integrated Cryptographic Services Facility (ICSF).

  2. An alternative approach to Basic Authentication for Web Services Security
    You are using the CICS Transaction Server WS-Security support for a basic authentication scenario, but the performance does not reach an acceptable level. This technote offers an alternative approach to implementing basic authentication that performs closer to SSL performance levels.

  3. Provider Pipeline configuration showing Authentication Trust=basic Mode=basic
    You are looking for an example of WS-Security Trust="basic" Mode="basic" to use in your CICS Transaction Server region. This combination allows for a user ID and Password then an asserted identity with just a user ID. You have a trusted service. All users will come in with the same user ID and Password then a unique asserted identification for the actual service.

  4. SOAP fault occurs when using CICS WS-Security
    You are using CICS Web services (WS) Security and a SOAP fault is being returned to the client. The SOAP fault can return various faultcode and faultstring elements that contain XSECCryptoException errors.

Product Alias/Synonym

CICS/TS CICS TS CICS Transaction Server

Document information

More support for:

CICS Transaction Server
Web Services

Software version:

3.1, 3.2, 4.1, 4.2, 5.1, 5.2

Operating system(s):


Reference #:


Modified date:


Translate my page

Content navigation