This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: MQSeries/Config/Authority, Next: MQSeries/Config/Machine, Prev: MQSeries/Command, Up: Module List Interface to parse authority files ********************************** NAME ==== MQSeries::Config::Authority - Interface to parse authority files SYNOPSIS ======== use MQSeries::Config::Authority; my $authobj = new MQSeries::Config::Authority('QMgrName' => 'TEST', 'ObjectType' => 'queue', 'ObjectName' => 'FOO.BAR'); print "All entities for queue: ", join(', ', $authobj->entities()), "\n"; print "Entity 'mqm' has authorities: ", join(', ', $authobj->authorities('mqm')), "\n"; if ($authobj->has_authority('allcmd', 'mqops')) { print "Entity 'mqops' has 'allcmd' authority\n"; } print "The command to recreate authority for user 'nobody' is:\n\t", "setmqaut -m TEST -t queue -n FOO.BAR -g nobody ", $authobj->authority_command(), "\n"; DESCRIPTION =========== The MQSeries::Config::Authority class is an interface to the authority files in /var/mqm/qmgrs/XYZ/auth/. This class will parse authority files for specific objects and take into account the @aclass and @class files. Objects created then provide access to the entities (Unix groups or principals) that have access to the object, allow you to query whether an entity has specific access levels, or to create command input that will allow you to recreate the access settings at a later date. The MQSeries::Config::Authority class will cache the parsed @aclass and @class authority files across multiple authority files for efficiency, but will check the timestamp of these files at every lookup. Should the files change, they will be re-parsed, so that up-to-date information is always returned. METHODS ======= new --- Create a new MQSeries::Config::Authority object. The constructor takes named parameters, of which two are required and three are optional, depending on the type and your environment: QMgrName The name of the queue manager containing the object. The Authority class will query the mqs.ini file for the queue-manager directory name, using the MQseries::Config::Machine class. ObjectType This must be either 'qmgr', 'queue', 'process' or 'namelist'. The aliases 'QMgr', 'QueueManager', 'Queue', 'Process' and 'Namelist' or also supported. ObjectName The name of the object to be read, if the object type is not 'qmgr'. BaseDir An optional parameter specifying the base directory, if not /var/mqm. Carp A reference to a routine used to issue warnings. Will default to carp. entities -------- Returns an array with all entities (Unix groups or principals). These can then be used in further method calls. As the authority file has a flat namespace, it is not indicated whether an entity name is that of a Unix group of that of a principal. numeric_authority ----------------- This method requires one parameter, an entity name, and will return the numeric authority value for that entity. The numeric authority is normally not of interest, but can be used when generating authority files directly. authorities ----------- This method has one parameter, an entity name, and one optional parameter, the format ('setmqaut' or 'PCF'). It returns a list of all authority names for this entity. If the format parameter is 'setmquat' or is not specified, the authority names returned correspond to the values as specified in `setmqaut', e.g. 'connect', 'inq', 'get', etc. If a user has all authorities, the full list of names is returned, not 'all'. If the format parameter is 'PCF', the PCF macros as defined by the MQSeries::Command module are returned. has_authority ------------- This method requires two parameters: an entity name and an authority name. It returns a boolean value indicating whether the user has the indicated authority or not. Apart from the indidivual authority names, this method also supports the combined authority names 'all', 'allcmd' and 'allmqi'. authority_command ----------------- This method requires one parameter, an entity name, and returns a string with authorities suitable for use in a `setmqaut' command. If the entity holds 'connect' authority, the string includes '+connect', otherwise it will include '-connect'. In order to keep the string short, the combined authority values 'all', 'allcmd' and 'allmqi' will be used when appropriate. SEE ALSO ======== MQSeries(3), MQSeries::Config::Authority(3)  File: pm.info, Node: MQSeries/Config/Machine, Next: MQSeries/Config/QMgr, Prev: MQSeries/Config/Authority, Up: Module List Interface to read the machine configuration file ************************************************ NAME ==== MQSeries::Config::Machine - Interface to read the machine configuration file SYNOPSIS ======== use MQSeries::Config::Machine; my $conf = new MQSeries::Config::Machine; print "All configuration sections: ", join(', ', $conf->stanzas()), "\n"; my $default = $conf->lookup('DefaultQueueManager'); if (defined $default) { print "Default queue manager: $default->{'Name'}\n"; } my $local = $conf->localqmgrs(); print "All local queue managers:\n"; while (my ($name, $data) = each %$local) { print " $name - $data->{'Directory'}\n"; } DESCRIPTION =========== The MQSeries::Config::Machine class is an interface to the machine configuration file, typically /var/mqm/mqs.ini. This class will parse the file and allow you to lookup any group of settings in the class. A utility function based on this will return a full list of all local queue managers and their base directory name. An MQSeries::Config::Machine object will cache the parsed configuration file for efficiency, but will check the timestamp of the file at every lookup. Should the file change, it will be re-parsed, so that up-to-date information is always returned. METHODS ======= new --- Create a new MQSeries::Config::Machine object. The constructor takes an optional filename parameter, used when your configuration file is not at the default location of /var/mqm/mqs.ini. stanzas ------- Return an array with all stanza names. These can then be used as a parameter to lookup. lookup ------ Lookup a stanza in the configuration file. Depending on the context, this returns either an array with one entry for each instance of the stanza found, or the latest stanza with that name. Each entry is a hash-reference with key-value pairs. For example, using `$conf-'lookup('QueueManager')> returns an array with one hash-reference for each locally-defined queue manager; each hash-reference will contain a 'Name' and 'Directory' field and whatever other fields the configuration file will contain. localqmgrs ---------- A convenience function written on top of lookup. This function returns a hash-reference mapping local queue manager names to configuration settings. FILES ===== /var/mqm/mqs.ini SEE ALSO ======== MQSeries(3), MQSeries::Config::QMgr  File: pm.info, Node: MQSeries/Config/QMgr, Next: MQSeries/ErrorLog/Entry, Prev: MQSeries/Config/Machine, Up: Module List Interface to read the queue manager configuration file ****************************************************** NAME ==== MQSeries::Config::QMgr - Interface to read the queue manager configuration file SYNOPSIS ======== use MQSeries::Config::QMgr; my $conf = new MQSeries::Config::QMgr('your.queue.manager'); print "All configuration sections: ", join(', ', $conf->stanzas()), "\n"; my $tuning = $conf->lookup('TuningParameters'); if (defined $tuning) { print "Tuning parameters:\n"; foreach my $param (sort keys %$tuning) { print "\t$param: $tuning->{$param}\n"; } } DESCRIPTION =========== The MQSeries::Config::QMgr class is an interface to a queue manager configuration file, typically /var/mqm/qmgrs/XXX/qm.ini for queue manager 'XXX'. This class will parse the file and allow you to lookup any group of settings in the class. An MQSeries::Config::QMgr object will cache the parsed configuration file for efficiency, but will check the timestamp of the file at every lookup. Should the file change, it will be re-parsed, so that up-to-date information is always returned. METHODS ======= new --- Create a new MQSeries::Config::QMgr object. The constructor takes one required and one optional parameter: The name of the queue manager The name of the base directory, if not /var/mqm The constructor will use the machine configuration file (by default /var/mqm/mqs.ini) to map the queue manager name to the appropriate directory name. stanzas ------- Return an array with all stanza names. These can then be used as a parameter to lookup. lookup ------ Lookup a stanza in the configuration file. Depending on the context, this returns either an array with one entry for each instance of the stanza found, or the latest stanza with that name. Each entry is a hash-reference with key-value pairs. For example, using `$conf-'lookup('QueueManager')> returns an array with one hash-reference for each locally-defined queue manager; each hash-reference will contain a 'Name' and 'Directory' field and whatever other fields the configuration file will contain. FILES ===== /var/mqm/mqs.ini /var/mqm/qmgrs/*/qm.ini SEE ALSO ======== MQSeries(3), MQSeries::Config::Machine  File: pm.info, Node: MQSeries/ErrorLog/Entry, Next: MQSeries/ErrorLog/Parser, Prev: MQSeries/Config/QMgr, Up: Module List One entry in an MQSeries error-log file *************************************** NAME ==== MQSeries::ErrorLog::Entry - One entry in an MQSeries error-log file SYNOPIS ======= # # Assuming we get an array of parsed MQSeries::ErrorLog::Entry # objects from somewhere, here's how we dump them to syslog. # use Sys::Syslog; openlog($0, 'pid', 'daemon'); sub process_errorlog_entries { foreach my $entry (@_) { syslog('info', "$entry"); # Overloaded operator-"" } } DESCRIPTION =========== The MQSeries::ErrorLog::Entry class is not used directly, but invoked through the MQSeries::ErrorLog::Parser class. When the MQSeries::ErrorLog::Tail or MQSeries::ErrorLog::Parser classes return an array of entries, these can be queried for their error-codes, summary, parsed fields, etc. This class has overloaded the '""' (to-string) operator, which means that printing an object results in reasonable results. METHODS ======= new --- Create a new MQSeries::ErrorLog::Entry object. The parameters are not documented; use the MQSeries::ErrorLog::Parser class to create these. error_code ---------- Return the error code (e.g., AMQ9001) timestamp --------- Return the original time-stamp from the entry, in Unix time() format summary ------- Return the original summary field ----- Get (one parameter) or set (two parameters) detailed parsed fields, such as 'QMgr', 'Channel', 'Host', etc. See the 'descriptions.pl' files used by the MQSeries::ErrorLog::Parser class for a list of supported messages and the fields parsed. fields ------ Get a list of all field names supported by this entry. as_string --------- Return a string with the details of this entry; also invoked by the overloaded operator-"". FILES ===== The file 'descriptions.pl' contains a list of all error messages supported, in the form of regular expressions and a set of field names extracted from these expressions. Additions and corrections are welcome. SEE ALSO ======== MQSeries(3), MQSeries::ErrorLog::Tail(3), MQSeries::ErrorLog::Parser(3)  File: pm.info, Node: MQSeries/ErrorLog/Parser, Next: MQSeries/ErrorLog/Tail, Prev: MQSeries/ErrorLog/Entry, Up: Module List Parse a portion of an MQSeries error log and return parsed Entry objects. ************************************************************************* NAME ==== MQSeries::ErrorLog::Parser - Parse a portion of an MQSeries error log and return parsed Entry objects. SYNOPSIS ======== use MQSeries::ErrorLog::Parser; my $qmgr = 'foo'; # Queue Manager we are processing my $parser = new MQSeries::ErrorLog::Parser('defaults' => { 'QMgr' => $qmgr }); open (ERRORS, "/var/mqm/qmgrs/$qmgr/errors/AMQERR01.LOG"); local $/; my @entries = $parser->parse_data(); close ERRORS; DESCRIPTION =========== The MQSeries::ErrorLog::Parser class is typically not used directly, but invoked through the MQSeries::ErrorLog::Tail class. When used directly, it can be used to parse a (possibly archived) error-log file and return an array of neatly-parsed MQSeries::ErrorLog::Entry objects. This class will try and deal with the vagaries of error-log processing, chief of which is that the MQSeries error-log is not written to in an atomic fashion, meaning that some error-log entries may be interleaved and hence un-parseable. All error-log entries can be parsed to some extent (summary, action, timestamp); however, most common error messages are also parsed in detail to give access to embedded fields such as 'QMgr', 'Channel', 'Queue', etc. METHODS ======= new --- Create a new MQSeries::ErrorLog::Parser object. The constructor take the following optional parameters: Carp A reference to an error-handling routine. This defaults to 'carp', but can be changed to your own error-handling routine. In order to avoid overloading the system with error messages, message format errors are not logged and errors for specific error-log messages are generated only once for each message code. defaults A reference to a hash with default parameters that will be used to initialize the MQSeries::ErrorLog::Entry object created. A typical default parameter is 'QMgr', which should be specified whenever you are parsing error-log messages for a specific queue manager. parse_data ---------- Parse a chunk of text with one or more error messages and return individual parsed entries. FILES ===== The file 'descriptions.pl' contains a list of all error messages supported, in the form of regular expressions and a set of field names extracted from these expressions. Additions and corrections are welcome. SEE ALSO ======== MQSeries(3), MQSeries::ErrorLog::Tail(3), MQSeries::ErrorLog::Entry(3)  File: pm.info, Node: MQSeries/ErrorLog/Tail, Next: MQSeries/FDC/Entry, Prev: MQSeries/ErrorLog/Parser, Up: Module List Watch MQSeries error-log files ****************************** NAME ==== MQSeries::ErrorLog::Tail - Watch MQSeries error-log files SYNOPSIS ======== use MQSeries::ErrorLog::Tail; my $err_log = new MQSeries::ErrorLog::Tail("/var/mqm/errors"); while (1) { my @entries = $err_log->process(); process_errorlog_entries(@entries) if (@entries); sleep(10) unless (@entries); } sub process_errorlog_entries { my (@errlog_entries) = @_; foreach my $entry (@errlog_entries) { # Send off to syslog or whatever } } DESCRIPTION =========== The MQSeries::ErrorLog::Tail class provides a mechanism to watch the MQSeries errorlog (AMQERR01.LOG), which is generally written to whenever an MQSeries error occurs, or when certain events happen. Every time the process() method is invoked, it will return a (possibly empty) array of MQSeries::ErrorLog::Entry objects, which can in turn be analyzed and shipped off to syslog or other monitoring tools. The MQSeries::ErrorLog::Tail class will notice file roll-overs (where the old AMQERR01.LOG is renamed AMQERR02.LOG and a new file AMQERR01.LOG is created). In such cases, it will first process the tail-end of the old file, then switch over to the new file. METHODS ======= new --- Create a new MQSeries::ErrorLog::Tail object. The argument is the directory to watch (/var/mqm/errors for a typical installation's system-wide global error log, /var/mqm/qmgrs/XYZ/errors for a typical installation's queue-manager specific error log). process ------- Process any changes since the previous invocation (or the constructor). Read any data found, parse it and return the MQSeries::ErrorLog::Entry objects that were read. SEE ALSO ======== MQSeries(3), MQSeries::ErrorLog::Parser(3), MQSeries::ErrorLog::Entry(3), MQSeries::FDC::Tail(3)  File: pm.info, Node: MQSeries/FDC/Entry, Next: MQSeries/FDC/Parser, Prev: MQSeries/ErrorLog/Tail, Up: Module List One entry in an MQSeries FDC file ********************************* NAME ==== MQSeries::FDC::Entry - One entry in an MQSeries FDC file SYNOPIS ======= # # Assuming we get an array of parsed MQSeries::FDC::Entry # objects from somewhere, here's how we dump them to syslog. # use Sys::Syslog; openlog($0, 'pid', 'daemon'); sub process_fdc_entries { foreach my $entry (@_) { syslog('info', "$entry"); # Overloaded operator-"" } } DESCRIPTION =========== The MQSeries::FDC::Entry class is not used directly, but invoked through the MQSeries::FDC::Parser class. When the MQSeries::FDC::Tail or MQSeries::FDC::Parser classes return an array of entries, these can be queried for their parsed fields. This class has overloaded the '""' (to-string) operator, which means that printing an object results in reasonable results. METHODS ======= new --- Create a new MQSeries::FDC::Entry object. The parameters are not documented; use the MQSeries::FDC::Parser class to create these. get_header ---------- Return a field parsed from the header. Any field from the header is available directly; in addition, a number of parsed fields are derived. Most FDC entries have following standard fields: Date/Time Host Name QueueManager (sometimes missing) PIDS LVLS Product Long Name Vendor Probe Id Application Name Component Build Date UserID Program Name Process Thread Major Errorcode Minor Errorcode Probe Type Probe Severity Probe Description Comment1 In addition, the following parsed fields are available (these have all lower-case names): uid (numerical userid from UserID field, if available) userid (text userid from UserID field, if available) event_code (event code from Probe Description, if available) get_body -------- Return the body with all details from the FDC entry as_string --------- Return a string with the details of this entry; also invoked by the overloaded operator-"". SEE ALSO ======== MQSeries(3), MQSeries::FDC::Tail(3), MQSeries::FDC::Parser(3)  File: pm.info, Node: MQSeries/FDC/Parser, Next: MQSeries/FDC/Tail, Prev: MQSeries/FDC/Entry, Up: Module List Parse a portion of an MQSeries FDC file and return parsed Entry objects. ************************************************************************ NAME ==== MQSeries::FDC::Parser - Parse a portion of an MQSeries FDC file and return parsed Entry objects. SYNOPSIS ======== use MQSeries::FDC::Parser; my $parser = new MQSeries::FDC::Parser("AMQ09151.0.FDC"); open (FDC, "/var/mqm/errors/AMQ09151.0.FDC"); local $/; my @entries = $parser->parse_data(); close FDC; DESCRIPTION =========== The MQSeries::FDC::Parser class is typically not used directly, but invoked through the MQSeries::FDC::Tail class. When used directly, it can be used to parse a (possibly archived) FDC file and return an array of neatly-parsed MQSeries::FDC::Entry objects. This class will try and deal with the vagaries of error-log processing, chief of which is that the MQSeries FDC is not written to in an atomic fashion, meaning that some error-log entries may be incomplete. In this case, the incomplete part is saved and prefixed to the data supplied in the next call. For this reason, you must create an individual Parser object for each file that is processed. METHODS ======= new --- Create a new MQSeries::ErrorLog::Parser object. The constructor takes the filename as its argument; this filename is only used for error messages. parse_data ---------- Parse a chunk of text with one or more FDC entries and return individual parsed entries. SEE ALSO ======== MQSeries(3), MQSeries::FDC::Tail(3), MQSeries::FDC::Entry(3)  File: pm.info, Node: MQSeries/FDC/Tail, Next: MQSeries/Message, Prev: MQSeries/FDC/Parser, Up: Module List Watch MQSeries FDC error files ****************************** NAME ==== MQSeries::FDC::Tail - Watch MQSeries FDC error files SYNOPSIS ======== use MQSeries::FDC::Tail; my $fdc_log = new MQSeries::FDC::Tail("/var/mqm/errors"); while (1) { my @entries = $fdc_log->process(); process_fdc_entries(@entries) if (@entries); sleep(10) unless (@entries); } sub process_fdc_entries { my (@fdc_entries) = @_; foreach my $entry (@fdc_entries) { # Send off to syslog or whatever } } DESCRIPTION =========== The MQSeries::FDC::Tail class provides a mechanism to watch the FDC logs, which are generally written to if a fatal MQSeries error, or internal MQSeries error, occurs. Every time the process() method is invoked, it will return a (possibly empty) array of MQSeries::FDC::Entry objects, which can in turn be analyzed and shipped off to syslog or other monitoring tools. The MQSeries::FDC::Tail class will notice new FDC files appearing; files being truncated (e.g. by housekeeping jobs) or files being removed. METHODS ======= new --- Create a new MQSeries::FDC::Tail object. The argument is the directory to watch (/var/mqm/errors for a typical installation). An optional second argument specifies the maximum number of files that may be open at the same time; the default is 200, well under the default limit of 255 open files imposed by the stdio libraries of many vendors. process ------- Process any changes since the previous invocation (or the constructor). Read any data found, parse it and return the MQSeries::FDC::Entry objects that were read. SEE ALSO ======== MQSeries(3), MQSeries::FDC::Parser(3), MQSeries::FDC::Entry(3), MQSeries::ErrorLog::Tail(3)  File: pm.info, Node: MQSeries/Message, Next: MQSeries/Message/Event, Prev: MQSeries/FDC/Tail, Up: Module List OO interface to MQSeries messages ********************************* NAME ==== MQSeries::Message - OO interface to MQSeries messages SYNOPSIS ======== use MQSeries; use MQSeries::Message; # # Create a vanilla MQSeries::Message object for getting messages # my $getmsg = MQSeries::Message->new(); # # Create a message for putting strings, which requires the # MQMD.Format field to be specified. This is essential for # character codeset conversion. # my $putmsg = MQSeries::Message->new ( MsgDesc => { Format => MQFMT_STRING, }, ); # # Create a reply message, copying the CorrelId from the MsgId of a # request. This reply is also a string. # my $request = MQSeries::Message->new(); # Assume we get the message via an MQSeries::Queue object... my $reply = MQSeries::Message->new ( MsgDesc => { Format => MQFMT_STRING, CorrelId => $request->MsgDesc("MsgId"), }, ); See MQSeries::Queue SYNOPSIS section as well. DESCRIPTION =========== The MQSeries::Message object is an OO mechanism for creating MQSeries messages, and putting and getting them onto MQSeries queues, with an interface which is much simpler than the full MQI. This module is used together with MQSeries::QueueManager and MQSeries::Queue. These objects provide a subset of the MQI, with a simpler interface. METHODS ======= new --- The arguments to the constructor are a hash, with the following key/value pairs (there are no required keys): Key Value === ===== Data Scalar BufferLength Positive Integer MsgDesc MQI MsgDesc hash (MQMD structure) Carp CODE reference Data When creating a message to be put into a queue, the Data should be specified. This must be a simple scalar value. Other subclasses of MQSeries::Message support the direct encoding of complex data structure, for example perl references can be sent and retreived as MQSeries messages using the MQSeries::Message::Storable module. The Data method will set the Data portion of the message if it is passed any defined value, and will simply return the data otherwise. Thus, to clear any existing Data from a message, one would pass the empty string: $message = MQSeries::Message->new( Data => "foo" ); $message->Data(""); # Clears Data value entirely In order to query the Data value, the method must be called with no further arguments; $data = $message->Data(); # Returns Data unmolested Buffer This method will return the raw, converted buffer when one exists. This is really only relevant for a message type which uses a PutConvert and/or GetConvert method to translate the raw buffer returned from MQGET(). BufferLength This sets the BufferLength of the messages to be extracted using MQGET. The default is 32K, and if the messages to be received from the queue are expected to be larger, this must be set appropriately. MsgDesc The value of this key is a hash refernece which sets the key/values of the MsgDesc structure. See the "MQSeries Application Programming Reference" documentation for the possible keys and values of the MQMD 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",$message); } } Then, one tells the object to use this routine: my $message = MQSeries::Message->new( Carp => \&MyLogger ) || die "Unable to create message.\n"; The default, as one might guess, is Carp::carp(); Data ---- This method is used to set or query the value of the Data structure. If an argument is specified, then the given data is assigned as the Data value for this object. If no argument is given, then the current Data value is returned. The Data can be any arbitrary perl data structure, however, it must be convertible to a scalar by means of the PutConvert and GetConvert hooks in MQSeries::QueueManager and MQSeries::Queue objects. See the documentation for those classes for more details. If the GetConvert and PutConvert hooks are not used, then the data must be a simple scalar value. BufferLength ------------ This method is used to set or query the current BufferLength used when extracting messages. If given an argument, the BufferLength is set to the given value. If the given value is not a positive integer, then an error is generated, and a false value returned. With no argument, the current BufferLength is returned. MsgDesc ------- This method can be used to query the MsgDesc data structure. If no argument is given, then the entire MsgDesc hash is returned. If a single argument is given, then this is interpreted as a specific key, and the value of that key in the MsgDesc hash is returned. 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. SUBCLASSES ========== This class is designed to be subclassed, and follows all the usual rules (see the "perltoot" documentation provided with the core perl distribution). In particular, the PutConvert and GetConvert arguments usually supplied to either the MQSeries::QueueManager or MQSeries::Queue constructors are not necessary if you implement a subclass of MQSeries::Message with methods of the same name. See the MQSeries::Message::Storable documentation for an example of one such class. See also the section "CONVERSION PRECEDENCE" in the MQSeries::QueueManager documentation. SEE ALSO ======== MQSeries(3), MQSeries::QueueManager(3), MQSeries::Queue(3), MQSeries::Message::Storable(3), MQSeries::Message::Event(3)  File: pm.info, Node: MQSeries/Message/Event, Next: MQSeries/Message/PCF, Prev: MQSeries/Message, Up: Module List OO Class for decoding MQSeries event messages ********************************************* NAME ==== MQSeries::Message::Event - OO Class for decoding MQSeries event messages SYNOPSIS ======== use MQSeries::Message::Event; my $message = MQSeries::Message::Event->new; DESCRIPTION =========== This class is a subclass of MQSeries::Message which provides a GetConvert() method to decode standard MQSeries Event messages. METHODS ======= Since this is a subclass of MQSeries::Message, all of that classes methods are available, as well as the following. PutConvert, GetConvert ---------------------- Neither of these methods are called by the users application, but are used internally by MQSeries::Queue::Put() and MQSeries::Queue::Get(), as well as MQSeries::QueueManager::Put1(). The PutConvert method will cause a failure, since this class is only to be used for decoding MQSeries events, not generating them. Perhaps a futute release will support the creation of such events. The GetConvert method decodes the message contents into the EventHeader and EventData hashes, which are available via the methods of the same name. Buffer ------ Actually, this is one of the MQSeries::Message methods, and not specific to MQSeries::Message::Event. However, it is important to note that this class is one of those that saves the raw buffer returned by MQGET in the object. The Buffer method will return the raw, unconverted PCF data in the original message. The autor uses this to echo the original event message to other systems management software that wants to parse the PCF. EventHeader ----------- This method can be used to query the EventHeader data structure. If no argument is given, then the entire EventHeader hash is returned. If a single argument is given, then this is interpreted as a specific key, and the value of that key in the EventHeader hash is returned. The keys in the EventHeader hash are the fields from the MQCFH structure. See the "MQSeries Programmable System Management" documentation. EventData --------- This method can be used to query the EventData data structure. If no argument is given, then the entire EventData hash is returned. If a single argument is given, then this is interpreted as a specific key, and the value of that key in the EventData hash is returned. The keys in the EventData hash vary, depending on the specific event. In general, these are the strings shown in the documentation for each individual event described in the "MQSeries Programmable System Management" documentation. The data structures in the eventdata in the original event are identified with macros, such as "MQCA_Q_MGR_NAME". Rather than use these (in some cases very cryptic) macros, the strings shown in the IBM MQSeries documentation are used instead. In this case, "QMgrName". The macros are mapped to strings as follows: Macro Key ===== === MQCACF_APPL_NAME ApplName MQCACF_AUX_ERROR_DATA_STR_1 AuxErrorDataStr1 MQCACF_AUX_ERROR_DATA_STR_2 AuxErrorDataStr2 MQCACF_AUX_ERROR_DATA_STR_3 AuxErrorDataStr3 MQCACF_BRIDGE_NAME BridgeName MQCACF_OBJECT_Q_MGR_NAME ObjectQMgrName MQCACF_USER_IDENTIFIER UserIdentifier MQCACH_CHANNEL_NAME ChannelName MQCACH_CONNECTION_NAME ConnectionName MQCACH_FORMAT_NAME Format MQCACH_XMIT_Q_NAME XmitQName MQCA_BASE_Q_NAME BaseQName MQCA_PROCESS_NAME ProcessName MQCA_Q_MGR_NAME QMgrName MQCA_Q_NAME QName MQCA_XMIT_Q_NAME XmitQName MQIACF_AUX_ERROR_DATA_INT_1 AuxErrorDataInt1 MQIACF_AUX_ERROR_DATA_INT_2 AuxErrorDataInt2 MQIACF_BRIDGE_TYPE BridgeType MQIACF_COMMAND Command MQIACF_CONV_REASON_CODE ConversionReasonCode MQIACF_ERROR_IDENTIFIER ErrorIdentifier MQIACF_OPEN_OPTIONS Options MQIACF_REASON_QUALIFIER ReasonQualifier MQIACH_CHANNEL_TYPE ChannelType MQIA_APPL_TYPE ApplType MQIA_HIGH_Q_DEPTH HighQDepth MQIA_MSG_DEQ_COUNT MsgDeqCount MQIA_MSG_ENQ_COUNT MsgEnqCount MQIA_Q_TYPE QType MQIA_TIME_SINCE_RESET TimeSinceReset SEE ALSO ======== MQSeries(3), MQSeries::QueueManager(3), MQSeries::Queue(3), MQSeries::Message(3)  File: pm.info, Node: MQSeries/Message/PCF, Next: MQSeries/Message/Storable, Prev: MQSeries/Message/Event, Up: Module List Generic OO and procedurel interface to PCF (Programmable Command Format) messages. ********************************************************************************** NAME ==== MQSeries::Message::PCF - Generic OO and procedurel interface to PCF (Programmable Command Format) messages. SYNOPSIS ======== # # 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); DESCRIPTION =========== 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) PubSub Administrative Messages (MQSeries::PubSub::AdminMessage) 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). METHODS ======= The MQSeries::Message::PCF class is a subclass of MQSeries::Message, so all of the methods of the latter class are also available. new --- 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" Header The value of this key is a HASH reference, representing the MQCFH PCF header structure. See below for specific details. Parameters 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. PROCEDURES ========== 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. MQEncodePCF ----------- 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. MQDecodePCF ----------- 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. Header and Parameter Data Structures ==================================== PCF Header (MQCFH) ------------------ 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. PCF Parameters (MQCFIN, MQCFST, MQCFIL, or MQCFSL) -------------------------------------------------- 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 PubSub administrative messages, and yet another for performance events. See the respective documentation for each of these formats for more information. Integer Parameter (MQCFIN) 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) String Parameter (MQCFST) 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) Integer List Parameter (MQCFIL) This is a HASH reference with the following input keys: 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. When returned, it has the following output keys: Parameter Values Type (always == MQCFT_INTEGER_LIST) String List Parameter (MQCFSL) This is a HASH reference with the following input keys (optional keys denoted by *): 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. When returned, it has the following output keys: Parameter Strings CodedCharSetId Type (always == MQCFT_STRING_LIST) SEE ALSO ======== MQSeries::Message::Event(3), MQSeries::Command::Request(3), MQSeries::Command::Response(3), MQSeries::PubSub::AdminMessage(3)  File: pm.info, Node: MQSeries/Message/Storable, Next: MQSeries/Message/XML-Dumper, Prev: MQSeries/Message/PCF, Up: Module List OO Class for sending and receiving perl references as MQSeries message application data *************************************************************************************** NAME ==== MQSeries::Message::Storable - OO Class for sending and receiving perl references as MQSeries message application data SYNOPSIS ======== use MQSeries::Message::Storable; my $message = MQSeries::Message::Storable->new ( Data => { some => "big ugly", complicated => { data => [0..5], structure => [6..10], }, }, ); DESCRIPTION =========== This is a simple subclass of MQSeries::Message which support the use of perl references as data structures in the message. These references have to be converted to a string of data which can be written to an MQSeries message as application data, and for this the Storable module is used. The Storable::nfreeze and Storable::thaw subroutines are not very forgiving. If the input to nfreeze is not a perl reference, then the code raises a fatal exception. Similarly, if the input to thaw is not a frozen perl reference (i.e. the output from a nfreeze() call), is also raises a fatal exception. Both of these are trapped with eval, but the data conversion is considered to fail, and thus the Put(), Get(), or Put1() method calls will subsequently fail. An object of this class will require that all of the messages put to or gotten from any given queue use perl references as the underlying data structure. This also requires that both the putting and getting application use this class to create the MQSeries messages. METHODS ======= PutConvert, GetConvert ---------------------- Neither of these methods are called by the users application, but are used internally by MQSeries::Queue::Put() and MQSeries::Queue::Get(), as well as MQSeries::QueueManager::Put1(). PutConvert() calls Storable::nfreeze to convert the perl reference (which can be arbitrarily deep) to a scalar buffer which is then passed to MQPUT() or MQPUT1(). GetConvert() calls Storable::thaw to convert the contents of a message retreived from a queue via MQGET() to a perl reference, which is then inserted into the Data structure of the message object. SEE ALSO ======== MQSeries(3), MQSeries::QueueManager(3), MQSeries::Queue(3), MQSeries::Message(3), Storable(3)  File: pm.info, Node: MQSeries/Message/XML-Dumper, Next: MQSeries/Queue, Prev: MQSeries/Message/Storable, Up: Module List Dumper - OO Class for sending and receiving perl references as MQSeries message application data in XML format, using the XML::Dumper module ******************************************************************************************************************************************** NAME ==== MQSeries::Message::XML-Dumper - OO Class for sending and receiving perl references as MQSeries message application data in XML format, using the XML::Dumper module SYNOPSIS ======== use MQSeries::Message::XML-Dumper; my $message = MQSeries::Message::XML-Dumper->new ( Data => { some => "big ugly", complicated => { data => [0..5], structure => [6..10], }, }, ); DESCRIPTION =========== This is a simple subclass of MQSeries::Message which support the use of perl references as data structures in the message. These references have to be converted to a string of data which can be written to an MQSeries message as application data, and for this the XML::Dumper module is used. METHODS ======= PutConvert, GetConvert ---------------------- Neither of these methods are called by the users application, but are used internally by MQSeries::Queue::Put() and MQSeries::Queue::Get(), as well as MQSeries::QueueManager::Put1(). PutConvert() calls XML::Dumper::pl2xml to convert the perl reference (which can be arbitrarily deep) to a scalar buffer which is then passed to MQPUT() or MQPUT1(). GetConvert() calls XML::Dumper::xml2pl to convert the contents of a message retreived from a queue via MQGET() to a perl reference, which is then inserted into the Data structure of the message object. SEE ALSO ======== MQSeries(3), MQSeries::QueueManager(3), MQSeries::Queue(3), MQSeries::Message(3), XML::Dumper(3)  File: pm.info, Node: MQSeries/Queue, Next: MQSeries/QueueManager, Prev: MQSeries/Message/XML-Dumper, Up: Module List OO interface to the MQSeries Queue objects ****************************************** NAME ==== MQSeries::Queue - OO interface to the MQSeries Queue objects SYNOPSIS ======== use MQSeries; use MQSeries::Queue; use MQSeries::Message; # # Open a queue for output, loop getting messages, updating some # database with the data. # my $queue = MQSeries::Queue->new ( QueueManager => 'some.queue.manager', 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()) ) { $queue->Commit() or die("Unable to commit changes to queue.\n" . "CompCode = " . $queue->CompCode() . "\n" . "Reason = " . $queue->Reason() . "\n"); } else { $queue->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 => 'some.queue.manager', 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 => 'some.queue.manager', 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 and MQSeries::Message. 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 String, or MQSeries::QueueManager object Queue* String, or ARRAY reference (distribution list) Mode* String Options* MQOPEN 'Options' values CloseOptions MQCLOSE 'Options' values DynamicQName String DisableAutoResize Boolean NoAutoOpen 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 NOTE: Only one or the 'Options' or 'Mode' keys can be specified. They are mutually exclusive. If 'NoAutoOpen' is given, then both 'Options' and 'Mode' are optional, as they canbe 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. Since the MQSeries::Queue object will internally create the MQSeries::QueueManager object, if given a name, this is the simpler mechanism. Code which opens multiple Queues on a single Queue Manager can be slightly optimized by creating the QueueManager object explicitly, and then reusing it for the multiple MQSeries::Queue objects which must be instantiated. This will avoid a few unnecesary MQCONN calls, but this overhead should prove to be minimal in most cases. If the "default" queue manager is to be used, then the QueueManager argument can either be specified as the empty string "", or just omitted entirely. 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 => "FOO", 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 => "FOO", 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 => "FOO", 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 => 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. NoAutoOpen This will disable the implicit call to the Open() method by the constructor, 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 refernece which sets the key/values of the MsgDesc 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",$message); } } Then, one tells the object to use this routine: my $queue = MQSeries::Queue->new ( QueueManager => 'some.queue.manager', 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 retreived 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 WARNING: These keys are deprecated, and their use no longer encouraged. They are left in place only for backwards compabitility. See the docs for the NoAutoOpen argument, and the Open() method. 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 => 'some.queue.manager', 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). 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 NoAutoOpen 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 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. If this option is specified, then the Sync option is simply ignored. 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 or MQCOMM call is made. These are both wrapped with the Backout() and Commit() methods respectively. The value is simply interpreted as true or false. 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. 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 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 retreives 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 retreived, 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 two very specific cases. Case 1: 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. Case 2: Reason == MQRC_CONVERTED_MSG_TOO_BIG In this case, the BufferLength of the Message object is reset to *twice* the DataLength value returned by the MQGET() call, and the MQGET() call is redone. Doubling the size is probably overkill, but there is no deterministic way of finding the actual size required. Since most of the conversions are character set mappings, we are assuming that double will always be sufficient. 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 retreive 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, and Wait options are simply ignored. 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). 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. 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. 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. 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 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 ClusterDate MQCA_CLUSTER_DATE ClusterName MQCA_CLUSTER_NAME ClusterNamelist MQCA_CLUSTER_NAMELIST 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 DefInputOpenOption MQIA_DEF_INPUT_OPEN_OPTION DefPersistence MQIA_DEF_PERSISTENCE DefPriority MQIA_DEF_PRIORITY DefinitionType MQIA_DEFINITION_TYPE 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 OpenInputCount MQIA_OPEN_INPUT_COUNT OpenOutputCount MQIA_OPEN_OUTPUT_COUNT ProcessName MQCA_PROCESS_NAME 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 QMgrName MQCA_CLUSTER_Q_MGR_NAME QName MQCA_Q_NAME QNames MQCACF_Q_NAMES 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 TimeSinceReset MQIA_TIME_SINCE_RESET 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. Backout ------- This method takes no arguments, and merely calls MQBACK. It returns true on success, and false on failure. NOTE: This operation is in reality not specific to the Queue, but rather to the Queue Manager connection. Because the API does not require the developer to specifically open a Queue Manager connection (via an MQSeries::QueueManager object), but will do so implicitly (see the new() documentation above), these methods are provided as part of the MQSeries::Queue API. Note, however, that this does *NOT* imply that syncpoint operations can be performed at the individual Queue level. Transactions are still per-queue manager connection. Commit ------ This method takes no arguments, and merely calls MQCMIT. It returns true on success, and false on failure. NOTE: The same comments for Backout() apply here. This is really a Queue Manager connection operation. 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. Pending ------- This method indicated whether or not there are currently actively pending transactions (puts or gets under syncpoint). 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', DisableAutoConnect => 1, ) || 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', NoAutoOpen => 1, ) || 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::Message::Storable(3)