MQSeries::PubSub::AdminMessage -- OO Class for decoding MQSeries PubSub adminstrative messages
use MQSeries; use MQSeries::PubSub::AdminMessage;
The MQSeries::PubSub::AdminMessage class is an abstraction for parsing the Publish/Subscribe administrative messages which are published in PCF (Programmable Command Format), unlike most PubSub messages which are in the MQRFH (Rules and Formats Format). This class is essentially only used by systems management applications, which would subscribe to the administrative messages published by the Publish/Subscribe broker itself, in the SYSTEM.BROKER.ADMIN.STREAM.
See the "MQSeries Pub/Sub User's Guide", Chapter 14: "Writing system management applications" for more details.
The MQSeries::PubSub::Message class is a subclass of MQSeries::Message, so it inherits all of the latters methods. In addition, the following methods are available (or overridden).
These methods return the CompCode and Reason, obviously respectively, in the MQCFH Header structure in the message. This is to allow for a more consistent "look and feel" to the application error handling code.
These methods return a HASH reference which represents either the MQCFH structure (Header) or PCF parameters (Parameters) in the message. When passed no arguments, the entire HASH is returned. When passed a single argument, then only the value of the key matching that argument is returned.
For example:
$message->Header("CompCode")
would be equivalent to
$message->CompCode()
But,
$message->Header()
would give you back the entire HASH reference, so you could also get at the CompCode with
$message->Header()->{CompCode}
See the "Header Format" and "Parameters Format" sections for more details.
These are called internally by the MQSeries::Queue::Get() and MQSeries::Queue::Put() methods, and not invoked directly by applications.
The Header data structure is a HASH reference whose keys are the MQCFH PCF Header structure fields. The supported fields returned by this API are documented in the "MQSeries Pub/Sub User's Guide", Chapter 14: "Writing system management applications".
Note that the values returned are all precisely as documented, with the exception of the "Command" key. Rather than the numerical values of the various MQCMD_* macros, these are mapped to the following text strings:
Macro Name Key ========== === MQCMD_DELETE_PUBLICATION DeletePublication MQCMD_DEREGISTER_PUBLISHER DeregisterPublisher MQCMD_DEREGISTER_SUBSCRIBER DeregisterSubscriber MQCMD_PUBLISH Publish MQCMD_REGISTER_PUBLISHER RegisterPublisher MQCMD_REGISTER_SUBSCRIBER RegisterSubscriber MQCMD_REQUEST_UPDATE RequestUpdate MQCMD_BROKER_INTERNAL BrokerInternal
Note however, that only value you will ever see when subscribing to administrative messages is "Publish", therefore the Header data is not terribly useful or interesting.
The Parameters parsed from the PCF messages depend on the specific type of data encoded in the publication. In most cases, the values are either a single value, or an ARRAY reference of values when that specific Paramater is repeated. Most of the values are strings, but in 3 specific cases, the values are HASH references.
Many publications return data for numerous subcribers, for example, and each of the relevant keys will contain an ARRAY of values, the order of which is respectively related to the individual subscriber. Thus, the nth entry in the ARRAY for each of the repeated fields all correspond to the same subscriber.
Thus, the correct way to deal with these results is:
foreach my $key ( sort keys %{$message->Parameters()} ) {
if ( ref $message->Parameters($key) eq "ARRAY" ) {
foreach my $parameter ( @{$message->Parameters($key)} ) {
# Do something intelligent with $parameter
}
}
else {
# Do something intellident with $message->Parameters($key)
}
}
The following keys are returned for all publications:
The value of this key is a HASH reference, whose keys represent the individual PublicationsOptions present.
The only option which is documented to be possibly present is MQPUBO_RETAIN_PUBLICATION, which is represented by the string "RetPub".
Thus one would test for the existence of this flag something like:
if ( $message->Parameters("PublicationOptions")->{RetPub} ) {
print "Publication is retained\n";
}
For completeness, all of the MQPUBO_* options which exist are defined, and their string representations are as follows:
Macro Name Value ========== ===== MQPUBO_CORREL_ID_AS_IDENTITY CorrelAsId MQPUBO_RETAIN_PUBLICATION RetPub MQPUBO_OTHER_SUBSCRIBERS_ONLY OtherSubOnly MQPUBO_NO_REGISTRATION NoReg MQPUBO_IS_RETAINED_PUBLICATION IsRetPub
This is set to the reserved stream name "SYSTEM.BROKER.ADMIN.STREAM".
This will be one of the following values:
MQ/QMgrName/Event/SubscriptionDeregistered MQ/QMgrName/Event/StreamDeleted MQ/QMgrName/Event/BrokerDeleted MQ/QMgrName/StreamSupport MQ/QMgrName/Children MQ/QMgrName/Parent
where "QMgrName" is the queue manager name of the broker sending the message, which is 48 characters long and padded with spaces.
The time of publication (set to universal time).
The other parameters which are present in the Parameters HASH depend on the specific type of publication, which is indicated by the Topic. Again, for specific details, see the IBM documentation, specifically the "MQSeries PubSub User's Guide", in particular "Part 4: System Programming".
In all cases other than the following, the data values for the parameters are unmolested. The exception is:
First of all, the author debated changing these strings to "RegRegOpts" and "RegOpts" for maintenance of sanity, but then the strings do not match up with the IBM docs.
Both of these are handled the same way as "PublicationOptions", and the value returned is a HASH reference with the following keys corresponding to each of the possible option flags:
Macro Name Value ========== ===== MQREGO_CORREL_ID_AS_IDENTITY CorrelAsId MQREGO_ANONYMOUS Anon MQREGO_LOCAL Local MQREGO_DIRECT_REQUESTS DirectReq MQREGO_NEW_PUBLICATIONS_ONLY NewPubsOnly MQREGO_PUBLISH_ON_REQUEST_ONLY PubOnReqOnly MQREGO_DEREGISTER_ALL DeregAll MQREGO_INCLUDE_STREAM_NAME InclStreamName MQREGO_INFORM_IF_RETAINED InformIfRet
Also, it is worth mentioning that there are severl keys which are not found in the IBM documentation, but which author discovered are in fact present in the published data experimentally (I am not making any of this up).
Macro Name Key ========== === MQCACF_PARENT_Q_MGR_NAME QMgrName MQIACF_PUBLICATION_OPTIONS PublicationOptions MQIACF_REGISTRATION_OPTIONS RegistrationOptions MQCACF_SUPPORTED_STREAM_NAME SupportedStreamName
MQSeries::PubSub::Broker(3), MQSeries::PubSub::Stream(3) MQSeries PubSub User's Guide
