/*********************************************************************/ /* /* IBM Message Service Client for C/C++ /* /* FILE NAME: readme.txt /* /* DESCRIPTION: Important notes about the product /* /*********************************************************************/ /* /* /* Licensed Materials - Property of IBM /* /* 5724-I13 /* /* (c) Copyright IBM Corp. 2003, 2019 /* All Rights Reserved /* /* U.S. Government Users Restricted Rights - use, /* duplication or disclosure restricted by GSA /* ADP Schedule Contract with IBM Corp. /* /* Status: Version 2.0.4.0 /* /* /*********************************************************************/ /* /* Updated: 21st Mar 2019 /* /*********************************************************************/ IA94 IBM Message Service Client for C/C++ README ================================================ Welcome to IBM Message Service Client for C/C++ (informally known as XMS). This README file applies to V2.0.4.0 and is supplemental to the "Message Service Clients for C/C++" manual (XMS_Client_00.pdf). This README file contains the following information: 1) Conventions used within the document 2) Supported environments 3) Installation instructions 4) List of known restrictions to API and pre-requisite software 5) Known problems 6) (RTT) Setting up Security using a data source for authentication (not OS) 7) InstallAnywhere Enterprise Edition 8) Uninstalling On Windows 9) Changes in this release 10) Readme updates made after translation ========================================================== 1) Conventions used within the document --------------------------------------- This README covers several operating systems. To aid readability of the document: a) 'XMS' has been used throughout as shorthand for IBM Message Service Client for C/C++. b) '/' has been used as a directory separator throughout. c) XMS 2.0.4/2.0.3 is designed to interoperate with 3 messaging providers: - 'RTT' refers to interaction with IBM WBI Brokers over the Real Time Transport protocol. - 'WPM' refers to interaction with WebSphere Platform Messaging; as embodied as the default messaging provider in IBM WebSphere Application Server v6.x, for example. - 'IBM MQ' refers to interaction with IBM MQ Queue Managers. 2) Supported environments ------------------------- XMS is built for C/C++ applications to run on the following platforms: - Linux Red Hat EL 5.0, 6.0 and SUSE Linux ES 9, SUSE Linux ES 10,SUSE Linux ES 11, all on Intel 32 bit architecture - compiler gcc 4.1.2 (See NOTE 1 below) - Linux Red Hat EL 5.0, 6.0 and SUSE Linux ES 9, SUSE Linux ES 10,SUSE Linux ES 11 on x86_64 bit architecture compiler gcc 4.1.0 (See NOTE 1 below) - Linux Red Hat EL 5.0, 6.0 and SUSE Linux ES 9, SUSE Linux ES 10,SUSE Linux ES 11 on ppc64 bit architecture compiler gcc 4.1.0 (See NOTE 1 below) - Windows Server 2008 R2, Windows 7 SP1,Windows 8 on Intel 32 bit architecture and Windows Server 2008 R2,Windows Server 2012,Windows 7 SP1,Windows 8 x64 - compiler Microsoft Visual Studio 2015. - Solaris 9 and 10 on SPARC 32 and 64 bit architecture - Sun ONE Studio 11 Enterprise Edition for Solaris (C and C++) - AIX 6.1 and 7.1 for 32 and 64 bit - IBM XL C/C++ Enterprise Edition for AIX v9.0 NB: Some features of XMS may be missing in some environments. Please refer to the 'list of known restrictions' section below. XMS has been tested for interaction with the following messaging servers: RTT - IBM WebSphere Message Brokers 6.1 with Fix Pack 10 Onwards IBM MQ - IBM WebSphere MQ 7.5 + with Fix Pack 10 (See NOTE 1 & 2 below ) IBM MQ 8.0.0.3 (See NOTE 1 & 2 below ) IBM MQ 9.0.0.2 (See NOTE 1 & 2 below ) IBM MQ 9.1.0.0 (See NOTE 1 & 2 below ) WPM - IBM WebSphere Application Server 7.0.0.19 onwards (See Note 3 below) IBM WebSphere Application Server 8.0.0.1 onwards (See Note 3 below) IBM WebSphere Application Server 8.5.5 onwards (See Note 3 below) Please note, not all environments receive the same level of support, please review the license terms under which you received XMS for details. For example, connections to IBM WebSphere Process Server and IBM WebSphere ESB are only supported for XMS clients distributed with those products. Fix Packs can be downloaded from the following IBM support Fix Central https://www.ibm.com/support/fixcentral/ NOTE 1: Use of LD_ASSUME_KERNEL on Linux - XMS has been designed to use the Native POSIX Thread Library (NPTL). As such, it is not recommended to use this environment variable to specify the LinuxThreads threading libraries. For further information and recommendations please refer to the 'known problems' section below. NOTE 2: If using IBM MQ, the machine used to run the XMS application must be installed with either the IBM MQ Client C libraries or a local queue manager. If the IBM MQ Client C libraries are used then the MQ v7.0.1.7/v7.1/v7.5 and later supported libraries are a must if the application wants to use features implemented in WebSphere MQ v7.0.1.7/v7.1/v7.5 respectively. The MQ v7.1/v7.5/v8/v9 and later supported version /MQ v7.0.1.7 Client C libraries can be used for 'client only' mode connections to MQv7.5/v7.1/7.0.1.7/v6.0.2.11 queue managers. If a 'bindings' mode connection is required then MQ v7.5.0.9/ MQ v8.0.0.8/MQ v9.0.0.2 or later supported server installation is required. NOTE 3: Support for IBM Websphere Application Server over SSL is not available on the following platforms i) SUSE Linux Enterprise Server (SLES) 9 3) Installation instructions ---------------------------- Installer setup programs are provided for Linux, Windows, Solaris and AIX. You should download the zip file relevant to your platform, and unzip the contents into a temporary directory. Each zip contains the files required to install IBM Message Service Client for C/C++ on your machine. To install the product, simply run the executable installation program and follow the instructions below. The install program requires administrator or root login. Running the setup program - GUI or Console When you run the setup program you will be prompted through a number of setup screens: - Welcome screen - Introduction and License Acceptance - Global Security Kit (GSKit) Installation Directory - Product (XMS) Installation Directory - Complete/Custom Install Panel - Features to install (if Custom Install is chosen) - Pre-Installation Summary - Readme Panel (if the View Readme option is chosen) You can press Cancel at any time during the install setup process to stop the installation process, but this option is not available while the product is actually being installed. If you are installing under Windows, shortcuts to the product's documentation and readme files will be added to the programs menu under "IBM Message Service Client for C/C++" Running the setup program - Silent Mode The installer can also be run in a non-interactive silent mode. By default, silent installation will be performed using the following product defaults: Product install directory: [platform default install directory]/IBM/XMS GSKit install directory: [platform default install directory]/IBM/gsk8 Features: All product features will be installed To use the installer in this way the product license must be explicitly accepted by adding 'LICENSE_ACCEPTED=TRUE' to the command line, i.e., Example For Unix: setup.bin -i silent -DLICENSE_ACCEPTED=TRUE Example For Windows: setup.exe -i silent -DLICENSE_ACCEPTED=TRUE As an alternative, if specific installation options are required a response file can be provided. Further information is available in the user manual. 4) List of known restrictions to API and pre-requisite software --------------------------------------------------------------- - Windows Only: IBM Directory Server Client v6.4 must be installed if application connects to a LDAP server to retrieve administered objects. The location of IBM Directory Server Client v6.4 must be updated in PATH environment variable before starting XMS application. Ensure the PATH is correctly updated matching the bitness, 32 or 64 of the application. Further ensure Microsoft Visual C++ 2013 Redistributable (x86) and (x64) are installed as IBM Directory Server Client v6.4 requires these runtime libraries. - COS Naming support for retrieval of WebSphere MQ administered objects stored in WebSphere Application Server JNDI is not available. - RTT authentication protocols and Quality of Protection The following authentication protocols are supported for the Real Time Transport: - Simple telnet-like password authentication (supported on all platforms). - Mutual Password Request (not supported on AIX, Solaris). Please refer to the product documentation supplied with 'IBM MQ Integrator Broker' and 'WebSphere MQ Event Broker' for more specific information about authentication and QOP. - Global transactions are not supported. - SSL connections to IBM MQ If you use the WebSphere MQ Version 7.0.0.1 and above client libraries and connect to a WebSphere MQ v7 queue manager, then you can create multiple connections to same queue manager in XMS application. However, connection to different queue manager is not permitted. If you attempt you get the MQRC_SSL_INITIALIZATION_ERROR error. - SSL connections to WPM Microsoft Windows certificate store is not supported on Windows x64. - WPM Administered Object Lookup In order to use the COS Naming service for WPM administered objects, additional configuration is required on the server. A web service must be deployed on a WebSphere Application Server-based product, to translate the Java information in the COS Naming service into a form readable by the non-Java XMS clients. Full details of this web service and its deployment can be found in user documentation. The web service can only be used to retrieve administered objects from an unsecured COS naming directory over the HTTP protocol. Accessing objects from a secured naming directory or using the HTTPS protocol is not supported. - IBM MQ Client Channel Definition Tables The use of Client Channel Definition Tables (CCDT), to configure client connections to IBM MQ queue managers, is not supported in this release. - Using JMS_IBM_MQMD_* properties as message selectors Usage of JMS_IBM_MQMD_* properties as message selector is not supported when connecting to WebSphere MQ v7.0. - IBM MQ Exit names IBM MQ Exits like the Send, Receive with name "null" are not supported. - Cipher Suit names Cipher Suit with name as "null" are not supported. - Client Identifiers Client Identifiers with "null" are not supported. In addition, please note that each supported messaging environment (currently IBM MQ, RTT, and WPM) may have restrictions on the extent to which it supports the JMS 1.1 specification, and hence limitations on the support for XMS functions. For example, message acknowledgement is not supported by IBM WBI Brokers, and hence by XMS when interacting with such brokers over RTT. For full details on such restrictions, please refer to the documentation for the IBM messaging 'server' product with which you are using XMS. Please also see 2) Supported environments. 5) Known problems ----------------- a) (IBM MQ) Exception listener not invoked when connected to WebSphere MQ V7.0 queue manager in bindings mode. Exception listener is not invoked when there are no asynchronous consumers and a connection to queue manager breaks. This is a limitation with WebSphere MQ V7.0 only and applicable only to applications connected in bindings mode. b) (RTT) Multiple network cards (XMS client): The string property XMSC_RTT_LOCAL_ADDRESS can optionally be set on a connection factory object to direct the connection to bind to a specific Network card installed on the client's machine when using the Direct IP (RTT) transport. The string property XMSC_RTT_LOCAL_ADDRESS can be set to an IP address or host name (i.e. 192.168.0.1 or card.one.local.machine). If this property is not set on a machine with more than one network card installed then network card selection will be random. c) What is TIME_WAIT: The program 'netstat' often reports connections in a state of 'TIME_WAIT'. This is normal behavior, the TIME_WAIT is an indication that a connection has been closed (or more correctly, is being closed). TCP holds the connection in a TIME_WAIT state for a certain length of time after normal connection close to ensure that delayed packets are caught and not treated as new connection requests. The size of TIME_WAIT would normally be twice the maximum lifetime that a packet can remain alive on an IP network and can be as much as 240 seconds. Large numbers of connections being opened and closed may result in a reduction of available TCP resources which would be reported as large numbers of connections in a 'TIME_WAIT' state. Reducing the operating systems TIME_WAIT setting can release these resources for reuse earlier. Please consult your OS documentation for details. d) (WPM) In testing, we have found that XMS applications sending messages through WebSphere Application Server Messaging Engines typically need to use a larger JVM heap than the default. Please see the Application Server documentation for details on changing heap configuration. e) (IBM MQ) When testing XMS pub/sub applications with WBIMB/IBM MQ, we used the following DB2 settings: MON_HEAP_SZ was 512 APP_CTL_HEAP_SZ was 512 Please see the DB2 documentation for details on changing configuration. f) (IBM MQ) XMS uses the new format for character fields in map messages on IBM MQ connections (see Using Java for more details). XMS can therefore read map messages sent by any XMS or IBM MQ JMS client application, but JMS client applications will only be able to read map messages containing character fields sent by XMS applications if they use IBM MQ JMS 5.3 fix pack 8 or later. This behaviour makes XMS consistent with IBM MQ JMS v6.0. g) Care should be taken when using infinite or long timeouts in a recieveWithWait call. In order to close the associated consumer (or session) the outstanding receive() call must first complete. h) (IBM MQ) On Linux, the use of LD_ASSUME_KERNEL to specify the LinuxThreads threading libraries is not recommended for XMS. This is known to cause the following issues: i) Trace and FFDC files will be named according to the PID of the thread that created them. ii) The trace configuration tool 'gxisc' will require the PID of the applications original thread. iii) Connections to WPM servers over SSL may create FFDC on exit. i) (IBM MQ) If a message listener is used to receive messages asynchronously from a message consumer, as recommended in the JMS spec, the message listener should be assigned before its associated connection is started. j) The installation can fail with a 'version already exists' error even though a previous version of the product is not present on the machine. This prevents the installation from continuing. The most likely cause is if a previous install or uninstall has failed, or the product has been removed from the disk without being uninstalled. To clear the error, edit the Zero G Registry file and remove the entries relating to "IBM Message Service Client for C/C++". The locations of this file is: -On Linux and UNIX, /var/.com.zerog.registry.xml -On Windows (x86 platform), C:\Program Files\Zero G Registry\.com.zerog.registry.xml -On Windows (x86-64 platform), C:\Program Files(x86)\Zero G Registry\.com.zerog.registry.xml k) (IPv6) When using WPM HTTP transport, specify a port range instead of port number in the local address. For example, [host_name][(low_port),(high_port)] l) On Solaris tar utility does not properly handle files with long path, So use gtar instead of tar for extracting the product. For example to extract the tar, /usr/sfw/bin/gtar xvf ia94.solarissparc.tar m) On widnows if XMS is uninstalled, tools folder will not be deleted after uninstallation. n) XMS release for Linux on POWERPC platform does not support WebSphere Application Server. 6) (RTT) Setting up Security using a data source for authentication (not the OS) -------------------------------------------------------------------- Ensure that the latest windows v5.0 broker CSD level is installed. In the broker installation directory locate the files 'password.dat' and 'pwgroup.dat' within the directory sample\Auth, these files can be used to setup basic authentication using a user name server. The files contain mappings for userids, passwords and groups. Populate the files with the settings you require. Create a user name server, select the options '-j -g', selecting the data source for authentication and the option '-q' (selecting say, the brokers queue manager) mqsicreateusernameserver ..... -j -g "C:\Program Files\IBM\WebSphere Business Integration Message Brokers\sample\Auth\password.dat" -q brokerQueueManagerName create a broker using the options '-s' and '-j'. mqsicreatebroker .... -q brokerQueueManagerName -s brokerQueueManagerName -j create a configuration manager mqsicreateconfigmgr .... -s brokerQueueManagerName ------------------------------------------------------------------ * Ensure that the User Name Server is started before the broker * or configuration manager ------------------------------------------------------------------ mqsistart usernameserver mqsistart configmgr mqsistart broker Start the Message Brokers toolkit GUI. Once the GUI has started, create a broker message flow that includes a 'Real-timeOptimizedFlow' node. Modify the nodes properties to add a port number, for example 1506. Select the Authentication checkbox if you require authentication. Use the GUI's Administration perspective to add a Broker into a broker domain. Modify the properties of the broker you have just created in the broker topology, (use the mouse right button, select properties). 'Authentication Protocol Type' should be set to 'P' (capital P). This setting is auto-deployed to the broker. Check for successful deployment in the GUI 'EventLog' (BIP2056I indicates success). Create a 'Broker ARchive file' file, adding the message flow created earlier to this file. Save this BAR file and deploy it to the broker (drag the BAR file and drop it on a broker Execution Group). Check the GUI 'EventLog' for successful deployment (BIP2056I is success). Once the BAR file has successfully deployed then the Message Brokers toolkit GUI can be stopped. The configuration manager may also be stopped (mqsistop configmgr). If the machine running the broker is shut down then only the user name server (mqsistart usernameserver) and the broker (mqsistart broker) need to be restarted. 7) InstallAnywhere Enterprise Edition ------------------------------------- Though you will normally run the installer in its "Wizard" form, it is possible, via Runtime Command Line Options, to finely control the installation. Typical of these options is "-silent" which will perform the installation without using the GUI. For general information on InstallAnywhere go to http://www.acresso.com/products/ia/installanywhere-overview.htm 8) Uninstalling On Windows --------------------------- The Add / Remove Program screen will only show one instance of XMS. If you have problems uninstalling your installation, or you have more than one instance, you may wish to launch the uninstall wizard manually. The uninstall program can be run from the following location /_uninst/uninstaller.exe 9) Changes in this release --------------------------- Following are the key change in 2.0.4 release: - Windows Only: - Microsoft Visual Studio 2015 compiler support for Microsoft Windows. - Customer must explicitly install IBM Directory Server Client v6.4 prior to using applications that use a LDAP server to retrieve connection factory and destination objects. Following are the key enhancements in 2.0.3 release: - TLS1.2 protocol and SHA2 cipher cupport WMQ7.1 and MQ7.5 supports TLS1.2 and SHA2 cipher. XMS has been changed to exploit this support. Addition of a new property XMSC_WMQ_SSL_ENCRYPTION_POLICY_SUITE_B for suite B compliance support. - Multicast RTT Connections is not supported. - This release supports supports more operating systems. Trademarks ---------- The following terms are trademarks of the IBM Corporation in the United States, or other countries, or both: IBM MQSeries SupportPac WebSphere ActiveX, Microsoft, Visual Basic, Visual C++, Windows, and Windows NT are trademarks or registered 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 Sun Microsystems, Inc. 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, and service names may be trademarks or service marks of others. Additional Information ---------------------- The Program includes "UnZipSFX stub" software from the Info-Zip group which is Copyright (c) 1999-2002, Info-ZIP. All rights reserved. IBM did not modify the UnZipSFX software. There are no extra charges or costs due to the use of this code, and the original compression sources are freely available from http://www.cdrom.com/pub/infozip/ or ftp://ftp.cdrom.com/pub/infozip/ on the Internet. The Program also makes use of the ICU software for conversion of character strings between codepages. ICU software is used under the following conditions: ICU License - ICU 1.8.1 and later COPYRIGHT AND PERMISSION NOTICE Copyright (c) 1995-2018 International Business Machines Corporation and others All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. -------------------------------------------------------------------------- All trademarks and registered trademarks mentioned herein are the property of their respective owners.