Sei sulla pagina 1di 74

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

Date last updated: 19-Apr-2011

Angel Rivera rivera@us.ibm.com 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.

+++ Related articles +++

Page 2 of 74

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:

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:

Integration of WebSphere MQ classes for JMS with WebSphere Application Server

htm

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

Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7

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.

Developing and testing an MDB using RAD 7.5, WebSphere Application Server V7 and MQ V7 as JMS Provider

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

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:

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.

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

WebSphere MQ

Implementation Version, shown in WMSG1703I log entry during server startup

Application Sever

JCA resource

Version

adapter Version

 
   
   

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.

MQC7: WebSphere MQ V7.0 Clients

MQC6: WebSphere MQ V6.0 Clients

Page 9 of 74

WebSphere Application Server 6.0 and 6.1:

Consult the following technotes:

Information about using WebSphere MQ as the JMS Provider for WebSphere Application Server 6.0

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:

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:

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

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 For Other Unix:

/usr/mqm

MQ_INSTALL_ROOT For Windows:

/opt/mqm

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

MQC7: WebSphere MQ V7.0 Clients

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

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.

WMSG0017E: Unable

WMSG1625E: It was not possible to detect the WebSphere MQ messaging provider code at the specified path <null>

JMSRegistrati A

messaging provider is 7.0.0.0.

JMSRegistrati I

WMSG1611I: The installed level of the WebSphere MQ

WMSG1703I: RAR implementation version 7.0.0.0-k700-L080820

Consult the following web page:

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

Version: 6.0.2.2 CMVC Level: j600-202-070711 Build Type: Production

WebSphere MQ classes for Java Message Service

Example of the partial output for 7.0:

Name:

Version: 7.0.0.0 CMVC Level: k000-L080529

Build Type: Production

Java Message Service Client

Name:

Version: 7.0.0.0 CMVC Level: k000-L080529 Build Type: Production

WebSphere MQ classes for Java Message Service

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

cat MANIFEST.MF

Page 18 of 74

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

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:

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

ources.xml#J2CResourceAdapter_1229526439385)"\n"WebSphere MQ Resource

Adapter(cells/veracruzNode01Cell/nodes/veracruzNode01|resources.xml#J2CR

esourceAdapter_1229526438873)"\n"WebSphere MQ Resource

Adapter(cells/veracruzNode01Cell|resources.xml#J2CResourceAdapter_122952

6439609)"'

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

ources.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.\nWMSG1

711I: 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:

Version: 6.0.2.4 CMVC Level: j600-204-080509

Build Type: Production

WebSphere MQ classes for Java Message Service

MQ V7:

$ dspmqver -p 4

Name:

Version: 7.0.1.0 CMVC Level: k000-L090724

Build Type: Production

Java Message Service Client

Name:

Version: 7.0.1.0 CMVC Level: k000-L090724 Build Type: Production

WebSphere MQ classes for Java Message Service

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.

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:

Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7

As well as the following Redbook:

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

Read Ahead Resources > JMS > Queues > $QueueName/$TopicName > Advanced properties Section: Optimizations

Page 25 of 74

You will see the Advanced Properties:

Page 25 of 74 You will see the Advanced Properties: You will need to scroll down.

You will need to scroll down. Section: Optimizations

You will need to scroll down. Section: Optimizations Read ahead, and cache, non-persistent messages for consumers

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

See previous page for the "Advanced Properties". Asynchronously send messages to the queue manager As per

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:

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:

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:

Interim fixes: MQ jar files

WebSphere Application Server fix packs

From Version 6.1.0.19 to Version 6.1.0.28 (MQ 6.0.2.4)

Fix Packs:

Interim fixes: MQ jar files

MQ fix packs (MQ 6)

Page 29 of 74

Version 6.1.0.29 and later

Fix Packs:

Interim fixes: MQ jar files

WebSphere Application Server fix packs

WebSphere Application Server V7

Fix Packs:

Interim fixes: WebSphere Application Server .pak files

WebSphere Application Server fix packs

For applying the interim fixes for the MQ RA, see the following 2 web pages from the WebSphere Application Server V7 Information Center

.ibm.websphere.installation.base.doc/info/aes/ae/cins_updi_installationovervi ew.html WebSphere Application Server V7 Information Center Installing maintenance packages overview

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

Unix: /opt/mqm

Windows:

/usr/mqm

C:\Program Files\IBM\WebSphere MQ

B) The location of the MQ native libraries is:

AIX:

Linux 32-bit: only /opt/mqm/java/lib

/usr/mqm/java/lib and /usr/mqm/java/lib64

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:

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:

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

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

Listener SampleMDBTopicLP stopped for JMSDestination jms/SampleMDBTopic

[12/28/09 10:35:36:879 EST] 00000023 MDBListenerIm I

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_0000002

3_09.12.28_10.35.36_0.txt

WMSG0043I: MDB

WMSG0058I: Listener

The FDC files show: UnsatisfiedLinkError: mqjbnd05

Exception = java.lang.NoClassDefFoundError

Source = com.ibm.ejs.util.am

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)

Alarm.run

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:

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:

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

.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

on: WebSphere Variables Ensure to select the scope to: Node You will need to scroll down

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

down or go to the next page in the long list of variables, until you find:

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.

htm

From the WebSphere Application Server V6 Admin Console:

Click on Servers > Application Servers > server1.

Click on Servers > Application Servers > server1. You will need to scroll down and under

You will need to scroll down and under Server Infrastructure, click Java and Process Management > Process definition

need to scroll down and under “ Server Infrastructure ” , click Java and Process Management

Page 38 of 74

Then click Java and Process Management > Process definition

74 Then click Java and Process Management > Process definition Then select “ Java Virtu al

Then select “Java Virtual Machine”

74 Then click Java and Process Management > Process definition Then select “ Java Virtu al

You will see:

74 Then click Java and Process Management > Process definition Then select “ Java Virtu al

Page 39 of 74

Scroll down to find "Generic JVM arguments.

39 of 74 Scroll down to find "Generic JVM arguments. U nder “Generic JVM arguments”, enter:

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:

Linux 32-bit: only /opt/mqm/java/lib

/usr/mqm/java/lib and /usr/mqm/java/lib64

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:

Configuring the WebSphere MQ messaging provider with native libraries information

Configuring the WebSphere MQ messaging provider with native libraries information

Procedure:

Page 41 of 74

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

Writing WebSphere MQ JMS applications

htm

>

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:

Exceptions in WebSphere MQ classes for JMS

htm

"

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

MQ 7 Information Center > Using Java >> Exceptions in WebSphere MQ classes for JMS >>> Upgrading from previous versions of WebSphere MQ classes for JMS

htm

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

Review the MQ error logs

Page 48 of 74

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:

V6,V7 - Windows:

C:\Program Files\IBM\WebSphere MQ\errors 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.

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:Mes

saging=all=enabled:

WebSphere Application Server V6 and V7 (all in one line):

*=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.i

bm.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/AppS

erver/bin:/home/db2inst1/sqllib/lib:/usr/lib:/opt/mqm/java/lib:/opt/mqm/j

ava/lib64

Current trace specification = *=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:c om.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:

.

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

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

2) MQ V7 runmqras tool

Page 54 of 74

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

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

- 200704_19)

$ 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:

Java Message Service (JMS) problems for versions 5.0, 5.1, and 6.0

The above web page has a link to:

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.

sphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 5.1 InfoCenter Running the collector tool

.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 6.1 InfoCenter Gathering information with the collector tool

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

er1/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:

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.

Similar to the file specification for “dir” findstr /s /i MQJMS2005 *.log

fileSpecification For example:

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.

IBM AlphaWorks: Trace Analyzer for WebSphere Application Server

d) Other tools are:

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/webservers/appserv/was/support/ IBM WebSphere Application Server Support site

WebSphere MQ JMS exception messages (Version 6)

Consulting the online Information Centers and Redbooks

WebSphere MQ V6 Information Center

WebSphere MQ V7 Information Center

WebSphere Application Server V6.1 Information Center

Page 63 of 74

WebSphere Application Server V7 Information Center

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:

WebSphere MQ V7 > Using Java >> When to use PROVIDERVERSION

htm

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:

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:

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

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

Information about using WebSphere MQ as the JMS Provider for WebSphere Application Server 6.1

Information about using the WebSphere MQ messaging provider for WebSphere Application Server Version 7.0

Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7

Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V6

Quick Guide of the Administrative Console from WebSphere Application Server for WebSphere MQ users

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

Using an MDB that always rolls back a message to test the handling of poison messages (WebSphere MQ V7, WebSphere Application Server V7)

Which version of MQ is shipped with WebSphere Application Server

MQC7: WebSphere MQ V7.0 Clients

MQC6: WebSphere MQ V6.0 Clients

Page 71 of 74

WSTE: Using WebSphere MQ V7 as JMS Provider for WebSphere Application Server V7

Enabling JMS trace for releases of WebSphere Application Server V5.1, V6.0, V6.1, and V7.0

Java Message Service (JMS) problems for versions 5.0, 5.1, and 6.0

MustGather: JMS problems for WebSphere Application Server V5.0, V5.1, and V6.0 releases

WebSphere MQ JMS exception messages (Version 6)

MustGather: Directions to start, end, and format trace

Developing and testing an MDB using RAD 7.5, WebSphere Application Server V7 and MQ V7 as JMS Provider

Download IBM Support Assistant (ISA) Lite for WebSphere Application Server

v6.x

java.lang.UnsatisfiedLinkError received when connecting to a queue manager

+++ Information Centers

.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

WebSphere Application Server V7 Information Center Configuring the WebSphere MQ messaging provider with native libraries information

Page 72 of 74

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

WebSphere Application Server V7 Information Center Configuring the WebSphere MQ messaging provider with native libraries information

.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

.ibm.websphere.installation.base.doc/info/aes/ae/cins_updi_installationovervi ew.html WebSphere Application Server V7 Information Center Installing maintenance packages overview

.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

.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

sphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 5.1 Information Center Running the collector tool

.ibm.websphere.base.doc/info/aes/ae/ttrb_runct.html WebSphere Application Server 6.1 Information Center Gathering information with the collector tool

Page 73 of 74

WebSphere Application Server V7: Gathering information with the collector tool (deprecated)

WebSphere MQ Version 7 "Using Java" manual "The Java Native Interface (JNI) libraries required by WebSphere MQ classes for JMS applications"

htm

htm

MQ V6 Information Center

> Writing WebSphere MQ JMS applications >> Handling errors

htm

MQ V6 Information Center

> Writing WebSphere MQ JMS applications

>> Exceptions in WebSphere MQ classes for JMS

WebSphere MQ V7

> Using Java

>> When to use PROVIDERVERSION

htm

+++ Other

http://www.ibm.com/software/webservers/appserv/was/support/ IBM WebSphere Application Server Support site

WebSphere MQ V6 Information Center

WebSphere MQ V7 Information Center

WebSphere Application Server V6.1 Information Center

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:

WebSphere MQ V7.0 Features and Enhancements (SG24-7583)

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

Using the WebSphere MQ messaging provider in WebSphere Application Server

V7:

Part 1: Introducing the new WebSphere MQ messaging provider

This is the end of the techdoc.

+++ end +++