IMS Enterprise Suite Version 2.1 SOAP Gateway README

Product readme


This readme file contains a list of known issues and workarounds for IBM® IMS™ Enterprise Suite Version 2.1 SOAP Gateway, for both z/OS® and distributed platforms.


Last update: July, 2014

This document contains the latest information about known issues, workarounds, changed product behavior, and updates for IBM IMS Enterprise Suite Version 2.1 SOAP Gateway. This document supplements the IMS Enterprise Suite V2.1 SOAP Gateway documentation in the IBM Information management Software for z/OS Solutions Information Center.

Fixes and enhancements for SOAP Gateway are made available as Authorized Program Analysis Reports (APARs) for z/OS systems. Fixes and enhancements for distributed systems are available for download.

The latest update for SOAP Gateway is V2.1.0.6, equivalent to APARs PI11043 and PI11565 for the z/OS platform.

For the z/OS platform, you must install V2.1 base code and then apply all the pre-requisite APARs to upgrade to the latest version.

For the distributed platforms, you can upgrade from the V2.1 base code, or install the latest version directly.

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


V2.1.0.7 fixes and updates

This update is for the distributed platform only, to include the updated version of IBM SDK Java Technology Edition, Version 6. There are no other changes.

For the z/OS platform, APARs PI10939, PI18480, PI18481, and PI18482 for the Base Services provide the IBM SDK Java Technology Edition, Version 6 update.

V2.1.0.6 fixes and updates

This version is made available for the z/OS platform as APARs PI11043 and PI11565. An accessibility issue with the administrative console was addressed in this version.

APARs PI11041, PI11038, and PI10939 for the Base Services are required for the IBM SDK Java Technology Edition, Version 6 update.

V2.1.0.5 fixes and updates

This version is made available for the z/OS platform as APARs PM88825, PM86774, PM88828, and PM86778. The IBM Java SDK V6 is updated and an internal issue is addressed.

Important: To APPLY the services PM86774 and PM88828 successfully, the SMPPTS data set must have at least 240 cylinders free.

V2.1.0.4 fixes and updates

For the distributed platform, V2.1.0.4 includes the fixes for the following issues:
  1. When concurrent requests are being processed, SOAP faults occur and requests are incorrectly discarded on some occasions.

For the z/OS platform, V2.1.0.4 includes the following APAR:

APAR PM82031:
  • The web services security related server binding and policy files for all SAML token types are overridden by the files for the User Name Token type.

V2.1.0.3 fixes and updates

This version is made available for the z/OS platform only as APAR PM61633. The same issue for the distributed platforms is addressed in V2.1.0.4.
  • APAR PM61633: When concurrent requests are being processes, SOAP faults occur and requests are incorrectly discarded on some occasions.

V2.1.0.2 fixes and updates

APAR PM59150 and APAR PM59637 (PTF UK77061 for both) contain the fixes for the following APARs:
  • APAR PM50047: Error responses for IMS synchronous callout messages are returned in UTF-8 encoding. The messages are unreadable in the ICAL I/O area. With this fix, the error response messages are now converted to EBCDIC format and in all uppercase letters.
  • APAR PM50048: The SOAP Gateway debug log buffer does not take into account the format of the correlation token that is added to synchronous callout request, response, or error messages. The binary format of the correlation token resulted in incorrect offset for the subsequent hexadecimal data in the log. In addition, Cyrillic characters in the data portion are represented by 2 hexadecimal bytes, causing the data to be incorrectly aligned. The issue is corrected.
  • APAR PM50051: For the one-thread-per-tpipe callout thread management configuration, 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 by IMS Connect. Subsequent synchronous callout requests are processed normally. This fix sends a cancel ICAL call with the client ID to IMS Connect to cancel the callout request on the tpipe. The first synchronous callout request after the callout thread restart is now processed normally. 
  • APAR PM52036: For the provider scenario, when a web service is undeployed, the associated service WSDL file and all imported XSD files are removed from the wsdl/ directory in the master configuration. If other web service WSDL files references the same XSD files, later redeployment of those web services would result in unresolved resource errors.

    The issue is caused by the following behaviors:
    1. When a web service is initially deployed, a copy of the service WSDL file and any imported XSD files is stored in the master configuration in the wsdl/ directory if these files are located elsewhere during the deployment. This copy is used when the service is redeployed.
    2. When the web service is undeployed, its service WSDL file and all referenced XSD files in the master configuration are removed.

    This behavior prevents multiple web services to share the same XSD file or import XSD files of the same name but different content. This fix resolves the issue for the provider scenario with the following behavior changes:
    1. When a web service is deployed, the related WSDL and XSD files are bundled into the web service Axis ARchive file (AAR file). SOAP Gateway no longer copies the WSDL and XSD files into the WSDL directory in the master configuration if these files reside somewhere else.
    2. Upon startup, SOAP Gateway now loads web services directly from the AAR files instead of the wsdl/ directory in the master configuration.
    3. When a service is undeployed, only its correlator and AAR files are deleted. No files from the master configuration wsdl/ directory are removed.
    These changes allow multiple provider web services to share the same XSD file, and also to import XSD files with the same name but different content.

    Restrictions: For the consumer (callout) and business event scenarios, you cannot import the same XSD file or have nested XSD import statements.

Other known issues resolved in
  • Problem: Lowercase characters in error response messages to callout requests are not correctly rendered with the UTF-8 code page. Non-error responses are processed correctly.
    Solution: This issue is addressed as a result of the fix for APAR PM50047.
  • Problem: User authentication details from the SOAP message header (when WS-Security is enabled) are not propagated to IMS Connect. The authentication details from the web service connection bundle definition are used instead.
    Solution: This issue is addressed in

V2.1.0.2 includes cumulative fixes and updates in the previous maintenance release, V2.1.0.1. See the following section for bug fixes in V2.1.0.1.

V2.1.0.1 fixes and updates

V2.1.0.1 includes the following fixes and updates:

  • APAR PM50044 (PTF UK75938): For SAML tokens, the NotOnOrAfter attribute should be optional when the tokens are used to validate SOAP message timestamp. Evaluation of the clockSkew value defined in the bindings.xml file should take into consideration the NotOnOrAfter value. With this fix, the NotOnOrAfter value is optional, and is considered when the clockSkew value is evaluated.
  • APAR PM50046 (PTF UK75938): User authentication details from the SOAP message header (when WS-Security is enabled) are not propagated to IMS Connect. The issue is addressed.
  • APAR PM50049 (for Windows only; no PTF for the z/OS platform): The SOAP Gateway server running on Windows should remain running when the Windows user logs off. The SOAP Gateway server can now be installed and run as a Windows service. The server remains running when the user logs off.
    For the Windows service support, new messages and new SOAP Gateway management utility commands are added to support:
    • Installing and uninstalling the SOAP Gateway server as a Windows service
    • Starting, stopping, and checking the status of the SOAP Gateway server as a Windows service. 

Recommended APARs for Java updates for SOAP Gateway running on z/OS:
APARs PM56817, PM57009, and PM56825 provide an updated version of Java (V6.0.9.3) for IMS Enterprise Suite V2.1 that addresses reported memory leak and data corruption issues on the z/OS platform.

Before you upgrade

Save a copy of the following files:
  • Files under the <SOAP_Gateway_installation_dir>/server/webapps/imssoap/xml directory
  • Files under the <SOAP_Gateway_installation_dir>/server/webapps/imssoap/wsdl directory
  • Your .aar files in the <SOAP_Gateway_installation_dir>/server/webapps/imssoap/WEB-INF/services directory

If you customized any server configuration files such as any logging properties or security login configuration, save a backup copy before you upgrade. Examples include the or wsjaas.conf files under the <SOAP_Gateway_installation_dir>/server/webapps/imssoap/WEB-INF directory.

You can roll back to the base version after you upgrade. However, your web service artifacts and custom files and settings are not preserved. All your web servicie artifacts and custom files must be manually added back.

Important: For the z/OS platform, before you SMP/E APPLY the fixes in APAR PM82031 , if the following files were customized, you must make a backup copy. After you APPLY this service, copy them back to the original directories:


where -SGW_DIR- is the SOAP Gateway installation directory.

After you upgrade:
  1. After installing the upgrade, you must run the migration command iogmgmt -migrate to ensure all web service artifacts are up to date.
  2. If you are upgrading from V2.1 or V2.1.0.1:
    • If the WSDL file for your existing provider web service contains XSD import statements, you must manually redeploy your web service.
      Previously, imported XSD files were not bundled into the web service AAR file; instead, they were copied into the SOAP Gateway server WSDL directory. This copy was used to deploy the web service and was loaded into the runtime configuration when the SOAP Gateway server started up. The fix for APAR PM52036 changes the behavior. Starting V2.1.0.2, the imported XSD files are now bundled into the web service AAR file, and when the SOAP Gateway server starts up, instead of scanning the XSD files in the WSDL directory, it loads web services directly from the AAR files. Because the SOAP Gateway server will not be able to find the imported XSD files in the AAR files for migrated web services at startup time, existing web services must be manually redeployed.
    • For the z/OS platform, you must manually remove the IMSSOAPIVP.aar file for the SOAP Gateway IVP before you start the SOAP Gateway server. With this update, a new IMSSOAPIVPService.aar file is added for the SOAP Gateway IVP service. If the old IMSSOAPIVP.aar file is left on the system, when you start the server, you would encounter an error in the job log stating that the IMSSOAPIVPService service is not valid because a service of the same name already exists. An AxisFault is generated because two services cannot have same name. The IMSSOAPIVP.aar file is located in <SOAP_Gateway_installation_dir>/server/webapps/imssoap/WEB-INF/services. You can use the rm UNIX command to remove the file. For example:

      rm -f -Pathprefix-/usr/lpp/ims/imses/V2R1/soap_gw/server/webapps/imssoap/WEB-INF/services/IMSSOAPIVP.aar

      This step is not needed for the distributed platforms. The IBM Installation Manager will handle the removal of the old AAR file during the upgrade.

Known Issues

You might encounter the following problems with IMS Enterprise Suite 2.1 SOAP Gateway. Use the indicated workaround to resolve the issue until a fix is made available.
  • Problem: 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).
    Workaround: Paste the following text in the <SOAP_Gateway_installation_dir>/server/webapps/imssoap/WEB-INF/web.xml file and restart SOAP Gateway:


  • Problem: The CSMOKY status message or other IMS Connect status data is seen inside the first message field of a callout request message.
    Workaround: Fill all of the allocated user data area in a callout message with data. Do not pad with blanks.
  • Problem: Asynchronous callout request response messages are not being received by the IMS application when the LL, ZZ, and trancode are not included in the response message structure.
    Workaround: Left-pad the first field in the response message with 8 blank characters, or include the LL, ZZ, and trancode values.
  • Problem: Web service timeout values are overridden by the timeout value of the first callout request that times out before the external web service returns a response. This timeout value is then used by all subsequent web service requests until the server is restarted.
    Workaround: For all correlators, set  the callout web service timeout value to the largest timeout value needed for any IMS callout requests to receive a response from the external web service.
  • Problem: With IMS Version 11, synchronous callout response messages are prefixed with 0000. Four characters of user data are lost from the end of the message.
    Workaround: Append four blanks to the end of synchronous callout response messages.
  • Problem: A few IOGS messages incorrectly list AIX as one of the supported platforms, when AIX is not a supported platform.
    Workaround: No workarounds. Ignore the AIX listing.
  • Problem: 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.

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 2011, 2013. All Rights Reserved.

Rate this page:

(0 users)Average rating

Add comments

Document information

More support for:

IMS Enterprise Suite
SOAP Gateway

Software version:


Operating system(s):

Linux on System z, Windows, z/OS

Reference #:


Modified date:


Translate my page

Machine Translation

Content navigation