NAME

MQSeries::Command - OO interface to the Programmable Commands

SYNOPSIS

  use MQSeries;
  use MQSeries::Command;

  #
  # Simplest usage
  #
  my $command = MQSeries::Command->new
    (
     QueueManager => 'some.queue.manager',
    )
    or die("Unable to instantiate command object\n");

  @qnames = $command->InquireQueueNames()
    or die "Unable to list queue names\n";

  foreach my $qname ( @qnames ) {

      $attr = $command->InquireQueue
	(
	 QName		=> $qname,
	 QAttrs		=> [qw(
			       OpenInputCount
			       OpenOutputCount
			       CurrentQDepth
			      )],
	) or die "InquireQueue: " . MQReasonToText($command->Reason()) . "\n";

      print "QName = $qname\n";

      foreach my $key ( sort keys %$attr ) {
	  print "\t$key => $attr->{$key}\n";
      }

  }

  #
  # High-level wrapper method: CreateObject
  #
  $command->CreateObject
    (
     Attrs		=>
     {
      QName		=> 'FOO.BAR.REQUEST',
      QType		=> 'Local',
      MaxQDepth		=> '50000',
      MaxMsgLength	=> '20000',
     }
    ) || die "CreateObject: " . MQReasonToText($command->Reason()) . "\n";

  $command->CreateObject
    (
     Clear		=> 1,
     Attrs		=>
     {
      QName		=> 'FOO.BAR.REPLY',
      QType		=> 'Remote',
      RemoteQName	=> 'FOO.BAR.REPLY',
      RemoteQMgrName	=> 'SAT1',
     }
    ) || die "CreateObject: " . MQReasonToText($command->Reason()) . "\n";

DESCRIPTION

The MQSeries::Command class implements an interface to the Programmable Command Format messages documented in the:

"MQSeries Programmable System Management"

section of the MQSeries documentation. In particular, this document will primarily explain how to interpret the above documentation, and thus use this particular implementation in perl. Please read and understand the following sections of the above document:

Part 2. Programmable Command Formats
  Chapter 8. Definitions of the Programmable Command Formats
  Chapter 9. Structures used for commands and responses

This interface also supports the text-based MQSC format messages used by the queue manager of some platforms, particularly MVS. Using the same interface, either PCF or MQSC command server can be queried, with the results translated into the same format for responses as well. Note that there are limits to how transparent this is (see MQSC NOTES), but the code tries quite hard to hide as many of the differences as possible.

COMMAND ARGUMENTS

Before we discuss the specific arguments and return values of each of the methods supported by the MQSeries::Command module, we must explain how the keys and values used by the interface were chosen, as this will allow the developer to understand how to take advantage of the very complete documentation provided by IBM (which will not be reproduced here).

For each command documented in 'Definitions of the Programmable Command Formats' (there is a specific page listing all of the commands, grouped by type), there is a corresponding method in this class. For example, there is a method named 'InquireQueueManager', for the obvious (I hope) PCF command.

All of these methods take a hash of key/value pairs as an argument, with the keys being those defined in the documentation for each command. When writing C code to produce PCF messages, the parameter names are macros, such as:

MQIACF_Q_MGR_ATTRS

to specify a list of queue manager attributes. Rather than use these names directly, the key strings are taken from the IBM documentation. In this example, the string used for this key is:

QMgrAttrs

The values depend on the structure type of the parameter. If the structure is a string (MQCFST) or an integer (MQCFIN) then the value of the key is simply a scalar string or integer in perl. If it either a string list (MQCFSL) or an integer list (MQCFIL), then the value of the key is an array reference (see the InquireQueueManager example in the SYNOPSIS) of scalar strings or integers.

RETURN VALUES

Most of the individual methods map to underlying commands which do not return any data. For all of these, the return value is simply Boolean; true or false. That is, the command either worked or failed.

Only the methods associated with those commands documented as producing data responses:

Escape
Inquire Channel
Inquire Channel Names
Inquire Channel Status
Inquire Cluster Queue Manager
Inquire Namelist
Inquire Namelist Names
Inquire Process
Inquire Process Names
Inquire Queue
Inquire Queue Manager
Inquire Queue Names
Reset Queue Statistics

return interesting information. Most of these will return an array of hash references, one for each object matching the query criteria. For example. The specific keys are documented in the section of the IBM documentation which discusses the "Data responses to commands", on the summary page "PCF commands and responses in groups". If you have read the IBM documentation as requested above, you should have found this page.

Note that in an array context, the entire list is returned, but in a scalar context, only the first item in the list is returned.

Four of these commands, however, have a simplified return value. All four of:

Inquire Channel Names
Inquire Namelist Names
Inquire Process Names
Inquire Queue Names

simply return an array of strings, containing the names which matched the query criteria.

METHODS

new

The arguments to the constructor are a hash, with the following key/value pairs:

Key                Value
===                =====
QueueManager       String or MQSeries::QueueManager object
ProxyQueueManager  String or MQSeries::QueueManager object
ReplyToQ           String or MQSeries::Queue object
CommandQueueName   String
DynamicQName       String
ModelQName	     String
Type               String ("PCF" or "MQCS")
Expiry	     Numeric
Wait               Numeric
ReplyToQMgr        String
Carp               CODE Reference
StrictMapping      Boolean	
CompCode           Reference to Scalar Variable
Reason             Reference to Scalar Variable

QueueManager

The name of the QueueManager (or alternatively, a previously instantiated MQSeries::QueueManager object) to which commands are to be sent.

This can be omitted, in which case the "default queue manager" is therefore assumed.

ProxyQueueManager

The name of the queue manager to which to MQCONN(), and submit messages on the QueueManagers behalf. This is to be used if a direct connection to the QueueManager is not possible, for example MVS queue managers with support for direct client access.

The messages will be put to what is assumed to be a remote queue definition which routes to the command queue on the desired QueueManager.

In order to specify the "default" queue manager as the ProxyQueueManager, an empty string must be explicitly given.

ReplyToQ

The ReplyToQ can be opened by the application, and the MQSeries::Queue object passed in to the MQSeries::Command constructor, if so desired, os, a fixed queue name can be given. This is a somewhat advanced usage of the API, since the default behavior of opening a temporary dynamic queue under the covers is usually prefered, and much simpler.

The responses are retreived from the reply queue using gets by CorrelId, so there should be no issue with using a pre-defined, shared queue for this, if so desired.

CommandQueueName

This specifies the queue to which the command messages will be put. The defaults are usually reasonable, and depend on the command message Type (PCF or MQSC).

PCF   => SYSTEM.ADMIN.COMMAND.QUEUE
MQSC  => SYSTEM.COMMAND.INPUT

If the ProxyQueueManager has been specified, then we assume the messages are being written to a remote queue definition, and the defaults are then:

PCF   => SYSTEM.ADMIN.COMMAND.QUEUE."QueueManager"
MQSC  => SYSTEM.COMMAND.INPUT."QueueManager"

See "MQSC NOTES" for some examples of how to use this in practice.

Type

This argument indicates whether the command server on the QueueManager supports either PCF or MQSC messages. The default is PCF. See the section "MQSC NOTES" for the Ugly Truth about the MQSC support.

Expiry

This value is used as the MQMD.Expiry field on all requests sent to the command server. The value is passed to the MQSeries::Message constructor, and should specify the time in tenths of a second. The default is 600, or 60 seconds.

A symbolic value ending on 's' for seconds or 'm' for minutes may also be specified, e.g. the symbolic value '45s' will have the same meaning as the number 450.

Wait

This value is used as the Wait argument to the MQSeries::Queue->Get() method call made against the ReplyToQ (a dynamic reply queue). and should be a time specified in milliseconds. The default is 60000, or 60 seconds.

A symbolic value ending on 's' for seconds or 'm' for minutes may also be specified, e.g. the symbolic value '45s' will have the same meaning as the number 45000.

NOTE: Both the Expiry and Wait defaults may be too slow for heavily loaded queue managers. Tune them appropriately.

ReplyToQMgr

The ReplyToQMgr normally defaults to the QueueManager, but it can be overridden, perhaps as a means of specifying an alternate return path over a specific channel. For example, the author uses special channels for SYSTEM related traffic, over which we forward MQSeries events from one queue manager to another, and also over which we wish the command server queries to flow.

The "default" path between QMA and QMB flows over a channel called QMA.QMB, but this traffic is application data, not administrative system data. The system queries flow over QMA.QMB.SYSTEM, and we need to ensure that replies to queries follow a similar reverse path. Specifying the ReplyToQMgr as "QMB.SYSTEM" accomplishes this.

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 $command = MQSeries::Command->new(
				       QueueManager => 'some.queue.manager',
				       Carp => \&MyLogger,
				      )
      or die("Unable to connect to queue manager.\n");

The default, as one might guess, is Carp::carp();

StrictMapping

If this argument has a true value, then strict mapping of PCF parameters and values will be enforced. Normally, if you feed a bogus string into the API, it will attempt to map it to the underlying PCF macro value, and if the mapping fails, it will quietly forgive you, and ignore the parameter. Enabling this feature will cause the translation of an encoded PCF message into the data structure for a Response, or the translation of a Request into an encoded PCF message, to fail if any of the mappings fail.

Usually, the command server will generate errors if you feed bogus data into the API. but that will only occur after the data has been encoded and sent to the command server. This feature will allow you to detect this error before the data is ever sent.

CompCode

Normally the CompCode and Reason are access via the methods of the same name. However, that obviously is not possible if the constructor fails. If you want to perform special handling of the error codes in this case, you will have tell the constructor where to write the CompCode and Reason, by providing a SCALAR reference.

For example:

my $CompCode = MQCC_FAILED;
my $Reason   = MQRC_NONE;

my $command = MQSeries::Command->new
  (
   QueueManager => 'some.queue.manager',
   CompCode     => \$CompCode,
   Reason       => \$Reason,
  );

Now, the CompCode and Reason are available, even if the constructor fails, in which case it would normally return nothing.

Reason

See CompCode above.

CompCode

This method will return the MQI CompCode for the most recent MQI call made by the API.

Reason

This method will return the MQI Reason for the most recent MQI call made by the API.

ReasonText

This method will return different strings depending on whether the command is MQSC or PCF. For MQSC, the command server sends back some text explaining the reason code, and for PCF, we simply call MQReasonToText on the reason code and return that instead.

MQSC sends back far less information encoded into the reason than PCF does, and the interesting information is usually found in the ReasonText. Therefore, this method should be used when raising exceptions, in order to get the most descriptive explanation for any given error.

Responses

Normally, the data of interest is returned from the method in question, but the individual responses are available via this method. This returns a list of MQSeries::Command::Response objects, one for each individual message recieved.

NOTE: In previous releases, this method was named "Response", but due to a namespace conflict between the class "MQSeries::Command::Response", and the method "MQSeries::Command->Response", and the headaches this causes, it has been renamed.

DataParameters

This method will return a list of parameters structures from all of the responses messages sent back which were not error responses. Some errors will send back responses with parameters, and these could easily be confused with real data (until you start looking at the actual data, of course).

ErrorParameters

This method will return a list of parameters structures from all of the responses messages sent back which were error responses. If a command fails, the Reason() will usually tell you enough about the cause of the failure, but if the reason is MQRCCF_CFIN_PARM_ID_ERROR, then the parameters in the error message will indicate which Parameter key was invalid.

CreateObject

This is a generic "wrapper" method for creating any generic MQSeries object. The arguments to this method are a hash, with the following key/value pairs:

Key                Value
===                =====
Attrs		     HASH reference
Verify	     Boolean
Clear              Boolean
Quiet              Boolean
Force	             Boolean

The key/value pairs in the Attrs argument are passed directly to the corresponding CreateQueue(), CreateChannel(), or CreateProcess() method. However, there is more to this than just creating the object. For clarity, this discussion will use creation of a queue as an example.

First, InquireQueue is called to see if the object already exists. If it does not exist, then the object is simply created, with the specified attributes.

If it does exist, and the QType matches, then the actual object attributes are compared against those passed to the CreateObject method, and if they match, then no action is taken, and the object is not modified.

If it does exist, but of a different QType, then the existing object is deleted, and the new object created as requested.

The idea here is to match the modification of the object conditional on the need for modifying the object. If the same CreateObject method call, with the same arguments, is called twice, then the second method invocation should be a noop, as far as the actual MQSeries object is concerned.

Attrs

As discussed above, this is a HASH reference, whose key/value pairs are used to determine what type of object is being created or updated, and those key/value pairs are passed as-is to the appropriate Create* method call for the specified MQSeries object type.

Verify

If this key has a true value, then no changes will actually be implemented. They will merely be reported via test messages on stdout.

Quiet

CreateObject is by default rather chatty about what it is doing, but all of the messages, other than errors, can be suppressed if this key has a true value.

Clear

Normally, when a Local queue is being replaced with another QType (eg. Remote or Alias), then the Local queue is not cleared before being deleted. If there are messages on the queue, this will cause an error. If the queue needs to be cleared, then this key must be passed with a true value.

This is a seperate option due to the inherit danger of destroying data accidentally. If you really want to clear the queues before recreating them as another QType, you will have to be explicitl about it.

Force

This option will be passed to the Change* method, if the object already exists and is of type Queue, forcing changes to be applied to objects which are currently in use. It is ignored for the other object types. Note that this should not be passed as a key to the Attrs hash, since this is not really an object attribute.

If Force is given as an Attrs key, and the underlying Create* method is called, since the object does not already exist, then the command server will return an error.

COMMAND REQUESTS

This section is NOT intended to replace the IBM "MQSeries Programmable System Management" documentation, and it merely serves to document the specific keys and values used by the perl implementation of the API.

In all cases, the keys which can be passed to the command are identical to the strings found in the documentation. However, some of the values also have more convenient string mapping as well, as these are not easily intuited by reading IBMs docs, thus these are clarified here.

The IBM docs list the possible values for each key as a list of MQSeries C macros (eg. MQCHT_SENDER), and if given, these will be respected. It will be faster to use the strings given, since these map directly to the actual macro values via a hash lookup, rather than a function call (all of the various C macros are implemented as function calls via an AUTOLOAD). Also, the author finds the replacement strings far more readable. YMMV.

For each key shown, the format of value is one of the following:

(string)

The value given must be a scalar value, interpretable as a text string.

(string list)

The value must be an ARRAY reference of scalar values, all of which must be interpretable as strings.

NOTE: Some of the parameters (for example, the MsgExit parameter for the various Channel commands) can take either a string or string list. In this case, the API will be forgiving, and try to determine what you meant automatically. If you pass a reference, it will create a string list parameter, and if you pass a plain scalar, it will create a string.

ANOTHER NOTE: if you pass a simple scalar string where a string list is explicitly required (as opposed to optional), then the API will create a list of one string for you.

(integer)

The value given must be a scalar value, interpretable as an integer. In some cases, a table will show a mapping from more readable text strings to the macros documented in the IBM manuals.

(integer list)

The value must be an ARRAY reference of scalar values, all of which must be interpretable as integers. As with the integer format, in some cases, a table will show a mapping from more readable text strings to the macros documented in the IBM manuals.

(Boolean)

The value given need only be 0 or 1. This was done for some of the integer types which are documented to take a pair of macros, whose values were simply zero or one, and when the true/false nature of the key was considered to be intiuitive. For example, "DataConversion" is either on (true) or off (false).

In order to reduce needless redundancy, only the keys which have special value mappings, or which have Boolean values will be listed here. For all others, the IBM documentation is sufficient.

Channel Commands

Subsets of the these keys are applicable to the following commands. See the documentation for each of the for the specific list.

Change Channel
Copy Channel
Create Channel
Delete Channel
Inquire Channel
Inquire Channel Names
Inquire Channel Status
Ping Channel
Reset Channel
Resolve Channel
Start Channel
Start Channel Initiator
Start Channel Listener
Stop Channel

The following keys have special value mappings:

ChannelType (integer)

Key				Macro
===				=====
Clntconn                    MQCHT_CLNTCONN
ClusterReceiver             MQCHT_CLUSRCVR
ClusterSender               MQCHT_CLUSSDR
Receiver                    MQCHT_RECEIVER
Requester                   MQCHT_REQUESTER
Sender                      MQCHT_SENDER
Server                      MQCHT_SERVER
Svrconn                     MQCHT_SVRCONN

TransportType (integer)

Key				Macro
===				=====
DECnet                      MQXPT_DECNET
LU62                        MQXPT_LU62
NetBIOS                     MQXPT_NETBIOS
SPX                         MQXPT_SPX
TCP                         MQXPT_TCP
UDP                         MQXPT_UDP

PutAuthority (integer)

Key				Macro
===				=====
Context                     MQPA_CONTEXT
Default                     MQPA_DEFAULT

MCAType (integer)

Key				Macro
===				=====
Process                     MQMCAT_PROCESS
Thread                      MQMCAT_THREAD

NonPersistentMsgSpeed (integer)

Key				Macro
===				=====
Normal                      MQNPMS_NORMAL
Fast                        MQNPMS_FAST

ChannelTable (integer)

Key				Macro
===				=====
Clntconn                    MQCHTAB_CLNTCONN
QMgr                        MQCHTAB_Q_MGR

ChannelInstanceAttrs (integer list)

Same as ChannelAttrs:

ChannelAttrs (integer list)

Key				Macro
===				=====
All                         MQIACF_ALL
AlterationDate              MQCA_ALTERATION_DATE
AlterationTime              MQCA_ALTERATION_TIME
BatchInterval               MQIACH_BATCH_INTERVAL
BatchSize                   MQIACH_BATCH_SIZE
Batches                     MQIACH_BATCHES
BuffersReceived             MQIACH_BUFFERS_RCVD
BuffersSent                 MQIACH_BUFFERS_SENT
BytesReceived               MQIACH_BYTES_RCVD
BytesSent                   MQIACH_BYTES_SENT
ChannelDesc                 MQCACH_DESC
ChannelInstanceType         MQIACH_CHANNEL_INSTANCE_TYPE
ChannelName                 MQCACH_CHANNEL_NAME
ChannelNames                MQCACH_CHANNEL_NAMES
ChannelStartDate            MQCACH_CHANNEL_START_DATE
ChannelStartTime            MQCACH_CHANNEL_START_TIME
ChannelStatus               MQIACH_CHANNEL_STATUS
ChannelType                 MQIACH_CHANNEL_TYPE
ClusterName                 MQCA_CLUSTER_NAME
ClusterNamelist             MQCA_CLUSTER_NAMELIST
ConnectionName              MQCACH_CONNECTION_NAME
CurrentLUWID                MQCACH_CURRENT_LUWID
CurrentMsgs                 MQIACH_CURRENT_MSGS
CurrentSequenceNumber       MQIACH_CURRENT_SEQ_NUMBER
DataConversion              MQIACH_DATA_CONVERSION
DiscInterval                MQIACH_DISC_INTERVAL
HeartbeatInterval           MQIACH_HB_INTERVAL
InDoubtStatus               MQIACH_INDOUBT_STATUS
LastLUWID                   MQCACH_LAST_LUWID
LastMsgDate                 MQCACH_LAST_MSG_DATE
LastMsgTime                 MQCACH_LAST_MSG_TIME
LastSequenceNumber          MQIACH_LAST_SEQ_NUMBER
LongRetriesLeft             MQIACH_LONG_RETRIES_LEFT
LongRetryCount              MQIACH_LONG_RETRY
LongRetryInterval           MQIACH_LONG_TIMER
MCAJobName                  MQCACH_MCA_JOB_NAME
MCAName                     MQCACH_MCA_NAME
MCAStatus                   MQIACH_MCA_STATUS
MCAType                     MQIACH_MCA_TYPE
MCAUserIdentifier           MQCACH_MCA_USER_ID
MaxMsgLength                MQIACH_MAX_MSG_LENGTH
ModeName                    MQCACH_MODE_NAME
MsgExit                     MQCACH_MSG_EXIT_NAME
MsgRetryCount               MQIACH_MR_COUNT
MsgRetryExit                MQCACH_MR_EXIT_NAME
MsgRetryInterval            MQIACH_MR_INTERVAL
MsgRetryUserData            MQCACH_MR_EXIT_USER_DATA
MsgUserData                 MQCACH_MSG_EXIT_USER_DATA
Msgs                        MQIACH_MSGS
NetworkPriority             MQIACH_NETWORK_PRIORITY
NonPersistentMsgSpeed       MQIACH_NPM_SPEED
Password                    MQCACH_PASSWORD
PutAuthority                MQIACH_PUT_AUTHORITY
QMgrName                    MQCA_Q_MGR_NAME
ReceiveExit                 MQCACH_RCV_EXIT_NAME
ReceiveUserData             MQCACH_RCV_EXIT_USER_DATA
SecurityExit                MQCACH_SEC_EXIT_NAME
SecurityUserData            MQCACH_SEC_EXIT_USER_DATA
SendExit                    MQCACH_SEND_EXIT_NAME
SendUserData                MQCACH_SEND_EXIT_USER_DATA
SeqNumberWrap               MQIACH_SEQUENCE_NUMBER_WRAP
ShortRetriesLeft            MQIACH_SHORT_RETRIES_LEFT
ShortRetryCount             MQIACH_SHORT_RETRY
ShortRetryInterval          MQIACH_SHORT_TIMER
StopRequested               MQIACH_STOP_REQUESTED
TpName                      MQCACH_TP_NAME
TransportType               MQIACH_XMIT_PROTOCOL_TYPE
UserIdentifier              MQCACH_USER_ID
XmitQName                   MQCACH_XMIT_Q_NAME

ChannelInstanceType (integer)

Key				Macro
===				=====
Current                     MQOT_CURRENT_CHANNEL
Saved                       MQOT_SAVED_CHANNEL

InDoubt (integer)

Key				Macro
===				=====
Backout                     MQIDO_BACKOUT
Commit                      MQIDO_COMMIT

The following keys have Boolean values:

Replace
DataConversion
Quiesce

Namelist Commands

Subsets of the these keys are applicable to the following commands. See the documentation for each of the for the specific list.

Change Namelist
Copy Namelist
Create Namelist
Delete Namelist
Inquire Namelist
Inquire Namelist Names

The following keys have special value mappings:

NamelistAttrs (integer list)

Key				Macro
===				=====
AlterationDate              MQCA_ALTERATION_DATE
AlterationTime              MQCA_ALTERATION_TIME
NamelistDesc                MQCA_NAMELIST_DESC
NamelistName                MQCA_NAMELIST_NAME
Names                       MQCA_NAMES

The following keys have Boolean values:

Replace

Process Commands

Subsets of the these keys are applicable to the following commands. See the documentation for each of the for the specific list.

Change Process
Copy Process
Create Process
Delete Process
Inquire Process
Inquire ProcessNames

The following keys have special value mappings:

ApplType (integer)

Key				Macro
===				=====
AIX                         MQAT_AIX
CICS                        MQAT_CICS
DOS                         MQAT_DOS
Default                     MQAT_UNIX
IMS                         MQAT_IMS
MVS                         MQAT_MVS
NSK                         MQAT_NSK
OS2                         MQAT_OS2
OS400                       MQAT_OS400
UNIX                        MQAT_UNIX
VMS                         MQAT_VMS
Win16                       MQAT_WINDOWS
Win32                       MQAT_WINDOWS_NT

ProcessAttrs (interger list)

Key				Macro
===				=====
All                         MQIACF_ALL
AlterationDate              MQCA_ALTERATION_DATE
AlterationTime              MQCA_ALTERATION_TIME
ApplId                      MQCA_APPL_ID
ApplType                    MQIA_APPL_TYPE
EnvData                     MQCA_ENV_DATA
ProcessDesc                 MQCA_PROCESS_DESC
ProcessName                 MQCA_PROCESS_NAME
ProcessNames                MQCACF_PROCESS_NAMES
UserData                    MQCA_USER_DATA

The following keys have Boolean values:

Replace

Queue Commands

Subsets of the these keys are applicable to the following commands. See the documentation for each of the for the specific list.

Change Queue
Clear Queue
Copy Queue
Create Queue
Delete Queue
Inquire Queue
Inquire Queue Names
Reset Queue Statistics

The following keys have special value mappings:

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

QAttrs (integer list)

Key				Macro
===				=====
All                         MQIACF_ALL
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

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

The following keys have Boolean values:

Replace
Force
InhibitPut
DefPersistence
InhibitGet
Shareability
HardenGetBackout
DistLists
TriggerControl
QDepthMaxEvent
QDepthHighEvent
QDepthLowEvent
Purge

Queue Manager Commands

Subsets of the these keys are applicable to the following commands. See the documentation for each of the for the specific list.

Change Queue Manager
Inquire Queue Manager
Ping Queue Manager

The following keys have special value mappings:

QMgrAttrs (integer list)

Key				Macro
===				=====
All                         MQIACF_ALL
AlterationDate              MQCA_ALTERATION_DATE
AlterationTime              MQCA_ALTERATION_TIME
AuthorityEvent              MQIA_AUTHORITY_EVENT
ChannelAutoDef              MQIA_CHANNEL_AUTO_DEF
ChannelAutoDefEvent         MQIA_CHANNEL_AUTO_DEF_EVENT
ChannelAutoDefExit          MQCA_CHANNEL_AUTO_DEF_EXIT
ClusterWorkLoadData         MQCA_CLUSTER_WORKLOAD_DATA
ClusterWorkLoadExit         MQCA_CLUSTER_WORKLOAD_EXIT
ClusterWorkLoadLength       MQIA_CLUSTER_WORKLOAD_LENGTH
CodedCharSetId              MQIA_CODED_CHAR_SET_ID
CommandInputQName           MQCA_COMMAND_INPUT_Q_NAME
CommandLevel                MQIA_COMMAND_LEVEL
DeadLetterQName             MQCA_DEAD_LETTER_Q_NAME
DefXmitQName                MQCA_DEF_XMIT_Q_NAME
DistLists                   MQIA_DIST_LISTS
InhibitEvent                MQIA_INHIBIT_EVENT
LocalEvent                  MQIA_LOCAL_EVENT
MaxHandles                  MQIA_MAX_HANDLES
MaxMsgLength                MQIA_MAX_MSG_LENGTH
MaxPriority                 MQIA_MAX_PRIORITY
MaxUncommittedMsgs          MQIA_MAX_UNCOMMITTED_MSGS
PerformanceEvent            MQIA_PERFORMANCE_EVENT
Platform                    MQIA_PLATFORM
QMgrDesc                    MQCA_Q_MGR_DESC
QMgrIdentifier              MQCA_Q_MGR_IDENTIFIER
QMgrName                    MQCA_Q_MGR_NAME
RemoteEvent                 MQIA_REMOTE_EVENT
RepositoryName              MQCA_REPOSITORY_NAME
RepositoryNamelist          MQCA_REPOSITORY_NAMELIST
StartStopEvent              MQIA_START_STOP_EVENT
SyncPoint                   MQIA_SYNCPOINT
TriggerInterval             MQIA_TRIGGER_INTERVAL

The following keys have Boolean values:

Force
AuthorityEvent
InhibitEvent
LocalEvent
RemoteEvent
StartStopEvent
PerformanceEvent
ChannelAutoDef
ChannelAutoDefEvent

Cluster Commands

Subsets of the these keys are applicable to the following commands. See the documentation for each of the for the specific list.

Inquire Cluster Queue Manager
Refresh Cluster
Reset Cluster
Resume Queue Manager Cluster
Suspend Queue Manager Cluster

The following keys have special value mappings:

ClusterQMgrAttrs (integer list)

Key				Macro
===				=====
AlterationDate              MQCA_ALTERATION_DATE
AlterationTime              MQCA_ALTERATION_TIME
BatchInterval               MQIACH_BATCH_INTERVAL
BatchSize                   MQIACH_BATCH_SIZE
ChannelStatus               MQIACH_CHANNEL_STATUS
ClusterDate                 MQCA_CLUSTER_DATE
ClusterName                 MQCA_CLUSTER_NAME
ClusterTime                 MQCA_CLUSTER_TIME
ConnectionName              MQCACH_CONNECTION_NAME
DataConversion              MQIACH_DATA_CONVERSION
Description                 MQCACH_DESC
DiscInterval                MQIACH_DISC_INTERVAL
HeartbeatInterval           MQIACH_HB_INTERVAL
LongRetryCount              MQIACH_LONG_RETRY
LongRetryInterval           MQIACH_LONG_TIMER
MCAName                     MQCACH_MCA_NAME
MCAType                     MQIACH_MCA_TYPE
MCAUserIdentifier           MQCACH_MCA_USER_ID
MaxMsgLength                MQIACH_MAX_MSG_LENGTH
ModeName                    MQCACH_MODE_NAME
MsgExit                     MQCACH_MSG_EXIT_NAME
MsgRetryCount               MQIACH_MR_COUNT
MsgRetryExit                MQCACH_MR_EXIT_NAME
MsgRetryInterval            MQIACH_MR_INTERVAL
MsgRetryUserData            MQCACH_MR_EXIT_USER_DATA
MsgUserData                 MQCACH_MSG_EXIT_USER_DATA
NetworkPriority             MQIACH_NETWORK_PRIORITY
NonPersistentMsgSpeed       MQIACH_NPM_SPEED
Password                    MQCACH_PASSWORD
PutAuthority                MQIACH_PUT_AUTHORITY
QMgrDefinitionType          MQIACF_Q_MGR_DEFINITION_TYPE
QMgrIdentifier              MQCA_Q_MGR_IDENTIFIER
QMgrType                    MQIACF_Q_MGR_TYPE
ReceiveExit                 MQCACH_RCV_EXIT_NAME
ReceiveUserData             MQCACH_RCV_EXIT_USER_DATA
SecurityExit                MQCACH_SEC_EXIT_NAME
SecurityUserData            MQCACH_SEC_EXIT_USER_DATA
SendExit                    MQCACH_SEND_EXIT_NAME
SendUserData                MQCACH_SEND_EXIT_USER_DATA
SeqNumberWrap               MQIACH_SEQUENCE_NUMBER_WRAP
ShortRetryCount             MQIACH_SHORT_RETRY
ShortRetryInterval          MQIACH_SHORT_TIMER
Suspend                     MQIACF_SUSPEND
TpName                      MQCACH_TP_NAME
TransportType               MQIACH_XMIT_PROTOCOL_TYPE
UserIdentifier              MQCACH_USER_ID
XmitQName                   MQCACH_XMIT_Q_NAME

Action (integer)

Key				Macro
===				=====
ForceRemove                 MQACT_FORCE_REMOVE

The following keys have Boolean values:

Quiesce

Escape Command

This command is not really part of a grouping, so its all by itself here.

The following keys have special value mappings:

EscapeType (integer)

Key				Macro
===				=====
MQSC                        MQET_MQSC

COMMAND RESPONSES

There are several commands which return data. The return value of the actual command methods depends on the specific command. All of the "Inquire*Names" commands return a list of the actual names returned, which greatly simplifies the parsing of the return value.

The commands which return a list of names are:

Inquire Channel Names
Inquire Namelist Names
Inquire Process Names
Inquire Queue Names

For example:

@qnames = $command->InquireQueueNames( QName => 'FOO.*' );

will result in @qnames containing a list of strings of all of the queue names starting with FOO.

The rest of the commands return a list of Parameters HASH references, extracted from each of the messages sent back from the command server. In a scalar context, only the first Parameters HASH reference is returned. This applies to all of the following commands:

Escape
Inquire Channel
Inquire Channel Status
Inquire Cluster Queue Manager
Inquire Namelist
Inquire Process
Inquire Queue
Inquire Queue Manager
Reset Queue Statistics

For example:

@queues = $command->InquireQueue( QName => 'FOO.*', QAttrs => 'All' );

will result in @queues containing a list of HASH references, each of which has key/value pairs for the attributes of one of the queues starting with FOO.

The keys in the Parameters HASH references are mapped from the numeric macro values back into the same strings described above for simplifying the input Parameters.

However, there are a few keys in the responses which are not supported as keys in the inquiry. In general, the return values are left unmolested, with the exception of the keys documented above for each command type, as well as the following:

Inquire Channel Status Response

The following keys have special value mappings:

ChannelStatus (integer)

Macro				Key
=====				===
MQCHS_BINDING                       Binding
MQCHS_INACTIVE                      Inactive
MQCHS_INITIALIZING                  Initializing
MQCHS_PAUSED                        Paused
MQCHS_REQUESTING                    Requesting
MQCHS_RETRYING                      Retrying
MQCHS_RUNNING                       Running
MQCHS_STARTING                      Starting
MQCHS_STOPPED                       Stopped
MQCHS_STOPPING                      Stopping

MCAStatus (integer)

Macro				Key
=====				===
MQMCAS_RUNNING                      Running
MQMCAS_STOPPED                      Stopped

The following keys can be interpreted in a Boolean context:

InDoubtStatus
StopRequested

Inquire Cluster Queue Manager Response

The following keys have special value mappings:

QMgrDefinitionType (integer)

Macro				Key
=====				===
MQQMDT_AUTO_CLUSTER_SENDER          AutoClusterSender
MQQMDT_AUTO_EXP_CLUSTER_SENDER      AutoExplicitClusterSender
MQQMDT_CLUSTER_RECEIVER             ClusterReceiver
MQQMDT_EXPLICIT_CLUSTER_SENDER      ExplicitClusterSender

QMgrType (integer)

Macro				Key
=====				===
MQQMT_NORMAL                        Normal
MQQMT_REPOSITORY                    Repository

ChannelStatus (integer)

Macro				Key
=====				===
MQCHS_BINDING                       Binding
MQCHS_INACTIVE                      Inactive
MQCHS_INITIALIZING                  Initializing
MQCHS_PAUSED                        Paused
MQCHS_REQUESTING                    Requesting
MQCHS_RETRYING                      Retrying
MQCHS_RUNNING                       Running
MQCHS_STARTING                      Starting
MQCHS_STOPPED                       Stopped
MQCHS_STOPPING                      Stopping

The following keys can be interpreted in a Boolean context:

Suspend

Inquire Queue Response

The following keys have special value mappings:

ClusterQType (integer)

Macro				Key
=====				===
MQCQT_ALIAS_Q                       Alias
MQCQT_LOCAL_Q                       Local
MQCQT_Q_MGR_ALIAS                   QMgrAlias
MQCQT_REMOTE_Q                      Remote

Inquire Queue Manager Response

The following keys have special value mappings:

Platform (integer)

Macro				Key
=====				===
MQPL_MVS                            MVS
MQPL_NSK                            NSK
MQPL_OS2                            OS2
MQPL_OS400                          OS400
MQPL_UNIX                           UNIX
MQPL_WINDOWS                        Win16
MQPL_WINDOWS_NT                     Win32

The following keys can be interpreted in a Boolean context:

DistLists
SyncPoint

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

COMMAND ARGUMENTS

RETURN VALUES

METHODS

new

CompCode

Reason

ReasonText

Responses

DataParameters

ErrorParameters

CreateObject

COMMAND REQUESTS

Channel Commands

Namelist Commands

Process Commands

Queue Commands

Queue Manager Commands

Cluster Commands

Escape Command

COMMAND RESPONSES

Inquire Channel Status Response

Inquire Cluster Queue Manager Response

Inquire Queue Response

Inquire Queue Manager Response

SEE ALSO

Module Install Instructions