Verifying the installation of IBM MQ Telemetry using the command line

Follow these instructions to run scripts and a sample application to verify that the IBM® MQ Telemetry components have installed, and are able to publish and subscribe.

Before you begin

Note:

This task uses the mqttv3app sample Java application, and the associated Java client library. These resources were previously available in the MA9C: IBM Messaging Telemetry Clients SupportPac, and the detailed instructions in this task assume that you have a copy of this SupportPac.

The MA9C: IBM Messaging Telemetry Clients SupportPac is no longer available. Free downloads of the latest telemetry clients and samples, for a range of programming languages, continue to be available from the Eclipse Paho project, and from MQTT.org.

The telemetry (MQXR) service must be started to run the sample programs. The user ID must be a member of the mqm group.

The SampleMQM script creates and uses a queue manager called MQXR_SAMPLE_QM. Therefore, do not run unaltered on a system that already has a MQXR_SAMPLE_QM queue manager. Any changes made might have implications for the configuration of the existing queue manager.

There are two commands to run the mqttv3app sample Java application. The first command creates a subscription, then waits for a message. The second command publishes to that subscription. Therefore the commands must be entered into different command lines or shell windows.

About this task

To perform verification on a server or device without a GUI, scripts are provided in the samples directory. The SampleMQM script performs the required steps to configure IBM MQ Telemetry. The mqttv3app sample Java application can then be run to validate the basic or custom IBM MQ Telemetry configuration by connecting, subscribing to topics, and publishing messages. The CleanupMQM sample script can be run to delete the queue manager created by the SampleMQM script.

The following items summarize the main goals that can be achieved using this verification procedure:

Validate a basic or custom IBM MQ Telemetry configuration by connecting, subscribing to topics and publishing messages.
Showcase the main features of the MQTT protocol.
Provide a simple tool to aid in debugging IBM MQ Telemetry applications.

Procedure

Download the MA9C: IBM Messaging Telemetry Clients SupportPac.
Decompress the client pack into a directory of your own choosing.

This task uses the mqttv3app sample Java application, and the associated mqttv3 Java client library. If you have an older version of the MA9C SupportPac, the sample applications and client libraries are in the CLIENTPACKDIR/SDK/clients/java directory, where CLIENTPACKDIR is the directory in which you decompressed the client pack.

Note: Recent versions of the MA9C: IBM Messaging Telemetry Clients SupportPac do not have the /SDK/ directory, and do not include a compiled copy of the mqttv3app sample application. If you have a recent version of the MA9C SupportPac, you need to compile the application manually, then create the /SDK/ directory and contents. For the latest information about available clients and samples, see IBM MQ Telemetry Transport sample programs.
Configure IBM MQ Telemetry.
The SampleMQM script runs through a series of steps, including creating the MQXR_SAMPLE_QM queue manager, defining and starting the telemetry (MQXR) service, setting up the default transmission queue, and configuring a telemetry channel.
For information about performing this manually, see Configuring a queue manager for telemetry on Linux® and AIX® , or Configuring a queue manager for telemetry on Windows .
- On Windows systems, enter the following command in a command line:
```
 MQINSTDIR\mqxr\samples\SampleMQM.bat
```
- On AIX or Linux systems, enter the following command in a shell window:
```
 MQINSTDIR/mqxr/samples/SampleMQM.sh
```
where MQINSTDIR is the installation directory for this installation of IBM MQ.
A queue manager called MQXR_SAMPLE_QM is created, and IBM MQ Telemetry is configured.

Run the mqttv3app sample Java application to create a subscription.

On Windows systems, enter the following commands in a command line:

java -cp
"CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.sample.mqttv3app.jar;
CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.client.mqttv3.jar"
org.eclipse.paho.sample.mqttv3app.Sample -a subscribe

On AIX or Linux systems, enter the following commands in a shell window:

java -cp
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.sample.mqttv3app.jar:
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.client.mqttv3.jar
org.eclipse.paho.sample.mqttv3app.Sample -a subscribe

The subscription is created, and waits to receive a message.

Run the mqttv3app sample Java application to publish to the subscription.
- On Windows systems, enter the following command in a second command line:
```
java -cp
"CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.sample.mqttv3app.jar;
CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.client.mqttv3.jar"
org.eclipse.paho.sample.mqttv3app.Sample -m "Hello from an MQTT v3 application"
```
- On AIX or Linux systems, enter the following command in a second shell window:
```
java -cp
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.sample.mqttv3app.jar:
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.client.mqttv3.jar
org.eclipse.paho.sample.mqttv3app.Sample -m "Hello from an MQTT v3 application"
```
The message Hello from an MQTT v3 application, that you typed into the second command line or shell window, is published by that application and received by the application in the first window. The application in the first window shows it on the screen.
Press Enter in the first command line or shell window to end the subscribing application.
Remove the queue manager created by the SampleMQM script.
- On Windows systems, enter the following command in a command line:
```
 MQINSTDIR\mqxr\samples\CleanupMQM.bat
```
- On AIX or Linux systems, enter the following command in a shell window:
```
 MQINSTDIR/mqxr/samples/CleanupMQM.sh
```

Results

If the scripts finished, and messages can be sent and received, the IBM MQ Telemetry installation is verified.

What to do next

If you encounter any problems during the verification process, see IBM MQ Telemetry troubleshooting. You can also view the error log:

On Windows systems, the default location for the queue manager log is MQINSTDIR\qmgrs\MQXR_SAMPLE_QM\mqxr
On AIX and Linux systems, the default location for the queue manager log is /var/mqm/qmgrs/MQXR_SAMPLE_QM/mqxr/