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