WebSphere MQ for Windows, V5.3 README
Welcome to WebSphere MQ for Windows, Version 5.3.
This README file applies to WebSphere MQ books dated October 2002 and CSD01 level of the V5.3 product shipped on or after October 2002.
This README file contains information that was not available in time for our publications. In addition to this file, README.TXT, you can find more information on the WebSphere MQ Web site:
http://www.ibm.com/software/products/en/ibm-mq
The SupportPac™ Web page is here:
http://www.ibm.com/support/docview.wss?rs=977&uid=swg27007205
For current information on known problems and available fixes, see the Support page of the WebSphere MQ Web site here:
http://www.ibm.com/support/docview.wss?rs=171&uid=swg27006037
Web documentation updates
The latest updates to the web-based WebSphere MQ documentation are now available from the WebSphere MQ Web site here:
http://www.ibm.com/software/integration/wmq/library/
The Change History is located at the bottom of the page.
WebSphere MQ for Windows V5.3 Quick Beginnings
Using MQSC commands to alter WebSphere MQ objects while the WebSphere MQ Explorer or WebSphere MQ Services are running can cause unpredictable results. You should close the WebSphere MQ Explorer and WebSphere MQ Services while the MQSC commands are used, and re-start them afterwards if required.
Chapter 1, "Planning to install the WebSphere MQ for Windows Server"
Prerequisite server software
In section "Java™" add
IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0
Chapter 3, "Installing WebSphere MQ"
Add a note:
When installing on Windows XP using a Remote Desktop Connection, you will need to logoff, then re-logon to pick up the changes made to your environment by the installation process.
In the section "Installing WebSphere MQ - step-by-step" step 4 of Installing WebSphere MQ, "Software Prerequisites" note that selecting the Supported Java Runtime Environment V1.3 or later now allows you to install the IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0 from the
CD.
Installing on Windows 2000 using Terminal Services
It is possible to get errors when installing WebSphere MQ on this configuration. Microsoft KB article 255582 explains:
"When you are installing a Windows Installer-based setup program from a Windows 2000 Server Terminal Services session, you may receive one of the following error messages (where myapp.msi is the name of the .msi file that you are running).
On a system running the base version of Windows 2000, you will receive error
2755:
Internal Error 2755. 3 <Path>\myapp.msi.
On a system running Windows 2000 Service Pack 1, you will receive error 1305:
Error reading from file: <Path>\myapp.msi. Verify that the file exists and that you can access it.
CAUSE
These errors occur if you're running from a Terminal Server session and the path to the installation files is a mapped drive. The Windows Installer service is running in a different session than the user and therefore has different drive mappings. The errors occur because the .msi files that are needed cannot be found.
RESOLUTION
To work around this problem, use the full universal naming convention (UNC) path on the command line or run the installation from the Terminal Server console."
On WebSphere MQ the .msi file name is either "IBM WebSphere MQ.msi" or "IBM WebSphere MQ Extended Transactional Client.msi". The UNC is of the form "\\<ServerName>\<ShareName>\setup.exe" where <ServerName> and <ShareName> are the appropriate values for your machine setup.
Please read the following notes before attempting to install on a Windows 2003 Standard or Enterprise edition system
a) The animation at the start of the install may not launch, but all subsequent parts of the install proceed correctly.
b) WebSphere MQ Fix Pack 4 ( CSD04 - PTF U200190 ) is a prerequisite for Windows 2003 support.
c) The existing documentation in the 'Quick Beginnings' is not correct for Windows Server 2003. The Windows 2003 'delegation Wizard' does not support Read GroupMembershipSAM. The option is, however, supported by Windows 2003 Server. WebSphere MQ requires this permission to be set - therefore the permission must be set manually to enable WebSphere MQ to function.
Please follow these instructions to set Read GroupMembershipSAM:
- Open Active Directory Users & Computers
- Put Active Directory Users & Computers in Advanced Feature Mode
- Find the domain name in the left panel, right click it and select Properties.
- Select the Security Tab.
- Select Advanced then click Add, type in 'domain mqm' and click OK.
- A new dialog will be displayed. Select the properties Tab. In the 'Apply onto' box change the view to 'User objects'.
- Select the allow checkbox for 'Read Group Membership' and 'Read Group MembershipSAM'.
- Click 'OK' to close all windows (Should be 3 times).
The 'domain mqm' group now has the rights to enumerate the group membership for all users in that domain.
Chapter 4: "Other methods of Installing WebSphere MQ"
In table 12. "Properties in the Services Stanza", the value only domain to property USERTYPE is added, so replace the USERTYPE entry with:
| Property | Values | Description |
| USERTYPE | local|domain|onlydomain | The type of user account to use: |
|
| local.
Creates a local user account. |
|
| domain.
Creates a local user account.
If this does not have the required
security authorities, it uses the
domain user account specified by
DOMAINNAME, USERNAME, and PASSWORD. |
|
| onlydomain.
Does not create a local user
account, but immediately uses the
domain user account specified by
DOMAINNAME, USERNAME and PASSWORD.
If any of these three properties
are missing, a USERTYPE of local is
assumed. |
The properties DOMAINNAME, USERNAME, and PASSWORD are required if USERTYPE is set to onlydomain.
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 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 Application Programming Guide
Appendix A, "Language compilers and assemblers"
replace the existing Table 66. Language compilers and assemblers for WebSphere MQ for Windows by
| Language | Compiler/Assembler |
| Basic | Microsoft Visual Basic for Windows, V6.0 |
| C++ | Microsoft Visual C++ V6.0 |
| C | Microsoft Visual C++ V6.0 |
| COBOL | VisualAge COBOL Enterprise, V2.2
Micro Focus Net Express, V3.0 or V3.1 |
| PL/I | IBM VisualAge for PL/I for Windows, V2.1 |
Note that the IBM VisualAge for C++ for Windows compilers are NOT supported.
replace the existing Table 69. Language compilers and assemblers for Windows 98 clients by
| Language | Compiler/Assembler |
| C++ | Microsoft Visual C++ V6.0 |
| C | Microsoft Visual C++ V6.0 |
| COBOL | Micro Focus Net Express, V3.0 or V3 |
WebSphere MQ V5.3 Using C++
Appendix A, "Compiling and linking"
The section "Compiling VisualAge C++ sample programs for Windows" should be deleted.
WebSphere MQ V5.3 Security
Chapter 13, "Working with the Secure Sockets Layer (SSL) on Windows systems"
To add personal certificates to a Queue Manager store on Windows NT 4.0 the WebSphere MQ Explorer or WebSphere MQ Services must be used. Amqmcert.exe must be used on Windows NT 4.0 to add certificates to a client store.
On Windows 2000 and Windows XP you can use amqmcert.exe or the WebSphere MQ Explorer or WebSphere MQ Services to add personal certificates to a Queue Manager store.
In the section "Creating a self-signed personal certificate" add the following examples on using the makecert certificate creation tool.
Creating Test Certificates Using MakeCert
Note: these instructions were tested using Makecert.exe version
5.131.3617.0.
Creating and Installing a Certificate Authority Certificate
You should create a separate certificate for the a root certificate. This certificate will sign the SSL Certificate. The CA certificate in the example has an id named "WebSphereCA". You can name it whatever you like.
- makecert -pe -n CN=WebSphereCA -ss MY -sr CurrentUser -a sha1
-sky signature -r WebSphereCA.cer
- run or double click on WebSphereCA.cer to install and trust the CA.
- On Dialog, click Install Certificate.
- Click the Next button.
- Click the "Place all certificates in the following Store" radio button and then click the Browse Button.
- Check the "show Physical Stores" checkbox.
- Expand the "Trusted Root Certification Authorities", select "Local Computer" and click the OK button.
- Click on the Next button and then the Finish button.
Creating the SSL Server Certificate
This example uses WebSphereMQ as the name of the SSL Certificate.
makecert -pe -n CN=WebSphereMQ -ss MY -sr CurrentUser -a sha1 -sky exchange
-eku 1.3.6.1.5.5.7.3.1 -in WebSphereCA -is MY -ir CurrentUser
-sp "Microsoft RSA SChannel Cryptographic Provider"
-sy 12 WebSphereMQ.cer
(Note: ensure the -sp name is exactly as specified in the example.)
Importing the SSL Certificates
The CA and Personal Certificates (issued to WebSphere in this example) can then be imported into the queue manager or client certificate stores using the WebSphere MQ Explorer, WebSphere MQ Services or amqmcert command line utility.
In the section "Requesting a personal certificate" add:
Strong Private Key Protection
When importing a certificate into the Personal Certificate store for the Current User, an option to "Enable strong private key protection" is offered. If this option is selected a dialogue is started where the level of security can be chosen. The dialogue offers a choice of High or Medium.
Both state that usage of this item will invoke a request for a user response. If either of these security levels are selected IBM WebSphere MQ will request a user response when the certificate is imported into the QM store. Any further user request will not then be made when WebSphere MQ "uses" this certificate: for example when channels are established.
Accessibility of the IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0
Java Web Start
The IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0 includes Java Web Start. This is a reference implementation of the Java Network Launching Protocol (JNLP). Java Web Start is an application deployment tool that is not required for application development, and its use is entirely optional.
The Java Web Start Application Manager is a client-side tool used to configure and administer both Java Web Start and the applications that have been deployed with it. The current version of this tool has some accessibility limitations (described in the IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0 User Guide) that affect its use with assistive technologies.
The Java User Guide describes keyboard alternatives to some functions of the Application Manager. In addition there are Open Source implementations of JNLP that support command line operation. More details are available from the SourceForge.net Web site (http://sourceforge.net/). Note, however, that such alternatives are not supported by IBM and may not provide all of the features found in Java Web Start.
Swing list box
The Swing list box allows multiple items to be selected using the mouse. Selections can be either by contiguous items (the shift key is held down while clicking the mouse button) or by discontiguous items (the control key is held down while clicking the mouse button). Using the keyboard, however, only
contiguous items can be selected.
The inability to perform discontiguous selection might affect users who cannot operate a mouse or other pointing device.
For applications that need to select more than one item, this alternative is recommended. Use a dialog containing two list boxes with arrow buttons between the boxes controlling the movement of list items from a source list on the left to a selected list on the right. This use of two list boxes is a common
feature in Windows applications and means that the user does not have to make discontiguous selections from a single list box.
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
Last Updated: 7 October 2005
|