WebSphere MQ for AIX, V5.3 README
Welcome to WebSphere MQ for AIX, Version 5.3.
This README file applies to WebSphere MQ books dated October 2002 and CSD01 level of the V5.3 product shipped on or after October 2002.
This README file contains information that was not available in time for our publications. In addition to this file, README.TXT, you can find more information on the WebSphere MQ web site:
http://www.ibm.com/software/products/en/ibm-mq
The SupportPac web page is here:
http://www.ibm.com/support/docview.wss?rs=977&uid=swg27007205
For current information on known problems and available fixes, see the Support page of the WebSphere MQ web site here:
http://www.ibm.com/support/docview.wss?rs=171&uid=swg27006037
Web documentation updates
The latest updates to the web-based WebSphere MQ documentation are now available from the WebSphere MQ web site here:
http://www.ibm.com/software/integration/wmq/library/library53.html
Note that latest changes are shown in red and earlier changes are shown in blue.
The Change History is located at the bottom of the page.
WebSphere MQ for AIX V5.3 Electronic Software Download installation
Introduction
These instructions apply to installing WebSphere MQ for AIX Version 5.3 from an installation image downloaded from IBM. Use it with the Quick Beginnings manual for this release. A version of the Quick Beginnings book is available from the download site; it has a description of 'WebSphere MQ
V5.3 Install Doc'. The installation image is provided as a compressed tape archive (tar) file.
Installation Steps
- Copy the WebSphere MQ tar file to a suitable directory accessible to the machines where the software is to be installed. This directory must be on a file system with at least 140Mb of free space (this is in addition to the disk space required for the product, as detailed in the Quick Beginnings publication).
- Make this directory the current directory and use the command :
tar -xvf MQ53Server_aix.tar
to create the installation image.
- After this operation succeeds, you can delete MQ53Server_aix.tar.
- Use the WebSphere MQ for AIX V 5.3 Quick Beginnings manual to install and configure the product. Replace any references to the CD drive by the directory used in the steps above.
All other instructions remain the same.
WebSphere MQ for AIX V5.3 Quick Beginnings
Chapter 1, "Planning to install WebSphere MQ for AIX"
In the section "Prerequisite software", sub-section operating system section the statement, "The C/C++ runtime installed on AIX must be at level 5.0.2.0 or higher", should say "The C/C++ runtime installed on AIX must be at release 5.0.2.0 or at any later release of version 5 , or at release 6.0.0.2 or at any later release of version 6."
Chapter 5, "Installing the WebSphere MQ for AIX client"
In the section "Installation procedure" add
The client CD contains two versions of the installation package, one with and one without the support for Secure Sockets Layer (SSL) function. By default, the installation procedure will use the full version. If you wish to install without support for SSL use this procedure.
- Insert the WebSphere MQ Clients CD-ROM 1 containing the AIX client into the CD-ROM drive.
- Mount the CD, for example:
> mount /cdrom1
- Specify the directory /cdrom1/aix/MQClient as the path input device or directory to smit or the -d argument to installp.
- Follow the procedure described in this chapter to install the client.
WebSphere MQ V5.3 System Administration Guide
Chapter 11 "Transactional support"
In section "Scenario 1: Queue manager performs the coordination" subsection "Oracle configuration" Figure 12."Sample XAResourceManager entry for Oracle on UNIX platforms" on AIX only you MUST add +SqlNet=db_link to the XAOpenString.
WebSphere MQ V5.3 Intercommunication
Chapter 1, "Concepts of intercommunication"
In the section "Distributed queuing components", subsection "Channel initiators and listeners", add the following subsection:New channel behaviour in WebSphere MQ
By default, in WebSphere MQ 5.3, threaded channels started by the channel initiator or a listener do not run under that process, but under a process called AMQRMPPA, otherwise known as a pool process.
To revert to the MQSeries 5.2 behavior, and have channels run under the originating process, define an environment variable MQNOREMPOOL. The existence of this variable, set to any value, runs the channel threads as part of the listener or channel initiator process. This can be useful when trying to isolate one or more channels from the rest of the configuration, for example when testing channel exits.
Chapter 6, "Channel attributes"
In the section "Channel attributes in alphabetical order", subsection "KeepAlive Interval (KAINT)", add the following:
You can set the KeepAlive Interval (KAINT) parameter for channels on a per-channel basis. You can access and modify the parameter, but it is only stored and forwarded on non-z/OS platforms; there is no functional implementation of the parameter.
If you need the functionality provided by the KAINT parameter, use the Heartbeat Interval (HBINT) parameter, as described in "Heartbeat interval (HBINT)".
Chapter 47, "Channel-exit calls and data structures"
In the section "MQCD - Channel definition", add to the fields SSLPeerNamePtr and SSLPeerNameLength the note:
When a certificate is received during a successful SSL handshake, the Distinguished Name of the subject of the certificate is copied into the MQCD field accessed by SSLPeerNamePtr at the end of the channel which receives the certificate. It overwrites the SSLPeerName value for the channel if this is present in the local user's channel definition.
If a security exit is specified at this end of the channel it will receive the Distinguished Name from the peer certificate in the MQCD.
WebSphere MQ V5.3 SCRIPT (MQSC) Command Reference
Chapter 2, "The MQSC commands"
In the section "ALTER QMGR" add the following description of the GSK_PKCS11 value of the SSLCRYP parameter:
The PKCS #11 token label must be entirely in lower case. Note that if you have configured your hardware with a mixed case or upper case token label you must reconfigure it with this lower case label.
In the section "ALTER QMGR", parameter SSLCRLNL(nlname) description change the list which describes when changes become effective to:
- On Windows and UNIX systems (apart from Linux for zSeries), when a new outbound single channel process first runs an SSL channel.
- On Windows and UNIX systems (apart from Linux for zSeries), when a new inbound TCP/IP single channel process first receives a request to start an SSL channel.
- On Windows and UNIX systems (apart from Linux for zSeries), for channels that run as threads of a process pooling process (amqrmppa), when the process pooling process is started or restarted and first runs an SSL channel. If the process pooling process has already run an SSL channel, and you want the change to become effective immediately, restart the queue manager.
- On Windows and UNIX systems (apart from Linux for zSeries), for channels that run as threads of the channel initiator, when the channel initiator is started or restarted and first runs an SSL channel. If the channel initiator process has already run an SSL channel, and you want the change to become effective immediately, restart the queue manager.
- On Windows and UNIX systems (apart from Linux for zSeries), for channels that run as threads of a TCP/IP listener, when the listener is started or restarted and first receives a request to start an SSL channel.
- On z/OS, when the channel initiator is restarted.
Add, after the list:
- On OS/400 queue managers this parameter is ignored, however it is used to determine what authentication information objects are written to the client channel definition table.
- On Linux for zSeries queue managers this parameter must not be specified when channels are started, however it is used to determine what authentication information objects are written to the client channel definition table. Note that changes to SSLCRLNL, or to the names in a previously specified namelist, or to previously referenced authentication information objects are reflected
immediately in the client channel definition table.
WebSphere MQ V5.3 Programmable Command Formats and Administration Interface
Chapter 3, "Definitions of Programmable Command Formats"
In the "Change Queue Manager" and "Inquire Queue Manager (Response)" sections add the following description of the GSK_PKCS11 value of the SSLCryptoHardware parameter:
The PKCS #11 token label must be entirely in lower case. Note that if you have configured your hardware with a mixed case or upper case token label you must reconfigure it with this lower case label.
WebSphere MQ V5.3 Using Java
Chapter 4, "Using WebSphere MQ classes for Java Message Service"
In the section "Running the sample applet", subsection "Running the applet as an application", before running the applet using the command:
java JMSTestApplet
compile the applet using the command:
javac JMSTestApplet.java
Chapter 5, "Using the WebSphere MQ JMS administration tool"
In section "Administering JMS objects" add a note to Table 11 "Property names and valid values": In certain environments, specifying the same queue name for both the brokerDurSubQueue and brokerCCDurSubQueue attributes on an MQTopic object can result in a JMSException being thrown. It is advised that separate queues are used for these two attributes."
Chapter 11, "Programming publish/subscribe applications"
In the section "Solving publish/subscribe problems" add a new section at the end, as follows:
"Other Considerations"
When connecting to WebSphere MQ Event Broker V2.1 on a Microsoft Windows system, with a large number of JMS clients using TCP/IP sockets (that is with a JMSAdmin property type of TRANSPORT(DIRECT)), note the following.
If a large number of connections happen almost simultaneously, a java.net.BindException Address in use exception might be thrown in response to a TopicConnection call. You can try to avoid this by catching the exception and retrying, or by pacing the connections.
WebSphere MQ V5.3 Security
Chapter 12, "Working with the Secure Sockets Layer (SSL) on UNIX systems"
The IKEYCMD command documented for creating a new CMS key database file does not produce the password stash file, which is essential for successful SSL message transfer. To create a key database file and a password stash file use the following IKEYCMD commands:
gsk6cmd -keydb -create -db <filename> -pw <password> -type cms -expire <days>
gsk6cmd -keydb -stashpw -db <filename> -pw <password>
where:
-db <filename> is the fully qualified path name of a CMS key database.
-pw <password> is the password for the CMS database.
-type cms is the type of database.
-expire <days> is the expiration time in days of the database password.
The default is 60 days for a database password.
In the section "Adding personal certificates to a key repository" before step 1: "Execute the gsk6ikm command to start the iKeyman GUI." add a step 0.5: Ensure that the certificate file to be imported has write permission for the current user
In the section "Configuring for cryptographic hardware" add a new last paragraph (just above the section "Managing Certificates on PKCS #11 hardware"):
If you have configured cryptographic hardware which uses the PKCS #11 interface using any of these methods, you must store the personal certificate for use on your channels in the key database file for the cryptographic token you have configured. This is described in "Managing Certificates on PKCS #11 hardware".
In the section "Managing Certificates on PKCS #11 hardware" replace point 8 by
8. Click OK. The Personal Certificates field shows the label of the new
personal certificate you added. You will note that this label is formed by
adding the cryptographic token label before the label you supplied.
Appendix A, "Cryptographic hardware"
Add a new entry to the list of supported cryptographic hardware:
IBM e-business Cryptographic Accelerator (#4960)
Interface: PKCS #11
Platforms:
AIX 5.1
WebSphere MQ V5.3 Application Programming Reference
Chapter 20, "MQSCO - SSL configuration options"
In the section "fields", in the CryptoHardware field, the GSK_PKCS11 string should be described as
GSK_PKCS11= <the PKCS #11 driver path and filename>; <the PKCS #11 token label>;<the PKCS #11 token password>;
Add the following description of this string
The PKCS #11 driver path is an absolute path to the shared library providing support for the PKCS #11 card. The PKCS #11 driver filename is the name of the shared library. An example of the value required for the PKCS #11 driver path and filename is /usr/lib/pkcs11/PKCS11_API.so
The PKCS #11 token label must be entirely in lower case. Note that if you have configured your hardware with a mixed case or upper case token label you must reconfigure it with this lower case label.
WebSphere MQ V5.3 Application Programming Guide
Chapter 20, "Building your application on AIX"
Section "Preparing C programs" add a note "When using the VisualAge C/C++ v6.0 compiler for C++ programs you must include the option "-q namemangling=v5" to get all the WebSphere MQ symbols resolved when linking the libraries."
Appendix A, "Language compilers and assemblers"
Replace the existing Table 54. Language compilers and assemblers for WebSphere MQ for AIX by
| Language | Compiler/Assembler |
| C++ | IBM VisualAge C++ Professional, V5 or V6 |
| C | IBM C for AIX, V5 or V6
IBM VisualAge C Professional, V5 or V6 |
| COBOL | Micro Focus Server Express, V2.0.10 or V2.0.11 |
Note: When using the VisualAge C/C++ v6.0 compiler for C++ programs you must include the option "-q namemangling=v5" to get all the WMQ symbols resolved when linking the libraries.
WebSphere MQ V5.3 Using C++
Appendix A, "Compiling and linking"
In section "Compilers for WebSphere MQ platforms", subsection AIX add "When using the VisualAge C/C++ v6.0 compiler for C++ programs you must include the option "-q namemangling=v5" to get all the WebSphere MQ symbols resolved when linking the libraries.
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.
|