The mq-dev-patterns repository contains a collection of sample programs for IBM MQ. It has examples in a variety of programming languages and styles, working in a number of environments. There are programs showing use of the MQI (or equivalent), JMS, AMQP and REST interfaces. Towards the end of last year, we added a set of C sample programs. Rich wrote a little about them here, but I thought I’d expand on why they were written, and how they work.
Why have a new set of samples?
This helps to fill out the set of languages available in the GitHub repository.
Even if there are fewer new business applications using it, C is still an important language for MQ. The C MQI is where new features usually first appear, and ensuring people know how to use it is important. Lessons learned from the C MQI can be carried forward easily into some of the other language bindings such as Go and Node.js.
Many people using the C client no longer have automatic access to the product sample source code. If you are using the Redistributable Client packages, then although they do include the binary versions of the samples such as amqsget and amqsput, they do not include the sample sources. So another way of providing examples is useful.
And although it’s very much a personal opinion, I’ve always found the product samples to:
- have too many comments (which can obscure what’s really going on)
- be a bit repetitive (although some of that has improved recently, with the move of the password handling to a separate module)
- have a mixture of basic and advanced features without being too clear about the distinction, even if you look them up in the documentation
- have more function than is strictly necessary for a sample meant to demonstrate the programming interface (the samples were never intended to be “production” applications but that’s how a lot of people use them).
So a new set of samples seemed like a good idea. With the principle being to show use of the core MQI in as straightforward a way as possible. And to make the C samples look the same as the other samples in the public repository.
How are they different?
These new samples are intended to match the other samples in the repository in function and general style.
There are a small number of programs that show just the most important and basic functions of the MQI. They work as pairs: put/get, publish/subscribe, request/response. Unlike the product samples, there are hardcoded message contents. As that is the kind of thing that doesn’t really affect the calls to the MQI.
These samples are not intended to show absolutely everything that you can do with MQ. For example, there’s no message browsing. There’s no message properties. But if you are getting started with MQ, these programs show the most common patterns and ways of programming to the interface.
These samples share the same configuration format with the other samples in the repository. There is a JSON file that defines the connection to the queue manager and which objects (like queues) to use. And elements in the JSON file can be overridden by environment variables.
How do they work?
One aspect of the design is to try to have only a single place where common work is done. As an example, the MQCONNX runs in a function in a shared module, rather than having duplicated copies of the call. That is probably the most complex MQI verb, as you might need to fill in a number of different structures. So having just one instance to look at should help people to learn.
Another thing that we had to deal with was handling the configuration.
The pattern of a JSON file was already set – many of the other repository samples use the same JSON file. Of course, many languages have JSON parsing as a core part of the standard packages or make it easy to grab in an add-on library. That’s not really true for C.
While you can find C JSON libraries (and the MQ product itself uses one such) they are not really suitable for sample programs as instructions would have to include downloading and building that library as well – we can’t guarantee that you already have one. So these new samples include a JSON-ish parser. It’s good enough to deal with the limited configuration file format but not to handle a full JSON syntax. And the parser is kept in a separate module, so as not to pollute the demonstration of the MQI. And you can then easily replace it with something more powerful if you need it.
Conclusion
I hope these new C samples are a useful addition to the available education of how to program MQI applications. Please let us know, either here or in the mq-dev-patterns repository, if there’s more that would help.
This post was last updated on January 13th, 2025 at 08:58 am