Understanding and using IMS SOAP Web services

SOA message exchange works with IMS transaction processors to keep mainframes on the leading edge of service delivery.

In the last few years, Service Oriented Architecture (SOA) has become a pervasive method for exchanging information between servers. IBM keeps the mainframe in the information exchange mix by providing SOA support for transaction processors like IMS and CICS. This article will discuss the implementation of SOA for IMS platforms.

Understanding IMS SOA
Let’s look at this from the standpoint of Web services. There are three major pieces needed for IMS to support Web services over Simple Object Access Protocol (SOAP).  First is the Rational Developer for System z (RDz), which provides tooling for generating artifacts needed for IMS to provide and consume Web services. The IMS SOAP Gateway manages SOAP requests and communicates with IMS Connect, which forms a pipeline between the SOAP Gateway and IMS.

I should note that IBM includes the SOAP Gateway in the IMS SOA Integration Suite, which is available to IMS licensees at no extra cost.

Enabling IMS SOAP
Implementation must start with RDz, which provides the foundation for IMS SOAP enablement. The tooling supports both bottom-up and top-down service generation. Let’s look at both angles.

The bottom-up approach to service generation exposes existing IMS applications as Web services. RDz provides a wizard that generates Extensible Markup Language (XML) Web Services Descriptor Language (WSDL) files from high-level language copy books (i.e., data structure definitions source modules similar to C header files or Java packages) written in COBOL or PL/1. The process begins with importing the copy books describing the IMS inbound and outbound message formats into RDz. From this information, the RDz wizard generates the following:

  • WSDL, which can be given to any clients wishing to utilize the IMS Web service.
  • COBOL programs that convert between SOAP Gateway XML documents and IMS messages.
  • A correlator file that ties all this stuff together, including the converter name, the target IMS transaction and IMS Connect connection specifications.

Ideally, the bottom-up process can expose an existing IMS application as a Web service without any programming changes. By comparison, the top-down approach to service generation creates high-level language structures from WSDL supplied by a web service provider. Currently the RDz process, WSDL2PLI, is limited to generating PL/1 copy books. The process outputs:

  •  A correlator file serving the same function as named above.
  • COBOL XML converters.
  • A pair of PL/I copy books for every Web service operation.
  • Pairs of optional XML Schema Definition (XSD) files. The XSD files describe the relationship between the SOAP messages and language structures.

Completing the process
After RDz generates the artifacts, there are a few more tasks to do before the IMS can use the Web service. First, for both bottom-up and top-down development, the COBOL XML converters must be uploaded to the host, compiled and linked. The load modules should go into LINKLIST or an APF authorized library available to IMS Connect.  Other artifacts, such as the WSDL and correlator files, must be uploaded to a z/OS Unix System Services (USS) file system to which IMS Connect and the gateway have access.

For top-down development, the RDz generated PL/I copy books should be uploaded to the host for use by programs that need to consume the Web service.

With the gateway  IBM provides the SOAP Gateway deployment utility. The utility, a texted based application, allows a programmer to upload the generated artifacts to a SOAP Gateway. It also allows someone to stop and start a non-z/OS instance of the SOAP Gateway. A programmer can display or alter the properties of all types of SOAP Gateway instances. Finally, the deployment utility provides support for displaying and modifying correlation file properties.

Walking through an IMS SOA request
Once all of the components are in place, IMS be should able to provide and consume Web services. Let’s look at a typical example of how the process works.

To consume an IMS-based Web service, a client sends a SOAP message to the IMS SOAP Gateway. The gateway uses a correlation file to identify the message and decide its fate. Once identified, the gateway transforms the SOAP message into an XML document, which it forwards to IMS Connect along with the target IMS transaction code.

IMS Connect receives the XML document and calls the appropriate, RDz-generated XML converter. The converter changes the XML document into something that looks like an ordinary IMS message. After the transformation, IMS Connect sends the message along to the IMS processor.

IMS queues the input message and schedules the transaction normally. The IMS transaction performs the process and returns an output message to IMS Connect. IMS Connect calls the converter again to change the IMS message into an XML document which it sends to the SOAP Gateway. In the last leg of the journey, the gateway sends a SOAP message back to the requesting client.

As another example, an IMS Web service requestor goes through the same steps in a different order. It begins with an IMS program issuing the ICAL command code that allows it to make synchronous calls to a non-IMS service. An eight-byte resource name in the ICAL parameter list will specify the Open Transaction Management Access resource (OTMA) descriptor.

OTMA uses this descriptor to discover whether the message should go to the SOAP Gateway via IMS Connect. Connect, for its part, calls the corresponding converter module to transform the IMS message into an XML document. After the transformation finishes, IMS Connect sends the document on to the gateway that forwards a SOAP message to the Web service provider. Once the service provider returns a message, the process reverses itself until the waiting IMS transaction receives a response.

Recent enhancements to the SOAP Gateway
IMS Enterprise Suite Fixpack 2 (APARs PM17547 and PM22798) added some enhancements to the SOAP Gateway. For IMS V10 and above, there is support for multiple operation web services, business event enhancements as well as a new management utility. For V11 customers, there are the top-down Web service generation as mentioned above as well as support for in-bound Security Assertion Markup Language (SAML) tokens.  Another security enhancements provides for client authentication through Application Transport Transport Layer Security (AT-TLS) z/OS services

About the author: Robert Crawford has been a systems programmer for 29 years.  While specializing in CICS technical support he has also worked with VSAM, DB2, IMS and assorted other mainframe products.  He has programmed in Assembler, Rexx, C, C++, PL/1 and COBOL.  The latest phase in his career finds him an operations architect responsible for establishing mainframe strategy and direction for a large Insurance company. He lives and works with his family in south Texas.


Dig Deeper on IBM system z and mainframe systems