Connecting a sample application to a queue manager

You can easily and simply connect an application to a queue manager. You can run your application in a number of ways, deployed in the cloud, for example. For validation purposes and the purposes of this example, you can run the IBM® MQ sample applications from your own machine (your laptop, for example).

By completing this task, you can:

Connect to an existing queue manager using the IBM MQ Client samples from your own machine.
Put a test message onto a queue.
Get the test message from a queue.

Note: A newly-deployed queue manager has TLS enabled by default on the predefined channels.

Before you begin

You need an existing queue manager, which can be created by following Creating a queue manager.
An application has been granted permissions to access queue managers within your IBM MQ as a Service service instance. You have obtained the IBM MQ as a Service username and API key for this application (for instructions, follow the Configuring access for connecting an application to a queue manager guide).
If you do not intend to use one of the predefined 'DEV.QUEUE.' queues to put and get messages, follow the Assigning user/group access to a queue guide to configure the authorization record required for your queue.
If you are using a JSON CCDT for your application , you must have a 9.1.2 (or above) installation of the client.
An existing installation of IBM MQ Client on your own machine. For instructions on installing a client, see Administering a queue manager using IBM MQ Explorer and the runmqsc command line.

TLS additional setup

To connect via TLS, you need to specify the channel definitions using a CCDT file.

Navigate to your IBM MQ as a Service UI by following the instructions in Getting started with IBM MQ as a Service.
Find your queue manager in the queue manager list and click on its name to navigate to the queue manager details page.
Click the Connection Information button in the top right of this page.
Tip: You might also want to download the text version, which is easier to read, and a useful source of the queue manager name and url.

In the dialog, click "JSON CCDT" to download the JSON CCDT description of your queue manager and save it in a suitable location:

If you wish to confirm the contents of the channel definitions, it should be a similar format to the example below:

{"channel":[{"name":"CLOUD.ADMIN.SVRCONN","clientConnection":{"connection":[{"host":"myqueuemanager.qm.us-south.mq.appdomain.cloud","port":31500}],"queueManager":"qm1"},"transmissionSecurity":{"cipherSpecification":"ANY_TLS12_OR_HIGHER",},"type":"clientConnection"},
    ...
  ]}

Create a Keystore file
- Follow these instructions to create a keystore file in TLS security for IBM MQ channels in IBM MQ as a Service for use in this application setup.
- After the keystore is created you must set the MQSSLKEYR environment variable.
MQSSLKEYR is the full path from the system root to the key store file. Note that the filename requires no suffix, so for a key store named key.kdb, specify just "key".
- Linux®/Mac - export MQSSLKEYR=/Users/you/store/key
- Windows (Command prompt) - set MQSSLKEYR=c:\mystore\key
- Windows (PowerShell) - $env:MQSSLKEYR=c:\mystore\key

Prepare for connection

Open a command shell on your own machine.

Set the 'MQCCDTURL' variable:
- Mac/Linux: export MQCCDTURL=file:////Users/you/definitions/connection_info_ccdt.json
- Windows: set MQCCDTURL=file:///c:/mydefinitions/connection_info_ccdt.json
- (PowerShell): $env:MQCCDTURL=file:///c:/mydefinitions/connection_info_ccdt.json
  Note: MQCCDTURL can be replaced by two other environment variables MQCHLLIB (the full path to the directory Windowsof your ccdt file) and MQCHLTAB (the filename of the ccdt file)
Set the MQSAMP_USER_ID variable:
- Linux: export MQSAMP_USER_ID="<application MQ username>"
- Windows (Command prompt): set MQSAMP_USER_ID=<application MQ username>
- Windows (PowerShell): $env:MQSAMP_USER_ID="<application MQ username>"
The next steps should be run from the same command shell.

Put a message onto the test queue using amqsputc

Note: Ensure that you have carried out the prerequisite steps listed above, in particular configuring application access to the queue manager.

In the same shell used in the previous steps:

Run <PATH_TO_SAMPLE_BIN_DIR>/amqsputc DEV.QUEUE.1 <your QMGR name>
- Where <PATH_TO_SAMPLE_BIN_DIR> is the path to the sample applications bin directory you made note of in the Prerequisites section above.
Enter the application API key when prompted for a password.
Type in a test message.
Press Enter twice to exit the amqsputc sample.

Get a message using amqsgetc

In the same shell used in the previous step:

Run <PATH_TO_SAMPLE_BIN_DIR>/amqsgetc DEV.QUEUE.1 <your QMGR name>
- Where <PATH_TO_SAMPLE_BIN_DIR> is the path to the sample applications bin directory you made note of in the Prerequisites section above.
Enter the application API key when prompted for a password.

Your test message is displayed.

After a short period, the amqsgetc sample program should end after finding no more messages.

Conclusion

You have successfully:

Connected to a queue manager using a sample application from your own machine.
Put a test message onto a queue.
Obtained the test message from the queue.