samples

README

Sample program information

Files in this directory are samples to demonstrate use of the Go interface to IBM MQ.

You can run them individually using go run <program>.go with any additional required or optional parameters on the command line. Look at the source code to see which configuration values can be changed.

Make sure you first read the README in the root of this repository to set up an environment where Go programs can be compiled, and how the packages refer to the MQ interfaces.

The buildSamples.sh script in the root directory can be used to create a container to compile the samples and copy them to a local directory.

Default values

Where needed for the sample programs:

• the default queue manager is "QM1"
• the default queue is "DEV.QUEUE.1"
• the default topic is based on "DEV.BASE.TOPIC" (topic string is under dev/... tree)

Description of sample programs

Current samples in this directory include

• amqsput.go : Put a single message to a queue
• amqsget.go : Get all the messages from a queue. Optionally get a specific message by its id
• amqspub.go : Publish to a topic
• amqssub.go : Subscribe to a topic and receive publications
• amqsconn.go: How to programmatically connect as an MQ client to a remote queue manager. Allow use of a userid/password for authentication. There are no default values for this sample.
• amqsprop.go: Set and extract message properties
• amqsinq.go : Demonstrate the Inq API for inquiring about object attributes
• amqsset.go : Demonstrate how to set attributes of an MQ object using the MQSET verb
• amqscb.go : Demonstrate use of the CALLBACK capability for asynchronous consumption of messages
• amqsbo.go : Show how to deal with poison messages by putting them to a configured backout queue
• amqsdlh.go : Putting a message to a DLQ with a dead-letter header
• amqspcf.go : Demonstrate use of the PCF functions to create a command and parse a response

Some trivial scripts run the sample programs in matching pairs:

• putget.sh : Run amqsput and then use the generated MsgId to get the same message with amqsget
• pubsub.sh : Start amqssub and then run the amqspub program immediately

Building a container:

• runSample.sh : Drives the process to get amqsput into the container
• runSample.bud.sh : Drives the process to get amqsput into the container using podman/buildah as an alternative approach
• runSample.*.Dockerfile : Instructions to create containers with runtime dependencies
• runSample.gomod : Copied into the container as go.mod Two variants of the Dockerfile are provided. Set the FROM environment variable to "UBI" to use Red Hat Universal Base Images as the starting points for building and runtime; otherwise an Ubuntu/Debian combination is used.

The mqitest sample program in its own subdirectory is a more general demonstration of many of the features available from the MQI rather than focussed on a specific aspect.

Running the programs

Apart from the amqsconn.go program, the other samples are designed to either connect to a local queue manager (on the same machine) or for the client configuration to be provided externally such as by the MQSERVER environment variable or the MQ Client Channel Definition Table (CCDT) file. The MQ_CONNECT_TYPE environment variable can be used to force client connections to be made, even if you have installed the full server product; that variable is not needed if you have only installed the MQ client libraries.

For example

  export MQSERVER="SYSTEM.DEF.SVRCONN/TCP/localhost(1414)"
  export MQ_CONNECT_TYPE=CLIENT
  go run amqsput.go DEV.QUEUE.1 QM1

The amqsput.go program also allows the queue and queue manager names to be provided by environment variables, to show another configuration mechanism. That approach will often be used in container deployments, and is demonstrated in the runSample set of files.

Publish/Subscribe testing

You will probably want to run amqssub JUST BEFORE running amqspub to ensure there is something waiting to receive the publications when they are made. The pubsub.sh script executes the two programs appropriately.

Building a container for running samples

There is an set of files in here that will show how to create a container that runs the amqsput program. The runSample*.sh scripts drive the process. It will try to connect to a queue manager running on the host machine.

The process is split into two pieces - the first is used to compile the program, and the second creates a (hopefully) smaller container with just the components needed to run the program.

More information

Comments in the programs explain what they are doing. For more detailed information about the MQ API, the functions, structures, and constants, see the MQ Knowledge Center.

You can also find general MQ application development advice here. Information about development for procedural programming languages such as C in that documentation is most relevant for the interface exported by this Go package.

Documentation

Overview

• This is an example of a Go program that deals with unprocessable or "poison" messages on an IBM MQ

• queue by moving them to a backout queue. As the message is moved to the backout queue

• a dead-letter header is attached both to indicate the reason for the move, and to

• permit a DLQ handler program to further process the message. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• The input queue should be defined with both BOTHRESH and BOQNAME values and

• the backout queue must exist

• DEF QL(DEV.QUEUE.1) BOTHRESH(3) BOQNAME(DEV.QUEUE.BACKOUT) REPLACE

• DEF QL(DEV.QUEUE.BACKOUT) *

• Each MQI call prints its success or failure. *

• This is an example of a Go program to get messages from an IBM MQ

• queue. It uses the asynchronous callback operation instead of using

• a synchronous MQGET. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• Each MQI call prints its success or failure. *

This is a short sample to show how to connect to a remote queue manager in a Go program without requiring external client configuration such as a CCDT. Only the basic parameters are needed here - channel name and connection information - along with the queue manager name.

For example, run as

amqsconn QMGR1 "SYSTEM.DEF.SVRCONN" "myhost.example.com(1414)"

If the MQSAMP_USER_ID environment variable is set, then a userid/password flow is also made to authenticate to the queue manager.

There is no attempt in this sample to configure advanced security features such TLS.

If an error occurs, the error is reported.

This is a short sample to show how to connect to a remote queue manager in a Go program with a TLS connection without requiring external client configuration such as a CCDT. The basic parameters are still needed here - channel name and connection information - along with the queue manager name.

For example, run as

amqsconn QMGR1 "SYSTEM.SSL.SVRCONN" "myhost.example.com(1414)"

If the MQSAMP_USER_ID environment variable is set, then a userid/password flow is also made to authenticate to the queue manager.

If an error occurs, the error is reported.

• This is an example of a Go program to put and get messages to an IBM MQ

• queue while manipulating a Dead Letter Header *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• This is an example of a Go program to browse messages from an IBM MQ

• queue. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• The program loops until no more messages are on the queue, waiting for

• at most 3 seconds for new messages to arrive. *

• Each MQI call prints its success or failure. *

• This is an example of a Go program to get messages from an IBM MQ

• queue. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• The program loops until no more messages are on the queue, waiting for

• at most 3 seconds for new messages to arrive. *

• Each MQI call prints its success or failure. *

• A MsgId can be provided as a final optional parameter to this command

• in which case we try to retrieve just a single message that matches. *

• This is an example of a Go program to inquire on some attributes of some IBM MQ

• objects. The program looks at a nominated queue, and also at a NAMELIST *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. * *

• This is an example of a Go program to create and parse PCF messages. It

• issues the equivalent of "DISPLAY Q(x) ALL". *

• The queue manager name and the queue to inquire on can be given as parameters on the

• command line. Defaults are coded in the program. It also accesses

• SYSTEM.ADMIN.COMMAND.QUEUE and SYSTEM.DEFAULT.MODEL.QUEUE. *

• The program loops until either the command responses indicate completion, or no more replies are on

• the queue, waiting for at most 3 seconds for new messages to arrive. *

• This is an example of a Go program to put and get messages to an IBM MQ

• queue while manipulating the message properties *

• While the main body of this sample is the same as the amqsput and amqsget

• samples, the important functions to understand here are setProperties and

• printProperties. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• This is an example of a Go program to publish messages to an IBM MQ

• topic. *

• The topic and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• A single message is published, containing a "hello" and timestamp.

• Each MQI call prints its success or failure. *

• This is an example of a Go program to put messages to an IBM MQ

• queue. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program.

• This sample also permits use of environment variables for the

• parameters, which might be preferable in some container

• deployments. *

• A single message is put, containing a "hello" and timestamp.

• Each MQI call prints its success or failure. The MsgId of the

• put message is also printed so it can be used as an optional

• selection criterion on the amqsget sample program. *

• This is an example of a Go program to set some attributes of an IBM MQ

• queue through the MQSET verb. The attributes that can be set are limited;

• those limitations are described in the MQSET documentation. *

• The queue and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. * *

• This is an example of a Go program to subscribe to publications from an IBM MQ

• topic. *

• The topic and queue manager name can be given as parameters on the

• command line. Defaults are coded in the program. *

• The program loops until no more publications are available, waiting for

• at most 3 seconds for new messages to arrive. *

• Each MQI call prints its success or failure. *