ibm-messaging / mq-dev-samples

Samples for getting started with IBM MQ

mq-dev-samples

What this repo is for

This repo hosts sample code referred to and used as part of tutorials for IBM MQ on IBM Developer.

Where to find code to copy/paste into your app

We have a wealth of messaging patterns, represented in many languages, including Java, .NET, Python, Node.js and Golang. They are available at the mq-dev-patterns repo, here!

Feel free to use code from the mq-dev-patterns repo to create your own messaging applications.

Using the gettingStarted/jms samples with TLS (IBM DDC MQ Badge Lab)

For reference these instructions were built from this tutorial. Check it out for additional hints and tips.

Getting setup

• Clone this repo
• Change directory to the working directory
  • Linux cd mq-dev-samples/gettingStarted/jms
  • Windows cd mq-dev-samples\gettingStarted\jms
• Download the javax.jms-api-2.0.1.jar jar

curl -o javax.jms-api-2.0.1.jar https://repo1.maven.org/maven2/javax/jms/javax.jms-api/2.0.1/javax.jms-api-2.0.1.jar

• Download the IBM MQ all client (9.2.2.0) com.ibm.mq.allclient-9.2.2.0.jar jar

curl -o com.ibm.mq.allclient-9.2.2.0.jar https://repo1.maven.org/maven2/com/ibm/mq/com.ibm.mq.allclient/9.2.2.0/com.ibm.mq.allclient-9.2.2.0.jar

• Copy the Queue Manager's public certificate .pem file qmgrcert.pem to the mq-dev-samples/gettingStarted/jms directory

cp <YOUR_DOWNLOAD_DIRECTORY>/qmgrcert.pem . (Linux) or copy <YOUR_DOWNLOAD_DIRECTORY>\qmgrcert.pem . (Windows)

• Use keytool to create a client .p12 trust store

keytool -keystore clientTruststore.p12 -storetype pkcs12 -importcert -file qmgrcert.pem -alias server-certificate

• Enter and then re-enter a password for your new truststore file clientTruststore.p12. It's important to remember this password as we'll use it when we run the sample later.
• Type yes to trust this certificate

Generate application credentials and an API key

Navigate to the "Application Credentials" tab of your cloud MQ service instance.

Click add, then create a user called "app". Click Add and generate API key, which will bring up your API token. Copy this and save it somewhere as you'll need it in the application you run to authenticate yourself to your MQ instance.

Start coding to put a message with jms

Open the com/ibm/mq/samples/jms/JmsPut.java file (Linux) or com\ibm\mq\samples\jms\JmsPut.java (Windows) in your favorite editor

Uncomment the following line

cf.setStringProperty(WMQConstants.WMQ_SSL_CIPHER_SUITE, "*TLS12");

Modify the following variables to match your IBM MQ configuration

private static final String HOST = "_YOUR_HOSTNAME_"; // Host name or IP address
private static final int PORT = 1414; // Listener port for your queue manager
private static final String CHANNEL = "DEV.APP.SVRCONN"; // Channel name
private static final String QMGR = "QM1"; // Queue manager name
private static final String APP_USER = "app"; // User name that application uses to connect to MQ
private static final String APP_PASSWORD = "_APP_PASSWORD_"; // Password that the application uses to connect to MQ
private static final String QUEUE_NAME = "DEV.QUEUE.1"; // Queue that the application uses to put and get messages to and from

Compile your jms code

• Change directory to mq-dev-samples/gettingStarted/jms (Linux) or mq-dev-samples\gettingStarted\jms (Windows)
• Compile your modified JmsPut.java application
  • For Linux javac -cp ./com.ibm.mq.allclient-9.2.2.0.jar:./javax.jms-api-2.0.1.jar com/ibm/mq/samples/jms/JmsPut.java
  • For Windows javac -cp .\com.ibm.mq.allclient-9.2.2.0.jar;.\javax.jms-api-2.0.1.jar com\ibm\mq\samples\jms\JmsPut.java
• You should now see a JmsPut.class file alongside your JmsPut.java source file

Run your jmsPut application

Execute your Java code, specifying the clientTruststore.p12 and password you set up earlier

• For Linux

java -Djavax.net.ssl.trustStore=clientTruststore.p12 -Djavax.net.ssl.trustStorePassword=passw0rd -cp ./com.ibm.mq.allclient-9.2.2.0.jar:./javax.jms-api-2.0.1.jar:. com.ibm.mq.samples.jms.JmsPut

• For Windows

java -Djavax.net.ssl.trustStore=clientTruststore.p12 -Djavax.net.ssl.trustStorePassword=passw0rd -cp .\com.ibm.mq.allclient-9.2.2.0.jar;.\javax.jms-api-2.0.1.jar;. com.ibm.mq.samples.jms.JmsPut

What you should see

Congratuations, you've just sent you're first IBM MQ Message and you should see output similar to the following:

Sent message:

  JMSMessage class: jms_text
  JMSType:          null
  JMSDeliveryMode:  2
  JMSDeliveryDelay: 0
  JMSDeliveryTime:  1617186154396
  JMSExpiration:    0
  JMSPriority:      4
  JMSMessageID:     ID:414d512049424d5f4444435f514d202000476460013f0040
  JMSTimestamp:     1617186154396
  JMSCorrelationID: null
  JMSDestination:   queue:///DEV.QUEUE.1
  JMSReplyTo:       null
  JMSRedelivered:   false
    JMSXAppID: JmsPutGet (JMS)             
    JMSXDeliveryCount: 0
    JMSXUserID: app         
    JMS_IBM_PutApplType: 28
    JMS_IBM_PutDate: 20210331
    JMS_IBM_PutTime: 10223528
Your lucky number today is 369
SUCCESS

mq-dev-samples's Issues

Cannot find symbol

When I run mvn clean package, it throws compilation error and says cannot find symbol.

Compiled JmsPutGet.java executes ok but no message placed in the queue

I'm running these tutorial instructions using a couple different Docker MQ images, both 9.2.0 and 9.3.5. When I execute JmsPut.class, I get the expected output showing me the lucky number:

java -cp `.\com.ibm.mq.allclient-9.3.0.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar;.' com.ibm.mq.samples.jms.JmsPutGet
Sent message:

  JMSMessage class: jms_text
  JMSType:          null
  JMSDeliveryMode:  2
  JMSDeliveryDelay: 0
  JMSDeliveryTime:  1710285567365
  JMSExpiration:    0
  JMSPriority:      4
  JMSMessageID:     ID:414d5120514d312020202020202020200e8ef06501d00440
  JMSTimestamp:     1710285567365
  JMSCorrelationID: null
  JMSDestination:   queue:///DEV.QUEUE.1
  JMSReplyTo:       null
  JMSRedelivered:   false
    JMSXAppID: JmsPutGet (JMS)
    JMSXDeliveryCount: 0
    JMSXUserID: app
    JMS_IBM_PutApplType: 28
    JMS_IBM_PutDate: 20240312
    JMS_IBM_PutTime: 23192739
Your lucky number today is 336

Received message:
Your lucky number today is 336
SUCCESS

However, when I go into my MQ console, I don't see the actual message in queue DEV.QUEUE.1. All my queues show 0 messages. I tried a bunch of different tests on both MQ versions, and I get the same results. If I use the amqsput command to manually put a message on the same qm/queue, it works just fine.

Anyone see this before or have any ideas what could be wrong?

3 bugs found running the script

1. The downloaded tar contains Package.gz but Package is required
2. The tar is extracted to /tmp/MQServer but the archive directory is set to ~/MQServer
3. if you fix these two problems and try the amqsputc example you run into error "MQCONNX ended with reason code 2540"

In addition to these errors, it would be nice if the example could be kept up to date. The version downloaded by the script is 9.2, the current version is 9.3.4 ...

mqadv_dev911_ubuntu_x86-64.tar.gz no longer exists

see https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/

[Improvement] Unable to install

The following is a problem i faced during the installation via the script. I think it's worth metioning in the README.md to help newcomers.

Problem

Installation via script fails when the path is inside the /root/ folder.

root@dev-server:/etc/apt/sources.list.d# sudo apt update
Get:1 file:/root/MQServer ./ InRelease
Ign:1 file:/root/MQServer ./ InRelease

[...]

Reading package lists... Done
N: Download is performed unsandboxed as root as file '/root/MQServer/./InRelease' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
E: Failed to fetch file:/root/MQServer/./Packages  File not found - /root/MQServer/./Packages (2: No such file or directory)
E: Some index files failed to download. They have been ignored, or old ones used instead.

Solution

Launch the script in a folder accessible by the user _apt (such as /tmp).

root@dev-server:/tmp# bash < <(curl -s https://raw.githubusercontent.com/ibm-messaging/mq-dev-samples/master/gettingStarted/installing-mq-ubuntu/mq-ubuntu-install.sh)

MQ Container tutorial missing steps to send messages to the queue

At the end of the tutorial, the summary says:

But the steps listed do not discuss how to do that. I tried using the steps from the Ubuntu tutorial but I got this error: MQCONNX ended with reason code 2035.

Unable to connect to local queue manager in created in MQ Explorer

Hello,

I set up a local queue manager via MQ Explorer (v 9.2.2.0, Windows 10) via this tutorial:
https://www.ibm.com/docs/en/ibm-mq/8.0?topic=tutorials-tutorial-1-sending-message-local-queue
and then I try to run JmsPutGet with the method here:
https://developer.ibm.com/components/ibm-mq/tutorials/mq-develop-mq-jms
but haven't been able to get it to work.

In particular, I have tried to set up the constants in the script to put/get a message from the queue manager, as follows:

    private static final String HOST = "localhost"; // Host name or IP address
private static final int PORT = 1414; // Listener port for your queue manager
private static final String CHANNEL = "SYSTEM.DEF.SVRCONN"; // Channel name
private static final String QMGR = "QM_APPLE"; // Queue manager name
private static final String APP_USER = "app"; // User name that application uses to connect to MQ
private static final String APP_PASSWORD = "passw0rd"; // API key
private static final String QUEUE_NAME = "Q1"; // Queue that the application uses to put and get messages to and from

I then compile the file with the following command in Windows command line:
javac -cp .\com.ibm.mq.allclient-9.1.4.0.jar;.\javax.jms-api-2.0.1.jar com\ibm\mq\samples\jms\JmsPutGet.java

Then I try to run the compiled program with:
java -cp .\com.ibm.mq.allclient-9.1.4.0.jar;.\javax.jms-api-2.0.1.jar;. com.ibm.mq.samples.jms.JmsPutGet

I get a error with reason code 2035 and completion code 2. I have tried numerous ways to fix the issue, such as the ones listed here and here, but still get the same error.

I've also tried to change channel to DEV.APP.SVRCONN, but that gives an error with reason code 2540.

The task of put/get to a local queue should be straightforward but for whatever reason I haven't been able to get it to work... If you could provide any help at all, I would really appreciate it.

Many thanks,
Frank

Cannot connect to IBM Cloud MQ

Following this tutorial (README), I end up with the following exception:
MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2035' ('MQRC_NOT_AUTHORIZED').

Difference from the actual tutorial:

• I am using a newer version of the ibm.mq.allclient (9.3.2.1) as with the older (9.2.2.2) I had an Exception due to deprecation
• I also added json-20230227.jar as a dependency because of a ClassNotFoundException: org.json.JSONException
• I have also set up a keystore for my client (following the steps for creating a self-signed certificate on this page and importing the certificate to MQ's keystore through the IBM Cloud Console) because I noticed in the logs that the client would send a "Produced client Certificate message" with an empty list of certificates.

Setting up a client keystore seems to work, because now the handshake looks good, but the example fails with the following stacktrace:

> java -Djavax.net.ssl.trustStore=clientTruststore.p12 -Djavax.net.ssl.trustStorePassword=passw0rd -Djavax.net.ssl.keyStore=clientKeystore.p12 -Djavax.net.ssl.keyStorePassword=passw0rd -Djavax.net.debug=ssl,handshake -cp .\com.ibm.mq.allclient-9.2.5.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20230227.jar;. com.ibm.mq.samples.jms.JmsPut

...
javax.net.ssl|DEBUG|10|main|2023-05-11 10:23:30.017 CEST|Finished.java:687|Produced client Finished handshake message (
"Finished": {
  "verify data": {
    ...
  }
}
)
javax.net.ssl|DEBUG|10|main|2023-05-11 10:23:30.018 CEST|SSLCipher.java:2626|algorithm = ChaCha20-Poly1305:KEYUPDATE
countdown value = 0
Exception in thread "main" com.ibm.msg.client.jms.DetailedJMSSecurityRuntimeException: JMSWMQ2007: Failed to send a message to destination 'MY_QUEUE'.
JMS attempted to perform an MQPUT or MQPUT1; however IBM MQ reported an error.
Use the linked exception to determine the cause of this error.
        at com.ibm.msg.client.jms.DetailedJMSSecurityException.getUnchecked(DetailedJMSSecurityException.java:270)
        at com.ibm.msg.client.jms.internal.JmsErrorUtils.convertJMSException(JmsErrorUtils.java:173)
        at com.ibm.msg.client.jms.internal.JmsProducerImpl.send(JmsProducerImpl.java:618)
        at com.ibm.mq.samples.jms.JmsPut.main(JmsPut.java:109)
Caused by: com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2035' ('MQRC_NOT_AUTHORIZED').
        at com.ibm.msg.client.wmq.common.internal.Reason.createException(Reason.java:203)
        at com.ibm.msg.client.wmq.internal.WMQMessageProducer.checkJmqiCallSuccess(WMQMessageProducer.java:1358)
        at com.ibm.msg.client.wmq.internal.WMQMessageProducer.checkJmqiCallSuccess(WMQMessageProducer.java:1313)
        at com.ibm.msg.client.wmq.internal.WMQMessageProducer.access$800(WMQMessageProducer.java:75)
        at com.ibm.msg.client.wmq.internal.WMQMessageProducer$SpiUnidentifiedProducerShadow.sendInternal(WMQMessageProducer.java:1123)
        at com.ibm.msg.client.wmq.internal.WMQMessageProducer$ProducerShadow.send(WMQMessageProducer.java:608)
        at com.ibm.msg.client.wmq.internal.WMQMessageProducer.send(WMQMessageProducer.java:1487)
        at com.ibm.msg.client.jms.internal.JmsMessageProducerImpl.sendMessage(JmsMessageProducerImpl.java:855)
        at com.ibm.msg.client.jms.internal.JmsMessageProducerImpl.synchronousSendInternal(JmsMessageProducerImpl.java:2055)
        at com.ibm.msg.client.jms.internal.JmsMessageProducerImpl.sendInternal(JmsMessageProducerImpl.java:1993)
        at com.ibm.msg.client.jms.internal.JmsMessageProducerImpl.send(JmsMessageProducerImpl.java:1535)
        at com.ibm.msg.client.jms.internal.JmsProducerImpl.send(JmsProducerImpl.java:609)
        ... 1 more

mq-demo is failing to connect to queue manager

Hi,

We established an IBMMQ in a docker container using this link https://developer.ibm.com/messaging/learn-mq/mq-tutorials/mq-connect-to-queue-manager/#docker

However, the demo application mq-demo from mq-dev-samples https://raw.githubusercontent.com/ibm-messaging/mq-dev-samples/master/gettingStarted/mq-demo-client-application/Dockerfile is failing to connect to the queue. Please find the attached screenshot regarding the error message.

Any hints or help ?

Thank you,