NAME

MQSeries::Message -- OO interface to MQSeries messages

SYNOPSIS

use MQSeries;
use MQSeries::Message;

#
# Create a vanilla MQSeries::Message object for getting messages
#
my $getmsg = MQSeries::Message->new();

#
# Create a message for putting strings, which requires the
# MQMD.Format field to be specified.  This is essential for
# character codeset conversion. 
#
my $putmsg = MQSeries::Message->new
  (
   MsgDesc 		=>
   {
    Format		=> MQFMT_STRING,
   },
  );

#
# Create a reply message, copying the CorrelId from the MsgId of a
# request.  This reply is also a string.
#
my $request = MQSeries::Message->new();

# Assume we get the message via an MQSeries::Queue object...

my $reply = MQSeries::Message->new
  (
   MsgDesc 		=>
   {
    Format		=> MQFMT_STRING,
    CorrelId 		=> $request->MsgDesc("MsgId"),
   },
  );

See MQSeries::Queue SYNOPSIS section as well.

DESCRIPTION

The MQSeries::Message object is an OO mechanism for creating MQSeries messages, and putting and getting them onto MQSeries queues, with an interface which is much simpler than the full MQI.

This module is used together with MQSeries::QueueManager and MQSeries::Queue. These objects provide a subset of the MQI, with a simpler interface.

METHODS

new

The arguments to the constructor are a hash, with the following key/value pairs (there are no required keys):

Key            Value
===            =====
Data           Scalar
BufferLength   Positive Integer
MsgDesc        MQI MsgDesc hash (MQMD structure)
Carp           CODE reference

Data

When creating a message to be put into a queue, the Data should be specified. This must be a simple scalar value. Other subclasses of MQSeries::Message support the direct encoding of complex data structure, for example perl references can be sent and retreived as MQSeries messages using the MQSeries::Message::Storable module.

The Data method will set the Data portion of the message if it is passed any defined value, and will simply return the data otherwise. Thus, to clear any existing Data from a message, one would pass the empty string:

$message = MQSeries::Message->new( Data => "foo" );
$message->Data(""); # Clears Data value entirely

In order to query the Data value, the method must be called with no further arguments;

$data = $message->Data(); # Returns Data unmolested

Buffer

This method will return the raw, converted buffer when one exists. This is really only relevant for a message type which uses a PutConvert and/or GetConvert method to translate the raw buffer returned from MQGET().

BufferLength

This sets the BufferLength of the messages to be extracted using MQGET. The default is 32K, and if the messages to be received from the queue are expected to be larger, this must be set appropriately.

MsgDesc

The value of this key is a hash refernece which sets the key/values of the MsgDesc structure. See the "MQSeries Application Programming Reference" documentation for the possible keys and values of the MQMD structure.

Also, see the examples section for specific usage of this feature. This is one area of the API which is not easily hidden; you have to know what you are doing.

Carp

This key specifies a code reference to a routine to replace all of the carp() calls in the API, allowing the user of the API to trap and handle all of the error message generated internally, or simply redirect how they get logged.

For example, one might want everything to be logged via syslog:

sub MyLogger {
    my ($message) = @_;
    foreach my $line (split(/\n+/, $message)) {
        syslog("err", $line);
    }
}

Then, one tells the object to use this routine:

my $message = MQSeries::Message->new( Carp => \&MyLogger )
  || die "Unable to create message.\n";

The default, as one might guess, is Carp::carp();

Data

This method is used to set or query the value of the Data structure. If an argument is specified, then the given data is assigned as the Data value for this object. If no argument is given, then the current Data value is returned.

The Data can be any arbitrary perl data structure, however, it must be convertible to a scalar by means of the PutConvert and GetConvert hooks in MQSeries::QueueManager and MQSeries::Queue objects. See the documentation for those classes for more details.

If the GetConvert and PutConvert hooks are not used, then the data must be a simple scalar value.

BufferLength

This method is used to set or query the current BufferLength used when extracting messages. If given an argument, the BufferLength is set to the given value. If the given value is not a positive integer, then an error is generated, and a false value returned.

With no argument, the current BufferLength is returned.

MsgDesc

This method can be used to query the MsgDesc data structure. If no argument is given, then the entire MsgDesc hash is returned. If a single argument is given, then this is interpreted as a specific key, and the value of that key in the MsgDesc hash is returned.

ERROR HANDLING

Most methods return a true or false value indicating success of failure, and internally, they will call the carp subroutine (either Carp::carp, or something user-defined) with a text message indicating the cause of the failure.

SUBCLASSES

This class is designed to be subclassed, and follows all the usual rules (see the "perltoot" documentation provided with the core perl distribution). In particular, the PutConvert and GetConvert arguments usually supplied to either the MQSeries::QueueManager or MQSeries::Queue constructors are not necessary if you implement a subclass of MQSeries::Message with methods of the same name.

See the MQSeries::Message::Storable documentation for an example of one such class.

See also the section "CONVERSION PRECEDENCE" in the MQSeries::QueueManager documentation.

SEE ALSO

MQSeries(3), MQSeries::QueueManager(3), MQSeries::Queue(3), MQSeries::Message::Storable(3), MQSeries::Message::Event(3)