WebSphere MQ 5.3 for AIX
Installation

Overview

Overview

You can find more information on the WebSphere MQ Web site and the SupportPac Web page

For current information on known problems and available fixes see the Support page of the WebSphere MQ Web site.

The Web-based WebSphere MQ documentation are now available from the WebSphere MQ Web site at:

WebSphere MQ for AIX V5.3 Electronic Software Download installation

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.

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.

Preparing for installation

Before you install WebSphere MQ for AIX, you need to:

Create the file systems used to hold WebSphere MQ and its data.
Set up the user ID and group for WebSphere MQ.

File systems

The installation directory for the WebSphere MQ product code is /usr/mqm. Working data is stored in /var/mqm. You cannot change these.

Creating a file system for the product code

Install WebSphere MQ for AIX in /usr/mqm. The space required depends on how many components you install. Typically you need 50MB for a server installation, or 15MB for a client installation.

If you cannot install the product code in this file system (for example, if it is too small to contain the product), you can do one of the following:

Create a new file system and mount it as /usr/mqm.
Create a new directory anywhere on your machine, and create a symbolic link from /usr/mqm to this new directory. For example:
mkdir /bigdisk/mqm
ln -s /bigdisk/mqm /usr/mqm

Allow the install program to expand the file system.

Whichever of these options you pick, do it before installing the product code. The file system into which the code is installed can be a remote network device, for example, NFS. However, define the mount options defined on that device to allow setuid programs, including root access, to run.

Creating a file system for the working data

Before you install WebSphere MQ for AIX we advise you to create and mount a journalized file system called/var/mqm. Use a partition strategy with a separate volume for the WebSphere MQ data. This means that other system activity is not affected if a large amount of WebSphere MQ work builds up.

To determine the size of the /var/mqm file system for a server installation, consider:

The maximum number of messages in the system at one time
Contingency for message buildups, if there is a system problem
The average size of the message data, plus 500 bytes for the message header
The number of queues
The size of log files and error messages
The amount of SSL trace that is written to the /var/mqm/trace directory (this is a new directory for this release)

Allow 50 MB as a minimum for a WebSphere MQ server. You need less space in /var/mqm for a WebSphere MQ client, typically 15 MB.

Creating separate file systems for working data

You can also create separate file systems for your log data (/var/mqm/log) and error files (/var/mqm/errors). If possible, store log files on a different physical volume from the WebSphere MQ queues (/var/mqm). This ensures data integrity in the case of a hardware failure.

If you create separate file systems:

The /var/mqm and /var/mqm/log directories must be on a local file system.
The /var/mqm/errors directory can be NFS mounted.

If you are creating separate file systems allow a minimum of 30 MB of storage for /var/mqm, 20 MB of storage for /var/mqm/log, and 4 MB of storage for /var/mqm/errors.

If you want to use individual queues that will hold more than 2 GB of data, enable /var/mqm to use large files.

The size of the log file depends on the log settings that you use. The size we recommend is for circular logging using the default settings. For further information on log sizes see WebSphere MQ System Administration Guide.

User ID and group

Creating the user ID and group

Both user ID and group ID must be set to mqm. For stand-alone machines, you can create the new user ID and group IDs locally; for machines administered in a network information services (NIS) domain, create the IDs on the NIS master server machine.

You can use the System Management Interface Tool (smit), for which you require root authority.

To create the mqm group, display the required window using this sequence:
```
  Security & Users
    Groups
      Add a Group
```
Set the name field to mqm.
To create the new user, mqm, display the required window using this sequence:
```
  Security & Users
    Users
      Add a User
```
Set the name field to mqm.
To add a password to the new user ID, display the required window using this sequence:
```
  Security & Users
    Change a Users Password 
      Passwords
```
Set the password as required.

Adding existing user IDs to the group

If you want to run administration commands, for example crtmqm (create queue manager) or strmqm (start queue manager), your user ID must be a member of the mqm group.

Users do not need mqm group authority to run applications that use the queue manager; it is needed only for the administration commands.

You can use smit to add an existing user ID to the mqm group. Display the required window using this sequence:

  Security & Users
    Users
      Change / Show Characteristics of a User

Enter the name of the user in the User Name field. Add mqm to the Group SET^(TM) field, which is a comma-separated list of the groups to which the user belongs. Users need not have their primary group set to mqm. Provided that mqm is in their set of groups, they can use the administration commands.

AIX by default has a slightly different System V Shared Memory model than the other UNIX platforms. This results in a limit of 10 shared memory segments being attached simultaneously by an individual process.

With WebSphere MQ for AIX, V5.3, queue managers make use of the AIX extension EXTSHM, which allows more than 10 segments to be attached by a single process. This is enabled by exporting the environment variable EXTSHM=ON in the environment before a process is started (the variable must be in upper case).

To take full advantage of this facility, set the environment variable EXTSHM=ON in the environment of all WebSphere MQ applications before they are started. All WebSphere MQ queue manager processes will set this variable for the lifetime of their process, if it is not already set when the queue manager is started.

If a user's WebSphere MQ application chooses not to set this variable, then it can still connect and communicate with WebSphere MQ correctly. However, if the application tries to use more shared memory than is available in the 10 slots provided for attaching shared memory segments, that request might fail.

The types of situations that can increase the number of segments that WebSphere MQ tries to attach are:

Many threads all attach to WebSphere MQ
Large messages transfer between the application and WebSphere MQ
An application uses other application libraries, such as database connections, and these other libraries allocate shared memory from the 10 slots available.

Note:: Not all applications support the use of the EXTSHM=ON environment variable. Do not set this value globally (for example, in /etc/environment). It is better to set this value locally in the profile of any user who wants to run WebSphere MQ applications.

Installation procedure

There are different ways of installing WebSphere MQ for AIX. You can use:

Easy installation
Custom installation
National language installation
Remote installation

The Easy installation procedure gives a minimal configuration on your machine, consisting of the following components:

Runtime
Base Kit
Server
Sample programs

If you want any of the other components, such as online documentation, use Custom installation.

If you want messages in a different national language from the locale selected on your machine, use National language installation.

To install WebSphere MQ for AIX on a remote machine, see Remote installation.

Before you start the installation procedure, make sure you have prepared your system as described in Preparing for installation.

Note:: We recommend that you install AIX PTF U472177 before installing WebSphere MQ for AIX, V5.3. This PTF updates the bos.rte.install fileset on AIX to Version 4.3.3.17.
Without this PTF it is possible that the WebSphere MQ product appears to install correctly, however, some of the product files might be missing.

Easy installation

This installation procedure uses the xinstallm program, which is available in the X11.vsm.rte optional fileset.

Log in as root.
Insert the WebSphere MQ for AIX Server CD-ROM into the CD-ROM drive.
Type: xinstallm -ez
The WebSphere MQ Welcome window is displayed, followed by a second window where you can make some selections.
Choose the CD-ROM software source.
For Which bundle of software would you like to install? choose Media-defined.
Click Install/Update to create the mqm.Server and mqm.Client.
Choose the mqm.Server bundle and click Install/Update again.
This installs the filesets in this bundle, and a work in progress window gives information as the installation proceeds.

At the end of the installation click on the View log button and scroll to the bottom of the log to see the filesets that have been installed successfully.

Once you have installed WebSphere MQ for AIX, you need to run the setmqcap command, inputting the number of processors you have paid for. The relationship between processors and capacity units for UNIX servers is show in Table 3.

Table 3. Relationship between processors and capacity units for UNIX servers

Server Capacity units required
RISC 1-2 processors per box 4
RISC 3-8 processors per box 8
RISC 9-23 processors per box 16
RISC 24 or more processors per box 30

Server	Capacity units required
RISC 1-2 processors per box	4
RISC 3-8 processors per box	8
RISC 9-23 processors per box	16
RISC 24 or more processors per box	30

The first time you start a queue manager on this machine, if you have not already run the setmqcap command, you will get a warning saying Purchased processor capacity units not set (use setmqcap), or if you have already run setmqcap but entered an incorrect value, you will get the warning Insufficient capacity units. You will need to run setmqcap to correct this before you can start a queue manager.

To change your installation, or back out a failed installation, use the System Management Interface Tool (smit) as described in the following text.

Custom installation

This installation procedure uses the System Management Interface Tool (smit), enabling you to select which components you want to install. The components and filesets are listed in WebSphere MQ components; install at least the Runtime, Base Kit, and Server components.

Log in as root.
Insert the WebSphere MQ for AIX Server CD-ROM into the CD-ROM drive.

Select the required smit window using the following sequence:

  Software Installation and Maintenance
    Install and Update Software
      Install and Update from LATEST Available Software

Alternatively you can use a fastpath command (smitty install_latest).

Click List to display the input device or directory for the software.
Select /dev/cd0 (CD-ROM Drive) and click OK.
Use the SOFTWARE to install field to obtain a list of available filesets, and select the filesets you want to install.

Note:

If you install the DCE extensions, you will not be able to run SSL channels.
Make sure that Include corresponding LANGUAGE filesets? is set to Yes.
On AIX V4.3.3:
1. Click OK to install WebSphere MQ.
On AIX V5.1:
1. Change Preview new LICENSE agreements? to yes and click OK to view the license agreements.
2. Change ACCEPT new license agreements? to yes and click OK to accept the license agreements and install WebSphere MQ.
Once you have installed WebSphere MQ for AIX, you need to run the setmqcap command, inputting the number of processors you have paid for. The relationship between processors and capacity units for UNIX servers is show in Table 3.

National language installation

The Easy and Custom installation procedures install messages in the language, specified by the locale selected on your machine, by default. If you require messages in a different language, use the following procedure.

The process is similar to Custom installation. You must install at least the Runtime, Base Kit, and Server components, in addition to the Message Catalog for your chosen language.

Log in as root.
Insert the WebSphere MQ for AIX Server CD-ROM into the CD-ROM drive.

Select the required smit window using the following sequence:

  Software Installation and Maintenance
    Install and Update Software
      Install and Update from ALL Available Software

Check List to display the input device or directory for the software.
Select /dev/cd0 (CD-ROM Drive) and click OK.
Use the SOFTWARE to install field to obtain a list of available filesets, and select the filesets you want to install (including the message catalog).
On AIX V4.3.3:
1. Click OK to install WebSphere MQ.
On AIX V5.1:
1. Change Preview new LICENSE agreements? to yes and click OK to view the license agreements.
2. Change ACCEPT new license agreements? to yes and click OK to accept the license agreements and install WebSphere MQ.
Once you have installed WebSphere MQ for AIX, you need to run the setmqcap command, inputting the number of processors you have paid for. The relationship between processors and capacity units for UNIX servers is show in Table 3.

Remote installation

To install WebSphere MQ for AIX on a remote machine, you can use standard AIX techniques.

To do this, log on to both systems as root. Put the WebSphere MQ for AIX Server CD-ROM in the CD-ROM drive of the machine from which you are going to take the copy. Follow this procedure for each target machine on which you want to install the product:

Create a CD-ROM file system on the local machine, and mount the CD-ROM file system on the local machine (mount /cdrom).
Using SMIT, export this file system using NFS to the target machine.
Log on to the remote machine and use NFS to mount the CD-ROM file system that you created (mount local_machine:/cdrom).
Use smit to install WebSphere MQ for AIX from the target directory that you specified.

Reinstalling WebSphere MQ for AIX

If you reinstall WebSphere MQ for AIX, a check is made to see if the WebSphere MQ configuration file (mqs.ini) exists. If the file exists, it is kept and used with the newly installed system. If the file does not exist, an empty mqs.ini file is placed in the directory /var/mqm.

Setting the queue manager CCSID

The coded character set identifier (CCSID) is fixed when you create a queue manager. The CCSID is determined by the locale that you use to run the crtmqm command. For more information on using command sets see WebSphere MQ System Administration Guide

The following table gives some examples of using the LANG parameter to change the code set and CCSID.

Table 4. Examples of setting the CCSID

Example Code set CCSID
export LANG=C (this is the default locale) ISO8859-1 819
export LANG=en_US ISO8859-1 819
export LANG=En_US IBM-850 850

Example	Code set	CCSID
export LANG=C (this is the default locale)	ISO8859-1	819
export LANG=en_US	ISO8859-1	819
export LANG=En_US	IBM-850	850

To modify an existing queue manager CCSID, follow this procedure:

Start MQSC commands by typing: runmqsc
Display the existing queue manager CCSID, using the MQSC command:
```
display qmgr ccsid
```
Change the CCSID to the new CCSID with the MQSC command:
```
alter qmgr ccsid (new.ccsid)
```
where new.ccsid is the number of the new CCSID.
Stop MQSC commands by typing: end
Stop the queue manager, and then restart it and any channels it uses.

See Chapter 10, Code sets supported by WebSphere MQ for AIX for further information about supported code sets. See Migrating to Euro support for information on migrating to a CCSID that supports the euro character.

Verifying a local installation

To verify a local installation with a simple configuration of one queue manager and one queue, use sample programs to put a message onto the queue and to read the message from the queue.

Note:: WebSphere MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is converted automatically to uppercase unless you enclose it in single quotation marks. Make sure you type the examples exactly as shown.

The procedures outlined in this section describe how to configure your default queue manager from the command line.

Setting up the installation

From a shell window, use these steps to install a queue manager and a queue:

Create a default queue manager called venus.queue.manager by entering the following command:
crtmqm -q venus.queue.manager

You will see messages telling you that the queue manager has been created, and that the default WebSphere MQ objects have been created.
To start the queue manager, type: strmqm
A message tells you when the queue manager has started.
The first time you start a queue manager on a machine, you might get one of the following warnings: Purchased processor capacity units not set (use setmqcap) or Insufficient capacity units. See Installation procedure for how to correct this.
Enable MQSC commands by typing: runmqsc
A message tells you that an MQSC session has started. MQSC has no command prompt.
Define a local queue called ORANGE.QUEUE by entering the following command:
define qlocal (orange.queue)

A message tells you when the queue has been created.
Stop MQSC by typing: end
You will see some messages, followed by the command prompt.

You have now defined:

A default queue manager called venus.queue.manager
A queue called ORANGE.QUEUE

Testing the installation

To test the queue manager and queue, use the amqsput sample program to put a message on the queue, and the amqsget sample program to get the message back from the queue:

Change into the /usr/mqm/samp/bin directory, which contains the sample programs.
Put a message on the queue using the following command:
./amqsput ORANGE.QUEUE

The following messages are displayed:
Sample amqsput0 start
target queue is ORANGE.QUEUE
Type some message text, on one or more lines, followed by a blank line. The following message is displayed:
Sample amqsput0 end

Your message is now on the queue and the command prompt is displayed again.
To get the message from the queue, use the following command:
./amqsget ORANGE.QUEUE

The sample program starts, and your message is displayed. After a pause, the sample ends and the command prompt is displayed again.

You have now successfully verified the local installation.

Installation procedure

There are different ways of installing WebSphere MQ for AIX, V5.3. You can use:

Easy installation
Custom installation
National language installation

Easy installation gives a minimal configuration on your machine, consisting of the following components:

Runtime
Base Kit
Client
Sample programs

If you want any of the other components, such as online documentation, use Custom installation.

If you want messages in a different national language from the locale selected on your machine, use National language installation.

Before you start the installation procedure, make sure that you have prepared your system as described in Preparing for installation.

Easy installation

This installation procedure uses the xinstallm program, which is available in the X11.vsm.rte optional fileset.

Log in as root.
Insert the WebSphere MQ Client CD-ROM into the CD-ROM drive.
Type: xinstallm -ez
This displays the WebSphere MQ Welcome window, followed by a second window.
Choose the CD-ROM software source.
For Which bundle of software would you like to install? choose Media-defined.
Click Install/Update to create the mqm.Client.
Choose the mqm.Client bundle and click Install/Update again.
This installs the filesets in this bundle; a work in progress window gives information as the installation proceeds.

At the end of the installation click the View log button and scroll to the bottom of the log to see the filesets that have been installed successfully.

To change your installation, or back out a failed installation, use the System Management Interface Tool (smit) as described in the following text.

Custom installation

This installation procedure uses the System Management Interface Tool (smit), enabling you to choose which components you want to install. The components and filesets are listed in WebSphere MQ components; install at least the Runtime, Base Kit, and Client components.

Log in as root.
Insert the WebSphere MQ Client CD-ROM into the CD-ROM drive.

Select the required smit window using the following sequence:

  Software Installation and Maintenance
    Install and Update Software
      Install and Update from LATEST Available Software

Alternatively you can use a fastpath command (smitty install_latest).

Click List to display the input device or directory for the software.
Select /dev/cd0 (CD-ROM Drive) and click OK.
Use the SOFTWARE to install field to obtain a list of available filesets, and select the filesets you want to install.
On AIX V4.3.3:
1. Click OK to install WebSphere MQ.
On AIX V5.1:
1. Change Preview new LICENSE agreements? to yes and click OK to view the license agreements.
2. Change ACCEPT new license agreements? to yes and click OK to accept the license agreements and install WebSphere MQ.

National language installation

Easy and Custom installation procedures install messages in the language specified by the locale selected on your machine by default. If you require messages in a different language, use the following procedure.

The process is similar to Custom installation. Install at least the Runtime, Base Kit, and Client components, in addition to the Message Catalog for your chosen language.

Log in as root.
Insert the WebSphere MQ Client CD-ROM into the CD-ROM drive.

Select the required smit window using the following sequence:

  Software Installation and Maintenance
    Install and Update Software
      Install and Update from ALL Available Software

Click List to display the input device or directory for the software.
Select /dev/cd0 (CD-ROM Drive) and clickOK.
Use the SOFTWARE to install field to obtain a list of available filesets, and select the filesets you want to install (including the message catalog).
On AIX V4.3.3:
1. Click OK to install WebSphere MQ.
On AIX V5.1:
1. Change Preview new LICENSE agreements? to yes and click OK to view the license agreements.
2. Change ACCEPT new license agreements? to yes and click OK to accept the license agreements and install WebSphere MQ.

Installing the client on the same machine as a server

To install a WebSphere MQ for AIX client on a server machine, use the WebSphere MQ Server CD-ROM. Choose the Client component on the Server CD-ROM to install the client code on the server machine, and use the installation procedure described in Installation procedure. Do not use the WebSphere MQ Clients CD-ROM.

You might install components from the WebSphere MQ Clients CD-ROM onto a machine, and subsequently want to install the WebSphere MQ Server component on the same machine. If so, first remove from the machine any components that you installed from the WebSphere MQ Clients CD-ROM. Then use the WebSphere MQ Server CD-ROM to install the Server, Client, and any other components that you need. You cannot install the server on a machine that already has other components installed from the WebSphere MQ Clients CD-ROM.

If you install a WebSphere MQ client on the same machine as an WebSphere MQ server, the client is not connected to the server automatically. Configure the communication channel (an MQI channel) between the client and the server

Verifying the installation

To verify your WebSphere MQ client installation, you need a workstation set up as a WebSphere MQ server, in addition to your client workstation. You can then use sample programs (which must be installed on the client) to test communications between the client and server.

The verification procedure assumes that:

TCP/IP is configured and initialized on both the server and the client machines.
The WebSphere MQ server product is installed on a UNIX machine; if this is not the case, some of the commands will be different (for details, refer to the WebSphere MQ Clients book).

Note:: WebSphere MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is converted automatically to uppercase unless you enclose it in single quotation marks. Make sure you type the examples exactly as shown.

Setting up the server workstation

From a shell window, use these steps to set up the server workstation:

Create a default queue manager called saturn.queue.manager by entering the following command:
crtmqm -q saturn.queue.manager

Messages tell you that the queue manager has been created, and that the default WebSphere MQ objects have been created.
To start the queue manager, type: strmqm
A message tells you when the queue manager has started.
Enable MQSC commands by typing: runmqsc
A message tells you that an MQSC session has started. MQSC has no command prompt.
Define a local queue called QUEUE1 by entering the following command:
define qlocal(queue1)

A message tells you when the queue has been created.
Define a server-connection channel by entering the following command:
define channel(channel1) chltype(svrconn) trptype(tcp) mcauser('mqm')

A message tells you when the channel has been created.
Stop MQSC by typing: end
Some messages are displayed, and the command prompt is displayed again.
Start a WebSphere MQ listener as a background task by entering the following command:
runmqlsr -t tcp &

You can use the -p parameter to specify the number of a port that the listener should listen on. If you do not specify it, the default of 1414 is used. The port number must be the same as the one that you specify when setting up the client.

You have now defined the following objects on the server:

A default queue manager called saturn.queue.manager
A local queue called QUEUE1
A server-connection channel called CHANNEL1

Setting up the client workstation

When a WebSphere MQ application is run on the WebSphere MQ client, the following information is required:

The name of the MQI channel that connects the client to the server
The communications protocol
The address of the server

You provide this information by defining a client-connection channel with the name used for the server-connection channel defined on the server. This example uses the MQSERVER environment variable to define the client-connection channel.

Before starting, use the ping command to check that your TCP/IP software is correctly configured, and that your WebSphere MQ client and server TCP/IP sessions have been initialized. From the client, enter:

ping server-address

ping n.n.n.n

where:

server-address: Is the TCP/IP host name of the server
n.n.n.n: Is the network address of the server

Press Ctrl-C to stop the ping command.

To create a client-connection channel, set the MQSERVER environment variable as follows:

export MQSERVER=CHANNEL1/TCP/'server-address(port)'

where:

CHANNEL1

Is the name of the server-connection channel already defined on the server

TCP

Is the communications protocol.

server-address

Is the TCP/IP host name of the server.

port

is optional and is the TCP/IP port number the server is listening on. If you do not give a port number, WebSphere MQ uses:

The one specified in the QM.INI file. If no value is specified in the QM.INI file, WebSphere MQ uses:
The port number identified in the TCP/IP services file for the service name WebSphere MQ. If this entry in the services file does not exist, a default value of 1414 is used.

The client and server listener program must use the same port number.

Testing communication between the workstations

On the WebSphere MQ client workstation, use the amqsputc sample program to put a message on the queue at the server workstation, and the amqsgetc sample program to get the message from the queue back to the client:

Change into the /usr/mqm/samp/bin directory, which contains the sample programs.
Put a message on the queue at the server using the following command:
./amqsputc QUEUE1 saturn.queue.manager

This displays the following messages:
Sample amqsput0 start
target queue is QUEUE1
Type some message text on one or more lines, followed by a blank line. This displays the following message:
Sample amqsput0 end

Your message is now on the queue and the command prompt is displayed again.
To get the message from the queue at the server, enter the following command:
./amqsgetc QUEUE1 saturn.queue.manager

The sample program starts and your message is displayed. After a pause, the sample ends and the command prompt is displayed again.

You have now successfully verified the client installation.

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"

1. 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.

2. 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.

3. In the section "dspmqcap", note that the command displays the number of
   processors for which you have purchased capacity units.

4. 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"

1. 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.

2. 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,  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"

1. 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.

2. 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:

   - SupportPac MA0C: MQSeries Publish/Subscribe
     (http://www-4.ibm.com/software/integration/support/supportpacs/individual/ma0c.html)

   - 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,  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.

:1: not found

Change History

5th July 2002

amqmcert option added.
Add information on when SSLCRLNameList, SSLKeyRepository and SSLCryptoHardware values become effective.
14th August 2002

Correct AIX PTF and add other recommended numbers.

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

AIX is a trademark of the IBM Corporation in the United States, other countries, or both.

WebSphere MQ 5.3 for AIX Installation

Contents

Links

Overview

WebSphere MQ for AIX V5.3 Electronic Software Download installation

WebSphere MQ V5.3 System Administration Guide

WebSphere MQ V5.3 Programmable Command Formats and Administration Interface

WebSphere MQ V5.3 Intercommunication

WebSphere MQ V5.3 Script (MQSC) command reference

WebSphere MQ V5.3 Security

WebSphere MQ V5.3 Application Programming Guide

WebSphere MQ V5.3 Messages

WebSphere MQ classes for Java and Java Message Service

Information not contained in the publications

WebSphere MQ V5.3 Clients

Electronic Software Download installation

Secure Sockets Layer (SSL) on WebSphere MQ clients

SSL channels

LDAP CRL (certificate revocation list) definitions on WebSphere MQ clients

WebSphere MQ V5.3 System Administration Guide

amqmcert

Change History

WebSphere MQ 5.3 for AIX
Installation