QueueController

The second part of the URI must be queue to call the QueueController. This controller has the following actions:

• clear
• copy
• create
• inquire
• remove

clear

Clears a queue by removing all messages. This action will execute MQCMD_CLEAR_Q. On success the JSON response object will have an empty data array, on failure an error object.

URL Parameters

api/queue/clear/<QueueManager>/<QName>

QueueManager

The name of the queuemanager. This parameter is required.

FromQName

The name of a queue to copy from. This parameter is required.

Query Parameters

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.

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.

copy

Create a new queue by copying attributes from another queue. This action will execute MQCMD_COPY_Q. On success the JSON response object will have an empty data array, on failure an error object.

URL Parameters

api/queue/copy/<QueueManager>/<FromQName>/<ToQName>

QueueManager

The name of the queuemanager. This parameter is required.

FromQName

The name of a queue to copy from. This parameter is optional if you use the corresponding query parameter.

ToQName

The name of the new queue. This parameter is optional if you use the corresponding query parameter.

Query Parameters

All query parameters are copied as attribute for the queue. FromQName, ToQname and QType are required. When a POST request is used, all query parameters will be ignored.

/api/queue/copy/PIGEON/MQWEB.TEST.Q1/MQWEB.TEST.Q2?QType=Local

JSON Object

When using an application/json POST request you can post a JSON object to create a queue. All URL parameters (except queuemanager) and query parameters are ignored.

Example

This sample is a Python script that creates a copy from a local queue:

'''
 This sample will copy a local queue.
 MQWeb runs on localhost and is listening on port 8081.
'''
import json
import httplib
import socket
import argparse

parser = argparse.ArgumentParser(
	description='MQWeb - Python sample - Copy local queue',
	epilog="For more information: http://www.mqweb.org"
)
parser.add_argument('-m', '--queuemanager', help='Name of the queuemanager', required=True)
parser.add_argument('-q', '--queue', help='Name of the queue', required=True)
parser.add_argument('-t', '--to_queue', help='Name of the new queue', required=True)
args = parser.parse_args()

url = "/api/queue/copy/" + args.queuemanager
data = {
    'FromQName' : args.queue,
    'ToQName' : args.to_queue,
    'QType' : 'Local'
}

try:
	conn = httplib.HTTPConnection('localhost', 8081)
	conn.request('POST', url, json.dumps(data), { 'Content-Type': 'application/json' })
	res = conn.getresponse()
	result = json.loads(res.read())

	if 'error' in result:
		print ('Received a WebSphere MQ error: ' +
			str(result['error']['reason']['code']) + ' - '  +
			result['error']['reason']['desc']
		)
	else:
		print(args.queue + ' copied to ' + args.to_queue + ' on ' + args.queuemanager)

except httplib.HTTPException as e:
	print ('An HTTP error occurred while creating queue: ' +
		e.errno + e.strerror
	)
except socket.error as e:
	print e.strerror
	print 'Is the MQWeb daemon running?'

create

Create a new queue. This action will execute MQCMD_CREATE_Q. On success the JSON response object will have an empty data array, on failure an error object.

URL Parameters

api/queue/create/<QueueManager>/<QName>

QueueManager

The name of the queuemanager. This parameter is required.

QName

The name of a queue. This parameter is optional.

Query Parameters

All query parameters are copied as attribute for the queue. QName and QType are required. If a queuename is passed on the URL, the QName query parameter will be ignored.

JSON Object

When using an application/json POST request you can post a JSON object to create a queue. All URL parameters (except queuemanager) and query parameters are ignored.

Example

/api/queue/create/PIGEON/MQWEB.TEST.Q1?QType=Local

This sample is a Python script that creates an alias queue:

'''
 This sample will create a new alias queue.
 MQWeb runs on localhost and is listening on port 8081.
'''
import json
import httplib
import socket
import argparse

parser = argparse.ArgumentParser(
	description='MQWeb - Python sample - Create alias queue',
	epilog="For more information: http://www.mqweb.org"
)
parser.add_argument('-m', '--queuemanager', help='Name of the queuemanager', required=True)
parser.add_argument('-a', '--alias', help='Name of the alias queue', required=True)
parser.add_argument('-t', '--target', help='Name of the target queue', required=True)
args = parser.parse_args()

url = "/api/queue/create/" + args.queuemanager

input = {
	'QName' : args.alias,
	'QType' : 'Alias',
	'BaseObjectName' : args.target,
	'BaseType' : 'Queue'
}

try:
	conn = httplib.HTTPConnection('localhost', 8081)
	headers = {
		'Content-Type': 'application/json'
	}
	conn.request('POST', url, json.dumps(input), headers)
	res = conn.getresponse()
	result = json.loads(res.read())

	if 'error' in result:
		print ('Received a WebSphere MQ error: ' +
			str(result['error']['reason']['code']) + ' - '  +
			result['error']['reason']['desc']
		)
	else:
		print('Alias ' + args.alias + ' for ' + args.target + ' created on ' + args.queuemanager)

except httplib.HTTPException as e:
	print ('An HTTP error occurred while inquiring queues: ' +
		e.errno + e.strerror
	)
except socket.error as e:
	print e.strerror
	print 'Is the MQWeb daemon running?'

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>

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:

• GT : Greater than
• LT : Less than
• EQ : Equal to
• NE : Not equal to
• NLT : Not less than
• NGT : Not greater than
• LE : Less than or equal to
• GE : Greater than or equal to
• CT : Contains
• EX : Excludes

A Stringfilter can use some additional operators:

• LK : Matches a generic string
• NL : Does not match a generic string
• CTG : Contains an item which matches a generic string
• EXG : Does not contain any item which matches a generic string.

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. This parameter is ignored when there is a URI parameter for a 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.

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:

• JSON property names are case-sensitive
• QAttrs is a JSON array with attributenames as element.
• CurrentQDepth can’t be used. You need to use an IntegerFilterCommand to do the same.
• A filter is an object: IntegerFilterCommand can be used to filter on parameters which has integer values, while StringFilterCommand can be used to filter on parameters with string values. The filter object has these three properties: Parameter (see FilterParam), Operator (see FilterOp) and FilterValue (see FilterValue).

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;
	}
}

remove

Removes a queue. This action will execute MQCMD_DELETE_Q. On success the JSON response object will have an empty data array, on failure an error object.

URL Parameters

api/queue/remove/<QueueManager>/<QName>

QueueManager

The name of the queuemanager. This parameter is required.

QName

The name of the queue to remove. This parameter is optional when the QName is passed as query parameter.

Query Parameters

QName

The name of the queue to remove.

Authrec

Specifies whether the associated authority record is also deleted. Possible values are Yes(default) or No.

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.

Purge

If there are messages on the queue Yes must be specified, otherwise the command fails. If this parameter is not present the queue is not purged. Possible values are Yes or No(default).

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

If this parameter is present, the queue must be of the specified type. Possible values are Local, Remote, Model or Alias. The value is case-sensitive.