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

NAME

MQSeries::Queue -- OO interface to the MQSeries Queue objects

SYNOPSIS

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

#
# Open a queue for input, loop getting messages, updating some
# database with the data.
#
my $qmgr_obj = MQSeries::QueueManager->
  new(QueueManager => 'some.queue.manager');
my $queue = MQSeries::Queue->
  new(QueueManager => $qmgr_obj,
      Queue        => 'SOME.QUEUE',
      Mode         => 'input_exclusive',
     ) or die("Unable to open queue.\n");

while (1) {
  my $getmessage = MQSeries::Message->new();

  $queue->
    Get(Message => $getmessage,
        Sync    => 1,
       ) or die("Unable to get message\n" .
                "CompCode = " . $queue->CompCode() . "\n" .
                "Reason = " . $queue->Reason() . "\n");

  if ( UpdateSomeDatabase($getmessage->Data()) ) {
      $qmgr_obj->Commit()
        or die("Unable to commit changes to queue.\n" .
               "CompCode = " . $queue->CompCode() . "\n" .
               "Reason = " . $queue->Reason() . "\n");
  } else {
      $qmgr_obj->Backout()
        or die("Unable to backout changes to queue.\n" .
               "CompCode = " . $queue->CompCode() . "\n" .
               "Reason = " . $queue->Reason() . "\n");
  }
}

#
# Put a message into the queue, using Storable to allow use of
# references as message data. (NOTE: this is done for you if use the
# MQSeries::Message::Storable class.)
#
use Storable;
my $queue = MQSeries::Queue->new
  (
   QueueManager       => $qmgr_obj,
   Queue              => 'SOME.QUEUE',
   Mode               => 'output',
   PutConvert         => \&Storable::nfreeze,
   GetConvert         => \&Storable::thaw,
  )
  or die("Unable to open queue.\n");

my $putmessage = MQSeries::Message->new
  (
   Data => {
            a => [qw( b c d )],
            e => {
                  f => "Huh?",
                  g => "Wow!",
                 },
            h => 42,
           },
  );

$queue->Put( Message => $putmessage )
  or die("Unable to put message onto queue.\n" .
         "CompCode = " . $queue->CompCode() . "\n" .
         "Reason = " . $queue->Reason() . "\n");

#
# Alternate mechanism for specifying the conversion routines.
#
my $queue = MQSeries::Queue->new
  (
   QueueManager       => $qmgr_obj,
   Queue              => 'SOME.QUEUE',
   Mode               => 'output',
  )
  or die("Unable to open queue.\n");

my $putmessage = MQSeries::Message->new
  (
   Data => {
            a => [qw( b c d )],
            e => {
                  f => "Huh?",
                  g => "Wow!",
                 },
            h => 42,
           },
  );

$queue->Put(Message    => $putmessage
            PutConvert => \&Storable::freeze,
           )
  or die("Unable to put message onto queue.\n" .
         "CompCode = " . $queue->CompCode() . "\n" .
         "Reason = " . $queue->Reason() . "\n");

DESCRIPTION

The MQSeries::Queue object is an OO mechanism for opening MQSeries Queues, and putting and getting messages from those queues, with an interface which is much simpler than the full MQI.

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

The primary value added by this interface is logic to retry the connection under certain failure conditions. Basically, any Reason Code which represents a transient condition, such as a Queue Manager shutting down, or a connection lost (possible due to a network glitch?), will result in the MQCONN call being retried, after a short sleep. See below for how to tune this behavior.

This is intended to allow developers to write MQSeries applications which recover from short term outages without intervention. This behavior is critically important to the authors applications, but may not be right for yours.

METHODS

new

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

Key                           Value
===                           =====
QueueManager                  MQSeries::QueueManager object
Queue*                        String, or ARRAY reference (distribution list)
Mode*                         String
Options*                      MQOPEN 'Options' values
CloseOptions                  MQCLOSE 'Options' values
DynamicQName                  String
DisableAutoResize             Boolean
AutoOpen                      Boolean
ObjDesc                       HASH Reference
Carp                          CODE Reference
PutConvert                    CODE Reference
GetConvert                    CODE Reference
CompCode                      Reference to Scalar Variable
Reason                        Reference to Scalar Variable
RetrySleep                    Numeric
RetryCount                    Numeric
RetryReasons                  HASH Reference
SelectionString               String (MQ v7)

NOTE: Only one or the 'Options' or 'Mode' keys can be specified. They are mutually exclusive. If 'AutoOpen' is given, then both 'Options' and 'Mode' are optional, as they can be passed directly to the Open() method.

QueueManager

The Queue Manager to connect to must be specified, unless you want to connect to the "default" queue manager, and your site supports such a configuration.

This can either be an MQSeries::QueueManager object, or the name of the Queue Manager. Specifying the queue manager name is deprecated and will stop working in a future release.

Queue

The name of the Queue obviously must be specified. This can be either a plain ASCII string, indicating a single queue, or an ARRAY reference, indicating a distribution list. There are three ways to specify the list.

The list may be a simple array of strings:

$queue = MQSeries::Queue->new
  (
   QueueManager       => $qmgr_obj,
   Queue              => [qw( QUEUE1 QUEUE2 QUEUE3 )],
  )

or, it can be an array of arrays, each one specifying the queue and queue manager name of the target queue:

$queue = MQSeries::Queue->new
  (
   QueueManager       => $qmgr_obj,
   Queue              => [
                          [qw( QUEUE1 QM1 )],
                          [qw( QUEUE2 QM2 )],
                          [qw( QUEUE3 QM3 )],
                         ],
  )

or finally, it can be an array of hash references, each naming the queue and queue manager:

$queue = MQSeries::Queue->new
  (
   QueueManager       => $qmgr_obj,
   Queue              =>
   [
    {
     ObjectName       => 'QUEUE1',
     ObjectQMgrName   => 'QM1',
    },
    {
     ObjectName       => 'QUEUE2',
     ObjectQMgrName   => 'QM2',
    },
    {
     ObjectName       => 'QUEUE3',
     ObjectQMgrName   => 'QM3',
    },
   ],
  )

In the latter two cases, the queue manager names are optional. Which method to use is largely a choice of style.

Mode

If the Mode key is specified, then the Options key may NOT be specified. These are mutually exclusive.

The Mode is a shorthand for opening the Queue for output or input, without requiring the developer to work with the Options flags directly. The mode may have one of the following values, which implies the Options shown.

Mode Value       Equivalent MQOPEN Options
==========       =========================
input            MQOO_INPUT_AS_Q_DEF | MQOO_FAIL_IF_QUIESCING
input_shared     MQOO_INPUT_SHARED | MQOO_FAIL_IF_QUIESCING
input_exclusive  MQOO_INPUT_EXCLUSIVE | MQOO_FAIL_IF_QUIESCING
output           MQOO_OUTPUT | MQOO_FAIL_IF_QUIESCING
Options

If the Options key is specified, then the Mode key may NOT be specified. These are mutually exclusive. This is a used as-is as the Options field in the MQOPEN call. Refer to the MQI documentation on MQOPEN() for more details.

CloseOptions

This option allows you to specify the MQCLOSE() Options to be used when the perl object destructor closes the queue for you. Since there are many close options to begin with, this is primarily useful for creating Permanent Dynamic queues that you want to automatically destroy when you are finished with them.

The value specified here will be passed directly to the MQCLOSE() call, so it should be specified as:

CloseOptions    => MQSeries::MQCO_DELETE_PURGE,

for example.

DynamicQName

This is the template string to use when opening a dynamic queue. This is only relevant is the Queue specified is a model queue. Normally, this would be some kind of string ending in a '*', resulting in a unique queue name for the application.

DisableAutoResize

This is a Boolean value, which if true, will disable the automatic resizing of the message buffer when it is either truncated, or the converted message will not fit.

See the Get() method documentation for more information.

AutoOpen

This is an optional parameter that defaults to true. If the value of this argument is false, then the constructor will not implicitly call the Open() method, thus requiring the application to call it itself. This allows for more fine-grained error checking, since the constructur will then fail only if there is a problem parsing the constructor arguments. The subsequent call to Open() can be error checked independently of the new() constructor.

ObjDesc

The value of this key is a hash reference which sets the key/values of the ObjDesc structure. See the "MQSeries Application Programming Reference" documentation for the possible keys and values of the MQOD 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 $queue = MQSeries::Queue->new
  (
   QueueManager       => $qmgr_obj,
   Queue              => 'SOME.QUEUE',
   Carp               => \&MyLogger,
  ) or die("Unable to connect to queue manager.\n");

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

PutConvert, GetConvert

These are CODE references to subroutines which are used to convert the data in a MQSeries::Message object prior to passing it to the MQPUT MQI call, or convert the data retrieved from the queue by the MQGET MQI call before inserting it into a MQSeries::Message object.

See the MQSeries::QueueManager documentation for details on the calling and error handling syntax of these subroutines, as well as an example using Storable.pm to pass perl references around in MQSeries messages.

If this key is not specified, then the MQSeries::Queue objects will inherit these CODE references from the MQSeries::QueueManager object. If the QueueManager key was given as a name, and not an object, then no conversion is performed.

Note that these can be overridden for individual Put() or Get() calls, if necessary for a single message, just as PutConvert can be overridden for a single Put1() call (see MQSeries::QueueManager docs).

Also, note that to disable these for a single message, or a single queue, one would simply pass a function that returns its first argument.

PutConvert => sub { return $_[0]; },
GetConvert => sub { return $_[0]; },

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

CompCode, Reason

When the constructor encounters an error, it returns nothing, and you can not make method calls off of a non-existent object. Thus, you do not have access to the CompCode() and Reason() method calls. If you want to extract these values, you will have to pass a scalar reference value to the constructor, for example:

my $CompCode = MQCC_FAILED;
my $Reason = MQRC_UNEXPECTED_ERROR;

my $queue = MQSeries::Queue->new
  (
   QueueManager               => $qmgr_obj,
   Queue                      => 'SOME,QUEUE',
   CompCode                   => \$CompCode,
   Reason                     => \$Reason,
  ) || die "Unable to open queue: CompCode => $CompCode, Reason => $Reason\n";

But, this is ugly (authors opinion, but then, he gets to write the docs, too).

NOTE: If you let the MQSeries::Queue object implicitly create the MQSeries::QueueManager object, and that fails, you will NOT get the CompCode/Reason values which resulted. This is intentional. If you want this level of granularity, then instantiante the MQSeries::QueueManager object yourself, and pass it to the MQSeries::Queue constructor.

See the ERROR HANDLING section as well.

RetryCount

The call to MQOPEN() (implemented via the Open() method), can be told to retry the failure for a specific list of reason codes. This functionality is only enabled if the RetryCount is non-zero. By default, this value is zero, and thus retries are disabled.

RetrySleep

This argument is the amount of time, in seconds, to sleep between subsequent retry attempts.

RetryReasons

This argument is either an ARRAY or HASH reference indicating the specific reason code for which retries will be attempted. If given as an ARRAY, the elements are simply the reason codes, and if given as a HASH, then the keys are the reason codes (and the values ignored).

SelectionString

This parameter is only supported if the module has been compiled with the MQ v7 libraries. It specifies the selector, which means the Get method will only return messages with matching properties. See the documentation for the MQSeries::Properties class for more details on message properties.

Open

This method will accept the following arguments which can be passed to the constructor (new()), and it merely calls Open() to open the actual queue object.

Key                           Value
===                           =====
Mode                          String
Options                       MQOPEN 'Options' values
RetrySleep                    Numeric
RetryCount                    Numeric
RetryReasons                  HASH Reference

This method is called automatically by the constructor, unless the AutoOpen argument is given.

Note that this is a new method as of the 1.06 release, and is provided to enable more fine grained error checking. See the ERROR HANDLING section.

Close

The arguments to this method are a hash of key/value pairs, and currently only one key is supported: "Options". The value is the Options argument to MQCLOSE(). This will override the "CloseOptions" passed to the constructor. This method merely calls MQCLOSE() to close the actual queue object.

It is important to note that normally, this method need not be called, since it is implicitly called via the object destructor. If the Close() call errors need to be handled, then it can be done explicitly. See the ERROR HANDLING section.

Put

This method wraps the MQPUT call. The arguments are a hash, with the following key/value pairs (required keys are marked with a '*'):

Key         Value
===         =====
Message*    MQSeries::Message object
PutMsgOpts  HASH Reference
PutMsgRecs  ARRAY Reference
Sync        Boolean
PutConvert  CODE Reference
Properties  HASH Reference or MQSeries::Properties object

The return value is true or false, depending on the success of the underlying MQPUT() call. If the operation fails, then the Reason() and CompCode() methods will return the appropriate error codes, if the error was an MQSeries error.

If a PutConvert() method failed before the actual MQPUT() function was called, then the Reason() code will be MQRC_UNEXPECTED_ERROR, and the PutConvertReason() will be true. All of the PutConvert() methods supplied with the various MQSeries::Message subclasses in this distribution will generate some form of error via carp (or the Carp attribute of the objects, if overridden).

Message

This argument is the message to be placed onto the queue. The value must be an MQSeries::Message object.

PutMsgOpts

This option allows the programmer complete control over the PutMsgOpts structure passed to the MQPUT() call. This may conflict with the 'Sync' option; see below.

The default options specified by the OO API are

MQGMO_FAIL_IF_QUIESCING

See the MQPUT() documentation for the use of PutMsgOpts.

PutMsgRecs

This argument is relevant only when using distribution lists.

The value is an ARRAY reference, specifying the put message records for the individual queues in the distribution list. Normally, these are specified as part of the PutMsgOpts, but this API attempts to hide the complexity of the PutMsgOpts structure from the user.

When using distribution lists, PutMsgRecs are often necessary to control how the MsgId, CorrelId, and three other specific fields in the MsgDesc are handled.

For details, see the MQPUT() and MQPUT1() documentation in MQSeries(3).

Sync

This is a flag to indicate that the Syncpoint option is to be used, and the message(s) not committed to the queue until an MQBACK, MQCOMM or MQDISC call is made. These are both wrapped with the queue manager Backout(), Commit() and Disconnect() methods respectively.

The value is simply interpreted as true or false.

If the Sync option is combined with the PutMsgOpts option, the Options field in the PutMsgOpts is checked for compatibility. If the Sync flag is true and the PutMsgOpts specifies MQseries::MQPMO_NO_SYNCPOINT, or vice versa, a fatal error is raised. If no conflict exists, the Sync flag amends the PutMsgOpts.

PutConvert

This is a means of overriding the PutConvert routine specified for the MQSeries::Queue object, for a single Put. See the new() documentation for more details.

Properties

This parameter is only supported if the module has been compiled with the MQ v7 libraries. It allows properties to be specified with the message. This can be used for selectors or for publish/subscribe.

The Properties parameter can be a hash reference or an MQSeries::Properties object. If it is a hash reference, it can be specified in two ways: as key/value pairs, or with property options.

Specifying the proeprties as key/value pairs is straightforward:

Properties => { 'perl.MQSeries.label'    => 'important',
                'perl.MQSeries.customer' => 'BigCompany',
              }

In this case, the property values are specified to MQ as strings, which is usually the correct thing to do. However, property options can be specified if so desired:

Properties => { 'perl.MQSeries.label' => 'important',
                'perl.MQSeries.price' => { Type  => MQSeries::MQTYPE_FLOAT64,
                                           Value => '8.99',
                                         },
                'perl.MQSeries.count' => { Type  => MQSeries::MQTYPE_INT32,
                                           Value => 12,
                                         },
              }

In addition to Name and Value, you can also specify Encoding and CCSID.

Get

This method wraps the MQGET call. The arguments are a hash, with the following key/value pairs (required keys are marked with a '*'):

Key                Value
===                =====
Message*           MQSeries::Message object
GetMsgOpts         HASH Reference
Wait               Numeric Value
Sync               Boolean
DisableAutoResize  Boolean
GetConvert         CODE Reference
Convert            Boolean (default: 1)

The return value of Get() is either 1, 0 or -1. Success or failure can still be interpreted in a Boolean context, with the following caveat. A value of 1 is returned when a message was successfully retrieved from the queue. A value of 0 is returned if some form of error was encountered. A value of -1 is returned when no message was retrieved, but the MQGET call failed with a Reason Code of "MQRC_NO_MSG_AVAILABLE".

The last condition (-1) may or may not be an error, depending on your application. This merely indicates that a message matching the specified MsgDesc criteria was not found, or perhaps the queue was just empty. You have to decide how to handle this.

The return value of 0 may indicate an error in either the MQSeries call itself, or if applicable, the failure of any GetConvert() method called after a successful MQGET() call. In this case, the GetConvertReason() should be checked, as this error may indicate an invalid or improperly formatted message. This is akin to an error encountered while parsing the body of the message.

By default, the Get() method will also handle the message buffer size being too small for one very specific case.

Reason == MQRC_TRUNCATED_MSG_FAILED

In this case, the BufferLength of the Message object is reset to the DataLength value returned by the MQGET() call, and the MQGET() call is redone.

Note that this functionality can be disabled, if not desired, by specifying DisableAutoResize as an argument to either the MQSeries::Queue->new() constructor or the Get() method.

Message

This argument is the MQSeries::Message object into which the message extracted from the queue is placed. This can be a 'raw' MQSeries::Message, or it can be one with the MsgId, or some other key in the MsgDesc explicitly specified, in order to retrieve a specific message. See MQSeries::Message documentation for more details.

GetMsgOpts

This option allows the programmer complete control over the GetMsgOpts structure passed to the MQGET() call. If this option is specified, then the Sync, Wait and Convert options may modify the 'Options' field in the get-message options or raise a fatal error; see below.

The default options specified by the OO API are

MQGMO_FAIL_IF_QUIESCING
MQGMO_CONVERT

See the MQGET() documentation for the use of GetMsgOpts.

Wait

This is a numeric or symbolic value, interpreted as follows. A symbolic value is a number ending on 's' for seconds or 'm' for minutes, which will be converted to the appropriate numeric value. If the value is greater than zero, then the MQGMO_WAIT option is used, and the value is set as the WaitInterval in the GetMsgOpts structure.

Remember, if a numeric value is specified, it is interpreted by the API as a number of milliseconds, not seconds (the rest of the OO-API uses seconds). Therefore, a symbolic value like "30s" or "2m" is preferred.

If the value is 0, then the MQGMO_NO_WAIT option is used.

If the value is -1, then the MQGMO_WAIT option is used, and the WaitInterval is set to MQWI_UNLIMITED, meaning the MQGET call will block until a message appears on the queue.

The default is 0, the same as the MQGET() call itself.

NOTE: MQWI_UNLIMITED should be used with caution, as applications which block forever can prevent queue managers from shutting down elegantly, in some cases.

If the Wait option is combined with the GetMsgOpts option, it will override the MQGMO_WAIT or MQGMO_NO_WAIT flag set in the GetMsgOpts.

Sync

This is a flag to indicate that the Syncpoint option is to be used, and the message(s) not committed to the queue until an MQBACK or MQCMIT call is made. These are both wrapped with the Backout() and Commit() methods respectively.

The value is simply interpreted as true or false.

If the Sync option is combined with the GetMsgOpts option, the Options field in the GettMsgOpts is checked for compatibility. If the Sync flag is true and the GettMsgOpts specifies MQGMO_NO_SYNCPOINT, or vice versa, a fatal error is raised. If no conflict exists, the Sync flag amends the GetMsgOpts.

Convert

This is a flag to indicate that the conversion option is to be used. The value is simply interpreted as true or false; if omitted, the default is true.

The only reason to turn this option off is when trying to read binary messages (MQFMT_NONE) generated in a different encoding.

If the Convert option is combined with the GetMsgOpts option, it will override the MQGMO_CONVERT flag set in the GetMsgOpts.

DisableAutoResize

This is a Boolean value, which if true, will disable the automatic resizing of the message buffer when it is either truncated, or the converted message will not fit.

GetConvert

This is a means of overriding the GetConvert routine specified for the MQSeries::Queue object, for a single Get. See the new() documentation for more details.

If the module has been compiled for MQ v7 and the queue manager connected to runs MQ v7, then the MQGET call retrieves the message proeprties by default. After the message has been read, the Properties method of the MQSeries::Message object can be called to retrieve the message properties. See the documentation of the MQSeries::Properties class for an example.

Inquire

This method is an interface to the MQINQ() API call, however, it takes more convenient, human-readable strings in place of the C macros for the selectors, as well as supports more readable strings for some of the data values as well.

For example, to query the MaxMsgLength and MaxQDepth of a queue:

my %qattr = $queue->Inquire( qw(MaxMsgLength MaxQDepth) );

The argument to this method is a list of "selectors", or Queue attributes, to be queried. The following table shows the complete set of possible keys, and their underlying C macro.

Note that this list is all-inclusive, and that many of these are not supported on some of the MQSeries releases or platforms. Consult the IBM documentation for such details.

Key                         Macro
===                         =====
AlterationDate		MQCA_ALTERATION_DATE,
AlterationTime		MQCA_ALTERATION_TIME,
BackoutRequeueName		MQCA_BACKOUT_REQ_Q_NAME,
BackoutThreshold		MQIA_BACKOUT_THRESHOLD,
BaseQName			MQCA_BASE_Q_NAME,
BaseType			MQIA_BASE_TYPE,	
CFStructure			MQCA_CF_STRUC_NAME,
CLWLQueuePriority		MQIA_CLWL_Q_PRIORITY,
CLWLQueueRank		MQIA_CLWL_Q_RANK,
CLWLUseQ			MQIA_CLWL_USEQ,	
ClusterDate			MQCA_CLUSTER_DATE,
ClusterName			MQCA_CLUSTER_NAME,
ClusterNamelist		MQCA_CLUSTER_NAMELIST,
ClusterQMgrName		MQCA_CLUSTER_Q_MGR_NAME,
ClusterQType		MQIA_CLUSTER_Q_TYPE,
ClusterTime			MQCA_CLUSTER_TIME,
CreationDate		MQCA_CREATION_DATE,
CreationTime		MQCA_CREATION_TIME,
CurrentQDepth		MQIA_CURRENT_Q_DEPTH,
DefBind			MQIA_DEF_BIND,
DefinitionType		MQIA_DEFINITION_TYPE,
DefInputOpenOption		MQIA_DEF_INPUT_OPEN_OPTION,
DefPersistence		MQIA_DEF_PERSISTENCE,
DefPriority			MQIA_DEF_PRIORITY,
DefPutResponse		MQIA_DEF_PUT_RESPONSE_TYPE,
DefReadAhead		MQIA_DEF_READ_AHEAD,	
DistLists			MQIA_DIST_LISTS,
HardenGetBackout		MQIA_HARDEN_GET_BACKOUT,
HighQDepth			MQIA_HIGH_Q_DEPTH,
InhibitGet			MQIA_INHIBIT_GET,
InhibitPut			MQIA_INHIBIT_PUT,
InitiationQName		MQCA_INITIATION_Q_NAME,
MaxMsgLength		MQIA_MAX_MSG_LENGTH,
MaxQDepth			MQIA_MAX_Q_DEPTH,
MsgDeliverySequence		MQIA_MSG_DELIVERY_SEQUENCE,
MsgDeqCount			MQIA_MSG_DEQ_COUNT,
MsgEnqCount			MQIA_MSG_ENQ_COUNT,
NonPersistentMsgClass	MQIA_NPM_CLASS,
OpenInputCount		MQIA_OPEN_INPUT_COUNT,
OpenOutputCount		MQIA_OPEN_OUTPUT_COUNT,
PageSetId			MQIA_PAGESET_ID,
ProcessName			MQCA_PROCESS_NAME,
PropertyControl		MQIA_PROPERTY_CONTROL,
QDepthHighEvent		MQIA_Q_DEPTH_HIGH_EVENT,
QDepthHighLimit		MQIA_Q_DEPTH_HIGH_LIMIT,
QDepthLowEvent		MQIA_Q_DEPTH_LOW_EVENT,
QDepthLowLimit		MQIA_Q_DEPTH_LOW_LIMIT,
QDepthMaxEvent		MQIA_Q_DEPTH_MAX_EVENT,
QDesc			MQCA_Q_DESC,
QMgrIdentifier		MQCA_Q_MGR_IDENTIFIER,
QName			MQCA_Q_NAME,
QNames			MQCACF_Q_NAMES,
QueueAccounting		MQIA_ACCOUNTING_Q,
QueueMonitoring		MQIA_MONITORING_Q,
QueueStatistics		MQIA_STATISTICS_Q,
QServiceInterval		MQIA_Q_SERVICE_INTERVAL,
QServiceIntervalEvent	MQIA_Q_SERVICE_INTERVAL_EVENT,
QType			MQIA_Q_TYPE,
RemoteQMgrName		MQCA_REMOTE_Q_MGR_NAME,
RemoteQName			MQCA_REMOTE_Q_NAME,
RetentionInterval		MQIA_RETENTION_INTERVAL,
Scope			MQIA_SCOPE,
Shareability		MQIA_SHAREABILITY,
StorageClass		MQCA_STORAGE_CLASS,
TimeSinceReset		MQIA_TIME_SINCE_RESET,
TPipeNames			MQCA_TPIPE_NAME,
TriggerControl		MQIA_TRIGGER_CONTROL,
TriggerData			MQCA_TRIGGER_DATA,
TriggerDepth		MQIA_TRIGGER_DEPTH,
TriggerMsgPriority		MQIA_TRIGGER_MSG_PRIORITY,
TriggerType			MQIA_TRIGGER_TYPE,
Usage			MQIA_USAGE,
XmitQName			MQCA_XMIT_Q_NAME,

The return value of this method is a hash, whose keys are those given as arguments, and whose values are the queried queue attributes. In most cases, the values are left unmolested, but in the following cases, the values are mapped to more readable strings.

DefBind (integer)
Key                         Macro
===                         =====
OnOpen                      MQBND_BIND_ON_OPEN
NotFixed                    MQBND_BIND_NOT_FIXED
DefinitionType (integer)
Key                         Macro
===                         =====
Permanent                   MQQDT_PERMANENT_DYNAMIC
Temporary                   MQQDT_TEMPORARY_DYNAMIC
DefInputOpenOption (integer)
Key                         Macro
===                         =====
Exclusive                   MQOO_INPUT_EXCLUSIVE
Shared                      MQOO_INPUT_SHARED
MsgDeliverySequence (integer)
Key                         Macro
===                         =====
FIFO                        MQMDS_FIFO
Priority                    MQMDS_PRIORITY
QServiceIntervalEvent (integer)
Key                         Macro
===                         =====
High                        MQQSIE_HIGH
None                        MQQSIE_NONE
OK                          MQQSIE_OK
QType (integer)
Key                         Macro
===                         =====
Alias                       MQQT_ALIAS
All                         MQQT_ALL
Cluster                     MQQT_CLUSTER
Local                       MQQT_LOCAL
Model                       MQQT_MODEL
Remote                      MQQT_REMOTE
Scope (integer)
Key                         Macro
===                         =====
Cell                        MQSCO_CELL
QMgr                        MQSCO_Q_MGR
TriggerType (integer)
Key                         Macro
===                         =====
Depth                       MQTT_DEPTH
Every                       MQTT_EVERY
First                       MQTT_FIRST
None                        MQTT_NONE
Usage (integer)
Key                         Macro
===                         =====
Normal                      MQUS_NORMAL
XMITQ                       MQUS_TRANSMISSION

Set

This method is an interface to the MQSET() API call, and like Inquire(), it takes more convenient, human-readable strings in place of the C macros.

For example, to put inhibit a queue:

$queue->Set( InhibitPut => 1 );

The argument to this method is a hash of key/value pairs representing queue attributes to be set. The MQSET() API supports setting a very limited subset of specific queue attributes. The following table shows the complete set of possible keys, and their underlying C macros.

Key                         Macro
===                         =====
InhibitGet                  MQIA_INHIBIT_GET
InhibitPut                  MQIA_INHIBIT_PUT
DistLists                   MQIA_DIST_LISTS
TriggerControl              MQIA_TRIGGER_CONTROL
TriggerData                 MQCA_TRIGGER_DATA
TriggerDepth                MQIA_TRIGGER_DEPTH
TriggerMsgPriority          MQIA_TRIGGER_MSG_PRIORITY
TriggerType                 MQIA_TRIGGER_TYPE

In addition, the data value for the "TriggerType" key can have one of the following values:

Key                         Macro
===                         =====
Depth                       MQTT_DEPTH
Every                       MQTT_EVERY
First                       MQTT_FIRST
None                        MQTT_NONE

All of the other values are simply Boolean (0 or 1), with the exception of "TriggerData", which is a string.

This method call returns true upon success, and false upon failure. CompCode() and Reason() will be set appropriately.

ObjDesc

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

QueueManager

This method takes no arguments, and returns the MQSeries::QueueManager object used by the queue.

CompCode

This method returns the MQI Completion Code for the most recent MQI call attempted.

Reason

This method returns the MQI Reason Code for the most recent MQI call attempted.

PutConvertReason

This method returns a true of false value, indicating if a PutConvert method failed or not. Similar to the MQRC reason codes, false indicates success, and true indicates some form of error. If there was no PutConvert method called, this will always return false.

GetConvertReason

This method returns a true of false value, indicating if a GetConvert method failed or not. Similar to the MQRC reason codes, false indicates success, and true indicates some form of error. If there was no GetConvert method called, this will always return false.

Reasons

This method call returns an array reference, and each member of the array is a Response Record returned as a possible side effect of calling a Put() method to put a message to a distribution list.

The individual records are hash references, with two keys: CompCode and Reason. Each provides the specific CompCode and Reason associated with the put of the message to each individual queue in the distribution list, respectively.

MQOPEN RETRY SUPPORT

Normally, when MQOPEN() fails, the method that called it (Open() or new()) also fails. It is possible to have the Open() method retry the MQOPEN() call for a specific set of reason codes.

By default, the retry logic is disabled, but it can be enabled by setting the RetryCount to a non-zero value. The list of reason codes defaults to just MQRC_OBJECT_IN_USE, but a list of retryable codes can be specified via the RetryReasons argument.

You are probably wondering why this logic is useful for MQOPEN(). The choice of the default RetryReasons is not without its own reason.

Consider an application that opens a queue for exclusive input. If that application crashes and restarts, there will typically be a window of time when the queue manager has not yet noticed that the crashed application instance has died. The application which has been restarted will not fail to open the queue, and MQOPEN() will set the reason to MQRC_OBJECT_IN_USE.

By retrying this particular reason code, and tuning the RetryCount and RetrySleep to be consistent with the timeout on the queue manager, applications can restart, reconnect and reopen these queues transparently.

There are almost certainly other scenarios where the RetryReasons may need to be customized, and thus the code supports this flexibility.

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.

In addition, the most recent MQI Completion and Reason codes will be available via the CompCode() and Reason() methods:

$queue->CompCode()
$queue->Reason()

When distribution lists are used, then it is possible for a list of reason codes to be returned by the API. Normally, these are buried inside the ObjDesc strucure, but they are also available via the

$queue->Reasons()

method. In this case, the $queue->Reason() will always return MQRC_MULTIPLE_REASONS. The return value of the Reasons() method is an array reference, and each array item is a hash reference with two keys: CompCode and Reason. These correspond, respectively, with the CompCode and Reason associated with the individual queues in the distribution list.

For example, the Reason code associated with the 3rd queue in the list would be:

$queue->Reasons()->[2]->{Reason}

In the case of the constructor new(), which returns nothing when it fails, these methods are not available. Most applications will not need to handle the specific CompCode and Reason when the instantiation fails, but if necessary, these can be obtained in one of two ways.

The older method, which is supported for backwards compabitility but strongly discouarged, is to pass references to scalar variables to new(). See the new() documentation above for more details.

The newer method would be to explicitly call the Open() method, and error check it yourself. This will mean that the constructor will now fail only if there is an error processing the constructor arguments, as opposed to an error in the MQSeries infrastructure.

Some examples should make this clear.

The simplest way to create an MQSeries::Queue object is:

my $queue = MQSeries::Queue->new
  (
   QueueManager               => 'some.queue.manager',
   Queue                      => 'SOME.QUEUE',
   Mode                       => 'input',
  ) || die;

But in this case, either the connection to the queue manager or the open of the queue could fail, and your application will not be able to determine why.

In order to explicitly have access to the CompCode and Reason one would do the following:

# Explicitly create your own MQSeries::QueueManager object
my $qmgr = MQSeries::QueueManager->new
  (
   QueueManager               => 'some.queue.manager',
   AutoConnect                => 0,
  ) || die "Unable to instantiate MQSeries::QueueManager object\n";

# Call the Connect method explicitly
unless ( $qmgr->Connect() ) {
  die("Connection to queue manager failed\n" .
      "CompCode => " . $qmgr->CompCode() . "\n" .
      "Reason   => " . $qmgr->Reason() . "\n");
}

my $queue = MQSeries::Queue->new
  (
   QueueManager               => $qmgr,
   Queue                      => 'SOME.QUEUE',
   Mode                       => 'input',
   AutoOpen                   => 0,
  ) || die "Unable to instantiate MQSeries::Queue object\n";

# Call the Open method explicitly
unless ( $queue->Open() ) {
  die("Open of queue failed\n" .
      "CompCode => " . $queue->CompCode() . "\n" .
      "Reason   => " . $queue->Reason() . "\n");
}

SEE ALSO

MQSeries(3), MQSeries::QueueManager(3), MQSeries::Message(3), MQSeries::Properties(3)