/ 
MQSeries-1.34
River stage one • 1 direct dependent • 1 total dependent
/ MQSeries::Properties

NAME

MQSeries::Properties -- OO interface to MQSeries message properties

SYNOPSIS

use MQSeries qw(:functions);
use MQSeries::Queue;
use MQSeries::Message;

#
# Open a queue for output, and write a message with properties
#
my $qmgr_obj = MQSeries::QueueManager->
  new('QueueManager' => 'some.queue.manager');
my $queue = MQSeries::Queue->new(QueueManager => $qmgr_obj,
                                 Queue        => 'SOME.QUEUE',
                                 Mode         => 'output')
  or die("Unable to open queue.\n");

my $msg = MQSeries::Message->new(Data => "Example message data');

$queue->Put(Message    => $msg,
            Properties => { 'perl.MQSeries.example' => 'property value', },
           );

#
# Alternative: perform a Put1 with properties
#
my $qmgr_obj = MQSeries::QueueManager->
  new('QueueManager' => 'some.queue.manager');
my $msg = MQSeries::Message->new(Data => "Example message data');

$qmgr_obj->Put1(Queue   =  > 'SOME.QUEUE',
                Message    => $msg,
                Properties => { 'perl.MQSeries.example' => 'property value', },
               );

#
# Open a queue for input, read a message, and then list the properties
#
my $queue = MQSeries::Queue->new(QueueManager => $qmgr_obj,
                                 Queue        => 'SOME.QUEUE',
                                 Mode         => 'input')
  or die("Unable to open queue.\n");

my $msg = MQSeries::Message->new();
$queue->Get(Message    => $msg)
  or die("Unable to get message");

my $props_hashref = $msg->Properties()->GetProperties();

#
# Create a properties object and manipulate it directly.  It can
# then be passed to a $queue->Put() operation as the Properties
# parameter.
#
my $props = MQSeries::Properties->new('QueueManager' => $qmgr_obj);
$props->SetProperty(Name  => 'perl.MQSeries.demo.int',
                    Value => 42,
                    Type  => MQSeries::MQTYPE_INT32);
$props->SetProperty(Name  => 'perl.MQSeries.demo.float',
                    Value => 3.141265,
                    Type  => MQSeries::MQTYPE_FLOAT64);
my $prop_hashref = $props->GetProperties('Name' => 'perl.MQSeries.%');
$props->DeletePropery(Name => 'perl.MQSeries.demo.float');

DESCRIPTION

The MQSeries::Properties class is used to work with message properties, a new feature of MQ v7. Message properties are attached to a message and can be used for compatibility with JMS applications, for selectors (see the SelectionString parameter on the MQSeries:Queue class), and for publish and subscribe.

Message properties are only available if the MQSeries module has been compiled against MQ v7 headers and libraries, and if the queue manager connected to runs MQ v7 or above.

The MQseries::Properties class represents a message handle (Hmsg) and the implementation uses the message-handle related MQI calls. Properties can be specified when messages are put and are implicitly retrieved when messages are read.

At the MQ level, message properties are typed; data types like text strings, byte strings, integers, floats and booleans are supported. The property type can be relevant for selector strings. At the perl level, properties are assumed to be strings unless otherwise specified, though the full range of types is supported.

METHODS

new

The property class constructor. This method is normally not invoked directly; instead, it is invoked by Put/Put1/Get operations when necessary. It can be invoked directly when a properties object is created to be used across multiple Put or Put1 calls.

The constructor takes one named parameter:

QueueManager

An MQSeries::QueueManager object

GetProperties

This method returns the property as a hash reference, i.e. key/value pairs. If a property has multiple values (this is technically possible but not recommended), it returns the first value. This matches the behavior of selectors.

This method has two optional named parameters:

Name

The name of the properties to be retrieved. This may contain a wildcard, e.g. 'perl.MQSeries.%'.

Type

The property type to be returned. This is not a selection mechanism, but performs data conversion at the MQ level. For example, if the type specified is MQSeries::MQTYPE_FLOAT64, the properties will be converted to 64-bit floating point numbers by MQ before being returned; an error will be retrurned if the data cannot be converted. Given the flexibility of perl when dealing with scalar values, this parameter is rarely required.

GetDetailedProperties

This method returns all the properties in detail, in the order they are specified and including duplicate values. This method has two optional named parameters:

Name

The name of the properties to be retrieved. This may contain a wildcard, e.g. 'perl.MQSeries.%'.

Type

The property type to be returned. This is not a selection mechanism, but performs data conversion at the MQ level. For example, if the type specified is MQSeries::MQTYPE_FLOAT64, the properties will be converted to 64-bit floating point numbers by MQ before being returned; an error will be retrurned if the data cannot be converted. Given the flexibility of perl when dealing with scalar values, this parameter is rarely required.

It returns an array of hash references, with one hash reference per property value. Each hash reference can contain the following keys:

Name

The property name

Value

The property value (this can be undef)

Type

The property type, as an integer matching one of the MQSeries::MQTYPE_xxx constants. For example, strings are returrned as MQSeries::MQTYPE_STRING.

Encoding

The returned encoding

CCSID

The returned character set id (when the type is MQSeries::MQTYPE_STRING).

DeletyProperty

This method deletes a property. It has one required named parameter:

Name

The name of the property to be deleted. This may not contain wildcards.

SetProperty

This method adds or updates a property. It has the following named parameters:

Name

The name of the property to be added or updated. This may not contain wildcards. This paramater is required.

Value

The property value. This can be undef for string / bytestring properties. This paramater is required.

Type

The property type, as an integer matching one of the MQSeries::MQTYPE_xxx constants. For example, strings are specified as MQSeries::MQTYPE_STRING and 32-bit integers as MQSeries::MQTYPE_INT32.

This parameter is optional. When not specified, the default is the string type.

The property type can be relevant when selectors are used. For example, if a queue is opened like this, only integer properties will match, and string proeprties will be ignored:

my $queue_obj = MQSeries::Queue->
  new(QueueManager    => $qmgr_obj,
      Queue           => 'SOME.QUEUE',
      Mode            => 'input',
      SelectionString => 'perl.MQSeries.test.value=5',
     );

To put a message that matches the selector, use:

$queue_obj->Put(Message    => $msg,
                Properties => { 'perl.MQSeries.test.value' =>
                                { Value => 5,
                                  Type  => MQSeries::MQTYPE_INT32,
                                }
                              },
               );

CompCode

The completion code from the most recent low-level MQI call for the message handle

Reason

The reason code from the most recent low-level MQI call for the message handle

SEE ALSO

MQSeries(3), MQSeries::QueueManager(3), MQSerie::Queue(3), MQSeries::Message(3)