The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MQSeries-1.34
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ MQSeries

NAME

MQSeries - Perl extension for MQSeries support

SYNOPSIS

There are two interfaces provided by the MQSeries modules. The first is a straight forward mapping to all of the individual MQI calls, and the second is a value-added, OO interface, which provides a simpler interface to a subset of the full MQI functionality.

The straight MQI mapping is:

  use MQSeries;

  $Hconn = MQCONN($Name,$CompCode,$Reason);
  MQDISC($Hconn,$CompCode,$Reason);

  $Hobj = MQOPEN($Hconn,$ObjDesc,$Options,$CompCode,$Reason);
  MQCLOSE($Hconn,$Hobj,$Options,$CompCode,$Reason);

  MQBACK($Hconn,$CompCode,$Reason);
  MQCMIT($Hconn,$CompCode,$Reason);

  $Buffer = MQGET($Hconn,$Hobj,$MsgDesc,$GetMsgOpts,$BufferLength,$CompCode,$Reason);
  MQPUT($Hconn,$Hobj,$MsgDesc,$PutMsgOpts,$Msg,$CompCode,$Reason);
  MQPUT1($Hconn,$ObjDesc,$MsgDesc,$PutMsgOpts,$Msg,$CompCode,$Reason);

  ($Attr1,...) = MQINQ($Hconn,$Hobj,$CompCode,$Reason,$Selector1,...);
  MQSET($Hconn,$Hobj,$CompCode,$Reason,$Selector1,$Attr1,...);

If the perl5 API is compiled with the version 5 headers and libraries, then the following MQI calls are also available:

  MQBEGIN($Hconn,$BeginOpts,$CompCode,$Reason);
  $Hconn = MQCONNX($Name,$ConnectOpts,$CompCode,$Reason);

There are also some additional utility routines provided which are not part of the MQI, but specific to the perl5 API:

  ($ReasonText,$ReasonMacro) = MQReasonToStrings($Reason);
  ($ReasonText) = MQReasonToText($Reason);
  ($ReasonMacro) = MQReasonToMacro($Reason);

The OO interface is provided in several optional modules. Three of these make up the core OO interface:

  MQSeries::QueueManager
  MQSeries::Queue
  MQSeries::Message

There are several subclasses of MQSeries::Message which handle special message formats:

  MQSeries::Message::Storable
  MQSeries::Message::Event
  MQSeries::Message::PCF
  MQSeries::Message::DeadLetter

There is also a module which provides an interface to the command server PCF messages for MQSeries administration:

  MQSeries::Command

There are two sets of classes that help you follow (tail -f style) and parse the two kinds of log-files written by MQSeries: the FDC files and the error-logs. These classes allow you to write a log monitoring daemon that feeds into syslog or your system management tools.

  MQSeries::ErrorLog::Tail
  MQSeries::ErrorLog::Parser
  MQSeries::ErrorLog::Entry
  MQSeries::FDC::Tail
  MQSeries::FDC::Parser
  MQSeries::FDC::Entry

There is a set of classes that parses configuration and authority files (/var/mqm/mqs.ini, /var/mqm/qmgrs/*/qm.ini, /var/mqm/qmgrs/*/auth/*/*).

  MQSeries::Config::Authority
  MQSeries::Config::Machine
  MQSeries::Config::QMgr

Some internal helper functions are stored in the module:

  MQSeries::Utils

See the documentation for each of these individual modules for more information.

DESCRIPTION

This module provides a perl language interface to MQSeries functions. It uses the standard MQSeries interface except where a perl convention is required or just more useful.

Where data structures are required, this interface uses a hash reference. The keys in the hash are structure element names. If an element is not specified in the hash, a default value will be used. Output elements are updated in the hash as necessary.

Basic Module Usage

By default, this module will export all functions and MQSeries constants into the caller's namespace. This may bloat that module's memory usage by some 400 Kbyte. For that reason, you can also request to only export the functions. To use macros, you would then either import them individually or refer to them using the MQSeries:: prefix.

This leads to the following use statements:

use MQSeries;

The default: export functions and constants.

use MQSeries qw(:functions);

Export just the functions. This should be the way most modules import MQSeries, as it saves 400Kbyte per module importing MQSeries. In order to use a macro, e.g. MQCC_FAILED, you could either add it to the list on the use statement, or refer to MQSeries::MQCC_FAILED.

use MQSeries qw(:constants);

Export just the constants; not very useful.

use MQSeries qw(:all);

The same as the default: export functions and constants.

Server vs. Client API

Compiled MQSeries applications, such as those written in C or C++, have to decide at compile/link time which of the two API styles to use: server (shared memory, same host) or client (TCP/IP, same or remote host). Perl applications can make this decision at runtime, dynamically.

By default, the MQSeries module will try to dynamically determine whether or not the localhost has any queue managers installed, and if so, use the "server" API, otherwise, it will use the "client" API.

This will Do The Right Thing (tm) for most applications, unless you want to connect directly to a remote queue manager from a host which is running other queue managers locally. Since the existence of locally installed queue managers will result in the use of the "server" API, attempts to connect to the remote queue managers will fail with a Reason Code of 2058.

To workaround this problem, you can force the use of either the server or client API explictly by using one of the following use statements.

use MQClient::MQSeries;

This will force the use of the client API, regardless of whether or not there are queue managers on the localhost.

use MQServer::MQSeries;

This will force the use of the server API, and thus only allow connections only to queue managers on the same machine. This normally is not necessary, since the API should detect existence of local queue manager and default to this flavor of access.

The author uses this in one and only one special case: the automated script that installs a queue manager, and then customizes it. When the script first runs, there is usually no local queue manager, but it will need to connect to it using the server API once it is created.

Of course, you can combine the various import options, for example the following is perfectly valid:

  use MQClient::MQSeries qw(:functions);

NOTE: The perl API, when compiled and installed, will normally build both the server and client extensions, but on some platforms one or the other is not available. For example, we currently only support the client API on IRIX, and only the server API on OS/390. Whether or not the server and/or client options are even available depends on how the MQSeries perl API was compiled and installed. Consult your administrator (or whoever built this extension) for such details.

SUBROUTINES

For complete details on each of the following subroutines, please consult the "MQSeries Application Programming Guide" and "MQSeries Application Programming Reference". This documentation will merely document how the perl API and the underlying C API calling and return code conventions vary.

One way in which all of these calls are identical to the C API is in the use of the '$CompCode' and '$Reason' conventions. All of the API calls take these as positional arguments, and the completion code and reason code are written to those variables, respecitively.

In general, all of the C data structures used to pass or return values to each API call are passed or returned as a perl hash reference, specified as a positional argument in the relavent API call.

MQCONN

  $Hconn = MQCONN($Name,$CompCode,$Reason);

This call returns the Hconn value, to be used in subsequent MQI calls. The C API took the $Hconn as a positional parameter, whereas the perl API returns it.

MQCONNX

  $Hconn = MQCONNX($Name,$ConnectOpts,$CompCode,$Reason);

NOTE: This MQI call is only available if the perl5 API is compiled against MQSeries version 5 headers and libraries.

This call returns the Hconn value, to be used in subsequent MQI calls. The C API took the $Hconn as a positional parameter, whereas the perl API returns it.

The $ConnectOpts value is a hash reference, with keys corresponding to the fields of the MQCO structure. This is an input value only.

With the $ConnectOpts, two interior data structures can be provided: ClientConn and SSLConfig. These provide access to the MQCNO and MQSCO options. The two data structures can be used independently; and example of them used in combination is shown below:

  $coption = { 'ChannelName'    => 'Some.Channel.Name',
               'TransportType'  => 'TCP',
               'ConnectionName' => 'hostname(port)',
             };
  $ssl_option = { 'KeyRepository' => '/var/mqm/ssl/key' };
  $Hconn = MQCONNX($qmgr_name, { 'ClientConn' => $coption,
                                 'SSLConfig'  => $ssl_option,
                               }, $cc, $re);

See the application programming reference for details on the additional fields available in the ClientConn data structure.

MQDISC

  MQDISC($Hconn,$CompCode,$Reason);

The calling convention of this subroutine is identical to the C API.

MQOPEN

  $Hobj = MQOPEN($Hconn,$ObjDesc,$Options,$CompCode,$Reason);

In the same way that MQCONN loses one positional parameter, and returns it to the caller, so does MQOPEN remove the $Hobj parameter from the argument list and returns the value.

The $ObjDesc parameter should be a hash reference, for example:

  $ObjDesc = {
              ObjectName        => 'SOME.MODEL.QUEUE',
              DynamicQName      => 'FOOBAR*',
             };

The $Options parameter should be a set of ORed options, for example:

  $Options = MQOO_INPUT_AS_Q_DEF | MQOO_FAIL_IF_QUIESCING;

If a distribution list is being opened, then the list of queues can be specified in one of three ways. The list is given via a new key "ObjectRecs", used to identify the list. This is different from the C-centric approach in the C API, namely to specify the list using the RecsPresent, ObjectRecPtr, etc.

The first method is to specify an array of plain queue names:

  $ObjDesc = {
              ObjectRecs        => [qw( QUEUE1 QUEUE2 QUEUE3 )],
             };

The second method is to specify an array or array references, each giving the QName and QMgrName:

  $ObjDesc = {
              ObjectRecs        => [
                                    [qw( QUEUE1 QM1 )],
                                    [qw( QUEUE2 QM2 )],
                                    [qw( QUEUE3 QM3 )],
                                   ],
             };

Finally, an array of hash references can be specified, each giving the QName and QMgrName via specific keys:

  $ObjDesc = {
              ObjectRecs        => [
                                    {
                                     ObjectName         => 'QUEUE1',
                                     ObjectQMgrName     => 'QM1',
                                    },
                                    {
                                     ObjectName         => 'QUEUE2',
                                     ObjectQMgrName     => 'QM2',
                                    },
                                    {
                                     ObjectName         => 'QUEUE3',
                                     ObjectQMgrName     => 'QM3',
                                    },
                                   ],
             };

In the second and third cases, the queue manager names are always optional. Which method to use is largely a matter of style.

When the Reason Code returned by the API is MQRC_MULTIPLE_REASONS, then these are encoded into an array of hash references, and that array is returned as a new key in the ObjDesc hash, "ResponseRecs". The order of the CompCode/Reason pair in the array corresponds to the order of the queues listed in the ObjectRecs array.

This is best explained in an example. In this case, we used the first, simple list of queue names for our distribution list.

  if ( $Reason == MQRC_MULTIPLE_REASONS ) {
      for ( $index = 0 ; $index <= scalar @{$ObjDesc->{ObjectRecs}} ; $index++ ) {
          next if $ObjDesc->{ResponseRecs}->[$index]->{Reason} == MQRC_NONE;
          print "QName: " . $ObjDesc->{ObjectRecs}->[$index] . "\n";
          print "Reason: " . $ObjDesc->{ResponseRecs}->[$index]->{Reason} . "\n";
          print "CompCode: " . $ObjDesc->{ResponseRecs}->[$index]->{CompCode} . "\n";
      }
  }

MQCLOSE

  MQCLOSE($Hconn,$Hobj,$Options,$CompCode,$Reason);

The calling convention of this subroutine is identical to the C API.

The $Options value is a set of ORed options, for example:

  $Options = MQCO_DELETE_PURGE;

MQBEGIN

  MQBEGIN($Hconn,$BeginOpts,$CompCode,$Reason)

NOTE: This MQI call is only available if the perl5 API is compiled against MQSeries version 5 headers and libraries.

The calling convention of this subroutine is identical to the C API.

The $BeginOpts value is a hash reference, with keys corresponding to the fields of the MQBO structure. This is both an input and output value.

MQBACK

  MQBACK($Hconn,$CompCode,$Reason);

The calling convention of this subroutine is identical to the C API.

MQCMIT

  MQCMIT($Hconn,$CompCode,$Reason);

The calling convention of this subroutine is identical to the C API.

MQGET

  $Buffer = MQGET($Hconn,$Hobj,$MsgDesc,$GetMsgOpts,$BufferLength,$CompCode,$Reason);

One positional parameter, the $Buffer, is removed from the argument list. This is the return value of this subroutine. The $MsgDesc and $GetMsgOpts values are hash references. The $MsgDesc will be populated with the MQMD structure returned by the MQGET call. This is also an input value, and the $MsgDesc data can be populated, for example, with a specific 'CorrelId'.

  $MsgDesc = {
              CorrelId => $correlid,
             };

The $GetMsgOpts hash reference contains the MQGMO data structure fields, for example:

  $GetMsgOpts = {
                 Options => MQGMO_FAIL_IF_QUIESCING | MQGMO_SYNCPOINT | MQGMO_WAIT,
                 WaitInterval => MQWI_UNLIMITED,
                };

MQPUT, MQPUT1

  MQPUT($Hconn,$Hobj,$MsgDesc,$PutMsgOpts,$Msg,$CompCode,$Reason);
  MQPUT1($Hconn,$ObjDesc,$MsgDesc,$PutMsgOpts,$Msg,$CompCode,$Reason);

Both of these calls differ from the C API in the same way as MQGET. Likewise, the $MsgDesc and $PutMsgOpts values are hash references for the appropriate data structures.

If MQPUT1() is being used to put a message to a distribution list, then the $ObjDesc is used in the same way as documented above for MQOPEN(). In addition, there is a special key to the $PutMsgOpts hash which can be specified, and the rest of this discussion applies equally to both MQPUT() and MQPUT1().

The $PutMsgOpts->{PutMsgRecs} value must be an array of hash references, one for each queue opened in the distribution list, interpreted in the same order. Each individual hash reference is interpreted as a single put message record. The keys of each record can be any of:

  MsgId
  CorrelId
  GroupId
  Feedback
  AccountingToken

For example, the following sets the CorrelId the same across all of the messages in a distribution list of three queues.

  $PutMsgOpts = {
                 PutMsgRecs => [
                                {
                                 MsgId          => MQPMO_NEW_MSG_ID,
                                 CorrelId       => $SomeCorrelId,
                                },
                                {
                                 MsgId          => MQPMO_NEW_MSG_ID,
                                 CorrelId       => $SomeCorrelId,
                                },
                                {
                                 MsgId          => MQPMO_NEW_MSG_ID,
                                 CorrelId       => $SomeCorrelId,
                                },
                               ],
                };

Note that the following fields of the $PutMsgOpts hash do not need to be specified:

  PutMsgRecFields (calculated automatically)
  PutMsgRecOffset
  PutMsgRecPtr
  ResponseRecPtr
  ResponseRecOffset

For the MQPUT() call, if the Reason code returned is MQRC_MULTIPLE_REASONS, then these are returned as part of the $PutMsgOpts hash, in the key ResponseRecs. For the MQPUT1() call, these are returned as part of the $ObjDesc hash.

See the MQOPEN() documentation above for the format of this value.

MQINQ

  ($Attr1,...) = MQINQ($Hconn,$Hobj,$CompCode,$Reason,$Selector1,...);

This call differs from the C API significantly. Rather than passing a list of pairs of selectors and attributes, only a list of selectors is passed. The return value is a list of attributed. The C API convention was simply to pass the address for each answer in the arguments, but in perl, it makes more sense to return this as a list.

MQSET

  MQSET($Hconn,$Hobj,$CompCode,$Reason,$Selector1,$Attr1,...);

This call also differs from the C API significantly. The C API took a pointer to an array of selectors, with an argument indicating the length of the array, and a similar pair of values for the attribute values themselves. The perl convention is to list the selectors and attributes in pairs, rather than by passing in an array reference.

MQCRTMH

  $Hmsg = MQCRTMH($Hconn,$CrtMsgHOpts,$CompCode,$Reason);

This call is only available if the module has been compiled with MQ v7. It creates a message handle, which can be used to get/set message properties.

The $CrtMsgHOpts parameter is a MQCMHO data structure, which for MQ v7 only contains an 'Options' field.

  $CrtMsgHOpts = { Options => ( MQSeries::MQCMHO_VALIDATE ) };

The default (listed above) is generally sufficient.

MQDLTMH

  MQDLTMH($Hconn,$Hmsg,$DltMsgHOpts,$CompCode,$Reason)

This call is only available if the module has been compiled with MQ v7. It deletes a message handle previously created with MQCRTMH.

The $DltMsgHOpts parameter is a MQDMHO data structure, which for MQ v7 only contains an 'Options' field, with no options defined. For MQ v7, just specify an empty hash reference.

MQDLTMP

  MQDLTMP($Hconn,$Hmsg,$DltPropOpts,$Name,$CompCode,$Reason)

This call is only available if the module has been compiled with MQ v7. it deletes a message property.

The $DltPropOpts parameter is a MQDMPO parameter, which only contains an 'Options' field.

  $DltPropOpts = { Options => ( MQSeries::MQDMPO_DEL_FIRST ) };

The default (listed above) is generally sufficient.

The $Name parameter is a fully qualified property name.

MQINQMP

  $PropertyValue = MQINQMP($Hconn,$Hmsg,$InqPropOpts,$Name,$PropDesc,$Type,$Length,$CompCode,$Reason)

This call is only available if the module has been compiled with MQ v7. It retrieves a message property. The return value is the value of the property retrieved.

The $InqPropOpts parameter is an MQIMPO data structure.

The $Name parameter is a property name, which may contain a wildcard.

The $PropDesc parameter is an MQPD data structure.

The $Type parameter determines the return type if the option MQSeries::MQIMPO_CONVERT_TYPE is specified as part of the $InqPropOpts parameter. In either case, it is also an output parameter that specifies the returned type of the proeprty, e.g. MQSeries::MQTYPE_STRING.

The $Length parameter is the maximum length of the property value to return. It is also an output parameter that specifies the length of the returned value.

MQSETMP

  MQSETMP($Hconn,$Hmsg,$SetPropOpts,$Name,$PropDesc,$Type,$Value,$CompCode,$Reason)

This call is only available if the module has been compiled with MQ v7. It sets or updates a message property.

The $SetPropOpts parameter is a MQHMSG data structur, which for MQ v7 only contains an 'Options' field.

  $SetPropOpts = { Options => ( MQSeries::MQSMPO_SET_FIRST ) };

The default (listed above) is generally sufficient.

The $Name parameter is the property name.

The $PropDesc parameter is an MQPD data structure.

The $Type parameter specifies the data type of the property, e.g. MQSeries::MQTYPE_STRING or MQSeries::MQTYPE_FLOAT64.

The $Value parameter is the actual proeprty value. It may be undef for string and byte string properties.

MQSTAT

  MQSTAT($Hconn,$StatType,$Stat,$CompCode,$Reason)

This call is only available if the module has been compiled with MQ v7. It returns queue manager asynchronous put status information.

The $StatType parameter must always be MQSeries::MQSTAT_TYPE_ASYNC_ERROR.

The $Stat parameter is a MQSTS data structure must be specified as a hash reference. On output, it includes the MQSTS fields documented in the Application Programming Reference for MQ v7.

MQReasonToStrings

  ($ReasonText,$ReasonMacro) = MQReasonToStrings($Reason);

This subroutine is specific to the perl API, although similar functionality is desperately needed in the other programming languages as well. This takes an MQSeries Reason code, and returns the English language text explaining the reason code, and the macro name. These strings are compiled into the perl module, encoded in the XS routines, after having been extracted from the IBM HTML documentation.

For example, a reason code of 2009 (MQRC_CONNECTION_BROKEN) will return:

  "Connection to queue manager lost."

which looks a lot better in error logs and alerts than 2009.

The macro name itself is also returned as a string, so one could use "MQRC_CONNECTION_BROKEN" in logs, error messages, etc.

In this release, only English language text is returned, but in a future release, these messages will be locale specific. This will almost certainly be implemented with locale-specific DBM files, but you probably do not need to know this just yet....

MQReasonToText

  ($ReasonText) = MQReasonToText($Reason);

This is nothing more than a trivial interface to MQReasonToStrings, returning just the one value (the reason text).

MQReasonToMacro

  ($ReasonMacro) = MQReasonToMacro($Reason);

This is nothing more than a trivial interface to MQReasonToStrings, returning just the one value (the MQRC_* macro as a string).