MQSeries::Properties -- OO interface to MQSeries message properties
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');
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.
MQSeries::Properties
SelectionString
MQSeries:Queue
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.
MQseries::Properties
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.
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:
An MQSeries::QueueManager object
MQSeries::QueueManager
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:
The name of the properties to be retrieved. This may contain a wildcard, e.g. 'perl.MQSeries.%'.
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.
MQSeries::MQTYPE_FLOAT64
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:
It returns an array of hash references, with one hash reference per property value. Each hash reference can contain the following keys:
The property name
The property value (this can be undef)
undef
The property type, as an integer matching one of the MQSeries::MQTYPE_xxx constants. For example, strings are returrned as MQSeries::MQTYPE_STRING.
MQSeries::MQTYPE_xxx
MQSeries::MQTYPE_STRING
The returned encoding
The returned character set id (when the type is MQSeries::MQTYPE_STRING).
This method deletes a property. It has one required named parameter:
The name of the property to be deleted. This may not contain wildcards.
This method adds or updates a property. It has the following named parameters:
The name of the property to be added or updated. This may not contain wildcards. This paramater is required.
The property value. This can be undef for string / bytestring properties. This paramater is required.
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.
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, } }, );
The completion code from the most recent low-level MQI call for the message handle
The reason code from the most recent low-level MQI call for the message handle
MQSeries(3), MQSeries::QueueManager(3), MQSerie::Queue(3), MQSeries::Message(3)
To install MQSeries, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MQSeries
CPAN shell
perl -MCPAN -e shell install MQSeries
For more information on module installation, please visit the detailed CPAN module installation guide.