IBM United States
Software Announcement 203-199
August 5, 2003
IBM SOAP for CICS feature delivers fully supported SOAP access to CICS
At a glance
The SOAP for CICS feature provides a mechanism which allows CICS applications, written in any supported programming language, to communicate via the Simple Object Access Protocol (SOAP). Transports are provided over Hypertext Transfer Protocol (HTTP) and WebSphere MQ. Both inbound and outbound function is provided. The implementation supports SOAP 1.1.
For ordering, contact:
Your IBM representative or the Americas Call Centers at 800-IBM-CALL (Reference: LE001).
The SOAP for CICS® feature delivers an enhanced level of the function already available as a Technology Preview in SupportPac CA1M, as a fully supported product for use in production.
The SOAP for CICS feature enables existing or new CICS applications, written in any supported programming language, to communicate outside of the CICS environment via the Simple Object Access Protocol (SOAP). Message transport is provided over Hypertext Transfer Protocol (HTTP), using functions of CICS Web Support (CWS), and includes support for Secure Sockets Layer (SSL) via HTTPS. Message transport is also provided over WebSphere® MQ. The SOAP protocol is supported at the Version 1.1 level.
The SOAP for CICS feature enables a user-written application layer to map the XML-based SOAP message into a COMMAREA, thus enabling access to COMMAREA-based applications using SOAP messages. SOAP for CICS not only permits existing CICS COMMAREA-based applications to be driven via XML-formatted SOAP messages; it can also be used for new XML-aware applications driven via SOAP messages, and enables CICS applications to issue outbound SOAP messages targeted via SOAP or XML messaging to remote applications.
This feature will help to maximize the re-use of enterprise assets via standard interfaces, enhancing the value of existing applications in the CICS environment.
The SOAP for CICS feature provides enhancements to the function already delivered by the SOAP for CICS Technology Preview, first made available as SupportPac CA1M in March 2003. However, whereas the Technology Preview is provided only for evaluation and/or prototyping, the SOAP for CICS feature is supported for use in production. There are also technical changes in the SOAP for CICS feature, some of which provide improved error handling to assist in problem determination. Other changes enhance performance or provide extended function. Unlike the Technology Preview, SOAP for CICS is here delivered as a feature of CICS Transaction Server for z/OS V2, licensed under the IBM Customer Agreement (ICA); it may be used in production, and is supported by program services.
The SOAP for CICS feature provides an infrastructure to allow CICS applications to service inbound requests and make outbound requests using the Simple Object Access Protocol (SOAP). These SOAP requests are transported over Hypertext Transfer Protocol (HTTP) or WebSphere Message Queuing (WebSphere MQ). The HTTP-based support uses functions provided by CICS Web Support and uses that support to manage security and transaction attributes. This includes the ability to use a Secure Sockets Layer (SSL) connection via the HTTPS protocol (an extension of HTTP running under SSL). The SOAP 1.1 protocol is implemented as described in the SOAP 1.1 specification (except that certain optional parts of the specification are not implemented). The SOAP for CICS feature uses functions provided by CICS Business Transaction Services (BTS, a function of CICS Transaction Server for OS/390® V1.3, and later); it may be used with CICS applications in any supported language.
The SOAP for CICS feature provides an interface to allow access to SOAP header elements. This interface enables custom processing of headers to perform such functions as application specific security checking, logging of requests, or request transformation.
Other enhancements include:
The SOAP for CICS feature can be used to allow access to existing COMMAREA-based applications via SOAP messages. This requires an application layer (referred to as a Message Adapter) to provide a mapping from an XML data stream to the structure employed by the COMMAREA for the relevant application program, plus the corresponding mapping from the returned COMMAREA to XML. This can be accomplished in a number of ways. WebSphere Studio Enterprise Developer (WSED) provides a tool to generate converter routines from COBOL copybooks, which can perform these mappings. Customers may develop mappings using parsing function built into Enterprise COBOL V3 and Enterprise PL/I V3, which is based on SAX (Simple API for XML) techniques.
The SOAP for CICS feature may also be used to develop new CICS applications that issue SOAP requests, targeting a remote server over HTTP or WebSphere Message Queuing. This enables CICS applications to exploit Web services that are hosted on other systems. The DFHWBCLI function has been introduced to provide outbound HTTP support for SOAP for CICS. It may also be used independently of SOAP for CICS, but refer to the warning in the Compatibility section.
The SOAP for CICS feature includes samples, provided both as COBOL source and as compiled modules. These are:
Note that applications written for the Technology Preview will run with the SOAP for CICS feature. For more information, refer to the Compatibility section.
For the SOAP specification, refer to:
Accessibility by people with disabilities
The SOAP for CICS feature has only one user interface, which is the screen in one of the supplied
samples, and can be used with a screen reader. The product documentation is provided in softcopy
Section 508 of the U.S. Rehabilitation Act
The SOAP for CICS feature is capable as of September 26, 2003, when used in accordance with IBM's associated documentation, of satisfying the applicable requirements of Section 508 of the Rehabilitation Act, provided that any assistive technology used with the product properly interoperates with it.
The SOAP for CICS feature enables CICS-based applications to be accessed as Web services within a service-oriented architecture. These may be existing or new applications written in any supported programming language. The applications can be invoked by SOAP requests over either HTTP or WebSphere Message Queuing, without the need for any intermediary application server. SOAP for CICS also enables CICS applications to invoke Web services which are hosted on other systems.
SOAP for CICS may be used within an end-to-end configuration involving WebSphere Application Server, where communication between WebSphere Application Server and CICS is via SOAP requests. Further enablement for this form of interoperation will be introduced in the future.
SOAP for CICS is not intended to replace existing facilities which provide access to CICS applications, such as connection via the CICS Transaction Gateway (using the J2EE Connector Architecture), or connection via IIOP (using the CORBA and EJB architectures), which will continue to be supported. Rather, it enables an additional form of connectivity appropriate for some applications, especially those used within service-oriented or Business to Business architectures.
For the announcement of CICS Transaction Server for z/OS V2.2 refer to Software Announcement
, dated December 4, 2001.
CICS Web pages
For up-to-date information on CICS, refer to:
For the Technology Preview of SOAP for CICS, refer to:
Note: CICS Transaction Gateway V4.0
Program services for CICS Transaction Gateway V4.0 (#0792033), originally scheduled to end on June 30, 2003, have been extended to November 30, 2003.
Note: CICS Universal Client V5.0.1
From August 1, 2003, CICS Universal Client V5.0.1 has been available for download. Enhancements in this modification level include:
For full details, refer to:
Note: CICS Transaction Gateway V5.0.1
From August 1, 2003, CICS Transaction Gateway V5.0.1 has been available for download. Enhancements in this modification level include:
For full details, refer to:
Specified operating environment
The hardware requirements for the SOAP for CICS® feature are the same as those for the base
product. Refer to Software Announcement
, dated December 4, 2001.
The SOAP for CICS feature operates with CICS Transaction Server for z/OS® V2.2. Two PTFs are required:
Note that, unlike the Technology Preview, the SOAP for CICS feature is not available for CICS TS V1.3.
CICS must be configured to support the Language Environment® runtime. Language Environment requires the following PTFs in order to enable the XML parser:
In addition, the PTFs for APAR PQ65085 enable additional COBOL runtime messages if using COBOL adapters generated by WebSphere® Studio Enterprise Developer V5.0.
The SOAP for CICS feature may be used with any client or server that supports SOAP 1.1 via HTTP or WebSphere MQ.
Any Web service is supported that uses the Document/Literal style of encoding. For example, client applications built using the AXIS framework, or frameworks implementing the JAX-RPC specification, or the Microsoft+ .NET framework, may be configured to use this encoding style.
Message Adapters can be written in COBOL, PL/I, Assembler, C, or C++. WebSphere Studio Enterprise Developer V5.0, or later, provides tools to generate conversion routines for mapping SOAP requests to existing COMMAREA interfaces. Use of these tools offers a substantial saving in effort as compared with hand-coding these routines. The code generated by WebSphere Studio Enterprise Developer V5.0 requires:
Customers who do not wish to use WebSphere Studio Enterprise Developer V5.0 to generate the converter routines may code their own converter routines in COBOL or PL/I exploiting the XML parser capability in:
Compatibility: Note that, as described in Software requirements , DFHWBCLI function for outbound HTTP is provided in CICS TS V2.2, for use with the SOAP for CICS feature, but may be withdrawn in a future release of CICS TS, after equivalent support for outbound HTTP is made available through the EXEC CICS interface.
This change will be transparent to applications using SOAP for CICS. However, applications that use the outbound HTTP function independently of SOAP for CICS will need to be altered at that time.
Applications written to run with the SOAP for CICS Technology Preview will run with the SOAP for CICS feature. However, changes would be required to exploit new functions of the feature.
Packaging: The SOAP for CICS feature is delivered only via Customized Offerings, on the media formats available in the Customized Offerings. With it is delivered a Program Directory. (For further information on publications, refer to the Publications section.) There is no separate Licensed Program Specifications document: the SOAP for CICS feature is included in the Licensed Program Specifications of the parent product.
Security, auditability, and control
The SOAP for CICS feature uses the security features of the parent product. These features include outbound HTTP over SSL, provided (refer to the Software requirements section) for the use of SOAP for CICS feature. The customer is responsible for evaluation, selection, and implementation of security features, administrative procedures, and appropriate controls in application systems and communication facilities.
Ordering z/OS through the Internet
ShopzSeries (formerly SHOPS390) provides an easy way to plan and order your z/OS ServerPac or CBPDO. It will analyze your current installation, determine the correct product migration, and present your new configuration based on z/OS. Additional products can also be added to your order (including determination of whether all product Requisite® s are satisfied). ShopzSeries is available in the U.S. and several countries in Europe. In countries where ShopzSeries is not available yet, contact your IBM representative (or Business Partner) to handle your order via the traditional IBM ordering process. For more details and availability, visit the ShopzSeries Web site at:
Orders for new licenses can be placed now. Shipments of the basic machine-readable material are through the Customized Offerings only.
Shipment will begin on the planned availability date.
In addition specify the following feature number:
Feature Description number CICS Transaction Server for z/OS V2: 5882 SOAP for CICS feature
Note that an order placed by the standalone path results in the shipment only of the associated items (refer to the Packaging section), but not of the machine-readable media. In order to receive machine-readable media, an order must be placed via the Customized Offerings.
Basic machine-readable material: This feature ships its executable code via the Customized Offerings (CBPDO, ServerPac, Systempac®). Non-customized items (such as CD-ROMs, Memos, and Hardcopy Publications) continue to be shipped via the stand-alone product. The media type for the items is chosen during the ordering procedure for the Customized Offerings.
The following printed program directory is supplied automatically with the basic machine-readable material:
Form Title number SOAP for CICS: Program Directory GI10-2572
No other hardcopy publications are provided.
The following softcopy publication is provided:
Form Title number SOAP for CICS: User's Guide SC34-6315
This may be downloaded, free of charge, in PDF format from the IBM Publications Center, at:
If hardcopy is required, it can be printed from the PDF.
The Program Directory is also available in PDF format from the Publications Center.
This feature, as with the base product, is shipped only via Customized Offerings (CBPDO, ServerPac, and SystemPac).
Terms and conditions
The terms for CICS Transaction Server for z/OS V2, licensed under the IBM Customer Agreement, are unchanged by this announcement. These terms apply to the SOAP for CICS feature.
IBM Electronic Services
IBM Global Services has transformed its delivery of hardware and software support services to put you on the road to higher systems availability. IBM Electronic Services is a Web-enabled solution that provides you with an exclusive, no-additional-charge enhancement to the service and support on the IBM . You should benefit from greater system availability due to faster problem resolution and pre-emptive monitoring. IBM Electronic Services is comprised of two separate but complementary elements: IBM Electronic Services news page and IBM Electronic Service Agent.
IBM Electronic Services news page provides you with a single Internet entry point that replaces the multiple entry points traditionally used by customers to access IBM Internet services and support. By using the news page, it enables you to gain easier access to IBM resources for assistance in resolving technical problems.
The IBM Electronic Service Agent is no-additional-charge software that resides on your IBM system that is designed to proactively monitor events and transmit system inventory information to IBM on a periodic customer-defined timetable. The IBM Electronic Service Agent tracks system inventory, hardware error logs and performance information. If the server is under a current IBM maintenance service agreement or within the IBM Warranty period, the Service Agent automatically reports hardware problems to IBM. Early knowledge about potential problems enables IBM to provide proactive service that maintains higher system availability and performance. In addition, information collected through the Service Agent will be made available to IBM service support representatives when they are helping answer your questions or diagnosing problems.
To learn how IBM Electronic Services can work for you, visit:
For information on the base product, CICS Transaction Server for z/OS Version 2.2, refer to Software Announcement 201-354 , dated December 4, 2001.
For ordering information for CICS Transaction Server for z/OS Version 2.2, refer to Software
, dated March 13, 2001.
IBM Global Financing offers competitive financing to credit-qualified customers to assist them in acquiring IT solutions. Our offerings include financing for IT acquisition, including hardware, software, and services, both from IBM and other manufacturers or vendors. Offerings (for all customer segments: small, medium, and large enterprise), rates, terms, and availability can vary by country. Contact your local IBM Global Financing organization or visit the Web at:
To order, contact the Americas Call Centers or your local IBM representative.
To identify your local IBM representative, call 800-IBM-4YOU (426-4968).
Phone: 800-IBM-CALL (426-2255) Fax: 800-2IBM-FAX (242-6329) Internet: email@example.com Mail: The Americas Call Centers Dept. LE001 P.O. Box 2690 Atlanta, GA 30301-2690 Reference: LE001
The Americas Call Centers, our national direct marketing organization, can add your name to the mailing list for catalogs of IBM products.
Note: Shipments will begin after the planned availability date.