A C++ Library for IBM MQSeries

Administrative actions establish one or more message queues for the set of distributed programs that will employ MQSeries. Configuration includes maximum message size, permission attributes, security exits, and so on. There are no limits beyond the practical to the number of queues, the number of network hops between multiple queue servers, or the number of clients that may participate in exchanging messages in any practical topology.

MQSeries administration empowers application design. Client programs have an efficient, reliable, characterizable means of asynchronous data exchange. Clients awaiting messages can poll the queue or block for a message. Because MQSeries administration is centralized in the intermediate layer (the message queue server), there is less of an application design question as to whether a given client program's periodic response will be sufficient to prevent overflow of some application-specific queuing resource. The limitations, such as there are, are centralized on the capacity of the message queue server as configured. Furthermore, persistence of data residing in the queue means interrupted service can be resumed without loss of transactions.

Uses of MQSeries in the real world range from transaction systems that span legacy platforms and modern desktops to applications that might have been tempted toward CORBA but find MQSeries vastly simpler in instances where the crux of the application is continual data flow between stages running in multiple process spaces (typically on separate and dissimilar hardware platforms). An exotic use of MQSeries under development is a stock trader's "heads-up" compute-anywhere system, allowing the ticker tape to roll by projected on the trader's retina while he's shouting up from the floor.

Early versions of MQSeries sported a standard C programming interface. In recent releases, IBM has started to provide its own C++ bindings. When working on a large ordering system where my station was one of the many destinations of a large data flow, I developed the "SoftWoehr library" -- the open-source C++ class library presented here. SoftWoehr also encapsulates the C language bindings exposed by MQSeries, but is a good deal simpler than IBM's. Still, SoftWoehr is standard C++ and should compile on any MQSeries-supported platform if you have a standard C++ compiler that supports the Standard C++ Libraries. The SoftWoehr library also has a different linguistic flavor than the IBM libraries, a flavor that some C++ programmers might find congenial.

The first step in MQSeries messaging the SoftWoehr library is to open an extant message queue manager. Creating a message queue manager is an administrative task generally performed through scripting or at the command line. Let's say you want to open a queue manager named MYQMGR. Using SoftWoehr, you open this manager using Listing One.

The next step is to open some queue managed by the manager. Let's say the queue is called APRICOT.QUEUE, so your code would read like Listing Two. Note that the queue was opened for both shared input and output. This call might fail due to a prior exclusive open, so you need to catch exceptions and see what any problem might be. Of course, the application itself may be programmed to recover or modify its behavior based on the MQSeries low-level completion code and reason code for failures that are carried along in the exception and for which specific accessors are provided.

Next, you might wish to put a message to the queue. The library treats all messages as an array of unsigned char. The library does not care about the message contents. Because there are some specific formats supported in MQSeries, later versions of the SoftWoehr library will include some specific support for these formats. Listing Three, for instance, just sends some silly text. Another application that has already opened the queue manager and queue for reading might then fetch the message back using Listing Four.

The SoftWoehr class library for IBM MQSeries is available from DDJ (see "Resource Center," page 5) as well as IBM's MQSeries SupportPac page (http://www .ibm.com/software/ts/mqseries/txppacs/ txpsumm.html) as a Category 4 (third-party contribution), and from the SoftWoehr Home Page (http://www.well .com/user/ jax/SoftWoehr).

DDJ

Listing One

#include "jaxmq.hpp"
using namespace SoftWoehr;
// ...
   /* A queue mgr to work with */
   MQQueueManager mq_queue_manager;
      /* Connect to our queue manager */
      try {
         mq_queue_manager.connect("MYQMGR");
         }
      /* Failed to open queue manager. */
      catch (MQQueueManager::FailedToConnectException & ex) {
         cout << "MQQueueManager::FailedToConnectException caught "
              << "opening " << queue_manager_name
              <<" ... Info follows:" << endl;
         cout << ex.get_text() << endl;
         cout << "Completion code : " << ex.get_completion_code() << endl;
         cout << "Reason          : " << ex.get_reason()          << endl;
         }
      /* Failed to open queue manager. */
      catch (MQException & ex) {
         cout << "MQQueueManager::MQException caught "
              << "opening " << queue_manager_name
              <<" ... Info follows:" << endl;
         cout << ex.get_text() << endl;
         }
      /* Announce success */
      cout << "MQQueueManager "
           << mq_queue_manager.get_name()
           << " called MQCONN()."  << endl;
      cout << "Handle is now      : "
           << mq_queue_manager.get_connection_handle()  << endl;
      cout << "Completion code is : "
           << mq_queue_manager.get_completion_code()    << endl;
      cout << "Reason is          : "
           << mq_queue_manager.get_reason()             << endl;

Back to Article

Listing Two

/* Open a queue */
try {
   MQObject::Options options ( MQObject::Options::open_input_shared
                             | MQObject::Options::open_output
                             )
                             ;
   mq_queue.open( mq_queue_manager
                , "APRICOT.QUEUE"
                , options
                )
                ;
   }

catch (MQQueue::FailedToOpenException & ex) {
   cout << "MQQueue::FailedToOpenException caught "
        << "opening APRICOT.QUEUE"
        << " ... Info follows:" << endl;
   cout << ex.get_text() << endl;
   }
catch (MQException &ey) {
   cout << "MQException caught "
        << "opening APRICOT.QUEUE"e
        << " ... Info follows:" << endl;
   cout << ey.get_text() << endl;
   }

Back to Article

Listing Three

 /* A message to put */
#define SILLY_MSG "This is the way we wash our queues!"
    MQMessage mq_message;
    mq_message.set_message(SILLY_MSG, strlen(SILLY_MSG) +1);
    try {
       /** Put a message */
       mq_queue.put(mq_message);
       }
    catch (MQObject::NotOpenedException & noex)
      {
      cout << "Exception caught putting message: " << noex.get_text() << endl;
      }
    catch (MQQueue::MessagePutException & mpex)
      {
      cout << "Exception caught putting message: " << mpex.get_text() << endl;
      cout << "Condition code: " << mpex.get_completion_code() << endl;
      cout << "Reason: "         << mpex.get_reason() << endl;
      }

Back to Article

Listing Four

/* Empty message to receive incoming. */
MQMessage mq_get_message;
try {
   /* The MQMessage can hold any practical length. Here's it just 
    * arbitrarily 1000 bytes max for our silly message.
    */
   mq_queue.get(mq_get_message, 1000);
   }
catch (MQObject::NotOpenedException & nonoex)
   {
   cout << "Exception caught getting message: " << nonoex.get_text() << endl;
   }
catch (MQQueue::MessageGetException & mgex)
   {
   cout << "Exception caught getting message: " << mgex.get_text() << endl;
   cout << "Condition code: " << mgex.get_completion_code() << endl;
   cout << "Reason: "         << mgex.get_reason() << endl;
   }
/* Print out the returned message */
cout << "Returned message == '"
     << mq_get_message.get_message()
     <<"'"
     << endl;

Back to Article