Search
Categories
Documents
MQSeries - Perl extension for MQSeries support (Displayed)
README
|
MQSeries - Perl extension for MQSeries support
MQSeries - Perl extension for MQSeries support
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::RulesFormat
MQSeries::Message::DeadLetter
There is also a set of modules which provide an interface to the
optional Publish/Subscribe system, which is available as a support
pack for the distributed platforms using Version 5 of MQSeries.
MQSeries::PubSub::Broker
MQSeries::PubSub::Stream
MQSeries::PubSub::Command (docs only, not used directly)
MQSeries::PubSub::Message
MQSeries::PubSub::AdminMessage
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.
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.
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.
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.
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.
$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.
$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($Hconn,$CompCode,$Reason);
The calling convention of this subroutine is identical to the C API.
$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($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($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($Hconn,$CompCode,$Reason);
The calling convention of this subroutine is identical to the C API.
MQCMIT($Hconn,$CompCode,$Reason);
The calling convention of this subroutine is identical to the C API.
$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($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.
($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($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.
This routine has been deprecated, and is no longer supported. The
next release will remove it from the documentation altogether.
Equivalent functionality is available via the MQDecodePCF subroutine,
which is optionally exported from the MQSeries::Message::PCF module.
The author highly recommends using the OO abstraction via
MQSeries::Message::Event, and interface which is supported and will
remain part of this API permanently.
($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....
($ReasonText) = MQReasonToText($Reason);
This is nothing more than a trivial interface to MQReasonToStrings,
returning just the one value (the reason text).
($ReasonMacro) = MQReasonToMacro($Reason);
This is nothing more than a trivial interface to MQReasonToStrings,
returning just the one value (the MQRC_* macro as a string).
Information
|
This site is currently in testing, it is not yet operating using the full database. Until it is officially launched you may wish to visit Help-Site Computer Manuals. After launch, this site (HelpSpy) will replace Help-Site. Information about the spider which is currently trawling the Internet looking for links to add to this directory can be found here. |
| 
