WebSphere MQ for AIX, V5.3 README
Welcome to WebSphere MQ for AIX, Version 5.3.
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/integration/wmq/
The SupportPac Web page is at:
http://www.ibm.com/software/integration/support/supportpacs/
For current information on known problems and available fixes, see
the Support page of the WebSphere MQ Web site at:
http://www.ibm.com/software/integration/wmq/support/
Web documentation updates
The latest updates to the Web-based WebSphere MQ documentation are now
available from the WebSphere MQ Web site at:
http://www.ibm.com/software/integration/wmq/library/
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 V5.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, Operating System", AIX 5.1 (Power 32 bit only) with PTF U476879 (trace update) also requires APAR fix IY29345.
We also recommend AIX PTFs U477366, U477367 and U477368 be installed on AIX V5.1 32- and 64-bit systems.
The C/C++ runtime installed on AIX must be at level 5.0.2.0 or higher.
Chapter 3, "Installing the WebSphere MQ for AIX server"
In the section "Installation procedure", the message issued if the setmqcap
command is not run is as follows:
Purchased processor allowance not set (use setmqcap). If you have not
purchased enough capacity units for your server, the message
"Insufficient license units" is displayed.
WebSphere MQ V5.3 System Administration Guide
Chapter 11 "Transactional support"
In the section "Using the Microsoft Transaction Server(MTS)", on Windows 2000, Hotfix Q313582 is required to use COM+. The hotfix is also known as "COM+ Rollup Package 18.1".
Chapter 13 "Supporting the Microsoft Cluster server (MSCS)"
In the section "Putting a Queue Manager under MSCS control", change step 4
to say:
4. Create an MSCS group to be used to contain the resources for the
queue manager. Name the group in such a way that it is obvious which
queue manager it relates to. For example, you might decide to call the
group QM1-Group. Each group must only contain one queue manager, as
described in Using multiple queue managers with MSCS.
In the section "WebSphere MQ MSCS support utility programs"
After successfully registering the WebSphere MQ MSCS libraries, using the
haregtyp.exe tool, it will be necessary to re-boot the system if there has
been no re-boot since installation of the WebSphere MQ product.
Chapter 15, "Problem determination"
In the section "Tracing", "Selective component tracing on WebSphere MQ for Windows", use the -t and -x options to control the amount of trace detail to record. By default, all trace points are enabled. The -x option enables you to specify the points you do not want to trace. So if, for example, you want to trace only data flowing over communications networks, use:
strmqtrc -x all -t comms
For a full description of the trace command, see strmqtrc (Start trace).
Chapter 17 "The Control Commands"
- In the section "amqmcert", there are known problems if AMQMCERT is used to configure both a WebSphere MQ client and server on the same Windows machine. In the unlikely event that this is required, you are advised to use the GUI (Explorer or Services) to configure SSL certificates for the server queue manager.
- In the section "dspmqtrc", subsection "Required parameters", replace the existing text with:
InputFileName
When one input file is given, dspmqtrc either formats it to stdout or uses the output file named by the user. If more than one input file is given, the output file named by the user is ignored, and formatted files are named AMQXXXXX.FMT, based on the PID of the trace file.
- In the section "dspmqcap", note that the command displays the number of processors for which you have purchased capacity units.
- In the section "setmqcap", note that you set the parameter CapUnits to the number of processors for which you have purchased capacity units.
Chapter 19, "Authorization service"
In the section "Object Authority (OAM)", add the following subsection:
Object Authority Manager (OAM) enhancements
This section describes some enhancements to the Object Authority Manager
(OAM) for MQSeries Version 5.2 and WebSphere MQ Version 5.3.
Refreshing the OAM after changing a user's authorization
In versions of MQSeries before Version V5.2, most changes to a user's authorization group membership made at the operating system level were not implemented by the OAM immediately, but took effect only after the queue manager was stopped and restarted.
In MQSeries Version 5.2 and WebSphere MQ Version 5.3, you can request that the OAM's authorization group information be updated immediately, reflecting changes made at the operating system level, without needing to stop and restart the queue manager.
Note: When you change authorizations with the setmqaut command, the OAM
supplied with MQSeries or WebSphere MQ implements such changes immediately.
Queue managers running the OAM provided with MQSeries Version 5.2 and
WebSphere MQ Version 5.3 store authorization data on a local queue,
called SYSTEM.AUTH.DATA.QUEUE.
Authorization data in MQSeries Version 5.2 and WebSphere MQ Version 5.3 is managed by the amqzfuma process. The function provided by the OAM is unaffected by this change and queue managers are automatically created to use the latest OAM as the default authorization service component. This
version creates no new authorization files, and existing files are no longer updated or deleted.
Migration
All authorization data is migrated from the authorization files to the
authorization queue the first time you restart the queue manager after
migrating from MQSeries 5.1. If the OAM detects a missing file:
1) If the authorization applies to a single object, the OAM gives the mqm
group access to the object and continues with the migration. Message
AMQ5528 is written to the queue manager's error log. Refer to the
Messages book for more information about message AMQ5528.
2) If the authorization applies to a class of objects, the OAM stops the
migration. The queue manager does not start until the file has been
replaced.
When you still want to store authorization data in files
This section tells you how you can continue to store authorization data in
files. However, if you do so, the performance of the OAM can be affected.
Storing authorization data on a local queue reduces the time required
to check an authorization.
The default OAM service module is amqzfu. MQSeries Version 5.2 and WebSphere MQ Version 5.3 also provide the previous service module as amqzfu0. There are two ways in which you can use the previous module to continue to store authorization data in files:
1) Modify the Module attribute in the ServiceComponent stanza of the qm.ini
file to use amqzfu0. This option is possible only for queue managers
created with a version of MQSeries before V5.2.
2) Replace the amqzfu module by the previous version. For example, you can do this by:
1. Removing the new amqzfu module
2. Renaming amqzfu0 as amqzfu
Note: You can restore the new amqzfu module from the copy provided
as amqzfu1.
Note: Once you have created or restarted a queue manager with the new amqzfu module, you can no longer replace it with the previous version. The migration process, described above, is not reversible.
Chapter 21, "Installable Services Interface Reference Information"
Add the following new function:
MQZ_REFRESH_CACHE
This function is provided by an MQZAS_VERSION_3 authorization service component, and is invoked by the queue manager to refresh the list of authorizations held internally by the component.
The function identifier for this function (for MQZEP) is
MQZID_REFRESH_CACHE (8L).
Syntax
MQZ_REFRESH_CACHE(QMgrName, ComponentData, Continuation, CompCode, Reason)
Parameters
QMgrName (MQCHAR48) - input
Queue manager name.
The name of the queue manager calling the component. This name is padded
with blanks to the full length of the parameter; the name is not terminated
by a null character.
The queue-manager name is passed to the component for information; the
authorization service interface does not require the component to make
use of it in any defined manner.
ComponentData (MQBYTE) - input/output
Component data.
This data is kept by the queue manager on behalf of this particular
component; any changes made to it by any of the functions provided by
this component are preserved, and presented the next time one of this
component's functions is called.
The length of this data area is passed by the queue manager in the
ComponentDataLength parameter of the MQZ_INIT_AUTHORITY call.
Continuation (MQLONG) - output
Continuation indicator set by component.
The following values can be specified:
MQZCI_DEFAULT
Continuation dependent on queue manager.
For MQZ_REFRESH_CACHE this has the same effect as MQZCI_CONTINUE.
MQZCI_CONTINUE
Continue with next component.
MQZCI_STOP
Do not continue with next component.
CompCode (MQLONG) - output
Completion code.
It is one of the following:
MQCC_OK
Successful completion.
MQCC_FAILED
Call failed.
Reason (MQLONG) -- output
Reason code qualifying CompCode.
If CompCode is MQCC_OK:
MQRC_NONE
(0, X'000') No reason to report.
If CompCode is MQCC_FAILED:
MQRC_SERVICE_ERROR
(2289, X'8F1') Unexpected error occurred accessing service.
For more information on this reason code, see the MQSeries Application
Programming Reference book.
C invocation
MQZ_REFRESH_CACHE (QMgrName, ComponentData,
&Continuation, &CompCode, &Reason);
Declare the parameters as follows:
MQCHAR48 QMgrName; /* Queue manager name */
MQBYTE ComponentData[n]; /* Component data */
MQLONG Continuation; /* Continuation indicator set by
component */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */
WebSphere MQ V5.3 Programmable Command Formats and Administration Interface
List of tables
Note that Tables 3, 4, and 5, which refer to CipherSpecs that can be used with WebSphere MQ, are not current. See the Security manual for the most recent table.
Chapter 2, "Using Programmable Command Formats"
In the section "Authority checking for PCF commands", the following PCF
commands also require the user id to belong to the mqm group:
Reset Cluster
Refresh Cluster
Suspend Queue Manager Cluster
Resume Queue Manager Cluster
Chapter 4, "Definitions of Programmable Command Formats"
Add the PCF command:
Security command "Refresh Security"
The Refresh Security (MQCMD_REFRESH_SECURITY) command refreshes the list of authorizations held internally by the authorization service component.
This PCF is supported if you are using MQSeries Version 5.2 and 5.2.1 or WebSphere MQ Version 5.3.
Required parameters:
None
Optional parameters:
None
Error codes
In addition to the values for any command, the following can be returned for this command in the response format header:
MQRCCF_PARM_COUNT_TOO_BIG
Parameter count too big.
WebSphere MQ V5.3 Intercommunication
Chapter 6, "Channel attributes"
In the section "User ID (USERID)", append the following note:
This also applies to USERIDs when defining a channel using MQSC.
WebSphere MQ V5.3 Script (MQSC) command reference
Chapter 1, "Using MQSC commands"
In the section "Rules for naming WebSphere MQ Objects", subsection "Reserved queue names", add SYSTEM.AUTH.DATA.QUEUE. to the list of reserved queue names.
Chapter 2, "The MQSC commands"
1. In the section "DEFINE CHANNEL", Table 3, which refers to CipherSpecs that can be used with WebSphere MQ is not current. See the Security manual for the most recent table.
2. In the section "PING CHANNEL", on HP-UX 11 it is not possible to ping an SSL channel using runmqsc. This also applies to using PCF or the Windows Explorer.
3. In the section "REFRESH SECURITY", note that the command REFRESH SECURITY, which was previously only valid on z/OS, is now also valid on AIX. The syntax for the command on AIX is:
>>-REFRESH SECURITY-------------------------------------->> | |
---------(---*---)---------
The optional * parameter specifies that the security refresh is to
be performed for all resource classes.
WebSphere MQ V5.3 Security
Chapter 6, "WebSphere MQ SSL support"
- In the section "Channel Attributes", the attribute types for the channel SSL Peer (SSLPEER) parameter, for example, "CN" or "L", must be entered in upper-case.
WebSphere MQ Explorer returns "Unexpected WebSphere MQ error" if any of the following strings are entered in an invalid format:
1) Queue manager SSL key repository location.
2) Custom channel SSL Cipher Specification (SSLCIPH) parameter.
3) Channel SSL Peer (SSLPEER) parameter.
- In the section "WebSphere MQ client considerations", if you want to perform client authentication with the Java client to a queue manager on a Windows platform, you must ensure that the CA certificates required to authenticate the client personal certificate are placed in the queue manager certificate store AND in the ROOT certificate store of the Windows operating system. You should also ensure that the queue manager is restarted when the CA certificate or certificates are added to, or removed from, the ROOT certificate store of the Windows operating system.
Chapter 15, "Working with CipherSpecs"
In the Table "Table 1. CipherSpecs that can be used with WebSphere MQ SSL support", the CipherSpec "TRIPLE_DES_SHA_US3" should read "TRIPLE_DES_SHA_US".
Various Chapters
WHEN SSL CHANGES BECOME EFFECTIVE
Changes to the certificates in the UNIX, OS/400, and z/OS key repositories
become effective as follows:
(a) On UNIX and OS/400 platforms, when a new outbound single channel process first runs an SSL channel.
(b) On UNIX and OS/400 platforms, when a new inbound TCP/IP single channel process first receives a request to start an SSL channel.
(c) On UNIX and OS/400 platforms, for channels which 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, this is generally best achieved by restarting the queue manager.
(d) On UNIX and OS/400 platforms, for channels which run as threads of a 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, this is generally best achieved by restarting the queue manager.
(e) On Windows, UNIX and OS/400 platforms, for channels which 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.
(f) On z/OS, when the channel initiator is started or restarted.
A new value for the SSLCRLNameList (SSLCRLNL) or SSLKeyRepository (SSLKEYR) queue
manager attributes becomes effective:
(a) On Windows, UNIX and OS/400 platforms, when a new outbound single channel process first runs an SSL channel.
(b) On Windows, UNIX and OS/400 platforms, when a new inbound TCP/IP single channel process first receives a request to start an SSL channel.
(c) On Windows, UNIX and OS/400 platforms, for channels which 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, this is generally best achieved by restarting the queue manager.
(d) On Windows, UNIX and OS/400 platforms, for channels which run as threads of a 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, this is generally best achieved by restarting the queue manager.
(e) On Windows, UNIX and OS/400 platforms, for channels which run as threads of a TCP/IP listener, when the listener is (re)started and first receives a request to start an SSL channel.
(f) On z/OS, when the channel initiator is started or restarted.
A new value for the SSLCryptoHardware (SSLCRYP) queue manager attribute becomes effective:
(a) When a new outbound single channel process first runs an SSL channel.
(b) When a new inbound TCP/IP single channel process first receives a request to start an SSL channel.
(c) For channels which 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, this is generally best achieved by restarting the queue manager.
(d) For channels which run as threads of a 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, this is generally best achieved by restarting the queue manager.
(e) For channels which 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.
WebSphere MQ V5.3 Application Programming Guide
Chapter 20, "Building your application on AIX"
When running threaded server or client applications under AIX 5.1 or AIX 4.3, set the AIX environment variable:
AIXTHREAD_SCOPE=S
Chapter 35, "Sample programs (all platforms except z/OS)"
1. In the section "Features demonstrated in the sample programs", note that the sample programs amqsputw.c, amqsputw.exe, amqsgetw.c, and amqsgetw.exe are no longer shipped with WebSphere MQ (they are old DOS programs.
2. In the section "Dead-letter queue handler sample", the reference to the System Management Guide should be to Chapter 12 of the System Administration Guide,
Appendix H, "Code page conversion"
- In the section "Simplified Chinese", add the following:
GB18030 support
Support for GB18030 is being added to operating systems regularly. Where this support will improve the support provided by WebSphere MQ, information will be added to the online version of this readme.
AIX support
There is no operating system support for GB18030 on AIX V4.3.3.
On AIX V5.1, APAR IY26937 provides support for conversion between GB18030 (CCSID 5488) and Unicode. Support is NOT provided for the conversion between GB18030 and 1388 (EBCDIC). Conversion between these CCSIDs can cause unpredictable results.
- In the section "Traditional Chinese", add the following:
On AIX, if you want to convert between CCSID 950 and 819 (AIX codesets big5 and ISO8859-1) remove the files:
/usr/lib/nls/loc/iconv/ISO8859-1_big5
/usr/lib/nls/loc/iconv/big5_ISO8859-
WebSphere MQ V5.3 Messages
Messages in the following range are missing from the non-English versions of the Messages book:
7500 through 7999
8500 through 8999.
For a description of these messages, please see the English version of the Messages book.
WebSphere MQ classes for Java and Java Message Service
General Notes
1) Supported JDK versions:
AIX IBM JDK 1.3.1
2) If you want to use Pub/Sub applications you need one of the following:
- Service at Fix Pack 8 level (which includes the Publish/Subscribe function) Please note that SupportPac MA0C: WebSphere MQ (MQSeries) Publish/Subscribe, which is only for use with WebSphere MQ V5.3 at Fix Pack 7 level or earlier, is no longer available for download.
- WebSphere MQSeries Integrator V2
3) Configuration
a) After installation, ensure that com.ibm.mq.jar, com.ibm.mqjms.jar,
jms.jar, and jndi.jar in the java/lib directory are present in the
CLASSPATH. Include the java/lib directory itself in the CLASSPATH
to access the properties files used by the base Java API. Include
providerutil.jar and either fscontext.jar or ldap.jar if you need to
access a JNDI namespace.
b) A number of convenience scripts are provided in the java/bin
directory. You might want to add this directory to your PATH variable.
4) Note that connector.jar is now packaged in the java/lib directory with
the other jar files. Users familiar with MQSeries classes for Java and
MQSeries classes for Java Message Service (MA88) 5.2 must be aware of
the following issues relating to this change:
- An entry must be made for connector.jar in the CLASSPATH, as described
on page 12 of the Using Java manual.
- Users who have implemented their own ConnectionManagers as described
on page 70 of the Using Java manual must replace references to
com.ibm.mq.resource and com.ibm.mq.resource.spi with references
to javax.resource and javax.resource.spi respectively.
Information not contained in the publications
1. The following Java libraries from Sun Microsystems are
redistributed with this product:
connector.jar Version 1.0
fscontext.jar Version 1.2 Beta 3
ldap.jar Version 1.2.2
jms.jar Version 1.0.2
jndi.jar Version 1.2.1
jta.jar Version 1.0.1
providerutil.jar Version 1.2
2. Subscription Store: BROKER option
To use the broker-based subscription store, you must use WebSphere MQ
Version 5.3 with the broker supplied as SupportPac MA0C. No other
combination of queue manager and broker presently supports this option.
See the Using Java manual for further information regarding subscription
stores.
WebSphere MQ V5.3 Clients
General note for WebSphere MQ V5.3 AIX clients:
The client code supplied on the server and client CD includes support
for Secure Sockets Layer (SSL). The SSL code includes administrative
functions, so the installed size of the client is larger than that of
the MQSeries V5.2 client. If you do not need the SSL functionality,
the MQSeries V5.2 client operates with WebSphere MQ V5.3 servers
and can be obtained from the WebSphere MQ SupportPac Web site.
Chapter 2, "Preparing for installation"
A DCE-threaded WebSphere MQ client application cannot be run over SSL on
AIX. Because TxSeries uses DCE threads, it cannot run as a WebSphere MQ
client that uses SSL on AIX.
Chapter 3, "Installing client components from WebSphere MQ products
and Version 5 MQSeries products (not z/OS)
Add the following new section:
Electronic Software Download installation
These instructions apply to installing the UNIX WebSphere MQ Clients from
an installation image downloaded from IBM. Use it with the Quick
Beginnings or Clients book 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
1. 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 the amount of free space indicated
below (this is in addition to the disk space required for the product,
as detailed in the Quick Beginnings book):
MQ53ClientSSL_aix.tar 110MB
2. Make this directory the current directory and use the command:
tar -xvf .tar
to create the installation image.
3. After the operation succeeds, you can delete the .tar.
4. Use the WebSphere MQ Quick Beginnings book for your platform, or the
Clients book, 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.
Add the following new chapter:
Secure Sockets Layer (SSL) on WebSphere MQ clients
SSL channels
There are two ways of specifying that a channel uses SSL. In order of
decreasing precedence, they are:
1 When your application makes an MQCONNX call
2 Using the client channel definition table
You cannot use the MQSERVER environment variable to specify that a
channel uses SSL.
LDAP CRL (certificate revocation list) definitions on WebSphere MQ clients
There are two ways of defining an LDAP CRL on a WebSphere MQ client.
In order of decreasing precedence, they are:
1 When your application makes an MQCONNX call
2 Using the client channel definition table
These methods are explained below.
MQCONNX
On an MQCONNX call, the MQSCO structure, in conjunction with the SSL
fields in MQCD, allows an application running as a WebSphere MQ client
to specify configuration options that control the use of SSL for the
client connection.
You can also use the MQAIR structure. MQAIR allows a WebSphere MQ client
to specify authentication information that is to be used for the
client connection. Each MQAIR structure contains an authentication
information record containing the information needed to access a single
LDAP CRL server. The MQSCO structure points to the first record in the
array of MQAIR records.
Both MQSCO and MQAIR are input parameters to the MQCONNX call. For more information, and the data structure details for MQSCO and MQAIR, see the WebSphere MQ Application Programming Reference.
Client channel definition table
When you define a client-connection (CLNTCONN) SSL channel, if the
SSLCRLNamelist queue manager attribute is set, any CRL information
current on the queue manager system on which the channel is defined is
included with the resulting client channel definition. If further CRL
information is added or the CRL information is altered or deleted, the
change is reflected in the client channel definition table on the queue
manager system. If the SSLCRLNamelist queue manager attribute is set to
blank, all the CRL information is removed from the client channel
definition table.
If a client channel definition table containing CRL information is
moved to a client system, the same CRL server information is used at
both the queue manager and client ends of the channel.
You can use different CRL information at the two ends of a channel, by
temporarily setting up the queue manager system with the client CRL
information and then copying the client channel definition table to the
client system. This CRL information then applies on the client system.
The queue manager system then alters its CRL information to what it
requires for itself.
When LDAP CRL information is added to an existing client channel
definition table, the information is added to the end of the table, and
existing channel definitions in the table are not affected. If these
existing channel definitions are from MQSeries systems before WebSphere
MQ 5.3, they can continue to be used by the appropriate MQSeries
clients. Note that MQSeries Version 5.2 and earlier clients fail in a
controlled manner if they encounter LDAP CRL information.
WebSphere MQ V5.3 System Administration Guide
amqmcert
Option omitted:
-r handle
Removes the certificate identified by handle.
Trademarks
The following terms are trademarks of the IBM Corporation in the
United States, or other countries, or both:
IBM AIX 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.
Change History
Last updated: 7 August 2008
|