SoftWoehr Class Library for IBM MQSeries** Class Reference
Revision 1.0.5
SoftWoehr Class Library for IBM MQSeries** and this documentation
are Copyright *C* 1999, 2000
Jack J. Woehr, P. O. Box 51, Golden, Colorado 80402-0051 USA
http://www.softwoehr.com
Table of Contents
#include 'ing
and using the classes
Start your program with
#include jaxmq.hpp
This in turn includes the MQSeries include files, so those files must be
findable by the C++ preprocessor.
Likewise, at link time, the MQSeries libraries must be findable by the
linker.
All classes provided are in the namespace SoftWoehr. Your program should
either declare that it is
using namespace SoftWoehr;
or should refer to the classes fully qualified, as in the declaration
SoftWoehr::MQQueue myQueue;
General behavior of
member functions
Most member functions, excluding those intended to return specific types
or objects, perform their work and return non-const reference to self.
If an error occurs, an instance of an appropriate MQException
derivative is thrown.
For example, queue operations don't return return codes. If all goes
well, they return non-const reference to self. Otherwise, they throw an
exception which contains the MQSeries completion code and reason code,
along with a string value which describes the error. See MQException
which characterizes the behavior of all exceptions thrown in the library.
Exceptions
Nested exception classes, e.g.,
MQQueueManager::NotConnected Exception
are pervasive in the library. All possess (at least) three public functions
inherited from MQException.
-
virtual const
std::string & get_text(void)
-
Returns a string describing the condition that generated the exception.
-
virtual
MQLONG get_completion_code(void)
-
Returns MQSeries completion code for error (if any, or 0) represented by
this exception.
-
virtual MQLONG get_reason(void)
-
Returns MQSeries reason code for error (if any, or 0) represented by this
exception.
You may derive from MQException in
your code if you wish. Please examine the source files
mqexcept.hpp
mqexcept.cpp
for more information.
All SoftWoehr Class Library code should execute within a try block.
If you are not sure what to catch, catch MQException and use const
string & MQException::get_text() to determine what has been
thrown.
Known shortcoming with exception strategy.
This code only uses exception specifications, e.g.,
Foo::bar(void) throws(woof);
sporadically. It should do so throughout. Read the headers.
Our humble apology is that C++ doesn't enforce exception specifications
in function declarations the way Java does.
Public classes and
their public members
Here are the most important SoftWoehr classes for IBM
MQSeries along with their most important public members. The list is
not exhaustive, due to
-
the number of constants and functions defined to represent options and
attributes of entities;
-
the number of nested exception classes defined;
-
various constraints upon the author's time.
Please examine the header files for more detail.
Listed here are the most important entities you will be dealing with
in your program, along with some guidelines for their usage. Also helpful
are the examples provided.
-
MQBase
-
This is the base class of all classes provided in the library.
-
It may become abstract in future releases.
-
Do not instance this class.
-
Public members
-
static const std::string release_version
-
A literal string describing the release. Currently, it is "SoftWoehr
Library Release 1.0 Copyright *C* 1999 for IBM MQSeries** 2.x."
-
MQException
-
All exceptions thrown by member functions found in this library inherit
from this class.
-
See the comments on general
behavior above.
-
The described behavior is the reason for this exception base class.
-
You do not need to create MQException derivatives or instances
on your own.
-
You are free to do so if you wish.
-
Public members
-
MQException()
-
MQException(const std::string & s)
-
s is the text string describing the exception.
-
MQException(const std::string & s, MQLONG completion_code, MQLONG
reason)
-
s is the text string describing the exception.
-
completion_code is the MQSeries completion code (if any) associated
with the exception.
-
reason is the MQSeries reason code associated with the exception.
-
virtual
const std::string get_text (void) const
-
Returns the string describing the exception.
-
virtual
MQLONG get_completion_code (void) const
-
Returns the MQSeries completion code (or 0) associated with the exception.
-
virtual MQLONG
get_reason (void) const
-
Returns the MQSeries reason code (or 0) associated with the exception.
-
MQQueueManager
-
This class represents a queue manager when used to open other objects.
When a queue manager is used as the object of inquiries, sets, etc, use
MQQueueManagerObject.
-
Open an MQQueueManager instance to perform most MQSeries operations
supported by this library.
-
Public members
-
MQQueueManager()
-
Create an instance not yet associated with any MQSeries queue manager.
-
Use connect() to connect the instance to a queue manager.
-
virtual MQQueueManager & connect(const std::string & mqmgr)
-
Associate an instance of MQQueueManager with a particular MQSeries
queue manager whose name is represented by string.
-
Throws MQQueueManager::AlreadyConnectedException if the instance
is already connected to some queue manager.
-
Throws MQQueueManager::FailedToConnectException if the instance
fails to connect.
-
virtual MQQueueManager & disconnect(void)
-
Disconnect an MQQueueManager instance from a particular queue
manager. The MQQueueManager instance can subsequently be reused
connect to another queue or to reconnect to the same queue.
-
Throws MQQueueManager::NotConnectedException() if the instance
is not currently connected to a queue manager.
-
virtual MQQueueManager & commit(void)
-
Commit most recent unit of work on a queue manager. If commit() is
not called, the work will be committed automatically at disconnect()
if not earlier.
-
Throws MQQueueManager::NotConnectedException() if the instance
is not currently connected to a queue manager.
-
Throws MQQueueManager::CommitException() if an error occurs in
the commit.
-
virtual MQQueueManager & back_out(void)
-
Backout most recent unit of work on a queue manager.
-
Throws MQQueueManager::NotConnectedException() if the instance
is not currently connected to a queue manager.
-
Throws virtual MQQueueManager::BackOutException(my_completion_code,my_reason)
if an error is encountered in the backout.
-
virtual bool is_connected(void) const
-
Returns true if the instance is currently connected to a queue
manager, false otherwise.
-
virtual MQHCONN get_connection_handle (void)
-
Returns the handle to the queue manager connection for use with MQSeries
API calls.
-
virtual const std::string & get_name (void) const
-
Returns the string name of the queue manager.
-
MQObject
-
This is the base class of the classes used to represent those entities
which can be opened as objects in MQSeries. They are
-
While you may instance this class and use it for operations on a queue
or queue manager, it is simpler just to open one of those specializations.
The emphasis in this documentation is on calls you will make from those
specializations, so the constructor for the base class is not documented.
See the source for more information if you wish to instance this base class.
-
Uses a nested class MQObject::Descriptor not documented here to
encapsulate the MQSeries values identifying types of objects. Please see
the header file mqobj.hpp for more information on this essentially self-documenting
class.
-
Uses a nested class MQObject::Options not documented here to encapsulate
MQSeries create options. Please see the header file mqobj.hpp
for more information on this essentially self-documenting class.
-
Public members
-
virtual bool is_opened(void) const
-
true if open on some MQSeries object, false otherwise.
-
virtual MQObject & close(MQObject::Options close_options)
-
close if open, throw nested NotOpenedException otherwise.
-
virtual const MQObject & inquire (MQInquiry
& mq_inquiry) const
-
Perform an inquiry on the object.
-
virtual const MQObject & set (MQSet &
mq_set) const
-
Perform a set on the object.
-
MQQueueManager & get_queue_manager(void) const
-
Get a reference to the MQQueueManager
via connection with which this object was opened.
-
MQHOBJ get_object_handle (void) const
-
Get the MQSeries C API object handle for the object itself.
-
const std::string & get_name (void) const
-
Return the string name of the object.
-
MQQueue
-
Represents an MQSeries message queue.
-
Inherits from MQObject.
-
Get a message from the queue by passing an MQMessage instance to MQQueue::get().
-
The simplest form of get() is shown here; there exist get() overloads
with more complex signatures.
-
Put a message to the queue by passing an MQMessage instance to
MQQueue::put().
-
The simplest form of put() is shown here; there exist put()
overloads with more complex signatures.
-
There exist public members not documented here for making queue inquiries.
-
Public members
-
virtual MQObject & open ( MQQueueManager & queue_manager, const
string & queue_name , const MQObject::Options & options)
-
Open a named queue on a given queue manager with a given set of options.
-
You can pass in a default constructed instance of the nested class MQObject::Options
for many messages.
-
MQObject::Options exists in part to define constants.
-
See the example programs for use of
MQObject::Options.
-
MQQueue & put ( MQMessage
& mq_message) throw( NotOpenedException, MessagePutException)
-
Put a message to the queue.
-
Throws nested exception class instance if queue not opened or message can't
be put.
-
Examine thrown MQQueue::MessagePutException using
-
MQQueue & get ( MQMessage
& mq_message, unsigned long length) throw( NotOpenedException , MessageGetException)
-
Get a message from the queue of up tolength octets.
-
Throws nested exception class instance if queue not opened or message can't
be gotten.
-
Examine thrown MQQueue::MessageGetException using
-
MQQueueManagerObject
-
Represents an MQSeries queue manager when opened as an "object" (in MQSeries
terminology) for operations to be performed upon it.
-
Inherits from MQObject.
-
When a connection to a queue manager is represented, instances of MQQueueManager
are used instead. MQueueManagerObject is for representing the
queue manager when it is treated in MQSeries as a target object rather
than as a connection handle.
-
Public members
-
virtual MQQueueManagerObject & open( MQQueueManager
& queue_manager, const MQObject::Options & options)
-
Open on an already-opened MQQueueManager with options indicated.
-
Nested class usually can be passed in as default construct
-
There are a number of members which perform inquiries on the queue manager.
Please see mqqmobj.hpp for more information.
-
MQMessage
-
Represents a message passed via MQSeries.
-
Accepts arbitrary data as an array of unsigned char.
-
Makes no assumption about the formatting or content of the message.
-
Queue an MQMessage by passing it to MQQueue::put().
-
Accept an incoming message by passing an MQMessage to MQQueue::get().
-
Provides accessors to message data.
-
Put options and get options are fully supported though not documented here.
-
Public members
-
MQMessage()
-
Create an empty MQMessage.
-
MQMessage (const unsigned char * message, unsigned long length)
-
Create an MQMessage with its data copied from the array of unsigned
char for the length indicated.
-
unsigned char * get_message(void)
-
Get a pointer to the data of the message.
-
It is dangerous to manipulate the data in place.
-
Copy out data you wish to use.
-
unsigned long get_length(void) const
-
Get length of data in the message.
-
MQMessage & set_message(const unsigned char * message, unsigned
long length)
-
Copy in data of any length to be the contents the message.
-
Any previous data is lost.
-
MQInquiry
-
Represents an inquiry upon an MQSeries object such as are represented in
this library by MQObject and its derivatives
MQQueue
and MQQueueManagerObject.
-
Since MQSeries inquiries and set operations use the same data structures
there is a typedef which declares MQSet
an alias for MQInquiry.
-
Please see mqinq.hpp and the examples
for more information.
-
MQSet
-
This is a typedef'ed alias for MQInquiry
since MQSeries inquiries and set operations use the same data structures.
-
Please see mqinq.hpp and the examples
for more information.
-
MQProcessDefinition
-
Represents a process definition.
-
Has members to make inquiries.
-
Please see mqprcobj.hpp and the
examples
for more information.