The point-to-point installation verification test for IBM MQ classes for JMS

A point-to-point installation verification test (IVT) program is supplied with IBM® MQ classes for JMS. The program connects to a queue manager in either bindings or client mode, sends a message to the queue called SYSTEM.DEFAULT.LOCAL.QUEUE, and then receives the message from the queue. The program can create and configure all the objects that it requires dynamically at run time, or it can use JNDI to retrieve administered objects from a directory service.

Run the installation verification test without using JNDI first because the test is self contained and does not require the use of a directory service. For a description of administered objects, see Configuring JMS objects using the administration tool.

The point-to-point installation verification test without using JNDI

In this test, the IVT program creates and configures all the objects that it requires dynamically at run time and does not use JNDI.

A script is provided to run the IVT program. The script is called IVTRun on UNIX and Linux® systems and IVTRun.bat on Windows, and is in the bin subdirectory of the IBM MQ classes for JMS installation directory.

To run the test in bindings mode, enter the following command:


IVTRun -nojndi [-m qmgr ] [-v providerVersion ] [-t]

To run the test in client mode, first set up the queue manager as described in Preparing and running the sample programs, where the channel to be used defaults to SYSTEM.DEF.SVRCONN and the queue to be used is SYSTEM.DEFAULT.LOCAL.QUEUE, then enter the following command:


IVTRun -nojndi -client -m qmgr -host hostname [-port port ] [-channel channel ]
[-v providerVersion ] [-ccsid ccsid ] [-t]

No equivalent script is provided on z/OS® systems, but you can run the IVT in bindings mode by invoking the Java class directly, using the following command:


java com.ibm.mq.jms.MQJMSIVT -nojndi [-m qmgr ] [-v providerVersion ] [-t]

The classpath must contain com.ibm.mqjms.jar.

The parameters on the commands have the following meanings:

-m qmgr

The name of the queue manager to which the IVT program connects. If you run the test in bindings mode and omit this parameter, the IVT program connects to the default queue manager.

-host hostname

The host name or IP address of the system on which the queue manager is running.

-port port

The number of the port on which the listener of the queue manager is listening. The default value is 1414.

-channel channel

The name of the MQI channel that the IVT program uses to connect to the queue manager. The default value is SYSTEM.DEF.SVRCONN.

-v providerVersion

The release level of the queue manager to which the IVT program expects to connect.

This parameter is used to set the PROVIDERVERSION property of an MQQueueConnectionFactory object and has the same valid values as those of the PROVIDERVERSION property. For more information about this parameter therefore, including its valid values, see JMS PROVIDERVERSION property and the description of the PROVIDERVERSION property in Properties of IBM MQ classes for JMS objects.

The default value is unspecified.

-ccsid ccsid

The identifier (CCSID) of the coded character set, or code page, to be used by the connection. The default value is 819.

-t

Tracing is switched on. By default, tracing is switched off.

A successful test produces output similar to the following sample output:

5724-H72, 5655-R36, 5724-L26, 5655-L82 (c) Copyright IBM Corp. 2008, 2024. All Rights Reserved.
Websphere MQ classes for Java(tm) Message Service 7.0
Installation Verification Test

Creating a QueueConnectionFactory
Creating a Connection
Creating a Session
Creating a Queue
Creating a QueueSender
Creating a QueueReceiver
Creating a TextMessage
Sending the message to SYSTEM.DEFAULT.LOCAL.QUEUE
Reading the message back again

Got message
JMSMessage class: jms_text
JMSType:     null
JMSDeliveryMode: 2
JMSExpiration:  0
JMSPriority:   4
JMSMessageID:   ID:414d5120514d5f6d627720202020202001edb14620005e03
JMSTimestamp:   1187170264000
JMSCorrelationID: null
JMSDestination:  queue:///SYSTEM.DEFAULT.LOCAL.QUEUE
JMSReplyTo:    null
JMSRedelivered:  false
JMSXUserID: mwhite
JMS_IBM_Encoding: 273
JMS_IBM_PutApplType: 28
JMSXAppID: IBM MQ Client for Java
JMSXDeliveryCount: 1
JMS_IBM_PutDate: 20070815
JMS_IBM_PutTime: 09310400
JMS_IBM_Format: MQSTR
JMS_IBM_MsgType: 8
A simple text message from the MQJMSIVT
Reply string equals original string
Closing QueueReceiver
Closing QueueSender
Closing Session
Closing Connection
IVT completed OK
IVT finished

The point-to-point installation verification test using JNDI

In this test, the IVT program uses JNDI to retrieve administered objects from a directory service.

Before you can run the test, you must configure a directory service that is based on a Lightweight Directory Access Protocol (LDAP) server or the local file system. You must also configure the IBM MQ JMS administration tool so that it can use the directory service to store administered objects. For more information about these prerequisites, see Prerequisites for IBM MQ classes for JMS. For information about how to configure the IBM MQ JMS administration tool, see Configuring the JMS administration tool.

The IVT program must be able to use JNDI to retrieve an MQQueueConnectionFactory object and an MQQueue object from the directory service. A script is provided to create these administered objects for you. The script is called IVTSetup on UNIX and Linux systems and IVTSetup.bat on Windows, and is in the bin subdirectory of the IBM MQ classes for JMS installation directory. To run the script, enter the following command:


IVTSetup

The script invokes the IBM MQ JMS administration tool to create the administered objects.

The MQQueueConnectionFactory object is bound with the name ivtQCF and is created with the default values for all its properties, which means that the IVT program runs in bindings mode and connects to the default queue manager. If you want the IVT program to run in client mode, or connect to a queue manager other than the default queue manager, you must use the IBM MQ JMS administration tool or MQ Explorer to change the appropriate properties of the MQQueueConnectionFactory object. For information about how to use the MQ Explorer JMS administration tool, see Configuring JMS objects using the administration tool. For information about how to use MQ Explorer, see Introduction to MQ Explorer or the help provided with MQ Explorer.

The MQQueue object is bound with the name ivtQ and is created with the default values for all its properties, except for the QUEUE property, which has the value SYSTEM.DEFAULT.LOCAL.QUEUE.

When you have created the administered objects, you can run the IVT program. To run the test using JNDI, enter the following command:


IVTRun -url "providerURL" [-icf initCtxFact ] [-t]

The parameters on the command have the following meanings:

-url "providerURL"

The uniform resource locator (URL) of the directory service. The URL can have one of the following formats:

ldap://hostname/contextName , for a directory service based on an LDAP server
file:/directoryPath , for a directory service based on the local file system

Note that you must enclose the URL in quotation marks (").

-icf initCtxFact

The class name of the initial context factory, which must be one of the following values:

com.sun.jndi.ldap.LdapCtxFactory, for a directory service based on an LDAP server. This is the default value.
com.sun.jndi.fscontext.RefFSContextFactory, for a directory service based on the local file system.

-t

Tracing is switched on. By default, tracing is switched off.

A successful test produces output similar to that for a successful test without using JNDI. The main difference is that the output indicates that the test is using JNDI to retrieve an MQQueueConnectionFactory object and an MQQueue object.

Although not strictly necessary, it is good practice to tidy up after the test by deleting the administered objects created by the IVTSetup script. A script is provided for this purpose. The script is called IVTTidy on UNIX and Linux systems and IVTTidy.bat on Windows, and is in the bin subdirectory of the IBM MQ classes for JMS installation directory.

Problem determination for the point-to-point installation verification test

The installation verification test might fail for the following reasons:

If the IVT program writes a message indicating that it cannot find a class, check that your class path is set correctly, as described in Environment variables used by IBM MQ classes for JMS.
The test might fail with the following message:
```
Failed to connect to queue manager ' qmgr ' with connection mode ' connMode '
and host name ' hostname '
```
and an associated reason code of 2059. The variables in the message have the following meanings:

qmgr

The name of the queue manager to which the IVT program is trying to connect. This message insert is blank if the IVT program is trying to connect to the default queue manager in bindings mode.

connMode

The connection mode, which is either Bindings or Client.

hostname

The host name or IP address of the system on which the queue manager is running.

This message means that the queue manager to which the IVT program is trying to connect is not available. Check that the queue manager is running and, if the IVT program is trying to connect to the default queue manager, make sure that the queue manager is defined as the default queue manager for your system.
The test might fail with the following message:
```
Failed to open MQ queue 'SYSTEM.DEFAULT.LOCAL.QUEUE'
```
This message means that the queue SYSTEM.DEFAULT.LOCAL.QUEUE does not exist on the queue manager to which the IVT program is connected. Alternatively, if the queue does exist, the IVT program cannot open the queue because it is not enabled for putting and getting messages. Check that the queue exists and that it is enabled for putting and getting messages.
The test might fail with the following message:
```
Unable to bind to object
```
This message means that there is a connection to the LDAP server, but that the LDAP server is not correctly configured. Either the LDAP server is not configured for storing Java objects, or the permissions on the objects or the suffix are not correct. For more help in this situation, see the documentation for your LDAP server.
The test might fail with the following message:
```
The security authentication was not valid that was supplied for
QueueManager ' qmgr ' with connection mode 'Client' and host name ' hostname '
```
This message means that the queue manager is not correctly set up to accept a client connection from your system. See Preparing and running the sample programs for details.