Embed Size (px)
Citation preview
Page 1 of 74
WebSphere MQ V5.3, V6 and V7 as JMS Provider for WebSphere
Application Server V5, V6.0, V6.1 and V7
IBM Techdoc: 7017881
http://www.ibm.com/support/docview.wss?uid=swg27017881
Date last updated: 19-Apr-2011
Angel Rivera – [email protected]
IBM WebSphere MQ Support +++ Objective +++ The objective of this techdoc is to provide a quick reference for the supported environments, configuration differences, and basic information on problem determination (PD) tasks when using WebSphere MQ Versions 5.3, 6 and 7, as JMS Provider for WebSphere Application Server Versions 5, 6.0, 6.1 and 7. The main target audience for this document is the support teams that provide technical assistance for customers who work with several versions of MQ and WebSphere Application Server. This document has the following chapters: Chapter 1: Supported versions of MQ and WebSphere Application Server Chapter 2: Configuration differences Chapter 3: Maintenance of the MQ JMS client files Chapter 4: Using Bindings transport type and local native MQ libraries Chapter 5: Debugging and Problem Determination Chapter 6: Miscellaneous questions Appendix A: Listing of all web pages mentioned in this techdoc +++ Acknowledgements +++ I want to thank Leonard Ponich, Justin Fries, Simon Gormley and the WebSphere MQ Java Support and Development teams for their feedback regarding most of the topics in this document.
Page 2 of 74
+++ Related articles +++ The following techdoc provides a quick summary of the relevant menu items from the WebSphere Application Server Administrative Console that are relevant for WebSphere MQ users: http://www.ibm.com/support/docview.wss?uid=swg27018556 Quick Guide of the Administrative Console from WebSphere Application Server for WebSphere MQ users The following section of the WAS V7 Information Center provides a very good summary of the changes between WAS V6 and V7 regarding the use of MQ as a JMS provider: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzao.doc/mi21350_.htm Integration of WebSphere MQ classes for JMS with WebSphere Application Server The following WebSphere Support Technical Exchange focuses on how to specify WebSphere MQ V7 as the JMS Provider for WebSphere Application Server V7. New features from WebSphere MQ V7 are discussed, as well as the different transport modes (bindings, client). http://www.ibm.com/support/docview.wss?uid=swg27016505 Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7 http://www.ibm.com/support/docview.wss?uid=swg27017733 Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V6 The following techdocs provide more details on using a basic Message Driven Ben (MDB) in WebSphere Application Server with WebSphere MQ as the JMS Provider. They provide tutorials that the reader can use to experiment and to become familiar with MQ as a JMS Provider. http://www.ibm.com/support/docview.wss?uid=swg27016507 Developing and testing an MDB using RAD 7.5, WebSphere Application Server V7 and MQ V7 as JMS Provider http://www.ibm.com/support/docview.wss?uid=swg27016581 Using an MDB with JMS message selectors with WebSphere MQ V7 and WebSphere Application Server V7 Includes sample code to create a message property "color" SampleJMSMsgProperty.java http://www.ibm.com/support/docview.wss?uid=swg27016582
Page 3 of 74
Using an MDB that always rolls back a message to test the handling of poison messages (WebSphere MQ V7, WebSphere Application Server V7)
Page 4 of 74
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Chapter 1: Supported versions of MQ and WebSphere Application Server ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ See the following IBM Support web page for the individual End of Support (EOS) dates for WebSphere MQ and WebSphere Application Server: http://www.ibm.com/software/websphere/support/lifecycle/index.html Statement of Support for WebSphere MQ V5.3 became out of support in Sep-2007. The latest CSD is 14 (Fix Pack: 5.3.0.14) - Customer needs Extended Support contract to engage IBM WebSphere MQ Support. V6 is supported (EOS is 30-Sep-2011) V7 is supported (no EOS date) Statement of Support for WebSphere Application Server V5.0 became out of support on 30 Sep 2006 V5.1 became out of support on 26 Sep 2008 V6.0 became out of support on 30 Sep 2010 V6.1 is supported (no End of Support date) V7.0 is supported (no End of Support date) Special cases for valid support for MQ 5.3 There are 3 special cases when the IBM WebSphere MQ Support team can provide support for problems related to MQ 5.3: 1) If the customer has an Extended Support contract that is valid (not expired) for MQ 5.3 or for WebSphere Application Server 5.x. 2) WebSphere Application Server 6.0 ships MQ 5.3 JMS Client jar files. Because this MQ 5.3 code is bundled with a supported product, then MQ Support can assist customers when encountering problems with this combination. 3) If MQ 5.3 is bundled with a product that still has a valid support. For example: ITIM – IBM Tivoli Identity Manager ships WebSphere Application Server 5 which includes MQ 5.3. Important Notes:
Page 5 of 74
a) The customer should report problems regarding the JMS client to the support team of the product that does the high level bundling. In the above example, the ITIM team should be contacted first; this team has to ensure that the customer is entitled to the high level of bundling. Then the high level bundling team (in this example: ITIM) should contact the IBM WebSphere Application Server Support team who in turn can request the technical assistance of the IBM MQ Support team. b) The support is ONLY when the customer is using MQ as the Embedded Messaging Component for WebSphere Application Server 5. In this case, the queue managers have a very distinct naming convention:
WAS_hostname_server1 For example: WAS_aemtux1_server1 If the name of the queue manager does NOT follow the above convention, then it means that the customer is NOT using the shipped MQ code as the embedded messaging component for WebSphere Application Server 5 and MQ is being used in standalone which is in violation of the terms of the license, and thus, those queue managers are NOT supported by IBM Support.
Page 6 of 74
Supported shipped combinations (WebSphere Application Server install) WebSphere Application Server 6.0 with shipped MQ 5.3 JMS Client jar files WebSphere Application Server 6.1 with shipped MQ 6 JMS Client jar files WebSphere Application Server 7.0 with shipped MQ 7 Resource Adapter See the following technote for the mapping of the MQ versions shipped with the different versions of WebSphere Application Server. http://www.ibm.com/support/docview.wss?uid=swg21248089 Which version of MQ is shipped with WebSphere Application Server WWeebbSSpphheerree AApppplliiccaattiioonn SSeerrvveerr VV77..00
WebSphere Application Server Version 7 ships with the WebSphere MQ Version 7 Resource Adapter. The table below shows the level of the Resource Adapter that is included with specific releases of the application server.
WebSphere
Application Sever Version
WebSphere MQ JCA resource
adapter Version
Implementation Version, shown in WMSG1703I
log entry during server startup
7.0.0.0
7.0.0.0
7.0.0.0-k700-L080820
7.0.0.1
7.0.0.1
7.0.0.0-k700-L081015.2
7.0.0.3
7.0.0.2
7.0.0.2-k700-002-090216
7.0.0.5
7.0.1.0
7.0.1.0-k000-L090615.1
7.0.0.6
7.0.1.0
7.0.1.0-k000-L090706
7.0.0.7
7.0.1.1
7.0.1.1-k701-101-091001
7.0.0.9
7.0.1.1
7.0.1.1-k701-101-091116
7.0.0.11
7.0.1.2
7.0.1.2-k701-102-100504
7.0.0.13
7.0.1.3
7.0.1.3-k701-103-100812
Page 7 of 74
WebSphere Application Server V6.0 and V6.1
WebSphere Application Server Versions 6.0 and 6.1 install the
WebSphere MQ files com.ibm.mq.jar and com.ibm.mqjms.jar
into the following directory:
install_root\lib\WMQ\java\lib
The tables below show the levels of WebSphere MQ that these JAR
files are taken from.
Specific Version of
WebSphere Application
Server V6.0
Version of WebSphere MQ
6.0 - 6.0.1.0 5.3 + CSD08
6.0.2.27 and later 5.3 + CSD14
Specific Version of
WebSphere Application
Server V6.1
Version of WebSphere MQ
6.1.0.0 - 6.1.0.8 6.0.1.1
6.1.0.9 - 6.1.0.14 6.0.2.1
6.1.0.15 - 6.1.0.18 6.0.2.2
6.1.0.19 - 6.1.0.28 6.0.2.4
6.1.0.29 6.0.2.8 + IC63701
6.1.0.31 and later 6.0.2.8 + IC63701 + IZ72486
Page 8 of 74
Supported combinations (standalone MQ install and WebSphere Application Server install) Note: Clarification on the terms used in the technotes mentioned in this section. 1) The term "WebSphere MQ messaging provider" refers to MQ files that are shipped with WebSphere Application Server: - WebSphere Application Server V5 and V6: the MQ jar files provided with WebSphere Application Server which are located in:
${WAS_INSTALL_ROOT}/lib/WMQ/java/lib - WebSphere Application Server V7: the MQ Resource Adapter (RA) that is provided in: ${WAS_INSTALL_ROOT} 2) The term "WebSphere MQ Client" refers to the standalone installation of the MQ JMS Client, that is, the code installed in:
AIX: /usr/mqm Unix: /opt/mqm
The installed code needs to be the MQ Client (MQ SupportPacs MQC6, MQC7) or the MQ Client+Server. http://www.ibm.com/support/docview.wss?uid=swg24019253 MQC7: WebSphere MQ V7.0 Clients http://www.ibm.com/support/docview.wss?uid=swg24009961 MQC6: WebSphere MQ V6.0 Clients
Page 9 of 74
WebSphere Application Server 6.0 and 6.1: Consult the following technotes: http://www.ibm.com/support/docview.wss?uid=swg21307212 Information about using WebSphere MQ as the JMS Provider for WebSphere Application Server 6.0 http://www.ibm.com/support/docview.wss?uid=swg21307203 Information about using WebSphere MQ as the JMS Provider for WebSphere Application Server 6.1 Summary: - Minimum level of the target MQ 6 Queue Manager should be: 6.0.1.1 - WebSphere Application Server 6.0: Needs APAR PK67271, which is included with 6.0.2.29. - WebSphere Application Server 6.1: needs to be at 6.1.0.17 or later to interact with a target MQ 7 Queue Manager. - MQ Resource Adapter is NOT supported. - WebSphere Application Server environment variable MQ_INSTALL_ROOT needs to be modified for Bindings transport type (This is explained in Chapter 4).
Page 10 of 74
WebSphere Application Server 7: The MQ RA V7 is supported under WebSphere Application Server V7. Consult the following technote: http://www.ibm.com/support/docview.wss?uid=swg21316899 Information about using the WebSphere MQ messaging provider for WebSphere Application Server Version 7.0 Summary: - Minimum level of a target MQ 6 Queue Manager should be: 6.0.2.5 - MQ Resource Adapter is used for both Bindings and Client transport type. - WebSphere Application Server environment variable MQ_INSTALL_ROOT is NOT needed in Unix + In Windows it is needed only when the MQ directory is not the default Consult also the following web page from the WebSphere Application Server V7 Information Center: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/tmj_instm.html Installing WebSphere MQ to interoperate with WebSphere Application Server Note for AIX: - Run the dltmqlnk WebSphere MQ control command. If your application server is 64 bit, you must run the dltmqlnk WebSphere MQ control command as root before applications are able to connect to a queue manager using a BINDINGS transport type. The command must be rerun each time a WebSphere MQ fix pack is installed. For more information, see the "Implications of a 64-bit queue manager" section of the WebSphere MQ for AIX® Quick Beginnings book: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.amqdac.doc/sq10340_.htm Unsupported usage of MQ and WebSphere Application Server The WebSphere MQ Resource Adapter (RA) V6 or V7 is not supported under WebSphere Application Server V6. The WebSphere MQ Resource Adapter (RA) V6 should not be installed within WebSphere Application Server V7.
Page 11 of 74
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Chapter 2: Configuration differences +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ WebSphere Application Server 5.x uses MQ 5.3 stripped version of MQ server and client MQ 5.3 is out of support. However, there are exceptions (as mentioned earlier) and thus, this section could be useful to those customers who have extended support. WebSphere Application Server 5.0 and 5.1 provide an Embedded Messaging Component which is a stripped version of the MQ 5.3 client and server. The subset of the MQ 5.3 code is installed in the normal MQ directories: AIX: /usr/mqm Unix: /opt/mqm Windows: C:\Program Files\IBM\WebSphere MQ The queue managers created by the embedded messaging component have a name that follows the pattern: WAS_hostname_server1 For example: WAS_aemtux1_server1 The queue managers are started and stopped when the WebSphere Application Server is started and stopped.
Page 12 of 74
WebSphere Application Server 6.x uses MQ 5.3 and 6 Client jar files WebSphere Application Server V6 ships the System Integration Bus (SIB) as the “Default Messaging Provider”, which is a different technology than MQ although there are many similarities between the products. WebSphere Application Server 6 also ships the "WebSphere MQ messaging provider" which is the following subset of the MQ Java/JMS jar files:
com.ibm.mq.jar com.ibm.mqjms.jar dhbcore.jar
These jar files are provided in the directory specified by:
${WAS_INSTALL_ROOT}/lib/WMQ/java/lib This location is also known as: MQJMS_LIB_ROOT Caveat: You should NOT modify this WebSphere Application Server environment variable. Instead, modify MQ_INSTALL_ROOT if necessary (see below for more details). In WebSphere Application Server V6.0: There is no harm in modifying MQJMS_LIB_ROOT, but the pitfall is that in case of problems, all the IBM problem determination tasks do NOT mention this variable, but instead, mention MQ_INSTALL_ROOT. This means that if MQJMS_LIB_ROOT is changed and if problems are encountered, then it may take longer to identify a configuration problem. In WebSphere Application Server V6.1: MQJMS_LIB_ROOT is NO longer used. It is still shown in the WebSphere Application Server Administration Console, but its value is NOT used. Instead, the following is actually used: ${MQ_INSTALL_ROOT}/java/lib In case that your server was upgraded from V6.0, if this variable is still shown in the Administrative Console, to make the configuration look easier this variable can be removed from the WebSphere variables.
Page 13 of 74
Role of MQ_INSTALL_ROOT The following WebSphere Application Server V5 and V6 environment variable is used by WebSphere Application Server to indicate the relative location of the MQ jar files. This is the WebSphere Application Server environment variable: MQ_INSTALL_ROOT The default value of MQ_INSTALL_ROOT is:
${WAS_INSTALL_ROOT}/lib/WMQ Where WAS_INSTALL_ROOT is: AIX: /usr/IBM/WebSphere/AppServer Others: /opt/IBM/WebSphere/AppServer Windows: C:\Program Files\IBM\WebSphere\AppServer Note: The installation directory for the WebSphere Process Server (WPS), which embeds the WebSphere Application Server is shown below for Unix: /opt/IBM/WebSphere/ProcServer When MQ_INSTALL_ROOT should be used? a) When using Bindings transport type: The MQ JMS Client jar files provided with WebSphere Application Server 6 can ONLY be used with a Client transport type for the Connection Factory. If the customer wanted to use the Bindings transport type, then it is necessary to: 1) Install the MQ server in the same host where WebSphere Application Server is installed, and 2) Modify the WebSphere Application Server environment variable MQ_INSTALL_ROOT to point to the location of the MQ server code, and 3) Stop and restart the WebSphere Application Server. For AIX, the value should be: MQ_INSTALL_ROOT /usr/mqm For Other Unix: MQ_INSTALL_ROOT /opt/mqm For Windows: MQ_INSTALL_ROOT C:\Program Files\IBM\WebSphere MQ For more details see in this document: Chapter 4: Using Bindings transport type and local native MQ libraries
Page 14 of 74
b) When desiring to use a latest MQ maintenance (Fix Pack) b.1) WebSphere Application Server versions that include the latest MQ Fix pack Until the WebSphere Application Server fix pack 6.1.0.18 (MQ 6.0.2.4), in order to use a newer version of the MQ JMS Client jar files, it was necessary to install a WebSphere Application Server fix pack. Starting with WebSphere Application Server fix pack 6.1.0.29 (MQ 6.0.2.8), there is a resume of providing the newer version of the MQ jar files via the WebSphere Application Server fix packs. Note about the numbering of WebSphere Application Server fix packs for Distributed Platforms: The fix packs for WebSphere Application Server are identified by odd numbers: 6.1.0.19 then 6.1.0.21 then 6.1.0.23, etc. b.2) WebSphere Application Server versions that included MQ 6.0.2.4 even though this MQ fix pack was not the latest one Between WebSphere Application Server fix pack 6.1.0.19 and fix pack 6.1.0.28, the version of the MQ JMS Client jar files has been 6.0.2.4. That is, these WebSphere Application Server fix packs do NOT provide newer versions of MQ. This means that if the customer using WebSphere Application Server 6.1.0.21 (for example) needed to use the MQ fix pack 6.0.2.8 because a fix that addressed a problem encountered with the MQ jar files, then the customer needs to do the following: 1) Install the MQ Client http://www.ibm.com/support/docview.wss?uid=swg24019253 MQC7: WebSphere MQ V7.0 Clients http://www.ibm.com/support/docview.wss?uid=swg24009961 MQC6: WebSphere MQ V6.0 Clients 2) Modify the WebSphere Application Server environment variable MQ_INSTALL_ROOT to point to the location of the MQ client code, and 3) Stop and restart the WebSphere Application Server.
Page 15 of 74
WebSphere Application Server V7 uses MQ Resource Adapter WebSphere Application Server V7 does NOT ship the individual MQ JMS Client jar files. Instead, it ships the MQ Resource Adapter (RA), which is a zip file that has the MQ JMS Client jar files and other files needed for the J2EE Connector Architecture (JCA). The MQ RA V7 is similar to the one provided in MQ RA V6 but it has additional files in order to be JCA compliant. The MQ RA can be used for both Bindings and Client transport type for the Connection Factories. The maintenance updates for the MQ RA are done via the WebSphere Application Server Fix Packs That is, it is not done via MQ fix packs or the installation of the MQ Client. The MQ_INSTALL_ROOT variable is not really used in Unix because the RA has already the specification of the MQ installation directories: /usr/mqm in AIX, /opt/mqm in Unix, C:\Program Files\IBM\WebSphere MQ in Windows. The MQ_INSTALL_ROOT variable is ONLY used with WebSphere Application Server V7 in Windows if and only if the MQ code is NOT installed in the default location:
C:\Program Files\IBM\WebSphere MQ Manual task is needed when applying a Fix Pack on top of WebSphere Application Server 7.0.0.0 (for using the correct MQ Resource Adapter) WARNING: There was an installation bug in WebSphere Application Server 7.0.0.0 and it did not handle correctly the proper location of the MQ RA and a fix was introduced in WebSphere Application Server 7.0.0.1 and later, in order to recognize newer versions of the MQ RA. In order to fully enable the fix, it is necessary to perform a manual task (one time only) with the WebSphere Application Server configuration. Otherwise, the old copy of MQ RA at version MQ 7.0.0.0 is used and any newer versions are ignored. This problem of not handling the correct location of the MQ RA causes the following errors:
Page 16 of 74
java.lang.UnsatisfiedLinkError: mqjbnd05 Other similar errors are: Ý3/18/10 7:31:06:344 EDT¨ 0000000d MDBListenerIm W WMSG0019E: Unable to start MDB Listener SoeMDB, JMSDestination jms/S0127MDBQueue : com.ibm.websphere.naming.CannotInstantiateObjectException: Exception occurred while the JNDI NamingManager was processing a javax.naming.Reference object. ... Caused by: javax.naming.NamingException: WMSG2001E: It was not possible to lookup the specified WebSphere MQ administered object because the WebSphere MQ client libraries are not available to the server. Ý3/18/10 7:31:06:407 EDT¨ 0000000b MDBListenerIm W WMSG0017E: Unable to lookup JMS resources, JNDI lookup exception: WMSG2001E: It was not possible to lookup the specified WebSphere MQ administered object because the WebSphere MQ client libraries are not available to the server. WMSG1625E: It was not possible to detect the WebSphere MQ messaging provider code at the specified path <null> JMSRegistrati A WMSG1611I: The installed level of the WebSphere MQ messaging provider is 7.0.0.0. JMSRegistrati I WMSG1703I: RAR implementation version 7.0.0.0-k700-L080820 Consult the following web page: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/tmj_wmqra_restoredefault.html WebSphere Application Server V7 Information Center; "Ensuring that servers use the latest available WebSphere MQ JCA resource adapter maintenance level" In WMQ 7 the original wmq.jmsra.rar file is located as shown below (this example is for Linux). It is ONLY used for reverting to a WebSphere Application Server 7.0.0.0 profile:
/opt/IBM/WebSphere/AppServer/lib/WMQ/ra/wmq.jmsra.rar At runtime, the most up to date copy of the MQ RA file is being used. This is also the location that the Fix Packs for the WebSphere Application Server place the RA file: /opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar
Page 17 of 74
+++ How to identify the version of the MQ jar files or RA To find out the level / version of the MQ JMS jar files that are shipped with WebSphere Application Server or that customers copy from a full MQ install, there are several ways: a) Using "java" command (only for MQ 6.0 and 7.0, not for MQ 5.3) on the jar files Linux (all in one line) java -cp /opt/mqm/java/lib/com.ibm.mqjms.jar com/ibm/mq/jms/MQJMSLevel
Windows: cd "C:\Program Files\IBM\WebSphere MQ\Java\lib" Then, all in one line: java -cp "C:\Program Files\IBM\WebSphere
MQ\Java\lib\com.ibm.mqjms.jar" com/ibm/mq/jms/MQJMSLevel
Example of the output for 6.0: Name: WebSphere MQ classes for Java Message Service Version: 6.0.2.2 CMVC Level: j600-202-070711 Build Type: Production Example of the partial output for 7.0: Name: Java Message Service Client Version: 7.0.0.0 CMVC Level: k000-L080529 Build Type: Production Name: WebSphere MQ classes for Java Message Service Version: 7.0.0.0 CMVC Level: k000-L080529 Build Type: Production b) By actually opening the jar file and looking at MANIFEST.MF file Here are some steps to obtain that information: cp /opt/mqm/java/lib/com.ibm.mq.jar /tmp/com.ibm.mq.jar cd /tmp jar -xvf /tmp/com.ibm.mq.jar cd META-INF
Page 18 of 74
cat MANIFEST.MF Look at the MANIFEST.MF file from an MQ jar file. For example, using WinZip on com.ibm.mqjms.jar: MQ 5.3: The following is for Fix pack 11 (disregard the 5.306), see the token after j5306. Implementation-Version: 5.306 - j5306-11-050725 MQ V6: The following is for Fix pack 6.0.2.2, see the token after j600, in this case "202" (which means 6.0.2.2): Implementation-Version: 6.0.2.2 - j600-202-070711 MQ V7: The following is for GA 7.0.0.0: Implementation-Title: WebSphere MQ classes for Java Message Service Implementation-Version: 7.0.1.0 - k000-L090724 c) From the JMS trace This is the most reliable, because it is what the WebSphere Application Server code is actually using. The trace string a JMS trace is (it should be in one line): *=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all: com.ibm.mq.*=all:jmsApi=all The trace file shows the location and version of the resource adapter that is being used: . [10/19/09 13:33:26:382 EDT] 00000000 > UOW= source=com.ibm.ejs.jms.JMSRegistrationHelper method=checkVersion org=IBM prod=WebSphere component=Application Server thread=[main] Entry parm0=/opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar parm1=com.ibm.ejs.jms.JMSRegistrationHelper@3e783e78 ... # See the method=getVersion [10/19/09 13:33:26:401 EDT] 00000000 < UOW= source=com.ibm.ws.wmqra.registration.WMQRAClientInstall method=getVersion (com.ibm.ws.wmqra.registration.WMQRAClientInstall) [:/62556255] org=IBM prod=WebSphere component=Application Server thread=[main] Exit parm0=7.0.1.0
Page 19 of 74
d) Resource Adapter: Via a wsadmin Jython “mqrar-version.py” The following technote provides the details of a script that can be used to identify the version of the MQ Resource Adapter provided with WebSphere Application Server V7 http://www-01.ibm.com/support/docview.wss?uid=swg21316899 Information about using the WebSphere MQ messaging provider for WebSphere Application Server Version 7.0 These are the details on how to create a Jython script and run it via wsadmin. 1) Login as root. 2) Create a script file named "mqrar-version.py" < begin file > wmqInfoMBeansUnsplit = AdminControl.queryNames("WebSphere:type=WMQInfo,*") wmqInfoMBeansSplit = AdminUtilities.convertToList(wmqInfoMBeansUnsplit) for wmqInfoMBean in wmqInfoMBeansSplit: print wmqInfoMBean; print AdminControl.invoke(wmqInfoMBean, 'getInfo', '') < end file > 3) Run the script as follows: wsadmin.sh -lang jython -f ./mqrar-version.py 4) Example of the output (This is an excerpt, to keep the example short) WASX7209I: Connected to process "server1" on node veracruzNode01 using SOAP connector; The type of process is: UnManagedProcess ---- WMSG1700I: Currently active WebSphere MQ messaging provider configuration in WebSphere Application Server Platform 7.0.0.7 [BASE 7.0.0.7 cf070942.55], report at 2/2/10 2:19 PM); WMSG1702I: Using the WebSphere MQ Resource Adapter WMSG1703I: RAR implementation version 7.0.1.1-k701-101-091001 WMSG1710I: Install Directory is /opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar. WMSG1711I: Native File Directory is null. WMSG1712I: Version is 7.0.1.1. WMSG1713I: Jar Files: /opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar/dhbcore.jar("DH610-GOLD" )
Page 20 of 74
/opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar/com.ibm.msg.client.commonservices.jar(version not found) … /opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar/com.ibm.mq.commonservices.jar(${version.number} - ${build.level}). WMSG1714I: Native Libraries WMSG1705I: Information from WebSphere MQ messaging provider follows: WMSG1715I: Name is com.ibm.msg.client.jms. WMSG1716I: Title is Java Message Service Client. WMSG1717I: Type is INFRA. WMSG1718I: Version is 7.0.1.1. WMSG1719I: Implementation info is {CMVC=k701-101-091001}. WMSG1715I: Name is com.ibm.mq.jms. WMSG1716I: Title is WebSphere MQ classes for Java Message Service. WMSG1717I: Type is INFRA. WMSG1718I: Version is 7.0.1.1. WMSG1719I: Implementation info is {CMVC=k701-101-091001}. e) Resource Adapter: Via a wsadmin Jython “AdminTask.manageWMQ” The AdminTask.manageWMQ from the developerWorks article: http://www.ibm.com/developerworks/websphere/techjournal/0901_leming/0901_leming.html The scripts are useful for those teams who have a large number of WebSphere Application Server servers. Log as root and issue the commands mentioned in the article from DeveloperWorks. By the way, they do not tell us that the -lang jython is necessary, but it is, otherwise the language is JACL. wsadmin.sh -lang jython >> It took around 60 seconds to get the wsadmin prompt WASX7209I: Connected to process "server1" on node veracruzNode01 using SOAP connector; The type of process is: UnManagedProcess WASX7031I: For help, enter: "print Help.help()" wsadmin>print AdminTask.help('WMQAdminCommands') WASX8007I: Detailed help for command group: WMQAdminCommands Description: A group of commands that help configure WebSphere MQ messaging resources.
Page 21 of 74
Commands: createWMQActivationSpec - Creates a WMQ Activation Specification at the scope provided to the command. … manageWMQ - Provides the ability to manage the settings associated with the WMQ resource adapter installed at a particular scope. … wsadmin>AdminConfig.list('J2CResourceAdapter', '*WebSphere MQ*') '"WebSphere MQ Resource Adapter(cells/veracruzNode01Cell/nodes/veracruzNode01/servers/server1|resources.xml#J2CResourceAdapter_1229526439385)"\n"WebSphere MQ Resource Adapter(cells/veracruzNode01Cell/nodes/veracruzNode01|resources.xml#J2CResourceAdapter_1229526438873)"\n"WebSphere MQ Resource Adapter(cells/veracruzNode01Cell|resources.xml#J2CResourceAdapter_1229526439609)"' Take the first item from the list and compose the following command: wsadmin>AdminTask.manageWMQ("WebSphere MQ Resource Adapter(cells/veracruzNode01Cell/nodes/veracruzNode01/servers/server1|resources.xml#J2CResourceAdapter_1229526439385)", ["-query"]) This is the result: '------------------------------------------------------------------------------------------\nWMSG1700I: Currently active WebSphere MQ messaging provider configuration in WebSphere Application Server Platform 7.0.0.7 [BASE 7.0.0.7 cf070942.55], report at 2/26/10 3:04 PM);\nWMSG1702I: Using the WebSphere MQ Resource Adapter\nWMSG1703I: RAR implementation version 7.0.1.1-k701-101-091001\nWMSG1710I: Install Directory is /opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar.\nWMSG1711I: Native File Directory is null. \nWMSG1712I: Version is 7.0.1.1. \nWMSG1713I: Jar Files: /opt/IBM/WebSphere/AppServer/installedConnectors/wmq.jmsra.rar/dhbcore.jar("DH610-GOLD" )\n … \n\n------------------------------------------------------------------------------------------------------\n' wsadmin>wsadmin>
Page 22 of 74
Using dspmqver if MQ client is installed If the MQ client or MQ server code is installed and if MQ_INSTALL_ROOT is pointing to the location of the standalone MQ code, then the following MQ command can be used to find out the version of the MQ JMS client. First, in Unix you need to ensure that the MQ environment variables for Java and JMS are properly configured. This can be accomplished by using the “setjmsenv” or "setjmsenv64" script provided with MQ. Notice the dot and a space before “setjmsenv”, this is important in order for the environment variables that are set in the script, to be available in the current process: 32-bit: . setjmsenv 64-bit: . setjmsenv64 Note: The installation of MQ in Windows already sets the proper variables. Secondly, issue the following command: MQ V6: $ dspmqver -p 4 Name: WebSphere MQ classes for Java Message Service Version: 6.0.2.4 CMVC Level: j600-204-080509 Build Type: Production MQ V7: $ dspmqver -p 4 Name: Java Message Service Client Version: 7.0.1.0 CMVC Level: k000-L090724 Build Type: Production Name: WebSphere MQ classes for Java Message Service Version: 7.0.1.0 CMVC Level: k000-L090724 Build Type: Production
Page 23 of 74
Note: If you get error AMQ8568 or AMQ8351 when using “dspmqver –p 4” consult the following technote for more details on how to solve the problem. http://www.ibm.com/support/docview.wss?uid=swg21413508 AMQ8568 mqjbnd=CC=2 RC=2495 when issuing "dspmqver -p 4"
Page 24 of 74
Exploiting new MQ V7 features in WebSphere Application Server V7 For more details on the new MQ V7 features that can be exploited in WebSphere Application Server V7, see the presentation from the WSTE previously mentioned: http://www.ibm.com/support/docview.wss?uid=swg27016505 Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7 As well as the following Redbook: http://www.redbooks.ibm.com/abstracts/SG247583.html?Open WebSphere MQ V7.0 Features and Enhancements (SG24-7583) The rest of this section shows how to use the WebSphere Application Server V7 Administration Console to enable these new MQ V7 features: These functions are ONLY available in WebSphere Application Server V7. Read Ahead Resources > JMS > Queues > $QueueName/$TopicName > Advanced properties Section: Optimizations
Page 25 of 74
You will see the Advanced Properties:
You will need to scroll down. Section: Optimizations
Read ahead, and cache, non-persistent messages for consumers As per queue definition Yes No Read ahead consumer close method Wait for all cached messages to be delivered Wait for the current message to be delivered
Page 26 of 74
Asynchronous put ("fire and forget") Resources > JMS > Queues > $QueueName/$TopicName > Advanced properties Section: Optimizations See previous page for the "Advanced Properties".
Asynchronously send messages to the queue manager As per queue definition Yes No
Page 27 of 74
Listener Ports and Activation Specifications A Message Driven Bean (MDB) inside the WebSphere Application Server receives messages from the MQ JMS client via one of the following 2 components from the application server: - A Listener Port - An Activation Specification WebSphere Application Server V6: - Only Listener Ports can be used. WebSphere Application Server V7: - Both Activation Specification (preferred) and - Listener Ports (deprecated, but still available) can be used. For more information on Activation Specifications, see the article: http://www.ibm.com/developerworks/websphere/techjournal/0901_leming/0901_leming.html Using the WebSphere MQ messaging provider in WebSphere Application Server V7: Part 1: Introducing the new WebSphere MQ messaging provider
Page 28 of 74
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Chapter 3: Maintenance of the MQ JMS client files +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The MQ JMS client files are maintained via different methods: WebSphere Application Server V5 WebSphere Application Server BEFORE 5.0.2 and 5.1.1: via fix packs for the WebSphere Application Server Interim fixes: EOS reached. Not supported. WebSphere Application Server AFTER 5.0.2 and 5.1.1: via MQ 5.3 fix packs Interim fixes: via MQ jar files (see earlier notes regarding support for MQ 5.3). See technote: http://www.ibm.com/support/docview.wss?uid=swg21259842 How to apply maintenance to WebSphere Application Server v5 embedded messaging beyond 5.0.2 and 5.1.1 Excerpt: In order to allow continued maintenance of the embedded messaging component, for WebSphere Application Server levels of 5.0.2 or later for the 5.0 product, or 5.1.1 or later for the 5.1 product, the regular WMQ fix packs for the full stand-alone WebSphere MQ v5.3 product can now be installed on top of embedded messaging. Note: If the level of WebSphere Application Server is below 5.0.2 or below 5.1.1, then customer needs to upgrade to 5.0.2 or 5.1.1 and then apply the MQ 5.3 CSD 14 fix pack. WebSphere Application Server V6 Version 6.0.2 Fix Packs: WebSphere Application Server fix packs (MQ 5.3) Interim fixes: MQ jar files (see earlier notes regarding support for MQ 5.3). Up to Version 6.1.0.18 Fix Packs: WebSphere Application Server fix packs Interim fixes: MQ jar files From Version 6.1.0.19 to Version 6.1.0.28 (MQ 6.0.2.4) Fix Packs: MQ fix packs (MQ 6) Interim fixes: MQ jar files
Page 29 of 74
Version 6.1.0.29 and later Fix Packs: WebSphere Application Server fix packs Interim fixes: MQ jar files WebSphere Application Server V7 Fix Packs: WebSphere Application Server fix packs Interim fixes: WebSphere Application Server .pak files For applying the interim fixes for the MQ RA, see the following 2 web pages from the WebSphere Application Server V7 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.installation.base.doc/info/aes/ae/cins_updi_installationoverview.html WebSphere Application Server V7 Information Center Installing maintenance packages overview http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.installation.base.doc/info/aes/ae/tins_ptfLevels.html WebSphere Application Server V7 Information Center Installing maintenance packages, interim fixes, fix packs, and refresh packs
Page 30 of 74
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Chapter 4: Using Bindings transport type and local native MQ libraries +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Question: What is the difference between the "MQ installation directory" and the location for the "MQ native libraries"? Answer: A) The WebSphere MQ V7 installation directory is: AIX: /usr/mqm Unix: /opt/mqm Windows: C:\Program Files\IBM\WebSphere MQ B) The location of the MQ native libraries is: AIX: /usr/mqm/java/lib and /usr/mqm/java/lib64 Linux 32-bit: only /opt/mqm/java/lib Others: /opt/mqm/java/lib and /opt/mqm/java/lib64 Windows: C:\Program Files\IBM\WebSphere MQ\java\lib Note regarding the scope: please refer to this link for more clarity on the path for the Native Libraries: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/tmj_adm33.html Configuring the WebSphere MQ messaging provider with native libraries information To quote: "Note that native path information at Server scope is used in preference to native path information at higher scopes, and native path information at Node scope is used in preference to native path information at Cell scope. " WebSphere Application Server V6: WebSphere Application Server V6 ships with a subset of the MQ client which enables applications inside WebSphere Application Server to use JMS with MQ by using the “Client” transport type. This MQ JMS client provided by WebSphere Application Server does NOT support the use of “Bindings” transport type, as indicated in the following technote: http://www.ibm.com/support/docview.wss?uid=swg21307203 Information about using WebSphere MQ as the JMS Provider for WebSphere Application Server 6.1
Page 31 of 74
Error messages in WebSphere Application Server V6 when trying to use Bindings mode with the MQ jar files Let‟s assume that the Connection Factory that the application that you are trying to use is changed from CLIENT (using TCP/IP) transport type to BINDINGS (using inter-process communications). Let‟s further assume that the value of MQ_INSTALL_ROOT is the default one:
${WAS_INSTALL_ROOT}/lib/WMQ When you are trying to start the Listener Port that uses the above Connection Factory, you will see the error in the WebSphere Application Server administration console: Listener port SampleMDBTopicLP could not be started
Page 32 of 74
The SystemOut.log file shows the following errors: [12/28/09 10:35:36:842 EST] 00000023 MDBListenerIm I WMSG0043I: MDB Listener SampleMDBTopicLP stopped for JMSDestination jms/SampleMDBTopic [12/28/09 10:35:36:879 EST] 00000023 MDBListenerIm I WMSG0058I: Listener Port SampleMDBTopicLP will attempt to restart in 60 seconds [12/28/09 10:35:36:995 EST] 00000023 ServiceLogger I com.ibm.ws.ffdc.IncidentStreamImpl initialize FFDC0009I: FFDC opened incident stream file /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/ffdc/server1_00000023_09.12.28_10.35.36_0.txt The FDC files show: UnsatisfiedLinkError: mqjbnd05 Exception = java.lang.NoClassDefFoundError Source = com.ibm.ejs.util.am._Alarm.run probeid = 95 Stack Dump = java.lang.NoClassDefFoundError: com.ibm.mq.server.MQSESSION (initialization failure) at java.lang.J9VMInternals.initialize(J9VMInternals.java:132) at com.ibm.mq.MQSESSIONServer.getMQSESSION(MQSESSIONServer.java:68) at com.ibm.mq.MQSESSION.getSession(MQSESSION.java:508) ... Caused by: java.lang.UnsatisfiedLinkError: mqjbnd05 (Not found in java.library.path) at java.lang.ClassLoader.loadLibraryWithPath(ClassLoader.java:979) at java.lang.ClassLoader.loadLibraryWithClassLoader(ClassLoader.java:948) The following technote describes also this problem: http://www.ibm.com/support/docview.wss?uid=swg21248900 java.lang.UnsatisfiedLinkError received when connecting to a queue manager The rest of this chapter describes how to overcome this problem. Note for AIX: Run the dltmqlnk WebSphere MQ control command. If your application server is 64 bit, you must run the dltmqlnk WebSphere MQ control command as root before applications are able to connect to a queue manager using a BINDINGS transport type. The command must be rerun each time a WebSphere MQ fix pack is installed. For more information, see the "Implications of a 64-bit queue manager" section of the WebSphere MQ for AIX® Quick Beginnings book: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.amqdac.doc/sq10340_.htm
Page 33 of 74
WebSphere Application Server V6: Installing MQ server and modifying MQ_INSTALL_ROOT In order to use the “Bindings” transport type, it is necessary to: A) Install the MQ server code in the same host as WebSphere Application Server B) Modify the MQ_INSTALL_ROOT environment inside WebSphere Application Server V6 to point to the location of the MQ code (outside the WebSphere Application Server directory structure). The rest of this section elaborates on these topics. Install the MQ server code in the same host as WebSphere Application Server V6 The minimum level for MQ is 6.0.1.1. WebSphere Application Server 6.1: The minimum level for WebSphere Application Server to interact with MQ V7 is: 6.1.0.17 WebSphere Application Server 6.0: Minimum level is WebSphere Application Server 6.0.2.29 to interact with MQ V7 See the following section from the WebSphere Application Server V6 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/tmj_instm.html Installing WebSphere MQ to interoperate with WebSphere Application Server
Page 34 of 74
WebSphere Application Server V6: Default configuration of MQ_INSTALL_ROOT (for Client transport type) In WebSphere Application Server V6 the MQ JMS client jar files are located in ${MQJMS_LIB_ROOT} which is defined as: ${MQ_INSTALL_ROOT}/java/lib The default value of MQ_INSTALL_ROOT is:
${WAS_INSTALL_ROOT}/lib/WMQ WAS_INSTALL_ROOT is AIX: /usr/IBM/WebSphere/AppServer Others: /opt/IBM/WebSphere/AppServer Windows: C:\Program Files\IBM\WebSphere\AppServer The jar files are located in ${MQ_INSTALL_ROOT}/java/lib Thus, the full path for these MQ jar files is: AIX: /usr/IBM/WebSphere/AppServer/lib/WMQ/java/lib Others: /opt/IBM/WebSphere/AppServer/lib/WMQ/java/lib Windows: C:\Program Files\IBM\WebSphere\AppServer\lib\WMQ\java\lib
Page 35 of 74
To find out the values for these variables, use the WebSphere Application Server administrative console: From the left panel, expand: Environment Then click on: WebSphere Variables Ensure to select the scope to: Node
You will need to scroll down or go to the next page in the long list of variables, until you find: MQ_INSTALL_ROOT ${WAS_INSTALL_ROOT}/lib/WMQ
Page 36 of 74
Modifying MQ_INSTALL_ROOT to use Bindings transport type in WebSphere Application Server V6 If you want to use Bindings transport type for your connection factories, then you will need to modify MQ_INSTALL_ROOT to use the MQ code that is installed in the same box, because the Bindings mode requires to have more MQ functions than the ones provided just with the MQ client jar files under the WebSphere Application Server directory structure. For AIX: MQ_INSTALL_ROOT /usr/mqm For Other Unix: MQ_INSTALL_ROOT /opt/mqm For Windows: MQ_INSTALL_ROOT C:\Program Files\IBM\WebSphere MQ Note: After you change this variable, you need to stop and restart the server.
Page 37 of 74
WebSphere Application Server V6 and WebSphere Application Server 7 with MQ V7 In order to locate the WebSphere MQ V7 native libraries required for BINDINGS mode, the application server needs to be configured to have the generic Java Virtual Machine (JVM) argument -Djava.libary.path set to the location of the libraries. For information about where these files are installed, please see the "The Java Native Interface (JNI) libraries required by WebSphere MQ classes for JMS applications" section in the WebSphere MQ Version 7 "Using Java" manual. http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm10340_.htm From the WebSphere Application Server V6 Admin Console: Click on Servers > Application Servers > server1.
You will need to scroll down and under “Server Infrastructure”, click Java and Process Management > Process definition
Page 38 of 74
Then click Java and Process Management > Process definition
Then select “Java Virtual Machine”
You will see:
Page 39 of 74
Scroll down to find "Generic JVM arguments.
Under “Generic JVM arguments”, enter: -Djava.library.path=library_path For Linux 32-bit, it should be: -Djava.library.path=/opt/mqm/java/lib For Linux 64-bit, HP-UX and Solaris, the string is: -Djava.library.path=/opt/mqm/java/lib:/opt/mqm/java/lib64 For AIX, the string is: -Djava.library.path=/usr/mqm/java/lib:/usr/mqm/java/lib64 For Windows, the string is: -Djava.library.path="C:\Program Files\IBM\WebSphere MQ\java\lib"
Page 40 of 74
WebSphere Application Server V7: It is required for bindings mode applications that the JMS runtime must access the appropriate "bindings module" in the "native" WMQ libraries. Thus the Resource Adapter's "native library path" must be configured to point to the WMQ directory where these libraries are located: AIX: /usr/mqm/java/lib and /usr/mqm/java/lib64 Linux 32-bit: only /opt/mqm/java/lib Others: /opt/mqm/java/lib and /opt/mqm/java/lib64 Windows: C:\Program Files\IBM\WebSphere MQ\java\lib For more information see the following web page from the WebSphere Application Server V7 Information Center: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/tmj_adm33.html Configuring the WebSphere MQ messaging provider with native libraries information
Page 41 of 74
Procedure: - In the navigation pane, expand Resources > JMS > JMS providers - Select the WebSphere MQ messaging provider that is at the correct Scope for the connection factory or activation specification that will create the bindings mode connection. Note that native path information at Server scope is used in preference to native path information at higher scopes, and native path information at Node scope is used in preference to native path information at Cell scope. - Under General Properties, in the Native library path property, enter the full name of the directory that contains the WebSphere MQ native libraries. For example, on Linux 32-bit enter /opt/mqm/java/lib. Click OK. - Save any changes to the master configuration. - If you are running in an application server environment, you must restart all affected servers twice when you have changed the native path information. Otherwise, a WMSG1623E message is produced, indicating that the WebSphere MQ messaging provider is not available.
Page 42 of 74
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Chapter 5: Debugging and Problem Determination +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ JMS application needs to display linked Exceptions At runtime, when encountering an exception, the MQ JMS client provides a main Exception followed by linked or nested exceptions. In the case of MQ V5 and V6, the main exception is usually a catch-call, not too informative message and it always has one or more linked exceptions: MQJMS2005: failed to create MQQueueManager for „mynode:WAS_mynode_server1' The wording is a bit confusing and some people interpret it as a problem in creating a new MQ queue manager under /var/mqm, when in reality is reporting a problem in creating an internal object in the JMS client code that has a type of MQQueueManager. An example is shown below: javax.jms.JMSException: MQJMS2005: failed to create MQQueueManager for 'mynode:WAS_mynode_server1' at com.ibm.mq.jms.services.ConfigEnvironment.newException(ConfigEnvironment.java:556) at com.ibm.mq.jms.MQConnection.createQM(MQConnection.java:1736) ... com.ibm.mq.MQException: MQJE001: An MQException occurred: Completion Code 2, Reason 2009 MQJE003: IO error transmitting message buffer at com.ibm.mq.MQManagedConnectionJ11.<init>(MQManagedConnectionJ11.java:239)
Many applications only show the main exception and do not show the linked exception. This means that the user will see the catch-all error MQJMS2005 without any further details. This causes delays with the problem determination tasks. It is critical that the application should be able to display the linked exceptions for MQ JMS. As I mentioned before, the MQJMS2005 is always shown with a linked exception which provides more details.
Page 43 of 74
MQ V6 – Handling JMS exceptions in the code The following web page from the MQ V6 Information Center has more details: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/uj24500_.htm Writing WebSphere MQ JMS applications > Handling errors . An excerpt is: (please see the whole web page) " Any runtime errors in a JMS application are reported by exceptions. The majority of methods in JMS throw JMSExceptions to indicate errors. It is good programming practice to catch these exceptions and display them on a suitable output. . A JMSException can contain a further exception embedded in it. For JMS, this can be a valuable way to pass important detail from the underlying transport. In the case of WebSphere MQ JMS, when WebSphere MQ raises an MQException, this exception is usually included as the embedded exception in a JMSException. . The implementation of JMSException does not include the embedded exception in the output of its toString() method. Therefore, it is necessary to check explicitly for an embedded exception and print it out, as shown in the following fragment: try { . . code which may throw a JMSException . } catch (JMSException je) { System.err.println("caught "+je); Exception e = je.getLinkedException(); if (e != null) { System.err.println("linked exception: "+e); } } "
Page 44 of 74
MQ V7 – Handling JMS exceptions in the code There was a major rework of the MQ Java and JMS classes in V7 and the handling of JMS exceptions was improved. Please consult the following web page from the MQ V7 Information Center: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm35210_.htm Exceptions in WebSphere MQ classes for JMS " A WebSphere MQ classes for JMS application must be able to handle exceptions that are thrown by a JMS API calls or delivered to an exception handler. Compared to previous versions, most exception messages and error codes have changed in Version 7 of WebSphere MQ classes for JMS. If your application parses or tests exception messages and error codes, it probably needs to be modified in order to use Version 7. … For example, if an application tries to create a message producer for a WebSphere MQ queue that does not exist, an exception is thrown with the following information: Message : JMSWMQ2008: Failed to open MQ queue 'Q_test'. Class : class com.ibm.msg.client.jms.DetailedInvalidDestinationException Error Code : JMSWMQ2008 Explanation : JMS attempted to perform an MQOPEN, but WebSphere MQ reported an error. User Action : Use the linked exception to determine the cause of this error. Check that the specified queue and queue manager are defined correctly. “
Page 45 of 74
Upgrading from previous versions of WebSphere MQ classes for JMS http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm35210_.htm MQ 7 Information Center > Using Java >> Exceptions in WebSphere MQ classes for JMS >>> Upgrading from previous versions of WebSphere MQ classes for JMS Compared to previous versions of WebSphere MQ classes for JMS, most error codes and exception messages have changed in Version 7. The reason for these changes is that WebSphere MQ classes for JMS now has a layered architecture and exceptions are thrown from different layers in the code. For example, if an application tries to connect to a queue manager that does not exist, a previous version of WebSphere MQ classes for JMS threw a JMSException exception with the following information: MQJMS2005: Failed to create MQQueueManager for 'localhost:QM_test'. This exception contained a linked MQException exception with the following information: MQJE001: Completion Code 2, Reason 2058 By comparison in the same circumstances, Version 7 of WebSphere MQ classes for JMS throws a JMSException exception with the following information: Message : JMSWMQ0018: Failed to connect to queue manager 'QM_test' with connection mode 'Client' and host name 'localhost'. Class : class com.ibm.msg.client.jms.DetailedJMSException Error Code : JMSWMQ0018 Explanation : null User Action : Check the queue manager is started and if running in client mode, check there is a listener running. Please see the linked exception for more information. This exception contains a linked MQException exception with the following information: Message : JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2058' ('MQRC_Q_MGR_NAME_ERROR'). Class : class com.ibm.mq.MQException Completion Code : 2 Reason Code : 2058 "
Page 46 of 74
+++ Basic problem determination Review the application server error logs In most cases of problems with the MQ JMS client, it is sufficient to review the SystemOut.log file of the application server. It usually contains the MQ JMS errors or warnings and related messages from the application server. The SystemOut.log file is located at: Version 5: ${WAS_HOME}/logs/server_name/SystemOut.log Where WAS_HOME is: AIX: /usr/Websphere/AppServer Unix: /opt/Websphere/AppServer Windows: C:\Program Files\WebSphere\AppServer Example: /usr/Websphere/AppServer/logs/server1/SystemOut.log Version 6 and 7: ${WAS_HOME}/profiles/profile_name/logs/server_name/SystemOut.log Where WAS_HOME is: AIX: /usr/IBM/WebSphere/AppServer Others: /opt/IBM/WebSphere/AppServer Windows: C:\Program Files\IBM\WebSphere\AppServer Example in Linux, using profile “AppSrv01” and server “server1” /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1 Notice that the SystemOut.log file (as well as the SystemErr.log and the trace.log files) when reaching a determined file size, it is copied and renamed to “SystemOut.time_stamp.log” and a new “SystemOut.log” file is created.
Page 47 of 74
Other application server files to review: a) SystemErr.log Another system file that sometimes has additional information on errors is:
SystemErr.log It is located in the same directory where SystemOut.log is stored. b) Native error logs The following files are also located in the same directory where SystemOut.log is stored.
native_stderr.log native_stdout.log
These files are used mainly when the customer is using non-IBM JVMs, such as in HP-UX and Solaris. c) FFDC files If the SystemOut.log shows that a First Failure Data Capture (FFDC) file was generated in response to an error condition, it is important to review it. The location of the FFDC files is: ${WAS_HOME}/profiles/profile_name/ffdc/server_name
Page 48 of 74
Review the MQ error logs This section applies to the local queue manager, the remote queue manager, using transport type of Client or of Bindings. The MQ error logs are located in the following directories. General logs: Unix: /var/mqm/errors Windows: C:\Program Files\IBM\WebSphere MQ\errors Specific logs for a queue manager: Unix: /var/mqm/qmgrs/<QMgrName>/errors Windows: C:\Program Files\IBM\WebSphere MQ\qmgrs\<QMgrName>\errors Trace logs: Unix: /var/mqm/trace V5.3 - Windows: C:\Program Files\IBM\WebSphere MQ\errors V6,V7 - Windows: C:\Program Files\IBM\WebSphere MQ\trace Obtaining JMS traces in WebSphere Application Server Sometimes it is necessary to capture the traces for the MQ JMS client when running within the application server. This is done by capturing the traces from the WebSphere Application Server and specifying a string that indicates which MQ Classes for JMS to capture. Note: In MQ V7, standalone JMS applications can use a JMS configuration file to specify several attributes for capturing the trace. By default, this configuration file is not used by WebSphere Application Server, and thus, there are no more details about this configuration file in this document. For more information on capturing the JMQ trace from the application server, see the following technote for the steps to configure the trace. http://www.ibm.com/support/docview.wss?uid=swg21199176 Enabling JMS trace for releases of WebSphere Application Server V5.1, V6.0, V6.1, and V7.0 The trace string should be as shown below. Specify all the tokens in the string in one line and no spaces between letters and symbols.
Page 49 of 74
WebSphere Application Server V5 (all in one line): JMSApi=all=enabled:JMSServer=all=enabled:JMSQueueManager=all=enabled:Messaging=all=enabled: WebSphere Application Server V6 and V7 (all in one line): *=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.ibm.mq.*=all:jmsApi=all Location of the trace files: <WAS_HOME>\profiles\<server_name>\logs\<server_name>\trace.log To disable the trace in WebSphere Application Server: Note: After you have finished collecting the trace, disable the tracing to avoid unnecessary consumption of system resources and disk space. Change the trace string to: WebSphere Application Server V5: <blank> WebSphere Application Server V6.0 and V7.0: *=info Note: The trace.log file shows the trace string specification, above the line “End Display Current Environment”: ************ Start Display Current Environment ************ WebSphere Platform 7.0.0.7 [BASE 7.0.0.7 cf070942.55] running with process name veracruzNode01Cell\veracruzNode01\server1 and process id 9989 Host Operating System is Linux, version 2.6.5-7.322-default … Java Library path = /opt/IBM/WebSphere/AppServer/java/jre/lib/i386:/opt/IBM/WebSphere/AppServer/bin:/home/db2inst1/sqllib/lib:/usr/lib:/opt/mqm/java/lib:/opt/mqm/java/lib64 Current trace specification = *=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.ibm.mq.*=all: JMSApi=all ************* End Display Current Environment ************* [3/1/10 12:44:42:848 EST] 00000000 I UOW=null source=com.ibm.ejs.ras.ManagerAdmin org=IBM prod=WebSphere component=Application Server thread=[main]
Page 50 of 74
If the trace is needed for the startup of the application server, then you will need to restart the application server. If you want to enable the trace on a running server, see the following pages from the appropriate information center: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.ejbfep.multiplatform.doc/info/ae/ae/ttrb_entrrs.html WAS V6: Enabling trace on a running server . http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/ttrb_entrrs.html WAS V7: Enabling trace on a running server Capture simultaneous traces for the MQ queue manager and JMS Sometimes it is necessary to capture concurrently the traces from the MQ queue manager and the MQ JMS client used by the WebSphere Application Server. The full instructions for obtaining the MQ traces are in the following web page. http://www.ibm.com/support/docview.wss?rs=172&uid=swg21174924 MustGather: Directions to start, end, and format trace For convenience, a summary of the steps is described below: - In a text note, indicate the date/time when you are starting these activities. The idea is to help IBM Support to narrow down the search when looking at the messages in the MQ error logs and to correlate them with any trace files. - If possible, indicate the message ids or correlation ids of the messages being put/get by the application that was of interest. Or indicate the name of the queue manager, the name of the queue, etc. - Login as an MQ administrator (mqm) in the host that has the Queue Manager - Delete previous traces: rm /var/mqm/trace/* - Start the trace: strmqtrc -m QMgrName -t all -t detail - Ensure that the JMS trace in the WebSphere Application Server is active - Recreate the problem.
Page 51 of 74
If the problem is of a “hang” nature, then capture between 30 seconds and 60 seconds of trace. - End the trace for MQ: endmqtrc -a - End the trace for WebSphere Application Server. - Format the MQ trace files, resulting in human readable files that have a suffix of FMT. This step is applicable only for Unix. The files in Windows are formatted already. cd /var/mqm/trace/ dspmqtrc *.TRC - Gather the files and send them to IBM Support (described in a later section). +++ Gathering files for IBM Support There are 4 ways to capture the files that are needed by IBM Support in case that you open a PMR to report a problem. 1) Manual gathering of both WebSphere Application Server and MQ data 2) MQ V7 runmqras tool 3) WebSphere Application Server Collector tool 4) ISA tool for WebSphere Application Server
Page 52 of 74
1) Manual gathering of both WebSphere Application Server and MQ data Collects the main files that need to be reviewed by the MQ Support teams are collected, with the bare essentials for the WebSphere Application Server Support teams. Advantage: - It is the easiest and fastest approach. Disadvantages: - Not all the files needed by WebSphere Application Server Support are collected. - Some secondary files and runtime data from MQ are not collected. - Prepare a tar file (or a zip file), where the complete PMR number is the first part of the file name. There is an agent running in the IBM ftp site that handles files based on the PMR number specified in the file name. Ensure to use the proper name of the Queue Manager (<qMgr>) in the directory structure. If the problem does not involve the queue manager, then do not include the corresponding line when preparing the tar file. This assumes that WebSphere Application Server and MQ are installed in the same host: . tar -cvf XXX.YYY.ZZZ.tar \ /var/mqm/trace/*FMT \ /var/mqm/errors/* \ /var/mqm/qmgrs/<qMgr>/errors/* \ <WAS_HOME>\profiles\<profile_name>\logs\<server_name>\* If MQ and the WebSphere Application Server are not located in the same box, then create one tar file for the MQ files and another for the WebSphere Application Server files. Ensure to have different file names for the tar files, such as XXX.mq.tar and XXX.was.tar - Compress the file (resulting in *.tar.Z) compress XXX.YYY.ZZZ.tar or use gzip (resulting in *.tar.gz) gzip XXX.YYY.ZZZ.tar - Send the file via ftp to us: 1. ftp ftp.emea.ibm.com 2. Login as user: anonymous For password: enter your email ID.
Page 53 of 74
3. Specify to transfer the file in binary mode: binary 4. Change directory to /toibm/unix: cd /toibm/unix 5. Put the file: put XXX.YYY.ZZZ.tar.Z 6. Exit the ftp utility by entering this command: Quit
Page 54 of 74
2) MQ V7 runmqras tool MQ V7 introduces a tool to collect the MQ data that is most frequently requested by MQ Support. Advantage: - It collects most of the main and secondary files for MQ, including runtime data. Disadvantages: - As of MQ 7.0.1.0, it does not capture the trace files though. - It does not collect WebSphere Application Server data. The command can be run as follows: runmqras.cmd -inputfile c:\isa.xml -zipfile c:\temp\isa.zip -workdirectory c:\tmp Fortunately, there is a simpler usage of the tool (no parameters):
runmqras
It uses the following defaults: Windows: -inputfile “%MQ_JAVA_DATA_PATH%\Config\isa.xml” -zipfile %TMP%\isa.zip -workdirectory %TMP%\work where %TMP% = %TEMP%/runmqras_yyyymmdd_hhmmss.ss UNIX: -inputfile “/var/mqm/config/isa.xml” -zipfile %TMP%/isa.zip -workdirectory %TMP%/work where %TMP% = /tmp/runmqras_yyyymmdd_hhmmss.ss Here is an example of how to run the tool and the data that is captured: $ runmqras java = found java version "1.5.0" Java(TM) 2 Runtime Environment, Standard Edition (build pxi32dev-20070511(SR5)) IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 Linux x86-32 j9vmxi3223-20070426 (JIT enabled) J9VM - 20070420_12448_lHdSMR JIT - 20070419_1806_r8
Page 55 of 74
GC - 200704_19) JCL - 20070511 /opt/java/bin/java -cp /opt/mqm/java/lib/com.ibm.mq.commonservices.jar:/opt/mqm/java/lib/com.ibm.mq.tools.ras.jar -Djava.library.path=/opt/mqm/lib:/opt/mqm/java/lib crtmqras.Zipper -inputfile /var/mqm/config/isa.xml -workdirectory /tmp/runmqras_20100104_134718/work -zipfile /tmp/runmqras_20100104_134718/isa.jar crtmqras v1.15 starts... crtmqras has successfully finished zip file can be found at /tmp/runmqras_20100104_134718/isa.jar $ cd /tmp/runmqras_20100104_134718 $ ls isa.jar work $ jar -xvf isa.jar inflated: var/mqm/mqs.ini inflated: var/mqm/errors/AMQ24820.0.FDC inflated: var/mqm/errors/AMQ24731.0.FDC inflated: var/mqm/errors/AMQ21472.0.FDC inflated: var/mqm/errors/AMQ21006.0.FDC inflated: var/mqm/errors/AMQ20796.0.FDC inflated: var/mqm/errors/AMQERR01.LOG inflated: var/mqm/errors/AMQERR02.LOG inflated: var/mqm/errors/AMQERR03.LOG inflated: var/mqm/errors/dynamic_file.inventory inflated: var/mqm/qmgrs/QM_VER/qm.ini inflated: var/mqm/qmgrs/QM_VER/qmstatus.ini inflated: var/mqm/qmgrs/QM_VER/errors/AMQERR01.LOG inflated: var/mqm/qmgrs/QM_VER/errors/AMQERR02.LOG inflated: var/mqm/qmgrs/QM_VER/errors/AMQERR03.LOG inflated: tmp/runmqras_20100104_134718/work/env.output inflated: tmp/runmqras_20100104_134718/work/ipcsa.output inflated: tmp/runmqras_20100104_134718/work/ipcsu.output inflated: tmp/runmqras_20100104_134718/work/dspmq.output inflated: tmp/runmqras_20100104_134718/work/ipcsc.output inflated: tmp/runmqras_20100104_134718/work/console.log inflated: tmp/runmqras_20100104_134718/work/runmqsc_1_QM_VER.output inflated: tmp/runmqras_20100104_134718/work/ipcst.output inflated: tmp/runmqras_20100104_134718/work/runmqsc_2_QM_VER.output inflated: tmp/runmqras_20100104_134718/work/ipcsl.output inflated: tmp/runmqras_20100104_134718/work/dspmqver.output inflated: tmp/runmqras_20100104_134718/work/ps.output
Page 56 of 74
3) WebSphere Application Server Collector tool Advantages: - It collects all the files that the WebSphere Application Server Support team needs. Disadvantages: - It does not collect the MQ traces. - It is deprecated in WebSphere Application Server. It is not being enhanced. This is the main web page for troubleshooting JMS problems in WebSphere Application Server: http://www.ibm.com/support/docview.wss?uid=swg21230514 Java Message Service (JMS) problems for versions 5.0, 5.1, and 6.0 The above web page has a link to: http://www.ibm.com/support/docview.wss?uid=swg21153217 MustGather: JMS problems for WebSphere Application Server V5.0, V5.1, and V6.0 releases This MustGather references the Collector Tool: Run the WebSphere Application Server collector tool to produce a jar file containing your WebSphere configuration files and other logs that are useful to the WebSphere Application Server support team. http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1//topic/com.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 5.1 InfoCenter Running the collector tool http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 6.1 InfoCenter Gathering information with the collector tool http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server V7: Gathering information with the collector tool (deprecated) The collector tool is available at: Unix: app_server_root/bin/collector.sh Windows:
Page 57 of 74
app_server_root \bin\collector.bat Short example of using the collector tool in Linux in WebSphere Application Server V7: 1. Log on to the system as root. 2. Make a working directory where you can start the collector program. mkdir /tmp/tmp-was 3. Make the working directory the current directory. cd /tmp/tmp-was 4. Run the collector program by entering the fully qualified command from the command line of the working directory. /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/collector.sh -profileName AppSrv01
5. The result of the collector tool is a jar file with a very long name: veracruz-veracruzNode01Cell-veracruzNode01-AppSrv01-WASenv.jar 6. To expand the jar file issue: jar –xvf veracruz-veracruzNode01Cell-veracruzNode01-AppSrv01-WASenv.jar
Some of the files provided by the collector tool are (local relative paths): ./hostname/root/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/SystemOut.log ./hostname/root/var/mqm/errors/AMQERR01.LOG ./hostname/root/var/mqm/errors/AMQERR02.LOG ./hostname/root/var/mqm/errors/AMQ24731.0.FDC If requested by IBM Support, you can send the jar file via ftp, as described in “1) Manual gathering”
Page 58 of 74
4) ISA tool for WebSphere Application Server Advantages: - It collects all the files that the WebSphere Application Server Support team needs. - It supersedes the Collector tool. It is supported by WebSphere Application Server. Disadvantages: - It does not collect any of the MQ files. - It requires a long interaction to provide the input data on what to collect. Visit the main web page for http://www.ibm.com/software/support/isa/ IBM Support Assistant You can also download a reduced version of ISA, called ISA Lite. The one for the WebSphere Application Server is: http://www.ibm.com/support/docview.wss?uid=swg24020502 Download IBM Support Assistant (ISA) Lite for WebSphere Application Server v6.x You need to review the readme.txt file to find out the pre-requisites for the tool and how to invoke it. The following example shows how to execute in Linux, the script for the collector tool via command prompt (non GUI). - Change to the directory where the ISALite installation file was downloaded and expanded. - Then change to the subdirectory: ISALite - Execute the script:
./runISALiteConsole.sh - Interact with the prompts.
Page 59 of 74
+++ Useful commands to navigate thru the large number of directories One drawback of using the Collector tool or ISA is that the gathered files are included in directory structure that could be rather cumbersome to navigate. This section describes some useful commands and scripts: a) How to find a specific file (FILENAME) Windows:
dir /s FILENAME Where: /s Searches for matching files in the current directory and all subdirectories. Unix:
find . -name FILENAME –print
Unix Script: findfile FILENAME The script “findfile” is a wrapper to the “find” command shown above. < begin script findfile> #!/usr/bin/ksh #---------------------------------------------------------------------+ # NAME: findfile path filename # # DESCRIPTION: # This shell script is a global find file command. # This shell script invokes the find command to perform a recursive # search in the directories. # #---------------------------------------------------------------------+ # # Invoke findfile USAGE="findfile filename" if [ "$#" -eq 1 ] then echo "findfile: searching in current directory tree for file: $1" find . -name $1 -print else echo "findfile: Usage is = $USAGE" fi # #-------- the end -------------------------------------------------- < end script >
Page 60 of 74
b) How to find the files that contain a specific STRING Windows:
findstr /s /i STRING fileSpecification Where: /s Searches for matching files in the current directory and all subdirectories. /i Specifies that the search is not to be case-sensitive. fileSpecification Similar to the file specification for “dir” For example: findstr /s /i MQJMS2005 *.log Unix: Case insensitive:
find . -type f -exec grep -li "STRING" {} \; Case sensitive:
find . -type f -exec grep -l "STRING" {} \;
Unix script: Case sensitive:
findstr –i STRING Case sensitive:
findstr STRING The script “findstr” is a wrapper to the “find” commands shown above. < begin script findstr> #!/usr/bin/ksh #---------------------------------------------------------------------+ # NAME: findstr string # # DESCRIPTION: # This shell script is a global find-string command. # # This shell script invokes the 'find' command to perform a recursive # search in the directories. The find command uses # the grep command to search for the actual string (case sensitive) # # The argument "-l" for grep is to list only the file names that # have a match, but do not include the match lines. # #---------------------------------------------------------------------+ # # Invoke findstr USAGE="findstr [-i] string \n where -i is for case insensitive searches" if [ "$#" -eq 0 ] then
Page 61 of 74
echo "findstr: Usage is = $USAGE" exit 1 else if [ "$1" = '-i' ] then echo "findstr: searching for case insensitive string: $2" find . -type f -exec grep -li "$2" {} \; exit 0 else echo "findstr: searching for actual string: $1" find . -type f -exec grep -l "$1" {} \; exit 0 fi fi # #-------- the end --------------------------------------------------+ < end script > +++ Other useful commands and tools a) To do a quick scan on the SystemOut.log, the following command shows all the Error messages. There are some false positives, but it is still useful: grep -e '[A-Z][^ [:space:]].*E:' SystemOut.log The following variation is to show the Warning messages: grep -e '[A-Z][^ [:space:]].*W:' SystemOut.log b) Simple script to quickly navigate to the directory with the WebSphere Application Server logs: < begin script > # Name: . cd-was # Purpose: to change directory to the logs of the WebSphere Application Server app server1 echo "Remember to invoke it as: . cd-was" echo "Changing directory to the WebSphere Application Server server1 logs" cd /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1 pwd < end of script >
Page 62 of 74
c) For reviewing the WebSphere Application Server trace.log files, the trace analyzer is really a nice tool. http://alphaworks.ibm.com/tech/ta4was IBM AlphaWorks: Trace Analyzer for WebSphere Application Server d) Other tools are: http://www.alphaworks.ibm.com/tech/jca?Open&ca=dnb-srr032008 IBM Thread and Monitor Dump Analyzer for Java For Javacore files only (no heapdumps) http://www.alphaworks.ibm.com/tech/heapanalyzer IBM Heap Analyzer (to analyze Java heap dumps) Searching the IBM Support site for keywords found in the trace or SystemOut.log After reviewing the SystemOut.log file and/or the trace.log file, you may want to search the IBM Support site for applicable technotes or APARs (fixes for reported problems) regarding the keywords for the error numbers, method names, etc. http://www.ibm.com/software/integration/wmq/support/ IBM WebSphere MQ Support site http://www.ibm.com/software/webservers/appserv/was/support/ IBM WebSphere Application Server Support site http://www.ibm.com/support/docview.wss?uid=swg21289029 WebSphere MQ JMS exception messages (Version 6) Consulting the online Information Centers and Redbooks http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp WebSphere MQ V6 Information Center http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp WebSphere MQ V7 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp WebSphere Application Server V6.1 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp
Page 63 of 74
WebSphere Application Server V7 Information Center http://www.redbooks.ibm.com/abstracts/redp4330.html?Open WebSphere Application Server V6.1: JMS Problem Determination Chapter 10. WebSphere MQ and MDBs Chapter 11. WebSphere MQ server problem determination Chapter 14. JMS application with WebSphere MQ problem determination
Page 64 of 74
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Chapter 6: Miscellaneous questions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Question 1: Is it possible to force an MQ V7 JMS client (used by WebSphere Application Server) to behave as an MQ V6 JMS client when talking to an MQ V7 Queue Manager? Answer 1: Yes, it is possible: set the server-connection channel from the queue manager to have the SHARECNV attribute a value of 0. This will disable the full-duplex and the multiplexing features, forcing the channel to behave as an MQ V6 one, which in turn, will force the MQ V7 client to choose the "migration" (MQ V6 leg) path of the code. See also Question 2 below. Question 2: Is PROVIDERVERSION a way to force a V7 client to use V6 migration mode if desired? Answer 2: Yes. Setting it to "6" results in the client using v6 migration mode, independent of the transport type (client or bindings). It can also be set to "7" which can be useful if you are trying to use V7 mode in some configurations; for further detail consult: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm41150_.htm WebSphere MQ V7 > Using Java >> When to use PROVIDERVERSION Question 3: Is it possible to use the MQ Explorer GUI or the MQ JMSAdmin tool to administer the JNDI objects stored in the WebSphere Application Server? Answer 3: No. The MQ Explorer GUI and the MQ JMSAdmin tool can only administer JNDI objects stored in a File System context (a file with the name: .bindings) or in LDAP.
Page 65 of 74
Question 4: Can Activation Specifications be used with the Application Server Facility (ASF)? Answer 4: - ASF and non-ASF are only used by Listener Ports from the WebSphere Application Server. - When using Activation Specs, WebSphere Application Server V7 settings of ASF vs non-ASF mode have no effect if target QMgr is also at V7. Internally the JMS client will always use the above new style of delivery with Activation Specs (new V7 using MQ MQCB / MQCTL APIs) - When using Activation Specs, WebSphere Application Server V7 settings of ASF vs non-ASF mode behave like in WebSphere Application Server V6 if the target QMgr is at V6. - When running with a WebSphere Application Server V7 listener port in ASF mode, it will also use the above new V7 style of delivery, if target QMgr is also at V7. - When running with a WebSphere Application Server V7 listener port in non-ASF mode, the V6 non-ASF style of delivery is maintained. Notes: - The V7 client uses the new MQ API calls MQCB/MQCTL to register a callback with the queue manager. This means that the queue manager is responsible for the detection and notification of messages to the client. - In the V7 API, the callback function uses marks to hide messages, and always picks the first available message. Question 5: When do MQ V7 JMS applications need to be compiled with explicit settings in the CLASSPATH? Answer 5: In MQ V7 a new JMQI library was introduced (com.ibm.mq.jmqi.jar) as a native interface (vs an emulated interface as in V6) to the MQI interface. Thus, to compile JMS applications with Java 1.5 & 1.6 it is not required to explicitly indicate the jmqi libraries in the CLASSPATH. However, to compile JMS applications with Java 1.4.2 it is required to explicitly indicate the jmqi libraries in the CLASSPATH. This is due to improvements added in Java 1.5 in the handling of dependencies of jar files.
Page 66 of 74
Question 6: Is it necessary to use MQ CLASSPATH settings for the WebSphere Application Server V7 at runtime? Answer 6: No. WebSphere Application Server V7 does not require any MQ CLASSPATH settings at runtime. The MQ classes are loaded from the WebSphere Application Server libraries using the RA mechanism rather than the mechanism for the class loaders. Question 7: In the WebSphere Application Console V7, the default transport type for connection factories is “Bindings, then Client”. When should it be used? The other types are “Client” and “Bindings”. Answer 7: The “Bindings, then Client” type can be used with WebSphere Application Servers clusters when all the application servers share the same MQ queue manager (a good configuration). In this case, it is fine to run the MQ queue manager in the same machine as one of the application servers. By setting “Bindings, then Client”, you allow the application server collocated with the queue manager to use the “Bindings” type and all other application servers in the cluster to use the “Client” type. Question 8: What happens to the MQ_INSTALL_ROOT during the upgrade of WebSphere Application Server V6 to V7? Answer 8: When a WebSphere Application Server installation is migrated from V6 to V7, the MQ_INSTALL_ROOT environment variable is not migrated across. This means the variable will be blank (or undefined) in the V7 environment. The reason is that customers could have been using this variable to point to a MQ v5.3 queue manager installation on WebSphere Application Server V6, which would be an invalid configuration in V7. The only usage of MQ_INSTALL_ROOT in V7 is to locate the native library for BINDINGS mode communication with MQ, in the case that the MQ code is installed in a non-default location in Windows (this is not applicable in Unix). This variable is overridden by any native library path configured on the Resource Adapter.
Page 67 of 74
The default value for the MQ_INSTALL_ROOT in WAS v7 would be the location where the RA is present, so, if you want to define MQ_INSTALL_ROOT, then it can be set to:
${WAS_INSTALL_ROOT}/lib/WMQ The MQ Resource Adapter supplied with WebSphere Application Server v7 is always the source of the WMQ JMS client code, irrespective of where MQ_INSTALL_ROOT points to. When specifying a transport type of Bindings, then you will need to specify also the native libraries for MQ. See Chapter 4 in this techdoc for more details. For more information, consult: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.soafep.multiplatform.doc/info/ae/ae/tmj_adm33.html WebSphere Application Server Version 7.0.x, Information Center Configuring the WebSphere MQ messaging provider with native libraries information Question 9: Is it OK to use a non-WebSphere Application Server application to access the JNDI objects from WebSphere Application Server? The reason for this question is to avoid duplication of administered JMS objects both in a WebSphere Application Server JNDI repository and a File System or LDAP JNDI repository used by MQ applications. Answer 9: It is not recommended that a WebSphere Application Server V6 JNDI repository is accessed via a non-WebSphere Application Server application, unless using the WebSphere Application Server Application Client. The primary reason is because many WebSphere Application Server jars would be required to be added to the CLASSPATH in order to get this functionality. Instead, it is possible to set up an external JNDI repository using the standard JMSAdmin method (via File System or LDAP), and have WebSphere Application Server access this external JNDI repository through the "Generic JMS Provider Interface". WebSphere Application Server V7 provides a "thin client" which can be used to allow an external WMQ JMS application access to the JNDI repository. This permits use of the WebSphere Application Server JNDI repository for both the WMQ and WebSphere Application Server applications. More information, consult the following: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.pmc.soafep.multiplatform.doc/tasks/tjj_jmsthcli_wmq.html WebSphere Application Server Version 7.0.x, Information Center
Page 68 of 74
Obtaining WebSphere MQ JMS resources in the thin client environment Question 10: Does the migration from WebSphere Application Server V6 to V7 keep the following 3 jar files, even though they are not going to be used? WebSphere Application Server V6 ships 3 MQ jar files that are located at: AIX: /usr/IBM/WebSphere/AppServer/lib/WMQ com.ibm.mqjms.jar com.ibm.mq.jar dhbcore.jar WebSphere Application Server V7 does not ship these individual jar files anymore, rather, the MQ Resource Adapter (RA) is shipped at: AIX: /usr/IBM/WebSphere/AppServer/lib/WMQ/ra/wmq.jmsra.rar WebSphere Application Server V7 does not use directly the above jar files. Answer 10: No, the migration from WebSphere Application Server V6 to V7 does not migrate or copy any .jar files from the mentioned /lib/WMQ directory. Question 11: Why is the MQ bindings library not included with the Resource Adapter? Answer 11: The native library components, such as libmqjbnd.so/mqjbnd.dll are considered a component of the queue manager, and are tested to ensure compatibility with the queue manager they are supplied with. By not shipping the native library with the resource adapter, this allows for the correct version of the MQ bindings library to be available for the queue manager in use. For example, if WebSphere Application Server 7 is installed on the same server as MQ 6.0.2.5 or later, the queue manager supplied version of the MQ bindings library is used, which ensures compatibility with the queue manager. Question 12: What does the migration of Listener Ports to Activation Specs migrate? Are Listener Port properties migrated to the Activation Spec, such as maximum sessions? What about custom properties, or properties that would be set at the Resource Adapter. Answer 12: The migration from a Listener Port to an Activation Specification only migrates the MQ connection details (queue manager name, connection type, hostname, etc.) as well as the Listener Port Maximum Sessions property.
Page 69 of 74
Other properties either have no direct equivalent, such as "Maximum retries", as per: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.express.doc/info/exp/ae/tmj_adm32.html WebSphere Application Server 7 Information Center Migrating a listener port to an activation specification for use with the WebSphere MQ messaging provider Or, are configured at the Resource Adapter level, and so affect all Activation Specifications and need to be configured manually, such as the reconnection parameters. Question 13: How is MARK_BROWSE used with MDBs in MQ V7 and V6? Answer 13: The mark function is only used with the V7 style connections for ASF mode connections. Therefore, a V7 style Listener Port in ASF mode, and V7 style Activation Specifications use a browse with mark. V6 style connections, and all non-ASF modes do not use browse with mark. For the browse with mark mode to operate efficiently, all applications reading messages from a queue need to use browse with mark. Also, z/OS V6 queue managers support browse with mark, which is used by the MQ V6 JMS client where possible. Note: The assumption is that message delivery is referring to the delivery of messages to MDBs, and not synchronous message delivery within servlets and non-MDB EJBs.
Page 70 of 74
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Appendix A: Listing of all web pages mentioned in this techdoc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ Technotes and techdocs http://www.ibm.com/support/docview.wss?uid=swg21307203 Information about using WebSphere MQ as the JMS Provider for WebSphere Application Server 6.1 http://www.ibm.com/support/docview.wss?uid=swg21316899 Information about using the WebSphere MQ messaging provider for WebSphere Application Server Version 7.0 http://www.ibm.com/support/docview.wss?uid=swg27016505 Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7 http://www.ibm.com/support/docview.wss?uid=swg27017733 Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V6 http://www.ibm.com/support/docview.wss?uid=swg27018556 Quick Guide of the Administrative Console from WebSphere Application Server for WebSphere MQ users http://www.ibm.com/support/docview.wss?uid=swg27016581 Using an MDB with JMS message selectors with WebSphere MQ V7 and WebSphere Application Server V7 Includes sample code to create a message property "color" SampleJMSMsgProperty.java http://www.ibm.com/support/docview.wss?uid=swg27016582 Using an MDB that always rolls back a message to test the handling of poison messages (WebSphere MQ V7, WebSphere Application Server V7) http://www.ibm.com/support/docview.wss?uid=swg21248089 Which version of MQ is shipped with WebSphere Application Server http://www.ibm.com/support/docview.wss?uid=swg24019253 MQC7: WebSphere MQ V7.0 Clients http://www.ibm.com/support/docview.wss?uid=swg24009961 MQC6: WebSphere MQ V6.0 Clients http://www.ibm.com/support/docview.wss?uid=swg21413508 AMQ8568 mqjbnd=CC=2 RC=2495 when issuing "dspmqver -p 4"
Page 71 of 74
http://www.ibm.com/support/docview.wss?uid=swg27016595 WSTE: Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7 http://www.ibm.com/support/docview.wss?uid=swg21199176 Enabling JMS trace for releases of WebSphere Application Server V5.1, V6.0, V6.1, and V7.0 http://www.ibm.com/support/docview.wss?uid=swg21230514 Java Message Service (JMS) problems for versions 5.0, 5.1, and 6.0 http://www.ibm.com/support/docview.wss?uid=swg21153217 MustGather: JMS problems for WebSphere Application Server V5.0, V5.1, and V6.0 releases http://www.ibm.com/support/docview.wss?uid=swg21289029 WebSphere MQ JMS exception messages (Version 6) http://www.ibm.com/support/docview.wss?uid=swg21174924 MustGather: Directions to start, end, and format trace http://www.ibm.com/support/docview.wss?uid=swg27016507 Developing and testing an MDB using RAD 7.5, WebSphere Application Server V7 and MQ V7 as JMS Provider http://www.ibm.com/support/docview.wss?uid=swg24020502 Download IBM Support Assistant (ISA) Lite for WebSphere Application Server v6.x http://www.ibm.com/support/docview.wss?uid=swg21248900 java.lang.UnsatisfiedLinkError received when connecting to a queue manager +++ Information Centers http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/tmj_instm.html WebSphere Application Server V7 Information Center Installing WebSphere MQ to interoperate with WebSphere Application Server V7 http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/tmj_adm33.html WebSphere Application Server V7 Information Center Configuring the WebSphere MQ messaging provider with native libraries information
Page 72 of 74
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/tmm_mig.html WebSphere Application Server V7 Information Center FixPack 1: Adjusting the WebSphere MQ resource adapter configuration when migrating profiles between maintenance level 7.0.0.0 and later levels http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.soafep.multiplatform.doc/info/ae/ae/tmj_adm33.html WebSphere Application Server V7 Information Center Configuring the WebSphere MQ messaging provider with native libraries information http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.pmc.soafep.multiplatform.doc/tasks/tjj_jmsthcli_wmq.html WebSphere Application Server V7 Information Center Obtaining WebSphere MQ JMS resources in the thin client environment http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.installation.base.doc/info/aes/ae/cins_updi_installationoverview.html WebSphere Application Server V7 Information Center Installing maintenance packages overview http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.installation.base.doc/info/aes/ae/tins_ptfLevels.html WebSphere Application Server V7 Information Center Installing maintenance packages, interim fixes, fix packs, and refresh packs http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/tmj_instm.html WebSphere Application Server V6 Information Center Installing WebSphere MQ to interoperate with WebSphere Application Server V6 http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1//topic/com.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 5.1 Information Center Running the collector tool http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 6.1 Information Center Gathering information with the collector tool http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html
Page 73 of 74
WebSphere Application Server V7: Gathering information with the collector tool (deprecated) http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm10340_.htm WebSphere MQ Version 7 "Using Java" manual "The Java Native Interface (JNI) libraries required by WebSphere MQ classes for JMS applications" http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/uj24500_.htm MQ V6 Information Center > Writing WebSphere MQ JMS applications >> Handling errors http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm35210_.htm MQ V6 Information Center > Writing WebSphere MQ JMS applications >> Exceptions in WebSphere MQ classes for JMS http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm41150_.htm WebSphere MQ V7 > Using Java >> When to use PROVIDERVERSION +++ Other http://www.ibm.com/software/integration/wmq/support/ IBM WebSphere MQ Support site http://www.ibm.com/software/webservers/appserv/was/support/ IBM WebSphere Application Server Support site http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp WebSphere MQ V6 Information Center http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp WebSphere MQ V7 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp WebSphere Application Server V6.1 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp WebSphere Application Server V7 Information Center
Page 74 of 74
http://www.ibm.com/software/websphere/support/lifecycle/index.html IBM Support - Lifecycle Individual End of Support (EOS) dates for WebSphere MQ and WebSphere Application Server: http://www.redbooks.ibm.com/abstracts/SG247583.html?Open WebSphere MQ V7.0 Features and Enhancements (SG24-7583) http://www.redbooks.ibm.com/abstracts/redp4330.html?Open WebSphere Application Server V6.1: JMS Problem Determination Chapter 10. WebSphere MQ and MDBs Chapter 11. WebSphere MQ server problem determination Chapter 14. JMS application with WebSphere MQ problem determination http://www.ibm.com/developerworks/websphere/techjournal/0901_leming/0901_leming.html Using the WebSphere MQ messaging provider in WebSphere Application Server V7: Part 1: Introducing the new WebSphere MQ messaging provider http://www.ibm.com/software/support/isa/ IBM Support Assistant This is the end of the techdoc. +++ end +++
