| IBM WebSphere MQ for iSeries, V5.3 README
Welcome to WebSphere MQ for iSeries, Version 5.3
This README file applies to WebSphere MQ books dated 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/support/entry/portal/Software/WebSphere/WebSphere_MQ
The SupportPac Web page is at:
http://www.ibm.com/support/docview.wss?uid=swg27007205
For current information on known problems and available fixes, see
the Support page of the WebSphere MQ Web site at:
http://www.ibm.com/support/entry/portal/Software/WebSphere/WebSphere_MQ
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/
The Change History is located at the bottom of the page.
WebSphere MQ for iSeries V5.3 Electronic Software Download installation
Introduction
These instructions apply to installing WebSphere MQ for iSeries Version 5.3
from an installation image downloaded from IBM. Use it with the WebSphere MQ
for iSeries 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'.
Two installation images are provided as zip files, a Server image containing
the Base and Java™ licensed programs and a Client image for the Java program
only. The Server image contains nineteen compressed iSeries save files (SAVF),
while the Client image contains only the 2 Java save files. The save files in
the Server image are:
MQ53BASE - WebSphere MQ Server base program objects
MQ53SAMP - WebSphere MQ Server Samples
MQ53JBASE - WebSphere MQ Java
MQ53JSAMP - WebSphere MQ Java Samples
plus additional language files
MQ53EN09 - WebSphere MQ Server Belgian English (2909) language objects
MQ53EN24 - WebSphere MQ Server English US (2924) language objects
MQ53FR28 - WebSphere MQ Server French (2928) language objects
MQ53SP31 - WebSphere MQ Server Spanish (2931) language objects
MQ53IT32 - WebSphere MQ Server Italian (2932) language objects
MQ53EN38 - WebSphere MQ Server English US uppercase DBCS (2938) language objects
MQ53FR40 - WebSphere MQ Server French MNCS (2940) language objects
MQ53IT42 - WebSphere MQ Server Italian MNCS (2942) language objects
MQ53EN50 - WebSphere MQ Server English US uppercase (2950) language objects
MQ53JA62 - WebSphere MQ Server Japanese (2962) language objects
MQ53FR66 - WebSphere MQ Server Belgian French MNCS (2966) language objects
MQ53FR81 - WebSphere MQ Server Canadian French MNCS (2981) language objects
MQ53EN84 - WebSphere MQ Server English US DBCS (2984) language objects
MQ53KO86 - WebSphere MQ Server Korean (2986) language objects
MQ53CH89 - WebSphere MQ Server Simplified Chinese (2989) language objects
The client image contains the Java base (MQ53JBASE) and Java samples
(MQ53JSAMP) only.
Installation Steps
1. Download one of the installation images and unzip it to a temporary
directory. The Server zip is called WMQiSeries53.zip and the Client zip
is called WMQiSeries53Java.zip.
2. On iSeries, create a library containing sufficient empty save files to
hold the uploaded files. The Server requires 5 files to include the Base
and Java licensed programs, the Client only requires the 2 files for Java.
To create the library and save files use the commands:
CRTLIB LIB(MQ53PROD)
CRTSAVF MQ53PROD/MQ53BASE
CRTSAVF MQ53PROD/MQ53SAMP
CRTSAVF MQ53PROD/MQ53JBASE
CRTSAVF MQ53PROD/MQ53JSAMP
CRTSAVF MQ53PROD/MQ53LANG
Additional save files may be created if more than one language is required
for the Base program.
3. Start an ftp session to your iSeries machine and upload the required save
files with the commands:
ftp (your_iSeries)
bin
put MQ53BASE MQ53PROD/MQ53BASE
put MQ53SAMP MQ53PROD/MQ53SAMP
put MQ53JBASE MQ53PROD/MQ53JBASE
put MQ53JSAMP MQ53PROD/MQ53JSAMP
put MQ53xxxx MQ53PROD/MQ53LANG
where MQ53xxxx represents one of the optional language objects above.
Note that the Client requires only the 2 Java save files.
4. To prepare for installation of WebSphere MQ for iSeries, sign on to your
iSeries machine and follow the instructions in the Quick Beginnings book.
5. Once preparation is complete you are ready to install the licensed
program(s). Enter the RSTLICPGM commands, specifying the install device
as *SAVF and naming the save file containing the option you wish to install.
For example:
/* WebSphere MQ Server program objects */
RSTLICPGM LICPGM(5724B41) DEV(*SAVF) SAVF(MQ53PROD/MQ53BASE) +
RSTOBJ(*PGM) OPTION(*BASE) OUTPUT(*PRINT)
/* WebSphere MQ Server US English commands */
RSTLICPGM LICPGM(5724B41) DEV(*SAVF) SAVF(MQ53PROD/MQ53LANG) +
RSTOBJ(*LNG) LNG(2924) OUTPUT(*PRINT)
/* WebSphere MQ Server Samples */
RSTLICPGM LICPGM(5724B41) DEV(*SAVF) SAVF(MQ53PROD/MQ53SAMP) +
OPTION(1) OUTPUT(*PRINT)
/* WebSphere MQ Java */
RSTLICPGM LICPGM(5639C34) DEV(*SAVF) SAVF(MQ53PROD/MQ53JBASE) +
OPTION(*BASE) OUTPUT(*PRINT)
/* WebSphere MQ Java Samples */
RSTLICPGM LICPGM(5639C34) DEV(*SAVF) SAVF(MQ53PROD/MQ53JSAMP) +
OPTION(1) OUTPUT(*PRINT)
WebSphere MQ for iSeries V5.3 Quick Beginnings "What's new in WebSphere MQ for iSeries, Version 5 Release 3"
Support for SSL on iSeries is provided by the OS400 operating system,
it is not shipped as part of WebSphere MQ.
Chapter 1, "Planning to install the WebSphere MQ for iSeries server"
Add the following notes:
We recommend that Korean DBCS users configure their terminal emulators
to use sessions capable of displaying 132 columns (for example, 27x132).
Otherwise, you might find that EDTF incorrectly displays DBCS characters
in WebSphere MQ error log messages that extend beyond 80 columns
in 24x80 capable sessions.
In the section "Software requirements" add
It is recommended that the latest OS/400 cumulative packages and
PTF's are installed before installing WebSphere MQ for iSeries 5.3
OS/400 V5R1M0
-------------
Latest Cum Package as of 18th September 2002 : C2134510
PTFs:
MF29056
MF29379
MF27789
MF27531
MF27109
SI03589
SI03029
OS/400 V5R2M0
-------------
Latest Cum Package as of 18th September 2002 : C2211520
PTFs:
MF29332
MF29193
SI05173
SI05750
Chapter 2, "Installing and migrating to WebSphere MQ for iSeries"
In the section "Before installation, subsection "Setting system values",
add:
QSHRMEMCTL
Set the system value to 1 before you install WebSphere MQ for iSeries.
This allows the users to use the shared or mapped memory that has write
capability.
In the section "Installation procedure", subsection "Installation of
translated versions", to the end of the paragraph following the RSTLICPMG
sample add:
"If this QSYS29nn library does not exist, it will be created by the RSTLICPGM
command."
In Notes 2 following this paragraph change the last sentence to read
"Alternatively, install the product in one of the supplied languages, using
parameters RSTOBJ(*LNG) LNG(language ID), and then add the corresponding
QSYS29nn library into the System Library List (CHGSYSLIBL)."
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 behavior 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 for iSeries System Administration Guide Version 5 Release 3
"What's new for this release"
In the section "Modifications to existing commands" add
Escape messages:
-----------------
In v5.3, when MQ commands fail they will issue a CPF0001 escape message.
This will allow CL programs to monitor MQ command failures using the standard
MONMSG CL command. You may wish to modify your CL programs to check for MQ
command failures using MONMSG if you do not already do so.
Add a new section
Channel Process Pooling
-----------------------
Channel process pooling is a new feature in WebSphere MQ for iSeries that
changes the way in which threaded TCP/IP channels are run. In previous
releases of MQSeries, threaded TCP/IP channels run either in the channel
initiator job (RUNMQCHI) or within the channel listener job which starts
them (RUNMQLSR).
Running large numbers of channels as threads in a single job is undesirable
as the number of connections achievable is limited to the resources available
to a single job.
One solution provided by WebSphere MQ for iSeries to achieve a large number of
connections is the non-threaded listener (AMQCLMAA) which starts a new
responder job (AMQCRSTA) for each inbound TCP/IP channel. The disadvantage of
using a non-threaded TCP/IP listener is that it is not as fast at starting a
new AMQCRSTA job as it is at starting a thread within a RUNMQLSR job,
consequently connection times for a non-threaded listener are generally slower
than those for a threaded listener.
A more scalable solution is to have the channel initiators and the listeners
hand the channel over to a pool of processes (AMQRMPPA).
The default channel listener type for new queue managers in WebSphere MQ for
iSeries 5.3 is the threaded listener (RUNMQLSR) to provide the scalability
benefits of process pooling.
Queue managers migrated from previous releases of MQSeries that used
non-threaded listeners will continue to use non-threaded listeners.
The type of listener that is started for a queue manager using the STRMQMLSR
command can be altered by changing the "ThreadedListener" stanza in the queue
managers qm.ini file as detailed in "Chapter 9 - Configuring WebSphere MQ"
in the System Administration Guide for iSeries.
Chapter 5, "Protecting WebSphere MQ objects"
In the section "WebSphere MQ authorities" there are some omissions in the
'Group 2 - Other Commands'
The following table summarizes all of the Group 2 commands
Work commands
=============
Command QMgr authorisation Other authorisation
-------- ------------------ ---------------------------
WRKMQM CONNECT,ADMDSP. - (Display only)
WRKMQMAUT** CONNECT,ADMDSP. -
WRKMQMAUTD** CONNECT,ADMDSP. -
WRKMQMAUTI** CONNECT,ADMDSP. -
WRKMQMCHL CONNECT,ADMDSP. - (Display only)
WRKMQMCHST CONNECT,ADMDSP. -
WRKMQMCL CONNECT,ADMDSP. -
WRKMQMCLQ CONNECT,ADMDSP. -
WRKMQMCLQM CONNECT,ADMDSP. -
WRKMQMLSR** CONNECT,ADMDSP. -
WRKMQMMSG CONNECT,ADMDSP Q BROWSE
WRKMQMNL CONNECT,ADMDSP NL + ADM*** FOR COMMAND REQUIRED
WRKMQMPRC CONNECT,ADMDSP PRC + ADM*** FOR COMMAND REQUIRED
WRKMQMQ CONNECT,ADMDSP Q + ADM*** FOR COMMAND REQUIRED
WRKMQMQSTS** CONNECT,ADMDSP. -
Display commands
================
Command QMgr authorization Other authorization
-------- ------------------ ---------------------------
DSPMQM CONNECT,ADMDSP. -
DSPMQMAUT CONNECT,ADMDSP. -
DSPMQMAUTI CONNECT,ADMDSP. -
DSPMQMCAP CONNECT,ADMDSP. -
DPSMQMCSVR CONNECT,ADMDSP. -
DSPMQMNL CONNECT,ADMDSP NL ADMDSP
DSPMQMOBJN CONNECT,ADMDSP. -
DSPMQMPRC CONNECT,ADMDSP PRC ADMDSP
DSPMQMQ CONNECT,ADMDSP Q ADMDSP
DSPMQMCHL CONNECT,ADMDSP. -
Other Channel commands
======================
Command QMgr authorization Other authorization
-------- ------------------ ---------------------------
ENDMQMCHL CONNECT Q ALLMQI (On channel XMITQ)
ENDMQMLSR - -
PNGMQMCHL CONNECT,INQ. -
RSTMQMCHL CONNECT. -
STRMQMCHL CONNECT Q ALLMQI (On channel XMITQ)
STRMQMCHLI CONNECT,INQ Q ALLMQI (On initQ for channel XMITQ)
STRMQMLSR - -
Other commands:
=============
Command QMgr authorization Other authorization
-------- ------------------ ---------------------------
CCTMQM - -
CHGMQM CONNECT,ADMCHG. -
CHGMQMNL CONNECT NL ADMCHG.
CHGMQMPRC CONNECT PRC ADMCHG.
CHGMQMQ CONNECT Q ADMCHG.
CLRMQMQ CONNECT Q ADMCLR.
CPYMQMNL CONNECT,ADMCRT. -
CPYMQMPRC CONNECT,ADMCRT. -
CPYMQMQ CONNECT,ADMCRT. -
CRTMQMNL CONNECT,ADMCRT NL ADMDSP (DEFAULT).
CRTMQMPRC CONNECT,ADMCRT PRC ADMDSP (DEFAULT).
CRTMQMQ CONNECT,ADMCRT Q ADMDSP (DEFAULT).
CVTMQMDTA - -
DLTMQMNL CONNECT NL ADMDLT.
DLTMQMPRC CONNECT PRC ADMDLT.
DLTMQMQ CONNECT Q ADMDLT.
DSCMQM - -
RFRMQMAUT CONNECT. -
RFRMQMCL CONNECT. -
RSMMQMCLQM CONNECT. -
RSTMQMCL CONNECT. -
SPDMQMCLQM CONNECT. -
Chapter 8, "Analyzing problems"
In the section "Obtaining diagnostic information" the description of
TRCMQM *END is correct. However the online help text for SET *END is:
*END
This option is identical in function to *OFF. It is
provided for compatibility with earlier releases of
MQ.
This help text should be ignored and instead, the following should be used as
the help for this parameter:
*END
This option ends tracing on all queue managers.
WebSphere MQ V5.3 SCRIPT (MQSC) Command Reference
Chapter 2, "The MQSC commands"
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 4, "Definitions of Programmable Command Formats"
At the start of the "Change, Copy, and Create Authentication Information
Object" section add:
Authentication objects contain the definitions required to perform Certificate
Revocation List (CRL) checking using LDAP servers, except on OS/400 where these
are defined by the Digital Certificate Manager for each Certification
Authority. Note that LDAP CRL functionality is not supported on Linux for
zSeries channels.
In the "Change Queue Manager" section, 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 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 Programmable Command Formats and Administration Interface
Chapter 4, "Definitions of Programmable Command Formats"
At the start of the "Change, Copy, and Create Authentication Information
Object" section add:
Authentication objects contain the definitions required to perform Certificate
Revocation List (CRL) checking using LDAP servers, except on OS/400 where these
are defined by the Digital Certificate Manager for each Certification
Authority. Note that LDAP CRL functionality is not supported on Linux for
zSeries channels.
In the "Change Queue Manager" section, 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 Application Programming Guide
Appendix A, "Language compilers and assemblers"
in Table 60. Language compilers and assemblers for WebSphere MQ for iSeries
the C++ compiler supported is IBM ILE C++ for iSeries (program 5722-WDS)
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.
|
Change History
15th January 2003
