MQSeries::Command - OO interface to the Programmable Commands
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";
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.
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.
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 AuthInfo Inquire AuthInfo Names 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 Inquire Queue Status Reset Queue Statistics
plus the following equivalents for MQSC
Inquire StorageClass Inquire StorageClass Names Inquire CFStruct Inquire CFStruct Names
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.
Some of these commands, however, have a simplified return value. All seven of:
Inquire AuthInfo Names Inquire Channel Names Inquire Namelist Names Inquire Process Names Inquire Queue Names Inquire StorageClass Names Inquire CFStruct Names
simply return an array of strings, containing the names which matched the query criteria.
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
RealQueueManager String
ReplyToQ String or MQSeries::Queue object
CommandQueueName String
CommandQueue MQSeries::Queue object
DynamicQName String
ModelQName String
Type String ("PCF" or "MQSC")
Expiry Numeric
Wait Numeric
ReplyToQMgr String
Carp CODE Reference
StrictMapping Boolean
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.
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.
If a remote queue manager is controlled through a proxy, by having the QueueManager parameter specify the proxy and the CommandQueueName an object descriptor, then by default any output will print the queue manager name incorrectly. The RealQueueManager parameter specifies the name used for display purposes.
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 retrieved 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.
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.
Alternatively, the CommandQueue parameter can be used.
For complex set-ups, where a remote queue manager is managed by the name of the command queue does not fit the standard scheme, the command queue can be opened manually and specified in the MQSeries::Command constructor as the CommandQueue parameter.
The CommandQueue parameter must be combined with the RealQueueManager parameter. In the example below, a mainframe queue manager CSQ1 is managed from the queue manager UNIXQM with a non-standard queue name:
$queue = MQSeries::Queue::->
new('QueueManager' => 'UNIXQM',
'Queue' => 'REMOTE.FOR.COMMANDQ.ON.CSQ1',
'Mode' => 'output',
) ||
die "Cannot open queue";
$cmd = MQSeries::Command::->
new('ProxyQueueManager' => 'UNIXQM', # Also ReplyToQMgr
'RealQueueManager' => 'CSQ1', # Displayed in messages
'Type' => "MQSC",
'CommandQueue' => $queue,
) ||
die "Cannot create command";
This mechanism can also be used when the command queue needs to be opened with special options. This is typically combined with a call to the MsgDesc method:
my $queue = MQSeries::Queue::->
new('QueueManager' => 'UNIXQM',
'Queue' => 'SYSTEM.ADMIN.COMMAND.QUEUE',
'Options' => (MQSeries::MQOO_FAIL_IF_QUIESCING |
MQSeries::MQOO_OUTPUT |
MQSeries::MQOO_SET_IDENTITY_CONTEXT,
),
) ||
die "Cannot open queue";
$cmd = MQSeries::Command::->
new('RealQueueManager' => 'UNIXQM',
'Type' => 'PCF',
'CommandQueue' => $queue,
) ||
die "Cannot create command";
$cmd->MsgDesc('ApplIdentityData' => "MyData",
'UserIdentifier' => "mqm",
);
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.
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.
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.
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.
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();
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.
This method will return the MQI CompCode for the most recent MQI call made by the API.
This method will return the MQI Reason for the most recent MQI call made by the API.
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.
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.
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).
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.
In some cases, it is useful or necessary to override specific MQMD fields in outgoing request messages. Examples include manually changeing the Persistence field, or changing the message identity or origin context. The MsgDesc method allows you to do so:
$cmd->MsgDesc('Persistence' => 0);
or
$cmd->MsgDesc('ApplIdentityData' => "MyData",
'UserIdentifier' => "mqm",
);
Note that setting the message identity or origin context requires you to open the command queue with the relevant open options; see the description of the CommandQueue parameter to new.
Note that the ReplyToQ, ReplyToQMgr and Expiry fields for the request message descriptor can be specified in the constructor new. The MsgDesc method is intended for the more obscure options.
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 Callback CODE reference
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.
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.
If this key has a true value, then no changes will actually be implemented. They will merely be reported via test messages on stdout.
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.
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.
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.
This optional argument allows you to provide an object comparison subroutine, instead of relying on the built-in function. This is virtually never required, unless your request contains some 'meta' attributes that translate to multiple or different MQSeries attributes.
The Callback parameter must be a reference to a subroutine that receives three parameters: a reference to the requested attributes, a reference to the attributes found in the object, and a reference to a subroutine that compares two single attribute values. The return value from the subroutine must be a reference to a hash with those attribute names and values that actually should be changed.
Please see the source code of MQSeries::Command, specifically the _CompareAttributes method, for the default callback. Any callback you provide must behave in a similar way.
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:
The value given must be a scalar value, interpretable as a text string.
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.
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.
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.
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.
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands 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:
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
Key Macro
=== =====
DECnet MQXPT_DECNET
LU62 MQXPT_LU62
NetBIOS MQXPT_NETBIOS
SPX MQXPT_SPX
TCP MQXPT_TCP
UDP MQXPT_UDP
Key Macro
=== =====
Context MQPA_CONTEXT
Default MQPA_DEFAULT
Key Macro
=== =====
Process MQMCAT_PROCESS
Thread MQMCAT_THREAD
Key Macro
=== =====
Normal MQNPMS_NORMAL
Fast MQNPMS_FAST
Key Macro
=== =====
Clntconn MQCHTAB_CLNTCONN
QMgr MQCHTAB_Q_MGR
Same as ChannelAttrs:
Key Macro
=== =====
All MQIACF_ALL
AlterationDate MQCA_ALTERATION_DATE
AlterationTime MQCA_ALTERATION_TIME
BatchHeartBeat MQIACH_BATCH_HB
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
LocalAddress MQCACH_LOCAL_ADDRESS
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
SSLCipherSpec MQCACH_SSL_CIPHER_SPEC
SSLClientAuth MQIACH_SSL_CLIENT_AUTH
SSLPeerName MQCACH_SSL_PEER_NAME
StopRequested MQIACH_STOP_REQUESTED
TpName MQCACH_TP_NAME
TransportType MQIACH_XMIT_PROTOCOL_TYPE
UserIdentifier MQCACH_USER_ID
XmitQName MQCACH_XMIT_Q_NAME
Key Macro
=== =====
Current MQOT_CURRENT_CHANNEL
Saved MQOT_SAVED_CHANNEL
Key Macro
=== =====
Backout MQIDO_BACKOUT
Commit MQIDO_COMMIT
Key Macro
=== =====
Optional MQSCA_OPTIONAL
Required MQSCA_REQUIRED
The following keys have Boolean values:
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands for the specific list.
Change AuthInfo Copy AuthInfo Create AuthInfo Delete AuthInfo Inquire AuthInfo Inquire AuthInfo Names
The following keys have special value mappings:
Key Macro
=== =====
CRLLDAP MQAIT_CRL_LDAP
Key Macro
=== =====
All MQIACF_ALL
AlterationDate MQCA_ALTERATION_DATE
AlterationTime MQCA_ALTERATION_TIME
AuthInfoConnName MQCA_AUTH_INFO_CONN_NAME,
AuthInfoDesc MQCA_AUTH_INFO_DESC,
AuthInfoName MQCA_AUTH_INFO_NAME,
AuthInfoType MQIA_AUTH_INFO_TYPE,
LDAPPassword MQCA_LDAP_PASSWORD,
LDAPUserName MQCA_LDAP_USER_NAME,
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands for the specific list.
Change Namelist Copy Namelist Create Namelist Delete Namelist Inquire Namelist Inquire Namelist Names
The following keys have special value mappings:
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:
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands for the specific list.
Change Process Copy Process Create Process Delete Process Inquire Process Inquire ProcessNames
The following keys have special value mappings:
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
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:
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands 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:
Key Macro
=== =====
OnOpen MQBND_BIND_ON_OPEN
NotFixed MQBND_BIND_NOT_FIXED
Key Macro
=== =====
Permanent MQQDT_PERMANENT_DYNAMIC
Temporary MQQDT_TEMPORARY_DYNAMIC
Key Macro
=== =====
Exclusive MQOO_INPUT_EXCLUSIVE
Shared MQOO_INPUT_SHARED
Key Macro
=== =====
FIFO MQMDS_FIFO
Priority MQMDS_PRIORITY
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
Key Macro
=== =====
High MQQSIE_HIGH
None MQQSIE_NONE
OK MQQSIE_OK
Key Macro
=== =====
Alias MQQT_ALIAS
All MQQT_ALL
Cluster MQQT_CLUSTER
Local MQQT_LOCAL
Model MQQT_MODEL
Remote MQQT_REMOTE
Key Macro
=== =====
Cell MQSCO_CELL
QMgr MQSCO_Q_MGR
Key Macro
=== =====
Depth MQTT_DEPTH
Every MQTT_EVERY
First MQTT_FIRST
None MQTT_NONE
Key Macro
=== =====
Normal MQUS_NORMAL
XMITQ MQUS_TRANSMISSION
The following keys have Boolean values:
The InquireQueueStatus command does not behave like the other queue commands. In addition, the documentation is incorrect and incomplete, so the following is subject to change.
For a request, the following keys are supported:
QName
StatusType
OpenType
QStatusAttrs
The following keys have special value mappings:
Key Macro
=== =====
Queue MQIACF_Q_STATUS
Handle MQIACF_Q_HANDLE
Key Macro
=== =====
All MQQSOT_ALL
Input MQQSOT_INPUT
Output MQQSOT_OUTPUT
Key Macro
=== =====
All MQIACF_ALL
ApplTag MQCACF_APPL_TAG
ApplType MQIA_APPL_TYPE
ChannelName MQCACH_CHANNEL_NAME
Conname MQCACH_CONNECTION_NAME
CurrentQDepth MQIA_CURRENT_Q_DEPTH
OpenInputCount MQIA_OPEN_INPUT_COUNT
OpenOptions MQIACF_OPEN_OPTIONS
OpenOutputCount MQIA_OPEN_OUTPUT_COUNT
ProcessId MQIACF_PROCESS_ID
QName MQCA_Q_NAME
ThreadId MQIACF_THREAD_ID
UncommittedMsgs MQIACF_UNCOMMITTED_MSGS
UserIdentifier MQCACF_USER_IDENTIFIER
The output of the InquireQueueStatus is dependent on the StatusType specified.
For StatusType 'Queue' (the default), the following fields are returned:
Key Macro
=== =====
CurrentQDepth MQIA_CURRENT_Q_DEPTH
OpenInputCount MQIA_OPEN_INPUT_COUNT
OpenOutputCount MQIA_OPEN_OUTPUT_COUNT
QName MQCA_Q_NAME
UncommittedMsgs MQIACF_UNCOMMITTED_MSGS
The following keys have Boolean values:
For StatusType 'Handle', the following fields are returned:
Key Macro
=== =====
ApplTag MQCACF_APPL_TAG
ApplType MQIA_APPL_TYPE
Browse MQIACF_OPEN_BROWSE
ChannelName MQCACH_CHANNEL_NAME
Conname MQCACH_CONNECTION_NAME
InputType MQIACF_OPEN_INPUT_TYPE
Inquire MQIACF_OPEN_INQUIRE
Output MQIACF_OPEN_OUTPUT
ProcessId MQIACF_PROCESS_ID
QName MQCA_Q_NAME
Set MQIACF_OPEN_SET
ThreadId MQIACF_THREAD_ID
UserIdentifier MQCACF_USER_IDENTIFIER
The following keys have special value mappings:
Key Macro
=== =====
CHINIT MQAT_CHANNEL_INITIATOR
QMGR MQAT_QMGR
USER MQAT_USER
Key Macro
=== =====
Exclusive MQQSO_EXCLUSIVE
No MQQSO_NO
Shared MQQSO_SHARED
The following keys have Boolean values:
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands for the specific list.
Change Queue Manager Inquire Queue Manager Ping Queue Manager
The following keys have special value mappings:
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
ConfigurationEvent MQIA_CONFIGURATION_EVENT
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
SSLCRLNamelist MQCA_SSL_CRL_NAMELIST
SSLCryptoHardware MQCA_SSL_CRYPTO_HARDWARE
SSLKeyRepository MQCA_SSL_KEY_REPOSITORY
StartStopEvent MQIA_START_STOP_EVENT
SyncPoint MQIA_SYNCPOINT
TriggerInterval MQIA_TRIGGER_INTERVAL
The following keys have Boolean values:
Subsets of the these keys are applicable to the following commands. As these are not PCF commands, see the MQSC command reference to see which keys are applicable for each each.
Change StorageClass Create StorageClass Delete StorageClass Inquire StorageClass Inquire StorageClass Names
The following keys have special value mappings:
Key
===
AlterationDate
AlterationTime
PageSetId
QSharingGroupDisposition
StorageClassDesc
StorageClassName
XCFGroupName
XCFMemberName
The following keys have Boolean values:
Subsets of the these keys are applicable to the following commands. As these are not PCF commands, see the MQSC command reference to see which keys are applicable for each each. Note that the CFStruct (Coupling Facility Application Structure) commands are available starting with release 5.3 of WebSphere MQ for z/OS.
Change CFStruct Create CFStruct Delete CFStruct Inquire CFStruct Inquire CFStruct Names
The following keys have special value mappings:
Key
===
AlterationDate
AlterationTime
CFStructDesc
CFStructLevel
CFStructName
Recovery
Subsets of the these keys are applicable to the following commands. See the documentation for each of the commands 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:
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
Key Macro
=== =====
ForceRemove MQACT_FORCE_REMOVE
The following keys have Boolean values:
This command is not really part of a grouping, so its all by itself here.
The following keys have special value mappings:
Key Macro
=== =====
MQSC MQET_MQSC
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 AuthInfo Names Inquire Channel Names Inquire Namelist Names Inquire Process Names Inquire Queue Names Inquire StorageClass Names (z/OS) Inquire CFStruct Names (z/OS)
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 AuthInfo Inquire CFStruct Inquire Channel Inquire Channel Status Inquire Cluster Queue Manager Inquire Namelist Inquire Process Inquire Queue Inquire Queue Manager Inquire Storage Class 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:
The following keys have special value mappings:
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
Macro Key
===== ===
MQMCAS_RUNNING Running
MQMCAS_STOPPED Stopped
The following keys can be interpreted in a Boolean context:
The following keys have special value mappings:
Macro Key
===== ===
MQQMDT_AUTO_CLUSTER_SENDER AutoClusterSender
MQQMDT_AUTO_EXP_CLUSTER_SENDER AutoExplicitClusterSender
MQQMDT_CLUSTER_RECEIVER ClusterReceiver
MQQMDT_EXPLICIT_CLUSTER_SENDER ExplicitClusterSender
Macro Key
===== ===
MQQMT_NORMAL Normal
MQQMT_REPOSITORY Repository
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:
The following keys have special value mappings:
Macro Key
===== ===
MQCQT_ALIAS_Q Alias
MQCQT_LOCAL_Q Local
MQCQT_Q_MGR_ALIAS QMgrAlias
MQCQT_REMOTE_Q Remote
The following keys have special value mappings:
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:
MQSeries(3), MQSeries::Queue(3), MQSeries::Message(3), MQSeries::Command::Request(3), MQSeries::Command::Response(3)
In addition, the MQSeries documentation is the primary source of documentation for the commands and their arguments, especially the following sections.
For MQSeries 5.2 and before, this is:
"MQSeries Programmable System Management"
Part 2. Programmable Command Formats
Chapter 8. Definitions of the Programmable Command Formats
Chapter 9. Structures used for commands and responses
For WebSphere MQ 5.3, this is:
"WebSphere MQ Programmable Command Formats and Administration Interface"
Part 1. Programmable Command Formats
Chapter 4. Definitions of the Programmable Command Formats
Chapter 5. Structures used for commands and responses
