IBM MQSeries Adapter Kernel for Multiplatforms Version 1.1.1 - readme.txt =============================================================== Welcome to IBM(R) MQSeries(R) Adapter Kernel for Multiplatforms Version 1.1.1 This README file contains information you need for installing as well as information that was not available for our printed publications. Accessing the product Web site Please visit the MQSeries Adapter Offering Web site for the most updated product information: http://www.ibm.com/software/mqseries/adapter/ The Web site information page contains updated documentation, including Release Notes and samples: http://www.ibm.com/software/ts/mqseries/adapter/information/ You can find additional information on the MQSeries Web site: http://www.ibm.com/software/ts/mqseries/ ============================================================ Documentation ============================================================ The documentation for IBM MQSeries Adapter Kernel for Multiplatforms Version 1.1.1 is provided in both a searchable Adobe Acrobat Portable Document Format (PDF) and in HTML form. Both are installed to the documentation directory under the installation root directory by the Adapter Kernel installation package. The Quick Beginnings PDF file (aqm7ac.pdf) and the Problem Determination Guide PDF file (aqm7aq.pdf) are also available in the root directory of the installation CD. The installed HTML documentation may be launched from index.html. On Windows NT and Windows 2000, the MQSeries Adapter Kernel installation program automatically creates a Start Menu shortcut to the Information Center. ============================================================ Installation ============================================================ NOTE: This file does not contain all information necessary for installation. See the MQSeries Adapter Kernel for Multiplatforms Quick Beginnings book for detailed information on how to install on a specific platform. The installation program for MQSeries Adapter Kernel for the various platforms uses Java to install the product to your workstation. It has been fully tested with IBM Java Development Kit 1.2.2 and 1.3 (Windows). Other versions of the Java Development Kit may work but are not directly supported. ** Known Problems ********************************************** * * * - If the Installation program finds version 1.1.6 of the JDK * * or JRE, it will fail. Uninstall version 1.1.6 and install * * version 1.2.2 or greater of the JDK. * * * * - When the Welcome panel displays, some users may see the * * word 'Malformed' in the text of the welcome message. This * * is a known bug with the installation tool being used and * * it does not affect how the product is installed. * * * * - On AIX, do not run the MQSeries Adapter Kernel Java * * classes with a 1999 vintage JDK 1.2.2, because the system * * can fail. Use a newer version. To check the version, * * use the command: * * * * java -version * * * * Then, check the version that is displayed. For example, * * * * java version "1.2.2" * * Classic VM (J2RE 1.2.2 IBM build cn122-20010503a * * (JIT enabled: jitc)) * * * * is a correct version, where 2001 indicates the year 2001. * **************************************************************** During installation, installation status messages are written to the log.txt file in the kernel's root directory. If a problem occurs during installation, you can examine this file. Windows NT and Windows 2000 Specific ==================================== To install on Windows NT and Windows 2000, insert the CD-ROM into the CD-ROM drive. If autorun is enabled, the installation process starts. If it is not, run the install.bat command file. AIX Specific ============ To install on AIX run the install.sh shell script. The X-Windows client needs to be running for this installation program to work. On some AIX systems the installation directory entry field within the installation program displays as white text on a white background. Use the style manager color utility to modify the system color pallette before starting the install. Solaris Specific ================ To install on Solaris run the install.sh shell script. Using JDK 1.2.2 to install on Solaris you need to set the environment variable THREADS_FLAG equal to "native", e.g. export THREADS_FLAG=native Some users may see an hour glass for the cursor on some of the installation panels. The cursor can still be used to select buttons when displayed as the hour glass. Some users may not be able to use the mouse to scroll the license agreement window. Click in the license agreement window and use the up and down arrow keys to scroll. HP-UX Specific ============== To install on HP-UX run the install.sh shell script. At the end of the log.txt file there may be two messages: one indicating date and time could not be changed and the second indicating the file permissions could not be changed. These messages can be ignored. With some X-Windows managers, font errors may be given that can cause the installation to fail. Installation from a remote Intel-based system is usually successful. AS/400 Specific =============== To install on OS/400 use the installAS400.jar file in the AS400 directory of the CD-ROM. Before installing on the AS/400 create a user profile named MQAKSRV using the CRTUSRPRF command. Performing an install to an OS/400 system can be performed either from the OS/400 system or from an attached client. We recommend using the attached client method, it is the easiest and it has the best overall performance. Running the Install from an OS/400 System: ------------------------------------------ Start Remote AWT on your client workstation by changing to the directory where you copied the RAWTGui.jar file and typing 'java -jar RAWTGui.jar'. The installAS400.jar file needs to be accessable to the OS/400 system. The file needs to be either in the IFS directory system, or on a device attached to the OS/400 system. If the file is on an attached device, you need to use the Create Link (CRTLINK) command to create a symbolic link to the file. You can significantly increase the performance of the install by running Create Java Program (CRTJVAPGM) against the installAS400.jar file. On some machines the running of the CRTJVAPGM can be very time consuming. Call the Run Java (RUNJVA) command, supplying the TCP/IP address of the client that is running Remote AWT: RUNJVA CLASS(run) CLASSPATH('/installAS400.jar') PROP((os400.class.path.rawt 1) (RmtAwtServer 'x.x.x.x') (java.version 1.2)) Running The Install From an Attached Client ------------------------------------------- You can perform the install by invoking the client's Java runtime and indicating that you want the install performed on the attached OS/400 system. Invoke the client's Java Runtime against the archive, and use the -os400 command line parameter to indicate you want the install performed on the attached client. If installing using the client's JDK version 1.2 or higher use the following command: java -classpath installAS400.jar; run -os400 If installing using the client's JDK version 1.1.8 use the following command: jre -cp installAS400.jar; run -os400 Note: A known problem with this version of the installation program is the generation of several warning messages such as "Warning: One of the license agreement files was not properly created." which can be safely ignored. =============================================================== Hints and tips --------------------------------------------------------------- General ======= 1. IBM MQSeries Adapter Kernel for Multiplatforms Version 1.1.1 is meant to be run with IBM Java Development Kit 1.2.2 and jdk1.3 (Windows). Other versions of the Java Development Kit may work but are not directly supported. 2. On NT and Unix when using jdk 1.1 at runtime copy the AQMUtilC library from the MQAK_root/bin/jdk1.1 directory to the MQAK_root/bin directory. Note: jdk1.1 is not directly supported. 3. Migration from IBM MQSeries Adapter Kernel Version 1.0 The aqmconfig.properties file used in version 1.0 has been replaced with an XML formatted file named aqmconfig.xml. You will need to convert the aqmconfig.properties file to the aqmconfig.xml format. Refer to the samples directory for an example of the xml format. 4. Verification installation testing assumes a running default MQSeries QManager. If there is no default QManager the test will fail. An indication of this is that an exception message will display with "MQException" in the message plus there will be two files, TEST1queue.out and TEST2queue.out, containing a message "No MQSC commands read". If creating a default QManager or making an existing QManager the default is not practical then perform the following steps before running the verification: a) At a command prompt change into the kernels root directory and then into the "verification" directory. b) Create test queues by running the following two commands where "yourQManagerName" is the QManager name to create the queues under: aqmcreateq TEST1 yourQManagerName aqmcreateq TEST2 yourQManagerName c) Modify the "aqmconfig.xml" file by changing the two DEFAULT entries to yourQManagerName where "yourQManagerName" is the QManager name to run under. The verification installation test can now be run as normal. Note: the two output files TEST1queue.out and TEST2queue.out will still have the message "No MQSC commands read" but this can be safely ignored. ------------------------------------------------------------------ Windows NT and Windows 2000 Specific ==================================== IBM jdk1.3 comes with an xml parser installed in the "extensions" directory (jre\lib\ext). The xml4j.jar file installed in the extensions directory overrides the xml parser classes supplied with MQAK. MQAK will not work correctly with the xml4j.jar file in the extensions directory. There are three possible solutions depending on what other applications are installed on that machine listed in order of preference. 1) If no other products require use of the jdk installed xml parser classes, then move the xerces.jar and xml4j.jar from the extensions directory, but do not put in the classpath. 2) If other products require use of the jdk installed xml parser classes but do not require MQAK, then move the xerces.jar and xml4j.jar from the extensions directory and include in the classpath used by the products but not in the classpath used by MQAK. 3) If other products require use of the jdk installed xml parser classes and MQAK, then replace the xml4j.jar in the extensions directory with the supplied MQAK xml4j_2_0_15.jar file. This file is located in the kernels root directory under "toolkit\support". AIX Specific ============ When running source adapters on AIX that are written in C you must set the AIXTHREAD_SCOPE environment variable to 'S'. Example: export AIXTHREAD_SCOPE=S The AIXTHREAD_SCOPE environment variable resets the disposition of the default attribute. This can be used to change the scheduling policy from m:n to 1:1 or vice versa. Settings for this environment variable are: AIXTHREAD_SCOPE=sched_policy where sched_policy is one of: P - process based scheduling (m:n) S - system based scheduling (1:1) In the 1:1 model, each user thread is mapped to one kernel thread, and each user thread runs on one virtual processor. In the m:n model, all user threads are mapped to a pool of kernel threads, and all user threads run on a pool of virtual processors. One user thread may be bound to a specific virtual processor (like 1:1) with remaining threads using the remaining virtual processors in the pool. When invoking the Java Virtual Machine from a native C executable, the JVM requires 1:1 threading. ------------------------------------------------------------------ MQSeries v5.1 is not currently supported using JDK 1.2.2 ------------------------------------------------------------------ Memory conflict between JDK1.2 (and JDK1.3 and above) on AIX - sharing segment 8. Reference http://www-4.ibm.com/software/ts/mqseries/support/summary/jvreadme.html An extra parameter for the mqs.ini file is now supported by MQSeries V5.2. The parameter is "IPCCBaseAddress" and is set on a per queue manager basis. By default this parameter is set to the value "8", but we recommend setting this to the value "12". The following is an example of an altered QueueManager stanza in an mqs.ini file: QueueManager: Name=MQJavaTest Prefix=/var/mqm IPCCBaseAddress=12 Allowable values for this parameter are "4", "5", "8", "9", "10", "11" or "12"; see the MQSeries V5.2 documentation for more information. We have found some jdk's may require a different parameter. ------------------------------------------------------------------ Solaris Specific ================ When using JDK 1.2.2 and running source/target adapters on Solaris that are written in C and sending and receiving messages using MQSeries you must set the THREADS_FLAG environment variable to 'native'. Example: export THREADS_FLAG=native ------------------------------------------------------------------ AS/400 Specific =============== When using 'C' adapters there is a variable string length limitation. If your messages reach this limit, obtain the latest Java PTF from AS/400 support. =============================================================== Late-Breaking News --------------------------------------------------------------- Missing entries for the setup ============================= Add the following entries to the CLASSPATH: CLASSPATH: \java\lib\com.ibm.mq.jar \java\lib \bin where is the home directory of your MQSeries installation. For example, C:\Program\Files\MQSeries and is the home directory of your MQSeries Adapter Kernel installation. For example, C:\Program\Files\MQAK =============================================================== Trademarks ========== The following terms are trademarks of IBM Business Machines Corporation in the United States, other countries, or both: DB2, FFST, IBM, MQSeries, OS/390, SupportPac, Tivoli, Tivoli Ready, VisualAge, AIX, AS/400, OS/400, RS/6000, WebSphere Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, Windows 2000, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. ################### end of readme.txt ##################