IMS Enterprise Suite Version 1.1 SOAP Gateway README

Product readme


This readme file contains a cumulative list of updates to IBM® IMS™ Enterprise Suite Version 1.1 SOAP Gateway, related installation information, and known issues and workaround.


Last update: June 2013

The latest update for IMS Enterprise Suite 1.1 SOAP Gateway is Fix Pack 6. This readme contains important information about required migration steps for Fix Packs 3 and later. Read this document carefully for issues addressed, known issues and their workarounds, and any migration tasks before upgrading. This readme supplements the IMS Enterprise Suite 1.1 SOAP Gateway documentation in the IBM Information Management Software for z/OS® Solutions Information Center.

Fix Pack 6 is provided for Windows and Linux™ for System z® as an Installation Manager package on the Enterprise Suite download website:

For z/OS, the equivalent functional enhancements and fixes for Fix Pack 6 are provided in the corrective service for APARs PM86784, PM86785, PM88381, and PM88773.

Fix Pack 6 for the z/OS platform prerequisites earlier fixes, including Fix Pack 5 (APARs PM82028 and PM83081), Fix Pack 4 (APARs PM42566 and PM42568), and Fix Pack 3 (APARs PM38023 and PM38024).

Important: See the IMS Enterprise Suite release notes for information about the latest maintenance level of SOAP Gateway for all versions that are in service.


New features and fixes in Fix Pack 6 (APARs PM86784, PM86785, PM88381, and PM88773)

This fix pack includes an updated version of IBM Java SDK V6. The following documented known issue is addressed:

  • Error responses for IMS synchronous callout messages are returned in UTF-8 encoding. The message is unreadable in the ICAL I/O area.
    This issue is addressed in Fix Pack 6. The error responses are now in EBCDIC.

Installation details

To APPLY the services PM86784, PM86785, and PM88381 successfully, the SMPPTS data set must have at least 270 cylinders free.

No special installation steps are required for Fix Pack 6. If you are upgrading from the Version 1.1 base code or Fix Pack 1, you must perform the pre-upgrade and post-upgrade steps described for Fix Pack 3.

New features and fixes in Fix Pack 5 (APARs PM82028 and PM83081)

This fix pack addresses an internal runtime issue.

Installation details

No special installation steps are required for Fix Pack 5. If you are upgrading from the Version 1.1 base code or Fix Pack 1, you must perform the pre-upgrade and post-upgrade steps described for Fix Pack 3.

New features and fixes in Fix Pack 4 (APARs PM42566 and PM42568)

With Fix Pack 3 and earlier, a persistent high workload volume can cause a memory concurrency issue in the SOAP Gateway server. In some cases, this issue can result in SOAP Gateway passing an incorrect XML converter name to IMS Connect. The request then fails with an IRZ0962S error message from the XML converter. This issue is resolved in Fix Pack 4. No other fixes are included.

Installation details

No special installation steps are required for Fix Pack 4. If you skip Fix Pack 2 or Fix Pack 3 and are upgrading from the Version 1.1 base code or Fix Pack 1, you must perform the pre-upgrade and post-upgrade steps described for Fix Pack 3.

New features and fixes in Fix Pack 3 (APARs PM38023 and PM38024)

SOAP Gateway now tries to refresh a connection pool when the previous connection to the same IMS Connect instance encountered an error. This socket reconnect support increases the fault tolerance of SOAP Gateway when a temporary network connection issue occurs or when IMS Connect is recycled. You can recycle IMS Connect as part of your system maintenance without the need to restart SOAP Gateway. The restriction in Fix Pack 2 to restart SOAP Gateway when IMS Connect is restarted is lifted. This function reduces number of errors a client encounters because of IMS Connect availability or connectivity issues. SOAP Gateway does not resubmit the request to avoid duplicate request errors. Upon receiving an error, the client can choose to resubmit the request.

SOAP Gateway can now periodically clean up idle connections in each connection pool to reduce resource usage. You can specify the cleanup interval and the minimum number of idle connections to keep in each connection pool with the iogmgmt -prop command.

The following known issues that were documented in the Fix Pack 2 readme are now fixed:

  • The iogmgmt -migrate command now supports both single- and multi-operation message correlator files.
  • Informational messages now correctly indicate the type of web service or callout application being deployed or undeployed.
  • Informational messages now correctly indicate when the thread pool is starting or stopping.
  • SAML-secured messages no longer receive an "incorrect password" error message from the server after a UNTP-secured request to the same server failed because of an incorrect password.

Fix Pack 3 contains the following cumulative enhancements introduced in Fix Pack 2:
  • For the web service provider scenario where an IMS application is enabled as a web service:
  • Client authentication for the provider scenario is supported by using the Java™ keystore (JKS) on all platforms.
  • Server authentication and client authentication using System Authorization Facility (SAF) keyring for the provider scenario is supported by using the Application Transparent Transport Layer Security (AT-TLS) feature in IBM z/OS Communication Server on the z/OS platform.
  • You can send a Security Assertion Markup Language (SAML) token by using the sender-vouches confirmation method from a client application to SOAP Gateway to dynamically authenticate the user per message.
  • You can plug in your own authentication module to intercept an inbound message to perform additional checks by using a Java Authentication and Authorization Service (JAAS) module.
  • You can generate a PL/I application template from a WSDL file by using Rational® Developer for System z Version 8.0.1 and later. After adding your business logic to the generated PL/I application, you can enable the application as a web service on SOAP Gateway. This approach is known as the top-down approach.
  • A new SOAP Gateway management utility is available that facilitates administrative task automation and provides management flexibility. The SOAP Gateway management utility is a command-line utility that replaces the SOAP Gateway deployment utility.
  • SOAP Gateway provides enhanced performance by storing web service information in a runtime cache. Instead of reading the information from a file system, SOAP Gateway can process request messages more efficiently, and manage changes to web service information with greater flexibility.
  • Multi-operation messages are now supported for the provider and the consumer scenarios. Rational Developer for System z Version 8.0.1 and later can generate correlators and converters for messages that contain multiple operations.
  • Performance for the consumer scenario needs improvements. SOAP Gateway now reuses client HTTP connections and cleans up related resources after the call to the external web service.
  • Excessive logging on the z/OS platform slows down SOAP Gateway I/O, impacting the transaction rate and response time. SOAP Gateway now only sends Write to Operator (WTO) ERROR messages related to the server startup. All other ERROR messages are written to the imssoap.log file that is located in the default directory. Logging to the iimssoap.log file can also be disabled by using the SOAP Gateway management utility.

Fix Pack 3 also contains cumulative fixes from Fix Packs 1 and 2 for APARs PM07229 (UK55284) and PM09532 (UK55289).

Pre-upgrade steps
Create a backup copy of the server.xml file (in the SOAP_Gateway_install_directory/server/ directory) before installing this Fix Pack. If you are migrating from Fix Pack 1 or earlier to Fix Pack 3, also back up all web service artifacts including correlator files (in the SOAP_Gateway_install_directory/server/webapps/imssoap/xml/ directory) and aar files ( in the SOAP_Gateway_install_directory/server/webapps/imssoap/WEB-INF/ directory).

Post-upgrade steps
After installing Fix Pack 3 with Installation Manager, take the following actions to migrate your SOAP Gateway server to the Fix Pack 3 configuration.

1. Installing this service preserves server configuration settings. Use the SOAP Gateway management utility command iogmgmt -view -sgp to verify the server properties after installing Fix Pack 3.

2. Issue the iogmgmt -migrate command to migrate files. The migrate command is cumulative and also applies changes to the correlator XML schema introduced in Fix Pack 2. If you have already migrated to the latest version, the migrate command detects that no update is necessary and does not make any additional changes. You can verify the completion status of a migrate command by viewing the IOGU0012I message in the console log.

3. Open the server.xml file in SOAP_Gateway_install_directory/server/conf directory with a text editor and make the following changes:

Change this line:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

To read:

<!-- <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> -->

Change this line:

<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">

To read:

<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">

Known Issues
You might encounter the following problems with SOAP Gateway Fix Pack 3. Use the indicated workaround to resolve the issue until a fix is made available.
  • The direct upgrade path from Fix Pack 1 to Fix Pack 3 is not supported on the Linux for System z platform.
    nd: You must upgrade to Fix Pack 2 first. After the upgrade is complete, start a command shell and switch directory to SOAP_Gateway_install_directory/migration/BASE1.1_TO_FIXPACK2. Issue the command migration to run the Fix Pack 2 migration tool. Upgrade to Fix Pack 3. After the upgrade is complete, issue the command iogmgmt -migrate.
  • Connection information might be exposed when a user navigates to the SOAP Gateway XML directory through the HTTP protocol (such as http://SOAP_Gateway_server:port/imssoap/xml/connbundle.xml).
    : Paste the following text in the SOAP_Gateway_install_dir/server/webapps/imssoap/WEB-INF/web.xml file and restart SOAP Gateway.



  • In some scenarios, lower-case characters in response messages to callout requests are not correctly rendered with the UTF-8 code page.
    : If you encounter this issue, do not use lower-case characters in response messages to callout requests.
  • In some scenarios, asynchronous callout request response messages are not received by the IMS application.
    : If you encounter this issue, left-pad the first field in the response message with 8 blank characters.
  • Web service timeout values are overridden by the web service timeout value of the first web service invoked when the server starts.
    : Configure web services on the server to use the largest timeout value needed for any of the deployed web services.
  • On the Windows platform only, XSD files included with an import statement in the WSDL file of a deployed web service are not removed when the service is undeployed. This issue does not impact the operation of the SOAP Gateway server.
    : Manually remove unused XSD files from the SOAP Gateway WSDL directory: SOAP_Gateway_install_directory/server/webapps/imssoap/wsdl/
  • Multiple parallel XSD import statements in a WSDL file are not supported. Nested XSD import statements are working correctly.
    : Manually add additional schema definitions to the .aar file of a deployed web service located in the SOAP_Gateway_install_directory/server/webapps/imssoap/WEB-INF/ directory.
  • The iogmgmt -diagnose command does not work.
    : This issue is resolved in Enterprise Suite Version 2.1 SOAP Gateway.
  • If a custom fault message is configured and an error occurs, the error message provided by SOAP Gateway incorrectly includes the name of the XML converter for processing the requests rather than the name of the converter for the fault message, causing confusion about the root cause of the problem. When a custom fault message is configured and an error during request processing occurs, the XML converter for request processing would call the fault converter. When such an error occurs, SOAP Gateway reports the incorrect converter name.
    Workaround: If you are getting an error message reporting issues with a converter and you have custom SOAP fault messages, check the IMS Connect console message for HWSA0380E to identify the actual converter that caused the failure.

Clarifications to product documentation

  • After the SOAP Gateway callout threads are stopped and then restarted (or the server is stopped and restarted), the first synchronous callout request on each tpipe to SOAP Gateway is returned to OTMA with a NAK response. Subsequent synchronous callout requests are processed normally.
  • The callout IVP WSDL file (IMSSOAPCalloutIVP.wsdl) must be updated with the SOAP Gateway server HTTP port number if the port number has been changed from the default. This step is only necessary to use the callout IVP, it does not affect any other SOAP Gateway usage.
  • If a socket connection to IMS Connect is lost and then reconnected while multiple messages are in-flight on that socket, all of the in-flight messages are dropped. Subsequent messages on the socket are processed normally.
  • Undeploying a web service with an absolute path to the correlator XML file deletes the target correlator but does not undeploy the web service. If you use an absolute path to the correlator XML file with the undeploy command, you must point to the copy of the correlator XML file that is stored in the SOAP Gateway XML directory (/server/webapps/imssoap/xml).
  • On the Linux for System z and z/OS platforms, an error occurs when the XML adapter type parameter is used when updating a correlator XML file (iogmgmt -corr -a). Specify the adapter type with underscores instead of spaces. For example, use "IBM_XML_Adapter" instead of "IBM XML Adapter".
  • An error in the configuration of SOAP Gateway SSL can cause IOGC004E errors in SOAP Gateway with HWSP1445E errors in the target IMS Connect host. The HWSP1445E error message contains encrypted characters in the msgid field. To resolve this issue, ensure that no SSL settings (such as keystore name) are configured in the SOAP Gateway connection bundle for the web service if you are not using SSL.

Contacting IBM software support
Contact IBM software support at:

Notices and trademarks


INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

  • Microsoft, Windows, and Windows Server are trademarks of Microsoft Corporation in the United States, other countries, or both.
  • Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
  • Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
  • UNIX is a registered trademark of The Open Group in the United States and other countries.
  • Other company, product, or service names may be trademarks or service marks of others.

Third Party Notices

The Program may include third party code that IBM, not the third party, licenses to Licensee under this Agreement. Notices, if any, for the third party code ("Third Party Notices") are included for Licensee's information only. These notices can be found in the Program's NOTICES file(s). Information on how to obtain source code for certain third party code can be found in the Third Party Notices. If in the Third Party Notices IBM identifies third party code as "Modifiable Third Party Code," IBM authorizes Licensee to 1) modify the Modifiable Third Party Code and 2) reverse engineer the Program modules that directly interface with the Modifiable Third Party Code provided that it is only for the purpose of debugging Licensee's modifications to such third party code. IBM's service and support obligations, if any, apply only to the unmodified Program.

(c) Copyright IBM Corporation 2009, 2013. All Rights Reserved.

Rate this page:

(0 users)Average rating

Document information

More support for:

IMS Enterprise Suite
SOAP Gateway

Software version:


Operating system(s):

Linux, Linux on System z, Windows, z/OS

Reference #:


Modified date:


Translate my page

Machine Translation

Content navigation