IBM United States
Software Announcement 203-199
August 5, 2003

IBM SOAP for CICS feature delivers fully supported SOAP access to CICS

 ENUS203-199.PDF (36KB)


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).

Overview

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.

Key prerequisites

  • CICS Transaction Server for z/OS® V2.2

Planned availability date

September 26, 2003

Description

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 ability to dynamically specify the CICS Transaction ID and security context of the application to be different from those performing the SOAP envelope processing.
  • When using HTTP transport, elimination of the need to use a VSAM file for the BTS process used in the SOAP for CICS functional processing. This both reduces customer set up tasks and improves request handling performance by eliminating some BTS-related input/output operations and associated transactional logging.
  • More efficient passing of data during SOAP for CICS processing by eliminating memory copy operations.

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:

  • A SOAP service sample application, which performs a stock quotation example
  • A sample with a 3270 screen that allows CICS to act as a SOAP client, for example to access the previous sample
  • Samples for the User Handler and Application Mapper components

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 (.pdf) format.

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.

Product positioning

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.

Reference information

For the announcement of CICS Transaction Server for z/OS V2.2 refer to Software Announcement 201-354 , 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:

  • Full accessibility
  • High performance memory mapped tracing for Client daemon

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:

  • Support for IBM WebSphere Application Server V5 for z/OS (including z/OSe)
  • Remote Gateway support on IBM WebSphere Application Server for z/OS
  • Full accessibility

For full details, refer to:

Trademarks

 
SupportPac is a trademark of International Business Machines Corporation in the United States or other countries or both.
 
CICS, WebSphere, z/OS, and OS/390 are registered trademarks of International Business Machines Corporation in the United States or other countries or both.
 
Other company, product, and service names may be trademarks or service marks of others.

Technical information

Specified operating environment

Hardware requirements

The hardware requirements for the SOAP for CICS® feature are the same as those for the base product. Refer to Software Announcement 201-354 , dated December 4, 2001.

Software requirements

The SOAP for CICS feature operates with CICS Transaction Server for z/OS® V2.2. Two PTFs are required:

  • PTF for APAR PQ76073.
    • This PTF provides updates to Business Transaction Services.
  • PTF for APAR PQ72017.
    • This PTF provides the DFHWBCLI function for outbound HTTP, which is required by the SOAP for CICS feature. However, it should be noted that the DFHWBCLI function may be withdrawn in a future release of CICS Transaction Server for z/OS: refer to the Compatibility section.

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:

  • For OS/390® V2.10, PTF UQ61947 for APAR PQ53267 and PTF UQ62918 for APAR PQ57816
  • For z/OS V1.2, PTF UQ62894 for APAR PQ57008
  • For z/OS V1.3, PTF UQ67085 for APAR PQ60925
  • For z/OS V1.4, PTF UQ70042 for APAR PQ66155

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:

  • IBM Enterprise COBOL for z/OS and OS/390 Version 3 (5655-G53)

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:

  • IBM Enterprise COBOL for z/OS and OS/390 Version 3 (5655-G53)
  • IBM Enterprise PL/I for z/OS and OS/390 Version 3 (5655-H31)

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.

Performance considerations: Performance information on the SOAP for CICS feature will be available by General Availability. For details, contact your IBM representative.

Planning information

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.

Also delivered with the SOAP for CICS feature is a media pack of WebSphere Studio Enterprise Developer V5.0, together with one Proof of Entitlement allowing full use of this 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:

Current licensees

This feature can be ordered either by customers who are already installed users of CICS Transaction Server for z/OS V2.2, or as part of a new order for CICS Transaction Server for z/OS V2.2.

New licensees

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.

Basic License: To order this feature of CICS Transaction Server for z/OS V2 via the standalone ordering path, specify the program number, 5697-E93, and feature number 9001 for asset registration.

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.

Publications

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.

The User's Guide will be integrated into the CICS Information Center in a future update.

Customized offerings

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 Operational Support Services — Support Line: Yes

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 eServer. 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 eServer 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:

Prices

There is no charge for the SOAP for CICS feature.

Reference information

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 Announcement 201-060 , dated March 13, 2001.

Global financing

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:

Order now

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:  ibm_direct@vnet.ibm.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.

Trademarks

 
Electronic Service Agent is a trademark of International Business Machines Corporation in the United States or other countries or both.
 
CICS, z/OS, Language Environment, OS/390, WebSphere, and Systempac are registered trademarks of International Business Machines Corporation in the United States or other countries or both.
 
Requisite is a registered trademark of IBM Corporation and Rational Software Corporation, in the United States, other Countries or both.
 
Other company, product, and service names may be trademarks or service marks of others.