MQSeries::Message::PCF -- Generic OO and procedural interface to PCF (Programmable Command Format) messages.
# # Here's an example of creating a PCF Command (InquireQueue) to send # to the command server. Note that this example is a bit contrived, # since you would normally use the higher level MQSeries::Command # object for this. # use MQSeries; use MQSeries::Message::PCF; # # The $header hash represents the MQCFH PCF Header. # $header = { Type => MQCFT_COMMAND, Command => MQCMD_INQUIRE_Q, }; # # The $parameters array is an array of hash references, each of # which individually represents one of the PCF parameter structures # (MQCFIN, MQCFST, MQCFIL, or MQCFSL). # $parameters = [ # QName is a string (MQCFST) { Parameter => MQCA_Q_NAME, String => "FOO.*", }, # QType is an integer (MQCFIN) { Parameter => MQIA_Q_TYPE, Value => MQQT_LOCAL, }, # QAttrs in an integer list (MQCFIL) { Parameter => MQIACF_Q_ATTRS, Values => [ MQCA_Q_NAME, MQIA_Q_TYPE, MQCA_Q_DESC, MQIA_MAX_Q_DEPTH, MQIA_MAX_MSG_LENGTH, ], }, # Although not shown in this example, string lists (MQCFSL) have a # structure similar to the integer lists. ]; my $message = MQSeries::Message::PCF->new ( Header => $header, Parameters => $parameters, ) || die; # # The rest of the SYNOPSIS shows the procedural interface, which you # can use directly if you really want to, but the intent was for # MQEncodePCF and MQDecodePCF to be used as building blocks for OO # classes which further abstract the PCF data. See the SEE ALSO # section for a list of modules which do exactly that. # use MQSeries; use MQSeries::Message::PCF qw(MQDecodePCF MQEncodePCF); my $msgdata = MQEncodePCF($header,$parameters); # # The reverse operation would be: # my ($header, $parameters) = MQDecodePCF($msgdata);
This module is both an OO API to PCF messages, and a pair of exportable procedures for encoding and decoding PCF messages. The two functions are imported by other classes which further parse and abstract specific PCF formats.
Note that it the intention of the author to provide specific implementations of each of the standard PCF formats used in the MQSeries product, and the current release already includes support for:
PCF Command Server messages (MQSeries::Command) Performance Events (MQSeries::Message::Event)
If you are reading this documentation with the intention of using it for any of the above standard MQSeries messages, please see the docs for those modules instead.
This module optionally exports the core PCF parsing procedures used by all of the above (MQEncodePCF and MQDecodePCF), and the OO API is provided for completeness (and because, well, it was trivial).
The MQSeries::Message::PCF class is a subclass of MQSeries::Message, so all of the methods of the latter class are also available.
The arguments to the MQSeries::Message::PCF constructor are passed directly to the MQSeries::Message constructor, upon which this object is based. There are two additional keys supported by this class as well: "Header" and "Parameters"
The value of this key is a HASH reference, representing the MQCFH PCF header structure. See below for specific details.
The value of this key is an ARRAY reference of HASH references. Each HASH reference represents one of the PCF parameters structures MQCFIN, MQCFST, MQCFIL, or MQCFSL. See below for details.
Both of these procedures must be explicitly imported by the caller, and they are provided as building blocks for higher level abstractions of the PCF message format. All of the previously mentioned OO classes in the MQSeries heirarchy which implement PCF formats use these procedures in this way.
This takes a pair of HASH references, for the PCF Header and Parameters (format discussed below) and returns a string which is the binary encoding of data into a set of C structures, suitable for use as the message body for an MQSeries message of the appropriate PCF format type.
my $msgdata = MQEncodePCF($header,$parameters);
This routine returns the undefined value if an error is encountered while encoding the data.
This takes a string, which is assumed to be the body of a PCF message, and returns a pair of HASH references, each representing the PCF Header and Parameters data structures (formats discussed below).
my ($header,$parameters) = MQDecodePCF($msgdata);
This routine returns an empty array if an error is encountered while decoding the data.
This is a HASH reference which represents the MQCFH PCF header structure. See the MQCFH documentation for the details of the keys which can be given in this hash, and the specific PCF implementation documentation for the possible values which can be given, since they vary from one usage to another.
Note that the "ParameterCount" key need not be specified, as the MQEncodePCF() subroutine will calculate this automatically, by simply counting the entries in the Parameters ARRAY.
Also, the "StrucLength", and "Version" keys are handled automatically, and need not be given.
When this HASH is returned, all of the structures fields are returned as keys in the HASH, although in most cases, you can ignore most of them.
This is an ARRAY reference or HASH references. Each individual HASH reference represents one of the PCF parameters structures, and each is discussed individually.
In all cases, the "Type" and "StrucLength" keys can be omitted, since the "Type" is derived from the other keys present (if there is a "Value" key, its a MQCFIN, a "String" key, its a MQCFST, etc). In fact, both of these keys will be entirely ignored.
The "Parameter" values depend entirely on the specific usage of the PCF format, with one set of possible values used for PCF command server messages and another for performance events. See the respective documentation for each of these formats for more information.
This is a HASH reference with the following input keys:
Parameter Value
The "Value" must be a numeric value, or an error will be raised.
When returned, it has the following output keys:
Parameter Value Type (always == MQCFT_INTEGER)
This is a HASH reference with the following input keys (optional keys denoted by *):
Parameter String CodedCharSetId*
The "String" must have a string value, or an error will be raised.
When returned, is has the following output keys:
Parameter String CodedCharSetId Type (always == MQCFT_STRING)
Parameter Values
The "Values" must be an ARRAY reference of numeric values, or an error will be raised. Note that the documented "Count" MQCFIL key may be omitted, since it is automatically calculated as the length of the ARRAY.
Parameter Values Type (always == MQCFT_INTEGER_LIST)
Parameter Strings CodedCharSetId*
The "Strings" must be an ARRAY reference of string values, or an error will be raised.Note that the documented "Count" MQCFSL key may be omitted, since it is automatically calculated as the length of the ARRAY.
Parameter Strings CodedCharSetId Type (always == MQCFT_STRING_LIST)
MQSeries::Message::Event(3), MQSeries::Command::Request(3), MQSeries::Command::Response(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.