QueueController

The second part of the URI must be queue to call the QueueController.

inquire

Get information about one or more queues. This action executes the MQCMD_INQUIRE_Q pcf command. On success, the returned JSON object will have a data array, on failure an error object.

URL Parameters

/api/queue/inquire/<QueueManager>/<QName>

QueueManager

The name of the queuemanager. This parameter is required.

QName

The name of a queue. Generic queue names are supported. This parameter is optional.

Query Parameters

CFStructure

Specifies the name of the storage class. This parameter is valid only on z/OS.

ClusterInfo

When true cluster information about queues and other queues in the repository that match the selection criteria is returned. By default this is false.

CommandScope

Specifies how the command is executed when the queue manager is a member of a queue-sharing group. This parameter applies to z/OS only.

CurrentQDepth

Only return queues which have at least CurrentQDepth messages. This is actually a shortcut for a Filter :

filter=I&filter_param=CurrentQDepth&filter_op=NLT&filter_value=<value>

For compatibility reasons with older versions this parameter can also be passed as QueueDepth.

Be aware that only one integer/string filter can be used for each call.

ExcludeSystem

When value is true, all queues starting with SYSTEM. will be discarded. This parameter is optional. By default the value is set to false.

ExcludeTemp

When value is true, all temporary queues will be discarded. This parameter is optional. By default the value is set to false.

When the QAttrs parameter is used, the DefinitionType attribute must be selected to make this work.

Filter

Speficies which filter to use: I means Integerfilter, S means Stringfilter. FilterParam and FilterValue are required to create the filter. When a filter can’t be build because of too little information, it will be silently discarded.

FilterOp

The operator that is being used to evaluate whether the parameter satisfies the filter-value. The default is EQ.

The following values are allowed:

A Stringfilter can use some additional operators:

FilterParam

The name of the parameter to filter on. The names are based on the names used in the WebSphere MQ information center.

FilterValue

The value to use for filtering. When a string is passed for an Integerfilter, a WebSphere MQ constant is assumed.

PageSetID

This parameter specifies that eligible queues are limited to those having the specified PageSetID value. This parameter applies to z/OS only.

QAttrs

With the QAttrs parameter you can specify which attributes must be returned from the PCF command. Multiple occurences of this parameter are possible. The value must be a valid attribute name.

Attrs is a synonym for QAttrs

QName

Only return queues with a name that matches QName. By default * is used which matches all queues. Name is a synonym for this parameter.

This parameter is ignored when there is a URI parameter for a queuename.

For compatibility reasons with older versions this parameter can also be passed as QueueName.

QSGDisposition

Disposition of the object within the group. Possible values are Live, Copy, Group, QMgr, Private or All. This parameter applies to z/OS only.

QType

Only return the queues of the given type. Possible values are Local, Remote, Model, Alias, Cluster or All. Default is All. The value is case-sensitive.

For compatibility reasons with older versions this parameter can also be passed as QueueType.

Usage

Only return queues with the given usage type. Use normal or xmitq. When this parameter is not set, all queues will be returned. The value is not case-sensitive.

This parameter doesn’t actually exist for MQCMD_INQUIRE_Q, but because it is useful to only get information for transmission queues this parameter is added.

When the QAttrs parameter is used, the Usage attribute must be selected to make this work.

For compatibility reasons with older versions this parameter can also be passed as QueueUsage.

Example

/api/queue/inquire/PIGEON/MQWEB.TEST.Q1
/api/queue/inquire/PIGEON/*
/api/queue/inquire/PIGEON?QName=*&CurrentQDepth=1
/api/queue/inquire/PIGEON?QAttrs=QName&QAttrs=CurrentQDepth

This sample is a PHP script that inquires all SYSTEM queues from the PIGEON queuemanager:

<?php
	/*
	 * This sample will show all SYSTEM queues from queuemanager PIGEON and
	 * prints the current queue depth if this property exists for the queue.
	 * MQWeb runs on localhost and is listening on port 8081. 
	 */
	$url = "http://localhost:8081/api/queue/inquire/PIGEON/SYSTEM*";

	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, $url);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

	if ( ($response = curl_exec($curl)) === false )	{
		$err = curl_error($curl);
		echo "An HTTP error occurred while getting queue information: $err\n";
	}
	else {
		$json = json_decode($response);
		if ( isset($json->error) ) {
			echo "An MQ error occurred while inquiring queues.\n";
			echo "Reason Code: {$json->error->reason->code} - {$json->error->reason->desc}\n";
		}
		else {
			if ( isset($json->data) && count($json->data) > 0 ) {
				foreach($json->data as $queue)
				{
					echo $queue->QName->value;
					if ( isset($queue->CurrentQDepth) ) {
						echo ': ' . $queue->CurrentQDepth->value;
					}
					echo "\n";
				}
			}
			else
			{
				echo "No queues found\n";
			}
		}
	}

JSON Object

When using an application/json POST request you can post a JSON object with names like the query parameters.

All URL parameters and query parameters are ignored except for the URL parameter for the name of the queuemanager.

    {
      'QName' : 'T*',
      'QAttrs' : [
        'QName',
        'CurrentQDepth'
      ],
      'IntegerFilterCommand' : {
        'Parameter' : 'CurrentQDepth',
        'Operator' : 'NLT',
        'FilterValue' : 1
      }
    }

There are some differences between query parameters and a JSON object:

An IntegerFilterCommand can’t be used together with a StringFilterCommand

This sample is a Perl script that inquires all SYSTEM queues and shows the current depth of these queues:

#!/usr/bin/perl
use strict;
use warnings;
use feature qw(say);

use JSON;
use LWP::UserAgent;
use HTTP::Request::Common;

# This sample will show all SYSTEM queues from the given queuemanager and
# prints the current queue depth if this property exists for the queue.

my $qmgr = shift;
die("Please pass me the name of a queuemanager as argument") 
	unless defined($qmgr);

my $json = JSON->new;

my %input = ( 
	'QName' => 'SYSTEM*',
	'QAttrs' => [
		'CurrentQDepth'
		# No need to add QName, it is always returned
	]
);
my $content = $json->encode(\%input);    

my $ua = LWP::UserAgent->new;
my $req = POST 'http://localhost:8081/api/queue/inquire/' . $qmgr;
$req->header(
	'Content-Type' => 'application/json',
	'Content-length' => length($content)
);
$req->content($content);

my $res = $ua->request($req);
die $res->status_line unless $res->is_success;
	
my $mqweb = $json->decode($res->content());
if ( exists($mqweb->{error}) ) {
	say 'An MQ error occurred while inquiring queues.';
	say 'Reason Code: '
		, $mqweb->{error}->{reason}->{code}
		, ' - '
		, $mqweb->{error}->{reason}->{desc};
}
else {
	foreach my $queue(@{$mqweb->{data}}) {
		my $output = $queue->{QName}->{value};
		$output .= ' : ' . $queue->{CurrentQDepth}->{value} 
			if ( exists($queue->{CurrentQDepth}) );
		say $output;
	}
}