The publish/subscribe IVT for IBM MQ classes for JMS

A publish/subscribe 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, subscribes to a topic, publishes a message on the topic, and then receives the message that it has just published. 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 Configure JMS objects using the administration tool.


The publish/subscribe 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 PSIVTRun on UNIX and Linux systems and PSIVTRun.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: 
PSIVTRun -nojndi [-m qmgr ] [-bqm brokerQmgr ] [-v providerVersion ] [-t]
To run the test in client mode, first set up the queue manager as described in Configure a queue manager to accept client connections on Windows, UNIX and IBM i noting that the channel to be used defaults to SYSTEM.DEF.SVRCONN, then enter the following command: 
PSIVTRun -nojndi -client -m qmgr -host hostname [-port port ] [-channel channel ]
[-bqm brokerQmgr ] [-v providerVersion ] [-ccsid ccsid ] [-t]
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.

    -bqm brokerQmgr
    The name of the queue manager on which the broker is running. The default value is the name of the queue manager to which the IVT program connects.

    This parameter is not relevant for queue manager version number v of 7, or greater.

    -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 MQTopicConnectionFactory 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 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 enabled. By default, tracing is disabled.

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

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

Creating a TopicConnectionFactory
Creating a Connection
Creating a Session
Creating a Topic
Creating a TopicPublisher
Creating a TopicSubscriber
Creating a TextMessage
Adding text
Publishing the message to topic://MQJMS/PSIVT/Information
Waiting for a message to arrive [5 secs max]...

Got message:
JMSMessage class: jms_text
JMSType:     null
JMSDeliveryMode: 2
JMSExpiration:  0
JMSPriority:   4
JMSMessageID:   ID:414d5120514d5f6d627720202020202001edb14620006706
JMSTimestamp:   1187182520203
JMSCorrelationID: ID:414d5120514d5f6d627720202020202001edb14620006704
JMSDestination:  topic://MQJMS/PSIVT/Information
JMSReplyTo:    null
JMSRedelivered:  false
JMSXUserID: mwhite
JMS_IBM_Encoding: 273
JMS_IBM_PutApplType: 26
JMSXAppID: QM_mbw
JMSXDeliveryCount: 1
JMS_IBM_PutDate: 20070815
JMS_IBM_ConnectionID: 414D5143514D5F6D627720202020202001EDB14620006601
JMS_IBM_PutTime: 12552020
JMS_IBM_Format: MQSTR
JMS_IBM_MsgType: 8
A simple text message from the MQJMSPSIVT program
Reply string equals original string
Closing TopicSubscriber
Closing TopicPublisher
Closing Session
Closing Connection
PSIVT finished


The publish/subscribe installation verification test using JNDI

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

Before we can run the test, we must configure a directory service that is based on a Lightweight Directory Access Protocol (LDAP) server or the local file system. We 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 Configure the JMS administration tool.

The IVT program must be able to use JNDI to retrieve an MQTopicConnectionFactory object and an MQTopic 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 MQTopicConnectionFactory object is bound with the name ivtTCF and is created with the default values for all its properties, which means that the IVT program runs in bindings mode, connects to the default queue manager, and uses the embedded publish/subscribe function. If we want the IVT program to run in client mode, connect to a queue manager other than the default queue manager, or use IBM Integration Bus instead of the embedded publish/subscribe function, we must use the IBM MQ JMS administration tool or IBM MQ Explorer to change the appropriate properties of the MQTopicConnectionFactory object. For information about how to use the IBM MQ JMS administration tool, see Configure JMS objects using the administration tool. For information about how to use IBM MQ Explorer, see the help provided with IBM MQ Explorer.

The MQTopic object is bound with the name ivtT and is created with the default values for all its properties, except for the TOPIC property, which has the value MQJMS/PSIVT/Information.

When you have created the administered objects, we can run the IVT program. To run the test using JNDI, enter the following command: 
PSIVTRun -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 we 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 enabled. By default, tracing is disabled.

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 MQTopicConnectionFactory object and an MQTopic 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 publish/subscribe 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 Set environment variables.
  • 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 the system.

  • 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 the LDAP server.
  • Th 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 correct set up to accept a client connect from the system. See Configure a queue manager to accept client connections on Windows, UNIX and IBM i for details.

Parent topic: Installing and configuring IBM MQ classes for JMS