This readme file describes known issues, workarounds, and updates for the IBM® IMS™ Enterprise Suite Version 2.2 Connect API for Java, for both z/OS® and distributed platforms.
Last update: March 9, 2015
This document contains the latest information about known issues, workarounds, changed product behavior, and updates for IBM IMS Enterprise Suite Version 2.2 Connect API for Java. This document supplements the information in IBM Knowledge Center.
Important: The version of the IBM Java SDK that is provided in the IMS Enterprise Suite Base Services to be installed by IBM Installation Manager has been deprecated (APAR PI33919). Download the latest supported version of Java. For the z/OS platform, see APAR PI33919 for more information and the download instructions for the IBM Java SDK. For Windows, see the download and installation instructions on the IMS Enterprise Suite download website.
Updates and service
An update for the Windows platform generally corresponds to one or more APARs for the z/OS platform. To obtain the fix for Windows, go to the IMS Enterprise Suite download website.
November, 2014: Version 18.104.22.168 for the Windows platform is equivalent to updates that are available in APARs PI18472, PI18473, and PI18474 for the z/OS platform for an updated version of Java.
June, 2014: Version 22.214.171.124 for the Windows platform is equivalent to updates that are available in APARs PI10937, PI11020, PI11039, and PI18479 for the z/OS platform for an updated version of Java.
September, 2013: Version 126.96.36.199 is available for the Windows platform. This fix contains service updates equivalent to APAR PM96945 for the z/OS platform.
August, 2013: Version 188.8.131.52 is available for the Windows platform. This fix contains service updates equivalent to APARs PM86769, PM88068, and PM88962 for the z/OS platform.
March, 2013: Version 184.108.40.206 is available for the Windows platform. This fix contains additional logging functions for client applications. See the Documentation changes section below for more information.
February, 2013: Version 220.127.116.11 is available for the z/OS and Windows platforms. PTF UK91746 for APAR PM81423 contains this service. This fix contains additional logging functions for client applications and updates the log file to display synchronous callout correlation tokens in hexadecimal instead of EBCDIC encoding for readability. See the Documentation changes section below for more information about the new logging controls. Get more information about the APAR and obtain the fix.
For Windows, go to the IMS Enterprise Suite download website to obtain the fix.
February, 2013: Version 18.104.22.168 is available for the z/OS platform. PTF UK91004 for APAR PM77947 contains this service. Get more information about the APAR and obtain the fix.
January, 2013: Version 22.214.171.124 is available for the Windows platform. This service corrects a problem with the value of the retrieved MfsModName property in certain scenarios. This service is a complete replacement for the API library.
November, 2012: A fix for APAR PM75838 is now available for the z/OS platform. This service includes fixes for several minor issues. The base 2.2.0 version for Windows includes these fixes. Get more information about this APAR and obtain the fix.
Problem: When the Connect API for Java sends a Send-Only-With-Ack error response (with NAK reason code) to an IMS synchronous callout request, IMS Connect returns a NAK response even if the error response and reason code were successfully received by OTMA. However, the IMS application that initiated the synchronous callout request receives the NAK reason code from the API client application normally.
Workaround: If the NAK response from IMS Connect has return code 16 and an OTMA sense code equal to the NAK reason code sent by the client, you can treat the NAK response as if it were an ACK response.
Problem: The API does not correctly process 2-dimensional byte arrays used as the source data for a response message to an IMS synchronous callout request. If multiple rows are specified, the API can enter a loop condition.
Workaround: Use a 1-dimensional byte array or specify all of the response data in the first row of a 2-dimensional byte array (A).
Problem: The Connect API for Java client application receives an HWS0001E error message with a null pointer exception while executing the type-2 command QUERY TRAN NAME or UPDATE TRAN NAME, or when retrieving information from a Type2CmdResponse object, if the entered QUERY was not in the right format.
Workaround: Use only well-formed type-2 command queries.
Fix: Included in PTF UK83045.
Problem: The Connect API for Java client application receives an HWS0018E error message after submitting an invalid IMSPlex name in a QUERY IMSPLEX type-2 command.
Workaround: If your application receives an HWS0018E message, check that the IMSPlex name is correct.
Fix: Included in PTF UK83405.
Problem: The Connect API for Java client application receives a HWS0018E error message when a type-2 command response contains an RSM.
Workaround: No workaround is available for this issue.
Fix: Included in PTF UK83405.
New API logging functions for Version 126.96.36.199: These methods are available in the ApiLoggingConfiguration class. Set these logging configuration properties before calling configureApiLogging. You can use these controls in combination with the controls added in version 188.8.131.52.
Sets the maximum number of bytes that can be written to an API log file through the Connect API logging file handler.
public void setLoggerFileLimit(int aLimitValue)
Gets the maximum number of bytes that can be written to an API logging file.
public int getLoggerFileLimit()
Sets the number of sequential log files files that the API log file handler will create before overwriting the first file.
public void setLoggerFileCount(int aCountValue)
Gets the API logging file handler's count for the number of files to use of the Connect API logging file handler when one file has reached its Limit.
public int getLoggerFileCount()
New API logging functions for Version 184.108.40.206: These methods are available in the ApiLoggingConfiguration class. Set these logging configuration properties before calling configureApiLogging.
Sets the API logger to either append to the existing log file (true) or overwrite it (false).
public void setLoggerToAppendMode(boolean aBooleanAppendValue)
Gets the current logger append mode.
public boolean isLoggerAppendModeEnabled()
Gets an API log file handler.
public Handler getLoggerFileHandler()
Restriction: IMS Connect support for Unicode character encoding cannot be enabled with the Connect API for Java. You can manually enable Unicode for input messages by setting the IRM_F1 X'20' flag bit on behalf of the input message with the IMS Connect User Message Exit. To use Unicode trancodes as well, you must include the trancode at the start of the input message data and set the IRM_F1 X'10' flag bit with the exit. In either case, indicate UTF-8 encoding with the IRM_ES X'01' flag bit.
Contacting IBM Software Support
Contact IBM Software Support.
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 2012, 2015. All Rights Reserved.