9.

IBM MQ Explorer

IBM
 Note
Before using this information and the product it supports, read the information in “Notices” on page
563.

This edition applies to version 9 release 3 of IBM® MQ and to all subsequent releases and modifications until otherwise
indicated in new editions.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it
believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2007, 2023.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

IBM MQ Explorer................................................................................................... 5
IBM MQ Explorer installation requirements................................................................................................5
What's new and what's changed in IBM MQ Explorer................................................................................ 6
Launching IBM MQ Explorer........................................................................................................................ 8
Multiple installations of IBM MQ Explorer...................................................................................................9
Installing IBM MQ Explorer into Eclipse environments............................................................................ 10
Displaying context-sensitive help (pop-up window help)........................................................................ 11
Configuring IBM MQ using IBM MQ Explorer............................................................................................ 12
Creating and configuring queue managers and objects......................................................................13
Testing your object definitions for problems....................................................................................... 45
Sending test messages........................................................................................................................ 71
Starting and stopping objects and services.........................................................................................73
Showing or hiding a queue manager....................................................................................................81
Connecting or disconnecting a queue manager.................................................................................. 91
Administering remote queue managers.............................................................................................. 92
Maintaining intercommunications along message channels.............................................................. 95
Configuring publish/subscribe messaging.......................................................................................... 98
Configuring publish/subscribe for IBM MQ queue managers............................................................. 99
Managing multi-instance queue managers....................................................................................... 110
Creating and configuring a queue manager cluster.......................................................................... 114
Managing security and authorities.....................................................................................................125
Viewing the status of objects.............................................................................................................171
Viewing and closing connections to applications............................................................................. 172
Creating and configuring JMS administered objects.............................................................................. 172
JMS contexts...................................................................................................................................... 174
JMS connection factories...................................................................................................................175
JMS destinations (queues and topics)...............................................................................................177
Messaging providers for IBM MQ classes for JMS............................................................................ 178
Adding an initial context.................................................................................................................... 178
Connecting and disconnecting an initial context.............................................................................. 180
Removing an initial context................................................................................................................181
Creating a connection factory............................................................................................................ 182
Creating a destination........................................................................................................................ 183
Creating a JMS object and an IBM MQ object simultaneously......................................................... 184
Creating a JMS object from an IBM MQ object..................................................................................186
Copying an administered object........................................................................................................ 187
Changing the transport type used for connections........................................................................... 187
Creating a subcontext........................................................................................................................ 188
Renaming an administered object..................................................................................................... 189
Renaming a context............................................................................................................................189
Deleting an administered object........................................................................................................190
Deleting a subcontext........................................................................................................................ 191
Configuring IBM MQ Explorer..................................................................................................................192
Filtering the objects displayed in tables............................................................................................193
Creating and configuring a service definition.................................................................................... 196
Creating and configuring a queue manager set.................................................................................201
Define schemes to change the order of columns in tables...............................................................217
Changing the colors............................................................................................................................221
Enabling installed plug-ins.................................................................................................................221
Changing the refresh frequency of queue manager information......................................................222
Specifying the default values used to connect to remote queue managers.................................... 223
Exporting and importing settings.......................................................................................................224

iii
 Including SYSTEM objects when you run tests................................................................................. 225
Including hidden queue managers in test configurations................................................................ 226
Displaying object authority settings as text...................................................................................... 226
Using Advanced Message Security..........................................................................................................227
Message signing................................................................................................................................. 227
Message encryption........................................................................................................................... 227
Distinguished names..........................................................................................................................227
Troubleshooting problems with IBM MQ Explorer................................................................................. 228
Collecting IBM MQ Explorer trace..................................................................................................... 229
Collecting IBM MQ Explorer trace in other Eclipse environments....................................................230
Using IBM MQ trace........................................................................................................................... 234
Collecting Javacore from IBM MQ Explorer...................................................................................... 235
Using MQ Telemetry................................................................................................................................ 237
MQ Telemetry objects........................................................................................................................ 237
MQTT client utility.............................................................................................................................. 239
Configuring MQ Telemetry using IBM MQ Explorer...........................................................................243
Administering MQ Telemetry using IBM MQ Explorer.......................................................................249
Troubleshooting MQ Telemetry using IBM MQ Explorer...................................................................253
MQ Telemetry reference.................................................................................................................... 256
IBM MQ Tutorials..................................................................................................................................... 259
Tutorial 1: Sending a message to a local queue................................................................................259
Tutorial 2: Sending a message to a remote queue............................................................................266
Tutorial 3: Sending a message on a client-server configuration.......................................................274
Reference.................................................................................................................................................279
Accessibility in IBM MQ Explorer.......................................................................................................279
Icons in IBM MQ Explorer.................................................................................................................. 280
Views in IBM MQ Explorer..................................................................................................................285
Preferences for IBM MQ Explorer...................................................................................................... 293
Properties........................................................................................................................................... 308
Status attributes.................................................................................................................................515
Byte array dialog................................................................................................................................ 553
Strings in property dialogs................................................................................................................. 553
Identifying durable subscriptions to the SYSTEM.FTE topic ........................................................... 554
Extending IBM MQ Explorer.................................................................................................................... 555
Importing the sample Eclipse plug-ins............................................................................................. 555
Writing an Eclipse plug-in for IBM MQ Explorer................................................................................556
Applying plug-ins to IBM MQ Explorer.............................................................................................. 560
API Reference.......................................................................................................................................... 561

Notices..............................................................................................................563
Programming interface information........................................................................................................ 564
Trademarks.............................................................................................................................................. 564

iv
Introduction to IBM MQ Explorer
IBM MQ Explorer is the graphical user interface in which you can administer and monitor IBM MQ objects,
whether they are hosted by your local computer or on a remote system.
IBM MQ Explorer runs on Windows and Linux® x86-64. It can remotely connect to queue managers that
are running on any supported platform including z/OS®, enabling your entire messaging backbone to be
viewed, explored, and altered from the console.
IBM MQ Explorer is built on open source Eclipse technology. As such, IBM MQ Explorer is highly
customizable and fully extensible. You can add new tools as plug-ins to IBM MQ Explorer to provide
new features in a way that is integrated into the console.

From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ
install package. It remains available as a stand-alone download available from Fix Central.
Related tasks
Installing IBM MQ Explorer as a stand-alone application on Linux and Windows
Related reference
“Accessibility in IBM MQ Explorer” on page 279
Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.

IBM MQ Explorer installation requirements

Before you install IBM MQ Explorer, review the minimum installation requirements.

IBM MQ Explorer is available for Windows x86_64 and Linux x86_64. From
IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It remains
available as a separate download, and can be installed from the stand-alone IBM MQ Explorer download
available from Fix Central.
The requirements to install IBM MQ Explorer from the stand-alone IBM MQ Explorer download available
from Fix Central include:
• 512 MB RAM
• 1 GHz processor
• At least 300 MB available disk space
• A suitable monitor for the operating system with a screen size of at least 1024x768
• On Linux, GTK2 including the GTK2-engines, which contain the GTK2 themes. The minimum GTK2 level
depends on the version of IBM MQ. From IBM MQ 9.1, GTK+ version 2.18.0, or later, is supported.
• Bitstream-vera-fonts (applies to Linux only).
Note: On Linux, if you have both GTK2 and GTK3 installed on your system then you must disable GTK3
with the environment variable SWT_GTK3=0.
IBM MQ Explorer is not supported on Eclipse platforms at a higher level than the one that it is built on.
However, IBM MQ Explorer is backwards compatible with earlier levels of Eclipse than the one that it is
built on.
For information about the Eclipse level that IBM MQ Explorer is built on, see “What's new and what's
changed in IBM MQ Explorer” on page 6.
Related tasks
Installing IBM MQ Explorer as a stand-alone application on Linux and Windows
Related information
Windows 8 system requirements

© Copyright IBM Corp. 2007, 2023 5

 Windows 10 system requirements

What's new and what's changed in IBM MQ Explorer

Learn about the main new and changed functions in IBM MQ Explorer.

New IBM MQ Explorer features in IBM MQ 9.3.0

From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ
install package. It remains available as a separate download.

New IBM MQ Explorer features in IBM MQ 9.2.x

From IBM MQ 9.2.0, IBM MQ Explorer is built on Eclipse 4.15.
For more information about installation requirements, see “IBM MQ Explorer installation requirements”
on page 5 and “Installing IBM MQ Explorer into Eclipse environments” on page 10.

New IBM MQ Explorer features in IBM MQ 9.1.x

Change to version of Eclipse that IBM MQ Explorer is built on
From IBM MQ 9.1.0, IBM MQ Explorer is built on Eclipse 4.7.3 instead of Eclipse 4.6.3.

From IBM MQ 9.1.4, IBM MQ Explorer is built on Eclipse 4.8 instead of Eclipse 4.7.3.
This change to the Eclipse level applies to Continuous Delivery only. For Long Term Support, the
Eclipse level remains at Eclipse 4.7.3.

From IBM MQ 9.1.5, IBM MQ Explorer is built on Eclipse 4.11 instead of Eclipse 4.8. This
change to the Eclipse level applies to Continuous Delivery only. For Long Term Support, the Eclipse
level remains at Eclipse 4.7.3.
Changes to delivery mechanism for updates to stand-alone IBM MQ Explorer
From IBM MQ 9.1.4, the stand-alone IBM MQ Explorer, previously known as SupportPac
MS0T, is available as a stand-alone application from Fix Central. SupportPac MS0T is no longer
available from the IBM download site.
For more information about installation requirements, see “IBM MQ Explorer installation requirements”
on page 5 and “Installing IBM MQ Explorer into Eclipse environments” on page 10.

New IBM MQ Explorer features in IBM MQ 9.0.4

IBM MQ Explorer is built on Eclipse 4.6.3 instead of Eclipse 4.4.2.
For more information about installation requirements, see “IBM MQ Explorer installation
requirements” on page 5 and “Installing IBM MQ Explorer into Eclipse environments” on page 10.

New IBM MQ Explorer features in IBM MQ 9.0

IBM MQ Explorer is built on Eclipse 4.4.2 instead of Eclipse 4.3.2.
For more information about installation requirements, see “IBM MQ Explorer installation
requirements” on page 5 and “Installing IBM MQ Explorer into Eclipse environments” on page 10.

New IBM MQ Explorer features in IBM MQ 8.0

IBM MQ Explorer is built on Eclipse 4.3.1 instead of Eclipse 3.6.2.
For more information about installation requirements, see “IBM MQ Explorer installation
requirements” on page 5 and “Installing IBM MQ Explorer into Eclipse environments” on page 10.

6 IBM MQ Explorer
Support for topic host routing for publish/subscribe clusters
In previous versions, when you configure a clustered topic on a queue manager, all queue managers
in the cluster become aware of all other queue managers in the cluster. When performing publish and
subscribe operations, each queue manager then connects directly to all the others. This approach is
still available in IBM MQ 8.0, where it is known as direct routing.
In IBM MQ 8.0, an alternative approach has also been added, known as topic host routing. With this
approach, all queue managers in the cluster become aware of the cluster queue managers that host
the routed topic definitions. When performing publish and subscribe operations, queue managers in
the cluster connect only to these topic host queue managers, and not directly to each other. The
topic host queue managers are responsible for routing publications from queue managers on which
publications are published to queue managers with matching subscriptions.
To support topic host routing, the following parameters are added:
• Cluster publication route. The routing behavior of publications between queue managers in
a cluster. This is set on the cluster tab of a topic object and is displayed on the cluster tab of a topic
object and when displaying cluster topics.
• Cluster object state. The current state of the clustered topic definition. This is displayed on
the cluster tab of a topic object, and when displaying cluster topics.
• Version. The version of the IBM MQ installation that the cluster queue manager is associated with.
This is displayed on the cluster-sender channels tab of the queue manager clusters display.
Support to better understand the size of your system
The following parameters are added to the publish/subscribe information reported. They are
displayed on the Publish/Subscribe status page for a given queue manager.
• Sub count. Shows the total number of subscriptions against the local topic tree.
• Topic count. Shows the total number of topic nodes in the local topic tree.
For more information, see “Queue manager Publish/Subscribe Engine status attributes” on page 524.
New connection details properties
For more information, see “Connection details properties” on page 466.
CHCKLOCL
Setting CHCKLOCL to Required for administrators or Required for all stops you from
locally administering the queue manager by way of the runmqsc commands unless you specify the -u
UserID parameter on the runmqsc command line.
For more information, see the CHKLOCL MQSC parameter explanation in the “User ID + Password
page” on page 423 section of “Authentication information properties” on page 420.
Security enabled remote queue manager connections
The SSL cipher specification RC2_MD5_EXPORT is no longer supported. Connections that use this
cipher specification and that are imported into IBM MQ Explorer for IBM MQ 8.0 have a blank SSL
cipher specification setting. A new cipher specification must be selected.
If a connection that was using this cipher specification is imported into IBM MQ Explorer 8 and then
used without changing it, a dialog that contains the IBM MQ error message AMQ4199 is displayed.
Deprecation of specific SSLv3 Cipher Suites
The three SSL cipher specifications listed in Java and JMS: changes to CipherSuite support in the IBM
MQ 8.0 product documentation are no longer supported.
However, you can re-enable other SSLv3 ciphers. See Deprecation: SSLv3 Ciphers in the IBM MQ 8.0
product documentation.

New for z/OS

For z/OS, the following changes are described in “Queue manager properties” on page 315 and
“Channel properties” on page 369:
• New “Statistics monitoring (z/OS)” on page 350 section.

Introduction to IBM MQ Explorer 7

 • Link added from “Statistics monitoring (Multiplatforms)” on page 333 to “Statistics monitoring (z/
OS)” on page 350.
• New Security policies, *Maximum ACE pool size (KB), and Excluded operator
messages parameters added to “System (z/OS)” on page 354.
• Channel statistics parameter description enhanced in “Statistics page” on page 388.
• Clarification added to the Cluster channel names parameter for z/OS. For more information,
see the Cluster channel names attribute in the “Extended page” on page 359 of “IBM MQ
queue properties” on page 358.
Related reference
“Icons in IBM MQ Explorer” on page 280
IBM MQ Explorer uses icons to represent the different objects, such as queue managers, queues, and
channels.

Launching IBM MQ Explorer

You can launch IBM MQ Explorer from the system menu on Linux, or the start menu on Windows.
Alternatively, you can use the MQExplorer command.

Before you begin

From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ
installation package. It remains available as a separate download, and can be installed from the stand-
alone IBM MQ Explorer download available from Fix Central.

Procedure
• To launch IBM MQ Explorer by using the system menu on Linux, or the start menu on Windows,
left-click the installation that you want to launch.

On Linux, the system menu entry for IBM MQ Explorer is added to the Development
category; where it appears within the system menu is dependent on your Linux distribution (SUSE or
Red Hat®), and your desktop environment (GNOME or KDE).
– On SUSE, left-click Computer > More Applications..., and find the installation of IBM MQ Explorer
that you want to launch under the Development category.
– On Red Hat, the installation of IBM MQ Explorer that you want to launch can be found under
Applications > Programming.

On Windows, open the start menu, and select the IBM MQ Explorer installation entry
under the IBM MQ group that corresponds to the installation that you want to launch. Each instance of
IBM MQ Explorer listed is identified by the name that you chose for its installation.
• To launch IBM MQ Explorer from the command line, enter the MQExplorer command.
The MQExplorer command is in MQ_EXPLORER_INSTALLATION_PATH, where
MQ_EXPLORER_INSTALLATION_PATH is the installation path for the stand-alone IBM MQ Explorer.
MQExplorer.exe (the launch MQExplorer command) supports standard Eclipse runtime options
including the following options:
-clean
Clean the caches used by the eclipse runtime to store bundle dependency resolution and eclipse
extension registry data. Using this option forces eclipse to reinitialize these caches.
-initialize
Initializes the configuration being run. All runtime-related data structures and caches are
refreshed. Any user/plugin defined configuration data is not purged. No application is run, any
product specifications are ignored and no UI is presented (for example, the splash screen is not
drawn).

8 IBM MQ Explorer
 For more information about the MQExplorer command, see MQExplorer (launch IBM MQ Explorer).

What to do next
For more information about multiple installations of IBM MQ, see “Multiple installations of IBM MQ
Explorer” on page 9.
To trace IBM MQ Explorer, use one of the following commands:

• On Linux use the runwithtrace command.

• On Windows use the runwithtrace.cmd command.

For more information, see “Troubleshooting problems with IBM MQ Explorer” on page 228.
Related tasks
Installing IBM MQ Explorer as a stand-alone application on Linux and Windows

Multiple installations of IBM MQ Explorer

An installation of IBM MQ Explorer can be included with each installation of IBM MQ on your system. Each
installation of IBM MQ Explorer is part of a separate installation of IBM MQ, and uses its own workspace.
If your system has multiple installations of IBM MQ Explorer, the only local queue managers shown on an
installation of IBM MQ Explorer are those local queue managers associated with that installation.

Copying settings between installations of IBM MQ Explorer

IBM MQ Explorer stores settings in a workspace; this workspace, identified by the name of the installation
of IBM MQ associated with it, is located in your home directory in IBM/WebSphereMQ/workspace-
Installation1. In this example, the name of the workspace associated with the workspace is
Installation1.
At startup, IBM MQ Explorer detects whether any workspaces from previous installations of IBM MQ are
present on your system.
If there is at least one workspace available from earlier installations of IBM MQ and IBM MQ Explorer, you
can choose whether to copy settings from one of these, or to start with a new workspace. At startup, a
dialog presents you with a list of these available workspaces, each of which is identified by the name of
the IBM MQ installation associated with it.
If you choose to copy settings from an earlier workspace, the settings copied are those used by the
current IBM MQ version of IBM MQ Explorer:
• IBM MQ Explorer Preferences
• IBM MQ Explorer Test Configurations
• Remote Queue Manager connections
• Queue Manager sets
• Schemes and Filters
• JMS Admin objects
• Service Definition repositories
• IBM Integration Bus data (if applicable)
• Managed File Transfer data (if applicable)
• SupportPac MS0P (if applicable)
These settings are not copied from the workspace:
• Any preferences unrelated to IBM MQ Explorer, IBM Integration Bus, or Managed File Transfer.
• Any projects unrelated to Service Definition repositories.

Introduction to IBM MQ Explorer 9

 • IBM MQ Explorer Test Results.
• Any other Eclipse settings, including views and perspective changes.
• Any other SupportPacs or extensions to IBM MQ Explorer; these add-ons must be reinstalled if you want
to use them with your new workspace.

Installing IBM MQ Explorer into Eclipse environments

You can install IBM MQ Explorer into your own Eclipse environment or Eclipse-based product to help with
developing Java applications or to develop your own extensions.

Before you begin

If you are using a version of Windows with User Account Control (UAC) enabled and your
Eclipse-based product is installed into a directory under UAC such as C:\Program Files, then you
must run the Eclipse-based product with elevated authority (Run as Administrator) before you install the
IBM MQ Explorer feature into it. When installed, the product can then be run without elevated authority.
For information about the Eclipse level that IBM MQ Explorer is built on, see “What's new and what's
changed in IBM MQ Explorer” on page 6.
Note: Before you place the IBM MQ Explorer plug-ins into your own Eclipse environment or Eclipse-based
product, consult the Detailed System Requirements report for your platform, and your version of IBM MQ
(see System Requirements for IBM MQ).
For information about the environments in which IBM MQ Explorer plug-ins are supported, see the
Development tools section of the Supported Software tab of the IBM MQ Detailed System Requirements
report.
To use the full set of cipher suites, and to operate with certified FIPS 140-2 or Suite-B compliance, a
suitable Java runtime environment (JRE) is required. IBM Java 7 Service Refresh 4, Fix Pack 2 or a higher
level of the IBM JRE provides the appropriate support. For more information, see the Java section of the
Supported Software tab of the IBM MQ Detailed System Requirements report.

About this task

IBM MQ Explorer is built on Eclipse as a stand-alone application that uses the Eclipse Rich Client
Platform. You can also install IBM MQ Explorer into your own compatible Eclipse environment or an
Eclipse-based product to aid with developing Java applications with IBM MQ, or developing your own
extensions to IBM MQ Explorer.

Procedure
To install IBM MQ Explorer into a compatible Eclipse-based environment:
1. Click Help and then click Install New Software in the Eclipse environment.
2. Click Add and then click Archive, and then browse to the mqexplorer/eclipse directory inside the
IBM MQ installation directory. Select the file MQExplorerSDK.zip.
3. Click OK after optionally typing a name for the local site.
4. A category of MQ Explorer is displayed. Expand this category and select MQ Explorer and optionally,
the translations.
5. Click Next and follow the instructions. Then, click the button to restart Eclipse (or the Eclipse-based
product).
If the installation fails due to a missing bundle, for example, org.eclipse.draw2d, you must install
the Eclipse Graphical Editing Framework (GEF) tools.
6. IBM MQ Explorer is available as a separate perspective. To view, click Open perspective, and then
click Other.

10 IBM MQ Explorer
 What to do next
If IBM MQ Explorer is being used to administer only remote queue managers, no further configuration is
required. If there are local queue managers to administer, you must run the Eclipse-based product with
the required environment settings for your operating system. In addition, the Eclipse-based product must
be a 64-bit application to match the 64-bit local queue managers.

On Windows, set the PATH environment variable to include the bin64 and java/lib64
directories of your IBM MQ installation. You can use the setmqenv command to do set the PATH
environment variable before you start the Eclipse-based product from the same command line. For
example, if IBM MQ is installed in directory C:\Program Files\IBM\MQ, and the stand-alone IBM
MQ Explorer is installed in directory C:\Program Files\IBM\MQ Explorer, enter the following
commands:

"C:\Program Files\IBM\MQ\bin\setmqenv" -s
"C:\Program Files\IBM\MQ Explorer\MQExplorer.exe"

On Linux x86_64 systems:

• Run the setmqenv command to configure your IBM MQ environment. For example, if IBM MQ is installed
in directory /opt/mqm, enter the following command:

. /opt/mqm/bin/setmqenv -s

• Set the LD_LIBRARY_PATH environment variable to include the java/lib64 and lib64 directories of
your IBM MQ installation before you run the Eclipse-based product. For example, if IBM MQ is installed
in /opt/mqm:

export LD_LIBRARY_PATH=/opt/mqm/java/lib64:/opt/mqm/lib64:$LD_LIBRARY_PATH

• Start the Eclipse-based product from the same command line that ran the setmqenv command. For
example, if IBM MQ Explorer is installed in directory /opt/mqexplorer enter the following command:

. /opt/mqexplorer/MQExplorer

Related tasks
“Collecting IBM MQ Explorer trace in other Eclipse environments” on page 230
By using a variant of the runwithtrace command, you can collect trace from an instance of IBM MQ
Explorer that is installed into your own Eclipse environment or Eclipse-based product.

Displaying context-sensitive help (pop-up window help)

At any time when you are working in IBM MQ Explorer, you can get context-sensitive help.

About this task

In wizards, the help is displayed in the banner of the wizard; in the rest of IBM MQ Explorer, the help
is displayed in the pop-up window help. Pop-up window help can be displayed in two different ways,
depending on where it is requested from, and what the default preferences have been set to. The two
displayed forms are:
• Small, yellow boxes that contain a brief description, explanation, or instruction relevant to the part of
the interface that currently has focus.
• A section that slides out of the side of the current dialog or perspective, that contains a brief
description, explanation, or instruction relevant to the part of the interface that currently has focus.
The pop-up window help usually also contains a hyperlink that opens the help system to provide more
detailed information.

Introduction to IBM MQ Explorer 11

 The pop-up window help is available on a variety of objects in the IBM MQ Explorer interfaces; for
example, folders, views, and properties dialogs.
To display the pop-up window help in IBM MQ Explorer:

Procedure
1. Bring focus to a part of the interface; for example, click a folder or hover over a properties dialog.
2. Display the pop-up window help:

• On Windows, press F1.

• On Linux, press Ctrl+F1.

Results
The pop-up window help displays.

What to do next
You can change the pop-up window help preferences by following this process: Click Window >
Preferences > Help
The Help Preferences dialog opens.

Configuring IBM MQ using IBM MQ Explorer

In the Navigator view, you can use the Properties dialog to configure certain IBM MQ properties that
apply to the whole installation. If necessary, you can also configure the properties of individual queue
managers.

About this task

You can configure certain properties of IBM MQ that apply to the whole installation of IBM MQ on the
computer. You can configure individual queue managers to override the IBM MQ properties if necessary.
To configure IBM MQ, complete the following steps.

Procedure
1. In the Navigator view, right-click IBM MQ , then click Properties... The Properties dialog opens.
2. In the Properties dialog, configure any of the following types of property as required:
• General: Basic IBM MQ properties, such as the default location of queue managers on the computer.
• Extended: More advanced IBM MQ properties, such as how EBCDIC newline characters are
converted to ASCII.
• Exits: Configure IBM MQ to use code modules (exits) that you have written yourself.
• Default log settings: Change the location and type of IBM MQ logs.
• ACPI: Specify how IBM MQ should respond when the computer tries to hibernate.
• Alert monitor: Configure IBM MQ to alert you when there is a problem, such as a required queue that
is missing.

Results
Any changes you make to the IBM MQ properties are made for all queue managers and objects on the
computer, unless the individual queue managers are set up differently to override the IBM MQ settings.

12 IBM MQ Explorer
Creating and configuring queue managers and objects
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.

About this task

All of the queue managers and objects that you can administer in IBM MQ Explorer are contained
in folders in the Navigator view. For example, the Queue Managers folder contains all of the queue
managers that you can administer in IBM MQ Explorer; the Channels folder contains all of a queue
manager's channels. For most folders, when you right-click the folder, a menu is displayed so that you can
perform tasks such as creating a new object.
When you click a folder in the Navigator view, the contents of the folder are displayed in the Content view.
For example, when you click the Queues folder, the queue manager's queues are displayed in the Content
view. You can then right-click an object in the Content view to perform tasks such as opening the object's
properties dialog, and deleting the object.
The following topics provide instructions about how to create, configure, and delete queue managers and
objects in IBM MQ Explorer.
• “Creating an IBM MQ object from a JMS object” on page 34
• “Configuring queue managers and objects” on page 37
• “Forcing changes to queue properties” on page 38
• “Strings in property dialogs” on page 553

• “Configuring system parameters on z/OS queue managers” on page 43

• “Configuring resource security on z/OS queue managers” on page 44

• “Deleting queue managers and objects” on page 41

Objects in IBM MQ Explorer

In IBM MQ Explorer, all of the queue managers and their IBM MQ objects are organized in folders in the
Navigator view.
You can perform the following tasks on many of the folders:
• To view the objects, click the relevant folder and the objects that are in the folder are listed in the
Content view.
• To create new objects, right-click the folder.
• To configure or delete an object, right-click the object.
For more information about administering queue managers and their objects, see the following topics.
• Queue managers
• Queues
• Topics
• Cluster topics
• Subscriptions
• Channels (including client connections)
• Listeners
• Process definitions
• Namelists
• Authentication information
• Trigger monitors

Introduction to IBM MQ Explorer 13

 • Channel initiators
• Custom services

• Storage classes

• Queue sharing groups

• Coupling facility structures

• Queue manager clusters
• JMS contexts
• JMS connection factories
• JMS destinations
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

Queue managers
A queue manager is a program that provides messaging services to applications. Applications that use the
Message Queue Interface (MQI) can put messages on queues and get messages from queues. The queue
manager ensures that messages are sent to the correct queue or are routed to another queue manager.
The queue manager processes both the MQI calls that are issued to it, and the commands that are
submitted to it (from whatever source). The queue manager generates the appropriate completion codes
for each call or command.
The queue managers are the main components in an IBM MQ messaging network. The queue managers
host the other objects in the network, such as the queues and the channels that connect the queue
managers together. A queue manager must be running to perform the following tasks:
• Start channels
• Process MQI calls
• Create, delete, alter queues and channel definitions
• Run a command server to process MQSC commands
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
“Showing or hiding a queue manager” on page 81
By default, the Navigator view shows all of the queue managers on the computer on which IBM MQ
Explorer is installed. However, if you have any queue managers that you are not currently administering,
you can, if you wish, choose to hide them. You can also show and hide remote queue managers.
“Removing a queue manager” on page 90
You can remove a queue manager from IBM MQ Explorer if you no longer want to administer it in IBM MQ
Explorer.
Related reference
“Queue manager properties” on page 315

14 IBM MQ Explorer
 You can set properties for both local and remote queue managers.

IBM MQ queues
A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.
A queue has a limited capacity in terms of both the maximum number of messages that it can hold and
the maximum length of those messages.

Queue type Description

Local queue A local queue is a definition of both a queue and the
set of messages that are associated with the queue.
The queue manager that hosts the queue receives
messages in its local queues.
Transmission queue Transmission queues are a special type of local queue.
When the queue manager sends a message to a
queue on a remote queue manager, the transmission
queue stores the message locally until the queue on
the remote queue manager is available. To create a
transmission queue, create a local queue and change
its Usage attribute to Transmission.
Remote queue definition Remote queue definitions are definitions on the local
queue manager of queues that belong to another
queue manager. To send a message to a queue on a
remote queue manager, the sender queue manager
must have a remote definition of the target queue.
Alias queue Alias queues are not actually queues; they are
additional definitions of existing queues. You create
alias queue definitions that refer to actual local
queues but you can name the alias queue definition
differently from the local queue (the base queue).
This means that you can change the queues that
an application uses without needing to change the
application; you just create an alias queue definition
that points to the new local queue.
Model queue A model queue is a template for queues that you
want the queue manager to create dynamically as
required. When an application tries to put a message
on a model queue, the queue manager dynamically
creates a local queue with the same name as the
model queue. Queues that are created in this way can
either be temporary or permanent.
Cluster queue A cluster queue is a queue that has been shared in
a cluster so that all of the queue managers in the
cluster can put and get from the queue using cluster
channels. For more information, see Queue manager
clusters.

Introduction to IBM MQ Explorer 15

Queue type Description
z/OS only. A shared queue is a queue that has the
Shared queue
queue sharing group disposition of Shared. All of
the queue managers in the queue sharing group can
put and get from the queue without needing active
channels. Only local queues can have the disposition
of Shared. For more information, see
Queue sharing groups.
z/OS only. A group queue is a queue that has the
Group definition queue
queue sharing group disposition of Group. Each of
the queue managers in the queue sharing group has a
copy of the queue (with the disposition Copy) stored
on their own page set. Local, remote, alias, and model
queues can have the disposition Group.
For more information, see Queue sharing groups.

For more information about queues, see Queues.

Related concepts
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“IBM MQ queue properties” on page 358
The properties that you can set for a queue depend on the type of queue. Different types of IBM MQ
queues have different properties. Some of the properties do not apply to all types of queue, some
properties are specific to cluster queues, and some properties are specific to z/OS queues.

Topics
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
A topic identifies what a publication is about and consists of a character string that can be up to 10,240
character long. Topics are key to the successful delivery of messages in a Publish/Subscribe system.
Instead of including a specific destination address in each message, a publisher assigns a topic to each
message. The queue manager matches the topic with a list of subscribers who subscribe to that topic, and
delivers the message to each of those subscribers.
A publisher can control which subscribers receive a publication by choosing carefully the topic that is
specified in the message.
The topic of a message does not have to be defined before a publisher can use it; a topic is created when
it is specified in a publication or subscription for the first time.

16 IBM MQ Explorer
For the latest about topic strings, wildcard characters, special characters, and topic trees, refer to the
following information:
• A topic string can include any character from the Unicode character set, including the space character.
However, there are characters that have special meanings: plus sign (+), number sign (#), asterisk (*),
and question mark (?). For more information about these characters, see Wildcard schemes.
• Topic strings are case-sensitive, and although a null character does not cause an error, do not use null
characters in your topic strings. For the latest information about topic strings, see Using topic strings.
• Each topic that you define is an element, or node, in the topic tree. For the latest information about topic
trees, see Topic trees.

Wildcards and special characters in topic strings

This topic details the wildcards that are used in the IBM MQ implementation of Publish/Subscribe
messaging.
A topic can contain any character in the Unicode character set. However, the following three characters
have a special meaning in IBM MQ Publish/Subscribe:
The topic level separator "/".
The multilevel wildcard "#".
The single-level wildcard "+".
The topic level separator is used to introduce structure into the topic, and can therefore be specified
within the topic for that purpose.
Wildcards are a powerful feature of the topic system in IBM MQ Publish/Subscribe. Wildcards allow
subscribers to subscribe to more than one topic at a time. The multilevel wildcard and single level
wildcard can be used for subscriptions, but they cannot be used within a topic by the publisher of a
message.
However, if a publisher uses the characters "+" or "#" together with other characters in any topic level
within a topic, these characters are not treated as wildcards, and they do not have any special meaning.
Related concepts
“Publishers and subscribers” on page 98
Publishers and subscribers are applications that send and receive messages (publications) using the
publish/subscribe method of messaging. Publishers and subscribers are decoupled from one another so
that publishers do not know the destination of the information that they send, and subscribers do not
know the source of the information that they receive.
Related reference
“Topic status attributes” on page 532
The status attributes of topics.

Cluster topics
Topics can be clustered in a similar manner to cluster queues, although an individual topic object can be a
member of only one cluster. A topic is made into a cluster topic by defining, on the topic object, the name
of the cluster that is to host the topic, and the cluster routing mechanism to use for publications on this
topic.
There are two options for routing publications across a publish/subscribe cluster: direct routing and topic
host routing. To choose the message routing to use within the cluster, you set the CLROUTE property on
the administered topic object to one of the following values:
• DIRECT
• TOPICHOST
By default, topic routing is DIRECT. This was the only option prior to IBM MQ 8.0. When you configure
a direct routed clustered topic on a queue manager, all queue managers in the cluster become aware of
all other queue managers in the cluster. When performing publish and subscribe operations, each queue
manager then connects directly to all the others.

Introduction to IBM MQ Explorer 17

 From IBM MQ 8.0, you can instead configure topic routing as TOPICHOST. When you use topic host
routing, all queue managers in the cluster become aware of the cluster queue managers that host the
routed topic definitions. When performing publish and subscribe operations, queue managers in the
cluster connect only to these topic host queue managers, and not directly to each other. The topic host
queue managers are responsible for routing publications from queue managers on which publications are
published to queue managers with matching subscriptions.
A topic host routed publish/subscribe cluster provides the following benefits:
• Improved scalability of larger clusters. Only the topic host queue managers need to be able to connect
to all other queue managers in the cluster. Therefore, there are fewer channels between queue
managers, and there is less inter-queue manager publish/subscribe administrative traffic than for direct
routing. When subscriptions change on a queue manager, only the topic host queue managers need to
be informed.
• More control over the physical configuration. With direct routing, all queue managers assume all roles,
and therefore all need to be equally capable. With topic host routing, you explicitly choose the topic
host queue managers. Therefore, you can ensure that those queue managers are running on adequate
equipment, and you can use less powerful systems for the other queue managers.

The effect of defining a local topic as well as a cluster topic

You define a local topic object if you want publisher applications connected to a queue manager to
publish only to locally connected subscribers. A local definition of a topic always overrides any clustered
topic definitions on remote queue managers.
Note: You also need to specify a Publication scope of Queue manager on the local topic object. If
Publication scope resolves to All, then remote subscribers are also sent publications published to the
topic defined on this queue manager.

Multiple cluster topic definitions in a direct routed cluster

In a direct routed cluster, you do not usually define a cluster topic on more than one cluster queue
manager. This is because direct routing makes the topic available at all queue managers in the cluster.
It is also not essential that the sole host queue manager is continually available, because the cluster topic
definition is cached by the full repository queue managers and by all other queue managers in their partial
cluster repositories. This caching allows for at least 60 days of availability while the host queue manager
is unavailable.
If you need to alter a cluster topic definition, take care to modify it at the same queue manager it was
defined on.

Multiple cluster topic definitions in a topic host routed cluster

In a topic host routed cluster, all publish/subscribe messaging is routed through the topic hosts.
Therefore, to ensure scalability and availability, it is usual to define a cluster topic on more than one
queue manager, and for the multiple cluster topic definitions to be identical.
Related concepts
“Publishers and subscribers” on page 98
Publishers and subscribers are applications that send and receive messages (publications) using the
publish/subscribe method of messaging. Publishers and subscribers are decoupled from one another so
that publishers do not know the destination of the information that they send, and subscribers do not
know the source of the information that they receive.
Related reference
“Topic properties” on page 391
An IBM MQ topic is an IBM MQ object that identifies what a publication is about. You can set properties
for topics. Some topic properties are specific to z/OS topics. Also, there are some properties that you can

18 IBM MQ Explorer
alter only while you are creating a topic. You cannot modify these properties after the IBM MQ topic has
been created.

Subscriptions
A subscription is a record that contains the information about the topic or topics that the subscriber
is interested in and wants to receive information about. Thus, the subscription information determines
which publications get forwarded to the subscriber. Subscribers can receive information from many
different publishers, and the information they receive can also be sent to other subscribers.
Published information is sent in an IBM MQ message, and the subject of the information is identified by
a topic. The publisher specifies the topic when it publishes the information, and the subscriber specifies
the topics on which it wants to receive publications. The subscriber is sent information about only those
topics to which it subscribes.
IBM WebSphere® MQ 7.0 or later queue managers use a Publish/Subscribe Engine to control the
interactions between publishers and subscribers. The Publish/Subscribe Engine receives messages from
publishers, and subscription requests from subscribers (to a range of topics). The Publish/Subscribe
Engine's job is to route the published data to the target subscribers.
Subscribers can specify that they do not want to receive retained publications, and existing subscribers
can ask for duplicate copies of retained publications to be sent to them. For more information on retained
publications, see “Publications” on page 19.
Related tasks
“Configuring publish/subscribe for IBM MQ queue managers” on page 99
In IBM MQ Explorer, you can configure IBM MQ queue managers as Publish/Subscribe Engines to route
messages between publishing applications and subscribing applications. To test your configurations, you
can register as a subscriber, and send and receive test publications if you are authorized to do so.
“Viewing a list of subscribers” on page 108
You can view a list of applications that are subscribed to topics on a Publish/Subscribe Engine, or a list of
applications that are subscribed to a specific topic.
Related reference
“IBM MQ subscription properties” on page 413
You can set properties for all types of subscriptions. Some of the properties do not apply to all types of
subscriptions, some properties are specific to z/OS subscriptions.
“Subscription status attributes” on page 534
The status attributes of subscriptions.

Publications
Publications are messages that are sent by an application to the Publish/Subscribe Engine. The Publish/
Subscribe Engine then sends the messages on to any applications that have subscribed to receive the
messages.
The Publish/Subscribe Engine can handle publications that it receives in different ways, depending on the
type of information contained in the publication.

State and event information

Publications can be categorized by the type of information that they contain:
State publications
State publications contain information about the current state of something, such as the price of
stock or the current score at a soccer match. When something happens (for example, the stock price
changes or the soccer score changes), the previous state information is no longer required because it
is superseded by the new information.
A subscriber application wants to receive the current version of the state information on startup, and
to be sent new information whenever the state changes.

Introduction to IBM MQ Explorer 19

 Event publications
Event publications contain information about individual events that occur, such as a trade in some
stock or the scoring of a particular goal. Each event is independent of other events.
A subscriber wants to receive information about events as they happen.

Retained publications
By default, when the Publish/Subscribe Engine has sent a publication to all interested subscribers, the
Publish/Subscribe Engine deletes the publication. This type of processing is suitable for event information
but is not always suitable for state information. A publisher can specify that the Publish/Subscribe Engine
must keep a copy of a publication, which is then called a retained publication. The copy can be sent
to subsequent subscribers who register an interest in the topic. This means that new subscribers do
not have to wait for information to be published again before they receive it. For example, a subscriber
who registers a subscription to a stock price would receive the current stock price straightaway, without
waiting for the stock price to change (and, therefore, be re-published).
The Publish/Subscribe Engine retains only one publication for each topic, so the old publication is deleted
when a new one arrives. So, ensure that only one publisher is sending retained publications on each topic.
Subscribers can specify that they do not want to receive retained publications, and existing subscribers
can ask for duplicate copies of retained publications to be sent to them.
For more information about how to decide whether to use retained publications, see Retained
publications.
Related concepts
“Publishers and subscribers” on page 98
Publishers and subscribers are applications that send and receive messages (publications) using the
publish/subscribe method of messaging. Publishers and subscribers are decoupled from one another so
that publishers do not know the destination of the information that they send, and subscribers do not
know the source of the information that they receive.
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.

Channels
IBM MQ can use three different types of channels: a message channel, an MQI channel, and an AMQP
channel.
Do not confuse these distinct types of channels:
Message channel
A message channel is a unidirectional communications link between two queue managers. IBM MQ
uses message channels to transfer messages between the queue managers. To send messages in
both directions, you must define a channel for each direction.
MQI channel
An MQI channel is bidirectional and connects an application (MQI client) to a queue manager on a
server machine. IBM MQ uses MQI channels to transfer MQI calls and responses between MQI clients
and queue managers.

AMQP channel
An AMQP channel, which is bidirectional and connects an AMQP client to a queue manager on a
server machine. IBM MQ uses AMQP channels to transfer AMQP calls and responses between AMQP
applications and queue managers.
When referring to message channels, the word channel is often used as a synonym for a channel
definition. It is usually clear from the context whether we are talking about a complete channel, which has
two ends, or a channel definition, which has only one end.

20 IBM MQ Explorer
 Message channels
Message channel definitions can be one of the following types:

Message channel definition type Description

Sender A sender channel is a message channel that the
queue manager uses to send messages to other
queue managers. To send messages using a sender
channel, you must also create, on the other queue
manager, a receiver channel with the same name as
the sender channel. You can also use sender channels
with requester channels if you are implementing a
"callback" mechanism.
Server A server channel is a message channel that the
queue manager uses to send messages to other
queue managers. To send messages using a server
channel, you must also create, on the other queue
manager, a receiver channel with the same name as
the server channel. You can also use server channels
with requester channels. In that case, the requester
channel definition at the other end of the channel
requests the server channel definition to start. The
server sends messages to the requester. The server
can also initiate the communication as long as the
server knows the connection name of the partner
channel.
Receiver A receiver channel is a message channel that the
queue manager uses to receive messages from other
queue managers. To receive messages using a receiver
channel, you must also create, on the other queue
manager, a sender or a server channel with the same
name as this receiver channel.
Requester A Requester channel is a message channel that the
queue manager uses to receive messages from other
queue managers. A Requester channel can request
the partner channel defined at the remote end to
start. If the partner channel is a Server channel,
the Server channel accepts the start request and
starts to send messages, from the transmission queue
identified in the Server channel definition, to the
Requester channel. If the partner channel is a Sender
channel, the Sender channel accepts the start request
but then closes the connection with the Requester.
The Sender channel then starts, negotiates a session
with the partner Requester channel and starts to
send messages from the transmission queue identified
in the Sender channel definition. This latter case
essentially provides for a call back mechanism in that
the Requester channel requests the Sender channel to
call back.

Introduction to IBM MQ Explorer 21

Message channel definition type Description
Cluster-sender A cluster-sender (CLUSSDR) channel definition defines
the sending end of a channel on which a cluster queue
manager can send cluster information to one of the
full repositories. The cluster-sender channel is used
to notify the repository of any changes to the queue
manager's status, for example the addition or removal
of a queue. It is also used to transmit messages.
The full repository queue managers themselves have
cluster-sender channels that point to each other. They
use them to communicate cluster status changes
to each other. It is of little importance which full
repository a queue manager's CLUSSDR channel
definition points to. After the initial contact has been
made, further cluster queue manager objects are
defined automatically as required so that the queue
manager can send cluster information to every full
repository, and messages to every queue manager. For
more information, see Queue manager clusters.
Cluster-receiver A cluster-receiver (CLUSRCVR) channel definition
defines the receiving end of a channel on which
a cluster queue manager can receive messages
from other queue managers in the cluster. A cluster-
receiver channel can also carry information about
the cluster-information destined for the repository.
By defining the cluster-receiver channel, the queue
manager indicates to the other cluster queue
managers that it is available to receive messages. You
need at least one cluster-receiver channel for each
cluster queue manager. For more information, see
Queue manager clusters.

For each channel you must define both ends so that you have a channel definition for each end of the
channel. The two ends of the channel must be compatible types.
You can have the following combinations of channel definitions:
• Sender-Receiver
• Server-Receiver
• Requester-Server
• Requester-Sender (callback)
• Cluster-sender-Cluster-receiver

Message channel agents

Each channel definition that you create belongs to a particular queue manager. A queue manager can
have several channels of the same or different types. At each end of the channel is a program, the
message channel agent (MCA). At one end of the channel, the caller MCA takes messages from the
transmission queue and sends them through the channel. At the other end of the channel, the responder
MCA receives the messages and delivers them to the remote queue manager.
A caller MCA can be associated with a sender, server, or requester channel. A responder MCA can be
associated with any type of message channel.
IBM MQ supports the following combinations of channel types at the two ends of a connection:

22 IBM MQ Explorer
Caller Direction of Responder
message flow
Channel type Listener required? Listener required? Channel type
Sender No Caller to Responder Yes Receiver
Server No Caller to Responder Yes Receiver
Server No Caller to Responder Yes Requester
Requester No Responder to Caller Yes Server
Requester Yes Responder to Caller Yes Sender

MQI channels
MQI channels can be one of the following types:

MQI channel type Description

Server connection A server connection channel is a bidirectional MQI
channel that is used to connect an IBM MQ client to
an IBM MQ server. The server connection channel is
the server end of the channel.
Client connection A client connection channel is a bidirectional MQI
channel that is used to connect an IBM MQ client to
an IBM MQ server. IBM MQ Explorer also uses client
connections to connect to remote queue managers.
The client connection channel is the client end of
the channel. When you create a client-connection
channel, a file is created on the computer that hosts
the queue manager. You must then copy the client-
connection file to the IBM MQ client computer.

AMQP channels

There is only one type of AMQP channel.

You use the channel to connect an AMQP messaging application with a queue manager, enabling the
application to exchange messages with IBM MQ applications. An AMQP channel allows you to develop
an application using MQ Light, and then deploy it as an enterprise application, taking advantage of the
enterprise-level facilities provided by IBM MQ.
For more information on channels, see Channels.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Starting and stopping a channel” on page 75
The way in which a channel is started depends on whether it is a caller channel or a responder channel.
When you stop a channel, you can choose whether to stop the channel after the current batch of

Introduction to IBM MQ Explorer 23

 messages has finished processing, or force the channel to shut down before the current message batch
has finished processing.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.

Listeners
A listener is an IBM MQ process that listens for connections to the queue manager.
Each listener object in IBM MQ Explorer represents a listener process; however, if you start a listener
process from the command line, the listener is not represented by a listener object in IBM MQ Explorer.
Therefore, to administer the listener process from IBM MQ Explorer, create the listener object in IBM MQ
Explorer. When you start the listener object in IBM MQ Explorer, the listener process starts.
There are different types of listener available in IBM MQ, depending on the transport protocol that the
Message Channel Agent (MCA) uses to send and receive messages through the message channels:
• LU6.2
• TCP/IP
• NetBIOS
• SPX

You can initiate new z/OS listeners in IBM MQ Explorer, which are displayed in the Content
view, where they can be started and stopped. Only TCP/IP and LU6.2 are supported for z/OS listeners in
IBM MQ Explorer.
For more information, see Listeners.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Listener properties” on page 389
You can set properties for all types of listeners. Some properties are specific to certain types of listener.

Process definitions
A process definition contains information about the application that starts in response to a trigger event
on a queue manager. When you enable triggering on a queue, you can create a process definition and
associate it with the queue.
Each queue can specify a different process definition, or several queues can share the same process
definition. If you create a process definition, the queue manager extracts the information from the
process definition and places it in the trigger message for the trigger monitor to use.
If you want to trigger the start of a channel, instead of an application, you do not need to create a process
definition because the transmission queue definition is used instead.

24 IBM MQ Explorer
For more information, see Process definitions.
Related concepts
“Trigger monitors” on page 30
A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Process definition properties” on page 418
You can set properties for process definitions. Some properties do not apply to all types of process
definitions. Some of the properties are specific to z/OS process definitions.

Namelists
A namelist is an IBM MQ object that contains a list of names of other objects.
Typically, namelists are used by applications such as trigger monitors, where they are used to identify a
group of queues, or with queue manager clusters to maintain a list of clusters referred to by more than
one IBM MQ object. Namelists are also used to maintain lists of authentication information objects, which
contain the authentication information about connections to LDAP servers.
For more information, see Namelists.
Related concepts
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.
“Trigger monitors” on page 30
A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.
“Authentication information” on page 26
Authentication information objects contain connection details of servers that can be used to determine
revocation status certificates.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Deleting queue managers and objects” on page 41

Introduction to IBM MQ Explorer 25

 When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Namelist properties” on page 419
You can set properties for namelists. Some of the properties are specific to z/OS namelists.

Authentication information
Authentication information objects contain connection details of servers that can be used to determine
revocation status certificates.
An authentication information object contains authentication information that is used when checking
whether a TLS certificate is revoked or not. The following table shows the IBM MQ TLS authentication
information support for different platforms:

Table 1. How IBM MQ TLS supports authentication information on different platforms

Platform Support
IBM MQ TLS supports checks for revoked certificates using OCSP, or using CRLs and
IBM
ARLs on LDAP servers, with OCSP as the preferred method. IBM MQ classes for Java
MQ for AIX®, Linux,
cannot use the OCSP information in a client channel definition table file. However, you
and Windows
can configure OCSP as described in Revoked certificates and OCSP.
IBM MQ TLS supports checks for revoked certificates using CRLs and ARLs on LDAP
IBM
servers only. IBM MQ for z/OS systems cannot use OCSP.
MQ for z/OS
IBM MQ TLS supports checks for revoked certificates using CRLs and ARLs on LDAP
IBM
servers only. IBM MQ for IBM i systems cannot use OCSP.
MQ for IBM i

For information about working with CRL & LDAP, see: “Working with revoked certificates” on page 27.
For information about working with OCSP, see: “Working with Online Certificate Status Protocol (OCSP)”
on page 27.
For information about controlling access at a channel level, see Channel authentication records.
Related concepts
“Namelists” on page 25
A namelist is an IBM MQ object that contains a list of names of other objects.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
“Configuring TLS on queue managers” on page 129
After starting the IBM strmqikm (iKeyman) GUI, you can use it to manage TLS certificates. You can also
authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.
Related reference
“Authentication information properties” on page 420

26 IBM MQ Explorer
 You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.

Working with revoked certificates

Authentication information objects contain connection details of responders or servers that can be used
to determine the revocation status of certificates.
An authentication information object contains authentication information that is used when checking
whether a TLS certificate is revoked or not. The following table shows the IBM MQ TLS authentication
information support for different platforms:

Table 2. How IBM MQ TLS supports authentication information on different platforms

Platform Support
IBM MQ TLS supports checks for revoked certificates using OCSP, or using CRLs and
IBM
ARLs on LDAP servers, with OCSP as the preferred method. IBM MQ classes for Java
MQ for AIX, Linux,
cannot use the OCSP information in a client channel definition table file. However, you
and Windows
can configure OCSP as described in Revoked certificates and OCSP.
IBM MQ TLS supports checks for revoked certificates using CRLs and ARLs on LDAP
IBM
servers only. IBM MQ for z/OS systems cannot use OCSP.
MQ for z/OS
IBM MQ TLS supports checks for revoked certificates using CRLs and ARLs on LDAP
IBM
servers only. IBM MQ for IBM i systems cannot use OCSP.
MQ for IBM i

For more information, see Securing.

Related concepts
“Namelists” on page 25
A namelist is an IBM MQ object that contains a list of names of other objects.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
“Configuring TLS on queue managers” on page 129
After starting the IBM strmqikm (iKeyman) GUI, you can use it to manage TLS certificates. You can also
authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.
Related reference
“Authentication information properties” on page 420
You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.

Working with Online Certificate Status Protocol (OCSP)

IBM MQ determines which Online Certificate Status Protocol (OCSP) responder to use, and handles the
response received. You might have to take steps to make the OCSP responder accessible.
An authentication information object contains authentication information that is used when checking
whether a TLS certificate is revoked or not.
Note: This information applies only to IBM MQ for AIX, Linux, and Windows systems. The following table
shows the IBM MQ TLS authentication information support for different platforms:

Introduction to IBM MQ Explorer 27

Table 3. How IBM MQ TLS supports authentication information on different platforms
Platform Support
IBM MQ TLS supports checks for revoked certificates using OCSP, or using CRLs and
IBM
ARLs on LDAP servers, with OCSP as the preferred method. IBM MQ classes for Java
MQ for AIX, Linux,
cannot use the OCSP information in a client channel definition table file. However, you
and Windows
can configure OCSP as described in Revoked certificates and OCSP.
IBM MQ TLS supports checks for revoked certificates using CRLs and ARLs on LDAP
IBM
servers only. IBM MQ for z/OS systems cannot use OCSP.
MQ for z/OS
IBM MQ TLS supports checks for revoked certificates using CRLs and ARLs on LDAP
IBM
servers only. IBM MQ for IBM i systems cannot use OCSP.
MQ for IBM i

To check the revocation status of a digital certificate using OCSP, IBM MQ determines which OCSP
responder to contact in one of two ways:
• Using the AuthorityInfoAccess (AIA) certificate extension in the certificate to be checked.
• Using a URL specified in an authentication information object or specified by a client application.
A URL specified in an authentication information object or by a client application takes priority over a URL
in an AIA certificate extension.
The URL of the OCSP responder might lie behind a firewall; if so, reconfigure the firewall so the OCSP
responder can be accessed or set up an OCSP proxy server. Specify the name of the proxy server by using
the SSLHTTPProxyName variable in the SSL stanza. On client systems, you can also specify the name of
the proxy server by using the environment variable MQSSLPROXY.
If you are not concerned whether TLS certificates are revoked, perhaps because you are running in a test
environment, you can set OCSPCheckExtensions to NO in the SSL stanza. If you set this variable, any AIA
certificate extension is ignored. This solution is unlikely to be acceptable in a production environment,
where you probably do not want to allow access from users presenting revoked certificates.
The call to access the OCSP responder can return one of the following three outcomes:
Good
The certificate is valid.
Revoked
The certificate is revoked.
Unknown
This outcome can arise for one of three reasons:
• IBM MQ cannot access the OCSP responder.
• The OCSP responder has sent a response, but IBM MQ cannot verify the digital signature of the
response.
• The OCSP responder has sent a response that indicates that it has no revocation data for the
certificate.
By default, IBM MQ rejects a connection if it receives an OCSP response of Unknown, and issues an error
message. You can change this behavior by setting the OCSPAuthentication attribute. This is held in the
SSL stanza of the qm.ini file for AIX and Linux systems, the WebSphere registry, or the SSL stanza of the
client configuration file. It can be set using the IBM MQ Explorer on applicable platforms.

OCSP outcome Unknown

If IBM MQ receives an OCSP outcome of Unknown, its behavior depends on the setting of the
OCSPAuthentication attribute. For queue managers, this attribute is held in the SSL stanza of the qm.ini
file for AIX and Linux systems, or the Windows registry, and it can be set using the IBM MQ Explorer. For
clients, it is held in the SSL stanza of the client configuration file.

28 IBM MQ Explorer
If an outcome of Unknown is received and OCSPAuthentication is set to REQUIRED (the default value),
IBM MQ rejects the connection and issues an error message of type AMQ9716. If queue manager
SSL event messages are enabled, an SSL event message of type MQRC_CHANNEL_SSL_ERROR with
ReasonQualifier set to MQRQ_SSL_HANDSHAKE_ERROR is generated.
If an outcome of Unknown is received and OCSPAuthentication is set to OPTIONAL, IBM MQ allows the
SSL channel to start and no warnings or SSL event messages are generated.
If an outcome of Unknown is received and OCSPAuthentication is set to WARN, the SSL channel
starts but IBM MQ issues a warning message of type AMQ9717 in the error log. If queue manager
SSL event messages are enabled, an SSL event message of type MQRC_CHANNEL_SSL_WARNING with
ReasonQualifier set to MQRQ_SSL_UNKNOWN_REVOCATION is generated.

Digital signing of OCSP responses

An OCSP responder can sign its responses in any of three ways. Your responder will inform you which
method is used.
• The OCSP response can be digitally signed using the same CA certificate that issued the certificate that
you are checking. In this case, you do not need to set up any additional certificate; the steps you have
already taken to establish SSL connectivity are sufficient to verify the OCSP response.
• The OCSP response can be digitally signed using another certificate signed by the same (CA) that issued
the certificate you are checking. The signing certificate is flowed together with the OCSP response in
this case. The certificate flowed from the OCSP responder must have an Extended Key Usage Extension
set to id-kp-OCSPSigning so that it can be trusted for this purpose. Because the OCSP response is
flowed with the certificate which signed it (and that certificate is signed by a CA which is already trusted
for SSL connectivity) then no additional certificate setup is required.
• The OCSP response can be digitally signed using another certificate which is not directly related to the
certificate you are checking. In this case, the OCSP Response is signed by a certificate issued by the
OCSP responder itself. You must add a copy of the OCSP responder certificate to the key database of
the client or queue manager which performs the OCSP checking. See Adding a CA certificate (or the
CA part of a self-signed certificate) into a key repository. When a CA certificate is added, by default
it is added as a trusted root, which is the required setting in this context. If this certificate is not
added, IBM MQ cannot verify the digital signature on the OCSP response and the OCSP check results
in an Unknown outcome, which might cause IBM MQ to close the channel, depending on the value of
OCSPAuthentication.
Related concepts
“Namelists” on page 25
A namelist is an IBM MQ object that contains a list of names of other objects.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
“Configuring TLS on queue managers” on page 129
After starting the IBM strmqikm (iKeyman) GUI, you can use it to manage TLS certificates. You can also
authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.
Related reference
“Working with revoked certificates” on page 27
Authentication information objects contain connection details of responders or servers that can be used
to determine the revocation status of certificates.
“Authentication information properties” on page 420

Introduction to IBM MQ Explorer 29

 You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.

Communication information object

IBM MQ Multicast offers low latency, high fanout, reliable multicast messaging. A communication
information (COMMINFO) object is needed to use Multicast transmission.
Multicast is more efficient that traditional unicast publish/subscribe messaging as it can be scaled to
a high number of subscribers without a detrimental effect in performance. IBM MQ enables reliable
Multicast messaging by using acknowledgments, negative acknowledgments, and sequence numbers to
achieve low latency messaging with high fanout.
IBM MQ Multicast fair delivery enables near simultaneous delivery, ensuring that no recipient gains an
advantage. As IBM MQ Multicast uses the network to deliver messages, a publish/subscribe engine is not
needed to fanout data. After a topic is mapped to a group address, there is no need for a queue manager,
because publishers and subscribers can operate in a peer-to-peer mode. This process allows the load to
be reduced on queue manager servers, and the queue manager server is no longer a potential point of
failure.
The COMMINFO object contains the attributes associated with multicast transmission. To create
COMMINFO object in the Navigator view:
1. In the Navigator view, expand the Queue Managers node.
2. Expand the node of the queue manager that you want to create a COMMINFO object on.
3. Right-click Communication Information to open the menu, then click New > Multicast
Communication Information to open the COMMINFO wizard.
4. Work through the COMMINFO wizard to create COMMINFO object.

Trigger monitors
A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.
If triggering is enabled for a queue and a trigger event occurs, the queue manager sends a trigger
message to the initiation queue. The trigger monitor reads the trigger message and takes appropriate
action, based on the data in the trigger message. Normally, this action would be to start some other
application to process the queue that caused the trigger message to be generated. From the point of view
of the queue manager, there is nothing special about a trigger monitor; it is just another application that
reads messages from a queue (the initiation queue).
When you have started a trigger monitor, it just continues monitoring the specified initiation queue. You
cannot stop a trigger monitor directly. When you stop the trigger monitor's queue manager, the trigger
monitor stops too.
For more information, see Trigger monitors.
Related concepts
“Channel initiators” on page 31
A channel initiator is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs. A channel initiator is a special type of trigger monitor that starts channels
rather than applications.
Related tasks
“Starting a trigger monitor” on page 78

30 IBM MQ Explorer
To start a trigger monitor, you must first create a service that will start the trigger monitor.

Channel initiators
A channel initiator is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs. A channel initiator is a special type of trigger monitor that starts channels
rather than applications.
If triggering is enabled for a queue and a trigger event occurs, the queue manager sends a trigger
message to the initiation queue. The channel initiator processes the trigger message and starts the
channel. From the point of view of the queue manager, there is nothing special about a channel initiator; it
is just another application that reads messages from a queue (the initiation queue).
Because a channel initiator is just a special type of trigger monitor, when you have started a channel
initiator, it just continues monitoring the specified initiation queue. You cannot stop a channel initiator
directly. When you stop the channel initiator's queue manager, the channel initiator stops too.
You also cannot create or delete a channel initiator. A channel initiator is created or deleted when its
queue manager is created or deleted.
Related concepts
“Trigger monitors” on page 30
A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.
Related tasks
“Starting a channel initiator” on page 80
To start a channel initiator, you must first create a service that will start the channel initiator.

Custom services
Custom services are services that you create to run commands automatically.
Custom services are stored in the Services folder on the queue manager to which the services belong.
You can specify the command and other options that are run when the service starts and stops. You can
automate a service to start and to run the command when the queue manager starts.
An example of when you might want to create a service is for starting a trigger monitor when the queue
manager starts.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Service properties” on page 399
You can configure properties for custom service objects in the Service properties dialog.

Storage classes
Storage classes can exist only on z/OS queue managers. A storage class maps one or more queues to a
page set. This means that the messages on the queues are stored on the page set.
You can use storage classes to control where non-shared message data is stored for administrative, data
set space and load management, or application isolation purposes. Only queues that are not shared store
their messages on page sets. Therefore, shared queues do not use storage classes. The messages on
shared queues are stored in coupling facility structures instead.

Introduction to IBM MQ Explorer 31

 You can create storage classes in IBM MQ Explorer but the only storage class property that you can
configure is the Description field.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

Queue sharing groups

Queue sharing groups exist only on z/OS queue managers. A queue sharing group is a group of queue
managers that can access the same shared queues. Each member of the queue sharing group has access
to the same set of shared queues.
All the queue sharing groups to which the queue managers in IBM MQ Explorer belong are shown in the
Queue Sharing Group folder. All the resources that members of a queue sharing group can access are
shown in folders in the queue sharing group.
Queue sharing groups have a name of up to four characters. The name must be unique in your network,
and must be different from any queue manager names.
You cannot create or configure queue sharing groups in IBM MQ Explorer.
For more information, see Queue sharing groups and clusters.

Shared queues
A shared queue is a queue that has been defined on a queue manager in a queue sharing group and
has the queue sharing group disposition of Shared. A shared queue's object definition is stored in the
queue sharing group's shared repository on Db2®, and the messages on the shared queue are stored in a
coupling facility structure on a physical coupling facility.
All of the queue managers in the queue sharing group can access the shared queue, which means that
they can put and get messages on the shared queue without needing active channels. Because any queue
manager can access the shared queue, an application is not dependent on the availability of any one
queue manager.
All of the shared queues that belong to a queue manager are shown in the queue manager's folder. All of
the shared queues in a queue sharing group are also shown in the queue sharing group's Shared Queues
folder.

Group definitions
Group definitions is the collective term for IBM MQ objects that are defined on queue managers in a
queue sharing group and have the queue sharing group disposition of Group. Any IBM MQ object that can
be defined on a z/OS queue manager can have the queue sharing group disposition of Group. When you
create a group definition object, the definition of the object is stored in the shared repository on Db2.
IBM MQ automatically creates a copy of the object (with queue sharing group disposition Copy) for
each queue manager and stores it on the queue manager's page set zero with the queue manager's
private objects, which have disposition Private. A page set is a data set that is specially formatted for
use by IBM MQ. The messages on queues that have disposition Copy are also stored on page sets but
they should not be stored on page set zero because if page set zero gets full, IBM MQ cannot function
correctly. You can specify which page set the messages are stored on by creating one or more storage
class objects which map the queues to page sets.

32 IBM MQ Explorer
All of the group definitions that belong to a queue manager are shown in the queue manager's folder.
All of the group definitions in a queue sharing group are also shown in the queue sharing group's Group
Definitions folder.
Related concepts
“Coupling facility structures” on page 33
The coupling facility objects in IBM MQ Explorer represent coupling facility structures on a physical
coupling facility. Coupling facility structures store the messages that are on shared queues. Each coupling
facility structure used by IBM MQ is dedicated to a specific queue sharing group, but a coupling facility
can hold structures for more than one queue sharing group.
“IBM MQ queues” on page 15
A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.
“Storage classes” on page 31
Storage classes can exist only on z/OS queue managers. A storage class maps one or more queues to a
page set. This means that the messages on the queues are stored on the page set.

Coupling facility structures

The coupling facility objects in IBM MQ Explorer represent coupling facility structures on a physical
coupling facility. Coupling facility structures store the messages that are on shared queues. Each coupling
facility structure used by IBM MQ is dedicated to a specific queue sharing group, but a coupling facility
can hold structures for more than one queue sharing group.
The physical coupling facility exists independently of the queue sharing group network, and typically runs
on a different power supply. This means that the coupling facility is resilient to software failures and
can be configured to be resilient to hardware failures and power-outages. The messages on the coupling
facility structures are, therefore, highly available.
For more information, see Managing the coupling facility.
Related concepts
“Queue sharing groups” on page 32
Queue sharing groups exist only on z/OS queue managers. A queue sharing group is a group of queue
managers that can access the same shared queues. Each member of the queue sharing group has access
to the same set of shared queues.
“IBM MQ queues” on page 15
A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Coupling facility structure properties” on page 434
You can set properties for coupling facility structures. Coupling facility structures are available only on
z/OS.

Queue manager clusters

A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.

Introduction to IBM MQ Explorer 33

 For example, you can create a cluster, and then set a queue on one of its queue managers to be shared
in the cluster. Now, on any other queue manager in the cluster, that queue is visible as if it were a local
queue, and you can just open it and put a message directly on it.

Note that sharing a queue in a cluster (a cluster queue) is different from sharing a queue
in a queue sharing group (a shared queue) on z/OS queue managers. However, on z/OS, a cluster queue
manager can also belong to a queue sharing group and can share its queue definitions with other queue
managers in the queue sharing group.
Also, a queue manager on any platform can be a member of more than one cluster at the same time.
Cluster support also allows more than one queue manager to host an instance of the same queue
(that is, a queue with the same name). This means that you can run more than one instance of an
application, each receiving messages and running independently, thus spreading the workload between
queue managers.
For more information, see Distributed queuing and clusters.
Related concepts
“Cluster repositories” on page 121
A cluster repository contains information about the cluster; for example, information about the queue
managers that are members of the cluster, and the cluster channels. Repositories are hosted by the
queue managers in the cluster.
“IBM MQ queues” on page 15
A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.

Queue sharing groups

Queue sharing groups exist only on z/OS queue managers. A queue sharing group is a group of queue
managers that can access the same shared queues. Each member of the queue sharing group has access
to the same set of shared queues.

Creating an IBM MQ object from a JMS object

You can create new IBM MQ queues and topics based on your existing JMS queues and topics. The values
of relevant properties of the JMS object are copied to the new IBM MQ object. In future, however, if you
make a change to one of the objects, the changes are not reflected in the other object.

Before you begin

• Add the initial context that contains the JMS queue or topic.
• Connect to the initial context.

About this task

If the JMS object that you use to create an IBM MQ object specifies a queue manager name in its
properties, you can only create the IBM MQ object on a queue manager with the same name. This means
you might have to add a new queue manager with the name specified in the JMS object.
To create an IBM MQ object from an existing JMS object, complete the following steps.

Procedure
1. In the Navigator view, expand the initial context that contains the JMS object (either a JMS queue or a
JMS topic), then click the Destinations folder to list the objects in the Content view.
2. In the Content view, right-click the object, then click Create MQ Queue or Create MQ Topic as
appropriate.
The New Queue or New Topic wizard opens as appropriate.

34 IBM MQ Explorer
3. In the wizard, click Select, then select the queue manager on which you want to create the new IBM
MQ object.
The queue manager's name is displayed in the Queue Manager field of the wizard.
4. Work through the wizard to define the new IBM MQ object, then click Finish.

Results
The new IBM MQ object is created and displayed under the appropriate queue manager in IBM MQ
Explorer.

What to do next
To view the new MQ object, in the Navigator view, expand the name of the queue manager on which you
created the MQ object. You can now continue to configure the IBM MQ object as necessary.
To create an MQ object and a JMS object simultaneously, follow the instructions in: “Creating an IBM MQ
object and a JMS object simultaneously” on page 35 or “Creating a JMS object and an IBM MQ object
simultaneously” on page 184.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Adding a queue manager from a JMS connection factory” on page 42
You can add an existing queue manager to IBM MQ Explorer from a JMS connection factory that uses MQ
MQI client transport (not bindings transport) and that specifies the host name and port that corresponds
with the queue manager.
“Creating a JMS object and an IBM MQ object simultaneously” on page 184
When you create a new JMS object, you can optionally create a corresponding IBM MQ object of the same
type.
“Creating an IBM MQ object and a JMS object simultaneously” on page 35
When you create a new IBM MQ object, you can optionally create a corresponding JMS object of the same
type.

Creating an IBM MQ object and a JMS object simultaneously

When you create a new IBM MQ object, you can optionally create a corresponding JMS object of the same
type.

Before you begin

• You must have an IBM MQ queue manager. If one does not exist, you can create one as described in:
“Creating and configuring queue managers and objects” on page 13
• You must have a JMS initial context. If one does not exist, you can create one as described in: Add the
initial context that will contain the JMS topic
• You must be connected to the JMS initial context as described in: Connect to the initial context

About this task

With the object creation wizards in IBM MQ Explorer, you can create an IBM MQ object and a JMS object
simultaneously. You begin by launching your required object wizard, for example; an IBM MQ queue. Then
you select the option to launch another wizard, for example; a JMS queue, after the object has been
created. The second object wizard must be of the same object type, and the properties of one are mapped
to the other.
You can perform this task for queues or topics:
1. Create an IBM MQ queue and a JMS queue simultaneously.

Introduction to IBM MQ Explorer 35

 2. Create an IBM MQ topic and a JMS topic simultaneously.

Procedure
• [OPTION 1] Create an IBM MQ queue and a JMS queue simultaneously.
When you create a new IBM MQ queue in IBM MQ Explorer, you can choose to launch the New JMS
Queue wizard to create a JMS queue immediately after the IBM MQ New Local Queue wizard has
finished. The New JMS Queue wizard now contains the details you entered when creating the IBM MQ
queue.
a) Select the queue manager you want to add a new IBM MQ queue to in the Navigator view, and
right-click on its Queues queue manager object folder.
b) Click New > Local Queue to open the New Local Queue wizard.
c) Type a name for your queue, then select Start wizard to create a matching JMS Queue. Work
through the wizard to create your queue.
After you have completed the New Local Queue wizard, the New Destination New JMS Queue wizard
opens, with many of the IBM MQ queue details mapped to the JMS queue.
• [OPTION 2] Create an IBM MQ topic and a JMS topic simultaneously.
When you create a new IBM MQ topic in IBM MQ Explorer, you can choose to launch the New JMS
Topic wizard to create a JMS topic immediately after the IBM MQ New Topic wizard has finished. The
New JMS Topic wizard now contains the details you entered when creating the IBM MQ topic.
a) Select the queue manager you want to add a new IBM MQ topic to in the Navigator view, and
right-click on its Topics queue manager object folder.
b) Click New > Topic to open the New Topic wizard.
c) Type a name for your topic, then select Start wizard to create a matching JMS topic. Work
through the wizard to create your topic.
Once you have completed the New Topic wizard, the New Destination New JMS Topic wizard opens,
with many of the IBM MQ topic details mapped to the JMS topic.
Related tasks
“Creating a destination” on page 183
A JMS client uses a destination object to specify the target of messages that the JMS client produces
and the source of messages that the JMS client receives. Destination objects can represent queues (for
point-to-point messaging) or topics (for publish/subscribe messaging).
“Creating an IBM MQ object from a JMS object” on page 34
You can create new IBM MQ queues and topics based on your existing JMS queues and topics. The values
of relevant properties of the JMS object are copied to the new IBM MQ object. In future, however, if you
make a change to one of the objects, the changes are not reflected in the other object.
“Creating a JMS object from an IBM MQ object” on page 186
You can create new JMS administered objects based on your existing IBM MQ objects.
Related reference
“Destination properties” on page 500
You can view and set destination properties in the Destination properties dialog. The properties that are
available in the dialog depend on the type of destination.
“Connection factory properties” on page 469

36 IBM MQ Explorer
You can view and set connection factory properties in the Connection Factory properties dialog. The
properties that are available in the dialog depend on which messaging provider the connection factory
uses.

Configuring queue managers and objects

You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

About this task

Attention: Security policies for AMS are not manageable by IBM MQ Explorer for IBM MQ for
z/OS.
On the z/OS platform you must use CSQ0UTIL.
To configure a queue manager or object using the properties dialog, complete the following steps.

Procedure
1. In the Navigator view, click the relevant folder to list its contents in the Content view.
For example, if you want to configure a queue, click the Queues folder to list the queue manager's
queues in the Content view.
2. In the Content view, right-click the queue manager or object, then click Properties.
The properties dialog for the queue manager or object opens.
3. Edit the properties as required.
4. To apply the changes without closing the dialog, click Apply, or to close the dialog and save your
changes, click OK.

Results
You can see many of your changes immediately but some changes, for example, changing the default
location of the queue manager's TLS key repository, do not take effect until you have stopped and
restarted the queue manager.

Example
For more information about the properties of each type of object, see the following topics:
• Queue manager properties
• Queue properties
• Channel properties
• Listener properties
• Queue manager manual set properties
• Queue manager automatic set properties
• Topic properties
• Service properties
• Subscription properties
• Process definition properties
• Namelist properties
• Authentication information properties

• Storage class properties

Introduction to IBM MQ Explorer 37

 • Queue sharing group properties

• Coupling facility structure properties

• Cluster queue manager properties
• Cluster queue properties
• Application Connection properties
• Message properties
• Connection factory properties
• Destination properties
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Deleting queue managers and objects” on page 41
When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Forcing changes to queue properties

If the changes that you are making to the properties of a queue affect the operation of a queue manager
or another program, you might be asked to confirm whether you want to force the changes to the queue
properties.

About this task

In certain circumstances, when you change queue properties and then click OK, a confirmation dialog is
displayed that informs you that the changes you are making affect the operation of the queue manager
or another program that is using the object. You are then asked if you want to force the change to the
object's properties. For the confirmation dialog to appear, you must have the object open in a separate
application.
You must force changes to local queues in the following circumstances:
• The Shareability property on the Extended property page is specified as Not shareable.
• One or more applications have the queue open for input.
• Both of the following statements are true:
– The Usage property is changed.
– Either one or more messages are on the queue, or one or more applications have the queue open.
You must force changes to alias queues in the following circumstances:
• The Base object property is specified.
• An application has the queue open.
You must force changes to remote queues in the following circumstances:
• The Transmission queue property is changed.
• One or more applications have this queue open as a remote queue.
• Both of the following statements are true:
– Any of Remote queue, Remote queue manager, or Transmission queue are changed.

38 IBM MQ Explorer
 – One or more applications have the queue open which resolved through this definition as a queue
manager alias.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“IBM MQ queue properties” on page 358
The properties that you can set for a queue depend on the type of queue. Different types of IBM MQ
queues have different properties. Some of the properties do not apply to all types of queue, some
properties are specific to cluster queues, and some properties are specific to z/OS queues.

Comparing the properties of two objects

You can compare the properties of an object with another object of the same type; for example, compare
a queue with another queue, a topic with another topic, or a channel with another channel.

About this task

You can compare two objects that are on the same queue manager, or on different queue managers.
To compare the properties of two objects:, complete the following steps.

Procedure
1. In the Content view, right-click the object that you want to compare, then click Compare with...
The Compare With dialog opens.
2. In the Compare With dialog, select the object to compare with:
• To compare with an object on the same queue manager, select the name of the object that you
want to compare with from the With container, and then browse for the queue manager or queue
with which to compare it.
• To compare with a queue on a different queue manager:
a. Select a queue manager from the On Queue Manager list.
b. Select the name of the object that you want to compare with from the With container.
• If you are comparing queue managers instead of queues, the option to browse for a queue is not
available.

Results
By default, the show differences only check box is selected so that only the properties that are different
are listed. To show all of the properties of each queue, clear the show differences only check box.
Related reference
“Properties” on page 308
Use this information to find out about the properties that you can view and edit, including properties
that apply to the whole IBM MQ installation and the properties of an individual IBM MQ object such as a
queue, a queue manager, or a channel.

Pinging a channel to verify a connection

When you define a channel, you must define both ends of the channel correctly otherwise the channel
does not work. You can test that you correctly defined a channel by sending data as a special message

Introduction to IBM MQ Explorer 39

 to the remote queue manager, and checking that the data is returned. The data is generated by the local
queue manager.

About this task

You must ping from the sender or server end of the channel. You cannot ping a channel that is running;
before you ping a channel, make sure that the channel is stopped or is not trying again.
To ping a channel, complete the following steps.

Procedure
In the Content view, right-click the sender or server channel definition, then click Ping.

Results
If the channel is correctly defined, a message is displayed saying: IBM MQ successfully sent data
to the remote queue manager and received the data returned. (AMQ4006)
If the channel is not correctly defined, an error message is displayed describing why you could not ping
the channel.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.

Purging an AMQP channel

You can purge an AMQP channel to remove messages on queues on that channel.

About this task

To purge a channel, complete the following steps.

Procedure
1. In the Navigator view, click the Channels folder to display the channels in the Content view.
2. In the Content view, right-click the channel, then click Purge.

Starting a channel manually

About this task

You can start caller channels in IBM MQ Explorer. When you start responder channels in IBM MQ Explorer,
you are actually changing the responder channel's state from Stopped to Inactive; the listener then
changes the state from Inactive to Started. You must, therefore, start a listener on your computer if you
are using responder channels.
To start a channel:

Procedure
1. In the Navigator view, click the Channels folder to display the channels in the Content view.
2. In the Content view, right-click the channel, then click Start.

40 IBM MQ Explorer
3. In the Purge Channel window, optionally specify that channels associated with a particular client ID
are purged.
4. Click OK to purge the channel.

Results
The channel is purged.

Deleting queue managers and objects

When you delete a queue manager or an object in IBM MQ Explorer, the queue manager or object no
longer exists on the system.

About this task

Important: Before you delete a queue manager or an object, make sure that none of your applications
need it. If you delete a queue manager, all the objects for the selected queue manager, such as queues or
channels, are deleted as well.
If you want to keep the queue manager or object on the system but you do not want it to be displayed in
IBM MQ Explorer, you can hide it. For more information, see Hiding queue managers in IBM MQ Explorer,
and Filtering the objects displayed in IBM MQ Explorer.
To delete a queue manager or an object, complete the following steps.

Procedure
1. In the Navigator view, click the relevant folder to list its contents in the Content view. For example, if
you want to delete a queue, click the Queues folder to list the queues for the selected queue manager
in the Content view.
2. In the Content view, right-click the queue manager or object, then click Delete.
To delete multiple objects, hold down the Shift or Ctrl key, select the objects you want to delete,
right-click the selected objects, then click Delete.
If you are deleting a queue and the queue contains messages, a dialog asks if you want to clear the
messages first. You cannot delete a queue without clearing its messages first.
3. When you are prompted, click Delete to confirm that you want to delete the queue manager or object.

Results
The queue manager or object is deleted from the system and any applications that need the queue
manager or object no longer work properly.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Sending test messages” on page 71

Introduction to IBM MQ Explorer 41

 You can use a test message to check whether an application or a queue manager can put a message on a
queue. You can also browse messages that are already on a queue or clear messages from a queue.

Adding a queue manager from a JMS connection factory

You can add an existing queue manager to IBM MQ Explorer from a JMS connection factory that uses MQ
MQI client transport (not bindings transport) and that specifies the host name and port that corresponds
with the queue manager.

Before you begin

• Add the initial context that contains the JMS connection factory.
• Connect to the initial context.

About this task

To add a queue manager from a JMS connection factory, complete the following steps.

Procedure
1. In the Navigator view, click the Connection Factories folder that contains the connection factory to
display the connection factory in the Content view.
2. In the Content view, right-click the connection factory, then click Add Queue Manager.
IBM MQ Explorer tries to add the queue manager to the Queue Managers folder using the connection
details in the connection factory.
3. When prompted, click Yes.

Results
The queue manager is added to the Queue Managers folder using the connection details that are specified
in the connection factory. It is possible for the same queue manager to be shown more than once in the
Queue Managers folder if each connection uses different connection details; for example, a local queue
manager could be connected using 'localhost' as the host name, and it could also be connected using the
IP address of the host as the host name.

What to do next
If you specify the queue manager's name with a * wildcard, you will be prompted that the determined
queue manager could change each time the same connection factory is used.
If you specify the queue manager's name with a * wildcard and the connection fails, you will not be able
to add the disconnected queue manager to the explorer, as the name will be undetermined.
It is not necessary for the JMS connection factory to specify the host name and port that corresponds
with the queue manager, a client channel definition table (CCDT) can be used instead. For more
information, see Client channel definition table.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Creating an IBM MQ object from a JMS object” on page 34

42 IBM MQ Explorer
You can create new IBM MQ queues and topics based on your existing JMS queues and topics. The values
of relevant properties of the JMS object are copied to the new IBM MQ object. In future, however, if you
make a change to one of the objects, the changes are not reflected in the other object.

Configuring system parameters on z/OS queue managers

If the default system parameter module that is supplied with IBM MQ does not contain the system
parameters that you want, you can create your own system parameter module and customized macros.

Before you begin

Before you can perform this task, you must have already added the z/OS queue manager to IBM MQ
Explorer and IBM MQ Explorer must be connected to the queue manager. For more information, see
Showing a remote queue manager and Connecting or disconnecting a queue manager.

About this task

A subset of a z/OS queue manager's properties are loaded from the queue manager system parameter
module when the queue manager starts. The default system parameter module that is supplied with IBM
MQ is called CSQZPARM. In the system parameter module are three macros:
• CSQ6SYSP, which controls the connection and tracing parameters
• CSQ6LOGP, which controls log initialization
• CSQ6ARVP, which controls archive initialization
If the default system parameter module does not contain the system parameters that you want, you can
create your own system parameter module and customized macros using the supplied JCL sample. You
cannot perform these customizations from IBM MQ Explorer because IBM MQ Explorer cannot connect to
a queue manager that is not running. For more information, see Customizing your queue managers.
You can, however, perform the following tasks in IBM MQ Explorer:
1. View the system parameters.
2. Override system parameters while the queue manager is running.

Procedure
• [OPTION 1] View the system parameters.
When the z/OS queue manager starts, it loads its system parameter module which sets the queue
manager's initial system parameter values. When the queue manager is running, you can monitor and
administer it from IBM MQ Explorer and, therefore, view the queue manager's initial system parameter
values.
a) In the Navigator view, right-click the queue manager, then click the relevant menu item to view the
initial parameter values that you are interested in:
– To view the log archive settings, click Configuration > Archive
– To view the log settings, click Configuration > Log
– To view the connection and tracing settings, click Configuration > System
A dialog opens. In the dialog, the Initial table contains the values of the system parameters that were
loaded from the system parameter module when the queue manager started.
• [OPTION 2] Override system parameters while the queue manager is running.
While the queue manager is running, you can change and temporarily override certain system
parameter values. You can make these changes from IBM MQ Explorer.
a) In the Navigator view, right-click the queue manager, then click the relevant menu item to view the
initial parameter values that you are interested in:
– To view the log archive settings, click Configuration > Archive

Introduction to IBM MQ Explorer 43

 – To view the log settings, click Configuration > Log
– To view the connection and tracing settings, click Configuration > System
A dialog opens. In the dialog, there is a table called Set. If you have already edited the system
parameters since the queue manager started, the Set table contains the new parameter values.
b) In the dialog, click Properties....
A Properties dialog opens.
c) In the Properties dialog, edit the parameters that you want to override, then click OK to close the
Properties dialog.
For more information about the individual parameters, see Queue manager properties.
The changes that you have made are shown in the Set table. The changes are temporary; the next time
that the queue manager is restarted, the changes are lost because the values in the system parameter
module are applied again.
Related tasks
“Showing a remote queue manager” on page 82
If you want to administer a remote queue manager, you must connect IBM MQ Explorer to the remote
queue manager so that the queue manager is displayed in the Navigator view. You can create a
connection manually, or using a client channel definition table. You can also create a new security-
enabled connection, or connect using an existing connection.
“Configuring resource security on z/OS queue managers” on page 44
For z/OS queue managers, you can activate or deactivate security for the whole queue manager (the
subsystem). If security is active at the subsystem level, you can configure the security of the queue
manager's resources, and, if the queue manager belongs to a queue sharing group, you can configure
security for the whole of the queue sharing group.
Related reference
“Queue manager properties” on page 315
You can set properties for both local and remote queue managers.

Configuring resource security on z/OS queue managers

For z/OS queue managers, you can activate or deactivate security for the whole queue manager (the
subsystem). If security is active at the subsystem level, you can configure the security of the queue
manager's resources, and, if the queue manager belongs to a queue sharing group, you can configure
security for the whole of the queue sharing group.

Before you begin

Before you can perform this task, you must have already added the z/OS queue manager to IBM MQ
Explorer and IBM MQ Explorer must be connected to the queue manager. For more information, see
Showing a remote queue manager and Connecting or disconnecting a queue manager.

About this task

If subsystem security is active, when a user accesses an IBM MQ resource, the queue manager signs the
user on to the queue manager. If the user does not access any IBM MQ resources on the queue manager
for a predetermined period of time, the user's user ID is "timed out" and is signed out.
In IBM MQ Explorer, you can perform the following tasks:
1. View the queue manager security settings
2. Configure the timeout period for user IDs
For more information, see Securing.

44 IBM MQ Explorer
 Procedure
• [OPTION 1] View the queue manager security settings
There can be none, one, or more security switches present that determine the security of the queue
manager. The switches can be set on or set off, and the setting of the switches is determined by the
presence or absence of switch profiles. In IBM MQ Explorer, you can view but not configure the setting
of the security switches.
a) In the Navigator view, right-click the queue manager, then click Configuration > Security.
The Security dialog opens. The Security Switches table displays all the security switches that are
present, and are relevant to the queue manager. The table shows whether each security switch is set
on or set off, and which profile determined this setting.
• [OPTION 2] Configure the timeout period for user IDs
If a user is authenticated to access a resource on the queue manager but then doesn't access any of
the queue manager's resources for a predetermined length of time, the user's user ID is timed out.
IBM MQ can make regular checks to determine whether a user ID has timed out. In IBM MQ Explorer,
you can configure the length of the timeout period, and the frequency of checks to determine whether
the timeout period has expired.
a) In the Navigator view, right-click the queue manager, then click Configuration > Security. The
Security dialog opens.
b) In the Security dialog, click Properties.... The Properties dialog opens.
c) In the Properties dialog, edit the parameters that you want to change.
For example, if the Security timeout value is 30 and the Security interval value is 10,
every 10 minutes IBM MQ checks user IDs and their associated resources to determine whether
any have not been used for 30 minutes. If a timed-out user ID is found, that user ID is signed off
within the queue manager. If any timed-out resource information associated with non-timed out
user IDs is found, that resource information is discarded. If you do not want to time-out user IDs,
set the Security interval value to zero. However, if the Interval value is zero, storage occupied
by user IDs and their associated resources is not freed until you issue a REFRESH SECURITY or
RVERIFY SECURITY command from the command line.
d) Click OK to close the Properties dialog.
The changes are shown in the table in the Security dialog.
Related reference
“Queue manager properties” on page 315
You can set properties for both local and remote queue managers.

Testing your object definitions for problems

You can use the IBM MQ Explorer tests to check your object definitions for errors and potential problems.

About this task

When you define objects in IBM MQ Explorer, certain properties of the objects are mandatory and you
cannot create the objects without defining those properties. However, there are several properties that
are not mandatory but which you should define so that your IBM MQ configuration works, so that the
configuration is easier to maintain, or for audit purposes.
The IBM MQ Explorer tests check your object definitions for errors and potential problems. Each area of
IBM MQ that can be checked is defined as a discrete test; for example, there is a test to check that you
have defined matching channel pairs, a test to check that you do not have more than one TCP listener
trying to listen on the same port, and a test to check that multiple queue managers on the same system
are not using the same or similar names. The problems found by the core tests do not always indicate
a serious error and sometimes just indicate where there is potential for confusion and mistakes when

Introduction to IBM MQ Explorer 45

 administering the objects; for example, two queue managers on the same system with similar names
could cause problems.
A set of tests is supplied to check the main IBM MQ object definitions (for example, queues and
channels); for the complete list of IBM MQ tests, see IBM MQ tests. There are also other tests available
that are supplied with other parts of IBM MQ Explorer, such as JMS administered objects.
Test results are displayed in the Test Results view, as shown in the following figure, which opens the first
time that you run the tests.

You can extend the supplied set of tests to include your own custom tests so that IBM MQ Explorer can
provide feedback that is directly relevant to how you use IBM MQ. For instructions and sample custom
tests, see Adding new tests.
Related tasks
“Enabling installed plug-ins” on page 221
If a new plug-in that you install in IBM MQ Explorer is not enabled by default, you can enable it by using
the Preferences dialog.
“Running tests” on page 46
The tests in IBM MQ Explorer are run as test configurations. A test configuration contains a selection
of tests and a list of objects (or types of object) against which the tests are run when you run the test
configuration.
“Adding new tests” on page 56
You can extend the set of tests that is supplied with IBM MQ Explorer to include your own custom tests.

Running tests
The tests in IBM MQ Explorer are run as test configurations. A test configuration contains a selection
of tests and a list of objects (or types of object) against which the tests are run when you run the test
configuration.

About this task

There is a default test configuration for each object type which you can run directly from any of the
objects or folders in the Navigator view. For more information, see “Running the default tests” on page
47.

46 IBM MQ Explorer
You can also create and edit your own test configurations to include new tests that you have written
yourself or that you have obtained from a third party. For more information, see “Creating and running
your own test configuration” on page 47.
When you have run a test configuration, you can rerun an individual test without editing the test
configuration. For more information, see “Rerunning an individual test” on page 48.
Related tasks
“Adding new tests” on page 56
You can extend the set of tests that is supplied with IBM MQ Explorer to include your own custom tests.
“Testing your object definitions for problems” on page 45
You can use the IBM MQ Explorer tests to check your object definitions for errors and potential problems.

Running the default tests

The default test configuration contains the tests that are appropriate for the type of object against which
you are running the test configuration.

About this task

You cannot change the selection of tests that are included in the default test configuration. If you edit the
default test configuration, next time you run the default test configuration, the edited test configuration is
not used; a new test configuration containing the default tests is created instead.
To run the default test configuration, complete the following steps.

Procedure
In the Navigator view, right-click the object or folder against which you want to run the tests, then click
Tests > Run Default Tests.
While the tests are running, click Run in Background on the progress bar to run the tests in the
background while you continue working. Alternatively, on the General page of the Preferences dialog,
select the Always run in background check box. To view the progress of the tests while they run in the
background, open the Progress view: click Window > Show View > Other then click Basic > Progress.

Results
When the test run has finished, a confirmation message is displayed. You can switch off this confirmation
message in the Preferences dialog.
The first time that you run any tests, the Test Results view opens within the IBM MQ Explorer window.
The test results are displayed in the Test Results view.
Related tasks
“Creating and running your own test configuration” on page 47
To have more control over the tests that are run or to include new tests that you have written, you can
create and edit your own test configurations.

Creating and running your own test configuration

To have more control over the tests that are run or to include new tests that you have written, you can
create and edit your own test configurations.

About this task

In a test configuration, you can select the tests that you want to run and also the objects or types of
objects that you want to run the tests against. When you create a test configuration, the default set of
tests is selected for the type of object from which you opened the dialog. However, you can change this
selection and also add other types of object to the test configuration.
To create and run your own test configuration, complete the following steps.

Introduction to IBM MQ Explorer 47

 Procedure
1. In the Navigator view, right-click an object or folder, then click Tests > Run Custom Test
Configuration.
The Run Tests Configurations dialog opens.
2. In the Run Tests Configurations dialog, click Tests to select it.
The configuration icons become available.
3. In the Run Tests Configurations dialog, click New to create a test configuration. The default set of
tests for the object or folder from which you opened the dialog is already selected in the new test
configuration.
A new test configuration is added to the navigation tree. For example, if you opened the Run
Tests Configurations dialog from Q1 queue on the QM1 queue manager, the Queues and Triggering
categories of tests are already selected in the new test configuration; these tests are set to run only
against queues on the QM1 queue manager.
4. In the Name field, type a meaningful name for the new configuration.
5. On the Tests page, select the tests, or categories of tests, to run when you run this test configuration.
6. If you want the test configuration to automatically update when you add new tests to IBM MQ
Explorer, select the Automatically include any new tests.
7. On the Objects page, select the objects, or types of objects, to run the tests against when you run this
test configuration.
8. If you want the test configuration to automatically update when you add new types of object
definitions to IBM MQ Explorer, select the Automatically include any new objects.
9. Click Apply to save the new test configuration.
10. Click Run to run the new test configuration.
While the tests are running, click Run in Background on the progress bar to run the tests in the
background while you continue working.

Results
When the test run has finished, a confirmation message is displayed. You can switch off this confirmation
message in the Preferences dialog.
The first time that you run any tests, the Test Results view opens within the IBM MQ Explorer window.
The test results are displayed in the Test Results view.
Related tasks
“Adding new tests” on page 56
You can extend the set of tests that is supplied with IBM MQ Explorer to include your own custom tests.
“Running the default tests” on page 47
The default test configuration contains the tests that are appropriate for the type of object against which
you are running the test configuration.

Rerunning an individual test

If you have used the information in a test result to change objects in IBM MQ Explorer, you can rerun the
test that produced that result without needing to run the whole test configuration again.

About this task

Rerunning an individual test enables you to quickly check whether the problem has been corrected.
Rerunning an individual test does not edit the test configuration and does not affect future test runs.

48 IBM MQ Explorer
Procedure
To rerun an individual test: In the Test Results view, right-click the test result, then click Run This Test
Again.
The test that generated the selected test result is run again and the test results generated by that test are
updated in the Test Results view.
Related tasks
“Running tests” on page 46
The tests in IBM MQ Explorer are run as test configurations. A test configuration contains a selection
of tests and a list of objects (or types of object) against which the tests are run when you run the test
configuration.

Viewing test results

You can view test results in the Test Results view, which shows the results of the last test configuration
run. You can filter or sort the test results that are displayed in the Test Results view.

About this task

The first time that you run tests against objects in IBM MQ Explorer, the Test Results view opens.
If you close the Test Results view, it reopens the next time you run a test. The view can be reopened
manually at any time by clicking Window > Show View > MQ Explorer - Test Results.
Each row in the Test Results view represents a single test result. One test can generate one or more
test results. To get more information about a test result, double-click the result. A new window opens to
provide a brief explanation of why the test result was generated and whether you must take action.
The Test Results view always shows the test results of the last test configuration run. If you rerun an
individual test, the original results of that test are replaced by the new results (or by nothing at all if the
problems were resolved) but the rest of the original test results are retained.

Click Export Results to save test results to a log file.

You can filter and sort the test results to make it easier to find the information that you need. For more
information see “Filtering test results in the Test Results view” on page 49 and “Sorting test results in
the Test Results view” on page 50.
Related tasks
“Filtering test results in the Test Results view” on page 49
You can filter the test results that are displayed in the Test Results view so that you can, for example,
limit the number of results that are shown at one time, filter the results to show only the errors, or show
only results that contain a specific string.
“Sorting test results in the Test Results view” on page 50
You can sort the test results in the Test Results view by specifying which column to sort by and whether
to display the results in ascending or descending order.
“Rerunning an individual test” on page 48
If you have used the information in a test result to change objects in IBM MQ Explorer, you can rerun the
test that produced that result without needing to run the whole test configuration again.

Filtering test results in the Test Results view

You can filter the test results that are displayed in the Test Results view so that you can, for example,
limit the number of results that are shown at one time, filter the results to show only the errors, or show
only results that contain a specific string.

About this task

To filter the test results displayed:

Introduction to IBM MQ Explorer 49

 Procedure
1. In the Test Results view, click the filter icon to open the Filters dialog.
The Filters dialog opens.
2. Edit the filters as required. For example, to show results that have names containing "IBM"; set
Object name to contains, and type IBM in the field.
3. Click OK to apply your changes and close the dialog.

Results
The Test Results view is refreshed to show only the test results that match the filter criteria.
Any changes you make in this dialog are applied to all views that list problems.
Related tasks
“Viewing test results” on page 49
You can view test results in the Test Results view, which shows the results of the last test configuration
run. You can filter or sort the test results that are displayed in the Test Results view.
“Sorting test results in the Test Results view” on page 50
You can sort the test results in the Test Results view by specifying which column to sort by and whether
to display the results in ascending or descending order.

Sorting test results in the Test Results view

You can sort the test results in the Test Results view by specifying which column to sort by and whether
to display the results in ascending or descending order.

About this task

Click the column name to sort the test results in descending order. Clicking the same column name again
sorts the test results in ascending order. For example:

Procedure
1. In the Test Results view, click the column header called Description to sort the test results in
descending order by description.
2. In the Test Results view, click the column header called Description again to sort the test results in
ascending order by description.
Related tasks
“Viewing test results” on page 49
You can view test results in the Test Results view, which shows the results of the last test configuration
run. You can filter or sort the test results that are displayed in the Test Results view.
“Filtering test results in the Test Results view” on page 49
You can filter the test results that are displayed in the Test Results view so that you can, for example,
limit the number of results that are shown at one time, filter the results to show only the errors, or show
only results that contain a specific string.

IBM MQ supplied tests

Tests that you can use to check your IBM MQ object definitions for problems are supplied with IBM MQ
Explorer.
The following categories of tests are supplied with IBM MQ Explorer to check IBM MQ objects:
• General tests
• Cluster tests
• Queue tests

50 IBM MQ Explorer
• Channel tests
• Listener tests
• Triggering tests
• TLS tests
The tests listed in the following tables are supplied with IBM MQ Explorer to check your IBM MQ object
definitions for problems. There are other tests supplied with IBM MQ Explorer to check objects such as
JMS administered objects for example; such tests are not included in the following table.

General
The following table lists the tests that check for general problems in your IBM MQ definitions.

Test Action Description

Check queue Verifies queue manager This test checks queue manager names, looking for
manager names names for potential names that are similar enough to cause confusion;
problems for example, the test checks for names that are
identical apart from capitalization. The test also displays
warnings for queue managers that are hosted on
different machines but with identical names.
Dead-letter queue Checks queue managers This test displays a warning for any queue manager that
definitions for dead letter queues does not have a dead-letter queue, and one or more
errors for any queue manager that has Dead-letter
Queue attributes that are not valid; for example, the
name of a queue that does not exist, or a queue
that cannot be used as a dead-letter queue. The test
displays a warning or error if any messages are found
on the dead-letter queue because this can be a useful
indication of a problem with the IBM MQ setup. The test
also displays warnings if any channels have a maximum
message length larger than the dead-letter queue size.
FFST error log Checks whether error This test displays an error if any FFST logs have been
logs have been written written to on this machine.
to FFST directory on this
machine
Stopped queue Checks to see if any This test displays a warning for each queue manager
managers queue managers are that is stopped.
stopped
Verify default Verifies default This test displays errors for any invalid uses of the
transmission transmission queues Default Transmission Queue attribute, including a
queues missing queue or a queue with an value that is not valid
in the Type attribute.

Clusters
The following table lists the tests that check for problems in your cluster definitions.

Test Action Description

Cluster fails to Checks that clusters can This test displays an error if any of the cluster
resolve queue successfully resolve all membership entries have not been correctly resolved
manager name queue manager names because the queue manager has not been successfully
contacted.

Introduction to IBM MQ Explorer 51

 Test Action Description
Cluster-sender Checks whether any of This test displays an error if a cluster-sender channel is
channels in the manually defined in the Retrying state.
Retrying state cluster sender channels
are still in Retrying state
Confirm cluster Checks that all cluster This test displays an error for any cluster-sender or
attributes are set channels have a cluster cluster-receiver channels that do not have cluster (or
value set cluster namelist) attributes set.
Duplicate cluster Checks whether any This test displays a warning if any cluster membership
members cluster memberships list contains duplicate entries for a single queue
list the same queue manager.
manager more than
once
Two full Checks that all clusters This test displays a warning if any cluster has only one
repositories have at least two queue full repository.
managers maintaining
full repositories of the
cluster
Verify cluster Verifies the use of This test verifies the cluster namelist attributes of
namelist namelists in cluster queues, channels, and queue managers. The test
definitions definitions displays errors if matching namelists cannot be found,
or if a namelist is empty.
Verify cluster Checks cluster name This test checks the cluster name attributes of queues,
names attributes for potential channels, and queue managers. The test checks for
problems names which are similar enough to cause confusion;
for example, names that are identical apart from
capitalization.
Verify cluster Verifies that all This test displays a warning if different instances of a
queue instances instances of a cluster cluster queue have different attributes.
queue have the same
attributes

Queues
The following table lists the tests that check for problems in your queue definitions.

Test Action Description

Identify full Checks if any known This test checks if the current depth of any known queue
queues queues are full is equal to the value of the queue's Maximum Message
Depth attribute.
Verify alias queue Verifies alias queue This test checks the definitions of alias queues. The test
definitions definitions checks the value of the Base Queue attribute of all
alias queues found, and checks to see if the value is a
valid target for the alias queue.
Verify queue Verifies names of MQ This test checks the names of queue definitions. The
names Queue objects test checks for names that are similar enough to
potentially cause confusion; for example names which
are identical apart from capitalization.

52 IBM MQ Explorer
Test Action Description
Verify that queues Verifies that all known This test verifies that all queues are get-enabled.
are get-enabled queues are not get Although it is not an error if a queue is not get-enabled,
inhibited it might be useful to check for this when trying to
identify the cause of unexpected behavior in your
applications.
Verify that queues Verifies that all known This test verifies that all queues are put-enabled.
are put-enabled queues are not put Although it is not an error if a queue is not put-enabled,
inhibited it might be useful to check for this when trying to
identify the cause of unexpected behavior in your
applications.
Verify remote Verifies remote queue This test verifies the Remote Queue Manager and
queue definitions definitions Remote Queue Name attributes of remote queue
definitions.
Verify use Verifies the usage of This test checks the value of the Transmission
of transmission transmission queues Queue attribute in remote queue definitions. The test
queue in queues in remote queue displays errors if the value is the name of a queue that
definitions does not exist or a queue of the wrong type.

Channels
The following table lists the tests that check for problems in your channel definitions.

Test Action Description

Identify in-doubt Checks if any known This test displays a warning for any channel that is in
channels channels are in an in- doubt.
doubt status
Matching channel Verifies attributes on This test tries to find matching channel pairs. If the test
pairs either end of a channel finds the matching channel pairs, it checks that the two
pair to look for potential ends of the channel are of appropriate types and that
problems the required attributes match at both ends of the pair.
The test displays a warning message if no match or
multiple matches are found for a channel; it displays an
error if a channel pair has incompatible attributes.
Ping all non- Performs an MQ ping This test pings all running sender, server, and cluster-
running channels on all non-running sender channels that are not running and displays
sender, server and any unsuccessful responses in the Test Results view.
cluster-sender channels Channels with Running status are not pinged because it
is assumed that they have valid definitions.
Ping connection Verifies that all This test tries to ping the host names that are referred to
names connection names in a channel definition's Connection name attributes.
referred to by channel The test uses the ping utility that is provided by the
definitions can be operating system, if one is available, otherwise the test
pinged does nothing. The test displays a warning if a ping fails,
and an error if the value of a required Connection
name attribute is missing,
Resolve Verifies that all This test tries to resolve the host names that are
connection names connection names referred to in channel definition's Connection name
referred to by channel attributes, and displays a warning if the host name
definitions can be cannot be resolved to an IP address.
resolved

Introduction to IBM MQ Explorer 53

 Test Action Description
Verify channel Examines the ratios of This test displays potential problems, such as channels
interval values the interval values on with a heartbeat interval greater than the disconnect
channel definitions interval.
Verify channel Verifies names of MQ This test checks the names of channel definitions. The
names channel objects test checks for names that are similar enough to cause
confusion; for example, names that are identical apart
from capitalization.
Verify MCA Verifies that all server- This test displays warnings if any channels have missing
User ID on connection channels MCA User ID attributes. Use it if you expect all server-
server-connection have a value entered for connection channels to have MCA User ID set.
channels MCAUSER
Verify use Verifies the usage of This test displays an error for any invalid use of the
of transmission transmission queues in Transmission queue attribute in sender and server
queues in channel definitions channel definitions, including missing queues, queues
channels with invalid attributes, and transmission queues that are
either not used by any channels or are used by multiple
channels.

Listeners
The following table lists the tests that check for problems in your listener definitions.

Test Action Description

TCP listener port Checks the usage of This test validates the TCP port numbers used by
numbers TCP port numbers by channel listeners. The test displays warnings if invalid
channel listeners port numbers are used or if the same port is used by
multiple queue managers.
Verify listener Verifies names of IBM This test checks the names of listener object definitions.
names MQ Listener objects The test checks for names that are similar enough to
potentially cause confusion; for example, names that are
identical apart from capitalization.

Triggering
The following table lists the tests that check for problems in your triggering configuration.

Test Action Description

Verify initiation Verifies usage of This test validates the Initiation Queue attribute
queue definitions initiation queue attribute of local and model queues. The test displays errors if
of triggered queues the value specifies a local queue that cannot be found.
The test also verifies that all the initiation queues have
processes that have the queue open for input. If a queue
does not have such a process, it indicates that there are
no trigger monitors running against that queue.
Verify process Verifies names of IBM This test checks the names of process definitions. The
names MQ process objects test checks for names that are similar enough to cause
confusion; for example, names that are identical apart
from capitalization.

54 IBM MQ Explorer
Test Action Description
Verify process Validates process object This test validates IBM MQ process definitions. The test
definitions definitions checks that system processes that are specified in the
object's Application ID attribute exist. Where the
Application ID attribute does not give an absolute
path, the test also displays a warning if multiple system
processes with the given name can be found in the path
environment.
Verify process Verifies usage of process This test validates the Process Name attribute of
definitions of attribute of triggered local and model queues and displays errors for process
queues queues names for which an IBM MQ process object definition
cannot be found.
Verify trigger data Verifies usage of trigger This test validates the Trigger Data attribute of local
queue definitions data queue attribute of and model queues and displays errors for names for
triggered queues which a channel cannot be found.
Verify use of Verifies usage of trigger If a queue meets its trigger conditions but the queue is
triggered queues queues not currently open for input, the test displays an error.

SSL/TLS
The following table lists the tests that check for problems in your SSL/TLS configuration.

Test Action Description

Verify that Verifies that SSL/TLS This test highlights any channels which have a last-
channels have channels have been started time earlier than the last modification time of
been restarted restarted since the last the key repository, and which could therefore need
change to the SSL/TLS refreshing.
key repository
Verify SSL channel Verifies that all This test highlights whether any channels have not
authentication channels require got the CipherSpec attribute set. Use this test if you
SSL/TLS authentication expect that all channels are using TLS.
Verify SSL client Verifies that all channels This test highlights whether any channels have not
authentication require SSL/TLS client got the Authetnication of Parties Initiating
authentication Connections (SSLCAUTH) attribute set to Required.
Use this test if you expect that all channels are
using SSL/TLS and that all your clients will present a
certificate for authentication.
Verify SSL key Verifies the presence of This test checks the SSL/TLS Key Repository
repository files SSL/TLS key repositories attribute of queue managers and checks to see if a
file can be found at that location. It also verifies that
a password stash file can be found and is readable.
Verify SSL peer Verifies the SSL/TLS This checks the Accept Only Certificates with
values peer attributes used in Distinguished Names Matching These Values
channel definitions (SSLPEER) attribute of all known channels, reporting
errors for invalid specifications, and warning when the
value is used when the CipherSpec attribute is not.

Related tasks
“Adding new tests” on page 56

Introduction to IBM MQ Explorer 55

 You can extend the set of tests that is supplied with IBM MQ Explorer to include your own custom tests.

Adding new tests

You can extend the set of tests that is supplied with IBM MQ Explorer to include your own custom tests.

About this task

The set of tests that is supplied with IBM MQ Explorer can be extended to include your own custom tests
so that you can teach the IBM MQ Explorer to provide feedback that is directly relevant to your uses of
IBM MQ.
The following topics provide more information about how to write your own tests:
• Creating a new test. A step-by-step guide to preparing the Eclipse development environment for writing
your own tests.
• The 'WMQTest' interface. An explanation of the methods used in a basic test.
• Design Considerations. Some pointers worth considering when writing your own tests.
Some sample source code is provided to assist with writing tests for IBM MQ Explorer:
• Sample 1. A skeleton test that returns static data, as an example of the WMQTest interface.
• Sample 2. A sample test that checks queue names against a defined naming convention, outputting
errors if any queues are found that do not meet the standard.
• Sample 3. A sample test that shows an asynchronous approach to requesting and processing data.
• Sample 4. A diagnostic tool. Use this code in place of real test code to write to the console the objects
that will be accessed by the real test code.

Creating a new test

You can create a new test to add to an existing category and set of tests.

About this task

These instructions describe how to create a new test in an existing category and set of tests (for example,
the Queues test set in the Queue manager tests category) in IBM MQ Explorer. The instructions explain
how to define the test in the Eclipse development environment. For information about writing the Java
test source, see the “WMQTest interface” on page 59.
If you want to create a new set or category of tests instead of using an existing set or category, or if you
have created new objects to administer in IBM MQ Explorer and you are writing tests for the new objects,
see Creating new test categories, test sets, and object types.
• Creating an Eclipse plugin project to contain the new test
• Defining a new test
• Writing a new test
• Deploying the new test

Creating an Eclipse plug-in project to contain the new test

Before you begin

Ensure that you have installed the Eclipse Graphical Editing Framework (GEF) tools. For more information,
see “Installing IBM MQ Explorer into Eclipse environments” on page 10.

About this task

Create and configure a new plug-in project to contain your new test:

56 IBM MQ Explorer
Procedure
1. Open the Plug-in Development perspective.
2. In the Package Explorer view, right-click, then click New > Plug-in Project. The New Plug-in Project
wizard opens.
3. In the Project name field, type a name for the project that contains your new tests.
4. Click Next.
5. Edit the details in the Version, the Name, and the Vendor fields, and then click Finish.
Note the value in the ID field can be different from the value that you entered in the Name field on the
previous page of the wizard. The project name is used only during development; the plugin ID is used
by Eclipse to load and identify the plugin.
The new plug-in project is displayed in the Package Explorer view and the plug-in manifest file is
automatically opened.
6. In the Plug-in Manifest editor, click the Dependencies tab. Two dependencies are already listed in the
Required Plug-ins pane.
7. Add the following plug-ins to the Required Plug-ins pane:
• com.ibm.mq.explorer.tests
• com.ibm.mq.explorer.ui
• com.ibm.mq.pcf.event
• com.ibm.mq.runtime
• org.eclipse.core.resources
If the listed plug-ins are not available, install the Eclipse Graphical Editing Framework (GEF) tools. For
more information, see “Installing IBM MQ Explorer into Eclipse environments” on page 10.
8. Save the MANIFEST.MF file.

Results
The plug-in project is ready to contain tests

Defining a new test

About this task

The following instructions describe how to define a new test an existing test set (for example, in the
Queues test set), in the existing Queue manager tests category. For more information about creating new
test sets in the Queue manager tests category, creating new categories, or defining new object types to be
tested, see Creating new categories, test sets, and object types.
Configure your plug-in to contain a new test:

Procedure
1. Ensure that the plugin.xml or MANIFEST.MF file is open in the Plug-in Manifest editor.
2. In the Plug-in Manifest editor, click the Extensions tab to display the Extensions page.
3. Click Add....
The New Extension wizard opens.
4. Highlight the com.ibm.mq.explorer.tests.Tests extension point, then click Finish.
The new tests extension is added to the All Extensions pane in the Plug-in Manifest editor.
5. Click the new test to highlight it, then enter the test's details as shown in the following table:

Introduction to IBM MQ Explorer 57

 Attribut Description Example value
e
id The unique identifier of the test. com.ibm.mq.explorer.tests.samples.QueueN
ames
name The meaningful name of the test. My Queues Test
class The Java class that contains the test. Do not com.ibm.mq.explorer.tests.samples.QueueN
enter this value yet; you can automatically ames
enter this value when you create the class
later.
testset The category to which the test belongs. The com.ibm.mq.explorer.tests.samples.wmq
example value shown associates the test
with the category Queue manager tests.
testsubs The subcategory to which the test belongs. queues
et The example value shown associates the
test with the subcategory Queues.
descript A description of what the test checks. Checks queue names against simple naming
ion conventions.
furtheri The location of an HTML or XHTML doc/QueueNamesInfo.html (The location
nfo document that contains more information of the file relative to the plugin.xml file.)
about the test. This document is displayed
in IBM MQ Explorer when you double-click
the test in the Run Tests dialog or a test
result in the Test Results view. For more
information, see Test Documentation
6. Save the Plug-in Manifest editor file.

Results
The plug-in project is now configured to contain a new test; next you need to write the test itself.
Define a new test for each new test that you want to write.

Writing a new test

About this task

Create a new Java class that contains the test:

Procedure
1. In the Extension Element Details pane, click the label of the class field, which is underlined.
The Java Attribute Editor wizard opens.
2. Ensure that only the Inherited abstract methods check box is selected, then click Finish. The Java
class file opens in the Java editor.
3. Save the Plug-in Manifest editor file. Notice that the value in the class field is automatically inserted.
4. Edit the Java source.
5. Document the test in a valid XHTML or HTML file. Save the file with the name and location that is
specified in furtherinfo attribute in the plugin.xml file. The location of the XHTML file might be
local (stored in the same plug-in as the test; for example, in a doc subfolder) or remote (stored on a
web server).

58 IBM MQ Explorer
Results
You have completed writing the test and configuring the plugin that contains the test. Next, export the
plug-in and deploy the plug-in to test it.
Write a new test for each test that you defined in the plugin.xml file.

Deploying the new test

About this task

Export the plug-in that contains your test (or set of tests) to the file system then restart IBM MQ Explorer
so that the new plug-in is loaded and you can run the tests:

Procedure
1. In the Package Explorer view, right-click the plugin project, com.ibm.mq.explorer.tests.samples,
then click Export.... The Export... dialog opens.
2. In the Plug-in Development perspective, click Deployable plug-ins and fragments to highlight it,
then click Next.
3. In Directory field, enter the location of the IBM MQ Explorer Tests plugin. The location is
MQ_INSTALLATION_PATH\eclipse, where MQ_INSTALLATION_PATH represents the high-level
directory in which IBM MQ is installed.
4. Select your plug-in in Available Plug-ins and Fragments, and then click Finish.
5. Restart Eclipse, and switch to the IBM MQ Explorer perspective.

Results
You have deployed your new plugin. Now you can run your new tests.

WMQTest interface
Tests written for IBM MQ Explorer must belong to a Java class that extends the provided WMQTest class.
This topic explains the interface and the operation of the provided methods.
• Test attributes - attributes for your test object
• Creating the test - the constructor for test objects
• Test structure - the beginning and end of the test
• Running the test - the main body for tests
• User preferences - accessing the preferences
• Completing the test - marking a test as complete
• Creating a test result - create test results
• Dealing with canceling - what happens if the user wants to cancel a test
• Test documentation - providing more information about the test

Test attributes
Define a test in the plug-in manifest file (plugin.xml) by using a collection of attributes. The attributes
for a test are listed in the following table.

Attribute Description
id A string that provides a unique identifier for the
test.
name A meaningful name for the test.

Introduction to IBM MQ Explorer 59

 Attribute Description
class The name of the Java class that contains the test
source code.
testset A string that defines the group in which to display
the test; for example, wmq, which displays the test
in the Queue manager tests category.
testsubset A string that defines the sub-group in which to
display the test; for example, queues, which
displays the test in the Queues category.
description A short description that describes what the test
does.
furtherinfo The location of an HTML or XHTML document that
contains more information about the test. This
document is displayed in IBM MQ Explorer when
you double-click the test in the Run Tests dialog or
a test result in the Test Results view.

You specify the values of these attributes in the plugin.xml file to define the test. These attributes can also
be accessed programmatically using the WMQTest methods listed in the following table.

Method Description
getTestID() Returns the test ID.
getTestName() Returns the name of the test.
getDescription() Returns the description of the test.
getTestSet() Returns a handle for the test set object that was
created to be a parent for the test.
getFurtherInfoPath() Returns the location of the XHTML or HTML
document that contains more information about
the test.

Creating the test

The IBM MQ Explorer Tests engine instantiates the test object using the provided constructor
WMQTest(). There is no need to subclass this constructor.

Test structure
The WMQTest method runTest defines the body of the test, and is called to start a test running.
The end of the runTest method does not imply the end of the test; you must explicitly specify the end
of the test using the testComplete method. You can implement tests so that they get the object data
asynchronously.
The runTest method submits a request to get data about objects and the test runs from the listener
method that receives the reply. This enables the test to wait for data without you needing to implement
thread waiting; this is demonstrated in Sample 3.
If a manual wait (sleep) is needed as a part of a test, you can use the object monitor for the test object to
use the Java wait and notify methods. The threading of the test engine is implemented without using
the object monitors of individual test objects.

60 IBM MQ Explorer
Running the test
The IBM MQ Explorer Tests engine calls runTest(WMQTestEngine,
IProgressMonitor,contextObjects, treeNode) to start the test running. The main body of your
test must be here.
WMQTestEngine
The WMQTestEngine parameter provides a handle to the test engine that is running the test.
This is provided to allow tests to return results while a test is in progress using the test engine's
returnResult(WMQTestResult[], WMQTest) method.
The first parameter of this method (WMQTestResult[]) contains the results to be returned, and the
second parameter (WMQTest) must be 'this', so that the test engine knows where the results have
come from. Using the WMQTestEngine parameter to return interim results is optional - alternatively,
test results can be returned on test completion (see Completing the test).
IProgressMonitor
The IProgressMonitor parameter provides a handle to the GUI feedback monitor being used for
the current test run. This allows your test to provide both textual feedback on the task and subtasks
currently running, and a progress bar for current completion.
The handle to the Progress Monitor is cached by the default implementation of runTest, so if this
has been used, a handle to the Progress Monitor can also be accessed using the WMQTest method
getGUIMonitor().
The Progress Monitor is a core Eclipse resource. See the Eclipse API documentation on the web for
further advice on using it.
contextObjects
The contextObjects parameter provides an MQExtObject array. The parameter provides the
context of the test to be run so that the relevant check boxes are pre-selected when the user opens
the Run Tests dialog.
treeNode
The treeNode parameter records which folder or object in the Navigator view was clicked to run the
default tests or to open the Run Tests dialog.

User preferences
Tests must conform to the user preferences provided using the Eclipse Preferences dialog. Use the
following methods to access the preferences:
• PreferenceStoreManager.getIncludeHiddenQmgrsPreference() which returns true if you
include queue managers that have been hidden in IBM MQ Explorer in the test, or false if they must be
excluded.
• PreferenceStoreManager.getIncludeSysObjsPreference() which returns true if system
objects (objects which have names beginning with SYSTEM.) must be included in the test, or false
if they must be excluded.

Completing the test

Complete a test by calling testComplete(WMQTestResult[]), passing it an array of test result
objects. See “Creating a test result” on page 62 for guidance on test result objects.
You can return results at completion using this method in addition to, or as an alternative to, returning test
results during a test run (as explained in Running the test). However, any results that are returned twice
are displayed twice.
Even if your test uses the WMQTestEngine method returnResult to return all of its results, it must still
call testComplete on completion. This is necessary to complete the test processing. You can provide an
empty array of WMQTestResult objects in the testComplete method if there are no new results to be
returned.

Introduction to IBM MQ Explorer 61

 For more information, see “Test structure” on page 60.

Creating a test result

Test results are implemented as WMQTestResult objects. Create results using:
WMQTestResult(int severity, String description, String qmgrname, String objectType)
where:
• severity is an integer identifying the severity of the problem. Use one of the following severity levels:
IMarker.SEVERITY_ERROR, IMarker.SEVERITY_WARNING or IMarker.SEVERITY_INFO
• description is the string explaining the problem found by the test, to be displayed in the Problems
View.
• qmgrname is the name of the queue manager where the problem was found.
• objectType is string giving the class of object where the problem can be found, for example, "Queues"
or "Channels".
For more information about what to do with the test result object when it has been created, see
“Completing the test” on page 61.

Dealing with canceling

You can cancel the test run while it is running. Use the method isCancelled() to check if a test must
stop.
A good test must regularly check whether it has been canceled to avoid delaying a user unnecessarily.
If you try to cancel a test but the test fails to respond for an extended period of time, the test engine
forces the test to stop by ending the thread that is running the test. Do not rely upon this method, it is
preferable that a test responds in time allowing the test to clean up any resources it has used, and to
return any test results that have been generated so far.

Test documentation
You can provide additional documentation to explain the results that they return, and provide guidance on
what must be done to resolve the problem.
Provide documentation in HTML, with the location identified in the plugin.xml file for the plug-in providing
the test. For details about defining tests in XML, see “Creating a new test” on page 56.
The location of the documentation HTML file can be:
• internal - Stored in the plug-in project providing the test itself. The location must be defined in the XML
relative to the plugin.xml file itself. For example, doc/TestDoc.html
• external - Stored on a web-server, allowing maintenance of the documentation separately from the test
itself. The location must be defined as a complete URL, beginning with 'http://'.

Creating new test categories, test sets, and object types

You can create new test categories, new test sets in an existing category, and new subsets in an existing
test set. You can also define new object types for which you want to create tests.

About this task

All of the tests that are supplied with IBM MQ Explorer are grouped in the Queue manager tests category.
In the Queue manager tests category, each test is associated with a specific test set; for example,
Queues or Channels. The test sets are used to make the default selections in the Run Tests dialog, which
is based on the type of folder or object in the Navigator view from which you opened the Run Tests
dialog. The test sets are also used to specify which tests are run in the default set of tests.

62 IBM MQ Explorer
You can see these categories and test sets if you open the Run Tests dialog (right-click a folder in
the Navigator view, then click Tests > Run custom test configuration) and look at one of the test
configurations on the Tests page of the dialog.
You can create new categories (like the Queue manager tests category). You can also create new test
sets (like the Queues test set) in a category, and even new subsets in an existing test set.
If you create new object types and folders to display in the Navigator view of IBM MQ Explorer and you
want to create tests that verify definitions of the new object types, you can define the new object types so
that they are displayed as options on the Objects page of the Run Tests dialog.
For instructions on creating new tests in an existing test set in the Queue manager tests category, see
Creating a new test. The following instructions describe how to create new categories and test sets, and
define new object types:
• Creating a new test set in an existing category (com.ibm.mq.explorer.tests.Testset)
• Creating a new category and test set (com.ibm.mq.explorer.tests.TestCategorys)
• Defining a new object type to be tested (com.ibm.mq.explorer.tests.ContextGroup)
Do the following tasks in the Plug-in Development perspective.

Creating a new test set in an existing category (com.ibm.mq.explorer.tests.Testset)

About this task

To create a new test set in an existing category (a category that you did not create; for example the Queue
manager tests category):

Procedure
1. On the Extensions page of the plugin.xml file, add the com.ibm.mq.explorer.tests.Testset
extension to the All Extensions pane.
2. Configure the new test set according to the details in the following table:

Attribut Description Example value

e
category The unique identifier of the category in com.ibm.mq.explorer.tests.coretests.wmq
Id which you are creating the new test set.
id The unique identifier of the category that com.ibm.mq.explorer.tests.samples.NewCat
you are creating. egory
name A meaningful name for the category. My New Category
descript A brief description of the category. This is my first new category.
ion
icon An optional icon that can be used to icons/newcat.gif (The location of the
represent the category. icon file relative to the plugin.xml file.)
furtheri The location of an HTML or XHTML doc/MyObject.html (The location of
nfo document that contains more information the HTML or XHTML file relative to the
about the test. This document is displayed plugin.xml file.)
in IBM MQ Explorer when you double-click
the test in the Run Tests dialog or a test
result in the Test Results view.
3. Save the plugin.xml file.

Results
You have created a new test set in an existing category.

Introduction to IBM MQ Explorer 63

 Creating a new category and test set (com.ibm.mq.explorer.tests.TestCategorys)

About this task

If you are creating a new category, you can create test sets in that category by using a single extension;
that is, you do not need to use the separate com.ibm.mq.explorer.tests.Testset extension as well.
To create a new category:

Procedure
1. On the Extensions page of the plugin.xml file, add the com.ibm.mq.explorer.tests.TestCategorys
extension to the All Extensions pane.
2. Configure the new category according to the details in the following table:

Attribut Description Example value

e
id The unique identifier of the category that com.ibm.mq.explorer.tests.samples.NewCat
you are creating. egory
name A meaningful name for the category. My New Category
descript A brief description of the category. This is my first new category.
ion
icon An optional icon that can be used to icons/newcat.gif (The location of the
represent the category. icon file relative to the plugin.xml file.)
furtheri The location of an HTML or XHTML doc/MyObject.html (The location of
nfo document that contains more information the HTML or XHTML file relative to the
about the test. This document is displayed plugin.xml file.)
in IBM MQ Explorer when you double-click
the test in the Run Tests dialog or a test
result in the Test Results view.
3. Save the plugin.xml file.

Results
You have created a new category.

What to do next
To create a new test set in this category:
1. Right-click the category, then click New > testset to add a new test set to the All Extensions pane.
2. Configure the new test set according to the details in the table in Creating a new test set in an existing
category. Notice that you do not set a categoryID attribute because you are creating the test set in the
category that you just created.
3. Save the plugin.xml file.
You have created a new test set in the new category.

Defining a new object type to be tested (com.ibm.mq.explorer.tests.ContextGroup)

About this task

If you have created new types of objects to be displayed in the Navigator view of IBM MQ Explorer and
you want to create tests to check definitions of the new object types, you must define the object types
by using an com.ibm.mq.explorer.tests.ContextGroup extension. This extension displays a new

64 IBM MQ Explorer
high-level group in the Run Tests dialog on the Objects page at the level of the supplied Queue Managers,
Clusters, and Queue Sharing Groups groups.
To define a new object type:

Procedure
1. On the Extensions page of the plugin.xml file, add the com.ibm.mq.explorer.tests.ContextGroup
extension to the All Extensions pane.
2. Configure the new group according to the details in the following table:

Attribut Description Example value

e
groupId The unique identifier of the group that you com.ibm.mq.explorer.tests.samples.NewGro
are creating. up
name A meaningful name for the group. My New Group
descript A brief description of the group. This is my first new group.
ion

You have defined the new group. Next, define the criteria that is used to identify which group an object
belongs to.
3. In the All Extensions pane, right-click the group, select New, and then select the type of criteria to use
according to the information in the following table:

Criteria Description Example value

type
instance The object must use an instance of a com.ibm.mq.explorer.clusterplugin
Of specific fully qualified class. .internal.objects.ClusterObject
objectTy The object's objectType attribute must have com.ibm.mq.explorer.queuemanager
pe a specific value. You can also specify
whether the value must match the criteria
exactly.
objectId The object's objectId attribute must have a com.ibm.mq.explorer.queuemanager
specific value. You can also specify whether
the value must match the criteria exactly.
4. Save the plugin.xml file.

Results
You have defined the new group of objects for which you can run tests.

Writing your own tests: Sample 1

The following source code is an example of a skeleton test that returns static data. The test is given here
as an example of the WMQTest interface.

/*
* Licensed Materials - Property of IBM
*
* 63H9336
* (c) Copyright IBM Corp. 2005, 2023. All Rights Reserved.
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with
* IBM Corp.

*/

Introduction to IBM MQ Explorer 65

 package com.ibm.mq.explorer.tests.sample;

/**
* Sample test that is run from an additional test in the WMQ standards test tree
*/
public class WMQTestSimple extends WMQTest {

/*
* (non-Javadoc)
*
* @see
com.ibm.mq.explorer.tests.WMQTest#runTest(com.ibm.mq.explorer.tests.internal.actions.WMQTestEngi
ne,
* org.eclipse.core.runtime.IProgressMonitor, com.ibm.mq.explorer.ui.extensions.MQExtObject[],
* java.lang.String)
*/
public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor,
MQExtObject[] contextObjects, TreeNode treenodeId) {

// Start with the default implementation. this will store a handle

// to the test engine that will be needed when we want to submit
// any results at the end of the test
super.runTest(callback, guimonitor, contextObjects, treenodeId);

// prepare space to store test results

ArrayList testresults = new ArrayList();

// initialise the progress bar part of the GUI used to show progress (4 stages)
guimonitor.beginTask(getTestName(), 4);

// Loop through 4 times, incrementing the progress counter by 1 each time

for (int k = 0; k < 4; k++) {
try {
// Sleep for a bit so it looks like we are doing some work
Thread.sleep(900);
}
catch (InterruptedException e) {
}

// increment GUI progress bar used to show progress, completed 1 sleep

guimonitor.worked(1);
}

// Create a new test result and add it to our array list of results
testresults.add(new WMQTestResult(IMarker.SEVERITY_INFO, "SAMPLE: Our addition test
worked!", //$NON-NLS-1$
"Object name", getTestSubCategory())); //$NON-NLS-1$

// package up results and return - test complete.

testComplete((WMQTestResult[]) testresults.toArray(new WMQTestResult[testresults.size()]));
}
}

Writing your own tests: Sample 2

The following source code is an example of a test that checks queue names against a defined naming
convention. If any queues are found with names that do not meet the defined naming convention, the
details are displayed in the Test Results view.

/*
* Licensed Materials - Property of IBM
*
* 5724-H72, 5655-L82, 5724-L26, 5655R3600
*
* (c) Copyright IBM Corp. 2005, 2023.
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
*/
package com.ibm.mq.explorer.tests.sample;

/**
* A sample test used to check Queue Names against naming conventions. Queue names are checked
if
* they begin with any of a set range of prefixes, defined in this class. Any names which do not
* start with one of the prefixes are output in an error.
*

66 IBM MQ Explorer
 * This example uses the PCF classes provide by the MS0B SupportPac. Download the SupportPac
from
* the IBM website, then include the jar file in the build path for the project.
*/
public class WMQQueueNames extends WMQTest {

/** Maintain a count of how many queue managers we are waiting for replies from. */
private static int numberOfQmgrs = 0;

/** Stores the accepted queue name prefixes. */

private static final String[] ACCEPTED_Q_PREFIXES = {"SALES_", "MARKETING_", "SHIPPING_", //
$NON-NLS-1$//$NON-NLS-2$ //$NON-NLS-3$
"INCOMING_", "OUTGOING_"}; //$NON-NLS-1$//$NON-NLS-2$

/** Stores the user preference for whether system queues should be included. */
boolean includeSystemObjs = false;

/**
* Starts the test.
*
*
* @param callback handle to the test engine running the test
* @param guimonitor a handle to the object monitoring the test, provided to allow the test to
* periodically check if the user has tried to cancel the test running and provide additional
user
* feedback
* @param contextObjects context MQExtObjects passed to the test engine
* @param treenodeId the treenodeid used to launch the tests
*/
public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor,
MQExtObject[] contextObjects, TreeNode treenodeId) {

// start with the default implementation. this will store a handle

// to the test engine that will be needed when we want to submit
// any results at the end of the test
super.runTest(callback, guimonitor, contextObjects, treenodeId);

// prepare space to store any results we might want to return

ArrayList testResults = new ArrayList();

// get from Preferences whether we should include system queues

includeSystemObjs = PreferenceStoreManager.getIncludeSysObjsPreference();

// get a list of queue managers from the Explorer

ArrayList allQmgrs = new ArrayList();

for (int k = 0; k < contextObjects.length; k++) {

if (contextObjects[k] instanceof MQQmgrExtObject) {
// Object is a queue manager, add to list
allQmgrs.add(contextObjects[k]);
}
}

// how many queue managers are there?

numberOfQmgrs = allQmgrs.size();

// use the number of queue managers as a guide to track progress

guimonitor.beginTask(getTestName(), numberOfQmgrs);

// for each queue manager, submit a query

for (int i = 0; i < numberOfQmgrs; i++) {

// get next queue manager

MQQmgrExtObject nextQueueManager = (MQQmgrExtObject) allQmgrs.get(i);

// only submit queries to connected queue managers

if (nextQueueManager.isConnected()) {

// get the name of the queue manager, for use in GUI

String qmgrName = nextQueueManager.getName();

// get a handle to a Java object representing the queue manager

MQQueueManager qmgr = nextQueueManager.getMQQueueManager();

try {
// get a PCF message agent to handle sending PCF inquiry to
PCFMessageAgent agent = new PCFMessageAgent(qmgr);

// use PCF to submit an 'inquire queue names' query

PCFMessage response = submitQueueNamesQuery(qmgrName, agent);

// did we get a response to the query?

Introduction to IBM MQ Explorer 67

 if (response != null) {
// get the queue names out of the reply
String[] qnames = (String[]) response.getParameterValue(CMQCFC.MQCACF_Q_NAMES);

// check each name

for (int j = 0; j < qnames.length; j++) {
boolean qnameOkay = checkQueueName(qnames[j]);

if (!qnameOkay) {
// if a problem was found with the name, we generate an
// error message, and add it to the collection to be
// returned
testResults.add(generateTestResult(qnames[j], qmgrName));
}
}
}
}
catch (MQException e) {
// record error details
e.printStackTrace();
}
}

// finished examining a queue manager

guimonitor.worked(1);
}

// return any results that this test has generated

WMQTestResult[] finalresults = (WMQTestResult[]) testResults
.toArray(new WMQTestResult[testResults.size()]);
testComplete(finalresults);
}

/**
* Used internally to submit a INQUIRE_Q_NAMES query using PCF to the given queue manager.
*
*
* @param qmgrName name of the queue manager to submit the query to
* @param agent
* @return the PCF response from the queue manager
*/
private PCFMessage submitQueueNamesQuery(String qmgrName, PCFMessageAgent agent) {

// build the pcf message

PCFMessage inquireQNames = new PCFMessage(CMQCFC.MQCMD_INQUIRE_Q_NAMES);
inquireQNames.addParameter(CMQC.MQCA_Q_NAME, "*"); //$NON-NLS-1$

try {
// send the message
PCFMessage[] responseMsgs = agent.send(inquireQNames);

// check if results received successfully

if (responseMsgs[0].getCompCode() == 0) {
return responseMsgs[0];
}
}
catch (IOException e) {
// record error details
e.printStackTrace();

}
catch (MQException e) {
// record error details
e.printStackTrace();
}

// for some reason, we don't have a response, so return null

return null;
}

/**
* Used internally to check the given queue name against the collection of acceptable
prefixes.
*
*
* @param queueName queue name to check
* @return true if the queue name is okay, false otherwise
*/
private boolean checkQueueName(String queueName) {

// if this is a system object (i.e. it has a name which begins with

// "SYSTEM.") we check the

68 IBM MQ Explorer
 if ((queueName.startsWith("SYSTEM.")) || (queueName.startsWith("AMQ."))) { //$NON-NLS-1$//
$NON-NLS-2$
if (!includeSystemObjs) {
// user has requested that we do not include system
// objects in the test, so we return true to
// avoid any problems being reported for this queue
return true;
}
}

// PCF response will white-pad the queue name, so we trim it now

queueName = queueName.trim();

// check the queue name against each of the acceptable prefixes

// in turn, returning true immediately if it is
for (int i = 0; i < ACCEPTED_Q_PREFIXES.length; i++) {
if (queueName.startsWith(ACCEPTED_Q_PREFIXES[i]))
return true;
}

// we have checked against all accepted prefixes, without

// finding a match
return false;
}

/**
* Used internally to generate a test result for the given queue name.
*
*
* @param queueName queue name which doesn't meet requirements
* @param qmgrName name of queue manager which hosts the queue
* @return the generated test result
*/
private WMQTestResult generateTestResult(String queueName, String qmgrName) {
String res = "Queue (" + queueName.trim() + ") does not begin with a known prefix"; //$NON-
NLS-1$//$NON-NLS-2$

return new WMQTestResult(IMarker.SEVERITY_ERROR, res, qmgrName, getTestSubCategory());

}
}

Writing your own tests: Sample 3

The following source code is an example of a test that shows an asynchronous approach to requesting
data and processing data.

/*
* Licensed Materials - Property of IBM
*
* 5724-H72, 5655-L82, 5724-L26, 5655R3600
*
* (c) Copyright IBM Corp. 2005, 2023.
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
*/
package com.ibm.mq.explorer.tests.sample;

/**
* Pseudo-code sample demonstrating an asynchronous approach to implementing a
* Test.
*/
public class QueuesTest extends WMQTest implements SomeListener {

/** Used to store test results. */

private ArrayList testresults = new ArrayList();

/**
* Used to start the test.
* <p>
* @param callback handle to the test engine running the test
* @param guimonitor a handle to the object monitoring the test,
* provided to allow the test to periodically check
* if the user has tried to cancel the test running
*/
public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor, MQExtObject[]
contextObjects, TreeNode treenodeId) {

super.runTest(callback, guimonitor, contextObjects, treenodeId);

Introduction to IBM MQ Explorer 69

 // reset all test stores
testresults = new ArrayList();

// initialise the progress bar part of the GUI used to show progress of
// this test
guimonitor.beginTask(getTestName(), numqmgrs);

// start the test!

// send query
PseudoQueueManager qmgrHandle = pseudoGetQueueManager();
submitQmgrQuery(qmgrHandle, this, query);

// note that the runTest method is now finished, but the test is not
over!
}

/**
* Used to process results received in response to the query submitted by
* runTest.
* <p>
* @param objects data received
*/
public void dataReponseReceived(ArrayList objects) {

// analyse each of the replies in the collection received in the reply

for ( int i = 0; i < objects.size(); i++ ) {
PseudoQueue nxtQueue = (PseudoQueue) objects.get(i);
analyseQueue(nxtQueue);

// increment GUI progress bar used to show progress of this test

getGUIMonitor().worked(1);
}

// return the completed results

WMQTestResult[] finalresults = (WMQTestResult[]) testresults.toArray(new
WMQTestResult[0]);
testComplete(finalresults);
}

/**
* Analyse the given queue. If any potential problems are found, a problem
* marker is added to the testresults collection.
* <p>
* @param queue queue to analyse
*/
private void analyseQueue(PseudoQueue queue) {

// do something

// add a problem marker to the collection

if (problemFound) {
testresults.add(new WMQTestResult(IMarker.SEVERITY_WARNING,
"A problem was found with "
+ queueName,
getQueueManagerName(queue),
getTestSubCategory()));
}
}
}

Writing your own tests: Sample 4

The following source code is an example of a diagnostic tool. Use this code in place of real test code to
write to the console the objects that will be accessed by the real test code.

/*
* Licensed Materials - Property of IBM
*
* 63H9336
* (c) Copyright IBM Corp. 2005, 2023. All Rights Reserved.
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with
* IBM Corp.

70 IBM MQ Explorer
 */
package com.ibm.mq.explorer.tests.sample;

/**
* List all the context objects provided to standard out
*/
public class WMQTestSimple extends WMQTest {

/*
* (non-Javadoc)
*
* @see
com.ibm.mq.explorer.tests.WMQTest#runTest(com.ibm.mq.explorer.tests.internal.actions.WMQTestEngi
ne,
* org.eclipse.core.runtime.IProgressMonitor, com.ibm.mq.explorer.ui.extensions.MQExtObject[],
* java.lang.String)
*/
public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor,
MQExtObject[] contextObjects, TreeNode treenodeId) {

super.runTest(callback, guimonitor, contextObjects, treenodeId);

// prepare space to store test results

ArrayList testresults = new ArrayList();

// Loop through all supplied MQExtObjects and output them to the console
System.out.println("Objects supplied to this test:"); //$NON-NLS-1$
for (int k = 0; k < contextObjects.length; k++) {
if (contextObjects[k] != null) {
System.out.println(contextObjects[k].getName());
}
}

// Output the tree node ID to the console

System.out.println("tree node ID supplied to this test: " + treenodeId); //$NON-NLS-1$

// Add a test result

testresults.add(new WMQTestResult(IMarker.SEVERITY_WARNING,
"SAMPLE: Listing context completed", //$NON-NLS-1$
"Object name", getTestSubCategory())); //$NON-NLS-1$

// package up results and return - test complete.

testComplete((WMQTestResult[]) testresults.toArray(new WMQTestResult[testresults.size()]));
}
}

Sending test messages

You can use a test message to check whether an application or a queue manager can put a message on a
queue. You can also browse messages that are already on a queue or clear messages from a queue.

About this task

You can verify whether an application or a queue manager can put a message on a queue by using IBM
MQ Explorer to put a test message on the queue. For instructions, see Putting a test message on a queue.
You can also use IBM MQ Explorer to browse messages that are already on a queue. Browsing a queue
enables you to view the messages that are on the queue without getting (removing) them from the queue.
For instructions, see Browsing the messages on a queue.
Finally, you can use IBM MQ Explorer to clear messages from a queue without having to stop and restart
the queue manager. For instructions, see Clearing the messages from a queue.

Putting a test message on a queue

You can use a test message to verify whether an application or a queue manager can put a message on a
queue.

About this task

To put a test message on a queue, complete the following steps.

Introduction to IBM MQ Explorer 71

 Procedure
1. In the Navigator view, click the Queues folder that contains the queue. The queue is displayed in the
Content view.
2. In the Content view, right-click the queue, then click Put Test Message... The Put Test Message dialog
opens.
3. In the Message data field, type some sample message data. For example, type This is a test
message.
4. Click Put Message. The message is put on the queue.
5. Click Close to close the Put Test Message dialog.

Results
In the Content view, the value in the Current queue depth column for the queue is incremented by one. If
the value has not changed, click Refresh on the Content view toolbar.
Related tasks
“Sending test messages” on page 71
You can use a test message to check whether an application or a queue manager can put a message on a
queue. You can also browse messages that are already on a queue or clear messages from a queue.
“Browsing the messages on a queue” on page 72
Browsing a queue enables you to view the messages that are on the queue without getting (removing)
them from the queue.
“Clearing the messages from a queue” on page 73
You can clear messages from a queue without having to stop and restart the queue manager.

Browsing the messages on a queue

Browsing a queue enables you to view the messages that are on the queue without getting (removing)
them from the queue.

About this task

To browse the messages on a queue, complete the following steps.

Procedure
1. In the Navigator view, click the Queues folder that contains the queue.
The queue is displayed in the Content view.
2. In the Content view, right-click the queue, then click Browse Messages...
The Message Browser dialog opens.

Results
The Message browser window displays a user-defined number of bytes from a user-defined number
of messages, with the most recent message at the end of the list. Double-click a message to view its
properties, including the data in the message. All of the messages remain on the queue.
Set the number of messages and number of bytes to be displayed in the Preferences window as
described in “Configuring IBM MQ Explorer” on page 192.
Related tasks
“Sending test messages” on page 71
You can use a test message to check whether an application or a queue manager can put a message on a
queue. You can also browse messages that are already on a queue or clear messages from a queue.
“Putting a test message on a queue” on page 71

72 IBM MQ Explorer
 You can use a test message to verify whether an application or a queue manager can put a message on a
queue.
“Clearing the messages from a queue” on page 73
You can clear messages from a queue without having to stop and restart the queue manager.

Clearing the messages from a queue

You can clear messages from a queue without having to stop and restart the queue manager.

About this task

To clear all the messages from a queue, complete the following steps.

Procedure
1. In the Navigator view, click the Queues folder that contains the queue.
The queue is displayed in the Content view.
2. In the Content view, right-click the queue, then click Clear Messages...
The Clear Queue dialog opens.
3. Select the method to use to clear the messages from the queue:
• If you use the CLEAR command, all of the messages are cleared from the queue. However, if the
queue is already opened exclusively by another application or if the queue contains uncommitted
messages, the command fails immediately and none of the messages are cleared.
• If you use the MQGET API call, the messages are got from the queue until no more messages are
available. However, MQGET does not recognize uncommitted messages, which means that there
could still be uncommitted messages on the queue. Also, the command might fail if the queue is
already exclusively opened by another application.
4. Click Clear.
A message is displayed to tell you whether the command was successful.
5. Click Close to close the dialog.

Results
All the messages are cleared from the queue unless there was a problem; for example, the queue
contains uncommitted messages.
Related tasks
“Sending test messages” on page 71
You can use a test message to check whether an application or a queue manager can put a message on a
queue. You can also browse messages that are already on a queue or clear messages from a queue.
“Putting a test message on a queue” on page 71
You can use a test message to verify whether an application or a queue manager can put a message on a
queue.
“Browsing the messages on a queue” on page 72
Browsing a queue enables you to view the messages that are on the queue without getting (removing)
them from the queue.

Starting and stopping objects and services

Before you can create objects for a queue manager, the queue manager must be running. Similarly, before
an application can send messages through a channel, the channel must be running and the receiving

Introduction to IBM MQ Explorer 73

 queue manager must have a running listener. In addition, any services like channel initiators and trigger
monitors must be running if they are needed.

About this task

For more information, see the following topics:
• Starting and stopping a queue manager
• Starting and stopping a channel
• Starting and stopping a listener
• Starting and stopping a command server
• Starting and stopping a custom service
• Starting a trigger monitor
• Starting a channel initiator

Starting and stopping a queue manager

You can start or stop an individual queue manager, or start or stop all the queue managers in a queue
manager set.

About this task

Before you can create IBM MQ objects to be hosted by a queue manager, and before you can start any of
the IBM MQ objects that are hosted by the queue manager, you must start the queue manager.
In some circumstances, such as if you have changed the attributes of the queue manager, if you want
to apply a fix pack to IBM MQ, or if you want to stop the queue manager participating in a messaging
network, you must stop the queue manager.
To start or stop a queue manager in IBM MQ Explorer, complete either of the following steps:
1. Start or stop an individual queue manager
2. Start or stop all the queue managers in a queue manager set

Procedure
• [OPTION 1] Start or stop an individual queue manager
a) In the Navigator view, expand the Queue Managers folder.
b) Right-click the name of the queue manager, then click Start or Stop.
c) If you chose to stop the queue manager, select Controlled or Immediate.
d) Click OK.
The icon next to the queue manager name changes to indicate that the queue manager has started or
stopped as appropriate.
• [OPTION 2] Start or stop all the queue managers in a queue manager set
Before you start or stop all the queue managers in a set, you must take the following steps:
– You must display queue manager sets as described in “Displaying queue manager sets” on page
201.
– You must define a set for the queue managers as described in “Defining manual sets” on page 202
or “Defining automatic sets” on page 203.
a) In the Navigator view, expand the Queue Managers folder.
b) Right-click the name of the set to open the menu. Click Start Local Queue Managers or Stop Local
Queue Managers.

74 IBM MQ Explorer
 The icon next to the queue manager's name changes to indicate that the queue managers in the set
have started or stopped as appropriate.
Related concepts
“Queue managers” on page 14
A queue manager is a program that provides messaging services to applications. Applications that use the
Message Queue Interface (MQI) can put messages on queues and get messages from queues. The queue
manager ensures that messages are sent to the correct queue or are routed to another queue manager.
“Objects in IBM MQ Explorer” on page 13
In IBM MQ Explorer, all of the queue managers and their IBM MQ objects are organized in folders in the
Navigator view.

Reconnectable clients
IBM MQ clients can take advantage of automatic reconnection if their connection to a queue manager
is broken. This is of value when a connection breaks, or a queue manager fails. When you stop a queue
manager you have the option of enabling the automatic reconnection of clients.
There are a number of ways to code and configure an IBM MQ MQI client to make it continue to work if the
queue manager to which it is connected fails. An application program can respond to a queue manager
failure by closing queues and subscriptions and disconnecting from the failing queue manager. The client
program might then attempt to reconnect, and either wait until the queue manager is running again, or
connect to another queue manager in the same queue manager group.
To make this common procedure easier, a client program can connect to a queue manager with the option
of being automatically reconnected to another queue manager (or reconnected to this queue manager) if
the current connection fails. No application programming is required. The application program does not
have to be notified of any broken connection errors from the queue manager.
Automatic client reconnection is not supported by IBM MQ classes for Java.
As the IBM MQ administrator, you might want to signal to all client application programs, including
ones that have requested queue manager failures to be handled automatically, that you are stopping
the queue manager deliberately, and want client applications to stop, rather than have the client
applications treat the queue manager stoppage as a failure and attempt to reconnect automatically.
This is the default behavior of the Stop queue manager command, to maintain compatibility with
earlier releases of IBM MQ. However, as an option on the Stop queue manager command, you can use
the Instruct reconnectable clients to reconnect option, and the indication that the queue
manager is stopping is intercepted by a reconnectable client connection, and it starts trying to reconnect
automatically as if a failure had occurred.
Related concepts
Automatic client reconnection

Starting and stopping a channel

The way in which a channel is started depends on whether it is a caller channel or a responder channel.
When you stop a channel, you can choose whether to stop the channel after the current batch of
messages has finished processing, or force the channel to shut down before the current message batch
has finished processing.

Before you begin

You must have the required transport protocol, for example, TCP/IP, on the computers at each end of the
channel.

About this task

Channels can be categorized as either callers or responders. An application starts caller channels either
directly, or automatically by using a channel initiator. Responder channels can be started only by the
listener.

Introduction to IBM MQ Explorer 75

 You can start caller channels in IBM MQ Explorer. When you start responder channels in IBM MQ Explorer,
you are actually changing the responder channel's state from Stopped to Inactive; the listener then
changes the state from Inactive to Started. You must, therefore, start a listener on your computer if you
are using responder channels.

Procedure
• Start a channel manually.
a) In the Navigator view, click the Channels folder to display the channels in the Content view.
b) In the Content view, right-click the channel, then click Start.
The channel starts. The icon next to the channel changes to show that the channel is running.
• Stop a channel.
a) In the Navigator view, click the Channels folder to display the channels in the Content view.
b) In the Content view, right-click the channel, then click Stop....
The Stop Channel dialog opens.
c) Select how IBM MQ stops the channel:
– Accept the default values (do not select the check boxes) to end the channel after the current
batch of messages has finished processing (on Multiplatforms), or to end the channel after the
current message (on z/OS). For a receiving channel, if there is no batch in progress, the channel
waits for either the next batch or the next heartbeat (if heartbeats are being used) before
stopping. For server-connection channels, the channel stops when the connection ends.
– Select the Force interruption of current message batch check box to terminate the
transmission of any current batch; the channel's thread or process is not terminated. This is
likely to result in in-doubt channels. For server-connection channels, the current connection is
broken.
– Select the Allow process/thread termination check box if you select the Force interruption of
current message batch check box and you want to terminate the channel thread or process.
d) If the channel definition is a responder channel, multiple queue managers or remote connections
can be using the same responder channel. You can, therefore, filter which channels are stopped:
select the relevant check box then type the name of the queue manager or remote connection.
e) Select the state that the channel will change to when it stops:
– Click Stopped to stop the channel but keep the process or thread running; the channel is still
active and consuming resources.
– Click Inactive to stop the channel, including stopping the process or thread; the channel is
inactive and is not consuming resources.
The channel stops running. The icon next to the channel changes to show that the channel is no longer
running.
Related concepts
“Listeners” on page 24
A listener is an IBM MQ process that listens for connections to the queue manager.
“Channel initiators” on page 31
A channel initiator is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs. A channel initiator is a special type of trigger monitor that starts channels
rather than applications.
“Channels” on page 20

76 IBM MQ Explorer
IBM MQ can use three different types of channels: a message channel, an MQI channel, and an AMQP
channel.

Starting and stopping a listener

Each listener object in IBM MQ Explorer represents a listener process; when you start the listener object
in IBM MQ Explorer, the listener process starts.

About this task

For a queue manager to receive messages from channels, it must have a running listener that is correctly
configured for its transport type. The listener will then start the receiving end of the channel when it
detects that an application has started the sending end of the channel.
To start or stop a listener, complete the following steps.

Procedure
1. In the Navigator view, click the Listeners folder to display the listeners in the Content view.
2. In the Content view, right-click the listener, then click Start or Stop.

Results
The listener starts or stops as appropriate.

Listeners on the z/OS platform are not listener objects and do not behave in the same way
as listener objects. When listeners on the z/OS platform are stopped, they are no longer associated with
the z/OS queue manager.
Related concepts
“Listeners” on page 24
A listener is an IBM MQ process that listens for connections to the queue manager.
“Channels” on page 20
IBM MQ can use three different types of channels: a message channel, an MQI channel, and an AMQP
channel.
Related tasks
“Starting and stopping a channel” on page 75
The way in which a channel is started depends on whether it is a caller channel or a responder channel.
When you stop a channel, you can choose whether to stop the channel after the current batch of
messages has finished processing, or force the channel to shut down before the current message batch
has finished processing.
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.

Starting and stopping a command server

To connect to a queue manager from IBM MQ Explorer, the queue manager command server must be
running.

About this task

To start or stop the command server, complete the following steps.

Procedure
In the Navigator view, right-click the queue manager, then click Start Command Server or Stop
Command Server.

Introduction to IBM MQ Explorer 77

 Results
The command server starts or stops as appropriate.
Related tasks
“Starting and stopping a queue manager” on page 74
You can start or stop an individual queue manager, or start or stop all the queue managers in a queue
manager set.

Starting and stopping a custom service

You can configure a custom service to start automatically when the queue manager starts. You can also
start or stop a service manually.

About this task

You can configure a custom service to automatically start when the queue manager starts by changing
the value of the Service control attribute in the service's properties dialog. The following instructions
describe how to manually start a service.
Note that if there is no end command defined in the service, for example, for trigger monitors, when the
service stops, the object that the service is controlling does not stop.
To start or stop a service, complete the following steps.

Procedure
1. In the Navigator view, click the Services folder to display the services in the Content view.
2. In the Content view, right-click the service, then click Start or Stop.

Results
The service starts or stops as appropriate. The icon next to the service changes to show whether the
service is running.
Related concepts
“Custom services” on page 31
Custom services are services that you create to run commands automatically.
“Trigger monitors” on page 30
A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.

Starting a trigger monitor

To start a trigger monitor, you must first create a service that will start the trigger monitor.

About this task

To start a trigger monitor from IBM MQ Explorer, you must first create a service that will run the
runmqtrm command (to start the trigger monitor) when the service starts.
Note that if you are starting a trigger monitor for a client, use the runmqtmc command instead. For more
information about trigger monitors, see Trigger monitors.
To start a trigger monitor, complete the following steps.
Note: When the trigger monitor runs as a service, the started process or application runs in the
background.

78 IBM MQ Explorer
Procedure
1. In the Navigator view, expand the queue manager on which you want to start the trigger monitor
service.
2. Right-click the queue manager's Services folder, then click New... > Service. The New Service dialog
opens.
3. In the New Service dialog, type a name for the service, for example, TriggerMonitor, then click
Next. You can now configure the new service.
4. Optional: In the Description field, type a description of the service, for example, A trigger
monitor for queue manager QM1.
5. In the Service control field, configure how the service starts and stops:
• To start and stop the service automatically when the queue manager starts and stops, click Queue
Manager
• To start the service automatically when the queue manager starts but not to stop when the queue
manager stops, click Queue Manager Start
• To configure the service so that you must manually start and stop it, click Manual.
6. In the Start Command field, type the full path to the runmqtrm command.
• Type: MQ_INSTALLATION_PATH\bin\runmqtrm where MQ_INSTALLATION_PATH is replaced by
the high-level directory in which IBM MQ is installed.
7. If the queue manager is not the default queue manager, in the Start args field, type -m
queue_manager_name where queue_manager_name is the name of the queue manager.
8. If you want to use a queue other than SYSTEM.DEFAULT.INITATION.QUEUE as the initiation queue, in
the Start args field, type -q initq_name where initq_name is the name of the queue.
9. In the Service Type field, select the type of service to run:
• If you select Command, you can run multiple instances of the service but you cannot view the
status of the service in IBM MQ Explorer.
• If you select Server, you can run only one instance of the service but you can view the status of the
service in IBM MQ Explorer.
10. Click Finish.
The new service is created on the selected queue manager.
11. Start the service.
For instructions, see “Starting and stopping a custom service” on page 78.

Results
The service starts and runs the runmqtrm command, which starts the trigger monitor on the queue
manager.
When you have started a trigger monitor, it just continues monitoring the specified initiation queue. You
cannot stop a trigger monitor directly. When you stop the trigger monitor's queue manager, the trigger
monitor stops too.
Related concepts
“Trigger monitors” on page 30

Introduction to IBM MQ Explorer 79

 A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.

Starting a channel initiator

To start a channel initiator, you must first create a service that will start the channel initiator.

About this task

Because a channel initiator is just a special type of trigger monitor, to start a channel initiator from IBM
MQ Explorer, you must first create a service that will run the runmqchi command (to start the channel
initiator) when the service starts.
The following instructions assume that you are creating a service called ChannelInitiator on a queue
manager called QM1. For more information about channel initiators, see Starting and stopping the
channel initiator.
To create the channel initiator service:

Procedure
1. In the Navigator view, expand the queue manager, QM1, that you want to start the channel initiator
on.
2. Right-click the queue manager's Services folder, then click New... > Service. The New Service dialog
opens.
3. In the New Service dialog, type a name for the service, for example, ChannelInitiator, then click
Next. You can now configure the new service, ChannelInitiator.
4. Optional: In the Description field, type a description of the ChannelInitiator service, for example, A
channel initiator for queue manager QM1.
5. In the Service control field, configure how the service starts and stops:
• To start and stop the service automatically when the queue manager starts and stops, click Queue
Manager
• To start the service automatically when the queue manager starts but not to stop when the queue
manager stops, click Queue Manager Start
• To configure the service so that you must manually start and stop it, click Manual.
6. In the Start Command field, type the full path to the runmqchi command.
• Type: MQ_INSTALLATION_PATH\bin\runmqchi where MQ_INSTALLATION_PATH is replaced by
the high-level directory in which IBM MQ is installed.
7. If QM1 is not the default queue manager, in the Start args field, type -m QM1
8. If you want to use a queue other than SYSTEM.CHANNEL.INITQ as the initiation queue, in the Start
args field, type -q initq_name where initq_name is the name of the queue.
9. In the Service Type field, select Command.
10. Click Finish.
The new service, ChannelInitiator, is created on the selected queue manager, QM1.
11. Start the service.
For instructions, see “Starting and stopping a custom service” on page 78.

Results
The service, ChannelInitiator, starts and runs the runmqchi command, which starts the channel initiator
on the queue manager, QM1.
Related concepts
“Trigger monitors” on page 30

80 IBM MQ Explorer
 A trigger monitor is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs.
“Channel initiators” on page 31
A channel initiator is an application that processes the trigger messages that are put on initiation queues
when a trigger event occurs. A channel initiator is a special type of trigger monitor that starts channels
rather than applications.

Showing or hiding a queue manager

By default, the Navigator view shows all of the queue managers on the computer on which IBM MQ
Explorer is installed. However, if you have any queue managers that you are not currently administering,
you can, if you wish, choose to hide them. You can also show and hide remote queue managers.

About this task

Before you can administer a queue manager in IBM MQ Explorer, you must show the queue manager in
the Queue Managers folder in the IBM MQ Explorer Navigator view. By default, all of the queue managers
on the computer on which IBM MQ Explorer is installed are detected automatically and are shown in the
Queue Managers folder. You can hide queue managers if you don't want to administer them in IBM MQ
Explorer.
If you are configuring JMS administered objects, you can add a queue manager to IBM MQ Explorer from
a connection factory that defines the queue manager's connection details. You are actually creating a
connection to IBM MQ Explorer from the connection factory that defines the queue manager's details.
You can also administer remote queue managers using cluster connections if you are already connected
to a queue manager that belongs to a cluster to which the remote queue manager also belongs.
The following topics describe how to show and hide local and remote queue managers in IBM MQ
Explorer:
• Show local queue managers
• Show remote queue managers
• Hide queue managers
• Show hidden queue managers
• Remove queue managers
• “Adding a queue manager from a JMS connection factory” on page 42
• Administering a remote cluster queue manager
Related concepts
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.
Related tasks
“Administering remote queue managers” on page 92

Introduction to IBM MQ Explorer 81

 In IBM MQ Explorer, you can enable IBM MQ queue managers on a remote computer for remote
administration.

Showing a local queue manager

If you want to administer a local queue manager, it must appear in the Navigator view.

About this task

All of the queue managers that are hosted on the computer on which IBM MQ Explorer is installed are
automatically detected and shown in the Queue Managers folder in IBM MQ Explorer but you can hide
them from view. To administer a local queue manager using IBM MQ Explorer, you must show the queue
manager in the Queue Managers folder in the Navigator view of IBM MQ Explorer.
If you have hidden the queue manager from view, you can show it again. For instructions, see: Showing
hidden queue managers.
Related tasks
“Hiding queue managers” on page 88
You can hide from view any queue manager that is displayed in the Navigator view. If you hide a queue
manager that is a member of one or more queue manager Sets, the queue manager is not displayed in any
of those Sets.
“Showing a remote queue manager” on page 82
If you want to administer a remote queue manager, you must connect IBM MQ Explorer to the remote
queue manager so that the queue manager is displayed in the Navigator view. You can create a
connection manually, or using a client channel definition table. You can also create a new security-
enabled connection, or connect using an existing connection.
“Administering remote queue managers” on page 92
In IBM MQ Explorer, you can enable IBM MQ queue managers on a remote computer for remote
administration.
“Removing a queue manager” on page 90
You can remove a queue manager from IBM MQ Explorer if you no longer want to administer it in IBM MQ
Explorer.

Showing a remote queue manager

If you want to administer a remote queue manager, you must connect IBM MQ Explorer to the remote
queue manager so that the queue manager is displayed in the Navigator view. You can create a
connection manually, or using a client channel definition table. You can also create a new security-
enabled connection, or connect using an existing connection.

About this task

IBM MQ Explorer automatically discovers all the queue managers on the computer on which IBM MQ
Explorer is installed. However, IBM MQ Explorer does not automatically discover queue managers on
other computers.
To administer remote queue managers, you must manually connect IBM MQ Explorer to the remote queue
manager and show the queue manager in the Queue Managers folder in IBM MQ Explorer.
Use one of the following methods to connect to a remote queue manager:
1. Create a connection manually. Create a connection to the remote queue manager using the Add
Queue Manager wizard. You can use the default SYSTEM.ADMIN.SVRCONN channel or a server-
connection channel that you specify yourself.
2. Create a connection using a client channel definition table. If you use a client channel definition table
to configure the channel, you can for example, define security exits on the channel.
3. Create a new security-enabled connection. Create a new security-enabled connection to the remote
queue manager.

82 IBM MQ Explorer
4. Connect using an existing connection. Connect to a remote queue manager using and existing
connection that has been made by another queue manager.
You can also show remote cluster queue managers in the Queue Managers folder so that you can
administer them from IBM MQ Explorer. For more information, see Administering remote cluster queue
managers.
If IBM MQ Explorer cannot connect to the remote queue manager for any reason (for example, the remote
queue manager is not running), a dialog is displayed asking if you want to add the queue manager anyway.
Click Yes and the queue manager is displayed in the Queue Managers folder but none of its details are
available until it connects.
IBM MQ Explorer cannot connect to queue managers that are running on IBM MQ platforms that do not
support remote administration. For more information about which IBM MQ platforms are supported, see
Administering remote queue managers.
Automatic client reconnect is not supported by IBM MQ classes for Java.
For more detailed information about CCDTs, see Client channel definition table.

Procedure
• [OPTION 1] Create a connection manually
Before you can create the connection, you must know the following information about the remote
queue manager:
– The name of the queue manager.
– The name of the computer that hosts the queue manager.
– The port number of the queue manager's listener.
– The name of the server-connection channel on the queue manager that IBM MQ Explorer uses to
connect to the queue manager. If you have enabled the queue manager for remote administration,
the SYSTEM.ADMIN.SVRCONN channel is available. Otherwise, use SYSTEM.DEF.SVRCONN, a client
channel definition table, or a server-connection channel that you have created and named.
a) Right-click on Queue Managers in the Navigator view, then click Add Remote Queue Manager
The Add Queue Manager wizard opens enabling you to create a connection.
b) In the Queue manager name field, type the name of the queue manager to which you want to
connect.
c) Ensure that Connect directly is selected, then click Next.
d) Ensure that Specify connection details is selected, then type the following details:
– In the Host name or IP address field, type the name of the computer that hosts the remote
queue manager; Use one of the following formats:
- The short host name, for example, joho The remote computer must be in the same domain as
your local computer.
- The fully qualified host name, for example, joho.example.com Use this if the remote
computer is in a different domain to your local computer.
- The IP address, for example 127.0.0.1
– In the Port number field, type the port number; for example, 1416
– In the Server-connection channel field, type the name of the channel to use
To change the defaults that are used, see “Specifying the default values used to connect to remote
queue managers” on page 223
e) Optional: Select the Autoreconnect check box to configure IBM MQ Explorer to automatically
reconnect to the queue manager if the connection is lost.
f) Optional: Change the frequency with which IBM MQ Explorer refreshes its information about the
queue manager. To prevent IBM MQ Explorer automatically refreshing its information about the

Introduction to IBM MQ Explorer 83

 queue manager, click No queue manager refresh interval; to specify a different refresh interval,
click Specify queue manager refresh interval, then type the number of seconds that you want IBM
MQ Explorer to wait before refreshing its information about the queue manager.
g) Click Finish.
IBM MQ Explorer connects to the remote queue manager, and the queue manager is shown in the
Queue Managers folder in the Navigator view.
• [OPTION 2] Create a connection using a client channel definition table
Instead of manually specifying the connection details of the remote queue manager, you can use a
predefined client channel definition table. Using this method of connection means that you can, for
example, configure the channel to use security exits.
Before you can create a connection using a client channel definition table, you must create the client
channel definition table on the computer that hosts the remote queue manager, then copy the client
channel definition table to the local computer (from which you want to connect to the remote queue
manager).
IBM MQ Explorer connects to the remote queue manager using the client channel definition table, and
the queue manager is shown in the Queue Managers folder in the Navigator view.
To connect to the remote queue manager using the client channel definition tables, complete the
following steps in IBM MQ Explorer on the local computer (the computer from which you want to
connect to the remote queue manager).
a) Right-click on Queue Managers in the Navigator view, then click Add Remote Queue Manager
The Add Queue Manager wizard opens enabling you to create a connection.
b) In the Queue manager name field, type the name of the queue manager to which you want to
connect.
c) Ensure that Connect directly is selected, then click Next.
d) Click Use client channel definition table, then browse for the client channel definition table file.
e) Optional: Select the Autoreconnect check box to configure IBM MQ Explorer to automatically
reconnect to the queue manager if the connection is lost.
f) Optional: Change the frequency with which IBM MQ Explorer refreshes its information about the
queue manager. To prevent IBM MQ Explorer automatically refreshing its information about the
queue manager, click No queue manager refresh interval; to specify a different refresh interval,
click Specify queue manager refresh interval, then type the number of seconds that you want IBM
MQ Explorer to wait before refreshing its information about the queue manager.
g) Click Finish.
• [OPTION 3] Create a new security-enabled connection
For more information about using TLS with client connections, see Secure Sockets Layer (SSL) support
in IBM MQ classes for Java.
To connect to a remote queue manager using a security-enabled connection, complete the following
steps in IBM MQ Explorer on the computer from which you want to connect to the remote queue
manager.
Note: If you place the IBM MQ Explorer plug-ins in another Eclipse environment, to use the full set
of CipherSuites, and to operate with certified FIPS 140-2 or Suite-B compliance, a suitable JRE is
required. IBM Java 7 Service Refresh 4, Fix Pack 2 or a higher level of the IBM JRE provides the
appropriate support.
a) Right-click on Queue Managers in the Navigator view, then click Add Remote Queue Manager
The Add Queue Manager wizard opens, enabling you to create a connection.
b) In the Queue manager name field, type the name of the queue manager to which you want to
connect.
c) Ensure that Connect directly is selected, then click Next.

84 IBM MQ Explorer
 d) Ensure that Specify connection details is selected, then type the following details:
– In the Host name or IP address field, type the name of the computer that hosts the remote
queue manager; Use one of the following formats:
- The short host name, for example, joho The remote computer must be in the same domain as
your local computer.
- The fully qualified host name, for example, joho.example.com Use this if the remote
computer is in a different domain to your local computer.
- The IP address, for example 127.0.0.1.
– In the Port number field, type the port number; for example, 1416.
– In the Server-connection channel field, type the name of the channel to use.
To change the defaults that are used, see “Specifying the default values used to connect to remote
queue managers” on page 223.
e) Optional: Select the Autoreconnect check box to configure IBM MQ Explorer to automatically
reconnect to the queue manager if the connection is lost.
f) Optional: Change the frequency with which IBM MQ Explorer refreshes its information about the
queue manager. To prevent IBM MQ Explorer automatically refreshing its information about the
queue manager, click No queue manager refresh interval; to specify a different refresh interval,
click Specify queue manager refresh interval, then type the number of seconds that you want IBM
MQ Explorer to wait before refreshing its information about the queue manager.
g) Click Next.
At this point in the wizard, you can select the optional security parameters on the new pages of the
wizard. All the security parameters are optional and you are not required to enable any of them if
you do not want to, however, you must select Enable SSL stores to access the Enable SSL options
parameters:
1. Optional. Select Enable security exit and type your security exit details into the fields. The remote
server conn channel must also have a security exit defined. Click Next.
2. Optional. Select Enable user identification and type your required user identification details in the
field. If you want to set the optional password, type your password details in the field. Optional: The
remote server conn channel can also have a security exit defined. Click Next.
3. Optional. Select Enable SSL stores to specify TLS certificate key repository details. The remote
server conn channel must also have TLS enabled. To specify certificate stores choose either one or
both of the following options.
– Optional. Click Browse in the Selected Certificate Store section of the dialog to locate the
certificate store file. If you want to set the optional password, click Enter password... to open
the Password details dialog where you must type your password details in the fields.
– Optional. Click Browse in the Personal certificate Store section of the dialog to locate your
personal certificate store file. You must set a password when defining a personal certificate
store; click Enter password... to open the Password details dialog where you must type your
password details in the fields.
Click Next.
4. Optional. Select Enable SSL options. Select the TLS options you require, and click Finish to create
the TLS-enabled connection and close the wizard. You must have previously selected Enable SSL
stores to access the Enable SSL options parameters.
Passwords used by the IBM MQ Explorer to connect to resources, for example, opening TLS stores or
connecting to queue managers, can be stored in a file. The location of the file can be changed to a
remote or removable device. For more information, see: “Passwords preferences” on page 163.
IBM MQ Explorer now connects to the remote queue manager using a TLS-secured connection, and
the queue manager is shown in the Queue Managers folder in the Navigator view.
• [OPTION 4] Connect using an existing connection

Introduction to IBM MQ Explorer 85

 IBM MQ Explorer connects to the remote queue manager and the queue manager is shown in the
Queue Managers folder in the Navigator view.
You can also use existing cluster connections to administer remote cluster queue managers. For more
information, see Administering remote cluster queue managers.
To connect using an existing connection that has been made by another queue manager, complete the
following steps.
a) Right-click on Queue Managers in the Navigator view, then click Add Remote Queue Manager.
The Add Queue Manager wizard opens enabling you to create a connection.
b) In the Queue manager name field, type the name of the queue manager to which you want to
connect.
c) Click Connect using an intermediate queue manager, then click Next.
d) From the Intermediate queue manager list, click the name of the queue manager that made the
existing connection.
e) Optional: Select the Autoreconnect check box to configure IBM MQ Explorer to automatically
reconnect to the queue manager if the connection is lost.
f) Optional: Change the frequency with which IBM MQ Explorer refreshes its information about the
queue manager. To prevent IBM MQ Explorer automatically refreshing its information about the
queue manager, click No queue manager refresh interval; to specify a different refresh interval,
click Specify queue manager refresh interval, then type the number of seconds that you want IBM
MQ Explorer to wait before refreshing its information about the queue manager.
g) Click Finish.
Related tasks
“Administering remote queue managers” on page 92
In IBM MQ Explorer, you can enable IBM MQ queue managers on a remote computer for remote
administration.
“Administering a remote cluster queue manager” on page 124
After connecting IBM MQ Explorer to a remote cluster queue manager using the cluster information
source as an intermediate queue manager, you can select to show the queue manager in the Queue
Managers folder. You can use then use the connection to administer the remote queue manager.
Related reference
“Passwords preferences” on page 163
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Creating a client channel definition table

You can create a client channel definition table for a queue manager to make it easier to connect
instances of IBM MQ Explorer to the queue manager.

About this task

When you connect IBM MQ Explorer to the queue manager using the client channel definition table, the
table provides all of the connection information and you do not need to know the connection details to
connect to the queue manager.
The following instructions describe how to create a client channel definition table that can be used for
connections secured by Transport Layer Security (TLS). To create a client channel definition table that
does not use TLS, just skip the steps about configuring TLS.
To create a client channel definition table, perform the following tasks on the computer that hosts the
remote queue manager:

86 IBM MQ Explorer
Procedure
1. If you want to secure connections that use the client channel definition table, configure the queue
manager for using TLS-enabled connections.
2. Create a server-connection channel on the queue manager.
3. If you are using TLS, configure the server-connection channel to use TLS.
4. Create a client-connection channel, with the same name as the server-connection channel, on the
queue manager.
5. If you are using TLS, configure the client-connection channel to use TLS.
If you have configured the server-connection channel to use TLS, you must also configure the client-
connection channel to match.
6. Move the queue manager's client channel definition table to the computer from which you want to
connect to the queue manager (the computer on which IBM MQ Explorer is installed). For example, use
FTP to transfer the file between the two computers.

Results
Your new client channel definition table is now available for IBM MQ Explorer to use to connect to the
remote queue manager.
Related tasks
“Configuring TLS channels” on page 131
To configure TLS channels, you use the SSL page of the Channel properties dialog to define the cipher
specification to be used. You can optionally configure a channel to accept only certificates with attributes
in the distinguished name of the owner that match given values. You can also optionally configure a queue
manager channel so that the queue manager refuses the connection if the initiating party does not send
its own personal certificate.
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.

Specifying the default location and default password of TLS certificates

You can configure IBM MQ Explorer to use TLS certificates in the TrustStore and KeyStore to connect to
remote queue managers with an TLS-enabled connection.

About this task

To configure IBM MQ Explorer with the location and password of the TLS certificate store, complete the
following tasks in IBM MQ Explorer on the computer from which you want to connect to the remote queue
manager:

Procedure
1. In IBM MQ Explorer, click Window > Preferences.
The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand Client Connections. The default security settings dialogs are now accessible.
4. Select SSL Key Repositories to display the SSL Key Repositories pane.
5. In the Trusted Certificate Store field, browse for the location of the TrustStore on the computer, and
in Personal Certificate Store field, browse for the location of the KeyStore on the computer.
The TrustStore and KeyStore contain the TLS certificates that are used with connections using client
channel definition tables. It is possible that the TrustStore and KeyStore are in the same location on
your computer.

Introduction to IBM MQ Explorer 87

 6. (Optional) Click Enter password... in the Trusted certificate Store section to open the SSL Password
dialog; in the SSL Password dialog, type the password that IBM MQ Explorer will need to access the
store.
7. Click Enter password... in the Personal Certificate Store section to open the SSL Password dialog; in
the SSL Password dialog, type the password that IBM MQ Explorer will need to access the store.
8. Click OK to save your changes and to close the Preferences dialog.

Results
IBM MQ Explorer can now use the TLS certificates in the TrustStore and KeyStore to connect to remote
queue managers with an TLS-enabled connection.
Related tasks
“Showing a remote queue manager” on page 82
If you want to administer a remote queue manager, you must connect IBM MQ Explorer to the remote
queue manager so that the queue manager is displayed in the Navigator view. You can create a
connection manually, or using a client channel definition table. You can also create a new security-
enabled connection, or connect using an existing connection.
“Creating a client channel definition table” on page 86
You can create a client channel definition table for a queue manager to make it easier to connect
instances of IBM MQ Explorer to the queue manager.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.

Hiding queue managers

You can hide from view any queue manager that is displayed in the Navigator view. If you hide a queue
manager that is a member of one or more queue manager Sets, the queue manager is not displayed in any
of those Sets.

About this task

Hiding queue managers enables you to restrict the queue managers that are displayed in the Queue
Managers folder if you have been working with many queue managers in IBM MQ Explorer.
To hide queue managers, complete any of the following steps:
1. Hide queue managers using Navigator: Method 1.
2. Hide queue managers using Navigator: Method 2.
3. Hide queue managers using Sets.

Procedure
• [OPTION 1] Hide queue managers using Navigator: Method 1.
a) In the Navigator view, select a queue manager. Hold down the Ctrl key to select more than one
queue manager.
b) To hide the selected queue managers, right-click then choose Hide.
The selected queue managers are no longer displayed in the Queue Managers folder. If the queue
managers you have hidden are members of one or more queue manager Sets, then those queue
managers are not displayed in those Sets.
• [OPTION 2] Hide queue managers using Navigator: Method 2.
a) In the Navigator view, right-click the Queue Managers folder, then click Show/Hide Queue
Managers.

88 IBM MQ Explorer
 The Show/Hide Queue Managers dialog opens. A list of the visible queue managers is displayed in
the Shown Queue Managers table of the Show/Hide Queue Managers dialog.
b) In the Shown Queue Managers table, select one or more queue managers then click Hide. The
selected queue managers are now listed in the Hidden Queue Managers table.
c) Click Close.
The selected queue managers are no longer displayed in the Queue Managers folder. If the queue
managers you have hidden are members of one or more queue manager Sets, then those queue
managers are not displayed in those Sets.
• [OPTION 3] Hide queue managers using Sets.
You can also hide from view any queue managers that are grouped in a queue manager Set. This
enables you to restrict the queue managers that are displayed in the Set and Queue Managers folder if
you have been working with many queue managers in IBM MQ Explorer.
Before you can hide all the queue managers in a Set, you must complete the following steps:
1. You must display the queue manager sets as described in “Displaying queue manager sets” on
page 201.
2. You must define a set for the queue managers as described in “Defining manual sets” on page 202
or “Defining automatic sets” on page 203.
a) In the Navigator view, right-click the Set, then click Hide All Queue Managers.
The queue managers in the set are no longer displayed in the Set folder.
When you hide the queue managers in a Set, the queue managers are then hidden in every Set
(including the All Set) not just the Set you selected.
Related tasks
“Showing hidden queue managers” on page 89
You can show queue managers that have previously been hidden from the Navigator view. You can restore
all hidden queue managers together, or restore a specific queue manager. You can also show hidden
queue managers that are grouped in a queue manager Set.
“Removing a queue manager” on page 90
You can remove a queue manager from IBM MQ Explorer if you no longer want to administer it in IBM MQ
Explorer.

Showing hidden queue managers

You can show queue managers that have previously been hidden from the Navigator view. You can restore
all hidden queue managers together, or restore a specific queue manager. You can also show hidden
queue managers that are grouped in a queue manager Set.

About this task

If you have hidden local or remote queue managers from view in the Queue Managers folder and you are
now required to administer those queue managers, you can show the queue managers again.
To restore all hidden queue managers in one go, complete any of the following steps:
1. Show all hidden queue managers.
2. Show specific hidden queue managers.
3. Show hidden queue managers using Sets.

Procedure
• [OPTION 1] Show all hidden queue managers.
a) In the Navigator view, right-click the Queue Managers folder, then click Show All Hidden Queue
Managers

Introduction to IBM MQ Explorer 89

 • [OPTION 2] Show specific hidden queue managers.
a) In the Navigator view, right-click the Queue Managers folder, then click Show/Hide Queue
Managers
The Show/Hide Queue Managers dialog opens. A list of the hidden queue managers is displayed in
the Hidden Queue Managers table.
b) In the Hidden Queue Managers table, select one or more queue managers, then click Show.
The selected queue managers are now listed in the Shown Queue Managers table.
c) Click Close.
The selected queue managers are shown in the Queue Managers folder.
• [OPTION 3] Show hidden queue managers using Sets.
Before you show the hidden queue managers that are grouped in a queue manager Set, you must
complete the following steps:
1. You must display the queue manager sets as described in “Displaying queue manager sets” on
page 201.
2. You must define a set for the queue managers as described in “Defining manual sets” on page 202
or “Defining automatic sets” on page 203.
a) In the Navigator view, right-click the Set, then click Show All Queue Managers.
The previously hidden queue managers are now shown in the Set folder.
When you show the queue managers in a Set, the queue managers are then shown in every Set
(including the All Set) not just the Set you selected.
Related tasks
“Hiding queue managers” on page 88
You can hide from view any queue manager that is displayed in the Navigator view. If you hide a queue
manager that is a member of one or more queue manager Sets, the queue manager is not displayed in any
of those Sets.
“Removing a queue manager” on page 90
You can remove a queue manager from IBM MQ Explorer if you no longer want to administer it in IBM MQ
Explorer.

Removing a queue manager

You can remove a queue manager from IBM MQ Explorer if you no longer want to administer it in IBM MQ
Explorer.

About this task

If you no longer want to administer a queue manager in IBM MQ Explorer, you can remove the queue
manager from the Queue Managers folder.
To remove a queue manager:

Procedure
1. In the Navigator view, right-click the Queue Managers folder, then click Show/Hide Queue
Managers....
The Show/Hide Queue Managers dialog opens.
2. If the queue manager is currently shown in the Queue Managers folder, in the Shown Queue
Managers table, hide the queue manager so that the queue manager is displayed in the Hidden Queue
Managers table.
For more information, see Hiding queue managers.
3. In the Hidden Queue Managers table, click the name of the queue manager, then click Remove...

90 IBM MQ Explorer
 4. When prompted, click Yes to confirm that you want to remove the queue manager from IBM MQ
Explorer.

Results
When you remove a queue manager from IBM MQ Explorer, the queue manager still exists on its host
computer but you cannot administer it in IBM MQ Explorer until you add it to the Queue Managers folder
again.
Related tasks
“Administering remote queue managers” on page 92
In IBM MQ Explorer, you can enable IBM MQ queue managers on a remote computer for remote
administration.
“Hiding queue managers” on page 88
You can hide from view any queue manager that is displayed in the Navigator view. If you hide a queue
manager that is a member of one or more queue manager Sets, the queue manager is not displayed in any
of those Sets.
“Showing hidden queue managers” on page 89
You can show queue managers that have previously been hidden from the Navigator view. You can restore
all hidden queue managers together, or restore a specific queue manager. You can also show hidden
queue managers that are grouped in a queue manager Set.

Connecting or disconnecting a queue manager

If you want to administer a queue manager in IBM MQ Explorer, you must connect IBM MQ Explorer to the
queue manager.

Before you begin

Before you can connect IBM MQ Explorer to a queue manager, perform the following tasks:
• Show the queue manager in the Queue Managers folder in IBM MQ Explorer.
• If the queue manager is on a different computer to IBM MQ Explorer, ensure that the queue manager is
running.

About this task

To administer a queue manager in IBM MQ Explorer, you must connect IBM MQ Explorer to the queue
manager. You can connect to any local queue manager, regardless of whether the queue manager is
running. However, you can connect to a remote queue manager only if it is running.
You can also configure a queue manager so that IBM MQ Explorer automatically reconnects to it if the
connection is lost. For more information, see “Automatically reconnecting to a queue manager” on page
92

Procedure
1. To connect IBM MQ Explorer to a queue manager: In the Navigator view, right-click the queue
manager, then click Connect or Disconnect.
IBM MQ Explorer connects or disconnects the queue manager. The color of the queue manager's icon
changes to yellow when connected, or gray when disconnected.
Disconnected queue managers remain in the Queue Managers folder. If you want to remove a queue
manager completely from IBM MQ Explorer, see “Removing a queue manager” on page 90.
2. If you have queue manager Sets enabled, then you can connect and disconnect all the queue
managers in a Set: In the Navigator view, right-click the set, then click Connect Queue Managers
or Disconnect Queue Managers.
All queue managers will be connected or disconnected depending on the option you selected.

Introduction to IBM MQ Explorer 91

 Related tasks
“Showing or hiding a queue manager” on page 81
By default, the Navigator view shows all of the queue managers on the computer on which IBM MQ
Explorer is installed. However, if you have any queue managers that you are not currently administering,
you can, if you wish, choose to hide them. You can also show and hide remote queue managers.
Related reference
“Icons in IBM MQ Explorer” on page 280
IBM MQ Explorer uses icons to represent the different objects, such as queue managers, queues, and
channels.

Automatically reconnecting to a queue manager

You can configure each queue manager so that IBM MQ Explorer automatically connects to it at startup
or reconnects to it if the connection is lost; for example, if the network connection to a remote queue
manager fails.

About this task

If you manually disconnect IBM MQ Explorer from the queue manager, the queue manager is not
automatically reconnected until the next time that you close and restart IBM MQ Explorer. Only queue
managers that are connected when IBM MQ Explorer is closed, and that are configured to autoreconnect,
are automatically reconnected when IBM MQ Explorer is started again.

Procedure
• To configure a queue manager so that IBM MQ Explorer automatically reconnects to it, perform one of
the following tasks:
• For a remote queue manager, when you add the queue manager to IBM MQ Explorer, you can select
the Automatically connect to this queue manager at startup or if the connection is lost check
box in the Show/Hide Queue Managers wizard.
• For local queue managers, and remote queue managers that are already shown in the Queue
Managers folder, in the Navigator view, right-click the queue manager, then click Autoreconnect. A
check mark is placed next to the menu item to indicate that IBM MQ Explorer is set to automatically
reconnect to the queue manager if the connection is lost.

What to do next
To configure the queue manager so that IBM MQ Explorer does not automatically reconnect to it, right-
click the queue manager, then click Autoreconnect. The check mark next to the menu item is removed.
Related tasks
“Connecting or disconnecting a queue manager” on page 91
If you want to administer a queue manager in IBM MQ Explorer, you must connect IBM MQ Explorer to the
queue manager.

Administering remote queue managers

In IBM MQ Explorer, you can enable IBM MQ queue managers on a remote computer for remote
administration.

About this task

In IBM MQ Explorer, you can administer IBM MQ on other computers that are connected to your computer
by TCP/IP. It is possible to connect to a remote queue manager by using a different transport protocol. To
use a different transport protocol, the connection must go through another queue manager to which IBM
MQ Explorer is connected.
All currently supported releases of IBM MQ on all platforms support remote administration.

92 IBM MQ Explorer
For more information about operating systems and command levels, see System Requirements for IBM
MQ on the external IBM website.
To find out what command level any IBM MQ queue manager supports, display the properties of the
queue manager and check the CommandLevel (CMDLEVEL) property.
You cannot start, stop, create, or delete a remote queue manager from IBM MQ Explorer.
To administer a queue manager on Computer A from IBM MQ Explorer on Computer B:

Procedure
1. On Computer A, show the queue manager in IBM MQ Explorer.
2. On Computer A, start the queue manager.
3. To use the SYSTEM.ADMIN.SVRCONN server connection channel on Computer A to connect to the
queue manager, enable the queue manager for remote administration.
4. On Computer B, show the remote queue manager in IBM MQ Explorer.

Results
You can administer the queue manager on Computer A from IBM MQ Explorer on Computer B.

Enabling remote administration of queue managers

In IBM MQ Explorer, you can administer queue managers that are hosted by other computers connected
to your computer by TCP/IP. This includes queue managers that are hosted on z/OS.

About this task

It is possible to connect to a remote queue manager using a different transport protocol but the
connection must go through another queue manager to which IBM MQ Explorer is connected.
To remotely administer a queue manager, the queue manager must be running and you must:

Procedure
1. Ensure that there is a running command server.
2. Create a server-connection channel to allow remote administration of the queue manager over TCP/IP.
3. Create a listener to accept incoming network connections.
4. Ensure that the listener is running.
Any TCP/IP listener and any server-connection channel can be used for this administration.
You must enable the IBM MQ queue manager for remote administration using the default
SYSTEM.ADMIN.SVRCONN server connection channel.
You can enable remote administration on a queue manager on Windows or Linux (x86 and x86-64
platforms) computers using IBM MQ Explorer. On other platforms, you must configure the queue manager
from the command line.
For more information, see Administering remote IBM MQ objects or Authority to administer IBM MQ on
UNIX and Windows systems.

Introduction to IBM MQ Explorer 93

 Enabling remote administration on an existing queue manager using the system
default objects
In IBM MQ Explorer, you can administer queue managers that are hosted by other computers connected
to your computer by TCP/IP using system default objects. This includes queue managers that are hosted
on z/OS.

About this task

When you install IBM MQ, if there are queue managers on the computer from a previous installation, and
any of the queue managers are not enabled for remote administration, you can choose to run the Remote
Administration wizard. The Remote Administration wizard updates the queue managers that you specify.
If you have already installed IBM MQ on the remote Windows or Linux (x86 and x86-64 platforms)
computer, and the computer hosts queue managers that are not enabled for remote administration, you
can enable them for remote administration using the system default objects as follows:
Before you enable remote administration on an existing queue manager using the system default objects,
start the queue manager in IBM MQ Explorer on the computer that hosts the remote queue manager.
To enable remote administration of an existing queue manager:

Procedure
1. Right-click the queue manager in the Navigator view, then click Remote Administration.... The
Remote Administration dialog opens. IBM MQ checks whether the SYSTEM.ADMIN.SVRCONN server
connection channel exists, and checks whether there is a listener created and running. The results are
displayed in the Remote Administration dialogue.
2. Click Create to create a SYSTEM.ADMIN.SVRCONN channel if one does not exist. The
SYSTEM.ADMIN.SVRCONN channel is created.
3. Click Create to create a LISTENER.TCP listener if one does not exist. The LISTENER.TCP listener is
created.
4. Click Close to close the dialog.
For more information, see Authority to administer IBM MQ on UNIX and Windows systems.

Enabling remote administration when you create a new queue manager

When you create a new queue manager in IBM MQ Explorer, you can enable remote administration for
this new queue manager. The queue manager is configured to use the SYSTEM.ADMIN.SVRCONN server
connection channel for remote administration.

About this task

This task provides steps on how to enable remote administration when a new queue manager is created.
To enable a new queue manager for remote administration, complete the following steps.

Procedure
1. In the Create Queue Manager wizard, select the following options:
a) Create server connection channel
b) Create listener configured for TCP/IP
2. Type a port number in the Listen on port number field. The port number must not be in use by another
running queue manager hosted on the same computer.
When the queue manager is created, it is configured to use the SYSTEM.ADMIN.SVRCONN server
connection channel for remote administration.
For more information, see Administering remote IBM MQ objects or Authority to administer IBM MQ on
UNIX and Windows systems.

94 IBM MQ Explorer
Maintaining intercommunications along message channels
You might sometimes need to take action in order to maintain intercommunications along message
channels. For example you might need to resolve an in-doubt channel by either backing out or committing
the messages, or reset channel synchronization if the message counts at the two ends of the channel
are not in synchronization. You can also configure channels to reduce the possibility of a sending channel
being put in doubt and made unavailable.

About this task

When a channel tries to commit a logical unit of work, if the receiving end of the channel is not available,
the sending end of the channel is put in-doubt because it cannot determine whether the messages on
the transmission queue have been committed. The messages are held on the transmission queue and no
messages can be sent through the channel until the channel's status has been resolved. Often, in-doubt
channels are automatically resolved by IBM MQ when connection between the two ends of the channel
is re-established. However, this can cause delays, especially if the connection cannot be re-established
because, for example, the receiving end of the channel has been deleted.
The Message Channel Agent (MCA) keeps a record of the number of messages sent and received (the
Sequence Number) and the ID of the last-committed logical units of work (the LUWID).
• “Resolving in-doubt channels” on page 96
• “Resetting channel synchronization” on page 95
• “Configuring the channel to reduce the opportunity of being put 'in-doubt'” on page 97
For more information, see Distributed queueing and clusters.
Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.

Resetting channel synchronization

If synchronization errors are reported because the message counts at the two ends of the channel are not
in synchronization, you can reset the synchronization.

About this task

The Message Channel Agents (MCAs) at the two ends of a channel each keep count of the number of
messages sent through the channel so that synchronization between the two ends of the channel can be
maintained. Synchronization can be lost, for example, when the channel definition at one end is deleted
and then re-created. The re-created channel definition resets its count to 0, and if a queue manager
attempts to use the channel, synchronization errors are reported because the two ends of the channel are
not in synchronization.
To fix problems with channel synchronization, you must reset the count of the channel definition that was
not re-created.
To reset the count, complete the following steps.

Procedure
1. In the Content view, right-click the channel definition that was not re-created, then click Reset The
Reset dialog opens.
2. In the Reset dialog, type the sequence number to which you want to reset the channel definition:
• If the other end of the channel has been deleted and then re-created, type 0.
• If the channel is a sender or server channel, type any number from 0 to the value defined in
the Sequence number wrap attribute of the channel (the default value is 999,999,999). The new

Introduction to IBM MQ Explorer 95

 message sequence number is sent automatically to the other end of the channel, which then sets its
number to match the next time that the channels are started.
• For all other channel types, type the current sequence number of the other end of the channel.
To find the current sequence number of the other end of the channel, right-click the name of the
channel, then click Status
3. Click Yes to reset the channel definition to the message count that you typed in the Message Sequence
Number field.

Results
The two ends of the channel have the same message count and so are synchronized.
For more information, see Distributed queueing and clusters.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Maintaining intercommunications along message channels” on page 95
You might sometimes need to take action in order to maintain intercommunications along message
channels. For example you might need to resolve an in-doubt channel by either backing out or committing
the messages, or reset channel synchronization if the message counts at the two ends of the channel
are not in synchronization. You can also configure channels to reduce the possibility of a sending channel
being put in doubt and made unavailable.
Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.

Resolving in-doubt channels

If there is no possibility that a link that has been lost might recover, you must resolve an in-doubt channel
by either backing out or committing the messages.

About this task

The sending end of a channel might be holding messages in-doubt because, for example, it has lost
the connection with the receiving end of the channel. If there is no prospect of the link recovering, the
channel must be resolved either to back out the messages (restore the messages to the transmission
queue) or commit the messages (discard the messages).
To resolve a channel, complete the following steps.

Procedure
1. Find out the last committed Logical Unit of Work ID (LUWID) for each end of the channel:
a) In the Content view, right-click the channel definition at one end of the channel, then click Status...
The Status dialog for that channel definition opens.
b) In the Status dialog, look for the value in the Last LUWID column. This value shows the ID of the
last logical unit of work that was committed by the channel. Make a note of the value.
c) Repeat Steps 1 and 2 for the channel definition at the other end of the channel.
2. In the Content view, right-click the sending end of the channel, then click Resolve... The Resolve
dialog opens.
3. In the Resolve dialog, select the method with which to resolve the channel:

96 IBM MQ Explorer
 • If the LUWID at the sending end of the channel is the same as the LUWID at the receiving end of
the channel, click Commit to commit the messages and discard the messages from the transmission
queue.
• If the LUWID at the sending end of the channel is different from the LUWID at the receiving end of
the channel, click Back out to back out the unit of work and retain the messages to the transmission
queue so that the messages can be re-sent.

Results
The channel is no longer in doubt and the transmission queue can be used by a different channel to
re-send the messages.
For more information, see Distributed queueing and clusters.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Maintaining intercommunications along message channels” on page 95
You might sometimes need to take action in order to maintain intercommunications along message
channels. For example you might need to resolve an in-doubt channel by either backing out or committing
the messages, or reset channel synchronization if the message counts at the two ends of the channel
are not in synchronization. You can also configure channels to reduce the possibility of a sending channel
being put in doubt and made unavailable.
Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.

Configuring the channel to reduce the opportunity of being put 'in-doubt'

By using the Batch heartbeat interval attribute, you can reduce the possibility of a sending channel being
put in doubt and made unavailable.

About this task

You can configure channels, using the Batch heartbeat interval attribute, so that the sending end of the
channel checks that the receiving end of the channel is still active before the channel tries to commit the
current logical unit of work. When the Batch heartbeat interval attribute is set, the sending end of the
channel sends a heartbeat to the receiving end before the channel tries to commit the current logical unit
of work.
If the sending channel has had a communication from the receiving channel within the Batch heartbeat
interval, the receiving channel is assumed to be still active, otherwise a 'heartbeat' is sent to the receiving
channel to check. The sending channel waits for a response from the receiving end of the channel for an
interval, based on the number of seconds specified in the channel Heartbeat Interval (HBINT) attribute.
The advantage of using the Batch heartbeat interval is that instead of the sending channel being put in
doubt and made unavailable, the only delay is the time during which the sending end of the channel is
sending the heartbeat and waiting for a response from the receiving end of the channel.
To configure the Batch heartbeat interval attribute:

Procedure
1. Open the sending channel properties dialog.
2. On the Extended page, type the number of seconds that the sending end of the channel waits for a
response from the receiving end of the channel.

Introduction to IBM MQ Explorer 97

 3. Click OK.

Results
Whenever the channel is ready to commit a logical unit of work, the sending end of the channel sends a
heartbeat to the receiving end of the channel to check that the receiving end of the channel is still active.
For more information, see Distributed queueing and clusters.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Maintaining intercommunications along message channels” on page 95
You might sometimes need to take action in order to maintain intercommunications along message
channels. For example you might need to resolve an in-doubt channel by either backing out or committing
the messages, or reset channel synchronization if the message counts at the two ends of the channel
are not in synchronization. You can also configure channels to reduce the possibility of a sending channel
being put in doubt and made unavailable.
Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.

Configuring publish/subscribe messaging

In publish/subscribe messaging, the sender of a message (the publisher) is decoupled from the recipient
of the message (the subscriber) so that the publisher does not need to know who will receive the
message and the subscriber does not necessarily know who sent the message. The publisher publishes
the message to the broker, which is then responsible for distributing the message to any subscribers who
have registered an interest in the information in the message.

Procedure
• “Publishers and subscribers” on page 98
• Configuring publish/subscribe messaging for IBM WebSphere MQ 7.0 and later queue managers.

Publishers and subscribers

Publishers and subscribers are applications that send and receive messages (publications) using the
publish/subscribe method of messaging. Publishers and subscribers are decoupled from one another so
that publishers do not know the destination of the information that they send, and subscribers do not
know the source of the information that they receive.
The provider of the information is called a publisher. Publishers supply information about a subject
without needing to know anything about the applications that are interested in the information.
The consumer of the information is called a subscriber. The subscriber decides what information it is
interested in, and then waits to receive that information. Subscribers can receive information from many
different publishers, and the information they receive can also be sent to other subscribers.
The information is sent in an IBM MQ message, and the subject of the information is identified by a
topic string. The publisher specifies the topic string when it publishes the information, and the subscriber
specifies the topic strings on which it wants to receive publications. The subscriber is sent information
about only those topic strings to which it subscribes.
IBM WebSphere MQ 7.0 and later queue managers, use a Pub/Sub Engine instead of a broker to
control the interactions between publishers and subscribers. The Pub/Sub Engine receives messages
from publishers, and subscription requests from subscribers. The Pub/Sub Engine's job is to route the
published data to the target subscribers.

98 IBM MQ Explorer
 Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
“Publications” on page 19
Publications are messages that are sent by an application to the Publish/Subscribe Engine. The Publish/
Subscribe Engine then sends the messages on to any applications that have subscribed to receive the
messages.
Related tasks
“Configuring publish/subscribe for IBM MQ queue managers” on page 99
In IBM MQ Explorer, you can configure IBM MQ queue managers as Publish/Subscribe Engines to route
messages between publishing applications and subscribing applications. To test your configurations, you
can register as a subscriber, and send and receive test publications if you are authorized to do so.

Configuring publish/subscribe for IBM MQ queue managers

In IBM MQ Explorer, you can configure IBM MQ queue managers as Publish/Subscribe Engines to route
messages between publishing applications and subscribing applications. To test your configurations, you
can register as a subscriber, and send and receive test publications if you are authorized to do so.

Before you begin

For more conceptual information about Publish/Subscribe, Topics, Subscriptions, and Publications, see
the following topics:
• Publish/subscribe messaging
• Topics
• Subscribers and subscriptions
• Publishers and publications
Before you begin configuring:
• “Creating and configuring queue managers and objects” on page 13. The queue manager will host the
Publish/Subscribe Engine.

About this task

To configure publish/subscribe messaging on an IBM MQ queue manager, complete one or more of the
tasks described in the subtopics.

Procedure
• “Creating a new topic” on page 100
• “Creating a new cluster topic” on page 101
• “Viewing the topic status” on page 102
• “Sending and receiving test publications on a topic object folder” on page 103
• “Sending and receiving test publications for specific topics” on page 104
• “Viewing topic status for publishers” on page 105
• “Viewing topic status for subscribers” on page 106
• “Creating a new subscription” on page 107
• “Viewing a list of subscribers” on page 108
• “Refreshing proxy subscriptions” on page 108
• “Creating a new Multicast communication information object” on page 109

Introduction to IBM MQ Explorer 99

 What to do next
In IBM MQ Explorer, you can also view and clear retained publications.

Creating a new topic

A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a publish/subscribe message.

Before you begin

For the latest information on topic strings, wildcard characters, special characters, and topic trees, see
the following links.
• A topic string can include any character from the Unicode character set, including the space character.
However, there are characters that have special meanings. The characters; plus sign (+), number sign
(#), asterisk (*), and question mark (?) are described in Wildcard schemes.
• Topic strings are case sensitive, and although a null character does not cause an error, do not use null
characters in your topic strings. For the latest information on topic strings, see Using topic strings.
• Each topic that you define is an element, or node, in the topic tree. For the latest information on topic
trees, see Topic trees.
The queue manager that hosts the Publish/Subscribe engine must be visible in the Navigator view. To
show the queue manager, follow the instructions in “Showing or hiding a queue manager” on page 81

About this task

To create a new topic in the IBM MQ Explorer:

Procedure
1. Expand the queue manager that hosts the Publish/Subscribe Engine to display the object-folders in
the Navigator view.
2. Right-click Topics, then click New > Topic.

Results
The New Topic wizard opens. Work though the wizard to create a new topic.

What to do next
For information about topic names, topic strings and topic wildcards, refer to the following links.
Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Viewing the topic status” on page 102

100 IBM MQ Explorer

A topic identifies what a publication is about. The topic status displays information about the topic, such
as publications and subscriptions.

Creating a new cluster topic

You can either convert an existing topic into a cluster topic, or create a new cluster topic. You do this by
navigating to the topic properties, then specifying the name of the cluster that is to host this topic, and the
cluster routing mechanism to use for publications on this topic.

Before you begin

Create a cluster containing two or more queue managers, as described in “Creating a queue manager
cluster” on page 115.
The SYSTEM.BASE.TOPIC and SYSTEM.DEFAULT.TOPIC should not typically be used as cluster topics.
This is because SYSTEM.BASE.TOPIC is present on all cluster queue managers, therefore it only affects
the local queue manager unless it is modified on all queue managers to have a correctly functioning
publish/subscribe cluster. The entire topic tree is also within a single cluster, preventing subsections of
topic space being in a cluster, and making it harder to divide subsections of topic space into separate
clusters. However, there are situations where it is necessary, such as IBM Integration BusCollective
migration. For more information, see Publish/subscribe messaging.
There are also a number of reasons not to make SYSTEM.DEFAULT.TOPIC a cluster topic: it is present on
all queue managers in a cluster, so it only affects the local queue manager, and all topics defined while it
is a cluster topic also become cluster topics in the same cluster.

About this task

To create a new cluster topic in the IBM MQ Explorer Navigator view, complete the following steps:

Procedure
1. Expand the cluster queue manager in which you want to create a new cluster topic.
2. In the navigation pane, select Topics.
A list of existing topics is displayed in the main pane.
3. Either select an existing topic, or create a new topic.
• To select an existing topic, double-click the topic in the main pane.
• To create a new topic, right-click Topics in the navigation pane, then select New > Topic. For more
information, see “Creating a new topic” on page 100.
4. In the properties pane, click Cluster to open the Cluster properties page.
5. Type the name of the cluster you want the topic to belong to in the Cluster topic field.
6. Optional: For IBM MQ 8.0 and later versions, select the routing mechanism from the Cluster route
drop-down list.
The choices are as follows:
Direct
Messages published on one queue manager are sent directly from that queue manager to every
subscription on any other queue manager in the cluster.
Topic host
Messages published on one queue manager are sent from there to a queue manager that hosts the
definition of the topic. That topic host queue manager routes the message on to every subscription
on any other queue manager in the cluster.
7. Click Apply to save the change.

Results
The topic has now become a cluster topic.

Introduction to IBM MQ Explorer 101

 Related concepts
“Cluster topics” on page 17
Topics can be clustered in a similar manner to cluster queues, although an individual topic object can be a
member of only one cluster. A topic is made into a cluster topic by defining, on the topic object, the name
of the cluster that is to host the topic, and the cluster routing mechanism to use for publications on this
topic.
Related tasks
“Viewing the topic status” on page 102
A topic identifies what a publication is about. The topic status displays information about the topic, such
as publications and subscriptions.

Viewing the topic status

A topic identifies what a publication is about. The topic status displays information about the topic, such
as publications and subscriptions.

Before you begin

Before you start:
• Show the queue manager that hosts the Publish/Subscribe Engine.

About this task

To view the status of a topic in the IBM MQ Explorer:

Procedure
1. In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine, then click
the Topics folder. The existing topics on the Publish/Subscribe Engine are shown in the Content view.
2. In the Content view, right-click the topic that you want to view the status for, then click Status.

Results
The Status dialog opens. One pane of the Status dialog shows the Topic String tree structure. You can
expand and collapse the topic string to navigate the tree structure and display individual topic status.

What to do next
For information about topic names, topic strings, and topic properties, refer to the topics linked at the end
of this topic.
Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Creating a new topic” on page 100
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a publish/subscribe message.
Related reference
“Topic properties” on page 391
An IBM MQ topic is an IBM MQ object that identifies what a publication is about. You can set properties
for topics. Some topic properties are specific to z/OS topics. Also, there are some properties that you can
alter only while you are creating a topic. You cannot modify these properties after the IBM MQ topic has
been created.
“Topic status attributes” on page 532

102 IBM MQ Explorer

The status attributes of topics.

Sending and receiving test publications on a topic object folder

You can send (publish) and receive (subscribe to) test publications (messages) to check that your
Publish/Subscribe Engine network and topics work as intended. You can configure a publication so that
the Publish/Subscribe Engine retains a copy after publishing it to the subscribers. This enables new
subscribers to receive the publication even if they subscribed after it was published.

Before you begin

Before you start:
• Show the queue manager that hosts the Pub/Sub Engine.

About this task

To send and receive test publications for any topic:

Procedure
1. Subscribe to the topic that you want to test:
a) In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine.
b) Right-click the Topics folder, then click Test Subscription....
The Subscribe application opens.
c) Type a topic string in the Topic String field. The topic string must be the same name as the
publisher.
2. Publish a message to the same topic:
a) In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine.
b) Right-click the Topics folder, then click Test Publication....
The Publish Test Message application opens.
c) In the Topic field, type the name of the topic on which you want to publish the message.
You or another publisher can already be registered to publish on the topic, or you can enter a new
topic string. When you publish the message, you are automatically registered as a publisher on the
topic.
d) In the Message data field, type a message to send in the publication.
For example, type Hello, world!
e) Click Publish message to send the message to the Pub/Sub Engine.
The subscriber receives the message (the publication).
3. Start another instance of the Subscribe application.
The second Subscribe application does not receive the message that was published by the Publish
Test Message application because it was not subscribing to the topic at the time that the publication
was sent to the Publish/Subscribe Engine.
4. Unsubscribe the second Subscribe instance from the topic.
a) In the second Subscribe application, click Unsubscribe.
The second Subscribe application can no longer receive publications on that topic. The first
Subscribe application can still receive publications on that topic.
5. Publish a retained publication to the topic.
a) In the Publish Test Message application, select the Retained message check box.
b) Change the text in the Message data field.
For example, type Hi, I'm home.
c) Click Publish message.

Introduction to IBM MQ Explorer 103

 The retained publication is published to the Publish/Subscribe Engine. The first Subscribe
application receives the retained publication. The second Subscribe application does not receive
the publication because it is currently not subscribed.
6. Subscribe the second Subscribe application to the topic again:
a) In the second Subscribe application, click Subscribe.
The second Subscribe application is subscribed to the topic again and receives the retained
publication because the Publish/Subscribe Engine kept a copy of the retained publication.

Results
You have now published and subscribed to test publications, including retained publications.
Related concepts
“Publications” on page 19
Publications are messages that are sent by an application to the Publish/Subscribe Engine. The Publish/
Subscribe Engine then sends the messages on to any applications that have subscribed to receive the
messages.
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.

Sending and receiving test publications for specific topics

You can send (publish) and receive (subscribe to) test publications (messages) to check that your
Publish/Subscribe Engine network and topics work as intended. You can configure a publication so that
the Publish/Subscribe Engine retains a copy after publishing it to the subscribers. This enables new
subscribers to receive the publication even if they subscribed after it was published.

Before you begin

Before you start:
• Show the queue manager that hosts the Publish/Subscribe Engine.

About this task

To send and receive test publications for a specific topic:

Procedure
1. Subscribe to the topic that you want to test:
a) In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine.
b) Click the Topics folder.
All the topics display in the Content view.
c) Right-click a specific topic in the Content view, then click Test Subscription....
The Subscribe application opens.
2. Publish a message to the same topic:
a) In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine.
b) Click the Topics folder.
All the topics display in the Content view.
c) Right-click the a specific topic in the Content view, then click Test Publication....
The Publish Test Message application opens.
d) In the Message data field, type a message to send in the publication.
For example, type Hello, world!
e) Click Publish message to send the message to the Publish/Subscribe Engine.

104 IBM MQ Explorer

 The subscriber receives the message (the publication).
3. Start another instance of the Subscribe application.
The second Subscribe application does not receive the message that was published by the Publish
Test Message application because it was not subscribing to the topic at the time that the publication
was sent to the Publish/Subscribe Engine.
4. Unsubscribe the second Subscribe instance from the topic.
a) In the second Subscribe application, click Unsubscribe.
The second Subscribe application can no longer receive publications on that topic. The first
Subscribe application can still receive publications on that topic.
5. Publish a retained publication to the topic.
a) In the Publish Test Message application, select the Retained message check box.
b) Change the text in the Message data field.
For example, type Hi, I'm home.
c) Click Publish message.
The retained publication is published to the Publish/Subscribe Engine. The first Subscribe
application receives the retained publication. The second Subscribe application does not receive
the publication because it is currently not subscribed.
6. Subscribe the second Subscribe application to the topic again:
a) In the second Subscribe application, click Subscribe.
The second Subscribe application is subscribed to the topic again and receives the retained
publication because the Publish/Subscribe Engine kept a copy of the retained publication.

Results
You have now published and subscribed to test publications, including retained publications on a specific
topic.
Related concepts
“Publications” on page 19
Publications are messages that are sent by an application to the Publish/Subscribe Engine. The Publish/
Subscribe Engine then sends the messages on to any applications that have subscribed to receive the
messages.
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.

Viewing topic status for publishers

Each topic can have many properties and values associated with it. When a topic has been assigned as a
publisher, you can view its status, and edit the scheme to display the status information.

Before you begin

Before you start:
• Show the queue manager that hosts the Publish/Subscribe Engine.

About this task

To view the status of a topic object publisher:

Procedure
1. In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine, then click
the Topics folder.

Introduction to IBM MQ Explorer 105

 The existing topics on the Publish/Subscribe Engine are shown in the Content view.
2. In the Content view, right-click the topic that you want to view the publisher status for, then click
Topic Status - Publishers...

Results
The Status dialog opens displaying the status of the topic object publisher.

What to do next
You can edit the way the information is presented in the Status dialog. For more information, see the
following links.
Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
Related tasks
“Viewing topic status for subscribers” on page 106
Each topic can have many properties and values associated with it. When a topic has been assigned as a
subscriber, you can view its status, and edit the scheme to display the status information.
“Creating a scheme” on page 218
You can create schemes for most of the tables of data in IBM MQ Explorer.
“Editing an existing scheme” on page 219
You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.
“Copying an existing scheme” on page 220
If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.

Viewing topic status for subscribers

Each topic can have many properties and values associated with it. When a topic has been assigned as a
subscriber, you can view its status, and edit the scheme to display the status information.

Before you begin

The queue manager that hosts the Publish/Subscribe engine must be visible in the Navigator view. To
show the queue manager, follow the instructions in: “Showing or hiding a queue manager” on page 81

About this task

To view the status of a topic object subscriber:

Procedure
1. In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine, then click
the Topics folder.
The existing topics on the Publish/Subscribe Engine are shown in the Content view.

106 IBM MQ Explorer

2. In the Content view, right-click the topic that you want to view the subscriber status for, then click
Topic Status - Subscribers

Results
The Status dialog opens displaying the status of the topic object subscriber.

What to do next
You can edit the way the information is presented in the Status dialog. For more information, see the
following links.
Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
Related tasks
“Viewing topic status for publishers” on page 105
Each topic can have many properties and values associated with it. When a topic has been assigned as a
publisher, you can view its status, and edit the scheme to display the status information.
“Creating a scheme” on page 218
You can create schemes for most of the tables of data in IBM MQ Explorer.
“Editing an existing scheme” on page 219
You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.
“Copying an existing scheme” on page 220
If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.

Creating a new subscription

You can create a new subscription to subscribe to a topic for an IBM WebSphere MQ 7.0, or later, queue
manager.

About this task

To create a new subscription:

Procedure
1. In the Navigator view, expand the queue manager that you want to create a new subscription on.
2. Right-click the Subscriptions object-folder, then click New > Subscription....

Results
The New Subscription wizard opens. You can now work through the wizard to create a new subscription.
Related concepts
“Topics” on page 16

Introduction to IBM MQ Explorer 107

 A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Configuring publish/subscribe for IBM MQ queue managers” on page 99
In IBM MQ Explorer, you can configure IBM MQ queue managers as Publish/Subscribe Engines to route
messages between publishing applications and subscribing applications. To test your configurations, you
can register as a subscriber, and send and receive test publications if you are authorized to do so.
Related reference
“IBM MQ Explorer Navigator view” on page 285
The Navigator view in IBM MQ Explorer displays all of the IBM MQ objects that you can administer and
monitor in IBM MQ Explorer.

Viewing a list of subscribers

You can view a list of applications that are subscribed to topics on a Publish/Subscribe Engine, or a list of
applications that are subscribed to a specific topic.

About this task

To view a list of subscribers:

Procedure
In the Navigator view, expand the queue manager that hosts the Publish/Subscribe Engine which you
want to view the subscribers of, then click the Subscriptions object-folder.

Results
The existing subscriptions on the Publish/Subscribe Engine are shown in the Content view.
Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related reference
“IBM MQ Explorer Content view” on page 293
The Content view in IBM MQ Explorer displays information about objects and properties.
“IBM MQ Explorer Navigator view” on page 285
The Navigator view in IBM MQ Explorer displays all of the IBM MQ objects that you can administer and
monitor in IBM MQ Explorer.

Refreshing proxy subscriptions

You can refresh proxy subscriptions on an IBM MQ queue manager.

About this task

Refreshing proxy subscriptions resynchronizes all the proxy subscriptions with all other directly
connected queue managers in any cluster or hierarchy in which this queue manager is participating.
You must refresh the proxy subscriptions only in exceptional circumstances, for example, when the queue
manager is receiving subscriptions that it must not be sent, or not receiving subscriptions that it must
receive. The following list describes some of the exceptional reasons for refreshing proxy subscriptions:
• Disaster recovery.
• Problems that are identified in a queue manager error log where messages inform of the issuing of the
REFRESH QMGR TYPE(REPOS) command.

108 IBM MQ Explorer

• Operator errors, for example, issuing a DELETE SUB command on a proxy subscription.
Missing proxy subscriptions can be caused if the closest matching topic definition is specified with
Subscription scope set to Queue Manager or it has an empty or incorrect cluster name. Note
that Publication scope does not prevent the sending of proxy subscriptions, but does prevent
publications from being delivered to them.
Extraneous proxy subscriptions can be caused if the closest matching topic definition is specified with
Proxy subscription behavior set to Force.
Missing or extraneous proxy subscriptions that are due to configuration errors are not changed by issuing
a resynchronization. A resynchronization does resolve missing or extraneous publications as a result of
the exceptional reasons listed.
To refresh the proxy subscriptions of a queue manager:

Procedure
1. In the Navigator view, select the queue manager that you want refresh the proxy subscriptions of.
2. Right-click the queue manager, then click Publish/Subscribe > Refresh Proxy Subscriptions.

Results
The Refresh proxy subscriptions dialog opens. You can now click Yes to refresh the proxy subscriptions,
or click No to close the dialog.
Related concepts
“Subscriptions” on page 19
A subscription is a record that contains the information about the topic or topics that the subscriber
is interested in and wants to receive information about. Thus, the subscription information determines
which publications get forwarded to the subscriber. Subscribers can receive information from many
different publishers, and the information they receive can also be sent to other subscribers.
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Configuring publish/subscribe for IBM MQ queue managers” on page 99
In IBM MQ Explorer, you can configure IBM MQ queue managers as Publish/Subscribe Engines to route
messages between publishing applications and subscribing applications. To test your configurations, you
can register as a subscriber, and send and receive test publications if you are authorized to do so.
Related reference
“IBM MQ Explorer Navigator view” on page 285
The Navigator view in IBM MQ Explorer displays all of the IBM MQ objects that you can administer and
monitor in IBM MQ Explorer.

Creating a new Multicast communication information object

IBM MQ Multicast offers low latency, high fan out, reliable multicast messaging.

About this task

Multicast is more efficient that traditional unicast publish/subscribe messaging, and can be scaled to a
high number of subscribers. IBM MQ enables reliable Multicast messaging by using acknowledgments,
negative acknowledgments, and sequence numbers to achieve low latency messaging with high fan out.
IBM MQ Multicast's fair delivery enables near simultaneous delivery, ensuring that no recipient gains an
advantage. As IBM MQ Multicast uses the network to deliver messages, a publish/subscribe engine is not
needed to fan-out data. After a topic is mapped to a group address, there is no need for a queue manager

Introduction to IBM MQ Explorer 109

 as publishers and subscribers can operate in a peer-to-peer mode. This allows the load to be reduced on
queue manager servers, and the queue manager server is no longer a potential point of failure.
To create a new topic in the IBM MQ Explorer:

Procedure
1. Expand the queue manager that you want to host the multicast communication information object on
to display the object-folders in the Navigator view.
2. Right-click Communication Information, then click New > Multicast Communication Information.

Results
The Communication Information wizard opens. Work though the wizard to create a new communication
information object.
Related reference
“Multicast Communication Information object properties” on page 428
You can set properties for Multicast communication information objects.

Managing multi-instance queue managers

You must configure the IBM MQ Explorer to manage multi-instance queue managers using remote
connections.
Use the Queue Managers > Add Remote Queue Manager menu item to add connections to a multi-
instance queue manager. Alternatively, if you have already configured a remote connection to a queue
manager, right-click the remote queue manager node in the IBM MQ Explorer navigator, then click
Connection Details > Manage Instances to add, remove, test, and reorder connections.
You must connect all instances of a queue manager to its remote queue manager node, and then the node
is able to monitor the status of all the instances of the queue manager. You can see which instance is
currently active, and which instances are in standby or disconnected.
It is important that you test the connections to all the instances of the queue manager when they are
in standby and in active status. Ensure that the listener is running on both the active and the standby
instances of the queue manager. A standby-instance queue manager does not have access to the queue
manager file system, and does not automatically start listeners until it becomes active. To test the
connections of both active and standby instances, consider starting the listener for both instances from
the command line.
Do not start listeners manually when they are configured to start with the queue manager. This produces
errors when the queue manager starts because the listener service fails due to the port already being in
use.

Connecting directly to a multi-instance queue manager

Create direct remote connections to multiple instances of a queue manager to administer a multi-instance
queue manager using IBM MQ Explorer.
On the Specify new connection details page, you are asked to provide connection information for two
instances of the queue manager. Both these instances might be remote, or one might be local and one
remote. The IBM MQ Explorer creates a single remote queue manager node in the navigation tree to
represent both instances of the queue manager. You can see the overall status of the multi-instance
queue manager.
Once you have already created a remote queue manager node in the IBM MQ Explorer, you can use it to
add and remove additional instances of the queue manager. You cannot add additional queue manager
instances to a local queue manager node.
Before connecting to a multi-instance queue manager you need to create a multi-instance queue
manager.

110 IBM MQ Explorer

Related concepts
Creating a multi-instance queue manager
You cannot create all the instances of a multi-instance queue manager using the IBM MQ Explorer.
Deleting a multi-instance queue manager
The IBM MQ Explorer does not provide a means to delete all the instances of a multi-instance queue
manager.
Starting a multi-instance queue manager
You can start a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Stopping a multi-instance queue manager
You can stop a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Managing connections to multi-instance queue managers
You can manage the connections IBM MQ Explorer uses to connect to a queue manager for remote
administration. You need multiple connections to monitor the status of all the instances of a multi-
instance queue manager. You can also configure multiple connections to a single instance of a queue
manager to make remote administration more reliable.

Creating a multi-instance queue manager

You cannot create all the instances of a multi-instance queue manager using the IBM MQ Explorer.
To create a highly available multi-instance queue manager, first create a queue manager on one server
with shared data and log directories on a highly available network storage device on a different server,
and then add the queue manager definition stanza to the mqs.ini file on another server of the same
architecture, and running the same or later version of IBM MQ. The commands dspmqinf and addmqinf
help you copy the queue manager definition from the first to the second server without having to edit the
mqs.ini file manually.
For more information, see Multi-instance queue managers.
Related concepts
Connecting directly to a multi-instance queue manager
Create direct remote connections to multiple instances of a queue manager to administer a multi-instance
queue manager using IBM MQ Explorer.
Deleting a multi-instance queue manager
The IBM MQ Explorer does not provide a means to delete all the instances of a multi-instance queue
manager.
Starting a multi-instance queue manager
You can start a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Stopping a multi-instance queue manager
You can stop a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Managing connections to multi-instance queue managers
You can manage the connections IBM MQ Explorer uses to connect to a queue manager for remote
administration. You need multiple connections to monitor the status of all the instances of a multi-

Introduction to IBM MQ Explorer 111

 instance queue manager. You can also configure multiple connections to a single instance of a queue
manager to make remote administration more reliable.

Deleting a multi-instance queue manager

The IBM MQ Explorer does not provide a means to delete all the instances of a multi-instance queue
manager.
To delete a multi-instance queue manager, you should delete the queue manager from one server, and
then use the rmvmqinf command to remove the queue manager definitions from other servers.
For more information, see Multi-instance queue managers.
Note: If you delete the queue manager again, but on another server that has the same queue manager
defined, the dltmqm command fails. If you do try to delete a queue manager on a server that had a queue
manager definition, but no queue manager, delete the queue manager again on the same server, and the
queue manager is completely removed.
Related concepts
Connecting directly to a multi-instance queue manager
Create direct remote connections to multiple instances of a queue manager to administer a multi-instance
queue manager using IBM MQ Explorer.
Creating a multi-instance queue manager
You cannot create all the instances of a multi-instance queue manager using the IBM MQ Explorer.
Starting a multi-instance queue manager
You can start a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Stopping a multi-instance queue manager
You can stop a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Managing connections to multi-instance queue managers
You can manage the connections IBM MQ Explorer uses to connect to a queue manager for remote
administration. You need multiple connections to monitor the status of all the instances of a multi-
instance queue manager. You can also configure multiple connections to a single instance of a queue
manager to make remote administration more reliable.

Starting a multi-instance queue manager

You can start a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
As a single-instance queue manager
Do not check the Permit a standby instance check box.
As a multi-instance queue manager
Start the first instance, checking the Permit a standby instance check box, then start the second
instance, also checking the Permit a standby instance check box.
Note: You cannot use a remotely connected queue manager to start a multi-instance queue manager.
Related concepts
Connecting directly to a multi-instance queue manager
Create direct remote connections to multiple instances of a queue manager to administer a multi-instance
queue manager using IBM MQ Explorer.
Creating a multi-instance queue manager
You cannot create all the instances of a multi-instance queue manager using the IBM MQ Explorer.
Deleting a multi-instance queue manager

112 IBM MQ Explorer

The IBM MQ Explorer does not provide a means to delete all the instances of a multi-instance queue
manager.
Stopping a multi-instance queue manager
You can stop a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Managing connections to multi-instance queue managers
You can manage the connections IBM MQ Explorer uses to connect to a queue manager for remote
administration. You need multiple connections to monitor the status of all the instances of a multi-
instance queue manager. You can also configure multiple connections to a single instance of a queue
manager to make remote administration more reliable.

Stopping a multi-instance queue manager

You can stop a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Stop all instances of the queue manager
Do not check the Allow switchover to standby instance check box.
Stop this instance of the queue manager, switching over to a standby instance
Check the Allow switchover to standby instance check box. If there is no standby instance running
the command fails and leaves the queue manager running.
Note: You cannot use a remotely connected queue manager to stop a multi-instance queue manager.
Related concepts
Connecting directly to a multi-instance queue manager
Create direct remote connections to multiple instances of a queue manager to administer a multi-instance
queue manager using IBM MQ Explorer.
Creating a multi-instance queue manager
You cannot create all the instances of a multi-instance queue manager using the IBM MQ Explorer.
Deleting a multi-instance queue manager
The IBM MQ Explorer does not provide a means to delete all the instances of a multi-instance queue
manager.
Starting a multi-instance queue manager
You can start a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Managing connections to multi-instance queue managers
You can manage the connections IBM MQ Explorer uses to connect to a queue manager for remote
administration. You need multiple connections to monitor the status of all the instances of a multi-
instance queue manager. You can also configure multiple connections to a single instance of a queue
manager to make remote administration more reliable.

Managing connections to multi-instance queue managers

You can manage the connections IBM MQ Explorer uses to connect to a queue manager for remote
administration. You need multiple connections to monitor the status of all the instances of a multi-
instance queue manager. You can also configure multiple connections to a single instance of a queue
manager to make remote administration more reliable.
The queue manager instances must share the same queue manager data; either by configuring multiple
connections to the same queue manager on a single server, or by configuring connections to multiple
instances of the same queue manager on different servers.
You cannot remove the active connection, which IBM MQ Explorer is using.
Click Test connections to refresh the status of the connections.

Introduction to IBM MQ Explorer 113

 To connect to a standby queue manager instance you must have configured a listener process to be
running while the queue manager is in standby status. For example, set the listener CONTROL to Queue
Manager or Queue Manager Start.
Related concepts
Connecting directly to a multi-instance queue manager
Create direct remote connections to multiple instances of a queue manager to administer a multi-instance
queue manager using IBM MQ Explorer.
Creating a multi-instance queue manager
You cannot create all the instances of a multi-instance queue manager using the IBM MQ Explorer.
Deleting a multi-instance queue manager
The IBM MQ Explorer does not provide a means to delete all the instances of a multi-instance queue
manager.
Starting a multi-instance queue manager
You can start a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.
Stopping a multi-instance queue manager
You can stop a multi-instance queue manager in two ways from a local queue manager in the IBM MQ
Explorer.

Creating and configuring a queue manager cluster

A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.

About this task

Since the queue managers in a cluster are logically associated and can share information with each
other, this means that an application can put a message on a cluster queue from any queue manager in
the cluster and the message is automatically routed to the queue manager where the cluster queue is
defined. The amount of system administration is reduced because the cluster channels that the cluster
queue managers use to exchange application messages are automatically defined as required.
IBM MQ Explorer provides wizards to help you to create and configure queue manager clusters and
objects.
You cannot use the wizards to manage queue managers and objects that belong to more than one cluster
(and, therefore, use namelists). However, you can still use the IBM MQ Explorer properties dialogs to edit
the properties of the queue managers and objects if you want them to belong to more than one cluster.
The following topics describe how to create and configure queue manager clusters in IBM MQ Explorer:
• “Creating a queue manager cluster” on page 115
• “Adding a queue manager to a cluster” on page 116
• “Removing a queue manager from a cluster” on page 117
• “Suspending the cluster membership of a queue manager” on page 118
• “Resuming the cluster membership of a queue manager” on page 119
• “Refreshing locally held information about a cluster” on page 119
• “Specifying a different cluster information source for IBM MQ Explorer ” on page 120
• “Cluster repositories” on page 121
• “Making a queue manager a full repository for more than one cluster” on page 122
• “Sharing a queue in a cluster” on page 123
• “Connecting to a remote cluster queue manager” on page 124
• “Administering a remote cluster queue manager” on page 124

114 IBM MQ Explorer

For more information, see Distributed queuing and clusters.
Related concepts
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.

Creating a queue manager cluster

IBM MQ Explorer treats queue manager clusters as objects so that you can create and administer them
like other MQ objects.

About this task

All the queue manager clusters that are known to IBM MQ Explorer are displayed in the Queue Manager
Clusters folder.
Before you can create a new queue manager cluster:
• Create two queue managers that will have the full repositories for the cluster.
• Each full repository queue manager in the cluster must have a running listener.
• You must know the connection details of each full repository queue manager in the cluster because you
are asked to enter these details in the wizard.
Note: You cannot use the Create Cluster wizard if the full repository queue managers already belong to
another cluster. If you want to use queue managers that already belong to another cluster, you must
configure the cluster using the MQSC commands.
To create a new cluster, complete the following steps.

Procedure
1. In the Navigator view, right-click the Queue Manager Clusters folder, then click New... The Create
Cluster wizard opens.
2. Work through the pages in the wizard to enter the following information about the new cluster:
a) Page 1: The name of the new cluster. This name must be unique in your organization.
b) Page 2: The name of a queue manager that will have a full repository of information about the
cluster. The queue manager must already exist; click Add queue manager to MQ Explorer if the
queue manager is not already known to IBM MQ Explorer.
c) Page 3: The name of a second queue manager that will have a full repository of information about
the cluster. The queue manager must already exist; click Add queue manager to MQ Explorer if the
queue manager is not already known to IBM MQ Explorer.
d) Page 4: The connection name of the first full repository queue manager. The format of the
connection name depends on the transport protocol that the queue manager uses. For example, if
the queue manager uses TCP/IP, you can use the format computer_name(port_number) where
computer_name is the name of the computer that hosts the queue manager, and port_number is
the port number on which the queue manager listens for connections.
3. Click Finish to create the cluster.

Results
The new cluster is displayed in the Queue Manager Clusters folder. The cluster's full repositories are
shown in its Full Repositories folder.

Introduction to IBM MQ Explorer 115

 For more information, see Distributed queuing and clusters and Administering IBM MQ using MQSC
commands.
Related concepts
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.
“Cluster repositories” on page 121
A cluster repository contains information about the cluster; for example, information about the queue
managers that are members of the cluster, and the cluster channels. Repositories are hosted by the
queue managers in the cluster.
Related tasks
“Adding a queue manager to a cluster” on page 116
You can use IBM MQ Explorer to add a queue manager to a cluster as either a full repository or a partial
repository.

Adding a queue manager to a cluster

You can use IBM MQ Explorer to add a queue manager to a cluster as either a full repository or a partial
repository.

About this task

This task shows how to add a queue manager to an existing cluster using the Create Cluster wizard in IBM
MQ Explorer. You can use the wizard to add a queue manager, provided that the queue manager does not
already belong to another cluster.
Although you can add any queue manager to an existing cluster, even if the queue manager already
belongs to another cluster, you cannot use the Create Cluster wizard if the queue manager already
belongs to another cluster. You must configure the cluster using MQSC commands.
Before you can add a queue manager to a cluster:
• Create the queue manager.
• The queue manager must have a running listener.
• You must know the connection details of the queue manager because the you are asked to enter these
details in the wizard.
To add a queue manager to a cluster:

Procedure
1. In the Navigator view, right-click the cluster, then click Add queue manager to cluster The Create
Cluster wizard opens.
2. Work through the pages in the wizard to enter the following information about the queue manager:
a) Page 1: The name of the queue manager. The queue manager must already exist; click Add queue
manager to MQ Explorer if the queue manager is not already known to IBM MQ Explorer.
b) Page 2: Whether the queue manager will be a full repository or a partial repository for the cluster.
c) Page 3: The connection name of the queue manager. The format of the connection name depends
on the transport protocol that the queue manager uses. For example, if the queue manager uses
TCP/IP, you can use the format computer_name(port_number) where computer_name is the
name or IP address of the computer that hosts the queue manager, and port_number is the port
number on which the queue manager listens for connections.

116 IBM MQ Explorer

 d) Page 4: If the queue manager will be a partial repository, select one or more full repository queue
managers to which the partial repository queue manager will send information about the cluster.
e) Page 5: If the queue manager will be a partial repository, select the cluster-receiver channel that
the full repository queue manager will use to receive information from the partial repository queue
manager.
f) Page 6: Using the list, specify a cluster-sender channel on each full repository queue manager that
they will use to send cluster information to the new repository queue manager.
3. Click Finish to add the queue manager the cluster.

Results
The queue manager is added to the cluster as a full repository or a partial repository. The queue manager
is displayed in the Full Repository folder or the Partial Repository folder for the cluster.
For more information, see Distributed queuing and clusters and Administering IBM MQ using MQSC
commands.
Related concepts
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.
“Cluster repositories” on page 121
A cluster repository contains information about the cluster; for example, information about the queue
managers that are members of the cluster, and the cluster channels. Repositories are hosted by the
queue managers in the cluster.
Related tasks
“Creating a queue manager cluster” on page 115
IBM MQ Explorer treats queue manager clusters as objects so that you can create and administer them
like other MQ objects.

Removing a queue manager from a cluster

If you no longer want a queue manager to be a member of a cluster, you can use IBM MQ Explorer to
remove the queue manager from the cluster.

About this task

When you remove the queue manager from the cluster using IBM MQ Explorer, the queue manager's
properties are updated; the table on the Cluster page of the queue manager's properties dialog is
updated, and if the queue manager was a full repository for the cluster, the attributes on the Repository
page of the queue manager's properties dialog are also updated.
When you remove a queue manager from a cluster, the queue manager's cluster queues and cluster
channels are no longer available to applications using the cluster.
Note that if the queue manager belongs to more than one cluster (using namelists), you cannot remove
a queue manager from a cluster using the following instructions; you must manually edit the queue
manager's properties.
To remove a queue manager from a cluster:

Procedure
1. In the Navigator view (in the Queue Manager Clusters folder), expand the cluster from which the
queue manager is currently suspended.

Introduction to IBM MQ Explorer 117

 2. Right-click the queue manager, the click Remove queue manager from cluster...
3. When you are prompted, click Yes.

Results
The queue manager is removed from the cluster and the queue manager's properties are updated.
Related tasks
“Suspending the cluster membership of a queue manager” on page 118
If a queue manager is a member of a cluster but you want to temporarily prevent the queue manager
sharing its cluster queues and exchanging messages using the cluster, you can use IBM MQ Explorer
to suspend the queue manager from the cluster. You can later easily resume the queue manager's
membership of the cluster.
“Adding a queue manager to a cluster” on page 116
You can use IBM MQ Explorer to add a queue manager to a cluster as either a full repository or a partial
repository.
“Creating and configuring a queue manager cluster” on page 114
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.
Removing a queue manager from a cluster: best practice
Removing a queue manager from a cluster: alternative method

Suspending the cluster membership of a queue manager

If a queue manager is a member of a cluster but you want to temporarily prevent the queue manager
sharing its cluster queues and exchanging messages using the cluster, you can use IBM MQ Explorer
to suspend the queue manager from the cluster. You can later easily resume the queue manager's
membership of the cluster.

About this task

To suspend a queue manager without using IBM MQ Explorer, see Suspend Cluster Queue Manager
(SPDMQMCLQM).
To suspend a queue manager from a cluster, in the Navigator view (in the Queue Manager Clusters
folder), right-click the queue manager, and then click Suspend cluster membership....
The queue manager is suspended from the cluster and its icon is decorated to show this.
For more information, see Distributed queuing and clusters.
Related tasks
“Resuming the cluster membership of a queue manager” on page 119
If you previously suspended a queue manager's membership of a cluster, but then want to resume the
queue manager's membership, you can use IBM MQ Explorer to do this without having to re-enter the
queue manager's connection details.
“Removing a queue manager from a cluster” on page 117
If you no longer want a queue manager to be a member of a cluster, you can use IBM MQ Explorer to
remove the queue manager from the cluster.
“Creating and configuring a queue manager cluster” on page 114

118 IBM MQ Explorer

A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.

Resuming the cluster membership of a queue manager

If you previously suspended a queue manager's membership of a cluster, but then want to resume the
queue manager's membership, you can use IBM MQ Explorer to do this without having to re-enter the
queue manager's connection details.

About this task

If you have suspended the cluster membership of a queue manager, the queue manager is unable to
exchange messages using the cluster, and the queue manager's cluster queues are unavailable to the
other queue managers in the cluster. You can easily resume the queue manager's cluster membership
without having to enter the queue manager's connection details again.
For more information, see Distributed queuing and clusters.
To resume the cluster membership of a queue manager:

Procedure
In the Navigator view (in the Queue Manager Clusters folder), right-click the queue manager, then click
Resume cluster membership...

Results
The queue manager is an active member of the cluster again and any decoration is removed from the
queue manager's icon to show this.
Related tasks
“Suspending the cluster membership of a queue manager” on page 118
If a queue manager is a member of a cluster but you want to temporarily prevent the queue manager
sharing its cluster queues and exchanging messages using the cluster, you can use IBM MQ Explorer
to suspend the queue manager from the cluster. You can later easily resume the queue manager's
membership of the cluster.
“Creating and configuring a queue manager cluster” on page 114
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.

Refreshing locally held information about a cluster

You are unlikely to need to refresh (discard) all locally held information about a cluster in normal
circumstances but you might be asked to do this by your IBM Support Center.

Before you begin

For large clusters, use of the REFRESH CLUSTER command can be disruptive to the cluster while it is
in progress, and again at 27 day intervals thereafter when the cluster objects automatically send status
updates to all interested queue managers. See Clustering: Using REFRESH CLUSTER best practices.

Procedure
1. In the Navigator view (in the Queue Manager Clusters folder), right-click the queue manager, the click
Refresh cluster membership... The Refresh Cluster Queue Managers dialog opens.
2. Select the scope of the refresh:

Introduction to IBM MQ Explorer 119

 • To refresh all of the queue manager's information about the cluster except for the following
information, click Refresh cluster:
– The queue manager's knowledge of all cluster queue managers and cluster queues that are
locally defined is retained.
– The queue manager's knowledge of all cluster queue managers that are full repositories is
retained.
– If the queue manager is a full repository, knowledge of the other cluster queue managers in the
cluster is retained. Everything else is removed from the local copy of the repository and is rebuilt
from the other full repositories in the cluster.
In addition, to specify that objects representing full repository cluster queue managers are also
refreshed, select Clear repository information. This option is available only to partial repository
queue managers. You can, however, temporarily configure a full repository to be a partial repository
so that you can refresh its repository too.
• To refresh the queue manager in all of the clusters to which it belongs, click Refresh all clusters.
In addition, to force the queue manager to restart its search for full repositories from the
information in the local cluster-sender channel definitions, even if the cluster-sender channel
connects the queue manager to several clusters, select Clear repository information.
3. Click OK.

Results
The queue manager's information about the cluster, or clusters, is refreshed.
For more information, see Distributed queuing and clusters.
Related concepts
Clustering: Using REFRESH CLUSTER best practices
Related tasks
“Creating and configuring a queue manager cluster” on page 114
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.

Specifying a different cluster information source for IBM MQ Explorer

You can change the full repository queue manager from which IBM MQ Explorer obtains information about
which queue managers belong to a cluster.

About this task

For each cluster, IBM MQ Explorer obtains information from one of the cluster's full repository queue
managers about which queue managers belong to the cluster. You can change the IBM MQ Explorer
information source by specifying a different full repository queue manager that belongs to the same
cluster.
To specify a different full repository queue manager, complete the following steps.

Procedure
1. In the Navigator view, click the cluster. The Content view displays the name of the full repository
queue manager that is currently the information source.
2. In the Content view, click Select... A dialog opens.
3. From the list, select a full repository queue manager, then click Finish.

120 IBM MQ Explorer

Results
The Content view now displays the name of the queue manager that you selected. IBM MQ Explorer
updates its information about the cluster from the full repository queue manager specified.
For more information, see Distributed queuing and clusters.
Related concepts
“Cluster repositories” on page 121
A cluster repository contains information about the cluster; for example, information about the queue
managers that are members of the cluster, and the cluster channels. Repositories are hosted by the
queue managers in the cluster.
Related tasks
“Creating and configuring a queue manager cluster” on page 114
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.

Cluster repositories
A cluster repository contains information about the cluster; for example, information about the queue
managers that are members of the cluster, and the cluster channels. Repositories are hosted by the
queue managers in the cluster.
Normally, to ensure availability, two queue managers (on different computers) host full repositories,
which contain a complete set of information about the cluster and its resources. The two queue managers
exchange messages to keep their repositories synchronized. All the other queue managers in the cluster
host partial repositories, which contain an incomplete set of information about the cluster and its
resources.
A queue manager's partial repository contains only information about the queue managers with which
the queue manager needs to exchange messages. The queue manager requests updates from the full
repositories so that if the information changes, the full repository queue managers sends them the new
information. For much of the time a queue manager's partial repository has all the information it needs to
perform within the cluster. When a queue manager needs some additional information, it makes inquiries
of the full repository and updates its partial repository.
Two special types of channel are used by each queue manager for this purpose, one each of cluster-
sender (CLUSSDR) and cluster-receiver (CLUSRCVR).

DHCP
If a computer uses DHCP (dynamic allocation of IP address), you are recommended to define the
repository's Connection name attribute using the computer's name instead of the computer's IP
address. This is because the connection name is used to find the repository. If the computer's IP address
is used and the IP address subsequently changes, other queue managers will no longer be able to find
the repository. This still applies even if all the queue managers in the cluster are on the same computer,
because the IP address is still used to find the repository.
Related concepts
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.
“Channels” on page 20

Introduction to IBM MQ Explorer 121

 IBM MQ can use three different types of channels: a message channel, an MQI channel, and an AMQP
channel.

Making a queue manager a full repository for more than one cluster
A queue manager can be a full repository for more than one cluster at the same time.

About this task

If you want a queue manager to be a full repository for more than one cluster, you must create a namelist
for the queue manager and list the names of the clusters in the namelist. The Create Cluster wizard does
not edit namelists so you must manage multiple clusters manually in IBM MQ Explorer.
To make a queue manager a full repository for more than one cluster, complete the following steps.

Procedure
1. Create a new namelist for the queue manager.
2. Open the new namelist's Properties dialog and edit the namelist:
a) On the General page of the Properties dialog, in the Names field, click Edit. The Edit Names dialog
opens.
b) Click Add The Add to Names dialog opens.
c) In the Add to Names dialog, type the name of a cluster for which you want the queue manager to
be a full repository, then click OK.
d) Add the name of each cluster for which you want the queue manager to be a full repository.
e) In the Edit Names dialog, click OK to return to the Properties dialog.
f) Click OK to apply the changes and close the Properties dialog.
3. Open the queue manager's Properties dialog and specify the namelist:
a) On the Repository page of the Properties dialog, click Repository for a list a clusters, then type
the name of the namelist in the field.
b) Click OK to apply the changes and close the Properties dialog.

Results
The queue manager is added to the Full Repository folder of the clusters that are listed in the namelist.
Any of the clusters that were not previously shown in the Queue Manager Clusters folder are shown now.
Related concepts
“Namelists” on page 25
A namelist is an IBM MQ object that contains a list of names of other objects.
Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Configuring queue managers and objects” on page 37

122 IBM MQ Explorer

You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

Sharing a queue in a cluster

A queue manager that belongs to a cluster can share one or more of its queues with all the other
members of the cluster.

About this task

Before you can share a queue in a cluster:
• The queue manager that owns the queue must be a member of the cluster.
• The queue manager's membership of the cluster must not be suspended.
To share a queue in a cluster, complete the following steps.

Procedure
1. In the Navigator view, click the queue manager's Queues folder. The queue manager's queues are
displayed in the Content view.
2. In the Content view, right-click the queue that you want to share, then click Properties... The queue's
Properties dialog opens.
3. On the Cluster page of the Properties dialog, click Shared in cluster, then type the name of the cluster
in which you want to share the queue. If the queue is already shared in a cluster or if you want to
share the queue in more than one cluster, click Shared in a list of clusters, then type the name of the
namelist that contains the list of clusters.
4. Click OK to apply the changes.

Results
The queue is now available to all the queue managers in the cluster or clusters in which the queue is
shared.
Related concepts
“Namelists” on page 25
A namelist is an IBM MQ object that contains a list of names of other objects.
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.
Related tasks
“Creating a queue manager cluster” on page 115
IBM MQ Explorer treats queue manager clusters as objects so that you can create and administer them
like other MQ objects.
“Adding a queue manager to a cluster” on page 116
You can use IBM MQ Explorer to add a queue manager to a cluster as either a full repository or a partial
repository.
“Resuming the cluster membership of a queue manager” on page 119

Introduction to IBM MQ Explorer 123

 If you previously suspended a queue manager's membership of a cluster, but then want to resume the
queue manager's membership, you can use IBM MQ Explorer to do this without having to re-enter the
queue manager's connection details.

Connecting to a remote cluster queue manager

You can connect IBM MQ Explorer to a remote queue manager by using the cluster information source as
an intermediary queue manager.

About this task

If a remote queue manager belongs to a cluster that is displayed in IBM MQ Explorer but IBM MQ
Explorer does not know anything about the queue manager, the queue manager's icon shows that it is not
connected. For IBM MQ Explorer to get information about the remote queue manager, it must connect to
the queue manager. Of course, if you don't know the connection details of the queue manager, you cannot
easily add it to the Queue Managers folder, and you might not want to be able to administer the queue
manager anyway. Therefore, you can connect IBM MQ Explorer to the remote queue manager using the
cluster information source as an intermediary queue manager.
For example, if QMX is the full repository queue manager from which IBM MQ Explorer obtains all its
information about the cluster, you can connect to QMZ, the remote cluster queue manager, using QMX as
an intermediary queue manager. This means that IBM MQ Explorer does not need to know the connection
details of the remote cluster queue manager because QMX, the cluster's full repository queue manager,
already has this information.
When IBM MQ Explorer is connected to the remote cluster queue manager, if you want to administer the
remote cluster queue manager, you can then show the queue manager in the Queue Managers folder.
To connect to a remote cluster queue manager, in the Navigator view (in the Queue Manager Clusters
folder), right-click the queue manager, and then click Connect to queue manager.
IBM MQ Explorer connects to the remote cluster queue manager using the full repository queue manager
that is IBM MQ Explorer’s information source about the cluster. Click the queue manager to display its
cluster queues and cluster channels in the Content view.
For more information, see Distributed queuing and clusters.
Related tasks
“Creating and configuring a queue manager cluster” on page 114
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. You can use the wizards and properties dialogs in IBM MQ Explorer to create
and configure queue manager clusters.

Administering a remote cluster queue manager

After connecting IBM MQ Explorer to a remote cluster queue manager using the cluster information
source as an intermediate queue manager, you can select to show the queue manager in the Queue
Managers folder. You can use then use the connection to administer the remote queue manager.

Before you begin

If a cluster queue manager is not shown in the Queue Managers folder, the cluster queue manager is
shown in the Queue Manager Clusters folder as being disconnected. You can connect to the remote
cluster queue manager using the cluster information source as an intermediate queue manager. When
the remote cluster queue manager is connected to IBM MQ Explorer, you can use that connection to
administer the queue manager but you must first show the queue manager in the Queue Managers folder.

About this task

To administer a remote cluster queue manager in IBM MQ Explorer:

124 IBM MQ Explorer

 Procedure
1. Ensure that the remote cluster queue manager is connected to IBM MQ Explorer. For more
information, see Connecting to a remote cluster queue manager.
2. Right-click the queue manager, then click Show in Queue Managers folder.

Results
The queue manager is added to the Queue Managers folder and you can now administer it like any other
remote queue manager.
“Connecting to a remote cluster queue manager” on page 124
You can connect IBM MQ Explorer to a remote queue manager by using the cluster information source as
an intermediary queue manager.
“Specifying a different cluster information source for IBM MQ Explorer ” on page 120
You can change the full repository queue manager from which IBM MQ Explorer obtains information about
which queue managers belong to a cluster.
“Administering remote queue managers” on page 92
In IBM MQ Explorer, you can enable IBM MQ queue managers on a remote computer for remote
administration.
“Queue manager clusters” on page 33
A cluster is a group of two or more queue managers that are logically associated and can share
information with each other. Any queue manager can send a message to any other queue manager in
the same cluster without you needing to set up a specific channel definition, remote queue definition, or
transmission queue, because all of this information is held in the repository, to which all queue managers
in the cluster have access.

Managing security and authorities

The security provisions in IBM MQ include securing channels using Transport Layer Security (TLS) and
controlling access to IBM MQ objects.

About this task

You can manage both TLS security and object authorities in IBM MQ Explorer. For more information see:
• “Securing channels with TLS” on page 126
• “Managing object authorities with an authorization service” on page 135
For more information about TLS, object authorities, and other ways of securing your IBM MQ queue
manager network, see Securing.
Related tasks
“Authorizing users to configure IBM MQ on Windows and Linux (x86 and x86-64 platforms)” on page 166
IBM MQ uses the normal user and group authorizations to protect IBM MQ applications and IBM MQ
administration.
“Refreshing the authorization service information on Multiplatforms” on page 167
On Multiplatforms, if you make a change to an entity, you must refresh the entity information in the
authorization service. You must do this for each queue manager that is affected by the changes that you
make to the entity.
“Refreshing TLS security” on page 168
You can make changes to the key repository without restarting a channel. However, the copy of the key
repository that is held in memory while a channel is running will not be affected. When you refresh the
cached copy of the key repository, the TLS channels that are currently running on the queue manager are
updated with the new information.
“Refreshing ESM classes (z/OS only)” on page 170

Introduction to IBM MQ Explorer 125

 IBM MQ for z/OS does not perform any authority checks itself; instead, it routes requests for authority
checks to an external security manager (ESM).

Securing channels with TLS

The TLS (Transport Layer Security) protocol enables queue managers to communicate securely with other
queue managers, or clients.

About this task

TLS Concepts
An TLS-enabled connection is secure in the following ways:
• Authentication: Queue managers or clients initiating an TLS-enabled connection are assured of the
identity of the queue manager that they are connecting to, and queue managers that are receiving
connections can check the identity of the queue manager or client that is initiating the connection.
• Message privacy: Using a unique session key, TLS, if configured to do so, encrypts all information
exchanged over the connection. This ensures that information cannot be viewed if it is intercepted by
unauthorized parties.
• Message integrity: The data cannot be tampered with over the connection.
• Certificate Authority chain: Each certificate in the Certificate Authority (CA) chain is signed by the
entity that is identified by its parent certificate in the chain. At the head of the chain is the root CA
certificate. The root certificate is always signed by the root CA itself. The signatures of all certificates in
the chain must be verified.
Sequence overview
There are two stages to the security, as described in the following steps.

Procedure
1. When a queue manager connects to another queue manager, the two carry out a standard TLS
exchange of certificates, and carry out validation checks. If the validation is successful, the connection
is established. To achieve this, you must configure both of your queue managers, and the channels that
they will use, with appropriate certificate settings.
2. When messages are sent from one queue manager to another queue manager along a channel,
the data is generally encrypted using a session key that has been established during the certificate
exchange. To achieve this you must configure the channels that you will use with appropriate
CipherSpecs.

Results
Sequence Details
A typical sequence for a simple TLS connection between queue managers QM1 and QM2 is as follows:
1. QM1 connects to QM2.
2. The personal certificate that is used by QM2 is sent to QM1.
3. QM1 authenticates the personal certificate against the chain of certificate authority certificates.
4. QM1 optionally checks for certificate revocation if Online Certificate Status Protocol (OCSP) is
supported on the server platform. For more information on OCSP see: “Working with Online Certificate
Status Protocol (OCSP)” on page 27.
5. QM1 optionally checks the personal certificate against the Certificate Revocation List (CRL). For more
information see: “Configuring TLS on queue managers” on page 129.
6. QM1 optionally applies a filter to only accept personal certificates that meet any defined peer names.
For more information see: “Configuring TLS channels” on page 131.
7. QM1 (if all is well) accepts the personal certificate from QM2.

126 IBM MQ Explorer

8. The secure connection is now established.
For more security, QM2 can request a certificate from QM1, and in that case the following steps also take
place:
1. QM1 sends its assigned personal certificate to QM2.
2. QM2 applies the same checks (Steps 3, 4, and 5) as previously shown.
3. QM2, if all is well, accepts the personal certificate from QM1.
The secure connection is now established.
For more information, see Securing.
Related tasks
“Configuring TLS security for IBM MQ” on page 127
To configure TLS security, you set up TLS on each queue manager and each client that uses TLS-enabled
connections.
“Configuring TLS on queue managers” on page 129
After starting the IBM strmqikm (iKeyman) GUI, you can use it to manage TLS certificates. You can also
authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.
Related reference
“Authentication information properties” on page 420
You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.

Configuring TLS security for IBM MQ

To configure TLS security, you set up TLS on each queue manager and each client that uses TLS-enabled
connections.

About this task

For an introduction, and details on how certificates are used to establish TLS connections, see Using SSL
security with IBM MQ.
Setting up TLS on a queue manager
To set up TLS on a queue manager, for each queue manager that uses TLS-enabled connections:

Procedure
1. Manage the digital certificates that are used by the queue manager. For more information, see
Managing SSL certificates.
2. Configure the queue manager for TLS-enabled messaging. For more information, see Configuring SSL
on queue managers.
3. Configure channels to support secure messaging using TLS. For more information, see Configuring SSL
channels.

Results
Setting up TLS on an IBM MQ MQI client
To set up TLS on an IBM MQ client, for each client that uses TLS-enabled connections:
1. Manage the digital certificates that are used by the client. For more information, see Managing SSL
certificates.
2. Configure the client for TLS-enabled messaging. For more information, see Configuring SSL on IBM MQ
clients.

Introduction to IBM MQ Explorer 127

 3. Configure the client channel definition to support secure messaging using TLS. For more information,
see Configuring SSL on IBM MQ clients.
For more information, see Securing.

Managing TLS certificates

To manage the TLS certificates on your local computer using a GUI, use the IBM strmqikm command
(iKeyman).

About this task

The information in this task applies to managing TLS certificates on a local computer.
Note that you cannot manage TLS certificates on remote computers using strmqikm.
To work with a personal certificate with strmqikm, you must complete the following steps.

Procedure
1. Create a key database file in the location that is specified in the queue manager's Key repository
attribute.
2. Request and obtain from a Certificate Authority (CA) a personal certificate with the correct label and its
full chain of CA certificates back to the Root certificate.
3. Add all the certificates, in the correct order, to the key repository of the queue manager using
strmqikm.

Results
For instructions on how to use strmqikm, and for more information about security, see Securing.
Related tasks
“Invoking the IBM strmqikm (iKeyman) GUI” on page 128
To manage your TLS certificates using the IBM the strmqikm (iKeyman) GUI, you must first open
strmqikm from IBM MQ Explorer.
“Configuring TLS security for IBM MQ” on page 127
To configure TLS security, you set up TLS on each queue manager and each client that uses TLS-enabled
connections.
Related reference
“Queue manager properties” on page 315
You can set properties for both local and remote queue managers.

Invoking the IBM strmqikm (iKeyman) GUI

To manage your TLS certificates using the IBM the strmqikm (iKeyman) GUI, you must first open
strmqikm from IBM MQ Explorer.

About this task

strmqikm
To open strmqikm from IBM MQ Explorer, complete the following steps.

Procedure
1. Start IBM MQ Explorer.
2. In the Navigator view, right-click IBM MQ, then click Manage SSL Certificates...

128 IBM MQ Explorer

Results
The IBM strmqikm GUI opens.
Note that you cannot manage TLS certificates on remote computers using strmqikm.
For instructions on how to use strmqikm, and for more information about security, see Securing IBM MQ.
Related tasks
“Securing channels with TLS” on page 126
The TLS (Transport Layer Security) protocol enables queue managers to communicate securely with other
queue managers, or clients.

Configuring TLS on queue managers

After starting the IBM strmqikm (iKeyman) GUI, you can use it to manage TLS certificates. You can also
authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.

Before you begin

For more information on how to start the strmqikm GUI, see “Invoking the IBM strmqikm (iKeyman)
GUI” on page 128.

About this task

This task introduces the commands that you use to work with TLS on an IBM MQ client. For more
information, see Securing and Setting up IBM MQ MQI client security.
Complete any of the following tasks:
1. Create the queue manager key repository
2. Change the queue manager key repository location
3. Authenticate certificates using Certificate Revocation Lists
4. Authenticate certificates using OCSP authentication
5. Configure cryptographic hardware

Procedure
• [OPTION 1] Create the queue manager key repository
The key repository is where certificates used by the queue manager are stored. On AIX, Linux, and
Windows platforms, the key repository is known as the key database file.
Before you can store the queue manager certificates in the key repository, you must ensure that a key
database file exists in this location.
a) Find the location of the queue manager key repository.
This is specified in the queue manager's Key Repository attribute.
b) If you need to create the key database file, do this using the strmqikm GUI.
For more information, see “Invoking the IBM strmqikm (iKeyman) GUI” on page 128.
c) In the strmqikm GUI, ensure that the queue manager key repository contains all the Certificate
Authority (CA) certificates that might be required to validate certificates that are received from
other queue managers.
• [OPTION 2] Change the queue manager key repository location
In certain circumstances you might want to change the key repository location; for example, to use a
single location that is shared by all queue managers on one operating system.
To change a queue manager key repository location:
a) Change the key repository location in the queue manager properties:

Introduction to IBM MQ Explorer 129

 a. Open IBM MQ Explorer and expand the Queue Managers folder.
b. Right-click the queue manager, then click Properties.
c. On the SSL property page, edit the path in the Key repository field to point to your chosen
directory.
d. In the warning dialog, click Yes.
b) Transfer the queue manager personal certificates to the new location using the strmqikm GUI.
For more information, see Securing.
• [OPTION 3] Authenticate certificates using Certificate Revocation Lists
Certification Authorities (CAs) can revoke certificates that are no longer trusted by publishing them
in a Certification Revocation List (CRL). When a certificate is received by a queue manager or an
IBM MQ MQI client, it can be checked against the CRL to ensure that it has not been revoked. CRL
checking is not mandatory for TLS-enabled messaging to be achieved, but is recommended to ensure
the trustworthiness of user certificates.
To set up a connection to an LDAP CRL server, complete the following steps:
a) In IBM MQ Explorer, expand the queue manager.
b) Create an authentication information object of type CRL LDAP. For more information, see “Creating
and configuring queue managers and objects” on page 13.
c) Repeat the previous step to create as many CRL LDAP authentication information objects as you
need.
d) Create a namelist and add to the namelist the names of the authentication information objects that
you created in Steps 2 and 3.
For more information, see “Creating and configuring queue managers and objects” on page 13.
e) Right-click the queue manager, then click Properties.
f) On the SSL page, in the CRL Namelist field, type the name of the namelist that you created in Step
4.
g) Click OK.
The certificates that the queue manager receives can now be authenticated against the CRL held on
the LDAP server.
You can add to the namelist up to 10 connections to alternative LDAP servers to ensure continuity of
service if one or more LDAP servers are inaccessible.
• [OPTION 4] Authenticate certificates using OCSP authentication

On AIX, Linux, and Windows, IBM MQ TLS support checks for revoked certificates using
OCSP (Online Certificate Status Protocol) or using CRLs and ARLs on LDAP (Lightweight Directory
Access Protocol) servers. OCSP is the preferred method. IBM MQ classes for Java and IBM MQ classes
for JMS cannot use the OCSP information in a client channel definition table file. However, you can
configure OCSP as described in Revoked certificates and OCSP.

IBM i and z/OS do not support OCSP checking, but they do allow the
generation of client channel definition tables (CCDTs) containing OCSP information.
For more information about CCDTs and OCSP, see Client channel definition table.
To set up a connection to an OCSP server, complete the following steps.
a) In IBM MQ Explorer, expand the queue manager.
b) Create an authentication information object of type OCSP.
For more information, see “Creating and configuring queue managers and objects” on page 13.
c) Repeat the previous step to create as many OCSP authentication information objects as you need.
d) Create a namelist and add to the namelist the names of the OCSP authentication information
objects that you created in Steps 2 and 3.

130 IBM MQ Explorer

 For more information, see “Creating and configuring queue managers and objects” on page 13.
e) Right-click the queue manager, then click Properties.
f) On the SSL page, in the Revocation namelist field, type the name of the namelist that you created
in Step 4.
g) Click OK.
The certificates that the queue manager receives are authenticated against the OCSP responder.
The queue manager writes OCSP information to the CCDT.
Only one OCSP object can be added to the namelist because the socket library can only use one OCSP
responder URL at a time.
• [OPTION 5] Configure cryptographic hardware
IBM MQ can support cryptographic hardware, and the queue manager must be configured accordingly.
a) Start IBM MQ Explorer.
b) In the Navigator view, right-click the queue manager, then click Properties.
The Properties dialog opens.
c) On the SSL page, click Configure.
The Cryptographic Hardware Settings dialog opens.
d) In the Cryptographic Hardware Settings dialog, enter the path to the PKCS #11 driver, and the
token label, the token password, and the symmetric cipher setting.
All supported cryptographic cards now use PKCS #11, so ignore references to the Rainbow
Cryptoswift or nCipher nFast cards.
e) Click OK.
The queue manager is now configured to use the cryptographic hardware.
You can also work with certificates that are stored on PKCS #11 hardware using iKeyman.
For more information, see Securing.
Related tasks
“Configuring TLS security for IBM MQ” on page 127
To configure TLS security, you set up TLS on each queue manager and each client that uses TLS-enabled
connections.
“Configuring TLS on IBM MQ MQI clients” on page 133
Manage the IBM MQ client certificates, configure the channels to use TLS, and authenticate certificates by
using either Certificate Revocation Lists or OCSP authentication.
Related reference
“Authentication information properties” on page 420
You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.

Configuring TLS channels

To configure TLS channels, you use the SSL page of the Channel properties dialog to define the cipher
specification to be used. You can optionally configure a channel to accept only certificates with attributes
in the distinguished name of the owner that match given values. You can also optionally configure a queue
manager channel so that the queue manager refuses the connection if the initiating party does not send
its own personal certificate.

About this task

To configure channels in IBM MQ Explorer, complete the following steps.

Introduction to IBM MQ Explorer 131

 Procedure
1. Open IBM MQ Explorer.
2. In the Navigator view, expand the Queue Managers folder, then click the Channels folder.
3. In the Content view, right-click the channel, then click Properties.
4. In the Properties dialog, open the SSL page.

Results
Use the SSL page of the Channel properties dialog for the following tasks.
Setting message security
TLS-enabled messaging offers two methods of ensuring message security:
• Encryption ensures that if the message is intercepted, it is unreadable.
• Hash functions ensure that if the message is altered, this is detected.
The combination of these methods is called the cipher specification, or CipherSpec. The same CipherSpec
must be set for both ends of a channel, otherwise TLS-enabled messaging fails. For more information, see
Securing.
On the SSL page of the Properties dialog, do one of the following:
• From the Standard cipher field, select a standard cipher.
• If you are an advanced user and you are administering a queue manager on a z/OS or IBM i platform
that includes new CipherSpecs that are not the IBM MQ predefined list, enter a platform-specific value
for a CipherSpec in the Custom ciphers field.
Filtering certificates on their owner's name
Certificates contain the distinguished name of the owner of the certificate. You can optionally configure
the channel to accept only certificates with attributes in the distinguished name of the owner that match
given values. To do this, select the Accept only certificates with Distinguished Names matching these
values check box.
The attribute names that IBM MQ can filter are listed in the following table:

Attribute names Meaning

SERIALNUMBER Certificate serial number
MAIL Email address
Email address (Deprecated in preference to MAIL)
E
UID or USERID User identifier
CN Common Name
T Title
OU Organizational Unit name
DC Domain component
O Organization name
STREET Street / First line of address
L Locality name
ST (or SP or S) State or Province name
PC Postal code / zip code

132 IBM MQ Explorer

Attribute names Meaning
C Country
UNSTRUCTUREDNAME Host name
UNSTRUCTUREDADDRESS IP address
DNQ Distinguished name qualifier

In the Accept only certificates with Distinguished Names matching these values field, you can use
the wildcard character (*) at the beginning or the end of the attribute value in place of any number of
characters. For example, to accept only certificates from any person with a name ending with Smith
working for IBM in GB, type:

CN=*Smith, O=IBM, C=GB

Authenticating parties initiating connections to a queue manager

When another party initiates a TLS-enabled connection to a queue manager, the queue manager must
send its personal certificate to the initiating party as proof of identity. You can also optionally configure
the queue manager channel so that the queue manager refuses the connection if the initiating party does
not send its own personal certificate. To do this, on the SSL page of the Channel properties dialog, select
Required from the Authentication of parties initiating connections list.
Related tasks
“Configuring TLS security for IBM MQ” on page 127
To configure TLS security, you set up TLS on each queue manager and each client that uses TLS-enabled
connections.

Configuring TLS on IBM MQ MQI clients

Manage the IBM MQ client certificates, configure the channels to use TLS, and authenticate certificates by
using either Certificate Revocation Lists or OCSP authentication.

About this task

This task introduces the commands that you use to work with TLS on an IBM MQ client. For more
information, see Securing and Setting up IBM MQ MQI client security.
Complete any of the following tasks:
1. Manage the IBM MQ client certificates
2. Configure the channels to use TLS
3. Authenticate certificates using Certificate Revocation Lists
4. Authenticate certificates using OCSP authentication

Procedure
• [OPTION 1] Manage the IBM MQ client certificates
Use the IBM strmqikm GUI to manage your TLS certificates. For more information, see “Invoking the
IBM strmqikm (iKeyman) GUI” on page 128.
a) Find the location of the client key repository.
Type the following command to examine the MQSSLKEYR environment variable:

echo %MQSSLKEYR%

Introduction to IBM MQ Explorer 133

 b) In the strmqikm GUI, ensure that the client key repository contains all the Certificate Authority
(CA) certificates that might be required to validate certificates that are received from other queue
managers.
c) Check your application, because the key repository can be set on an MQCONNX call.
If both values are set, the value set on the MQCONNX call overrides the value of MQSSLKEYR.
• [OPTION 2] Configure the channels to use TLS
Set up the TLS channels as described in “Configuring TLS channels” on page 131.
• [OPTION 3] Authenticate certificates using Certificate Revocation Lists
Certification Authorities (CAs) can revoke certificates that are no longer trusted by publishing them
in a Certification Revocation List (CRL). When a certificate is received by a queue manager or an
IBM MQ MQI client, it can be checked against the CRL to ensure that it has not been revoked. CRL
checking is not mandatory for TLS-enabled messaging to be achieved, but is recommended to ensure
the trustworthiness of user certificates.
You can set up an IBM MQ MQI client to check certificates against CRLs on LDAP servers.
a) On the IBM MQ server, in IBM MQ Explorer, expand the queue manager.
b) Create a new authentication information object of type CRL LDAP. For more information, see
“Creating and configuring queue managers and objects” on page 13.
c) Repeat the previous step to create as many authentication information objects as you need.
d) Create a namelist and add to the namelist the names of the authentication information objects that
you created in Steps 2 and 3.
For more information, see “Creating and configuring queue managers and objects” on page 13.
e) Right-click the queue manager, then click Properties.
f) On the SSL page, in the CRL Namelist field, type the name of the namelist that you created in Step
4.
g) Click OK.
All the LDAP CRL information is now written to the client channel definition table.
h) Make the client channel definition table available to the client, or, if you are using Windows Active
Directory, write out the information from the client channel definition table to the Active Directory.
See the setmqscp command.
You can add to the namelist up to 10 connections to alternative LDAP servers to ensure continuity of
service if one or more LDAP servers are inaccessible. For more information, see Securing.
See also Overview of IBM MQ MQI clients.
• [OPTION 4] Authenticate certificates using OCSP authentication
You can set up an IBM MQ MQI client to check certificates against an OCSP responder. Some client
environments do not support OCSP revocation checking, but all server platforms support the ability to
define OCSP configuration which will be written into the client channel definition table file.
a) On the IBM MQ server, in IBM MQ Explorer, expand the queue manager.
b) Create a new authentication information object of type OCSP.
For more information, see “Creating and configuring queue managers and objects” on page 13.
c) Repeat the previous step to create as many OCSP authentication information objects as you need.
d) Create a new namelist and add to the namelist the names of the OCSP authentication information
objects that you created in Steps 2 and 3.
For more information, see “Creating and configuring queue managers and objects” on page 13.
e) Right-click the queue manager, then click Properties.
f) On the SSL page, in the Revocation namelist field, type the name of the namelist that you created
in Step 4.

134 IBM MQ Explorer

 g) Click OK.
h) Make the client channel definition table available to the client.
Only one OCSP object can be added to the namelist because the socket library can only use one OCSP
responder URL at a time. For more information, see Securing.
See also Overview of IBM MQ MQI clients.
Related tasks
“Configuring TLS security for IBM MQ” on page 127
To configure TLS security, you set up TLS on each queue manager and each client that uses TLS-enabled
connections.
“Configuring TLS on queue managers” on page 129
After starting the IBM strmqikm (iKeyman) GUI, you can use it to manage TLS certificates. You can also
authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.
Related reference
“Authentication information properties” on page 420
You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.

Managing object authorities with an authorization service

The authorization service is an installable service that enables you to view and manage the access
authorities of groups and users on IBM MQ objects. You can manage these authorities using IBM MQ
Explorer.

About this task

The authorization service component that is supplied with IBM MQ is the Object Authority Manager (OAM)
but you can use IBM MQ Explorer to manage authorities through other installable authorization services if
you prefer.
The authorization service maintains an access control list (ACL) for each IBM MQ object to which it is
controlling access. An ACL contains a list of all the group IDs that can perform operations on the object;
on Windows, the ACL can contain user IDs as well as group IDs. In the authorization service, you can grant
and revoke authorities for users to access queue managers and objects.
For more information about managing object authorities with the OAM, see Object authority manager
(OAM) and Securing.
For more information about granting authorities on queue managers and objects, see the following topics:
• Granting the Create authority
• Granting authorities on a queue manager
• Granting authorities on a specific object
• Granting authorities on multiple objects
Related concepts
“Authorities you can set on IBM MQ objects” on page 152
You can set authorities for users and groups accessing different IBM MQ objects.
“Authority records” on page 149
An authority record is the set of authorities that have been granted to a particular user or group of users
(entities) on a named object.
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
“Users and groups (entities) in the authorization service” on page 149

Introduction to IBM MQ Explorer 135

 In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Enabling installed plug-ins” on page 221
If a new plug-in that you install in IBM MQ Explorer is not enabled by default, you can enable it by using
the Preferences dialog.

Granting the Create authority

To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

About this task

The authority can be granted to the group to which the user belongs (in which case, all members of the
group are granted the Create authority) or, on Windows queue managers only, to an individual user.
The user can have the authority to create any type of object on the queue manager or just to create
specific types of objects; for example, channels, queues, and listeners only.
Note that the ability to create a queue indirectly grants full administrative rights. Do not grant Create
authority to ordinary users or applications.
To grant the authority to a group or user to create objects on a queue manager, complete the following
steps.

Procedure
1. In the Navigator view, right-click the queue manager, then click Object Authorities > Manage Create
Authorities... The Manage Create Authorities dialog opens.
2. Windows queue managers only: if you are granting the authority to an individual user, click the Users
tab.
3. Click New... The Add Authorities dialog opens.
4. Enter the name of the group or user, as appropriate.
5. Select the check boxes for the objects for which you want to grant the Create authority, then click OK.

Results
An authority record for the group or user is added to the table and the Create authorities that you granted
are shown.
If the group or user already has Create authorities for some of the objects on the queue manager, select
the existing authority record and edit it. If you add a new authority record for a user or group that already
has an authority record on the object, you are prompted to confirm that you want to overwrite the existing
authority record.
Related concepts
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
“Authorities you can set on IBM MQ objects” on page 152
You can set authorities for users and groups accessing different IBM MQ objects.
Related tasks
“Granting authorities on a queue manager” on page 138

136 IBM MQ Explorer

To perform an operation on a queue manager, the user must have authority to perform that particular
operation on the queue manager.
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.

Granting role-based authorities on a queue manager

A user must have the correct authorities to perform operations on objects; you can assign these
authorities individually, but if a user needs either read-only access or full administrative access to all
the objects hosted by a queue manager, this can be granted in a single action.

About this task

Note: This procedure grants the requested access in addition to whatever access the user or group
currently has. If you grant read-only access to a user or group, that user or group does not lose any
existing administrative authorities.
To grant a group or user either read-only access or full administrative access to all the objects hosted by a
queue manager, complete the following steps.

Procedure
1. In the Navigator view, right-click the queue manager, then click Object Authorities > Add Role Based
Authorities... The Add Role Based Authorities dialog opens.
2. Windows queue managers only: if you are granting the authority to an individual user, click User and
enter the user name.
3. If you are granting the authority to a group, click Group and enter the group name.
4. Select the appropriate radio button to grant read only access or full administrative access.
5. If you want to allow the user or group to browse messages on the queues hosted by the queue
manager, select the Permit reading of messages on queues check box.
6. Equivalent commands to grant the requested authorities are displayed in the Command preview pane.
You can copy one or more commands and paste them into a script or onto the command line.
7. Click OK.

Results
The requested authorities are granted to the user or group.
Note: On IBM i, you might also need to change access authorities to allow the user to issue the
commands you have generated. Do this using the GRTOBJAUT command.
Related concepts
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140

Introduction to IBM MQ Explorer 137

 A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting the Create authority” on page 136
To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.
“Granting the authority to connect to a queue manager” on page 141
Before a user can access a queue manager's objects, the user must connect to the queue manager. The
user must, therefore, have authority to connect to that queue manager.

Granting authorities on a queue manager

To perform an operation on a queue manager, the user must have authority to perform that particular
operation on the queue manager.

About this task

The user can have the authority to perform any operation on the queue manager or just to perform
specific operations; for example, to connect to the queue manager, to delete the queue manager, or to
display the queue manager's attributes.
To grant authorities to a group or user to perform operations on a queue manager, complete the following
steps.

Procedure
1. In the Navigator view, right-click the queue manager, then click Object Authorities > Manage Queue
Manager Authority Records... The Manage Authority Records dialog opens.
2. Windows queue managers only: if you are granting the authority to an individual user, click the Users
tab.
3. Click New... The Add Authorities dialog opens.
4. Enter the name of the group or user, as appropriate.
5. Select the check boxes for the authorities that you want to grant, then click OK.

Results
An authority record for the group or user is added to the table and the authorities that you granted are
shown.
If the user or group already has some authorities on the queue manager, select the existing authority
record and edit it. If you add a new authority record for a user or group that already has an authority
record on the object, you are prompted to confirm that you want to overwrite the existing authority record.
Related concepts
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
“Authorities you can set on IBM MQ objects” on page 152
You can set authorities for users and groups accessing different IBM MQ objects.
Related tasks
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140

138 IBM MQ Explorer

A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting the Create authority” on page 136
To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

Granting authorities on a specific object

A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.

About this task

To grant a user or group of users authority to perform operations on a specific object, complete the
following steps.

Procedure
1. In the Content view, right-click the object, then click Object Authorities > Manage Authority Records.
The Manage Authority Records dialog opens.
2. Expand the Specific Profiles folder. Only one profile is displayed because only one specific profile can
match one object. If you open the Manage Authority Records dialog from a folder in the Navigator view,
a specific profile for each of the objects in the folder is displayed in the Specific Profiles folder.
3. Click the profile that is displayed in the Specific Profiles folder. The authority records that have been
granted on the object are displayed.
4. Windows queue managers only: if you are granting the authority to an individual user, click the Users
tab.
5. Click New... The Add Authorities dialog opens.
6. Enter the name of the group or user, as appropriate.
7. Select the check boxes for the authorities that you want to grant on the object, then click OK.

Results
An authority record for the user or group is added to the table and the authorities that you granted are
shown in the authority record.
If the user or group already has some authorities for the object, select the existing authority record and
edit it. If you add a new authority record for a user or group that already has an authority record on the
object, you are prompted to confirm that you want to overwrite the existing authority record.
Related concepts
“Generic and specific profiles” on page 150
When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
“Authorities you can set on IBM MQ objects” on page 152
You can set authorities for users and groups accessing different IBM MQ objects.
Related tasks
“Granting authorities on multiple objects” on page 140

Introduction to IBM MQ Explorer 139

 A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting the Create authority” on page 136
To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

Granting authorities on multiple objects

A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.

About this task

To grant a user or group the same set of authorities on multiple objects, complete the following steps.

Procedure
1. In the Navigator view, on the queue manager that hosts the objects, right-click the folder that contains
the objects, then click Object Authorities > Manage Authority Records.... The Manage Authority
Records dialog opens.
2. You can use an existing generic profile or create a new generic profile:
• If there is an existing generic profile that matches the objects, expand the Generic Profiles folder,
click the generic profile, then click New > User Authority... or New > Group Authority.... The Add
Authorities dialog opens.
• If there is no existing generic profile that matches the objects, right-click the Generic Profiles
folder, then clickNew > User Authority Using New Profile... or New > Group Authority Using New
Profile.... The Add Using Generic Profile dialog opens.
3. Enter the name of the user or group..
4. Type a name for the profile using wildcard characters. The name of the profile must match the names
of all of the objects to which you want the profile to apply.
5. Select the check boxes for the authorities that you want to grant on the objects, then click OK.

Results
An authority record for the user or group is added to the table and the authorities that you granted are
shown.
If the user or group already has some authorities for the object, select the existing authority record and
edit it. If you add a new authority record for a user or group that already has an authority record on the
object, you are prompted to confirm that you want to overwrite the existing authority record.
Related concepts
“Generic and specific profiles” on page 150
When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
“Authorities you can set on IBM MQ objects” on page 152

140 IBM MQ Explorer

You can set authorities for users and groups accessing different IBM MQ objects.
Related tasks
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
Related reference
“Wildcards used in generic profiles” on page 158
You can use some wildcard characters in generic profiles.

Granting the authority to connect to a queue manager

Before a user can access a queue manager's objects, the user must connect to the queue manager. The
user must, therefore, have authority to connect to that queue manager.

About this task

Any authorities granted to the user on the queue manager's objects are irrelevant unless the user can
connect to the queue manager.
When you view the authority records of objects on a queue manager for which the user does not have
Connect authority, the Find Accumulated Authorities dialog displays a message to warn you that the
authorities will have no effect until you grant Connect authority to the user or to a group to which the user
belongs.
To grant Connect authority for a queue manager to a user or group, complete the following steps.

Procedure
1. In the Navigator view, right-click the queue manager, then click Object Authorities > Manage Queue
Manager Authority Records... The Manage Authority Records dialog opens.
2. Highlight the record for the user or group to which you want to add the Connect authority, then click
Edit... The Edit Authorities dialog opens.
3. Select the Connect check box, then click OK.

Results
The user now has Connect access to the queue manager. When the user accesses the queue manager's
objects, the authorities that you have granted to the user take effect.
Related concepts
“Authorities you can set on IBM MQ objects” on page 152
You can set authorities for users and groups accessing different IBM MQ objects.
Related tasks
“Granting authorities on a queue manager” on page 138
To perform an operation on a queue manager, the user must have authority to perform that particular
operation on the queue manager.
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting the Create authority” on page 136

Introduction to IBM MQ Explorer 141

 To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

Comparing the authorities of two entities

In the authorization service, you can compare the authorities that have been granted to two groups of
users.

About this task

An example of the authorities that you could compare is to compare the authorities of group AppDev6
with the authorities of SysDev6 on queue Q_STOCKS_5.
On Windows queue managers, you can also compare the authorities that have been granted to two
individual users, or compare the authorities of a group with the authorities of an individual user.
To compare the authorities of two groups or users, complete the following steps.

Procedure
1. In the Content view, right-click the object on which the two groups or users have authorities, then click
Object Authorities > Manage Authority Records... The Manage Authority Records dialog opens.
2. Click the profile (generic profile or specific profile) that matches the objects on which the two groups
or users have authorities. The authority records associated with the profile are displayed.
3. Click the authority record of one of the groups or users, then click Compare The Compare Authority
Records dialog opens.
4. Enter the name of the group or user with which you want to compare authorities, then click Compare.
The two groups or users and their authorities are displayed in the table.
5. Optional: To show only the authorities that are set differently, select the Show differences only
check box. The authorities that are the same for both groups or users are hidden so that you can
see the differences more easily. In the following figure, the Compare Authority Records dialog shows
that the only differences between the authority records of the user called User500 and the group
called AppDev6 are that the Browse, Get, Inquire, and Set authorities have been granted explicitly to
AppDev6 but not to User500.

142 IBM MQ Explorer

Results
The dialog displays only the authority records for the entities on the object. The dialog does not display
authorities that the user or group might inherit from other sources (the accumulated authorities). For
more information about comparing accumulated authorities, see Comparing the accumulated authorities
of two entities.
Related concepts
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.

Comparing the accumulated authorities of two entities

You can compare the accumulated authorities on an object of two users, two groups, or a user with a
group.

About this task

To compare the accumulated authorities of two entities, complete the following steps.

Procedure
1. Display the accumulated authorities for a user or group on an object. For more information, see Finding
the accumulated authorities of an entity on an object.
2. Click the accumulated authorities row of the table to highlight it, then click Compare The Compare
Accumulated Authorities dialog opens.
3. Enter the name and type of the entity with which you want to compare the accumulated authorities,
then click Compare. The two sets of accumulated authorities are displayed in the table.
4. Optional: Select the Show accumulated differences only check box to show only the authorities that
are different. For example, in the following figure, the Compare Accumulated Authority Records dialog
shows that in the comparison between the user called User500 and the group called mqm, the only
difference is that mqm has the Put authority but User500 does not.

Introduction to IBM MQ Explorer 143

 5. Optional: Select the Show authorities records check box to expand both sets of accumulated
authorities row to display the authority records that contribute to the accumulated authorities.
The following figure shows the comparison between the user called User500 and the group called
mqm with the authority records displayed.

Results
The dialog displays the accumulated authorities and the authority records that contribute to the
accumulated authorities. You cannot edit the authority records from this dialog.

144 IBM MQ Explorer

Related concepts
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Comparing the authorities of two entities” on page 142
In the authorization service, you can compare the authorities that have been granted to two groups of
users.

Finding the authorities of a user or group on an object

You can search the authorization service for authority records or accumulated authorities that have been
granted to groups or users (entities) on a queue manager's objects. If the group or user does not have an
authority record on the specified objects, no results are displayed.

About this task

To find the authorities, complete the following steps.

Procedure
1. In the Navigator view, right-click the queue manager, then click Object Authorities > Find Authorities.
The Find Authorities dialog opens.
2. Select the type of information that you want to display:
• To view the authorities that have been explicitly granted to the group or user, click Authority
records.
• To view the authorities that have accumulated for the group or user, click Accumulated authorities.
3. In the Entity type field, select the entity for whom you are finding the authorities:
• To view the authorities for a specific user, click A user. If Authority records is selected, this option is
available on Windows queue managers only.
• To view the authorities for a specific group of users, click A group.
• To view the authorities for a group or a user of a particular name, click A user or a group. This option
is available on Windows queue managers only.
• To view the authorities for all users, click All users. This option is available on Windows queue
managers only.
• To view the authorities for all groups, click All groups.
• To view the authorities for all entities, click All users and groups. This option is available on
Windows queue managers only.
4. In the Entity name field, type the name of the entity.
5. In the Object type field, select the type of object on which the authorities were granted.
6. In the Profile type field, select the type of profile that the object's name must match:
• To find authorities on a specific object, click Specific profile.
• To find authorities on multiple objects, click Generic profile. The generic profile must already exist.
7. In the Profile name field, enter the name of the profile that the object name must match.
8. Click Find.

Introduction to IBM MQ Explorer 145

 Results
The authority records or accumulated authorities are displayed in the table.
You can edit or remove the authority records that are displayed in the table. Be aware, however, that
removing an authority record might revoke authorities from that user or group (or from any users in the
group) that is associated with that record.
Related concepts
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
“Generic and specific profiles” on page 150
When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting authorities on a queue manager” on page 138
To perform an operation on a queue manager, the user must have authority to perform that particular
operation on the queue manager.

Finding the accumulated authorities of an entity on an object

You can find and view the accumulated authorities of an entity. The accumulated effect of the authorities
of an entity on an object affects whether the entity can perform operations on the object.

About this task

When you view the authority records that have been created on a specific object (for example, a queue
called Q2) in the Manage Authority Records dialog, you can see what authorities have been explicitly
granted to the user or group (the entity) on that object; you can also see which generic profiles apply to
that object and whether the entity has authority records against any of the generic profiles. You cannot,
however, easily see the accumulated effect of those authorities, which is ultimately what affects whether
the entity can perform operations on the object.
You can find and view the accumulated authorities of an entity on an object in any of the following ways:
• In the Manage Authority Records dialog, click the authority record for the entity, then click
Accumulated Authorities... For more information about opening the Manage Authority Records dialog,
see “Granting authorities on a specific object” on page 139 or “Granting authorities on multiple objects”
on page 140.
• In the Content view, right-click the object, then click Object Authorities > Find Accumulated
Authorities...
• In the Navigator view, right-click the queue manager, then click Object Authorities > Find Authorities...
For more information about finding accumulated authorities in the Find Authorities dialog, see Finding
the authorities of a user or group on an object.

146 IBM MQ Explorer

The accumulated authorities for the entity are displayed in the first row of the table; the other rows
display all of the authority records that contribute to the accumulated authorities. If one authority record
contains an authority to perform a particular operation (for example, to put messages on the queue), the
accumulated authorities allow the entity to perform that operation.
You can edit one or more of the authority records that contribute to the accumulated authorities. You can
also remove an authority record from in the Find Accumulated Authorities dialog. Be aware, however, that
removing an authority record might revoke authorities from the user or group (or from any users in the
group) that is associated with that record.
Related concepts
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
“Generic and specific profiles” on page 150
When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
Related tasks
“Granting authorities on multiple objects” on page 140
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.

Determining why an entity has certain authorities

An entity's authorities can accumulate from several sources so it is useful to be able to find out which
authority records contributed to an entity's accumulated authorities.

About this task

After determining why an entity has certain authorities, you can then change the accumulated authorities
in one or more of the authority records as appropriate.
To determine why a entity has certain authorities on an object, complete the following steps.

Procedure
1. In the Content view, right-click the object, then click Object Authorities > Find Accumulated
Authorities... The Find Accumulated Authorities dialog opens.
2. Select the type of entity and type the name of the entity. The table displays the entity's accumulated
authorities and the authority records that contribute to them.
3. Look down the column of the authority (for example, the Put column) to determine which authority
record has caused the entity to have that accumulated authority.

Results
When you have determined which authority records have contributed to the group or user's accumulated
authorities, you can edit one or more of the authority records to change the accumulated authorities (be
aware that changes you make could be inherited by other groups or users as well).

Introduction to IBM MQ Explorer 147

 You can also remove an authority record from in the Find Accumulated Authorities dialog. Be aware,
however, that removing an authority record might revoke authorities from the user or group (or from any
users in the group) that is associated with that record.
Related concepts
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.

Accumulated authorities
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
A user can be granted authorities on an object from the following sources:
• An authority record that has been created on the object for the user (Windows only).
• An authority record that has been created on the object for a group to which the user belongs.
• An authority record that has been created for the user against a generic profile that matches the object
(Windows only).
• An authority record that has been created for a group to which the user belongs against a generic profile
that matches the object.
If a user is granted an authority (for example, the authority to put messages on a queue called Q1) from
just one of these sources, the user has that authority, even if authority records from other sources do not
grant that authority. For example, the following figure shows that the user called User500, who belongs
to group AppDev6, does not have authority to put messages on Q1 because the Put authority has not
been granted to User500 or to AppDev6. User500, however, does have authority to get messages from Q1
because the Get authority has been granted to AppDev6 so User500 inherits the Get authority.

In the figure, the first row of the table in the Find Accumulated Authorities dialog shows the accumulated
authorities of User500. The next two rows show the authority records that contribute to the accumulated
authorities. In the scenario shown in the figure, the authority record for User500 does not contain the Put
and Get authorities; the authority record for AppDev6, however, contains the Get authority. Therefore, the
accumulated authorities for User500 show that User500 has Get authority but not Put authority on queue
Q1.

148 IBM MQ Explorer

The warning message in the Find Accumulated Authorities dialog shows that although User500 has some
authorities to perform operations on queue Q1, User500 does not have authority to connect to the queue
manager that hosts Q1.
Related concepts
“Authority records” on page 149
An authority record is the set of authorities that have been granted to a particular user or group of users
(entities) on a named object.
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Granting the Create authority” on page 136
To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

Authority records
An authority record is the set of authorities that have been granted to a particular user or group of users
(entities) on a named object.
On objects on Windows, you can create authority records for individual users and for groups of users. On
AIX, Linux, and IBM i, you can create authority records only for groups of users; if you grant authorities to
an individual user, the authorization service creates or updates the authority record for the user's primary
group so that the same authorities are granted to all the users in the group.
To be able to perform operations on an object or a queue manager, an entity (a user or a group) must
have an authority record that contains the authorities to perform those operations. For example, for a user
called User337 to be able to put messages on queue Q1, User337 or a group to which User337 belongs
must have an authority record that contains the Put authority.
You can grant authorities on single objects by creating an authority record against a specific profile, or you
can grant authorities on multiple objects by creating an authority record against a generic profile. Because
you can create authority records for individual users and for groups, and you can create authority records
against generic profiles which can apply to multiple objects, the authorities that an individual user has on
a particular object can accumulate from several sources.
Related concepts
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.
“Generic and specific profiles” on page 150
When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
Related tasks
“Determining why an entity has certain authorities” on page 147
An entity's authorities can accumulate from several sources so it is useful to be able to find out which
authority records contributed to an entity's accumulated authorities.

Users and groups (entities) in the authorization service

In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and

Introduction to IBM MQ Explorer 149

 groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
On objects on Windows, you can create authority records for individual users and for groups of users. On
AIX, Linux, and IBM i, you can create authority records only for groups of users; if you grant authorities to
an individual user, the authorization service creates or updates the authority record for the user's primary
group so that the same authorities are granted to all the users in the primary group.
The following figure shows the authority record for the mqm group on a queue called Q_STOCKS_5.
Q_STOCKS_5 is a queue on a Windows queue manager so it is possible to view authority records that have
been created for individual users. If the queue were hosted on a Linux, AIX, or IBM i queue manager,
there would be no Users tab available in the dialog.

The users and groups that are displayed in IBM MQ Explorer are defined in the operating system that
hosts the queue manager and objects. You cannot, therefore, create or delete entities from within the IBM
MQ Explorer itself. If you make a change to an entity while IBM MQ Explorer is running, you must refresh
the authorization service to pick up the changes; for more information, see Refreshing authorization
service information .
Entities can be granted authorities explicitly and also by inheritance. For more information about how
entities can inherit authorities, see Accumulated authorities.
On Windows, delete the authority records corresponding to a particular Windows user account before
deleting that user account. It is impossible to remove the authority records after removing the Windows
user account.
Related concepts
“Authority records” on page 149
An authority record is the set of authorities that have been granted to a particular user or group of users
(entities) on a named object.
“Accumulated authorities” on page 148
Accumulated authorities are the total authorities that a user or group has to perform an operation on an
object.

Generic and specific profiles

When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
Profiles define the name and type of object to which the authorities will apply. A specific profile exactly
matches the name of the object, while a generic profile matches one or more objects using wildcard
characters.

150 IBM MQ Explorer

Specific profiles
A specific profile applies only to the object of that name and type. To grant or revoke an authority on
a single object, you select the relevant specific profile and create or edit the authority records for that
profile.
For example, to grant group AppDev6 the authority to put messages on queue Q.STOCKS.5, select the
specific profile called Q.STOCKS.5 and create or edit the authority record for group AppDev6. The
authority record will apply only to the queue called Q.STOCKS.5.
Objects of type queue or topic with names that match the profile name do not have to exist when the
command is issued.

Generic profiles
A generic profile is a profile that you have created to associate with more than one object of the same
type. You can grant authorities to a set of objects at the same time by creating an authority record against
the generic profile. For example, to grant group AppDev6 the authority to put messages on any queue with
a name that starts with Q.STOCKS., grant the authority using a generic profile that is named Q.STOCKS.*
For more information about wildcards, see Wildcards used in generic profiles.
Objects with names that match the profile name do not have to exist when the command is issued.
Related concepts
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
Related reference
“Wildcards used in generic profiles” on page 158
You can use some wildcard characters in generic profiles.

Authorization service control commands

IBM MQ Explorer performs the same functions as the IBM MQ control commands setmqaut, dspmqaut,
and dmpmqaut.
The following table shows the authorities in IBM MQ Explorer and the equivalent parameters when you
use the control commands.

Authority Control command

Alternate user authority altusr
Browse browse
Change chg
Clear clr
Connect connect
Create crt

Introduction to IBM MQ Explorer 151

 Authority Control command
Ctrl ctrl
Ctrlx ctrlx
Delete dlt
Display dsp
Get get
Put put
Inquire inq
Pass all context passall
Pass identity context passid
Set set
Set all context setall
Set identity context setid
System system

Related tasks
“Granting authorities on a queue manager” on page 138
To perform an operation on a queue manager, the user must have authority to perform that particular
operation on the queue manager.
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.

Authorities you can set on IBM MQ objects

You can set authorities for users and groups accessing different IBM MQ objects.
The following table lists the authorities that you can set for users and groups accessing different IBM MQ
objects. Some authorities can be set against specific objects only; the table shows whether each authority
is valid for each object.

152 IBM MQ Explorer

Author Descri Queue Remot Queue Proces Namel Authe Chann Client- Servic Listen
ity ption manag e s ist nticati el conne e er
er queue definit on ction
manag ions inform chann
er ation el
Altern Use Yes No No No No No No No No No
ate anothe
user r
ID user's
ID to
open
queue
s and
put
messa
ges on
queue
s.
Brows Brows No No Yes No No No No No No No
e e
messa
ges on
a
queue.
Chang Chang Yes No Yes Yes Yes Yes Yes Yes Yes Yes
e e the
attribu
tes of
the
object.
Clear Clear No No Yes No No No No No No No
the
messa
ges
from
the
queue.
Conne Allow Yes No No No No No No No No No
ct the
applic
ation
to
connec
t to the
queue
manag
er.

Introduction to IBM MQ Explorer 153

 Author Descri Queue Remot Queue Proces Namel Authe Chann Client- Servic Listen
ity ption manag e s ist nticati el conne e er
er queue definit on ction
manag ions inform chann
er ation el
Create Create Yes No Yes Yes Yes Yes Yes Yes Yes Yes
object
s of
the
specifi
ed
type
on the
queue
manag
er.
Ctrl Start, No No No No No No Yes No Yes Yes
stop,
and
ping
the
chann
el.
Ctrlx Reset No No No No No No Yes No No No
or
resolv
e the
chann
el.
Delete Delete Yes No Yes Yes Yes Yes Yes Yes Yes Yes
the
object.
Displa Displa Yes No Yes Yes Yes Yes Yes Yes Yes Yes
y y the
attribu
tes or
status
of the
object.
Get Get No No Yes No No No No No No No
messa
ges
from
the
queue.
Put Put No Yes Yes No No No No No No No
messa
ges on
the
queue.

154 IBM MQ Explorer

Author Descri Queue Remot Queue Proces Namel Authe Chann Client- Servic Listen
ity ption manag e s ist nticati el conne e er
er queue definit on ction
manag ions inform chann
er ation el
Inquir Displa Yes No Yes Yes Yes Yes No No No No
e y the
attribu
tes or
status
of the
object.
Pass Allow No Yes Yes No No No No No No No
all the
contex applic
t ation
to pass
all the
contex
t fields
from
the
reques
t
messa
ge to a
messa
ge that
the
applic
ation is
putting
on the
queue.

Introduction to IBM MQ Explorer 155

 Author Descri Queue Remot Queue Proces Namel Authe Chann Client- Servic Listen
ity ption manag e s ist nticati el conne e er
er queue definit on ction
manag ions inform chann
er ation el
Pass Allow No Yes Yes No No No No No No No
identit the
y applic
contex ation
t to pass
the
identit
y
contex
t fields
from
the
reques
t
messa
ge to
the
messa
ge that
the
applic
ation is
putting
on a
queue.
Set Set Yes No Yes Yes No No No No No No
attribu
tes on
the
queue.
Set all Allow Yes Yes Yes No No No No No No No
contex the
t applic
ation
to set
the
identit
y and
origin
contex
t fields
in a
messa
ge.

156 IBM MQ Explorer

Author Descri Queue Remot Queue Proces Namel Authe Chann Client- Servic Listen
ity ption manag e s ist nticati el conne e er
er queue definit on ction
manag ions inform chann
er ation el
Set Allow Yes Yes Yes No No No No No No No
identit the
y applic
contex ation
t to set
the
identit
y
contex
t fields
in a
messa
ge, and
allow
the
queue
manag
er to
genera
te the
origin
contex
t.
Syste Gives Yes No No No No No No No No No
m authori
ty to
princip
als or
groups
who
are
authori
zed to
carry
privile
ged
operati
ons on
object
s

Related tasks
“Granting authorities on a queue manager” on page 138
To perform an operation on a queue manager, the user must have authority to perform that particular
operation on the queue manager.
“Granting authorities on a specific object” on page 139
A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue.
“Granting authorities on multiple objects” on page 140

Introduction to IBM MQ Explorer 157

 A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.
“Granting the Create authority” on page 136
To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

Wildcards used in generic profiles

You can use some wildcard characters in generic profiles.
The following table lists the wildcard characters that you can use in generic profiles.

Wildcar Description Example

d
charact
er
? Use the question mark (?) instead of any AB.?D applies to the objects AB.CD, AB.ED,
single character. and AB.FD.
* Use the asterisk (*) as a qualifier in a profile ABC.*.JKL applies to the objects
name to match any one qualifier in an object ABC.DEF.JKL, and ABC.GHI.JKL; it does
name. A qualifier is the part of an object not apply to ABC.JKL because * used in this
name delimited by a period. For example, in context always indicates exactly one qualifier.
ABC.DEF.GHI, the qualifiers are ABC, DEF,
and GHI.
Use the asterisk (*) as a character within ABC.DE*.JKL applies to the objects
a qualifier in a profile name to match zero ABC.DE.JKL, ABC.DEF.JKL, and
or more characters within the qualifier in an ABC.DEGH.JKL.
object name.
** Use the double asterisk (**) once in a profile If you use ** as the profile name, the profile
name as the entire profile name to match all applies to all processes.
object names.
Use the double asterisk (**) once in a profile **.ABC identifies all objects with the final
name as either the beginning, middle, or qualifier ABC.
ending qualifier in a profile name to match
zero or more qualifiers in an object name.

Note that wildcard characters must use quotation marks on systems that expand them. In general, AIX
and Linux platforms require double quotation marks around generic profiles, whereas Windows platforms
do not.
For other platforms, refer to your product documentation.
Related concepts
“Generic and specific profiles” on page 150
When you manage authorities for a folder of objects (for example, the Queues folder) using the Manage
Authority Records dialog, you grant authorities against profiles instead of granting authorities on specific
objects.
Related tasks
“Granting authorities on multiple objects” on page 140

158 IBM MQ Explorer

A user must have the correct authorities to perform operations on objects; for example, to browse the
messages on a queue. You can grant the same set of authorities to multiple objects on a queue manager
by using generic profiles.

Exporting authorities to a file

You can export object authorities to a text file from IBM MQ Explorer.

About this task

The authorities are formatted in the text file so that you can use lines from the file on the command line or
in scripts to set authorities on other computers in your IBM MQ network. For example, a file could contain
the following lines:

setmqaut -m QM_A -n Q1 -t queue -p user@domain +browse +chg +clr +dlt +dsp +put +inq +get
+passall +passid +set +setall +setid
setmqaut -m QM_A -n Q1 -t queue -g mqm +browse +chg +clr +dlt +dsp +put +inq +get +passall
+passid +set +setall +setid

You can export different subsets of object authorities. Complete any of the following tasks:
1. Export all object authorities for a queue manager and its objects
2. Export all Create authorities for a queue manager
3. Export authorities by object type

Procedure
• [OPTION 1] Export all object authorities for a queue manager and its objects
a) In the Navigator view, right-click the queue manager, then click Object Authorities > Save All. A
dialog opens.
b) Type a name for the text file and save the authorities.
All of the object authorities for the queue manager and its objects are saved in the text file.
• [OPTION 2] Export all Create authorities for a queue manager
a) In the Navigator view, right-click the queue manager, then click Object Authorities > Manage the
Create Authorities.
The Manage Create Authorities dialog opens. For more information about the managing Create
authorities, see Granting the Create authority.
b) Click Save As.
A dialog opens.
c) Type a name for the text file and save the authorities.
All of the Create authorities for the queue manager are saved in the text file.
• [OPTION 3] Export authorities by object type
a) In the Navigator view, right-click the queue manager, then click Object Authorities > Find
Authorities The Find Authorities dialog opens.
b) Enter the search parameters as required, then click Find; for more information, see Finding the
authorities of a user or group.
c) Click Save As A dialog opens.
d) Type a name for the text file and save the authorities.
All of the object authorities from the records that were found are saved in the text file.
Related tasks
“Exporting and importing settings” on page 224

Introduction to IBM MQ Explorer 159

 You can export your settings from IBM MQ Explorer for backup purposes, or to transfer and import the
settings into another instance of IBM MQ Explorer.
“Finding the authorities of a user or group on an object” on page 145
You can search the authorization service for authority records or accumulated authorities that have been
granted to groups or users (entities) on a queue manager's objects. If the group or user does not have an
authority record on the specified objects, no results are displayed.
“Granting the Create authority” on page 136
To create a new object on a queue manager, the user who performs the operation must have authority to
create that type of object on the queue manager.

Configuring a default security exit

A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.

About this task

The default security definitions will be persisted in IBM MQ Explorer and will be automatically included in
Preferences in any import actions or export actions. The security exit details for each queue manager will
be persisted with the other connection details of the queue manager.
To configure the default security exit:

Procedure
1. Click Window > Preferences.
The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand Client Connections.
The default security settings dialogs are now accessible.
4. Configure the security settings as required.

What to do next
The default security exit has now been configured. All new client connections in the same IBM MQ
Explorer now use the settings you have configured as a default. The settings can be overridden when
adding a new remote queue manager.
Related tasks
“Configuring the client security details for a queue manager set” on page 160
The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.
“Passwords preferences” on page 163
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Configuring the client security details for a queue manager set

The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.

Before you begin

Before you set the security details for a queue manager set, queue manager sets must be visible, as
described in: “Displaying queue manager sets” on page 201.

160 IBM MQ Explorer

About this task
The security definitions are persisted in IBM MQ Explorer and are automatically included in Preferences
in any import actions or export actions. The security details for each queue manager are persisted with
the other connection details of the queue manager. The security details can be set for the All queue
manager set as well as for user-defined queue manager sets.
To configure the security details for all existing queue managers in a queue manager set:

Procedure
1. Right-click the queue manager set you want to define the security details for.
2. Click Edit Security Settings...
The Set Connection Details wizard opens, and you can set the security exit details, user ID and
password details, TLS certificate store details, and enable the default TLS options. User ID and
password details are also applicable to any local queue managers that are part of the set.
3. Select the security options that you want from each page of the wizard.
4. Select the queue managers that you want to apply the new security settings to. Click Finish to apply
the changes and close the Set Connection Details dialog.

What to do next
The security details are configured for the selected queue manager set. All the queue managers that you
selected in the queue manager set are configured with the new security details. The security configuration
applies to all instances of the same queue managers in different queue manager sets.
The changes will not be applied until the next time the queue manager is connected.
Related tasks
“Configuring a default security exit” on page 160
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.
“Passwords preferences” on page 163
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Default security preferences

A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.
The default security preferences are part of the Preferences dialog, and they can be opened in the
following way:
1. Click Windows > Preferences.... The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand Client Connections. The default security settings dialogs are now accessible.

Security Exit
Select Enable default security exit to set the default security exit for all client connections in the same
IBM MQ Explorer. The security exit for all the client-connected queue managers in a set can be changed.
The security exit can be overridden if you define a new security exit when you add a new remote queue
manager.

Introduction to IBM MQ Explorer 161

 The Security Exit for all client-connected queue managers in a set can be changed. The TLS options can
be overridden when you add a new remote queue manager.

Item Description
Exit Specifies the name of the exit program to be run by the security exit. Exit name can be
name up to 1024 characters long and is case sensitive. Exit name can be a fully qualified java
class name found in the directory or jar file. Exit name can be a C exit, of the format:
dll_name(function_name). The default path for exits is always used to locate C exits, you
cannot specify the location of the exit library in this entry field unless no default path is set.
in Specifies the directory for the security exit (Java exits only).
directory
in jar Specifies the jar file for the security exit (Java exits only).
Exit data Exit data can be up to 32 characters long. If no value has been defined for that attribute,
this field is all blanks.

SSL/TLS Options
Select Enable default SSL options to enable the default SSL/TLS options for all client connections in the
same IBM MQ Explorer. The SSL/TLS options for all client-connected queue managers in a set can be
changed. The SSL/TLS options can be overridden when you add a new remote queue manager.

Item Description
SSL The CipherSpec identifies the combination of encryption algorithm and hash function used
CipherSp by an SSL/TLS connection. A CipherSpec forms part of a CipherSuite, which identifies the
ec key exchange and authentication mechanism as well as the encryption and hash function
algorithms.
The size of the key used during the handshake can depend on the digital certificate you use,
but some of the CipherSpecs supported by IBM MQ include a specification of the handshake
key size. Note that larger handshake key sizes provide stronger authentication. With smaller
key sizes, the handshake is faster.
For more information, see CipherSpecs and CipherSuites.

SSL FIPS Select Yes to use only FIPS-certified cipher suites. If you select Yes, then all TLS connections
required must use FIPS-certified cipher suites.

Select No to use any available cipher suites.

The default setting is No.
If you change this setting from Yes to No, or from No to Yes a dialog will be opened asking if
you want to restart MQ Explorer.
Any changes to this setting will not be applied until the MQ Explorer has been restarted.

SSL Type the number of bytes, from 0 to 999 999 999, that are sent and received within a TLS
reset conversation before the secret key is renegotiated. A value of 0 means that the secret key
count is never renegotiated. The number of bytes includes control information that is sent by the
message channel agent (MCA). If the value of this attribute is greater than 0 and the value of
the Heartbeat interval attribute in the Channel properties is greater than 0, the secret key is
also renegotiated before message data is sent or received following a channel heartbeat.
Peer The Distinguished Name (DN) of the queue manager to be used by TLS. The peer name
name is set to indicate that connections will only be allowed where the server is successfully
authenticated as a specific DN.

162 IBM MQ Explorer

SSL/TLS Stores
Select Enable default SSL stores to work with the Trusted Certificate Store and the Personal Certificate
Store.
To configure IBM MQ Explorer with the location and password of the SSL/TLS certificate store, refer to:
“Specifying the default location and default password of TLS certificates” on page 87.
By enabling the default SSL/TLS stores, IBM MQ Explorer can use the certificates in the TrustStore and
KeyStore to connect to remote queue managers with a TLS-enabled connection.
The SSL/TLS Stores for all client-connected queue managers in a set can be changed. The SSL/TLS Stores
can be overridden when you add a new remote queue manager.
Related tasks
“Configuring a default security exit” on page 160
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.
“Configuring the client security details for a queue manager set” on page 160
The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.
Related reference
“Passwords preferences” on page 163
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Passwords preferences
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.
Passwords used by the IBM MQ Explorer to connect to resources (for example: opening TLS stores or
connecting to queue managers), can be stored in a file. The password file can be stored locally, to a
remote device, or to a removable device.
To open the Passwords preference panel:
1. Click Window > Preferences. The Preferences dialog opens.
2. Expand MQ Explorer.
3. Select Passwords to display the Passwords panel.

Item Description
Do not save Passwords are not stored to a file. This is the default value.
passwords
Save Passwords are saved to the file you specify. Select Save passwords to file and click
passwords Browse to select a location for the encrypted password file
to file
Use default You must use a key to open a password store. This is the default value.
key
User You must use a key to open a password store. Select User defined key then click Change
defined key to enter your password. The password must contain a minimum of 8 characters.

Related tasks
“Configuring a default security exit” on page 160
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.
“Configuring the client security details for a queue manager set” on page 160

Introduction to IBM MQ Explorer 163

 The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.

Configuring API exits

An API exit is a code module, a .dll file, that you provide yourself and that runs immediately before or
after MQI calls.

About this task

When IBM MQ receives a call from a program to one of its API entry points, IBM MQ calls your API exit.
The API exit runs either before or after the MQI is run, according to how you configured the exit.
You can configure none, one, or many exits to be called, and you can configure the sequence in which
multiple exits are called. On Windows and Linux (x86 and x86-64 platforms), you can configure the API
exits using IBM MQ Explorer. The configuration details are stored in .ini files.
1. Configure an API exit in IBM MQ Explorer.
2. Override a common API exit with a local API exit.
There are three types of API exit definition:
Common (ApiExitCommon)
One set of definitions per computer. When the queue manager starts, the API exits that are defined,
if any, are read and applied to the queue manager. Configure common API exits in the IBM MQ
properties dialog. Common exits are displayed in the Local API Exits table in the properties dialog of
each local queue manager.

Template (ApiExitTemplate)
One set of definitions per computer. When a queue manager is created, the API exits defined here, if
any, are copied into the newly created queue manager as local exits. Configure template API exits in
the IBM MQ properties dialog.
Local (ApiExitLocal)
One set of definitions per queue manager. When the queue manager starts, any API exits that are
defined override the common exits if their Name attributes are the same, and if the override has been
specified. When a common API exit is overridden, none of the fields in the common definition are
saved, even if the optional Data attribute has an assigned value. Configure local API exits in the queue
manager's properties dialog.
When you configure API exits in the IBM MQ and queue manager properties dialogs, the attribute values
are added to the ApiExitCommon, ApiExitTemplate, and ApiExitLocal stanzas in the configuration
files or the Windows registry.

Table 4. API exit attributes

Attribute Meaning Stanza key
Name Specifies the descriptive name of the API exit which is passed to Name
the API exit in the ExitInfoName field of the MQAXP structure.
This name must be unique and is limited to a length of 48
characters, and must contain only those characters that are valid
for the name of IBM MQ objects, such as queue names.
Type Specifies the type of exit: common, template, local, or (Not a separate
override. stanza key.)

164 IBM MQ Explorer

Table 4. API exit attributes (continued)
Attribute Meaning Stanza key
Sequence This attribute is an unsigned numeric value that defines the Sequence
sequence in which this API exit is called in comparison with
other API exits. An API exit with a low sequence number is called
before another API exit with a higher sequence number. The order
in which different API exits with the same sequence number are
called is undefined. It is perfectly valid for there to be gaps in the
sequence numbers of the API exits defined for a queue manager.
Module Specifies the module that contains the code for the API exit. If Module
this field contains the full path name of the module it is used
as is. If this field contains just the module name, the module is
located using the same method as channel exits; that is, using the
value in the Exit default path field on the Exits page of the queue
manager properties dialog.
Function Specifies the name of the function entry-point into the module Function
that contains the code for the API exit. This entry-point is the
MQ_INIT_EXIT function. The length of this field is limited to
MQ_EXIT_NAME_LENGTH.
Data If this attribute is specified, leading and trailing blanks are Data
removed, the remaining string is truncated to 32 characters, and
the result is passed to the exit in the ExitData field of the MQAXP
structure. If this attribute is not specified, the default value of 32
blanks is passed to the exit in the ExitData field of the MQAXP
structure.

Procedure
• [OPTION 1] Configure an API exit in IBM MQ Explorer.
a) Open the relevant properties dialog:
b) On the Exits page, click Add.... The Add API Exit dialog opens.
c) Type the required information into the fields of the Add API Exit dialog.
d) Click OK to create the exit and close the Add API Exit dialog.
The properties of the new API exit are displayed in the table on the Exits page.
• [OPTION 2] Override a common API exit with a local API exit.
When a local API exit is defined on a queue manager with the same name as a common exit, the
common exit is overridden. That is, the common exit is not called; instead, the overriding local exit
is called. To prevent accidental overriding, the user interface makes you take deliberate actions to
configure an override; for example, you cannot add a new exit with the same name as an existing exit,
and you cannot change the name of an exit to be the same as an existing exit. However, you might
want to add a local API exit to a queue manager so that the common API exit is not used and the local
API exit is used instead. In this case, you need to override the common API exit with the local API exit.
a) Open the Exits page of the queue manager properties dialog.
b) Click the common exit that you want to override in the Local API Exits table.
c) Click Override.
The Edit API Exit dialog opens with the name of the common API exit displayed.
d) Type the details of the local API exit in the Edit API Exit dialog, and click OK to save the changes.
The local exit now overrides the common exit that has the same name.
“Configuring queue managers and objects” on page 37

Introduction to IBM MQ Explorer 165

 You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Queue manager properties” on page 315
You can set properties for both local and remote queue managers.
“IBM MQ properties” on page 309
IBM MQ properties apply to the whole IBM MQ installation.

Authorizing users to configure IBM MQ on Windows and Linux (x86 and

x86-64 platforms)
IBM MQ uses the normal user and group authorizations to protect IBM MQ applications and IBM MQ
administration.

Configuring IBM MQ

About this task

The IBM MQ installation automatically creates the local group mqm. Only users that belong to the mqm
group can perform tasks such as creating, deleting, and altering queue managers, setting authorizations
on queue manager objects, and running listeners. For more information regarding the commands that are
used to perform these tasks, see Administering IBM MQ for Multiplatforms using control commands.
On Windows, user names that are members of the Windows Administrators group also have the
authority to perform these tasks. Users that are members of the Windows Administrators group are
also authorized to alter the local Windows operating system settings. For IBM MQ on Windows, user
names can contain a maximum of 20 characters; for IBM MQ on other platforms, user names can contain
a maximum of only 12 characters.
To give a user authority to administer queue managers:

Procedure
1. Log in to the operating system with a user name that has Administrator authority on Windows, or root
authority on Linux.
2. Add the users user name to the mqm group.

Results
On Windows, the security token that the IBM MQ Explorer queries for authority when it starts, contains
the user name and authority information and is cached by Windows. If changes are made to a user name
authorization, that user must log off and on again for the changes to take effect when IBM MQ Explorer is
restarted.

Performing IBM MQ operations

About this task

To perform operations such as connecting to a queue manager, opening a queue, or creating a queue, the
user must have the correct IBM MQ privileges. Only users who belong to the mqm group or who have been
granted +chg permission on the queue manager can perform tasks such as creating, deleting, and altering
queue managers. A user that has the correct privileges can run applications but cannot, for example,
create or delete queue managers unless they are also a member of the mqm group.
You can make user name authorizations with various levels of capability for the IBM MQ applications you
create and implement on your own network so that, for example, a user name might have the authority
to connect to a queue manager and put and get messages to a queue, but not have authority to alter the
attributes of that queue. Use the setmqaut command to do this. For more information, see setmqaut.
You can make the user names that use your application members of a global group for your network, and

166 IBM MQ Explorer

then, on each computer where the application must run, make the global group a member of the mqm
group.
Changes made to IBM MQ authorizations by the setmqaut command take immediate effect. However,
changes made to user name authorization do not take effect until the relevant queue manager is stopped
and restarted.

Starting Windows service for an IBM MQ installation

About this task

The service starts at Windows startup time, before any user is logged on. The service is used to start any
queue managers configured with the automatic startup option. In order to ensure that queue manager
processes run with correct authority, the service must be configured with an appropriate user name. For
more information on configuring the IBM MQ service, see Changing the password of the IBM MQ Windows
service user account.

Refreshing the authorization service information on Multiplatforms

On Multiplatforms, if you make a change to an entity, you must refresh the entity information in the
authorization service. You must do this for each queue manager that is affected by the changes that you
make to the entity.

About this task

The users and groups (entities) that are displayed in the authorization service are defined in the operating
system. You cannot, therefore, create or delete entities from within the authorization service itself. If you
make a change to an entity (either a user or a group) while the queue manager is running, you must
refresh the entity information in the authorization service.
When you refresh the entity information in the authorization service, the authorization service rebuilds its
Access Control List (ACL) using the new entity information.
To refresh the entity information in the queue manager's authorization service using IBM MQ Explorer,
complete the following steps.

Procedure
1. In the Navigator view, right-click the queue manager for which you want to refresh the entity
information, then click Security > Refresh Authorization Service.
2. When prompted, click Yes.

Results
The entity information for the queue manager and all of its objects is refreshed in the authorization
service.
Ensure that you refresh the entity information for each queue manager that is affected by the changes
that you made to the entity.
Related concepts
“Users and groups (entities) in the authorization service” on page 149
In the authorization service, authorities are granted to users (also known as principals when the user
name is fully qualified with the domain name) or groups of users for accessing IBM MQ objects. Users and
groups are collectively known as entities in the authorization service. You grant a set of authorities to an
entity by creating an authority record.
Related tasks
“Refreshing TLS security” on page 168

Introduction to IBM MQ Explorer 167

 You can make changes to the key repository without restarting a channel. However, the copy of the key
repository that is held in memory while a channel is running will not be affected. When you refresh the
cached copy of the key repository, the TLS channels that are currently running on the queue manager are
updated with the new information.
“Refreshing ESM classes (z/OS only)” on page 170
IBM MQ for z/OS does not perform any authority checks itself; instead, it routes requests for authority
checks to an external security manager (ESM).
“Refreshing the connection authentication configuration” on page 168
If the configuration for connection authentication changes, you must refresh the queue manager's view of
this configuration.

Refreshing the connection authentication configuration

If the configuration for connection authentication changes, you must refresh the queue manager's view of
this configuration.

About this task

When the configuration to enable or disable connection authentication or the details of the user
repository to be used for connection authentication are changed, you must refresh the queue manager's
view of this configuration.

Procedure
1. In the Navigator view, right-click the queue manager for which you want to refresh the connection
authentication configuration, then click Security > Refresh Connection Authentication.
2. When prompted, click Yes.

Results
The configuration for connection authentication is picked up by the queue manager and will be used to
determine whether connection authentication should be applied to any subsequent connections to the
queue manager.
Related tasks
“Refreshing the authorization service information on Multiplatforms” on page 167
On Multiplatforms, if you make a change to an entity, you must refresh the entity information in the
authorization service. You must do this for each queue manager that is affected by the changes that you
make to the entity.
“Refreshing ESM classes (z/OS only)” on page 170
IBM MQ for z/OS does not perform any authority checks itself; instead, it routes requests for authority
checks to an external security manager (ESM).
“Refreshing TLS security” on page 168
You can make changes to the key repository without restarting a channel. However, the copy of the key
repository that is held in memory while a channel is running will not be affected. When you refresh the
cached copy of the key repository, the TLS channels that are currently running on the queue manager are
updated with the new information.

Refreshing TLS security

You can make changes to the key repository without restarting a channel. However, the copy of the key
repository that is held in memory while a channel is running will not be affected. When you refresh the

168 IBM MQ Explorer

cached copy of the key repository, the TLS channels that are currently running on the queue manager are
updated with the new information.

About this task

When a channel is secured using TLS, the digital certificates and their associated private keys are stored
in the key repository. A copy of the key repository is held in memory while a channel is running. If you
make a change to the key repository the changes do not become active in the in-memory copy of the key
repository while a channel is running.
When you refresh the cached copy of the key repository, all TLS channels that are currently running are
updated:
• Sender, server, and cluster-sender channels that use TLS are allowed to complete the current batch
of messages. The channels then run the SSL handshake again with the refreshed view of the key
repository.
• All other channel types that use TLS are stopped. If the partner end of the stopped channel has retry
values defined, the channel retries and runs the SSL handshake again. The new SSL handshake uses
the refreshed view of the contents of the key repository, the location of the LDAP server to be used for
the Certificate Revocation Lists, and the location of the key repository. In the case of server-connection
channel, the client application loses its connection to the queue manager and has to reconnect to
continue.
To refresh the cached copy of the key repository, complete the following steps.

Procedure
1. In the Navigator view, right-click the queue manager for which you want to refresh the cached copy of
the key repository, then click Security > Refresh SSL.
2. When prompted, click Yes.

Results
The TLS channels that are currently running on the queue manager are updated with the new information.
The queue manager FIPS configuration (SSLFipsRequired) is also refreshed by this command on AIX,
Linux, and Windows.
Related tasks
“Securing channels with TLS” on page 126
The TLS (Transport Layer Security) protocol enables queue managers to communicate securely with other
queue managers, or clients.
“Refreshing the authorization service information on Multiplatforms” on page 167
On Multiplatforms, if you make a change to an entity, you must refresh the entity information in the
authorization service. You must do this for each queue manager that is affected by the changes that you
make to the entity.
“Refreshing ESM classes (z/OS only)” on page 170
IBM MQ for z/OS does not perform any authority checks itself; instead, it routes requests for authority
checks to an external security manager (ESM).
“Refreshing the connection authentication configuration” on page 168

Introduction to IBM MQ Explorer 169

 If the configuration for connection authentication changes, you must refresh the queue manager's view of
this configuration.

Refreshing ESM classes (z/OS only)

IBM MQ for z/OS does not perform any authority checks itself; instead, it routes requests for authority
checks to an external security manager (ESM).

About this task

The IBM MQ product documentation assumes that you are using the z/OS Security Server Resource
Access Control Facility (RACF®) as the ESM.
So that IBM MQ does not have to contact RACF for every authority check, IBM MQ puts information about
the user and the user's authorities in a cache. When you add, delete, or change a RACF resource profile
that is held in one of the following classes:
• MQADMIN
• MQNLIST
• MQPROC
• MQQUEUE
• MXADMIN
• MXNLIST
• MXPROC
• MXQUEUE
• MXTOPIC
force IBM MQ to refresh the ESM classes so that it throws away the cached information and starts to
rebuild the cache from RACF.
For more information about MQSC commands, see Administering IBM MQ using MQSC commands.
To refresh z/OS classes:

Procedure
1. In the Navigator view, right-click the queue manager for which you want to refresh the classes, then, to
refresh all of the classes, click Security > Refresh ESM Classes > ALL. Alternatively, instead of clicking
ALL, click the type of class that you want to refresh:
2. When prompted, click Yes.

Results
The classes that you selected are refreshed: the profiles are deleted from the in-storage table and must
be retrieved directly from RACF next time they are needed.
Related tasks
“Refreshing the authorization service information on Multiplatforms” on page 167
On Multiplatforms, if you make a change to an entity, you must refresh the entity information in the
authorization service. You must do this for each queue manager that is affected by the changes that you
make to the entity.
“Refreshing TLS security” on page 168
You can make changes to the key repository without restarting a channel. However, the copy of the key
repository that is held in memory while a channel is running will not be affected. When you refresh the
cached copy of the key repository, the TLS channels that are currently running on the queue manager are
updated with the new information.
“Refreshing the connection authentication configuration” on page 168

170 IBM MQ Explorer

 If the configuration for connection authentication changes, you must refresh the queue manager's view of
this configuration.

Viewing the status of objects

You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

About this task

Complete any of the following tasks:
1. View the status of an object
2. View the status of all objects of a specific type for a selected queue manager
3. View the status of multiple instances of the same receiver channel

Procedure
• [OPTION 1] View the status of an object
a) In the Content view, right-click the object, then click Status...
b) If you are viewing a channel definition's status, click Channel Status to view the current status of
the channel, or Saved Status to view the saved status of the channel.
c) The Status dialog for the object opens, displaying the status information that you requested.
• [OPTION 2] View the status of all objects of a specific type for a selected queue manager
a) In the Explorer view, right-click the folder of objects (for example Queues) for a selected queue
manager, then click Status....
A new Content view is displayed in a separate window.
b) The status of all the objects in the object-folder are displayed in the new Content view window.
• [OPTION 3] View the status of multiple instances of the same receiver channel
Different applications can use different instances of the same receiver channel at the same time. It is
possible for these different instances to have different statuses.
There are two ways to view the status of multiple channel instances in the IBM MQ Explorer:
a) In the Content view, right-click the channel, then click Status... You can view the current status of
the channel (click Channel Status) or the saved status of the channel (click Saved Status).
All the statuses for the individual instances are aggregated into a single status displayed in the
Content view.
b) In the Navigator view, right-click the channels folder of your selected queue manager, then click
Status. You can view the current status of the channel (click Channel Status) or the saved status of
the channel (click Saved Status).
A new Content view is opened in a separate window. The status of all the objects in the folder are
displayed in the new Content view window. All of the channel instances and the individual statuses
are displayed in the Content view.
The aggregated status displayed is dependent on the number of instances and their different statuses,
as follows:
– There are no channel instances: Status is shown as Inactive.
– There is a single channel instance: Status is shown as the actual status of the channel.
– There are more than 1 instances, all with the same status: Status is shown as the actual status of
the channels.
– There are more than 1 instances, with mixed statuses: Status is shown as Mixed.

Introduction to IBM MQ Explorer 171

 Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Status attributes” on page 515
In IBM MQ Explorer, you can view the current status of IBM MQ objects. For example, you can find out
whether a channel is running, or you can find out when the last message was put on a certain queue. You
can also view the saved status of a channel.

Viewing and closing connections to applications

You can use the Application Connections dialog to find out which applications are currently connected
to a specific queue manager, and which queue manager objects an application is currently accessing. You
can also use this dialog to close a connection.

About this task

Before you delete an IBM MQ object, or change its attributes, check whether any applications are
currently connected to the queue manager or accessing its objects. The Application Connections dialog
displays the applications that are currently connected to a specific queue manager, and which queue
manager objects the application is currently accessing.
You can use the Application Connections dialog to close a connection. Be aware that when you close a
connection between an application and a queue manager, the application can no longer access any of the
queue manager's objects. This might prevent the application from working correctly.
To view a list of the applications that are connected to a queue manager:

Procedure
1. In the Navigator view, right-click the queue manager, then click Application Connections. The
Application Connections dialog opens.
2. In the Application Connections dialog, the first table lists the applications that are currently
connected to the queue manager.
3. Click an application to display, in the second table, a list of the objects on the queue manager that the
application is accessing.
4. Optional: Close a connection:
a) Click the name of the application, then click Close Connection.
b) When you are prompted, click Yes to confirm that you want to close the connection.
The connection between the application and the queue manager is closed.

Results
If you closed a connection, the application that used that connection can no longer access the queue
manager's objects.

Creating and configuring JMS administered objects

You can use IBM MQ Explorer to configure the JMS administered objects that enable communication
between Java applications and IBM MQ.

About this task

The Java Message Service (JMS) is a Java API that allows applications that are written in Java to the JMS
specification to communicate with any messaging product that implements the JMS API. Because the

172 IBM MQ Explorer

JMS API is an open standard and has multiple implementations, you can select which messaging provider
(the JMS provider) to use according to your requirements.
IBM MQ is a JMS provider; it provides a messaging system that implements both current versions of the
JMS API:

• Java Message Service (JMS 2.0)

• Jakarta Messaging 3.0

Note: For Jakarta Messaging 3.0, you cannot administer JNDI using IBM MQ Explorer. JNDI
administration is supported by the Jakarta Messaging 3.0 variant of JMSAdmin, which is JMS30Admin.
You can use the IBM MQ graphical user interface, IBM MQ Explorer, to configure the JMS administered
objects that enable communication between the Java application (the JMS client) and IBM MQ (the JMS
provider).
There are two types of JMS administered objects in IBM MQ classes for JMS:
• Connection factories, which the JMS client uses to create connections to the JMS provider.
• Destinations, which the JMS client uses to represent the target and source of messages.
The administered objects are stored in a naming and directory service that is accessed by IBM MQ
Explorer using the Java Naming Directory Interface (JNDI) API. The administered objects are stored in
locations on the naming and directory service known as the JNDI namespaces. There are various JNDI
service providers that you can use as the naming and directory service, including Lightweight Directory
Access Protocol (LDAP) and local or remote file systems.
Because the JMS client uses the JMS administered objects to connect to the JMS provider, you configure
the administered objects to define how the JMS client sends and receives, or publishes and subscribes,
messages. The JMS client does not directly communicate with the JMS provider and is unaware of which
JMS provider is being used. This means that you can change the JMS provider without having to update
the JMS client.
To configure IBM MQ classes for JMS so that a JMS client can connect to and access administered objects
in a JNDI namespace, you must perform the following tasks in IBM MQ Explorer:

Procedure
1. Connect to the JNDI namespace. For more information, see Adding an initial context.
2. Create and configure the administered objects that are stored in the JNDI namespace. For more
information, see Creating a connection factory and Creating a destination.

Results
For more information about programming JMS applications and configuring IBM MQ classes for JMS, see
Using IBM MQ classes for JMS.
Related concepts
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
“JMS destinations (queues and topics)” on page 177

Introduction to IBM MQ Explorer 173

 A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.

JMS contexts
A context is a set of bindings that associates names with objects stored in a naming and directory service.
JMS clients (Java applications that use the JMS API) use contexts to look up the names of the JMS
objects in the naming and directory service. Every context has a naming convention associated with it.
For more information about LDAP naming considerations, see Configuring the JMS administration tool.

Initial contexts
For each location in the naming and directory service, you need to specify an initial context to give a
starting point from which the JMS client can resolve the names of the objects in that location of the
naming and directory service. JMS clients access the objects in the naming and directory service through
the Java Naming Directory Interface (JNDI); the location in the naming and directory service that is
defined by the context is known as the JNDI namespace.
When you specify an initial context in IBM MQ Explorer, the full contents of the JNDI namespace are
displayed but, in IBM MQ Explorer, you can edit only the IBM MQ classes for JMS objects that are stored
there. All of the initial contexts that you add to IBM MQ Explorer are displayed in the Navigator view in the
JMS Administered Objects folder, as shown in the following figure.
In the figure, File System Initial Context is the initial context for a location in the
local filesystem: C:/JMSAdmin/JMSAdmin1 and LDAP Initial Context is the initial context
for a location on an LDAP server, on a computer called hiss with the distinguished name
cn=JMSData,dc=ibm,dc=uk.

When you have added the initial context to IBM MQ Explorer, you can create connection factory objects,
destination objects, and subcontexts in the JNDI namespace.

Subcontexts
A subcontext is a subdivision of a JNDI namespace and can contain connection factories and destinations
as well as other subcontexts. A subcontext is not an object in its own right; it is merely an extension of
the naming convention for the objects in the subcontext. You can create multiple subcontexts in a single
context.
In the following figure, the subcontext called A Subcontext is bound to the initial context called
File System Initial Context. In the file system where the context and subcontext are stored,
the subcontext is a sub-directory of the initial context; other JNDI implementations, such as LDAP, might
store subcontexts differently.

174 IBM MQ Explorer

 You can create connection factory objects, destination objects, and other subcontexts in a subcontext.
Related concepts
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
Related tasks
“Adding an initial context” on page 178
To create and configure JMS objects in IBM MQ Explorer, you must add an initial context to define the root
of the JNDI namespace in which the JMS objects are stored in the naming and directory service.
“Connecting and disconnecting an initial context” on page 180
You can connect or disconnect IBM MQ Explorer to an initial context that is displayed in the JMS
Administered Objects folder. You can also configure each initial context so that IBM MQ Explorer
automatically reconnects to it the next time that you close and restart IBM MQ Explorer.
“Creating a subcontext” on page 188
A subcontext is a subdivision of a JNDI namespace and can contain connection factories and destinations
as well as other subcontexts. You can create subcontexts within initial contexts or within other
subcontexts.
Related information
https://docs.oracle.com/javase/jndi/tutorial/TOC.html

JMS connection factories

A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
You can use IBM MQ Explorer to create connection factories and to define the connection parameters that
the connection factory will use to create connections.

Introduction to IBM MQ Explorer 175

 Connection factories, like destinations, are administered objects and are stored in a JNDI namespace,
which is a defined location within the naming and directory service. The initial context defines the root
of the JNDI namespace. In IBM MQ Explorer, all connection factories are stored in Connection Factories
folders in the appropriate context and subcontexts, as shown in the following figure.
In the figure, the connection factory that is called Connection Factory 1 is stored in the Connection
Factories folder of the initial context called File System Initial Context.

When you define a connection factory, you select the messaging provider that is used as the JMS provider
(for example, IBM MQ or Real-time); a connection factory can create connections only to that messaging
provider. For the JMS client to create connections to a different messaging provider, you must create a
new connection factory and specify the messaging provider. Real-time transport is not available in IBM
MQ 8.0. If you are using IBM MQ 8.0 you can define Real-time transport, but it fails when an attempt is
made to create a connection.

Domain-independent connection factories

There are two messaging domains: the point-to-point messaging domain and the publish/subscribe
messaging domain. You can create a connection factory to create connections specifically for point-
to-point messaging (using the QueueConnectionFactory interface) or specifically for publish/subscribe
messaging (using the TopicConnectionFactory interface). From JNDI, you can also create connection
factories that are domain independent and so can be used for both point-to-point and publish/subscribe
messaging (using the ConnectionFactory interface). For more information, see Creating a connection
factory.
If the JMS application is intended to use only point-to-point messaging or only publish/subscribe
messaging, you can select the specific messaging domain when you create the connection factory and a
domain-specific connection factory is created.
If, however, you want to perform both point-to-point and publish/subscribe work under the same
transaction, you can create a domain-independent connection factory. For example, you might want a
JMS application to subscribe to a topic (publish/subscribe messaging) then when the JMS application
receives a particular message, it sends another message to a queue (point-to-point messaging). It is
difficult to reliably perform both point-to-point and publish/subscribe work under the same transaction
if you use domain-specific connection factories: you must create a separate connection factory for
each messaging domain, which means that the point-to-point work is done under a transaction that is
controlled by the QueueSession session and the publish/subscribe work is done under a transaction that
is controlled by the TopicSession session. It is difficult to ensure that the send and receive actions either
both happened or both were backed out.
Instead of creating one domain-specific connection factory for the point-to-point work and one domain-
specific connection factory for the publish/subscribe work, you can create a single domain-independent
connection factory for both. This means that the connection factory creates one connection, which
creates one session. The session creates a MessageConsumer from a topic and a MessageProducer to a

176 IBM MQ Explorer

 queue. When the JMS application receives the published message, the next message can be sent to the
queue under the same session's transaction; both operations can then be committed or rolled back as a
single unit of work.
For more information, see Using IBM MQ classes for JMS.
Related concepts
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
Related tasks
“Creating a connection factory” on page 182
A JMS client (a Java application that uses the JMS API) uses connection factories to create connections to
the JMS provider (a messaging provider such as IBM MQ).

JMS destinations (queues and topics)

A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
The JMS client can use a single destination object to put messages on and to get messages from, or the
JMS client can use separate destination objects. The same destination object can be used for both IBM
MQ and Real-time messaging providers so, unlike with connection factories, you do not need to create
separate destination objects for different messaging providers. Real-time transport is not available in IBM
MQ 8.0. If you are using IBM MQ 8.0 you can define Real-time transport, but it fails when an attempt is
made to create a connection.
In the figure, the destination called Destination 1 is stored in the Destinations folder of the initial
context called File System Initial Context.

When you create a destination object, you must specify whether the destination is a JMS queue (in
the point-to-point messaging domain) or a JMS topic (in the publish/subscribe messaging domain); you
cannot change the domain after the destination has been created. You must also configure the destination
with the name of the queue or topic that the destination represents. An advantage of using JMS is that you
can change the name of the queue or topic that the JMS client uses by changing the value of a property in
the destination definition and you do not update the JMS client itself.
For more information, see Using IBM MQ classes for JMS and Publish/subscribe messaging.
Related concepts
“IBM MQ queues” on page 15

Introduction to IBM MQ Explorer 177

 A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.

Messaging providers for IBM MQ classes for JMS

A JMS client (a Java application that uses the JMS API) uses a connection factory to create a connection
with the JMS provider. The messaging provider that is used as the JMS provider determines which types
of transport are available to use for the connection.
If you are using point-to-point messaging or if you are using the IBM MQ Publish/Subscribe broker for
publish/subscribe messaging, you must use IBM MQ as the messaging provider. The JMS client, therefore,
connects to a queue manager and the type of transport that the connection uses depends on whether the
JMS client is on the same computer as the queue manager:
• If the JMS client is on a different computer from the queue manager, the JMS client must use a client
connection (TCP/IP) to connect to the queue manager.
• If the JMS client is on the same computer as the queue manager, the JMS client can connect to the
queue manager directly using bindings or using a client connection (TCP/IP).
When you create a connection factory, you select which messaging provider will be used as the JMS
provider. This constrains the connection factory to creating connections suitable only for the selected
messaging provider. If you want to change messaging provider, you must create a new connection factory
and specify a different messaging provider. For more information, see Creating a connection factory.
You can, however, change the type of transport used as long as the new transport is appropriate for the
selected messaging provider. To do this, you must change the transport type that is associated with the
connection factory that the JMS client uses to create connections. For more information, see Changing the
transport type used for connections.
Related concepts
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
Related tasks
“Creating a connection factory” on page 182
A JMS client (a Java application that uses the JMS API) uses connection factories to create connections to
the JMS provider (a messaging provider such as IBM MQ).
“Changing the transport type used for connections” on page 187
You can change the transport type that a JMS client uses to connect to a JMS provider. You might also
need to change any properties and settings that are required by the new transport type.

Adding an initial context

To create and configure JMS objects in IBM MQ Explorer, you must add an initial context to define the root
of the JNDI namespace in which the JMS objects are stored in the naming and directory service.

About this task

You must add an initial context for each JNDI namespace that you want to access. All of the initial
contexts that you add to IBM MQ Explorer are displayed in the JMS Administered Objects folder in the
Navigator view.
To add an initial context to the JMS Administered Objects folder in IBM MQ Explorer, complete the
following steps.

Procedure
1. In the Navigator view, right-click the JMS Administered Objects folder, then click Add Initial Context
The Add Initial Context wizard opens.

178 IBM MQ Explorer

2. Select the location of the JNDI namespace in the naming and directory service:
• Click LDAP server if the JNDI namespace is located on an LDAP server. You must know the following
connection details:
– The host name of the LDAP server.
– The distinguished name of the location of the JNDI namespace.
• Click File system if the JNDI namespace is located in a file system. You must know the following
connection details:
– The path to the location of the JNDI namespace in the file system.
• Click Other if the JNDI namespace is located somewhere else. You must know the following
connection details:
– The name and location of the initial context factory class of the JNDI service provider.
– The URL of the location of the JNDI namespace.
3. If the JNDI namespace is on an LDAP server, or is provided by some other JNDI service provider that
requires authentication, select the type of authentication that IBM MQ Explorer must use to connect to
the JNDI namespace:
• Click None to use anonymous authentication to connect to the JNDI namespace. The JNDI does not
pass any security credentials to the service provider from IBM MQ Explorer.
• Click Simple authentication if IBM MQ Explorer must pass security credentials to the JNDI service
provider.
• Click CRAM-MD5 authentication if IBM MQ Explorer must pass security credentials of CRAM-MD5
standard to the JNDI service provider.
4. Optional: Edit the nickname that will be used to display the initial context in IBM MQ Explorer. By
default, the location of the JNDI namespace is used but you can change it to something that is easier
to read and recognize.
5. Optional: Select whether IBM MQ Explorer automatically connects to the initial context:
• Select the Connect immediately on finish check box to connect to the initial context when the
wizard closes.
If you clear this check box, when the wizard closes, the initial context is added to the JMS
Administered Objects folder but IBM MQ Explorer cannot access the JMS objects in the JNDI
namespace until you connect to the initial context.
• Select the Automatically reconnect to context on startup check box if you want IBM MQ Explorer
to automatically reconnect to the initial context every time that you close and re-open IBM MQ
Explorer.
6. Click Finish.

Results
The initial context is added to the JMS Administered Objects folder in the Navigator view. If IBM MQ
Explorer is connected to the initial context, you can now create connection factory objects, destination
objects, and subcontexts in the initial context.
Related concepts
“JMS contexts” on page 174
A context is a set of bindings that associates names with objects stored in a naming and directory service.
Related tasks
“Connecting and disconnecting an initial context” on page 180
You can connect or disconnect IBM MQ Explorer to an initial context that is displayed in the JMS
Administered Objects folder. You can also configure each initial context so that IBM MQ Explorer
automatically reconnects to it the next time that you close and restart IBM MQ Explorer.
“Removing an initial context” on page 181

Introduction to IBM MQ Explorer 179

 If you no longer want to access and administer JMS objects in a particular JNDI namespace, you can
remove the initial context that defines the root of the JNDI namespace from the JMS Administered
Objects folder in IBM MQ Explorer.
“Creating a connection factory” on page 182
A JMS client (a Java application that uses the JMS API) uses connection factories to create connections to
the JMS provider (a messaging provider such as IBM MQ).
“Creating a destination” on page 183
A JMS client uses a destination object to specify the target of messages that the JMS client produces
and the source of messages that the JMS client receives. Destination objects can represent queues (for
point-to-point messaging) or topics (for publish/subscribe messaging).
“Creating a subcontext” on page 188
A subcontext is a subdivision of a JNDI namespace and can contain connection factories and destinations
as well as other subcontexts. You can create subcontexts within initial contexts or within other
subcontexts.

Connecting and disconnecting an initial context

You can connect or disconnect IBM MQ Explorer to an initial context that is displayed in the JMS
Administered Objects folder. You can also configure each initial context so that IBM MQ Explorer
automatically reconnects to it the next time that you close and restart IBM MQ Explorer.

About this task

To administer IBM MQ classes for JMS objects in IBM MQ Explorer, IBM MQ Explorer must be connected
to the initial context that defines the root of the JNDI namespace in which the JMS objects are stored.
If IBM MQ Explorer is disconnected from the initial context, the context is still displayed in the JMS
Administered Objects folder but you cannot view or administer the objects in JNDI namespace.
Complete either of the following tasks:
1. Connect or disconnect an initial context that is displayed in the JMS Administered Objects folder.
2. Enable or cancel automatic reconnection to an initial context.

Procedure
• [OPTION 1] Connect or disconnect an initial context that is displayed in the JMS Administered Objects
folder.
a) If the JNDI namespace is on a different computer to IBM MQ Explorer, ensure that the naming and
directory service is available.
b) In the Navigator view, right-click the initial context, then click Connect or Disconnect as required.
c) If the JNDI service provider requires authentication (for example, LDAP), enter your authentication
details when prompted.
IBM MQ Explorer connects or disconnects the initial context. The color of the initial context's icon
changes to show its status: gray if it is disconnected; blue if it is connected.
If you disconnect an initial context that is configured so that IBM MQ Explorer automatically
reconnects to it, the next time that you close and restart IBM MQ Explorer, the initial context is
reconnected.
If you want to remove the initial context completely from IBM MQ Explorer, see Removing an initial
context.
• [OPTION 2] Enable or cancel automatic reconnection to an initial context.
You can configure each initial context so that IBM MQ Explorer automatically reconnects to it the
next time that you close and restart IBM MQ Explorer. If you do not configure an initial context to
automatically reconnect, when you close and restart IBM MQ Explorer, it is not reconnected.

180 IBM MQ Explorer

 If the initial context is in a naming and directory service that requires authentication (for example, an
LDAP server), when you start IBM MQ Explorer, you are prompted for the authentication details for
each initial context that requires authentication and is set to automatically reconnect.
– When you add an initial context to the JMS Administered Objects folder in IBM MQ Explorer, select
the Automatically reconnect on startup check box in the Add New Context wizard.
– In the Navigator view, for initial contexts that are already shown in the JMS Administered Objects
folder, right-click the initial context then click Autoreconnect. A check mark is placed next to the
menu item to indicate that the initial context is set to automatically reconnect to IBM MQ Explorer
on startup.
– To cancel automatic reconnection, right-click the initial context then click Autoreconnect. The
check mark next to the menu item is removed.

Related concepts
“JMS contexts” on page 174
A context is a set of bindings that associates names with objects stored in a naming and directory service.
Related tasks
“Adding an initial context” on page 178
To create and configure JMS objects in IBM MQ Explorer, you must add an initial context to define the root
of the JNDI namespace in which the JMS objects are stored in the naming and directory service.
“Removing an initial context” on page 181
If you no longer want to access and administer JMS objects in a particular JNDI namespace, you can
remove the initial context that defines the root of the JNDI namespace from the JMS Administered
Objects folder in IBM MQ Explorer.

Removing an initial context

If you no longer want to access and administer JMS objects in a particular JNDI namespace, you can
remove the initial context that defines the root of the JNDI namespace from the JMS Administered
Objects folder in IBM MQ Explorer.

About this task

Removing the initial context from the JMS Administered Objects folder in IBM MQ Explorer does not
delete the JNDI namespace and the objects that it contains from the naming and directory service. If you
later want to administer the JMS objects using IBM MQ Explorer, you can add the initial context again; for
more information, see Adding an initial context.
If you do not want to administer JMS objects in the JNDI namespace now but intend to do so later, you
can disconnect from the initial context without removing it from IBM MQ Explorer; for more information,
see Connecting and disconnecting an initial context.
To remove an initial context from IBM MQ Explorer:

Procedure
1. In the Navigator view, right-click the initial context, then click Remove
2. When prompted, click Yes.

Results
The initial context is removed from the JMS Administered Objects folder in IBM MQ Explorer. The JNDI
namespace is not deleted from the naming and directory service so you can add the initial context to IBM
MQ Explorer again later.
Related concepts
“JMS contexts” on page 174

Introduction to IBM MQ Explorer 181

 A context is a set of bindings that associates names with objects stored in a naming and directory service.
Related tasks
“Adding an initial context” on page 178
To create and configure JMS objects in IBM MQ Explorer, you must add an initial context to define the root
of the JNDI namespace in which the JMS objects are stored in the naming and directory service.
“Connecting and disconnecting an initial context” on page 180
You can connect or disconnect IBM MQ Explorer to an initial context that is displayed in the JMS
Administered Objects folder. You can also configure each initial context so that IBM MQ Explorer
automatically reconnects to it the next time that you close and restart IBM MQ Explorer.

Creating a connection factory

A JMS client (a Java application that uses the JMS API) uses connection factories to create connections to
the JMS provider (a messaging provider such as IBM MQ).

About this task

When you define a connection factory, you select the messaging provider that is to be used as the JMS
provider. If you want to change the JMS provider, you must create a new connection factory for the new
JMS provider.
The initial context for the JNDI namespace in which you want to create the connection factory must be
displayed in the JMS Administered Objects folder and must be connected to IBM MQ Explorer.
To create a connection factory object, complete the following steps.

Procedure
1. In the Navigator view, expand the JMS Administered Objects folder, then expand the initial context
(and subcontexts, if necessary) for the JNDI namespace in which the connection factory will be stored.
2. Right-click the Connection Factories folder, then click New > Connection Factory.... The New
Connection Factory wizard opens.
3. In the wizard, type a name for the connection factory and select the messaging provider to which the
JMS client will use the connection factory to connect, then click Next:
• If you are using point-to-point messaging or if you are using the IBM MQ Publish/Subscribe broker,
click IBM MQ.
4. Select the type of connection factory that you want to create:
• Click Connection Factory if the JMS application will use both point-to-point messaging and publish/
subscribe messaging, especially if you want the JMS application to perform both types of messaging
under the same transaction.
• Click Queue Connection Factory if the JMS application will use only point-to-point messaging.
• Click Topic Connection Factory if the JMS application will use only publish/subscribe messaging.
5. Optional: To support XA transactions, select the Support XA transactions check box. XA transactions
are not supported if you are using Real-time as the messaging provider.
6. Click Next.
7. Select the type of transport that will be used by the connections that are created by the connection
factory, then click Next:
• If the JMS client that uses the connection factory is on a different computer from the queue
manager, click MQ Client. This means that the connection uses TCP/IP. If you select MQ Client
and you selected the Support XA transactions check box on the previous page of the wizard, you
must install the Java Extended Transaction Support component of IBM MQ.
• If the JMS application using the connection factory runs on the same computer as the queue
manager, you can click MQ Client (see the previous option for more information) or you can click
Bindings, which means that the JMS client connects directly to the queue manager.

182 IBM MQ Explorer

 • If the JMS client that uses the connection factory will connect to the Real-time broker using TCP/IP,
click Direct.
• If the JMS client that uses the connection factory will connect to the Real-time broker using HTTP
tunneling, click Direct HTTP.
Note: Real-time transport is not available in IBM MQ 8.0. If you are using IBM MQ 8.0 you can define
Real-time transport, but it fails when an attempt is made to create a connection.
8. Optional: If you want to create the connection factory object with the same attributes as an existing
connection factory, select the Create with attributes like an existing JNDI object, then click Select
to select the existing connection factory.
9. Click Finish.

Results
The new connection factory is displayed in the Content view of the Connection Factories folder.
Related concepts
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
Related tasks
“Creating a destination” on page 183
A JMS client uses a destination object to specify the target of messages that the JMS client produces
and the source of messages that the JMS client receives. Destination objects can represent queues (for
point-to-point messaging) or topics (for publish/subscribe messaging).
“Creating a subcontext” on page 188
A subcontext is a subdivision of a JNDI namespace and can contain connection factories and destinations
as well as other subcontexts. You can create subcontexts within initial contexts or within other
subcontexts.
“Changing the transport type used for connections” on page 187
You can change the transport type that a JMS client uses to connect to a JMS provider. You might also
need to change any properties and settings that are required by the new transport type.
“Deleting an administered object” on page 190
When you delete an administered object in IBM MQ Explorer, the administered object no longer exists in
the JNDI namespace in the naming and directory service.
“Renaming an administered object” on page 189
When you have created an administered object (connection factories and destinations), you can
subsequently rename it in IBM MQ Explorer.

Creating a destination
A JMS client uses a destination object to specify the target of messages that the JMS client produces
and the source of messages that the JMS client receives. Destination objects can represent queues (for
point-to-point messaging) or topics (for publish/subscribe messaging).

Before you begin

• Add the initial context in which you want to create the destination.
• Connect to the initial context.

About this task

To create a destination object, complete the following steps.

Introduction to IBM MQ Explorer 183

 Procedure
1. In the Navigator view, expand the JMS Administered Objects folder, then expand the initial context
(and subcontexts, if necessary) in which the destination will be stored in the JNDI naming and
directory service.
2. Right-click the Destinations folder, then click New > Destination. The New Destination wizard opens.
3. In the wizard, type a name for the destination, then click Next.
4. Select the type of destination that you want to create, then click Next:
• If you are using point-to-point messaging, click Queue.
• If you are using publish/subscribe messaging, click Topic.
5. Optional: If you want to create the destination object with the same attributes as an existing
destination, select the Create with attributes like an existing JNDI object, then click Select to select
the existing destination.
6. Click Finish.

Results
The new destination is displayed in the Content view of the Destinations folder.
Related concepts
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
Related tasks
“Creating a connection factory” on page 182
A JMS client (a Java application that uses the JMS API) uses connection factories to create connections to
the JMS provider (a messaging provider such as IBM MQ).
“Creating a subcontext” on page 188
A subcontext is a subdivision of a JNDI namespace and can contain connection factories and destinations
as well as other subcontexts. You can create subcontexts within initial contexts or within other
subcontexts.
“Deleting an administered object” on page 190
When you delete an administered object in IBM MQ Explorer, the administered object no longer exists in
the JNDI namespace in the naming and directory service.
“Renaming an administered object” on page 189
When you have created an administered object (connection factories and destinations), you can
subsequently rename it in IBM MQ Explorer.
“Creating a JMS object from an IBM MQ object” on page 186
You can create new JMS administered objects based on your existing IBM MQ objects.

Creating a JMS object and an IBM MQ object simultaneously

When you create a new JMS object, you can optionally create a corresponding IBM MQ object of the same
type.

Before you begin

• You must have an IBM MQ queue manager. If one does not exist, you can create one as described in:
“Creating and configuring queue managers and objects” on page 13
• You must have a JMS initial context. If one does not exist, you can create one as described in: Add the
initial context that will contain the JMS topic
• You must be connected to the JMS initial context as described in: Connect to the initial context

184 IBM MQ Explorer

About this task
With the object creation wizards in IBM MQ Explorer, you can create an IBM MQ object and a JMS object
simultaneously. You begin by launching your required object wizard, for example; an IBM MQ queue. Then
you select the option to launch another wizard, for example; a JMS queue, once the object has been
created. The second object wizard must be of the same object type, and the properties of one are mapped
to the other.
Complete either of the following tasks:
1. Create a JMS queue and an IBM MQ queue simultaneously.
2. Create a JMS topic and an IBM MQ topic simultaneously.

Procedure
• [OPTION 1] Create a JMS queue and an IBM MQ queue simultaneously.
When you create a new JMS queue in IBM MQ Explorer, you can choose to launch the IBM MQ New
Local Queue wizard to create an IBM MQ queue immediately after the New JMS Destination wizard
has finished. The New Local Queue wizard now contains the details you entered when creating the
JMS queue.
a) Select the JMS Initial Context you want to add a new JMS queue to in the Navigator view, and
right-click on its Destinations initial context object folder.
b) Click New > Destination to open the New Destination wizard.
c) Type a name for your queue, then select Queue in the Type field.
d) Select Start wizard to create a matching MQ Queue. Continue through the wizard to create your
queue.
After you have completed the New Destination wizard, the New MQ Queue wizard opens, with many
of the JMS queue details mapped to the IBM MQ queue.
• [OPTION 2] Create a JMS topic and an IBM MQ topic simultaneously.
When you create a new JMS topic in IBM MQ Explorer, you can choose to launch the IBM MQ New
Topic wizard to create an IBM MQ topic immediately after the New JMS Destination wizard has
finished. The New Topic wizard now contains the details you entered when creating the JMS topic.
a) Select the JMS Initial Context you want to add a new JMS topic to in the Navigator view, and
right-click on its Destinations initial context object folder.
b) Click New > Destination to open the New Destination wizard.
c) Type a name for your topic, then select Topic in the Type field.
d) Select Start wizard to create a matching MQ Topic. Continue through the wizard to create your
topic.
After you have completed the New Destination wizard, the New Topic wizard opens, with many of the
JMS topic details mapped to the IBM MQ topic.
Related tasks
“Creating a destination” on page 183
A JMS client uses a destination object to specify the target of messages that the JMS client produces
and the source of messages that the JMS client receives. Destination objects can represent queues (for
point-to-point messaging) or topics (for publish/subscribe messaging).
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Creating an IBM MQ object from a JMS object” on page 34

Introduction to IBM MQ Explorer 185

 You can create new IBM MQ queues and topics based on your existing JMS queues and topics. The values
of relevant properties of the JMS object are copied to the new IBM MQ object. In future, however, if you
make a change to one of the objects, the changes are not reflected in the other object.
“Creating a JMS object from an IBM MQ object” on page 186
You can create new JMS administered objects based on your existing IBM MQ objects.
Related reference
“Destination properties” on page 500
You can view and set destination properties in the Destination properties dialog. The properties that are
available in the dialog depend on the type of destination.
“Connection factory properties” on page 469
You can view and set connection factory properties in the Connection Factory properties dialog. The
properties that are available in the dialog depend on which messaging provider the connection factory
uses.

Creating a JMS object from an IBM MQ object

You can create new JMS administered objects based on your existing IBM MQ objects.

Before you begin

• Show the queue manager that hosts the IBM MQ queue or topic.
• Create and configure queue managers and objects.
• Add an initial context.

About this task

To create a JMS administered object from an existing IBM MQ object, complete the following steps.

Procedure
1. In the Navigator view, expand the queue manager that hosts the IBM MQ object (either an IBM MQ
queue or IBM MQ topic), then click the Queues or Topics folder as appropriate to list the objects in the
Content view.
2. In the Content view, right-click the object, then click Create JMS Queue or Create JMS Topic as
appropriate.
The New Destination wizard opens.
3. In the wizard, click Select, then select the JMS context in which you want to create the new JMS
object.
The JMS context's name is displayed in the JMS Context field of the wizard.
4. Work through the wizard to define the new JMS object, then click Finish.

Results
The new JMS administered object is created and displayed under the appropriate JMS context in IBM MQ
Explorer.

What to do next
You can now continue to configure the JMS object as necessary.
To create a JMS object and an IBM MQ object simultaneously, follow the instructions in: “Creating a JMS
object and an IBM MQ object simultaneously” on page 184 or “Creating an IBM MQ object and a JMS
object simultaneously” on page 35
Related tasks
“Creating a destination” on page 183

186 IBM MQ Explorer

 A JMS client uses a destination object to specify the target of messages that the JMS client produces
and the source of messages that the JMS client receives. Destination objects can represent queues (for
point-to-point messaging) or topics (for publish/subscribe messaging).
“Creating a JMS object and an IBM MQ object simultaneously” on page 184
When you create a new JMS object, you can optionally create a corresponding IBM MQ object of the same
type.
“Creating an IBM MQ object and a JMS object simultaneously” on page 35
When you create a new IBM MQ object, you can optionally create a corresponding JMS object of the same
type.

Copying an administered object

To copy an administered object in IBM MQ Explorer, you create a new object based on the existing object
that you want to copy.

About this task

To create a copy of an existing JMS administered object, complete the following steps.

Procedure
1. In the Navigator view, right-click the relevant object folder, then open the New wizard.
For example, right-click the Connection Factories folder, then click New > Connection Factory.
2. Select the options that you require until you get to page of the wizard on which you can choose to
create the object with attributes like an existing object.
3. Select the Create with attributes like an existing object check box.
4. Click Select The Select the Like Object dialog opens. The dialog lists all of the objects in the JNDI
namespace that match the selections you have already made in the wizard. For example, if you are
creating a connection factory, the dialog lists all the connection factories that use the same transport
type, messaging provider, and connection factory class as the one you are creating.
5. Click the object that you want to base the new object on, then click OK.
6. Click Finish to create the object.

Results
The new object is created with the same attributes as the existing object that you specified.

Changing the transport type used for connections

You can change the transport type that a JMS client uses to connect to a JMS provider. You might also
need to change any properties and settings that are required by the new transport type.

About this task

A JMS client (a Java application that uses the JMS API) uses a connection factory to create a connection
with the JMS provider. The messaging provider that is used as the JMS provider determines which types
of transport are available to use for the connection.
To change the transport used by the JMS client to connect to the JMS provider, complete the following
steps.

Procedure
1. In the Navigator view, click the Connection Factories folder that contains the connection factory for
which you want to change the transport type. The connection factory is displayed in the Content view.
2. In the Content view, right-click the connection factory, then click Switch Transport.

Introduction to IBM MQ Explorer 187

 3. Click the available transport type:
• If you are using IBM MQ as the messaging provider, click either Bindings or Client.
• If you are using Real-time transport as the messaging provider, click either Direct or Direct HTTP.
Real-time transport is not available in IBM MQ 8.0. If you are using IBM MQ 8.0 you can define
Real-time transport, but it fails when an attempt is made to create a connection.
4. Check whether you need to change any properties and settings that are required by the new transport
type; for example, if you are changing from Bindings to Client, you need to set up the client connection
if you have not done so already.

Results
The next time that a connection factory creates a connection for the JMS client, the connection uses the
new type of transport.
Related concepts
“Messaging providers for IBM MQ classes for JMS” on page 178
A JMS client (a Java application that uses the JMS API) uses a connection factory to create a connection
with the JMS provider. The messaging provider that is used as the JMS provider determines which types
of transport are available to use for the connection.
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
Related tasks
“Creating a connection factory” on page 182
A JMS client (a Java application that uses the JMS API) uses connection factories to create connections to
the JMS provider (a messaging provider such as IBM MQ).

Creating a subcontext
A subcontext is a subdivision of a JNDI namespace and can contain connection factories and destinations
as well as other subcontexts. You can create subcontexts within initial contexts or within other
subcontexts.

About this task

A subcontext extends the initial context's naming convention. The extended naming convention is used to
organize the administered objects in the JNDI namespace.
To create a new subcontext within an initial context or within another subcontext, complete the following
steps.

Procedure
1. In the Navigator view, right-click the initial context or subcontext in which you want to create the new
subcontext, then click New > Subcontext... The New Subcontext dialog opens.
2. Type a name for the new subcontext, then click OK.

Results
The new subcontext is displayed in the Navigator view, under the initial context or subcontext in which
you created it.
Related concepts
“JMS contexts” on page 174

188 IBM MQ Explorer

 A context is a set of bindings that associates names with objects stored in a naming and directory service.
Related tasks
“Deleting a subcontext” on page 191
When you delete a subcontext in IBM MQ Explorer, the subcontext no longer exists in the JNDI
namespace.
“Adding an initial context” on page 178
To create and configure JMS objects in IBM MQ Explorer, you must add an initial context to define the root
of the JNDI namespace in which the JMS objects are stored in the naming and directory service.

Renaming an administered object

When you have created an administered object (connection factories and destinations), you can
subsequently rename it in IBM MQ Explorer.

About this task

To rename an administered object, complete the following steps.

Procedure
1. In the Content view, right-click the object that you want to rename, then click Rename The Rename
Object dialog opens.
2. Type a new name for the object, then click OK.

Results
The renamed object is displayed in the Content view.
Related concepts
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
“JMS contexts” on page 174
A context is a set of bindings that associates names with objects stored in a naming and directory service.
Related tasks
“Renaming a context” on page 189
You can rename a subcontext, provided that you have first deleted from the subcontext any objects that
are stored in the subcontext.

Renaming a context
You can rename a subcontext, provided that you have first deleted from the subcontext any objects that
are stored in the subcontext.

About this task

After you have added an initial context to IBM MQ Explorer, you cannot change its nickname; you must
remove then add the initial context to IBM MQ Explorer with the new nickname. You can, however, change
the name of a subcontext.
To rename a subcontext, complete the following steps.

Introduction to IBM MQ Explorer 189

 Procedure
1. Delete from the subcontext any objects that are stored in the subcontext, including IBM MQ classes for
JMS connection factories and destinations, other subcontexts, and any other objects that are shown in
the Content view of the initial context.
2. Refresh the Content view of the subcontext so that IBM MQ Explorer has up-to-date information about
the content of the JNDI namespace.
3. In the Navigator view, right-click the subcontext, then click Rename
The Rename dialog opens. If the Rename menu item is not available, there are still objects in the
subcontext; the objects might not be displayed in IBM MQ Explorer; refresh the Content view to ensure
that IBM MQ Explorer has up-to-date information about the content of the JNDI namespace.
4. Type the new name for the subcontext, then click OK.

Results
The subcontext is renamed.
Related concepts
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
“JMS contexts” on page 174
A context is a set of bindings that associates names with objects stored in a naming and directory service.
Related tasks
“Renaming an administered object” on page 189
When you have created an administered object (connection factories and destinations), you can
subsequently rename it in IBM MQ Explorer.

Deleting an administered object

When you delete an administered object in IBM MQ Explorer, the administered object no longer exists in
the JNDI namespace in the naming and directory service.

About this task

Important: Before you delete an administered object, make sure that none of your JMS client
applications need it. Any JMS client applications that do still need the administered object after you
delete it will no longer work properly.
To delete an administered object, complete the following steps.

Procedure
1. In the Content view, right-click the administered object, then click Delete
2. When you are prompted, click Delete to confirm that you want to delete the administered object.

Results
The administered object is deleted from the JNDI namespace as well as from IBM MQ Explorer.
Related concepts
“JMS connection factories” on page 175

190 IBM MQ Explorer

 A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
“JMS contexts” on page 174
A context is a set of bindings that associates names with objects stored in a naming and directory service.

Deleting a subcontext
When you delete a subcontext in IBM MQ Explorer, the subcontext no longer exists in the JNDI
namespace.

About this task

You cannot delete a subcontext that contains administered objects; you must first delete from the
subcontext all of the connection factories, destinations, and subcontexts in the subcontext.
Important: Before you delete a subcontext, make sure that none of your JMS client applications need any
of the administered objects in subcontext. After you delete the subcontext, any JMS client applications
that do still need these administered objects that were previously in the subcontext will no longer work
properly.
To delete a subcontext, complete the following steps.

Procedure
1. Delete from the subcontext any objects that are stored in the subcontext, including IBM MQ classes for
JMS connection factories and destinations, other subcontexts, and any other objects that are shown in
the Content view of the initial context.
2. Refresh the Content view of the subcontext so that IBM MQ Explorer has up-to-date information about
the content of the JNDI namespace.
3. In the Navigator view, right-click the subcontext, then click Delete...
If the Delete... menu item is not available, there are still objects in the subcontext; the objects might
not be displayed in IBM MQ Explorer; refresh the Content view to ensure that IBM MQ Explorer has
up-to-date information about the content of the JNDI namespace.
4. When you are prompted, click Delete to confirm that you want to delete the subcontext.

Results
The subcontext is deleted from the JNDI namespace as well as from IBM MQ Explorer.
Related concepts
“JMS contexts” on page 174
A context is a set of bindings that associates names with objects stored in a naming and directory service.
“JMS connection factories” on page 175
A connection factory is an object that a JMS client (a JMS program that uses the JMS API) uses to create a
connection with a JNDI provider (a messaging provider such as IBM MQ).
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
Related tasks
“Deleting an administered object” on page 190

Introduction to IBM MQ Explorer 191

 When you delete an administered object in IBM MQ Explorer, the administered object no longer exists in
the JNDI namespace in the naming and directory service.

Configuring IBM MQ Explorer

Use this information to help you to configure your IBM MQ Explorer installation.

About this task

You can customize the way that IBM MQ Explorer presents information to you, including the order of
columns in tables and the objects that are displayed in the Content view. You can also customize a range
of other preferences to suit your business needs. The availability of certain preferences depends on which
plugins you have that are installed and enabled for IBM MQ Explorer.
Key settings can be configured in the Preferences dialog. To open the Preferences dialog: Click Window
> Preferences. Other settings can be configured as per the information in the following table:

Table 5. Options for configuring the settings for IBM MQ Explorer preferences
Type of setting Configuration task Where to find more information
Authorization Displaying object authority settings as “Displaying object authority settings as
service text text” on page 226
Client connections Remote queue managers; specifying “Specifying the default values used to
default values that are used to connect connect to remote queue managers” on
to remote queue managers page 223
TLS Key Repositories; specifying the “Specifying the default location and
default location and default password of default password of TLS certificates” on
TLS certificates page 87
TLS Options; specifying default security “Default security preferences” on page
preferences 161
Security exit; configuring a default “Configuring a default security exit” on
security exit page 160
User identification; enabling default user “Users and groups (entities) in the
identification authorization service” on page 149
Display settings Changing the colors “Changing the colors” on page 221
Defining schemes and filters from the Filtering the objects displayed in the
relevant content view Content view
Setting the order of columns in tables Changing the order of columns in tables
and the objects that are displayed
Changing the refresh frequency of queue “Changing the refresh frequency of
manager information queue manager information” on page
222
Displaying object authority settings as “Displaying object authority settings as
text text” on page 226
Enable Plug-ins Enabling installed plug-ins “Enabling installed plug-ins” on page
221
Managed File Configuring managed file transfer “Configuring Managed File Transfer
Transfer preferences” on page 299
Messages Configuring messages “Configuring message preferences” on
page 300

192 IBM MQ Explorer

 Table 5. Options for configuring the settings for IBM MQ Explorer preferences (continued)
Type of setting Configuration task Where to find more information
Passwords Setting password preferences “Passwords preferences” on page 163
Telemetry Configuring telemetry channels “Telemetry channels” on page 238
Tests Including hidden queue managers in “Including hidden queue managers in
test configurations test configurations” on page 226
Including SYSTEM objects when you run “Including SYSTEM objects when you
tests run tests” on page 225

You can export and import the customizations that you make in IBM MQ Explorer. For more information,
see Exporting and importing settings in MQ Explorer.
Related tasks
“Configuring IBM MQ using IBM MQ Explorer” on page 12
In the Navigator view, you can use the Properties dialog to configure certain IBM MQ properties that
apply to the whole installation. If necessary, you can also configure the properties of individual queue
managers.
Related reference
“Accessibility in IBM MQ Explorer” on page 279
Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.

Filtering the objects displayed in tables

When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.

About this task

An example of the filtering that you can do is that when the Content view displays the contents of a queue
manager's Queues folder, you might choose to display only the queues that have a name that starts with
saturn. Instead of creating a new filter for each type of object on each queue manager, you can create a
filter for a type of object, such as queues, on one queue manager, and then reuse the filter for queues on
other queue managers.
You can filter on the following criteria:
• The name of the object.
• The type of the object (queues and channels only).
• An attribute of the object (optional).
IBM MQ Explorer supplies and applies a standard filter for each type of object. For example, the
Standard for Queues filter includes all the queues so that you can be sure that you are viewing
all the queues on the queue manager, the Standard for Channels filter includes all the channels,
and so on. IBM MQ also supplies a selection of other useful filters; for example, an All queues with
messages filter displays only queues that have one or more messages.
To apply a different filter to a folder of objects:

Procedure
1. In the Content view or dialog that contains the table, click the small arrow next to the current filter
name. A menu is displayed.
2. If you want to apply one of the other supplied filters, in the menu, click the name of the filter. The
menu closes and the filter is applied to the table.

Introduction to IBM MQ Explorer 193

 3. If you want to apply a different filter (that was not supplied with IBM MQ), click More Filters... The
Select Filter dialog opens displaying the filters that are available.
4. In the Apply filter list, click the filter that you want to apply, or click No filter to remove all filtering
from the table.
5. Click OK.

Results
The selected filter is applied to the selected folder.
Related concepts
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.

Creating a filter

About this task

You can create filters for any IBM MQ object, including channels, queues, listeners, and services. A filter
can be applied only to one type of object because different types of objects have different attributes.
The following instructions use an example of creating a filter for queues so that only local queues with
names that start with jupiter and that contain more than 50 messages are displayed in the Content
view. You can easily adapt the instructions to create filters for other types of object too.
To create a new filter:

Procedure
1. In the Content view or dialog that contains the table, click the small arrow next to the current filter
name. A menu is displayed.
2. From the menu, click Manage Filters. The Manage Filters dialog opens displaying the filters that
already exist for the object type.
3. In the Manage Filters dialog, click Add The Add Filter dialog opens.
4. In the Add Filter dialog, in the Filter Name field, type a name for the filter; for example, Queues
containing more than 50 messages
5. Following the Filter Name field, are the Includes objects where fields, in which you can enter the
criteria to add to the new filter. For example, if you are creating a filter for queues, the fields are
labeled Includes Queues where. Enter the following information:
a) The first row of fields allows you to filter on the name of the object. By default, the third field
contains an asterisk (*) so that all objects, regardless of their names, are included in the filter. For
example, to include only the queues that start with jupiter, type jupiter*
b) Queues and channels only: The next row of fields allows you to filter on the type of the object. By
default, the filter includes all types of the object. For example, to include only local queues, select
Local Queue.
c) Optional: You can enter another criteria to the filter based on the value of an attribute of the
objects. Select the check box labeled - and - so that you can edit the fields. For example, to include
only queues that contain more than 50 messages, in the first field, select the attribute Current
queue depth; in the second field, select Greater than; in the third field, type 50.
6. Optional: To automatically apply an existing column scheme when the filter is applied, select the
check box labeled Automatically apply a Column Scheme when this filter is applied, then select the
column scheme from the list.
7. Click OK. The Add Filter dialog closes. The new filter is displayed in the Manage Filters dialog with
any other available filters.

194 IBM MQ Explorer

8. In the Manage Filters dialog, click OK. The Manage Filters dialog closes.

Results
You can now apply the filter to the table.
Related concepts
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
Related tasks
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.
“Editing an existing filter” on page 195
You can edit any filters that you created previously and you can also edit the filters that are supplied with
IBM MQ Explorer; for example, the Default for Queues filter.
“Copying an existing filter” on page 196

Editing an existing filter

You can edit any filters that you created previously and you can also edit the filters that are supplied with
IBM MQ Explorer; for example, the Default for Queues filter.

About this task

You can edit a filter that is currently applied to the table that you are viewing, or edit another filter.
1. Edit the current filter
2. Edit a non-current filter

Procedure
• [OPTION 1] Edit the current filter
a) In the Content view or dialog that contains the table, click the small arrow next to the current filter
name.
A menu is displayed.
b) From the menu, click Edit Current Filter.
The Edit Filter dialog opens.
c) In the Edit Filter dialog, make your changes, then click OK. For more information about the fields in
the dialog, see: “Creating a filter” on page 194.
The changes to the filter are automatically applied to any tables that are using that filter.
• [OPTION 2] Edit a non-current filter
a) In the Content view or dialog that contains the table, click the small arrow next to the current filter
name.
A menu is displayed.
b) From the menu, click Manage Filters.
The Manage Filters dialog opens displaying the filters that exist for the object type.
c) In the Manager Filters dialog, click the filter that you want to edit, then click Edit.
The Edit Filter dialog opens.
d) In the Edit Filter dialog, add, remove, or change the criteria that are set for the filter, then click OK.
For more information about the fields in the dialog, see: “Creating a filter” on page 194.
e) Click OK to close the Manage Filters dialog.

Introduction to IBM MQ Explorer 195

 The changes to the filter are automatically applied to any tables that are using that filter.
Related tasks
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.
“Creating a filter” on page 194
“Copying an existing filter” on page 196

Copying an existing filter

About this task

If there exists a filter that is similar to a filter that you want to create, you can copy the existing filter and
then edit it as required. You can copy any filter that you created previously and you can also copy the
filters that are supplied with IBM MQ Explorer; for example, the Default for Queues filter. You cannot
copy a filter for one type of object to use on another type of object; for example, you cannot copy a filter
for channels to use for filtering queues.
To copy an existing filter:

Procedure
1. Make sure that the type of object for which you are creating a filter is displayed in the Content view,
then click the small arrow next to the current filter name. A menu is displayed.
2. In the Select Filter dialog, click Manage Filters... The Manage Filters dialog opens displaying the filters
that exist for the object type.
3. In the Manage Filters dialog, click the filter that you want to copy, then click Copy As... The Copy Filter
dialog opens.
4. In the Copy Filter dialog, type a name for the new filter, then click OK.
5. In the Manage Filters dialog, click Edit... The Edit Filter dialog opens.
6. In the Edit Filter dialog, add, remove, or change the criteria that are set for the filter, then click OK. For
more information about the fields in the dialog, see Creating a filter.
7. Click OK to close the Manage Filters dialog.

Results
The new filter is available to apply in the Select Filter dialog.
Related tasks
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.
“Creating a filter” on page 194
“Editing an existing filter” on page 195
You can edit any filters that you created previously and you can also edit the filters that are supplied with
IBM MQ Explorer; for example, the Default for Queues filter.
“Copying an existing filter” on page 196

Creating and configuring a service definition

The IBM MQ Service Definition specification provides a standard for documenting IBM MQ applications as
services, using WSDL and URIs.
Service definitions simplify the reuse of IBM MQ applications in service oriented architectures. By
describing applications as services, using the same formats as traditional web services, they can be

196 IBM MQ Explorer

managed in the same way which promotes reuse and enabling integration with standard service tooling.
The service definition wizard validates required information before producing a correctly formatted
service definition, meaning you will not need to have detailed knowledge of both WSDL and the IBM
MQ service definition specification which would be needed to produce service definitions manually.
Service definitions aid the cataloging and governing of IBM MQ applications by allowing the resources
used by an application, such as queues and queue managers, to be easily queried and for services to
be looked up dynamically at runtime. This is particularly true for customers who have unmanaged IBM
MQ applications (not hosted by CICS® or an Application Server, running stand-alone on Windows, UNIX,
System i®, or as batch mainframe applications) which have been developed over time with inconsistent
documentation and no reliable inventory of applications.
The following topics describe how to create service definitions in IBM MQ Explorer:
• “Adding a service definition repository” on page 197
• “Deleting a service definition repository” on page 198
• “Creating a new service definition” on page 198
The following topics describe how to configure existing service definitions in IBM MQ Explorer:
• “Deleting service definitions” on page 199
• “Viewing a service definition WSDL file” on page 200
• “Exporting a WSDL file” on page 200
The following topics describe the various attributes of the properties pages for service definitions sets in
IBM MQ Explorer:
• “IBM MQ service definition properties” on page 401

Note: The IBM MQ Explorer Service Definition Wizard, which was introduced in IBM
WebSphere MQ 7.0, is deprecated for IBM MQ 8.0.

Adding a service definition repository

Use this information to create a new service definition repository.

Before you begin

New service definitions must be created within a file based repository. Multiple repositories can be
created, each containing none, one, or more service definitions. By creating multiple repositories it is
possible to group service definitions together. Repositories cannot be nested, they can only be created
directly beneath Service Definition Repositories in the Navigator view.

About this task

To add a new service definition repository in the Navigator view:

Procedure
1. Right-click on Service Definition Repositories to open the menu, then click Add Repository to open
the Add New Service Definition Repository dialog.
2. Type a name for the new repository and click Finish to close the dialog and create the new repository.
Related tasks
“Deleting a service definition repository” on page 198
Deleting a service definition repository also deletes any service definitions contained within it.
“Creating a new service definition” on page 198
The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0
“Deleting service definitions” on page 199

Introduction to IBM MQ Explorer 197

 Deleting a service definition is permanent. When you delete a service definition, the service definition
cannot be recovered.

Deleting a service definition repository

Deleting a service definition repository also deletes any service definitions contained within it.

Before you begin

When you delete a service definition repository, you also delete all the service definitions contained within
that repository. Neither the repository or service definitions can be recovered.
If a service definition is still required, you have two options available:
• You can create a new service definition in a different repository, and select the Create with attributes
like an existing Service Definition option in the New Service Definition wizard and select your
required service definition.
• You can export a service definition to a new location.

About this task

To delete a repository in the Navigator view:

Procedure
1. Right-click on the repository you want to delete to open the menu, then click Remove.
A confirmation dialog opens.
2. Click Delete to permanently delete the repository and all its stored service definitions.
The confirmation dialog closes and the repository is deleted. It might take a few seconds for the
change to be updated in the Navigator view.
Related tasks
“Adding a service definition repository” on page 197
Use this information to create a new service definition repository.
“Creating a new service definition” on page 198
The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0
“Deleting service definitions” on page 199
Deleting a service definition is permanent. When you delete a service definition, the service definition
cannot be recovered.

Creating a new service definition

The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0

Before you begin

Service definitions simplify the reuse of IBM MQ applications in service oriented architectures. By
describing applications as services, using the same formats as traditional web services, they can be
managed in the same way which promotes reuse and enabling integration with standard service tooling.
The service definition wizard validates required information before producing a correctly formatted
service definition, meaning you will not need to have detailed knowledge of both WSDL and the IBM
MQ service definition specification which would be needed to produce service definitions manually.
Service definitions aid the cataloging and governing of IBM MQ applications by allowing the resources
used by an application, such as queues and queue managers, to be easily queried and for services to
be looked up dynamically at runtime. This is particularly true for customers who have unmanaged IBM
MQ applications (not hosted by CICS or an Application Server, running stand-alone on Windows, UNIX,

198 IBM MQ Explorer

System i, or as batch mainframe applications) which have been developed over time with inconsistent
documentation and no reliable inventory of applications.
You must create a service definition repository before you can define a new service definition. For more
information see “Adding a service definition repository” on page 197

About this task

When you have created a repository in the Navigator view:

Procedure
1. Right-click the repository that you want to define a new service definition in to open the menu.
2. Click New > New Service Definition to open the New Service Definition wizard. As you work through
the wizard, you can press F1 for context sensitive help (Ctrl + F1 on Linux installations)

Results
A new service definition is created inside the selected repository. You can create more than one service
definition inside each repository.

What to do next
Service definition names must be unique within each repository, but can be reused in other repositories.
Related tasks
“Deleting service definitions” on page 199
Deleting a service definition is permanent. When you delete a service definition, the service definition
cannot be recovered.
“Adding a service definition repository” on page 197
Use this information to create a new service definition repository.
“Deleting a service definition repository” on page 198
Deleting a service definition repository also deletes any service definitions contained within it.

Deleting service definitions

Deleting a service definition is permanent. When you delete a service definition, the service definition
cannot be recovered.

About this task

To permanently delete a service definition in the Navigator view, complete the following steps.

Procedure
1. Select the service definition repository which holds the service definition that you want to delete.
2. In the Content view, right-click on the service definition that you want to delete to open the context
menu, then click Delete.
A confirmation dialog opens.
3. Click Delete to permanently delete the service definition.
The confirmation dialog closes and the service definition is deleted. It might take a few seconds for the
change to be updated in the Content view.
Related tasks
“Creating a new service definition” on page 198
The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0
“Adding a service definition repository” on page 197

Introduction to IBM MQ Explorer 199

 Use this information to create a new service definition repository.
“Deleting a service definition repository” on page 198
Deleting a service definition repository also deletes any service definitions contained within it.

Viewing a service definition WSDL file

After you have created a new service definition, you can view the WSDL file that is created.

About this task

To view the contents of the WSDL service definition file, complete the following steps.

Procedure
1. In the Navigator view, select the service definition repository which holds the service definition that
you want to view
2. In the Content view, right-click the service definition that you want to view to open the menu, then
click View.
By default, the WSDL service definition file opens in a new view next to the Navigator view.
Related tasks
“Creating a new service definition” on page 198
The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0
“Deleting service definitions” on page 199
Deleting a service definition is permanent. When you delete a service definition, the service definition
cannot be recovered.
Related reference
“IBM MQ service definition properties” on page 401
You can set properties and attributes for service definitions while creating a new service definition, or
when editing an existing service definition.

Exporting a WSDL file

After you have created a new service definition, you can export the WSDL file to a new location.

About this task

To export the contents of the WSDL service definition file:

Procedure
1. In the Navigator view, select the service definition repository which holds the service definition that
you want to export.
2. In the Content view, right-click the service definition that you want to export to open the menu, then
click Export.
A dialog opens to specify the name and location of the exported file.
Related tasks
“Creating a new service definition” on page 198
The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0
“Deleting service definitions” on page 199
Deleting a service definition is permanent. When you delete a service definition, the service definition
cannot be recovered.
Related reference
“IBM MQ service definition properties” on page 401

200 IBM MQ Explorer

 You can set properties and attributes for service definitions while creating a new service definition, or
when editing an existing service definition.

Creating and configuring a queue manager set

Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.

About this task

Grouping queue managers is particularly useful if you administer large numbers of queue managers
using IBM MQ Explorer, because queue managers belonging to particular applications, departments, or
companies can be grouped together.
The following topics describe how to create queue manager sets in IBM MQ Explorer:
• “Displaying queue manager sets” on page 201
• “Defining manual sets” on page 202
• “Defining automatic sets” on page 203
The following topics describe how to configure existing queue manager sets in IBM MQ Explorer:
• “Managing filters for automatic sets” on page 204
• “Adding and removing queue managers manually” on page 206
• “Adding and removing queue managers automatically” on page 207
• “Copying an existing set” on page 212
• “Deleting a set” on page 213
• “Copying queue managers to a set” on page 214
• “Dragging queue managers” on page 215
• “Importing and exporting queue manager sets” on page 216
The following topics describe the various attributes of the properties pages for queue manager sets in
IBM MQ Explorer:
• “Editing the properties of an automatic set” on page 210
• “Properties of manual sets” on page 209
• “Properties of automatic sets” on page 208
• “Editing the properties of a manual set” on page 211
• “Manage Sets properties” on page 211

Displaying queue manager sets

Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.

About this task

From the Navigator view:
1. In the Navigator view, right-click the Queue Managers folder to open the menu, then click Sets >
Show Sets.
The Show Sets command displays a default set called All which cannot be edited, and always contains
all the queue managers.
If you want to hide all the sets (while maintaining their definitions and groupings), to simplify the
Navigator view for example:

Introduction to IBM MQ Explorer 201

 1. In the Navigator view, right-click the Queue Managers folder to open the menu, then click Sets > Hide
Sets.
The Hide Sets command removes all the defined sets, including the All set, from the Navigator view
(while maintaining their definitions and groupings).
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.
“Copying an existing set” on page 212
Copy an existing set to create a new queue manager set with the same configuration.

Defining manual sets

You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.

About this task

To define a new set:

Procedure
1. In the Navigator view, right-click the Queue Managers folder, then click Sets > New Set... The New
Set wizard opens.
2. Type a valid name for your new queue manager set. The name of the set is not constrained by the
normal MQ object naming rules. The name must, however, be different from the names of any existing
set.
3. Click Manual to add queue managers manually.
4. Select one of the following options:
• Click Finish to create an empty set, or
• Click Next to add queue managers to the new set.
5. On the manual selection pane, select the check box next to the corresponding queue manager name to
add the queue manager to your new set. You can add multiple queue managers.
6. Click Finish to create your set and close the wizard.

Results
The new manual queue manager set is displayed in the Navigator view.

202 IBM MQ Explorer

What to do next
If you created an empty set in step 3, you can manually add queue managers as described here: “Adding
and removing queue managers manually” on page 206
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Defining automatic sets

You can define queue manager sets that automatically include relevant queue managers.

About this task

To define a new set:

Procedure
1. In the Navigator view, right-click the Queue Managers folder, then click Sets > New Set... The New
Set wizard opens.
2. Type a valid name for your new queue manager set. The name of the set is not constrained by the
normal MQ object naming rules. The name must, however, be different from the names of any existing
set.
3. Click Automatic to add queue managers using automatic filters and click Next.
4. Select the filter you want to use from the Available Filters pane, and click Add->. The filter will be
removed from the Available Filters pane and placed in the Selected Filters pane. To select multiple
filters, for example Platform = Unix and Command level = 500, use one of the following
options:
• Select matches ALL the selected filters to add an AND statement to the filter, for example
Platform = Unix -AND- Command level = 500. The wizard will not allow you to continue
if you have selected conflicting filters, for example Platform = Unix -AND- Platform =
Windows is not allowed.
• Select matches ANY of the selected filters to add an OR statement to the filter, for example
Platform = Unix -OR- Command level = 500

Introduction to IBM MQ Explorer 203

 If you need to create, copy, edit, or delete filters, you can do so now by clicking on Manage Filters...
and following the instructions as described in: “Managing filters for automatic sets” on page 204.
Alternatively, filters can be managed at a later time if required.
5. Click Finish to create your set and close the wizard.

Results
The new automatic queue manager set is displayed in the Navigator view.

What to do next
You can create new filters to add or remove queue managers, as well as copy, edit and delete filters as
described in: “Managing filters for automatic sets” on page 204
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Managing filters for automatic sets

You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.

Before you begin

Before you add, edit, copy or delete filters, complete the following steps:
1. Enable set visibility as described in “Displaying queue manager sets” on page 201.
2. Define a set for the queue managers to be added to or removed from as described in “Defining
automatic sets” on page 203.
3. Right-click the set you want to manage filters for in the Navigator view, then click Edit Set... to open
the Edit Set window.
4. Click Manage Filters to open the Manage Filters window.

About this task

To manage filters, choose any of the following options:
1. Add a new filter

204 IBM MQ Explorer

2. Edit a filter
3. Copy a filter
4. Remove a filter

Procedure
1. [OPTION 1] Add a new filter
a) Open the Manage Filters window, as described at the beginning of this topic.
b) In the Manage Filters window, click Add...
The Add Filter window opens.
c) In the Add Filter window, in the Filter Name field, type a name for the filter; for example, Queues
containing more than 50 messages
d) In the Includes queue managers where fields, you can enter the criteria to add to the new filter.
For example, enter the following information:
i) The first row of fields allows you to filter on the name of the queue manager. By default, the third
field contains an asterisk (*) so that all queue managers, regardless of their names, are included
in the filter. For example, to include only the queues that start with jupiter, type jupiter*
ii) Optional: You can enter another criteria to the filter based on the value of an attribute of the
objects. Select the check box labeled - AND- so that you can edit the fields. For example,
to include only queue manager that have a Description field of Payroll, select the attribute
Payroll; in the second field, select equal to; in the third field, type Payroll.
e) Optional: To automatically apply an existing column scheme when the filter is applied, select the
check box labeled Automatically apply a Column Scheme when this filter is applied, then select
the column scheme from the list.
f) Click OK.
The Add Filter window closes. The new filter is displayed in the Manage Filters window with any
other available filters.
g) In the Manage Filters window, click OK.
The Manage Filters window closes.
Your new filter is added to the list of available filters.
2. [OPTION 2] Edit a filter
a) Open the Manage Filters window, as described at the beginning of this topic.
b) In the Manage Filters window, click Edit...
The Edit Filter dialog opens.
c) In the Edit Filter dialog, add, remove, or change the criteria that are set for the filter, then click OK.
For more information about the fields in the dialog, see Add a new filter.
d) Click OK to close the Manage Filters window.
The changes to the filter are automatically applied to any tables that are using that filter. MQ Explorer
might take several seconds to apply the filters to the queue managers.
3. [OPTION 3] Copy a filter
To create a filter that is similar to an existing one, you can copy the existing filter and then edit it as
required. You can copy any filter that you have created previously and you can also copy the filters that
are supplied with IBM MQ Explorer; for example, the Command level = 500 filter.
a) Open the Manage Filters window, as described at the beginning of this topic.
b) In the Manage Filters window, select the filter you want to copy, then click Copy As...
The Copy Filter dialog opens.
c) In the Copy Filter dialog, type a name for the new filter, then click OK.
The copied filter name cannot be the same as an existing filter.

Introduction to IBM MQ Explorer 205

 d) In the Manage Filters window, click Edit...
The Edit Filter dialog opens.
e) In the Edit Filter dialog, add, remove, or change the criteria that are set for the filter, then click OK.
For more information about the fields in the dialog, see Add a new filter.
f) Click OK to close the Manage Filters window.
The new filter is available to apply.
4. [OPTION 4] Remove a filter
a) Open the Manage Filters window, as described at the beginning of this topic.
b) In the Manage Filters window, select the filter you want to delete, then click Remove...
The Remove Filter confirmation dialog opens.
c) Click Yes to remove the filter and close the confirmation dialog.
d) Click OK to close the Manage Filters window.
The filter you deleted is removed from the list of filters for the selected queue manager set. Any queue
managers added to the set by the filter will no longer be a member of the set in the Navigator view.
Related tasks
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Adding and removing queue managers manually

When you have created a manual queue manager set, you can manually add and remove queue
managers.

Before you begin

Before you start:
1. Enable set visibility as described in: “Displaying queue manager sets” on page 201.
2. Define a set for the queue managers to be added to or removed from as described in: “Defining manual
sets” on page 202.

About this task

There are two ways to manually add and remove queue managers in the IBM MQ Explorer Navigator view.

Procedure
• To add or remove queue managers using the first method:
a) Right-click the set that you want to modify.
The All set membership cannot be modified.
b) Click Set Membership... to open the Set Membership dialog.

206 IBM MQ Explorer

 All available queue managers are displayed. Queue managers that are already a member of the set
have their corresponding check box already selected.
c) To add the queue manager to the set, select the check box next to the corresponding queue
manager name. To remove the queue manager from the set, clear the check box next to the
corresponding queue manager.
You can select multiple queue managers.
d) Click OK to save your changes and close the dialog.
• To add or remove queue managers using the second method:
a) Right-click the queue manager you want to add to a queue manager set.
b) Click Sets > Manual Set Membership... to open the Manual Set Membership dialog.
c) To add the queue manager to a queue manager set, select the check box next to the corresponding
queue manager set name. To remove the queue manager from that queue manager set, clear the
check box next to the corresponding queue manager set.
You can select multiple queue manager sets.
d) Click OK to save your changes and close the dialog.

Results
If you added queue managers to a set or removed queue managers from the set, then the new set
membership is shown in the Navigator view.
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Adding and removing queue managers automatically

You can define filters to automatically manage the membership of your queue manager sets.

Before you begin

Before you start:
1. Enable set visibility as described in: “Displaying queue manager sets” on page 201.
2. Define a set for the queue managers to be added to or removed from as described in: “Defining
automatic sets” on page 203.

Introduction to IBM MQ Explorer 207

 About this task
To add and remove queue managers:

Procedure
1. Right-click the set that you want to modify. The All set membership cannot be modified.
2. Click Edit Set... to open the Edit Set dialog. The current filters are displayed, allowing you to add or
remove them (you can also edit, copy and delete them as described in: “Managing filters for automatic
sets” on page 204).
3. Click OK to save your changes and close the window.

Results
If your changes to the filter added queue managers to the set or removed queue managers from the set,
then the new set membership is shown in the Navigator view.

What to do next
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.

Properties of automatic sets

An automatic queue manager set has several properties that you can edit.
Descriptions of the options on the Edit Set dialog are listed in the following table.

Object Description
Set Name Enter a valid name for your queue manager set. The name of the set is not constrained
by the normal IBM MQ object naming rules concerning characters, but is constrained by
the IBM MQ object naming rules for length. The set name must be different from the
names of any existing set.

208 IBM MQ Explorer

Object Description
matches ALL Select matches ALL the selected filters to add an AND statement to the filter, for
the selected example: Platform = Unix -AND- Command level = 500.
filters
The wizard will not allow you to continue if you have selected conflicting filters. For
example, you cannot have: Platform = Unix -AND- Platform = Windows.
AND statements cannot be mixed with OR statements in the filter. For example, you
cannot have: Platform = Unix -OR- Platform = Windows -AND- Command
level = 500

matches ANY Select matches ANY of the selected filters to add an OR statement to the filter, for
of the selected example: Platform = Unix -OR- Command level = 500.
filters
OR statements cannot be mixed with AND statements in the filter. For example, you
cannot have: Platform = Unix -OR- Platform = Windows -AND- Command
level = 500

Add-> Select the filter in the Available Filters pane that you want to add and click Add->.
The filter is removed from the Available Filters pane and placed in the Selected Filters
pane.
<-Remove Select the filter in the Selected Filters pane that you want to remove, and click
<-Remove. The filter is removed from the Selected Filters pane and placed back in
the Available Filters pane.
Manage Click Manage Filters... to open the Manage Filters window. The process of managing
Filters... filters is explained here: “Managing filters for automatic sets” on page 204.

Related tasks
“Editing the properties of an automatic set” on page 210
You can edit the properties of an existing automatic set.
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Properties of manual sets

A manual queue manager set has only one property that you can edit.
A description of the option on the Edit Set dialog is listed in the following table:

Object Description
Set Name Enter a valid name for your queue manager set. The name of the set is not constrained
by the normal IBM MQ object naming rules concerning characters, but is constrained by
the IBM MQ object naming rules for length. The set name must be different from the
names of any existing set.

Introduction to IBM MQ Explorer 209

 Related tasks
“Editing the properties of a manual set” on page 211
You can edit the properties of an existing manual set.
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.

Editing the properties of an automatic set

You can edit the properties of an existing automatic set.

About this task

There are two ways to open the Edit Set dialog for automatic queue manager sets in the IBM MQ Explorer
Navigator view. To open the Edit Set dialog using the first method:

Procedure
1. Right-click the automatic set you want to edit.
2. Click Edit Set... to open the Edit Set dialog.

Results
The Edit Set dialog is now open, and you can edit the properties of the automatic set.

What to do next
To open the Edit Set dialog using the second method:
1. Right-click Queue Managers
2. Click Sets > Manage Sets to open the Manage Sets dialog.
3. Select the automatic set you want to edit the properties of.
4. Click Edit... to open the Edit Set dialog for automatic sets.
The Edit Set dialog is now open, and you can edit the properties of the automatic set.
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers automatically” on page 207

210 IBM MQ Explorer

You can define filters to automatically manage the membership of your queue manager sets.
Related reference
“Properties of automatic sets” on page 208
An automatic queue manager set has several properties that you can edit.

Editing the properties of a manual set

You can edit the properties of an existing manual set.

About this task

There are two ways to open the Edit Set dialog for manual queue manager sets in the IBM MQ Explorer
Navigator view. To open the Edit Set dialog using the first method:

Procedure
1. Right-click the manual set you want to edit.
2. Click Edit Set... to open the Edit Set dialog.

Results
The Edit Set dialog is now open, and you can edit the properties of the manual set.

What to do next
To open the Edit Set dialog using the second method:
1. Right-click Queue Managers
2. Click Sets > Manage Sets to open the Manage Sets dialog.
3. Select the manual set you want to edit the properties of.
4. Click Edit... to open the Edit Set dialog for manual sets.
The Edit Set dialog is now open, and you can edit the properties of the manual set.
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
Related reference
“Properties of manual sets” on page 209
A manual queue manager set has only one property that you can edit.

Manage Sets properties

You manage set properties through the Manage Sets dialog.
Right-click Queue Managers to open the Sets menu item, then click Manage Sets to open the Manage
Sets dialog.
Descriptions of the options on the Manage Sets dialog are listed in the following table.

Introduction to IBM MQ Explorer 211

 Obje Description
ct
Add Click Add... to open the New Set window to define a new set. Manual sets and automatic sets
can be added in this way. The process for defining a new manual set is explained here: “Defining
manual sets” on page 202. The process for defining a new automatic set is explained here:
“Defining automatic sets” on page 203 .
Cop Click Copy As... to open the Copy As dialog. Manual sets and automatic sets can be copied in this
y As way. The process for copying defined sets is explained here: “Copying an existing set” on page
212
Edit When a manual set is currently selected, click Edit... to open the Edit Set dialog. The name of the
manual set can be changed. The name you enter must be unique, you are unable to click OK until
a unique name has been entered.
When an automatic set is currently selected, click Edit... to open the Edit Set window.

Rem Click Remove... to remove the selected set. You will be prompted to confirm or cancel your
ove request.

Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Dragging queue managers” on page 215
Queue managers can be dragged into sets, as well as dragged out of sets.

Copying an existing set

Copy an existing set to create a new queue manager set with the same configuration.

Before you begin

Before you start:
1. Enable set visibility as described in: “Displaying queue manager sets” on page 201.
2. Define a set to be copied, as described in: “Defining automatic sets” on page 203 or: “Defining manual
sets” on page 202 .

About this task

To copy an existing set:

Procedure
1. In the Navigator view, right-click the Queue Managers folder, then click Sets > Manage Sets....
The Manage Sets window is opened.

212 IBM MQ Explorer

2. Select the set you want to copy
3. Click Copy As... to open the Copy Set dialog.
4. Type a name for your set in the New Set Name field. The new set name must be unique.
5. Click OK to copy the set and close the dialog.

Results
You have successfully copied a set, the Navigator view is updated with the new set (This might take a few
seconds if there are many queue managers in the set).
Related tasks
“Creating and configuring a queue manager set” on page 201
Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Deleting a set
Deleting a queue manager set deletes the set itself, but not the queue managers within the set.

Before you begin

1. Enable set visibility as described in: “Displaying queue manager sets” on page 201.
2. Define a set to be deleted, as described in: “Defining automatic sets” on page 203 or in: “Defining
manual sets” on page 202 .

About this task

When you delete a queue manager set, the queue managers within the set are NOT deleted. To delete an
existing set, complete the following steps.
1. In the Navigator view, right-click the set you want to delete, to open the menu. Click Delete to open a
confirmation dialog. Click Delete to permanently delete the selected set.

Results
You have successfully removed a set, the Navigator view is updated with the new information (This might
take a few seconds if there are many queue managers in the set).
Related tasks
“Creating and configuring a queue manager set” on page 201

Introduction to IBM MQ Explorer 213

 Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Defining automatic sets” on page 203
You can define queue manager sets that automatically include relevant queue managers.
“Managing filters for automatic sets” on page 204
You use filters to define which queue managers are grouped in a set. You can add, edit, copy and delete
filters to configure automatic queue manager sets.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Adding and removing queue managers automatically” on page 207
You can define filters to automatically manage the membership of your queue manager sets.

Copying queue managers to a set

Copying queue managers from one set to another is an easy way to add a queue manager to a selection of
sets quickly, without the need to having to add the queue manager to each set individually for example.

Before you begin

Before you start:
1. Enable set visibility as described in: “Displaying queue manager sets” on page 201.
2. Define a minimum of 2 manual sets, one to be copied from and another to be copied to, as described
in: “Defining manual sets” on page 202. Automatic sets cannot be used with this following process.

About this task

To copy the queue managers to a set:

Procedure
1. In the Navigator view, right-click the set you want to copy the queue managers from, then click Copy
to set....
The Copy to set dialog opens.
2. Select the check box next to the corresponding set name to add the queue managers to. You can select
multiple sets.
3. Optional: You can click Manage Sets... to define or remove a set as is described in: “Adding and
removing queue managers manually” on page 206
4. Click OK to close the Copy to set dialog.

Results
You have successfully copied the contents of one set to another. The navigator view is updated with the
new information (This might take a few seconds if there are many queue managers in the set).
Related tasks
“Creating and configuring a queue manager set” on page 201

214 IBM MQ Explorer

Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Dragging queue managers” on page 215
Queue managers can be dragged into sets, as well as dragged out of sets.

Dragging queue managers

Queue managers can be dragged into sets, as well as dragged out of sets.

Before you begin

Before you start:
1. Enable set visibility as described in: “Displaying queue manager sets” on page 201.
2. Define a set for the queue managers to be added to or removed from, as described in: “Defining
manual sets” on page 202.

About this task

There are several ways to drag queue managers:

Procedure
• Drag a queue manager from the All set into a manual set to add it to that manual set. The queue
manager will not be removed from the All set.
• Drag a queue manager from a manual set into the All set to remove it from the manual set.
• Drag a queue manager from a manual set into a second manual set. The queue manager will be added
to the second manual set and removed from the first.
• Drag a queue manager from an automatic set into a manual set to add it to the manual set. The queue
manager will not be removed from the automatic set.
• Drag a queue manager from a manual set into a second manual set while holding down the Ctrl key.
The queue manager will be added to the second manual set and remain in the first.

Example

What to do next
Queue managers cannot be dragged into an automatic set from another set. Queue managers cannot be
dragged from an automatic set into the All set, for example: You cannot remove a queue manager from an
automatic set by dragging it.
Related tasks
“Creating and configuring a queue manager set” on page 201

Introduction to IBM MQ Explorer 215

 Queue manager sets enable you to group queue managers in folders, and enable you to make actions to
all the queue managers in the set. This enables you to subdivide your queue managers, for example into
'test' and 'production' sets, or into sets based on the operating system of the platform.
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.
“Defining manual sets” on page 202
You can define manual queue manager sets that do not contain any queue managers, and add queue
managers when required.
“Adding and removing queue managers manually” on page 206
When you have created a manual queue manager set, you can manually add and remove queue
managers.
“Copying queue managers to a set” on page 214
Copying queue managers from one set to another is an easy way to add a queue manager to a selection of
sets quickly, without the need to having to add the queue manager to each set individually for example.

Importing and exporting queue manager sets

You can export your queue manager sets from IBM MQ Explorer for backup purposes, or to transfer and
import the queue manager sets into another instance of IBM MQ Explorer.

About this task

Complete either of the following tasks:
1. Export queue manager sets
2. Import queue manager sets

Procedure
• [OPTION 1] Export queue manager sets
a) In the Navigator view, right-click IBM MQ, then click Export MQ Explorer settings...
The Export dialog opens.
b) Select Sets from the check boxes.
c) Enter the file name and location for the compressed file that is created to store the exported queue
manager sets.
d) Click OK.
A compressed file that contains the exported queue manager sets is created. The compressed file
contains the settings in XML files.
When you are exporting manual queue manager sets, a list of the names of the queue managers that
are members of the set, and the QMID of the queue managers, is exported. When you are exporting
automatic queue manager sets, a list of identifiers for filters that queue managers must match, and
whether queue managers must match any or all of the filters, is exported.
• [OPTION 2] Import queue manager sets
a) In the Navigator view, right-click IBM MQ, then click Import MQ Explorer settings...
The Import dialog opens.
b) Browse for the compressed file that contains the queue manager sets.
c) Select Sets to import the settings. If the compressed file does not contain any exported queue
manager set information, the check box associated with sets is unavailable.
d) Click OK.

216 IBM MQ Explorer

 The settings from the compressed file are imported into IBM MQ Explorer. The queue manager
appends the imported sets with the currently defined sets, such that the sets are merged together
in IBM MQ Explorer.
When you are importing manual queue manager sets, a list of the names of the queue managers
that are members of the set, and the QMID of the queue managers, is imported. Any existing queue
manager with a QMID that matches a QMID from the imported set definition is added to the queue
manager set. If IBM MQ Explorer does not contain a queue manager with a matching QMID, then the
imported information for that queue manager is ignored.
When you are importing automatic queue manager sets, a list of identifiers for filters that queue
managers must match, and whether queue managers must match any or all of the filters, is imported.
Only existing queue managers that match the imported filter rules are added to the corresponding
automatic set. If any filters are missing, a dialog is displayed asking you to either select a different
filter or delete the set.
Queue manager set definitions cannot be imported into IBM WebSphere MQ 6.0 Explorer or earlier.
Related tasks
“Displaying queue manager sets” on page 201
Before you can work with queue manager sets, you must first display the sets in IBM MQ Explorer.
Although the queue manager sets still exist when the sets are hidden, you are unable to manage them.

Define schemes to change the order of columns in tables

When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
For example, queues have a large number of attributes; when you display the contents of a Queues folder
in the Content view, if you are not interested the creation date and time of the queues, you can choose
not to display those attributes, or you can move those columns to somewhere else in the table.
The changes that you make are saved as schemes so that you can apply the same set of changes to the
same type of objects on other queue managers too.

IBM MQ Explorer supplies and applies standard schemes. Because IBM MQ for z/OS for
queue managers and objects can have slightly different attributes, each object scheme has settings
for the object on Multiplatform queue managers and for z/OS queue managers. The standard schemes
include all the attributes for objects of that type. For example, the Standard for Queues scheme
includes all the attributes for queues on Multiplatforms and z/OS platforms so that you can be sure that
you can see all the attributes for the queues that are listed.
To apply an existing scheme to a table:
1. In the Content view, or dialog that contains the table, click the small arrow next to the current scheme
name. A menu is displayed.
2. From the menu, click Select Scheme The Select Scheme dialog opens.
3. In the Select Scheme dialog, click the scheme that you want to apply. The attributes that the scheme
will display are listed in the dialog.
4. Click OK.
The selected scheme is applied to the folder of objects.
Related tasks
“Creating a scheme” on page 218
You can create schemes for most of the tables of data in IBM MQ Explorer.
“Editing an existing scheme” on page 219
You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.
“Copying an existing scheme” on page 220

Introduction to IBM MQ Explorer 217

 If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.

Creating a scheme
You can create schemes for most of the tables of data in IBM MQ Explorer.

About this task

You can create schemes for queues, channels, and listeners; you can also create schemes for status
tables in the Status dialogs, such as the Queue Status dialog. A scheme can be applied only to one type of
object because different types of objects have different attributes.

The following instructions use an example of creating a scheme for queues so that only
the Queue name, Queue type, and Current queue depth attributes are displayed for queues on
Multiplatforms.

The same attributes plus QSG disposition are displayed for queues on z/OS.
You can easily adapt the instructions to create schemes for other types of object too.
To create a scheme, complete the following steps.

Procedure
1. In the Content view or dialog that contains the table, click the small arrow next to the current filter
name. A menu is displayed.
2. From the menu, click Manage Schemes The Manage Schemes dialog opens displaying schemes that
already exist for the object type.
3. In the Manage Schemes dialog, click Add The Add Scheme dialog opens.
4. In the Add Scheme dialog, in the Scheme Name field, type a name for the scheme; for example,
Monitoring the depth of my queues By default, all of the attributes are included in the
scheme.
5. Edit the scheme as required for distributed objects and for z/OS objects. For example:
a) On the Distributed page, click Remove All. All the attributes in the Displayed attributes list are
removed.
b) In the Available attributes list, click Queue name, then click Add. The Queue name attribute is
added to the Displayed attributes list.
c) Repeat step 6 for the Queue type and Current queue depth attributes.
d) Click the z/OS tab to change to the z/OS page.
e) On the z/OS page, click Copy Distributed to z/OS. The changes that you made on the Distributed
page are copied to the z/OS page.
f) In the Available attributes list, click QSG disposition, then click Add. The QSG disposition
attribute is added to the Displayed attributes list.
6. Click OK. The Add Scheme dialog closes. The new scheme is displayed in the Manage Schemes dialog
along with the other available schemes.
7. Click OK to close the Manage Schemes dialog.

Results
You can now apply the scheme to a table of data.

218 IBM MQ Explorer

Related concepts
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
Related tasks
“Editing an existing scheme” on page 219
You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.
“Copying an existing scheme” on page 220
If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.

Editing an existing scheme

You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.

About this task

You can edit a scheme that is currently applied to the table that you are viewing, or edit another scheme.
The changes to the scheme are automatically applied to any tables that are using that scheme.
1. Edit the current scheme
2. Edit a non-current scheme
3. Reset the status table

Procedure
• [OPTION 1] Edit the current scheme
a) Make sure that the type of object for which you are creating a scheme is displayed in the Content
view, then, in the Content view, click the small arrow next to the current scheme name. A menu is
displayed.
b) From the menu, click Edit Current Scheme. The Edit Scheme dialog opens.
c) In the Edit Scheme dialog, make the changes, then click OK. For more information about the
dialog, see Creating a scheme.
• [OPTION 2] Edit a non-current scheme
a) Make sure that the type of object for which you are creating a scheme is displayed in the Content
view.
b) In the Content view, click the small arrow next to the current scheme name.
A menu is displayed.
c) From the menu, click Manage Schemes.
The Manage Schemes dialog opens, displaying the schemes that exist for the object type.
d) In the Manage Schemes dialog, click the scheme that you want to edit, then click Edit.
The Edit Scheme dialog opens.
e) In the Edit Scheme dialog, add or remove attributes from the scheme as required, then click OK.
For more information about the dialog, see Creating a scheme.
f) Click OK to close the Manage Schemes dialog.
The changes to the scheme are automatically applied to any tables that are using that scheme.
• [OPTION 3] Reset the status table

Introduction to IBM MQ Explorer 219

 Use this step to reset the width of the columns to their default values after you have modified the
layout of the status table.
a) Make sure that the table for which you are resetting the column widths is displayed in the Content
view.
b) In the Content view, click the small arrow next to the current scheme name.
A menu is displayed.
c) From the menu, click Reset Column Widths.
The width of the columns on the status table are reset to their default values.
Related tasks
“Copying an existing scheme” on page 220
If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.
“Creating a scheme” on page 218
You can create schemes for most of the tables of data in IBM MQ Explorer.

Copying an existing scheme

If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.

About this task

You can copy any scheme that you have created previously and you can also copy the schemes that are
supplied with IBM MQ Explorer; for example, the Standard for Queues scheme. You cannot copy a
scheme for one type of object to use on another type of object; for example, you cannot copy a scheme for
channels to use for filtering queues.
To copy an existing scheme:

Procedure
1. Make sure that the type of object for which you are creating a filter is displayed in the Content view,
then, in the Content view, click the small arrow next to the current filter name. A menu is displayed.
2. From the menu, click Manage Schemes The Manage Schemes dialog opens displaying the schemes
that already exist for the object.
3. In the Manage Schemes dialog, click the scheme that you want to copy, then click Copy As The Copy
Scheme dialog opens.
4. In the Copy Scheme dialog, type a name for the new scheme, then click OK.
5. In the Manage Schemes dialog, click Edit The Edit Scheme dialog opens.
6. In the Edit Scheme dialog, add or remove attributes from the scheme as required, then click OK.
7. Click OK to close the Manage Schemes dialog.

Results
You can now apply the scheme to a table of data.
Related concepts
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
Related tasks
“Editing an existing scheme” on page 219

220 IBM MQ Explorer

 You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.
“Creating a scheme” on page 218
You can create schemes for most of the tables of data in IBM MQ Explorer.

Changing the colors

You can change the colors that are used to highlight parts of the IBM MQ Explorer interface.

About this task

In IBM MQ Explorer, there are several places where color is used to highlight parts of the interface. For
example, in the Content view, cells that are not applicable to an object are colored gray; in the command
window that contains the command details of the Create Queue Manager wizard, sections of the text are
highlighted in different colors. In the Preferences dialog, you can change the colors that are used.
To change the color of cells that are not applicable:

Procedure
1. Open the Preferences dialog: Window > Preferences
2. In navigation tree of the Preferences dialog, expand MQ Explorer, then click Colors.
3. On the Colors page, click the palette button for the feature that you want to change. The palette button
in the Content View section of the page controls the color of cells that are not applicable (cells that are
colored gray by default); the palette buttons in the Command Details section of the page control the
color of the text and background in the command windows that are displayed in the Details window
when you create, delete, start, and stop a queue manager in IBM MQ Explorer.
4. In the palette, click the color that you want to use (or define a custom color), then click OK.
5. Click OK to close the Preferences dialog.

Results
The color that you selected is used.
Related tasks
“Configuring IBM MQ Explorer” on page 192
Use this information to help you to configure your IBM MQ Explorer installation.
Related reference
“Accessibility in IBM MQ Explorer” on page 279
Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.

Enabling installed plug-ins

If a new plug-in that you install in IBM MQ Explorer is not enabled by default, you can enable it by using
the Preferences dialog.

About this task

When you install a new plug-in in IBM MQ Explorer, whether the plug-in is supplied by IBM or by a third
party, if the plugin does not appear to be working in IBM MQ Explorer, it is likely that the plug-in is not
enabled by default.
To enable an installed plugin, complete the following steps.

Introduction to IBM MQ Explorer 221

 Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. In the navigation tree of the Preferences dialog, expand MQ Explorer, then click Enable plug-ins. A
list of the available plugins is displayed.
3. Select the check box next to the plug-in that you want to enable, then click OK.

Results
The plug-in is now enabled in IBM MQ Explorer. Any folders or menu items for example, that are related to
the plug-in are now available in IBM MQ Explorer.
You can also disable plug-ins that you do not use. For example, if you do not use clustering in your
messaging networks, you can clear the check box next to the Cluster Component plugin. The Cluster
Component plugin remains installed on your computer so that you can enable it in future. Because the
plug-in is still installed on your computer, the help that is associated with clustering is still available in the
help system and in the context-sensitive help.

Changing the refresh frequency of queue manager information

In IBM MQ Explorer, the information about local and remote queue managers is automatically refreshed
at set intervals. You can change the refresh frequency for a specific queue manager, or the default refresh
frequency for all new queue managers. You can also prevent a specific queue manager's information from
being refreshed automatically.

About this task

By default, the information that is displayed about remote queue managers is refreshed less frequently
than the information about local queue managers because of the increase in network traffic every time
that the information is requested from remote systems.
You can also prevent specific queue managers being refreshed automatically. For example, if you know
that a queue manager will remain stopped for a period of time, you could prevent IBM MQ Explorer
requesting information about it and so reduce the network traffic.
• “Changing the refresh frequency for a specific queue manager” on page 222
• “Changing the default refresh frequency for all new queue managers” on page 223
• “Preventing automatic refresh of a queue manager's information” on page 223

Changing the refresh frequency for a specific queue manager

About this task

To change the frequency with which information about a specific queue manager is refreshed:

Procedure
1. In the Navigator view, right-click the queue manager, then click Connection Details > Set Refresh
Interval The Automatic Refresh dialog opens.
2. In the Automatic Refresh dialog, edit the value in the Interval field.
3. Optional: To reset the automatic refresh rate to the default value, click Apply Default.
4. Click OK to save the new refresh rate.

Results
The information about the queue manager is now automatically refreshed at the new rate.

222 IBM MQ Explorer

 Changing the default refresh frequency for all new queue managers

About this task

To change the frequency with which the information about local and remote queue managers is refreshed:

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. On the MQ Explorer page, in the Default Queue Manager Refresh Intervals fields, type the refresh
interval, in seconds, then click OK.

Results
All new queue managers that are added to IBM MQ Explorer are now refreshed at the new rate.

Preventing automatic refresh of a queue manager's information

About this task

To prevent queue manager information in IBM MQ Explorer from being refreshed automatically:

Procedure
1. In the Navigator view, right-click the queue manager, then click Connection Details > Set Refresh
Interval The Automatic Refresh dialog opens.
2. In the Automatic Refresh dialog, clear the check box, then click OK.

Results
The information about the queue manager is no longer refreshed automatically. To refresh the information
about the queue manager, click Refresh on the menu in the Content view.

Specifying the default values used to connect to remote queue managers

You can either configure IBM MQ Explorer with the default values directly, or configure IBM MQ Explorer
to use system environment value variables.

About this task

To configure IBM MQ Explorer with default values to use when connecting to remote queue managers,
complete one of the following tasks:
1. Specify the default values directly.
2. Use the system environment variable.

Procedure
• [OPTION 1] Specify the default values directly.
To configure IBM MQ Explorer with the default port number and server-connection channel used to
connect to remote queue managers, complete this task in IBM MQ Explorer on the computer from
which you want to connect to the remote queue manager.
a) In IBM MQ Explorer, click Window > Preferences.
The Preferences dialog opens.
b) Expand MQ Explorer.
c) Expand Client Connections.
d) Select Remote Queue Managers to display the Remote Queue Managers pane.

Introduction to IBM MQ Explorer 223

 e) In the Port number field, enter the default port number to be used when connecting to a remote
queue manager.
f) In the Server-connection channel field, enter the default channel name to be used when
connecting to a remote queue manager.
IBM MQ Explorer now uses the provided defaults when creating a new connection to a remote
queue manager. These defaults can be changed when adding in a new connection to a remote queue
manager using the Add Queue Manager wizard.
• [OPTION 2] Use the system environment variable.
To configure IBM MQ Explorer to use the system environment variable values when connecting to
remote queue managers, complete this task in IBM MQ Explorer on the computer from which you want
to connect to the remote queue manager.
a) In IBM MQ Explorer, click Window > Preferences.
The Preferences dialog opens.
b) Expand MQ Explorer.
c) Expand Client Connections.
d) Select Remote Queue Managers to display the Remote Queue Managers pane.
e) Select the Use environment (MQSERVER) check box to override the specified defaults and use the
system environment variable to set the default port and default channel name.
IBM MQ Explorer now uses the MQSERVER system environment variable when creating a new
connection to a remote queue manager. These defaults can be changed when adding in a new
connection to a remote queue manager using the Add Queue Manager wizard.
Related tasks
“Showing a remote queue manager” on page 82
If you want to administer a remote queue manager, you must connect IBM MQ Explorer to the remote
queue manager so that the queue manager is displayed in the Navigator view. You can create a
connection manually, or using a client channel definition table. You can also create a new security-
enabled connection, or connect using an existing connection.

Exporting and importing settings

You can export your settings from IBM MQ Explorer for backup purposes, or to transfer and import the
settings into another instance of IBM MQ Explorer.

About this task

You can export and import the following types of settings in IBM MQ Explorer:
• Column schemes that you have created
• Filters that you have created
• Connection details for remote queue managers
• Preferences that you have set in IBM MQ Explorer
• Queue manager set memberships, set definitions, and set filters

Exporting settings

About this task

You can export your settings from your workspace to transfer and import the settings into another
instance of IBM MQ Explorer for example.
To export your settings from your IBM MQ Explorer workspace:

224 IBM MQ Explorer

 Procedure
1. To open the Export dialog, in the Navigator view, right-click IBM MQ, then click Export MQ Explorer
settings.... Alternatively, you can open the Export dialog by clicking File > Export, then selecting MQ
Explorer > MQ Explorer Settings from the dialog.
2. Select the check boxes for the types of settings that you want to export.
3. As the data is written to the file system, enter the file name and location for the compressed file that
will be created to store the exported settings.
4. Click OK.

Results
A compressed file that contains the exported settings is created. The compressed file contains the
settings in XML files.
For information about exporting queue manager sets, see: “Importing and exporting queue manager sets”
on page 216.

Importing settings

About this task

To import settings to IBM MQ Explorer:

Procedure
1. In the Navigator view, right-click IBM MQ, then click Import MQ Explorer settings... The Import dialog
opens.
2. Browse for the compressed file that contains the settings.
3. Select the types of settings that you want to import into IBM MQ Explorer. If the compressed file does
not contain settings of a certain type, the check box associated with that type is unavailable.
4. Click OK.

Results
The settings from the compressed file are imported into IBM MQ Explorer.
For information about importing queue manager sets, see: “Importing and exporting queue manager
sets” on page 216.

Including SYSTEM objects when you run tests

By default, SYSTEM objects are not included in test results, but you can choose to include them if
required.

About this task

Definitions of SYSTEM.DEFAULT objects are provided in IBM MQ as incomplete templates so, by default,
they are not included when you run tests. However, you can include them if you want.
To include SYSTEM objects in test results, complete the following steps.

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. In the navigation tree of the Preferences dialog, expand IBM MQ Explorer, then click Tests.
3. Select the Include SYSTEM objects in the test results check box.

Introduction to IBM MQ Explorer 225

 Results
Next time you run tests against objects in IBM MQ Explorer, any available SYSTEM objects are also tested.

Including hidden queue managers in test configurations

Queue managers that are hidden in IBM MQ Explorer do not by default appear in the list of available
objects when you create new test configurations. However, you can choose to have hidden queue
managers included so that they listed as available queue managers against which you can run tests.

About this task

Queue managers that are currently hidden in IBM MQ Explorer are not currently of interest to you so, by
default, they are not included in the list of available objects when you create new test configurations.
To include hidden queue managers, complete the following steps.

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. In the navigation tree of the Preferences dialog, expand IBM MQ Explorer, then click Tests.
3. Select the Include hidden objects in the list of available objects check box.

Results
Next time you create or edit a test configuration, any hidden queue managers are listed as available queue
managers against which you can run the tests.

Displaying object authority settings as text

In IBM MQ Explorer dialogs, object authorities are displayed as icons by default, but you can choose to
have them displayed as text instead.

About this task

In the Manage Authority Records dialogs, and in other dialogs that display object authorities, the tables
use icons to show whether an authority is granted. If you prefer, you can set the tables to use text instead
of icons.
To change the tables to use text instead of icons to show whether an authority is granted, complete the
following steps.

Procedure
1. Open the Preferences dialog: Window > Preferences
2. Expand MQ Explorer.
3. On the Authorization Service page, click Display authorities as text.
4. Click OK to close the Preferences dialog.

Results
The next time that you open a dialog that displays object authorities, the tables will show authorities
using text instead of icons.
Related tasks
“Configuring IBM MQ Explorer” on page 192

226 IBM MQ Explorer

 Use this information to help you to configure your IBM MQ Explorer installation.
Related reference
“Accessibility in IBM MQ Explorer” on page 279
Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.

Using Advanced Message Security

Advanced Message Security is a separately installed and licensed component that provides a high level
of protection for sensitive data flowing through the IBM MQ network, while not impacting the end
applications

Message signing
By using a digital signature on the message the identity of the sender and the authenticity of the message
can be confirmed, and therefore the sender of the message is unable to deny (or repudiate) the sending of
that message.
When an application places a message on a queue, Advanced Message Security checks if the target
queue has a Advanced Message Security policy for signing or encryption. If signing is required, Advanced
Message Security creates an envelope containing the message data, a cryptographic signature, and the
public certificate data of the user associated with the application.
When an application retrieves the message from the queue, Advanced Message Security strips the
signature from the message data and verifies that the sender is known and signed by a trusted certificate
authority. In addition, Advanced Message Security checks that the user identified by the signature is
authorized, by policy, to place messages on the target queue.
The signature also includes a digest of the message data, generated at the time the message was placed
on the queue. This digest is verified to ensure that the data in the message has not been altered between
being placed on the queue and being retrieved.

Message encryption
By using message encryption, a message sender can be sure that the content of the message has not
been modified before reaching the recipient.
When an application places a message on a queue, Advanced Message Security checks if the target queue
has a Advanced Message Security policy for signing or encryption. If encryption is required, Advanced
Message Security signs and encrypts the data.
In addition to the signing process, Advanced Message Security encrypts the message data with a
symmetric key, using the encryption algorithm specified in the Advanced Message Security policy
associated with the target queue. The message is then addressed to each potential recipient specified
in that policy, using the users' public keys.
When an application retrieves the message from the queue, Advanced Message Security verifies the
signature and decrypts the message data using the private key of the recipient user.

Distinguished names
Advanced Message Security uses the Public Key Infrastructure (PKI) identity to represent a user or an
application. This type of identity is used for signing and encrypting messages. The identity is represented
by the distinguished name (DN) field in a certificate associated with signed and encrypted messages.
Sender distinguished names
The sender distinguished names (DNs) identify users authorized to place messages on a queue.
However, Advanced Message Security does not check whether a message has been placed on a data-
protected queue by a valid user until the message is retrieved. At this time, if the policy stipulates
one or more valid senders, and the user that placed the message on the queue is not in the list of

Introduction to IBM MQ Explorer 227

 valid senders, Advanced Message Security returns an error to the getting application, and place the
message on its error queue.
A policy can have 0 or more sender DNs specified. If no sender DNs are specified for the policy, any
user can put data-protected messages to the queue providing the user's certificate is trusted.
Sender distinguished names have the following form:

CN=Common Name,O=Organization,C=Country

If one or more sender DNs are specified for the policy, only those users can put messages to the
queue associated with the policy.
Sender DNs, when specified, must match exactly the DN contained in the digital certificate associated
with user putting the message.
Recipient distinguished names
The recipient distinguished names (DN) identify users authorized to retrieve messages from a queue.
A policy can have zero or more recipient DNs specified. Recipient distinguished names have this form:

CN=Common Name,O=Organization,C=Country

If no recipient DNs are specified for the policy, any user can get messages from the queue associated
with the policy. This implies that the policy does not specify encryption, as a policy with encryption
requires recipient DNs to be specified.
If one or more recipient DNs are specified for the policy, only those users can get messages from the
queue associated with the policy.
Recipient DNs, when specified, must match exactly the DN contained in the digital certificate
associated with user getting the message.
Configuring Advanced Message Security policies involves creating the policies using tools provided
with Advanced Message Security.
Note: Advanced Message Security does not allow policies for SYSTEM queues. These are queues with
a name that begin with 'SYSTEM.'. If you define a policy for a SYSTEM queue, it is ignored.

Troubleshooting problems with IBM MQ Explorer

Troubleshooting is the process of finding and eliminating the cause of a problem. If you are having
problems with IBM MQ Explorer, use the techniques described to help you diagnose and solve them.
You can prevent many problems with your object definitions and messaging configurations by testing your
object definitions for potential problems. For more information, see Testing your object definitions for
problems.
If an error message is displayed while you are working in IBM MQ Explorer, click More Details on the error
message to display more information about the problem.
Related tasks
“Collecting IBM MQ Explorer trace” on page 229
When you start the IBM MQ Explorer by using the runwithtrace command, extra parameters are
incorporated that enable tracing of IBM MQ Explorer.
“Collecting IBM MQ Explorer trace in other Eclipse environments” on page 230
By using a variant of the runwithtrace command, you can collect trace from an instance of IBM MQ
Explorer that is installed into your own Eclipse environment or Eclipse-based product.
“Using IBM MQ trace” on page 234

228 IBM MQ Explorer

 IBM MQ trace enables you to collect detailed information about what IBM MQ is doing.

Collecting IBM MQ Explorer trace

When you start the IBM MQ Explorer by using the runwithtrace command, extra parameters are
incorporated that enable tracing of IBM MQ Explorer.

Before you begin

This task assumes that you have a typical IBM MQ Explorer installation. That is, an installation running
in its own Eclipse instance, as installed by the standard product installer. If you have installed IBM MQ
Explorer into your own Eclipse environment or Eclipse-based product, see “Collecting IBM MQ Explorer
trace in other Eclipse environments” on page 230.

About this task

To collect trace for a typical IBM MQ Explorer installation, you start IBM MQ Explorer using the
runwithtrace command that is supplied with the product.
Note: You normally enable tracing only when asked to do so by your IBM Service Representative. Tracing
slows down IBM MQ Explorer and the trace files can rapidly become large.
The runwithtrace command launches IBM MQ Explorer with extra settings that enable tracing. Note
that the runwithtrace command takes no parameters itself.
The output location of the trace file is printed to the command line when the command runs because the
actual location is dependent upon
• the status of the IBM MQ installation.
• the user permissions.
The IBM MQ Explorer trace files have a name of the format AMQYYYYMMDDHHmmssmmm.TRC.n that
indicates the start time of the trace session. When a trace file reaches its maximum size, the trace facility
renames all trace files from the session by incrementing the file suffix .n by one. The trace facility then
creates a new file with the suffix .0 that contains the latest trace.
To trace IBM MQ Explorer, complete the following steps.

Procedure
1. Close IBM MQ Explorer.

2.
Optional: On Windows systems, use runwithtrace.cmd to run IBM MQ Explorer with tracing
activated.
The runwithtrace command is in the same directory as the MQExplorer command.

3.
Optional: On Linux systems, use runwithtrace to run IBM MQ Explorer with tracing activated.
The runwithtrace command is in the same directory as the MQExplorer command.
Related tasks
“Collecting IBM MQ Explorer trace in other Eclipse environments” on page 230
By using a variant of the runwithtrace command, you can collect trace from an instance of IBM MQ
Explorer that is installed into your own Eclipse environment or Eclipse-based product.
“Installing IBM MQ Explorer into Eclipse environments” on page 10

Introduction to IBM MQ Explorer 229

 You can install IBM MQ Explorer into your own Eclipse environment or Eclipse-based product to help with
developing Java applications or to develop your own extensions.

Collecting IBM MQ Explorer trace in other Eclipse environments

By using a variant of the runwithtrace command, you can collect trace from an instance of IBM MQ
Explorer that is installed into your own Eclipse environment or Eclipse-based product.

Before you begin

This task assumes that you have installed IBM MQ Explorer into your own Eclipse environment or
Eclipse-based product, and therefore cannot use the standard runwithtrace command as described
in “Collecting IBM MQ Explorer trace” on page 229.

About this task

IBM MQ Explorer can be installed into your own Eclipse environment or Eclipse-based product to help
develop Java applications, or to develop your own extensions.
To collect trace, you use a runwithtrace command to start IBM MQ Explorer. You cannot use the
runwithtrace command that is supplied with the product. Instead, you use a variant of the command,
as described in the following procedure.
Note: You normally enable tracing only when asked to do so by your IBM Service Representative. Tracing
slows down IBM MQ Explorer and the trace files can rapidly become large.

Procedure
1. The IBM MQ Explorer trace mechanism relies on AspectJ and Equinox Weaving plug-ins being
installed. To confirm that they are installed:
a) Click Help
b) Click About...
c) Click Installation Details
d) Click the Plug-ins tab.
The org.eclipse.equinox.weaving.caching.j9 plug-in no longer exists, but you require this
plug-in if you are using IBM MQ 9.0 Long Term Support, or IBM MQ 9.0 Continuous Delivery releases,
prior to IBM MQ 9.0.4.
Verify that the following plug-ins are installed:

org.aspectj.runtime
org.aspectj.weaver

org.eclipse.equinox.weaving.aspectj
org.eclipse.equinox.weaving.caching
org.eclipse.equinox.weaving.caching.j9
org.eclipse.equinox.weaving.hook

2. If they are not already installed, install the AspectJ and Equinox Weaving plug-ins. These plugins
must match the version of Eclipse you are using and can be downloaded from the Eclipse AspectJ
Development Tools download site. To determine which download site to use for your version of
Eclipse, see https://projects.eclipse.org/projects/tools.ajdt.
For information about the Eclipse level that IBM MQ Explorer is built on, see “What's new and what's
changed in IBM MQ Explorer” on page 6.
Currently, these builds are available as development builds only; you should select the latest one
available.
To install the AspectJ and Equinox Weaving plug-ins, complete the following substeps:
a) Click Help then click Install New Software...

230 IBM MQ Explorer

 b) Click Add... then enter the location of the download site appropriate for the Eclipse version.
For example, for Eclipse 4.4, enter https://download.eclipse.org/tools/ajdt/44/dev/
update.
c) Click OK
A list of available software is displayed.
d) Expand the Other AJDT Tools (Optional) category and select AspectJ Compiler and Equinox
Weaving SDK.
e) Click Next and follow the wizard instructions.
3. Trace IBM MQ Explorer.
Close and restart the IBM MQ Explorer by using the runwithtrace script. For the script to use for
Windows operating systems, see “runwithtrace command script for Windows” on page 231. For the
script to use for Linux operating systems, see “runwithtrace command script for Linux” on page 233.
The script must be run from the directory that contains the Eclipse executable file.
When you start the IBM MQ Explorer by using the runwithtrace command, extra parameters are
incorporated that enable tracing of IBM MQ Explorer. Note the runwithtrace command takes no
parameters itself.
The output location of the trace file is printed to the command line when the command runs because
the actual location is dependent upon
• the status of the IBM MQ installation.
• the user permissions.
The IBM MQ Explorer trace files have a name of the format AMQYYYYMMDDHHmmssmmm.TRC.n that
indicates the start time of the trace session. When a trace file reaches its maximum size, the trace
facility renames all trace files from the session by incrementing the file suffix .n by one. The trace
facility then creates a new file with the suffix .0 that contains the latest trace.
4. Uninstall the AspectJ and Equinox Weaving plug-ins. When you finish with IBM MQ Explorer trace,
you can remove the AspectJ and Equinox Weaving plugins from the Eclipse environment. To uninstall
AspectJ and Equinox Weaving plug-ins:
a) Click Help and then click About....
b) Click Installation Details and then click the Installed Software tab.
c) Select the items AspectJ Complier and Equinox Weaving SDK.
d) Click Uninstall... and follow the wizard instructions.
Related tasks
“Collecting IBM MQ Explorer trace” on page 229
When you start the IBM MQ Explorer by using the runwithtrace command, extra parameters are
incorporated that enable tracing of IBM MQ Explorer.
“Installing IBM MQ Explorer into Eclipse environments” on page 10
You can install IBM MQ Explorer into your own Eclipse environment or Eclipse-based product to help with
developing Java applications or to develop your own extensions.

runwithtrace command script for Windows

To collect trace from an instance of IBM MQ Explorer that is installed into your own Eclipse environment
or Eclipse-based product, you use a variant of runwithtrace command. A command script for use on
Windows systems is embedded in this topic.
Copy and save the following script as a text file called runwithtrace.cmd, then run the script as
described in step 3 of "Using IBM MQ Explorer trace in other Eclipse environments".

@echo off

REM ---------------------------------------------------------------------------

Introduction to IBM MQ Explorer 231

 REM File Name : runwithtrace.cmd
REM
REM File Description : This script is used when MQ Explorer plug-ins are
REM installed into another Eclipse or Eclipse based product.
REM It launches eclipse and will run WebSphere MQ Explorer with trace enabled.
REM
REM ---------------------------------------------------------------------------

setlocal

REM ---------------------------------------------------------------------------
REM Special case for when MQ Explorer plug-ins are installed in an Eclipse or an
REM Eclipse based product.
REM
REM eclipse needs to be in current directory.
REM ---------------------------------------------------------------------------

if exist "eclipse.exe" goto :MQExplorer_found

goto :no_MQExplorer

:MQExplorer_found
set explorerCmd=eclipse.exe

REM ---------------------------------------------------------------------------
REM Special processing for enabling trace
REM 1. Allow a user to supply their own properties file, pointed to by the
REM MQPROPERTIES environment variable
REM 2. Otherwise, build a properties file in %temp% which writes trace
REM to the MQ_INSTALLATION_PATH\trace directory if writeable, otherwise to
REM %temp% itself
REM ---------------------------------------------------------------------------

if not "%MQPROPERTIES%."=="." goto :own_properties

REM Create a properties file with the default trace options

set MQPROPERTIES=%temp%\mq_trace.properties

REM Set MQTRACE to temp or the MQ trace directory

if "%MQ_JAVA_DATA_PATH%."=="." goto :set_to_temp

set MQTRACE=%MQ_JAVA_DATA_PATH%\trace
goto :finish_set

:set_to_temp
set MQTRACE=%temp%

:finish_set

REM -------------------------------------------------------------------
REM Where should trace be written to - Try the MQ trace directory first
REM -------------------------------------------------------------------
if "%MQTRACE%"=="%MQ_JAVA_DATA_PATH%\trace" goto :MQ_dir_available
echo Trace will be written to the temporary directory %MQTRACE%
goto :finish_trace_location

:MQ_dir_available
echo Confirming write access to the MQ trace directory %MQTRACE%
echo Test >> "%MQTRACE%\test.gui" 2>NUL
if exist "%MQTRACE%\test.gui" goto :MQ_dir_used
echo Trace will be written to the temporary directory %temp%
set MQTRACE=%temp%
goto :finish_trace_location

:MQ_dir_used
echo Trace will be written to the MQ trace directory %MQTRACE%
del "%MQTRACE%\test.gui" >nul 2>&1

:finish_trace_location

REM Convert back slashes to forward slashes for use in properties file
REM Note :\=/ converts back slashes to forward slashes.
set MQTRACE=%MQTRACE:\=/%

REM -------------------------------------------------------------
REM Now build the default properties file
REM -------------------------------------------------------------
echo Diagnostics.MQ=enabled > %MQPROPERTIES%
echo Diagnostics.Java=all >> %MQPROPERTIES%
echo Diagnostics.Java.Trace.Detail=high >> %MQPROPERTIES%
echo Diagnostics.Java.Trace.Destination.File=enabled >> %MQPROPERTIES%
echo Diagnostics.Java.Trace.Destination.Console=disabled >> %MQPROPERTIES%

232 IBM MQ Explorer

 echo Diagnostics.Java.Trace.Destination.Pathname=%MQTRACE% >> %MQPROPERTIES%
echo Diagnostics.Java.FFDC.Destination.Pathname=%MQTRACE% >> %MQPROPERTIES%
echo Diagnostics.Java.Errors.Destination.Filename=%MQTRACE% >> %MQPROPERTIES%

:own_properties

REM ---------------------------------------------------------------------------
REM Build the command line
REM All parameters passed to this script are passed through.
REM Set the load time weaving options, it's set as part of the vmargs parameter.
REM ---------------------------------------------------------------------------

REM Note.
REM In eclipse and eclipse based products the osgi.framework.extensions is set
REM as part of the Equinox Weaving plug-ins eclipse installation.
REM Therefore unlike in the normal MQ Explorer script LTW_OPTIONS is empty

REM set LTW_OPTIONS=-Dosgi.framework.extensions=org.eclipse.equinox.weaving.hook

set LTW_OPTIONS=
set explorerCmd=%explorerCmd% %* -vmargs -Xmx512M %LTW_OPTIONS% "-
Dcom.ibm.mq.commonservices=%MQPROPERTIES%"

REM ---------------------------------------------------------------------------
REM Launch MQ Explorer
REM ---------------------------------------------------------------------------
echo Launching %explorerCmd%
start %explorerCmd%

goto :end

:no_MQExplorer
echo ERROR - eclipse.exe not found in the current directory.
echo ERROR - This script needs to be run in the same directory as eclipse.exe

:end
endlocal

runwithtrace command script for Linux

To collect trace from an instance of IBM MQ Explorer that is installed into your own Eclipse environment
or Eclipse-based product, you use a variant of runwithtrace command. A command script for use on
Linux systems is embedded in this topic.
Copy and save the following script as a text file called runwithtrace.cmd, then run the script as
described in step 3 of "Using IBM MQ Explorer trace in other Eclipse environments".

#!/bin/sh
#---------------------------------------------------------------------------
# File Name : runwithtrace
#
# File Description : This script is used when MQ Explorer plug-ins are
# installed into another Eclipse or Eclipse based product.
# It launches eclipse and will run WebSphere MQ Explorer with trace enabled.
#
#---------------------------------------------------------------------------

# ---------------------------------------------------------------------------
# Special processing for enabling trace
# 1. Allow a user to supply their own properties file, pointed to by the
# MQPROPERTIES environment variable
# 2. Otherwise, build a properties file in /tmp which writes trace
# to /var/mqm/trace directory if writeable, otherwise to /tmp itself
# ---------------------------------------------------------------------------

# test if variable is not set or refers to a file that does not exist
if [ -z "$MQPROPERTIES" -o ! -f "$MQPROPERTIES" ]
then
# Create a properties file with the default trace options
MQPROPERTIES=/tmp/mq_trace.properties
# -----------------------------------------------------
# Where should trace go - Try the trace directory first
# -----------------------------------------------------
echo "Confirming write access to the MQ trace directory /var/mqm/trace"
MQTRACE=/var/mqm/trace
# test if dir exists and is writable

Introduction to IBM MQ Explorer 233

 if [ -d $MQTRACE -a -w $MQTRACE ]
then
echo "Trace will be written to the MQ trace directory /var/mqm/trace"
else
echo "Trace will be written to the temporary directory /tmp"
MQTRACE=/tmp
fi

# -------------------------------------------------------------
# Now build the default properties file
# -------------------------------------------------------------
echo Diagnostics.MQ=enabled > $MQPROPERTIES
echo Diagnostics.Java=all >> $MQPROPERTIES
echo Diagnostics.Java.Trace.Detail=high >> $MQPROPERTIES
echo Diagnostics.Java.Trace.Destination.File=enabled >> $MQPROPERTIES
echo Diagnostics.Java.Trace.Destination.Console=disabled >> $MQPROPERTIES
echo Diagnostics.Java.Trace.Destination.Pathname=$MQTRACE >> $MQPROPERTIES
echo Diagnostics.Java.FFDC.Destination.Pathname=$MQTRACE >> $MQPROPERTIES
echo Diagnostics.Java.Errors.Destination.Filename=$MQTRACE >> $MQPROPERTIES

fi

# ---------------------------------------------------------------------------
# Build the command line to run
# Look in the current directory
# All parameters passed to this script are passed through.
# Set the load time weaving options, it's set as part of the vmargs parameter.
# ---------------------------------------------------------------------------

# Special case for when MQ Explorer plug-ins are installed in an Eclipse or an

# Eclipse based product.
# eclipse needs to be in current directory.

if [ -f "eclipse" ]
then
explorerCmd="./eclipse"
fi

if [ ! -f "${explorerCmd}" ]
then
echo "ERROR - eclipse executable could not be found in the current directory"
echo "ERROR - This script needs to be run in the same directory as the eclipse executable"
exit 1
fi

# Note.
# In eclipse and eclipse based products the osgi.framework.extensions is set
# as part of the Equinox Weaving plug-ins eclipse installation.
# Therefore unlike in the normal MQ Explorer script LTW_OPTIONS is empty

# LTW_OPTIONS=-Dosgi.framework.extensions=org.eclipse.equinox.weaving.hook
LTW_OPTIONS=
explorerCmd="$explorerCmd $* -vmargs -Xmx512M $LTW_OPTIONS
-Dcom.ibm.mq.commonservices=$MQPROPERTIES"

# ---------------------------------------------------------------------------
# Launch MQ Explorer
# ---------------------------------------------------------------------------
echo Launching $explorerCmd

exec $explorerCmd

Using IBM MQ trace

IBM MQ trace enables you to collect detailed information about what IBM MQ is doing.

About this task

You normally enable tracing only when asked to do so by your IBM service representative. Tracing slows
down IBM MQ and the trace files can rapidly become very large.
For more information, see strmqtrc and endmqtrc.
Using IBM MQ Explorer to start and stop tracing is equivalent to using the control commands strmqtrc
-e and endmqtrc -e, which trace all processes on the specified queue manager.

234 IBM MQ Explorer

 IBM MQ trace does not trace IBM MQ Explorer. For details about how to trace IBM MQ Explorer, see
“Troubleshooting problems with IBM MQ Explorer” on page 228.

Starting trace

About this task

To turn on the trace service:

Procedure
1. In the Navigator view, right-click IBM MQ, then click Trace....
2. In the Trace dialog, select one or more of the following options:
• To output data for every trace point in the system, click All.
• To activate tracing at high-detail level for flow processing trace points, click Detail.
3. Click Start.

Results
The IBM MQ trace starts writing information to the trace files. IBM MQ continues to write to the trace files
until you stop the trace.

Stopping trace

About this task

To turn off the trace service:

Procedure
1. In the Navigator view, right-click IBM MQ, then click Trace....
2. Click Stop.

Results
The IBM MQ trace stops writing to the trace files.

Viewing trace files

About this task

You can find the local trace files in the trace subdirectory of the directory that was chosen during the
installation for data files. If you installed to the default directories, the trace directory is in the IBM MQ
program installation directory.
The files in the trace directory have names like AMQ123.TRC where 123 is the PID of the process that
wrote the file. You can view the files using any viewer that can display a simple ASCII file.

Collecting Javacore from IBM MQ Explorer

For certain issues, it is useful to collect a Javacore file from IBM MQ Explorer to check the status of the
internal threads within the user interface.

About this task

You should collect Javacore only when asked to do so by your IBM Service Representative. The output
location for the Javacore depends on the platform that IBM MQ Explorer is running on:

Introduction to IBM MQ Explorer 235

 • On Linux, the Javacore is generated in the current working directory, which is typically the
user's home directory. For example:
Directory: /home/mquser/
Filename example: javacore.20200108.101650.31132.0001.txt

• On Windows, the Javacore is generated in the user's home directory. For example:
Directory: C:\Users\MQUser\
Filename example: javacore.20200108.101825.4100.0001.txt
To collect a Javacore, complete the following steps.

Procedure
1. Close IBM MQ Explorer.

2.
On Linux:
a) Use the command MQExplorer to run IBM MQ Explorer.
• If you are running the IBM MQ Explorer that was installed as part of a full IBM MQ server
installation, the MQExplorer command is in /opt/mqm/bin, where opt/mqm is the IBM MQ
installation directory.
• If you installed the stand-alone IBM MQ Explorer (MS0T SupportPac),
the MQExplorer command is in MQ_EXPLORER_INSTALLATION_PATH, where
MQ_EXPLORER_INSTALLATION_PATH is the stand-alone IBM MQ Explorer (MS0T SupportPac)
installation path.
b) Determine the process identifier for the IBM MQ Explorer process. The following example shows
how to determine the process identifier for the current user:

ps -u `whoami` | grep MQExplorer | awk ' { print $1 } '

If you are not sure how to get the process identifier, contact your systems administrator.
c) Run following the command to generate the Javacore:

kill -3 <MQExplorer process identifier>

3.
On Windows:
a) Use the command MQExplorer -debug to run IBM MQ Explorer.
• If you are running the IBM MQ Explorer that was installed as part of a full IBM MQ server
installation, the MQExplorer command (MQExplorer.exe) is in the MQ_INSTALLATION_PATH/
bin64 directory, where MQ_INSTALLATION_PATH is the IBM MQ installation path.
• If you installed the stand-alone IBM MQ Explorer (MS0T SupportPac), MQExplorer.exe is
in MQ_EXPLORER_INSTALLATION_PATH directory, where MQ_EXPLORER_INSTALLATION_PATH is
the IBM MQ Explorer (MS0T SupportPac) installation path.
b) When a command-line window appears for IBM MQ Explorer, set Windows focus on this window,
and press Control+Break to generate a Javacore.
Related reference
MQExplorer (launch IBM MQ Explorer)

236 IBM MQ Explorer

Using MQ Telemetry
IBM MQ Telemetry supports the connection of an IBM MQ message server to telemetry devices including,
but not limited to, sensors and actuators, mobile phones, smart meters, medical devices, vehicles, and
satellite locations. The connection is made possible by the MQ Telemetry Transport (MQTT) protocol.
MQTT is an open message format and protocol that you can use to transfer messages from telemetry
devices to a message server or the other way round. It can run on constrained devices and across
constrained networks. Constraints on devices include low memory and processing capability. Constraints
on networks include low bandwidth, high latency, high cost, and fragility. MQTT has been successfully
deployed in various industries, including energy, utilities, and the retail sector.
Related concepts
MQ Telemetry security
Related tasks
Developing applications for MQ Telemetry

MQ Telemetry objects
This information provides details on MQ Telemetry objects which include: telemetry channels, telemetry
channel status objects, and the MQXR service.
Related concepts
“Telemetry (MQXR) service” on page 237
The IBM MQ Extended Reach (MQXR) service is more commonly referred to as the MQ Telemetry service.
It is a TCP/IP listener that is installed as an IBM MQ service. It runs when a queue manager starts or
stops.
“Telemetry channels” on page 238
A Telemetry channel is a communication link between a queue manager on IBM MQ, and MQTT clients.
Each channel might have one or more telemetry devices connected to it.
“Telemetry channel status objects” on page 238
A telemetry channel status object is an MQTT client that collects information from telemetry devices
attached to it and sends the information to IBM MQ.

Telemetry (MQXR) service

The IBM MQ Extended Reach (MQXR) service is more commonly referred to as the MQ Telemetry service.
It is a TCP/IP listener that is installed as an IBM MQ service. It runs when a queue manager starts or
stops.
An MQXR service is defined when you run the Define sample configuration wizard. Only one instance of
this service can be defined per queue manager.
To view the MQXR service, click the Services folder on the queue manager to which the service belongs,
in the Navigator view. Ensure that the Show System Objects option is selected, and navigate to the
service. The service is called SYSTEM.MQXR.SERVICE.
You can modify the properties of an MQXR service like a standard IBM MQ service.
Related tasks
“Defining the MQXR service” on page 246
The MQXR service is defined when you run the Define sample configuration wizard. You can also define
the MQXR service manually.
“Starting and stopping the MQXR service” on page 250

Introduction to IBM MQ Explorer 237

 Before you can start or stop the MQXR service, the queue manager must be running.

Telemetry channels
A Telemetry channel is a communication link between a queue manager on IBM MQ, and MQTT clients.
Each channel might have one or more telemetry devices connected to it.
For messages flowing from IBM MQ to MQTT clients, messages are taken from the default MQTT transmit
queue, and sent through the telemetry channel. Messages destined for specific MQTT clients are routed to
them using their client identifiers.

Advanced option
Telemetry channels have an option which sets the maximum number of client connections that can be
displayed in the Channel Status Content view. This option is called Max responses. The default value
is 500. Consider configuring this option before you start your queue manager. If your queue manager is
running, you must restart it to apply the advanced option changes.
To configure the maximum responses option, perform the following actions:
1. Click Window > Preferences.
2. Expand IBM MQ Explorer, then click Telemetry.
3. In the Max responses field, type the number of client connections to display at any one time.
4. Click OK.
Client connections on all telemetry channels up to the maximum response limit are shown in the Channel
Status Content view. If client connections exceed this limit, a warning is displayed within the Content
view. For example, if you set the maximum responses to 10 and you reach or exceed this number, the
following warning is displayed: The display has been limited to the first 10 responses.
Use a filter to select a subset of responses.
The Telemetry channel status window shows client connections specific to that channel. The maximum
response option limit applies only to client connections on this channel.
Related tasks
“Creating and configuring a telemetry channel” on page 243
A telemetry channel connects a number of MQTT clients to IBM MQ. Create one or more telemetry
channels on a queue manager. Each of these telemetry channels might have different configuration
settings, making it easier to manage the clients attached to them.
“Starting and stopping a telemetry channel” on page 250
“Viewing the status of a telemetry channel” on page 251
“Filtering Telemetry objects” on page 252
If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

Telemetry channel status objects

A telemetry channel status object is an MQTT client that collects information from telemetry devices
attached to it and sends the information to IBM MQ.
MQTT clients appear as queue managers to other standard IBM MQ queue managers. In the same
way that channels are a communication link between queue managers in IBM MQ, a telemetry channel
performs the same purpose. It links a queue manager to MQTT clients.
You can write your own MQTT client application that implements the MQTT v3 protocol. For more
information about writing MQTT client applications, see Developing applications for IBM MQ Telemetry.

238 IBM MQ Explorer

 Purge an MQTT client
Purging an MQTT client connection disconnects the client from a telemetry channel and cleans up the
state of that client.
Cleaning the state of a client involves deleting all pending publications, and removing all subscriptions
from that client.
Related tasks
“Viewing the status of a telemetry channel” on page 251
“Filtering Telemetry objects” on page 252
If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.
Related reference
“Telemetry channel status attributes” on page 258
As with IBM MQ, you can view the status of a telemetry channel. For each attribute, there is a brief
description of what information the attribute is used for. All of the telemetry channel status attributes are
read-only.

MQTT client utility

The MQTT client utility is a Java application with which you can explore the features of MQTT, that is,
connecting to a queue manager, and publishing and subscribing to topics.
You can use the client utility to verify your telemetry setup (for example, when you create a telemetry
channel), or the client might serve as an aid when you are developing and debugging applications.
For more information about the features and properties of the MQTT client utility, see the following
descriptions:
Publish
Publish a message to a topic which is then distributed to interested subscribers.
Subscribe
Clients and the MQXR listener can register their interest in a topic by subscribing to it and thus receive
messages published to that topic.
Topic
A topic is the key that identifies the information channel to which messages are published.
Subscribers use the topic name to identify the information channels on which they want to receive
published messages.
Topic wildcards
A subscription might contain special characters, and you can subscribe to multiple topics at once.
A topic level separator uses the forward slash (/) to separate each level within a topic, creating a
hierarchical structure. For example, ibm/qmgr/apple. Topic level separators allow more flexibility
and simplifies management of topics.
For subscriptions, two wildcard characters are supported:
• The number sign (#) is used to match any number of levels within a topic. For example, if you
subscribe to the topic ibm/qmgr/#, you receive messages on the topics ibm/qmgr/apple and
ibm/qmgr/orange.
• The plus sign (+) matches only one topic level. For example, ibm/qmgr/+ matches ibm/qmgr/
apple but not ibm/qmgr/apple/queue.
You can use the + at the end of the topic tree or within the topic tree. For example, ibm/+ and
ibm/+/orange are both valid.
Publication topics are not allowed to contain either the + or #.
Message
A message, in the context of an MQTT client utility, refers to the message payload distributed to
subscribers that show interest in a topic. Messages can consist of alphanumeric characters.

Introduction to IBM MQ Explorer 239

 Quality of service (QoS)
The MQTT client utility provides three qualities of service, as follows:
At most once (QoS = 0)
The message is delivered at most once, or it is not delivered at all. There is no acknowledgment on
receipt of the message.
The message might be lost if the client is disconnected, or if the server fails.
At least once (QoS = 1)
The message is delivered at least once. It might be delivered multiple times if no acknowledgment
is received after a period of time, or if a failure is detected and the communication session is
restarted.
The message must be stored locally at the sender until an acknowledgment is received, in case the
message must be sent again. Messages might be duplicated at the receiving application.
Exactly once (QoS = 2)
This is the highest level of delivery where a message is delivered once and only once. Delivery is
assumed, but duplicate messages are not delivered to the receiving application.
Retained
This option is only used when publishing messages. It determines whether a message, from a
publication on a topic, is retained by the MQTT server (in IBM MQ, the queue manager) after it
is delivered to the current subscribers. If you create a subscription to a topic that has a retained
publication, you immediately receive the most recent retained publication on that topic.
Last will and testament
This is a connection option which determines the message that is sent to IBM MQ, in the event of the
MQTT client being disconnected unexpectedly. This option includes a topic, message, QoS, and the
option to retain the publication. Consider setting the QoS to 1 or 2 to guarantee delivery.
Clean session
Starting an MQTT client with a clean session removes all pending publications, and all old
subscriptions that existed on the client before connection. If no previous session exists, the client
utility starts with a new session.
Client history
The client history provides information about events that occur while using the MQTT client utility.
Examples of events include: Connected, Disonnected, Published, or Subscribed.
View the full details of an entry by selecting the entry and pressing Enter. Alternatively, double-click
the entry.
Reorder the columns in the client history by dragging the column names and placing them in any order
of your choice.
Related tasks
“Running the MQTT client utility” on page 241
You can run the MQTT client utility in several ways. You can run it when you create a new telemetry
channel, when you run the Define sample configuration wizard, from an already existing telemetry
channel, or from the MQ Telemetry welcome page.
“Using the MQTT client utility” on page 242

240 IBM MQ Explorer

Use one or more MQTT client utilities to test your telemetry setup. Within the scope of this task, one client
utility is used to publish and subscribe to messages.

Running the MQTT client utility

You can run the MQTT client utility in several ways. You can run it when you create a new telemetry
channel, when you run the Define sample configuration wizard, from an already existing telemetry
channel, or from the MQ Telemetry welcome page.

About this task

When you launch the MQTT client utility after a basic configuration is set up or a new telemetry channel is
created, the utility retains the port number and host name of the telemetry channel.

Methods to launch the client utility

Running the utility from the Define sample configuration wizard
Follow the steps for defining a sample configuration. For more information, see “Defining a sample
configuration” on page 245.
1. When the Define sample configuration wizard starts, select Launch MQTT Client Utility.
2. Click Finish.
Running the utility from the New Telemetry Channel wizard
Follow the steps for creating a new telemetry channel using the wizard. For more information, see
“Creating and configuring a telemetry channel” on page 243.
1. On the Summary page of the wizard, select Launch MQTT Client Utility.
2. Click Finish.
Running the utility from the IBM MQ Telemetry Welcome page
1. Click the Telemetry folder to display the MQ Telemetry welcome page.
2. From the Content view, click Run MQTT Client Utility.
Running the utility from a telemetry channel
You can launch the MQTT client utility on specific telemetry channels.
1. Expand the Telemetry folder, then click Channels. Your telemetry channels are listed in the
Content view.
2. Right-click a telemetry channel and select Launch MQTT Client Utility.
Note: If you choose to perform authentication with either JAAS or TLS, you do not get the option to
launch the MQTT client utility from a telemetry channel. This is because the MQTT client utility does
not support JAAS or TLS authentication. However, you can write your own MQTT client application to
support authentication using JAAS or TLS.
Related tasks
“Defining a sample configuration” on page 245
You can use the Define sample configuration wizard to reconfigure your queue manager, making it
suitable for the MQ Telemetry feature. The sample configuration defines and starts the MQXR service,
defines the transmit queue, and creates a sample telemetry channel.
“Creating and configuring a telemetry channel” on page 243
A telemetry channel connects a number of MQTT clients to IBM MQ. Create one or more telemetry
channels on a queue manager. Each of these telemetry channels might have different configuration
settings, making it easier to manage the clients attached to them.
“Using the MQTT client utility” on page 242

Introduction to IBM MQ Explorer 241

 Use one or more MQTT client utilities to test your telemetry setup. Within the scope of this task, one client
utility is used to publish and subscribe to messages.

Using the MQTT client utility

Use one or more MQTT client utilities to test your telemetry setup. Within the scope of this task, one client
utility is used to publish and subscribe to messages.

Before you begin

• Make sure that the telemetry (MQXR) service is running.
• You need at least one running telemetry channel to successfully use the MQTT client utility.

About this task

There are several methods to start the MQTT client utility. For more information about running the client
utility, see “Running the MQTT client utility” on page 241. Within the scope of this task, the client utility is
started from the PlainText telemetry channel created with the Define sample configuration wizard.
By default, the MCA user ID of the PlainText channel is set to guest on Windows, and nobody on
Linux. You need these default values in order to subscribe to topics.

Procedure
1. Right-click the PlainText telemetry channel, then click Run MQTT Client Utility. The client utility
window opens. The Host and Port fields are automatically set using values from the selected
telemetry channel.
2. Type a client ID in the Client identifier field. A new client identifier is generated each time you launch
an MQTT client utility from a telemetry channel. You can either use the generated identifier or type a
name of your choice. If you run more than one client utility on a telemetry channel, ensure that you
use different client IDs for each client utility. If two MQTT client utilities have the same client ID, the
most recent one to connect forcefully disconnects the previous one. When you run more than one
MQTT client utility from a telemetry channel, the generated client identifier has a numeric suffix that
is incremented every time a new client utility is started.
3. Click Options to open the Connection Options window. You can start the client utility with a clean
session, or configure the last will and testament options.
4. Click Connect to establish a connection with the PlainText telemetry channel. A new event entry of
Connected is displayed in the Client history.
5. Type a topic name in the Subscription Topic field. The default topic name is testTopic and this
name is used throughout this task.
6. Select the subscription quality of service from the Request QoS menu.
7. Click Subscribe to subscribe to the topic testTopic. A new event entry of Subscribed is displayed
in the Client history, along with the topic name, QoS, and the time of subscription.
8. Accept the default topic name, testTopic, in the Publication Topic field. In general, ensure that
the subscription and publication topics match so that the MQTT client receives messages from the
correct topic.
9. Type a message in the Message field. The default message test is Test Message.
10. Select the publication quality of service from the Request QoS menu.
11. Select Retained to forward the most recent retained publication on this topic to new subscribers.
12. Click Publish to publish the message on the testTopic topic for interested subscribers. A new
event entry of Published is displayed in the Client history, along with the topic name, QoS, whether
the message is retained, and the time of subscription. On the receiving client utility, a new event entry
of Received is displayed in the Client history.
13. Select the received message in the Client history, then click View message to view the full message
in the Message Viewer window. Alternatively, select the message and press Enter, or double-click
the received message.

242 IBM MQ Explorer

 Results
Publishing messages and viewing the messages from topics subscribed to, shows that you have correctly
set up your queue manager for Telemetry.
Related concepts
“MQTT client utility” on page 239
The MQTT client utility is a Java application with which you can explore the features of MQTT, that is,
connecting to a queue manager, and publishing and subscribing to topics.
Related tasks
“Resolving problems if your MQTT client fails to connect” on page 254
If your MQTT client cannot connect to a telemetry channel, there might be a number of reasons.
“Resolving problems if your MQTT client disconnects unexpectedly” on page 255
Discover what is going wrong when an MQTT client is unexpectedly disconnected from a telemetry
channel.

Configuring MQ Telemetry using IBM MQ Explorer

Configure IBM MQ to run the Telemetry feature, using IBM MQ Explorer. Create telemetry objects, and
test your telemetry setup using the MQTT client utility.

About this task

Change the MQ Telemetry information by modifying the values specified on a set of configuration
attributes that govern the Telemetry feature. The sample configuration provides a basic setup with
defined attributes. Change the behavior of the preset telemetry objects by modifying their attributes or
properties. For more information about the meaning of each attribute, see “Telemetry channel properties”
on page 256 and “Telemetry channel status attributes” on page 258.
Related tasks
“Creating and configuring a telemetry channel” on page 243
A telemetry channel connects a number of MQTT clients to IBM MQ. Create one or more telemetry
channels on a queue manager. Each of these telemetry channels might have different configuration
settings, making it easier to manage the clients attached to them.
“Defining a sample configuration” on page 245
You can use the Define sample configuration wizard to reconfigure your queue manager, making it
suitable for the MQ Telemetry feature. The sample configuration defines and starts the MQXR service,
defines the transmit queue, and creates a sample telemetry channel.
“Defining the MQXR service” on page 246
The MQXR service is defined when you run the Define sample configuration wizard. You can also define
the MQXR service manually.
“Defining the MQXR service manually on Linux” on page 247
“Defining the MQXR service manually on Windows” on page 248

Creating and configuring a telemetry channel

A telemetry channel connects a number of MQTT clients to IBM MQ. Create one or more telemetry
channels on a queue manager. Each of these telemetry channels might have different configuration
settings, making it easier to manage the clients attached to them.

Procedure
Create and configure a new telemetry channel by completing the following steps:
1. Right-click the telemetry Channels folder and click New > Telemetry channel. The New Telemetry
Channel wizard opens.
2. Type the name of the channel in the Channel name field.

Introduction to IBM MQ Explorer 243

 The names of telemetry channels are restricted to 20 characters. The characters that can be used in
a telemetry channel name, as with all IBM MQ names, are:
Uppercase A-Z
Lowercase a-z
Numerics 0-9
Period (.)
Underscore (_)
Forward slash (/)
Percent sign (%)
Leading or embedded blanks are not allowed.
3. Type the port number in the Port number field. The default port number for a telemetry channel
without TLS security is 1883.
4. Optional: If you choose to secure your new telemetry channel using TLS, select Secure channel
using SSL. The port number changes to 8883, which is the default for a channel secured using TLS.
a) Click Next.
b) Type the name of the SSL/TLS file to use in the SSL Key File field.
c) Type the password to unlock the key file in the SSL Passphrase field.
d) Select Identify client using digital certificate to force all clients to send their privately signed
digital certificate for authentication, or select Allow anonymous clients to stop the telemetry
channel from authenticating the client using TLS.
5. Click Next.
6. Select one of the following options for client authentication:
• Don't check client supplied username and password: Select this option if you want your
program to either perform its own authentication, or you do not need any clients authenticated.
• Check client supplied username and password (using JAAS): Select this option to verify
the identity of the client using JASS. Select the name of the JAAS configuration you want to
implement from the JAAS config name menu.
7. Click Next.
8. Select from one of the following menu options:
• Select MQTT Client ID to use the supplied MQTT client ID.
• Select Fixed user ID to disregard whatever user ID is supplied by the client. Type your preferred
user ID in the User ID field. The default value is Guest on Windows systems, and nobody on
Linux systems.
• Select Username provided by client to use the user name supplied in by the client. If no user
name is supplied, the client fails to connect to IBM MQ.
9. Click Next.
10. Optional: Select Launch MQTT client utility to launch the graphical utility to test the MQTT protocol.
11. Review the list of actions to be performed and click Finish.

Results
A new telemetry channel is created. View this channel by expanding the Telemetry folder and clicking the
Channels folder.

What to do next
You can now manage your telemetry channel authorities.
For information about how to grant authorities in IBM MQ Explorer, see “Managing object authorities with
an authorization service” on page 135.

244 IBM MQ Explorer

Related tasks
“Defining a sample configuration” on page 245
You can use the Define sample configuration wizard to reconfigure your queue manager, making it
suitable for the MQ Telemetry feature. The sample configuration defines and starts the MQXR service,
defines the transmit queue, and creates a sample telemetry channel.
“Defining the MQXR service” on page 246
The MQXR service is defined when you run the Define sample configuration wizard. You can also define
the MQXR service manually.

Defining a sample configuration

You can use the Define sample configuration wizard to reconfigure your queue manager, making it
suitable for the MQ Telemetry feature. The sample configuration defines and starts the MQXR service,
defines the transmit queue, and creates a sample telemetry channel.

Before you begin

Before you run the Define sample configuration wizard:
• You must install the IBM MQ Telemetry feature on the computer.
• You must be willing to let the wizard reconfigure your queue manager. If you are unsure of the
implications, create a new queue manager solely for this purpose, or see “Implications of running the
sample configuration” on page 253.

About this task

By using the sample configuration to get started, you can set up a basic configuration on your computer so
that you can explore the telemetry features. You cannot run the sample configuration twice on the same
queue manager unless you remove one or more of the IBM MQ object definitions created. When an object
definition created by the sample configuration is deleted, running the wizard again only re-creates that
missing object.

Procedure
1. From the Telemetry welcome page, click Define sample configuration. The Define sample
configuration wizard opens.
2. Review the list of actions that will occur on completion of this wizard, and click Finish.

Results
The Define sample configuration wizard performs the following actions and creates the appropriate
resources:
• Defines and starts the MQXR service.
• Defines the default transmit queue.
• Allows Guest on Windows systems, and nobody on Linux systems, to send messages to clients
connected to the MQTT listener.
• Allows Guest on Windows systems, and nobody on Linux systems, to both publish on and subscribe to
any topic.
• Defines a sample telemetry channel.
Also, the Define sample configuration link on the Telemetry welcome page is replaced by The sample
configuration has been set up for this queue manager. This is the first form of visual verification that the
sample configuration was set up properly.

Introduction to IBM MQ Explorer 245

 What to do next
You can view the sample telemetry channel that the wizard created by expanding the Telemetry folder
and clicking the Channels folder.
If you remove one of the definitions created by the sample configuration wizard, you can run the wizard
again. The wizard creates the same resource that you deleted and informs you in the summary section.

Defining the MQXR service

The MQXR service is defined when you run the Define sample configuration wizard. You can also define
the MQXR service manually.

About this task

Running the Define sample configuration wizard creates some IBM MQ objects and resources. One of
these objects is the MQXR service. For more information about running the Define sample configuration
wizard, see “Defining a sample configuration” on page 245.
You can also define the MQXR service manually by performing a list of steps. For more information,
see “Defining the MQXR service manually on Windows” on page 248 and “Defining the MQXR service
manually on Linux” on page 247.

Results
The creation of an expansible Telemetry folder node indicates the successful definition of the MQXR
service.
Related tasks
“Telemetry node does not appear” on page 255
Find out what to look for if the Telemetry node does not appear.

Encrypting passphrases for MQTT TLS channels

You can encrypt passphrases for MQTT TLS channels with the MQXR service STARTARG options, -sf and
-sp.

About this task

The -sf option provides a credentials key file for encryption of MQTT TLS channel passphrases. Note
that, for convenience, a default key is provided.
The -sp option specifies the protection mode. The default value is 2 to use the more secure credentials
protection method. See “Defining the MQXR service manually on Linux” on page 247 or “Defining the
MQXR service manually on Windows” on page 248 for more information, depending on the operating
systems your enterprise uses.
When a channel is created or altered, the passphrases are encrypted using the credentials key file
provided for the -sf option. Encrypted passphrases are stored in the platform-specific properties file,
mqxr_win.properties or mqxr_unix.properties.
Example of an encrypted passphrase stored in the platform-specific properties file:

com.ibm.mq.MQXR.channel.SSL.PassPhrase=<MQXR>2!kvAzYv/1aCMfSQ5igkFVmQ==
!f4rX5KL7aFKHJl7Ln0X+OQ==

Example to encrypt passphrases using the default key:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+"

-sf "[DEFAULT]"')

where DEFAULT means the default key is used for encryption of passphrases.

246 IBM MQ Explorer

 Attention: The DEFAULT word has to be enclosed with square bracket, that is [DEFAULT].

Example to encrypt passphrases with a user defined key in keyfile.txt:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+"

-sf "c:\pathOfKeyfile\keyfile.txt"')

Creating the SYSTEM.MQXR.SERVICE on Linux, and Creating the SYSTEM.MQXR.SERVICE on Windows

are updated to specify the default key to use for encrypting MQTT TLS channels.
You can also define the MQXR service manually by performing a list of steps. For more information,
see “Defining the MQXR service manually on Windows” on page 248 and “Defining the MQXR service
manually on Linux” on page 247.
If you want to change the credentials key file used for encrypting the passphrases, carry out the following
procedure.

Procedure
1. Ensure that you know the passphrases for each MQTT TLS channel.
2. Stop the MQXR service SYSTEM.MQXR.SERVICE.
3. Alter the MQXR service SYSTEM.MQXR.SERVICE to add the STARTARG option -sf and provide the
credentials key file to be used for encryption.
For example, to encrypt passphrases using the DEFAULT key, issue the following command:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+"

-sf "[DEFAULT]"')

Similarly, to encrypt passphrases with a user defined key in keyfile.txt, issue the following command:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+"

-sf "c:\pathToKeyfile\keyfile.txt"')

4. Start the MQXR service SYSTEM.MQXR.SERVICE.

5. Change the TLS channel passphrases
Do this through IBM MQ Explorer, or by using the MQSC ALTER CHANNEL (MQTT) command.
Passphrases are encrypted using the credentials key file provided by the -sf option in step “3” on
page 247
6. Start the channels to use the new encrypted passphrase.
Notes:
• In the preceding steps, if you do not alter the channel after restarting the service, a channel with a
plain text passphrase fails to start. An error is logged to indicate that the passphrase needs to be
updated.
• If you want to turn off encryption, carry out the same procedure, but in step “3” on page 247 start
the MQXR service without specifying the -sf option.
For migration of this process, see Migrating plain text passphrases to encrypted passphrases.

Attention: MQXR still supports plain text passphrase, but you should encrypt all MQTT TLS
channel passphrases in your enterprise.

Defining the MQXR service manually on Linux

You can define the MQXR service manually by using IBM MQ Explorer. A queue manager can have only
one instance of the MQXR service defined.

Before you begin

• Install the MQ Telemetry feature.

Introduction to IBM MQ Explorer 247

 Procedure
1. In the Navigator view, right-click the Services folder.
2. Click New > Service to open the New Service Definition wizard.
3. In the Name field, type SYSTEM.MQXR.SERVICE and click Next.
4. In the Description field type a description of the service (for example, Manages clients using
MQXR protocols such as MQTT).
5. Select an option from the Service control menu.
6. In the Start command field, type +MQ_INSTALL_PATH+/mqxr/bin/runMQXRService.sh

7.
In the Start args field, include the -sf and -sp options:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" -sf “PathOfKeyFile” -sp

2')
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" -sf DEFAULT" -sp 2')

where the -sp option specifies the protection mode. The default value is 2 to use the more secure
credentials protection method.
8. In the Stop command field, type +MQ_INSTALL_PATH+/mqxr/bin/endMQXRService.sh
9. In the Stop args field, type -m +QMNAME+
10. In the StdOut field, type +MQ_Q_MGR_DATA_PATH+/mqxr.stdout
11. In the StdErr field, type +MQ_Q_MGR_DATA_PATH+/mqxr.stderr
12. Select Server from the Service type menu.
13. Click Finish.

Note: In Step “7” on page 248, the -sf option is for encrypting the passphrases of TLS channels. For
more information, see “Encrypting passphrases for MQTT TLS channels” on page 246.

Results
The MQXR service is created.
To view the MQXR service in the Navigator view click the Services folder. Ensure the Show System
Objects option is selected, and navigate to the service.
In this task, the service is called SYSTEM.MQXR.SERVICE.
Related tasks
“Defining the MQXR service manually on Windows” on page 248

Defining the MQXR service manually on Windows

You can define the MQXR service manually by using IBM MQ Explorer. A queue manager can have only
one instance of the MQXR service defined.

Before you begin

• Install the MQ Telemetry feature.

Procedure
1. In the Navigator view, right-click the Services folder.
2. Click New > Service to open the New Service Definition wizard.
3. In the Name field, type SYSTEM.MQXR.SERVICE and click Next.
4. In the Description field, type a description of the service (for example, Manages clients using
MQXR protocols such as MQTT).

248 IBM MQ Explorer

 5. Select an option from the Service control menu.
6. In the Start command field, type +MQ_INSTALL_PATH+\mqxr\bin\runMQXRService.bat

7.
In the Start args field

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" -sf “c:\PathOfKeyFile”

-sp 2')
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" -sf DEFAULT" -sp 2')

where the -sp option specifies the protection mode. The default value is 2 to use the more secure
credentials protection method.
8. In the Stop command field, type +MQ_INSTALL_PATH+\mqxr\bin\endMQXRService.bat
9. In the Stop args field, type -m +QMNAME+
10. In the StdOut field, type +MQ_Q_MGR_DATA_PATH+\mqxr.stdout
11. In the StdErr field, type +MQ_Q_MGR_DATA_PATH+\mqxr.stderr
12. Select Server from the Service type menu.
13. Click Finish.

Note: In Step “7” on page 249, the -sf option is for encrypting the passphrases of TLS channels. For
more information, see “Encrypting passphrases for MQTT TLS channels” on page 246.

Results
The MQXR service is created.
To view the MQXR service in the Navigator view click the Services folder. Ensure the Show System
Objects option is selected, and navigate to the service.
In this task, the service is called SYSTEM.MQXR.SERVICE.
Related tasks
“Defining the MQXR service manually on Linux” on page 247

Administering MQ Telemetry using IBM MQ Explorer

MQ Telemetry can be administered by using IBM MQ Explorer. You can control the MQXR service, and
monitor the MQTT clients that are connected to IBM MQ.

About this task

For information about client authorization, authenticating a telemetry channel using TLS, and JAAS
configurations, see Administering IBM MQ Telemetry.
Related tasks
“Starting and stopping the MQXR service” on page 250
Before you can start or stop the MQXR service, the queue manager must be running.
“Starting and stopping a telemetry channel” on page 250
“Viewing the status of a telemetry channel” on page 251
“Filtering Telemetry objects” on page 252

Introduction to IBM MQ Explorer 249

 If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

Starting and stopping the MQXR service

Before you can start or stop the MQXR service, the queue manager must be running.

About this task

When you start the MQXR service on a queue manager, it listens on the receiving ends of the telemetry
channels on that queue manager for incoming messages from clients.
Stopping the MQXR service has the following implications:
• The MQXR service does not listen for client connections.
• The Telemetry folder cannot be expanded. This means that you cannot:
– Create or view telemetry channels
– View client connections
– Send messages to clients
– Receive messages from clients
You can modify the properties of an MQXR service in a similar way to a standard IBM MQ service.
Right-click the service name, and click Properties.
In the Properties window, you can configure the MQXR service to start and stop with the queue manager,
or start and stop manually, by selecting the appropriate option from the Service control menu.

Procedure
Use the following steps to start or stop the MQXR service:
1. In the Navigator view, click the Services folder.
2. Ensure that Show System Objects is selected.
3. In the Content view, right-click the MQXR service name (SYSTEM.MQXR.SERVICE), and click Start or
Stop.
4. Click Yes on the confirmation dialog.

Results
The MQXR service starts or stops depending on what action you selected.
Related tasks
“Defining the MQXR service” on page 246
The MQXR service is defined when you run the Define sample configuration wizard. You can also define
the MQXR service manually.

Starting and stopping a telemetry channel

A telemetry channel is automatically started when it is created. It stops when the queue manager or
MQXR service is stopped. You can also start and stop a telemetry channel manually.
A telemetry channel also stops when it is purged. Purging a telemetry channel disconnects all the MQTT
clients connect to it, cleans up the state of the MQTT clients, and stops the telemetry channel. Cleaning
the state of a client involves deleting all the pending publications, and removing all the subscriptions from
the client.

Before you begin

Ensure that the MQXR service is defined and running.

250 IBM MQ Explorer

Procedure
Start or stop a telemetry channel manually, by performing the following steps:
1. In the Navigator view, expand the Telemetry folder.
2. Click Channels.
3. In the Content view, select the telemetry channel you want to start or stop.
4. Right-click the selected telemetry channel, then click Start or Stop.

Results
The telemetry channel starts or stops depending on what action you performed.
Note: To purge a telemetry channel, right-click the selected channel and click Purge.
Related tasks
“Creating and configuring a telemetry channel” on page 243
A telemetry channel connects a number of MQTT clients to IBM MQ. Create one or more telemetry
channels on a queue manager. Each of these telemetry channels might have different configuration
settings, making it easier to manage the clients attached to them.
“Starting and stopping the MQXR service” on page 250
Before you can start or stop the MQXR service, the queue manager must be running.

Viewing the status of a telemetry channel

The status of a running telemetry channel provides information about the clients connected to it.
A telemetry channel status object can be purged. Purging an MQTT client connection disconnects the
client from a telemetry channel and cleans up the state of the client. Cleaning the state of an MQTT client
involves deleting all pending publications, and removing all subscriptions from that client.

Procedure
To view the status of a telemetry channel, perform the following steps:
1. In the Navigator view, expand the Telemetry folder, then click the Channels folder. Your telemetry
channel definitions are displayed in the Content view.
2. Right-click the appropriate telemetry channel, then click Status. A new Content view opens in a
separate window displaying the client connections on that telemetry channel.

Viewing all client connections to telemetry channels

It is possible to view all the client connections made to all telemetry channels on a queue manager. To do
this, expand the Telemetry folder, then click the Channel status folder in the Navigator view.
All client connections to every telemetry channel on that queue manager are displayed in the Content
view. You can reorder the display of objects by clicking the relevant column name to sort the results.
Alternatively, you can use filtering.
By default, IBM MQ Explorer displays only the first 500 client connections. For more information about
how to configure the maximum number of connections displayed at any given time, see “Advanced
option” on page 238.
Note: To purge a telemetry channel status object, right-click the selected object and click Purge.
Related tasks
“Filtering Telemetry objects” on page 252

Introduction to IBM MQ Explorer 251

 If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

Filtering Telemetry objects

If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

Before you begin

• Install the MQ Telemetry feature.
• Configure your queue manager for the MQ Telemetry feature. For more information, see “Configuring
MQ Telemetry using IBM MQ Explorer” on page 243.

About this task

The Telemetry channel status view has a filtering option. Within Telemetry, filtering is best used when
viewing the client connections in the Telemetry Channel Status Content view. Multiple telemetry
channels might have multiple clients attached to each of them. All of these connections are displayed
in the Channel Status folder. For example, you might want to display MQTT clients with client IDs
like ibm_client. This returns clients with client IDs such as ibm_client1, ibm_client2, and
ibm_client3.
You can also filter telemetry channels using the same filtering steps. For this task, you are filtering in the
Telemetry Channel Status content view.

Procedure
To filter telemetry objects, perform the following steps:
1. Assuming that you have installed and set up your queue manager for Telemetry, click the Channel
Status folder.
2. In the Telemetry Channel status Content view, click the arrow next to the Filter name.
• To select a filtering option from a list of defined filters, click Select Filter. The default filter in the
Channel Status Content view is Standard for Telemetry Channel Status.
• To change the options for the current filter, click Edit current filter.
• To add, copy, or edit filters, click Manage filters.
a) To add a filter, in the Manage filters window, click Add.
b) Type a meaningful name in the Filter Name field. For example, type Clients belonging to my
IBM channel.
c) Set the condition to apply to the telemetry channels. For example, Channel name like
IBM.CHANNEL.
d) To add another rule, select AND.
e) Click Select to change the attribute to filter on.
f) Type an appropriate rule, then click OK.
3. Select the filter name that you want to apply to that content view and click OK.

Results
The filter is applied and your objects are filtered based on the criteria set in the filtering option.

252 IBM MQ Explorer

Troubleshooting MQ Telemetry using IBM MQ Explorer
Help is provided for some of the problems that might occur when you use IBM MQ Explorer to administer
telemetry.

About this task

When you install the Telemetry feature, you might want to run the Define sample configuration wizard to
set up a basic configuration of telemetry. See “Defining a sample configuration” on page 245.
You can verify and test your basic setup by using the MQTT client utility to publish, and subscribe to,
messages. For more information about testing your sample configuration, see “Using the MQTT client
utility” on page 242.
Related tasks
“Resolving problems if your MQTT client fails to connect” on page 254
If your MQTT client cannot connect to a telemetry channel, there might be a number of reasons.
“Resolving problems if your MQTT client disconnects unexpectedly” on page 255
Discover what is going wrong when an MQTT client is unexpectedly disconnected from a telemetry
channel.
“Telemetry node does not appear” on page 255
Find out what to look for if the Telemetry node does not appear.
“Resolving problems with a telemetry channel” on page 255
If a telemetry channel fails to start, stops unexpectedly, or drops client connections, there are a few
things to consider to diagnose the problem.
Related reference
“Implications of running the sample configuration” on page 253
When you run the Define sample configuration wizard, IBM MQ objects are defined. Some of these
objects alter the behavior of the queue manager, and you should be aware of how these objects affect the
queue manager and its communication links.

Implications of running the sample configuration

When you run the Define sample configuration wizard, IBM MQ objects are defined. Some of these
objects alter the behavior of the queue manager, and you should be aware of how these objects affect the
queue manager and its communication links.
Running the Define sample configuration wizard sets the default transmit queue of the queue manager
to SYSTEM.MQTT.TRANSMIT.QUEUE, which takes precedence over an existing default transmit queue, if
one existed on that queue manager.
Defining the default transmit queue to be the MQTT transmit queue, enables IBM MQ applications to send
point-to-point messages to MQTT clients without the need to create a separate queue manager alias for
every client. Messages destined for MQTT clients are routed through the MQTT transmit queue on the
queue manager, to the MQTT client with a client identifier that matches the queue manager name that the
message is sent to. IBM MQ queue managers perceive MQTT clients as though they were remote queue
managers.
If you had previously used an IBM MQ default transmit queue to route messages to other queue
managers, you must explicitly create alternative routes (for example, by defining queue manager aliases)
before running the sample configuration or manually configuring your queue manager to enable the
Telemetry feature.
Running the sample configuration causes MQTT clients to access IBM MQ resources with user name
Guest on Windows, and nobody on Linux.

Introduction to IBM MQ Explorer 253

 Resolving problems if your MQTT client fails to connect
If your MQTT client cannot connect to a telemetry channel, there might be a number of reasons.

Procedure
Consider the following reasons to diagnose the problem with an MQTT client failing to connect:
• Check that the queue manager and telemetry (MQXR) service are running.
Start the queue manager. By default, the MQXR service should start with the queue manager. If you
configured the MQXR service control to start manually, you might have to start the service from the
Services folder. For more information about starting the MQXR service, see “Starting and stopping the
MQXR service” on page 250.
• Check that the telemetry channel and telemetry (MQXR) service are defined and running correctly.
You can manually define the MQXR service and set the default transmit queue of the queue manager to
SYSTEM.MQTT.TRANSMIT.QUEUE, which takes precedence over an existing default transmit queue.
This makes the queue manager suitable for Telemetry. Alternatively, you might want to consider
running the Define sample configuration wizard from the Telemetry welcome page, if you have not
done so already.
• Have you written your own client?
If so, did you write your client application with the MQTT v3 protocol and not the v5 protocol? Try to
isolate the problem by running the MQTT client utility.
• Do you have a valid client identifier name?
When connecting to IBM MQ, the MQTT client identifier should be less than 23 characters, and contain
only alphabetic characters, numeric characters, and the period (.), forward slash (/), underscore (_),
and percent sign (%).
• Did you connect your MQTT client and exhaust the MQTT keep alive interval?
The keep alive attribute is the interval in milliseconds after which, the MQTT client is disconnected due
to inactivity. If the MQXR service does not receive any communication from the client within the keep
alive interval, it disconnects from the client.
• Is a large number of MQTT clients trying to connect to a telemetry channel at the same time?
Every telemetry channel has a backlog attribute. This is the number of concurrent connection
requests that the telemetry channel supports. Ensure that the value is not set to a number that is
less than the number of MQTT clients trying to connect.
• Check that the TCP/IP connection is still active.
Related tasks
“Defining a sample configuration” on page 245
You can use the Define sample configuration wizard to reconfigure your queue manager, making it
suitable for the MQ Telemetry feature. The sample configuration defines and starts the MQXR service,
defines the transmit queue, and creates a sample telemetry channel.
“Defining the MQXR service” on page 246
The MQXR service is defined when you run the Define sample configuration wizard. You can also define
the MQXR service manually.
Related reference
“Telemetry channel properties” on page 256
Each telemetry channel attribute has a brief description which you must understand before you can
configure the channel. MQ Telemetry only supports the TCP/IP protocol.
“Telemetry channel status attributes” on page 258

254 IBM MQ Explorer

As with IBM MQ, you can view the status of a telemetry channel. For each attribute, there is a brief
description of what information the attribute is used for. All of the telemetry channel status attributes are
read-only.

Resolving problems if your MQTT client disconnects unexpectedly

Discover what is going wrong when an MQTT client is unexpectedly disconnected from a telemetry
channel.

Procedure
If your MQTT client connects successfully and later disconnects with no apparent reason, consider the
following reasons to diagnose the problem:
• The queue manager, MQXR service, or telemetry channel is not running.
Start the queue manager, MQXR service, or telemetry channel. Try reconnecting the MQTT client, and
check that this solution rectifies the problem.
• Another client is started and connects with the same client ID.
In this case, IBM MQ accepts the connection from the second MQTT client and forcefully disconnects
the first MQTT client.
• The MQTT client accesses a topic that it is not authorized to, either for publishing or subscribing.
IBM MQ disconnects the MQTT client.
• The TCP/IP connection is no longer active.
Diagnose and fix the problem with your TCP/IP connection, and try reconnecting the MQTT client.

Telemetry node does not appear

Find out what to look for if the Telemetry node does not appear.

Procedure
• Have you installed MQ Telemetry?
Check that you have all the prerequisites, and that you have installed Telemetry. See Installation under
Telemetry in the IBM MQ product documentation.

Resolving problems with a telemetry channel

If a telemetry channel fails to start, stops unexpectedly, or drops client connections, there are a few
things to consider to diagnose the problem.

Procedure
• Your telemetry channel fails to start.
Refresh the Telemetry Channels Content view, and ensure that the channel is not currently running.
Check that the port number of the telemetry channel is not in use by another application.
• A telemetry channel stops unexpectedly.
Ensure that the telemetry (MQXR) service is still running.
• The telemetry channel drops MQTT client connections.
For more information about MQTT clients being dropped unexpectedly, see “Resolving problems if
your MQTT client disconnects unexpectedly” on page 255.
• You cannot view the status of a telemetry channel.
Check that the telemetry channel in question is running.

Introduction to IBM MQ Explorer 255

 Ensure that the MQTT clients are connected to the correct telemetry channel. Check the port number
and host name on the client matches that of the telemetry channel.
If you have set up your own filter in the telemetry Channel Status Window, revert to the default of
Standard for Telemetry Channel Status and check that the required MQTT clients are displayed.
• You cannot run the MQTT client utility from a telemetry channel.
If you choose to perform authentication using TLS or JAAS, you cannot launch the MQTT client utility
from that telemetry channel. This is because the MQTT client utility does not support TLS or JAAS
authentication. However, you can write your own MQTT v3 client application to support JAAS or TLS
authentication.
• The Telemetry Channels folder does not display any channels, or the channel you created.
Check that you have successfully created a telemetry channel using either the Define sample
configuration wizard (which creates the PlainText channel), or the New Telemetry Channel wizard
(which creates a channel according to your specifications).
Check that the filtering option is set to the telemetry channel default of Standard for Telemetry
Channels.
Related tasks
“Filtering Telemetry objects” on page 252
If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

MQ Telemetry reference
Use the reference information in this section to accomplish tasks associated with the use of Telemetry in .
Related reference
“Telemetry channel properties” on page 256
Each telemetry channel attribute has a brief description which you must understand before you can
configure the channel. MQ Telemetry only supports the TCP/IP protocol.
“Telemetry channel status attributes” on page 258
As with IBM MQ, you can view the status of a telemetry channel. For each attribute, there is a brief
description of what information the attribute is used for. All of the telemetry channel status attributes are
read-only.

Telemetry channel properties

Each telemetry channel attribute has a brief description which you must understand before you can
configure the channel. MQ Telemetry only supports the TCP/IP protocol.
Right-click any telemetry object, then click Properties to view and edit the telemetry channel's
properties.
The following table lists the attributes that you can set on the Telemetry channel properties dialog (Note
1).

Attribute Meaning
Channel name Read-only. This is the name of the telemetry channel definition.
Channel type Read-only. This is the type of channel, in this case, MQTT.
Overall channel status Read-only. This is the current status of the telemetry channel.
Xmit protocol Read-only. The transmission protocol of the channel. Only TCP/IP is
supported.

256 IBM MQ Explorer

Attribute Meaning
Port This is the port number that the MQXR service accepts client connections on.
The default port number for a telemetry channel is 1883; and the default port
number for a telemetry channel secured using TLS is 8883.

Local address (optional) Type the IP address that the telemetry channel listens on. Use this option
when a server has multiple IP addresses.
Backlog (optional) The number of outstanding connection requests that the telemetry channel
can support at any one time. When the backlog limit is reached, any further
clients trying to connect will be refused connection until the current backlog is
processed.
The value is in the range 0 - 999999999. The default value is 4096.

MCA user ID (optional) The user ID for the message channel agent. It is the user identifier (up to
12 characters) to be used by the MCA for authorization to access IBM MQ
See Note 2
resources. If this property is specified, the user name supplied by the client is
not used for IBM MQ authorization.
Use client ID (optional) Decide whether you want to use the MQTT client ID for the new connection as
the IBM MQ user ID for that connection. If this property is specified, the user
See Note 2
name supplied by the client is ignored.
SSL CipherSuite (optional) If you choose to use this property, the CipherSuite must be available at
the client end of the telemetry channel. Leaving this option blank makes
both ends of the telemetry channel negotiate a CipherSuite that they both
understand.
SSL Authentication (optional) Determines whether the client is treated anonymously. SSL authentication
defines whether the telemetry channel must receive and authenticate a TLS
certificate from a client.
SSL Key repository (optional) The store for digital certificates and their associated private keys. If you do
not specify a key file, TLS is not used.
SSL Passphrase (optional) The password for the key repository. If no passphrase is entered, then
unencrypted connections must be used.
JAAS config file (read-only) The file path of the JAAS configuration.
JAAS config name (optional) The name of the configuration in the jaas.config file that you want to
implement.

Note:
1. When you edit the attributes of a telemetry channel, you must restart the channel for the changes to
apply.
2. Do not specify both MCA user ID and Use client ID properties. If you specify both, the telemetry
channel will fail when it tries to start.
If neither the MCA user ID and Use client ID properties are set, the user name and password
from the client are used and the user name is authenticated by JAAS using the password.
Related tasks
“Configuring MQ Telemetry using IBM MQ Explorer” on page 243
Configure IBM MQ to run the Telemetry feature, using IBM MQ Explorer. Create telemetry objects, and
test your telemetry setup using the MQTT client utility.
“Administering MQ Telemetry using IBM MQ Explorer” on page 249

Introduction to IBM MQ Explorer 257

 MQ Telemetry can be administered by using IBM MQ Explorer. You can control the MQXR service, and
monitor the MQTT clients that are connected to IBM MQ.

Telemetry channel status attributes

As with IBM MQ, you can view the status of a telemetry channel. For each attribute, there is a brief
description of what information the attribute is used for. All of the telemetry channel status attributes are
read-only.
The following table provides the descriptions of telemetry channels status attributes:

Attribute Meaning
Channel name The name of the telemetry channel definition.
Client ID The identifier of the client.
Status The status of the client, which can be Running or Disconnected.
Indoubt in The number of indoubt inbound messages to the server. Indoubt inbound
messages are messages that have been received by the server but have
not completed the acknowledgments with the client.
Indoubt out The number of indoubt outbound messages from the server. Indoubt
outbound messages are messages that have been sent by the server but
have not had acknowledgments of receipt from the client.
Connection name The name of the remote connection. The connection name is always an
IP address, or it could be localhost (127.0.0.1).
MQTT keep alive The interval in milliseconds after which the client is disconnected
because of inactivity. If the MQXR service does not receive any
communication from the client within the keep alive interval, it
disconnects from the client. This interval is calculated based on the
MQTT keep alive time sent by the client when it connects.
MCA user ID The message channel agent user identification string. It is the user
identifier (1-12 characters) to be used by the MCA for authorization to
access IBM MQ resources. If this property is specified, the user name
supplied by the client is not used for IBM MQ authorization.
Messages sent The number of messages sent by the telemetry channel to the client
since the most recent client connection session.
Messages received The number of messages received by the telemetry channel from the
client since the most recent client connection session.
Last message time The time the last message was sent or received.
Channel start time The time the telemetry channel was started.
Pending out The number of outbound pending messages on the telemetry channel
waiting to be sent to the MQTT client.
Channel start date The date the telemetry channel was started.

Related tasks
“Viewing the status of a telemetry channel” on page 251
“Filtering Telemetry objects” on page 252

258 IBM MQ Explorer

 If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

IBM MQ Tutorials
These tutorials show how to perform basic tasks such as creating a queue manager, creating a queue,
creating a channel, putting a message onto a queue, and getting a message from a queue. The tutorials
are relevant only for Multiplatforms.
Each tutorial is divided into several subtasks. You can perform each task by using either of the following
interfaces:
• The IBM MQ Explorer graphical interface.
• The IBM MQ Script Commands (MQSC) command line interface.
For more information about MQSC commands, see Administering IBM MQ using MQSC commands.
The first tutorial shows you how to set up a simple local stand-alone installation that has no
communication links with any other installations of IBM MQ. Each of the subsequent tutorials then builds
upon IBM MQ objects that have been set up during previous tutorials. Therefore, it is recommended that
these tutorials are completed in order.
The tutorials are designed to get you started with IBM MQ, and do not cover the more complex messaging
scenarios.

Tutorial 1: Sending a message to a local queue

A tutorial to set up a queue manager, create a queue, put a test message onto the queue, and verify the
receipt of the message.

About this task

This tutorial shows you how to set up a queue manager QM_APPLE and a queue Q1 on a local stand-alone
installation that has no communication links with any other installations of IBM MQ. When the objects
have been defined, there are multiple tools that may be used to test the setup. The first task is to put
a test message. This task can be completing by using the IBM MQ Explorer, or the distributed platform
amqsput program. The second task is to verify that the message was added to the queue. This task can
be completed by using the IBM MQ Explorer, or the distributed platform amqsget program.
When you have completed Tutorial 1, you should have a basic understanding of how IBM MQ messaging
works in a simple messaging topology that has a queue manager with local queues.

Creating the queue manager

Before you begin

Before creating a queue manager, you must ensure that IBM MQ is correctly installed.

About this task

This topic shows how to create a queue manager called QM_APPLE.

Introduction to IBM MQ Explorer 259

 You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

Creating the queue manager using IBM MQ Explorer

Procedure
1. Start IBM MQ Explorer.
2. In the Navigator view, right-click the Queue Managers folder, then click New > Queue Manager.
The Create Queue Manager wizard opens.
3. In the Queue Manager name field, type
QM_APPLE.
4. Click Next twice.
5. Ensure that Automatic is selected from the Select type of queue manager startup option.
6. Click Next.
7. Ensure that the Create listener configured for TCP/IP check box is selected.
8. If the Finish button is not available, type another port number in the Listen on port number field.
If the current value is 1414, try using a different port number, for example: 1415 or 1416. If the
default port number of 1414 is not used at this stage, make a note of the port number used because
you will need it in later stages of this tutorial when QM_APPLE serves as a receiving queue manager.
9. Click Finish.

Results
An icon representing this queue manager is displayed in the Queue Managers folder in the Navigator
view of IBM MQ Explorer, and the queue manager automatically starts running after you create it, as
shown in the following screen capture:

Creating the queue manager using MQSC

About this task

Open a command prompt, and follow these steps:

Procedure
1. Create a queue manager called QM_APPLE by typing the command:

crtmqm QM_APPLE

Messages tell you that the queue has been created and that the default IBM MQ objects have been
created.
2. Start this queue manager by typing the command:

260 IBM MQ Explorer

 strmqm

A message tells you when the queue manager has started.

Results
You have now created a queue manager with the name QM_APPLE.

Creating the local queue

Before you begin

Before creating a local queue on the queue manager, you must already have completed the task: Creating
the queue manager.

About this task

This topic shows how to create a local queue called Q1 on the queue manager called QM_APPLE.
You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

Creating the local queue using IBM MQ Explorer

Procedure
1. In the Navigator view, expand the Queue Managers folder.
2. Expand queue manager QM_APPLE.
3. Right-click the Queues folder, then click New > Local Queue.
The New Local Queue wizard opens.
4. In the Name field, type Q1
5. Click Finish.

Results
The new queue Q1, is displayed in the Content view, as displayed in the following screen capture:

If the queue is not displayed in the Content view, click Refresh in the Content view.

Introduction to IBM MQ Explorer 261

 Creating the local queue using MQSC

About this task

Open a command prompt and follow these steps:

Procedure
1. Enable MQSC commands by typing the command:

runmqsc QM_APPLE

2. Type the following command:

define qlocal (Q1)

Messages tell you that the queue has been created and that the default IBM MQ objects have been
created.
3. Stop MQSC by typing the command:

end

Results
You have now created a local queue called Q1.

Putting a test message on the local queue

Before you begin

Before putting a test message on the queue, you must already have completed the following tasks in this
tutorial:
• Creating the local queue manager
• Creating the local queue

About this task

This topic shows how to put a test message on the local queue Q1.
You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

Putting a test message on the queue using IBM MQ Explorer

Procedure
1. In the Navigator view, expand the Queue Managers folder.
2. Expand queue manager QM_APPLE, which you created.
3. Click the Queues folder.
The queues of the queue manager are listed in the Content view.
4. In the Content view, right-click the local queue Q1, then click Put Test Message.
The Put test message dialog opens.
5. In the Message data field, type some text, for example this is a test message, then click Put
message.

262 IBM MQ Explorer

 The Message data field is cleared and the message is put on the queue.
6. Click Close.

Results
In the Content view, notice that the Q1 Current queue depth value is now 1, as shown in the
following screen capture:

If the Current queue depth column is not visible, you might need to scroll sideways in the Content
View.

Putting a test message on the queue using amqsput

About this task

The amqsput sample program is used to put a message on the queue that you created.
On Windows the sample programs are installed by default with IBM MQ Server or Client. On Linux, the
samples programs RPM need to be installed.
Open a command prompt and follow these steps:

Procedure
1. Start the amqsput sample program as follows:

• On Linux, change to the MQ_INSTALLATION_PATH/samp/bin directory, where

MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed. Type
the command:

./amqsput Q1 QM_APPLE

• On Windows, type the command:

amqsput Q1 QM_APPLE

The following messages are displayed:

Sample AMQSPUT0 start

target queue is Q1
2. Type some message text on one or more lines, then press Enter twice.
The following message is displayed:

Sample AMQSPUT0 end

Results
You have now created a test message and put it onto the local queue.

Introduction to IBM MQ Explorer 263

 In the IBM MQ Explorer Content view, notice that the Q1 Current queue depth value is now 1, as
shown in the following screen capture:

If the Current queue depth column is not visible, you might need to scroll sideways in the Content
View.

Verifying that the test message was sent

Before you begin

Before getting the test message from the local queue, you must already have completed the following
tasks in this tutorial:
• Creating the local queue manager
• Creating the local queue
• Putting a test message on the local queue

About this task

This topic shows how to verify that the test message was sent.
You can perform this task using either of the following interfaces:
1. Use the IBM MQ Explorer graphical interface
2. Use the IBM MQ Script Command (MQSC) command-line interface

Procedure
• [OPTION 1] Use the IBM MQ Explorer graphical interface to verify that the test message was sent.
a) In the Navigator view, expand the Queue Managers folder, then expand QM_APPLE.
b) Click the Queues folder.
c) In the Content view, right-click Q1, then click Browse Messages.
The Message browser opens to show the list of the messages that are currently on Q1.
d) Double-click the last message to open its properties dialog.
On the Data page of the properties dialog, the Message data field displays the content of the
message in human-readable form, as shown in the following screen capture:

264 IBM MQ Explorer

• [OPTION 2] Use the IBM MQ Script Command (MQSC) command-line interface to verify that the test
message was sent.
The amqsget sample program is used to get the message back from the queue.
a) Open a command prompt.
b) Start the amqsget sample program:

– On Windows, type the following command:

amqsget Q1 QM_APPLE

– On Linux, change to the MQ_INSTALLATION_PATH/samp/bin directory, where

MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed. Type
the following command:

./amqsget Q1 QM_APPLE

Introduction to IBM MQ Explorer 265

 The sample program starts, and your message is displayed along with any other messages on this
queue. After a pause of 15 seconds, the sample ends and the command prompt is displayed again.
You have now completed this tutorial.

Tutorial 2: Sending a message to a remote queue

A tutorial showing how to send messages to a remote queue manager.

Before you begin

This tutorial builds upon IBM MQ objects set up in “Tutorial 1: Sending a message to a local queue” on
page 259. You must complete Tutorial 1 to proceed with this tutorial.

About this task

This tutorial shows you how to set up messaging between a queue manager that is called QM_ORANGE
and a queue manager called QM_APPLE. You can complete this tutorial, and verify your environment, by
setting up the sending queue manager on the same computer as the target queue manager. A message
that is created on the sending queue manager is delivered to a queue called Q1 on the receiving queue
manager (this queue is referred to as a remote queue).
Important: During this tutorial, you must use the computer on which you created queue manager
QM_APPLE and local queue Q1.
You must set up a queue manager and queues (a remote queue definition and a transmission queue) on
your computer, and then define a message channel. Finally, put a test message onto the sending queue
manager, and get it from the queue on the receiving queue manager.
When you have completed this tutorial, you should have a basic understanding of how to set up and use
IBM MQ messaging using a remote queue definition.

Creating the queue manager on the sending machine

Before you begin

Before creating a queue manager on the sending machine, you must ensure that IBM MQ Server is
correctly installed. The queue manager on the sending machine cannot be created remotely. It must be
created locally on the sending machine.

About this task

In this part of the tutorial, you will create a queue manager QM_ORANGE on the sending machine.
You can perform this task using either of the following interfaces:
• The MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

266 IBM MQ Explorer

Creating the queue manager using IBM MQ Explorer on the sending machine

About this task

This process cannot be done remotely. It must be done locally on the sending machine:

Procedure
1. Start IBM MQ Explorer.
2. In the Navigator view, right-click the Queue Managers folder, then click New > Queue Manager
The Create Queue Manager wizard opens.
3. In the Queue Manager name field, type QM_ORANGE.
4. Click Next twice to go to the Enter configuration options section of the wizard.
5. Select Create server-connection channel.
6. Ensure that Automatic is selected from the Select type of queue manager startup option.
7. Click Next to go to the Enter listener options section of the wizard.
8. Ensure that the Create listener configured for TCP/IP check box is selected.
9. If the Finish button is not available, type another port number in the Listen on port number field.
If the current value is 1414, try typing 1415 or 1416
10. Click Finish.

Results
An icon representing this queue manager is displayed in the Queue Managers folder in the Navigator
view of IBM MQ Explorer, and the queue manager automatically starts running after you create it.

Creating the sending queue manager using MQSC

About this task

Open a command prompt on the sending machine and follow these steps:

Procedure
1. Create a default queue manager called QM_ORANGE by typing the command:

crtmqm QM_ORANGE

Messages tell you that the queue has been created and that the default IBM MQ objects have been
created.
2. Start this queue manager by typing the command:

strmqm QM_ORANGE

A message tells you when the queue manager has started.

Results
You have now created the sending queue manager.

Creating the queues on the sending queue manager

Before you begin

Before creating the queues on the sending queue manager, you must already have created the queue
manager in the task:

Introduction to IBM MQ Explorer 267

 • Creating the queue manager.

About this task

In this part of the tutorial, you will create a remote queue definition and a transmission queue on the
sending queue manager.
You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

Creating the queues on the sending queue manager using IBM MQ Explorer

About this task

On the sending queue manager:

Procedure
1. In the Navigator view, expand the Queue Managers folder.
2. Expand queue manager QM_ORANGE.
3. Right-click the Queues folder, then click New > Remote Queue Definition.
The New Remote Queue Definition wizard opens.
4. In the Name field, type Q1
5. Click Next.
6. In the Remote queue field, type Q1
7. In the Remote queue manager field, type QM_APPLE
8. In the Transmission queue field, type QM_APPLE
9. Click Finish.
You have now created the remote queue definition.
10. Click the QM_ORANGE queue manager.
11. Right-click the Queues folder, then click New > Local Queue
The New Local Queue wizard opens.
12. In the Name field, type QM_APPLE
13. Click Next.
14. In the Usage field, select Transmission.
15. Click Finish.
You have now created the transmission queue on the local machine.

Results
The new queues, Q1 and QM_APPLE, are displayed in the Content view.

If the queues are not displayed in the Content view, click Refresh in the Content view.

Creating the queues on the sending queue manager using MQSC

About this task

Open a command prompt on the sending machine and follow these steps:

Procedure
1. Start MQSC by typing the command:

268 IBM MQ Explorer

 runmqsc

A message tells you that an MQSC session has started.

2. Define a local queue called QM_APPLE by typing the following command:

define qlocal (QM_APPLE) usage (xmitq)

A message tells you when the queue has been created.

3. Define a remote queue definition by typing the following command:

define qremote (Q1) rname (Q1) rqmname(QM_APPLE) xmitq (QM_APPLE)

Results
You have now created the queues on the sending queue manager. The next task is to create the message
channel between the sending and receiving queue managers.

Creating a message channel

Before you begin

Before creating a message channel, you must already have completed the following tasks in this tutorial:
• Creating the queue manager
• Creating the queues

About this task

In this part of the tutorial, you will create a message channel between the sending and receiving queue
managers.
You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

Creating the message channel using IBM MQ Explorer

Procedure
1. On the receiving queue manager QM_APPLE, create the receiver end of the channel:
a) In the Navigator view, expand the queue manager QM_APPLE that you created earlier.
b) Right-click the Channels folder, then click New > Receiver Channel.
The New Receiver Channel wizard opens.
c) In the Name field, type QM_ORANGE.QM_APPLE
d) Click Finish.
You have now created the receiver channel on the receiving machine.
2. On the sending queue manager QM_ORANGE, create the sender end of the channel:
a) Expand the queue manager QM_ORANGE that you created earlier.
b) Right-click the Channels folder, then click New > Sender Channel.
The New Sender Channel wizard opens.
c) In the Name field, type QM_ORANGE.QM_APPLE, then click Next.
d) In the Connection name field, type the computer name or IP address of the receiving machine (you
should already have obtained this with your system administrator's help).

Introduction to IBM MQ Explorer 269

 If the default port number 1414 was not used when creating QM_APPLE, the Connection name
field entry should be of the format:

con-name(port)

Where con-name is the computer name or IP address of the receiving machine, and port is the
port number used when the receiving queue manager was set up.
e) In the Transmission queue field, type QM_APPLE
The transmission queue name you enter here must match the name you entered for the
transmission queue in Creating the queues on the sending queue manager.
f) Click Finish.
g) Click the Channels folder.
h) Right-click QM_ORANGE.QM_APPLE.
i) From the pop-up menu, click Start.
j) Click OK.
You have now created the sender channel on the sending machine.
Note: You do not have to start the receiver channel because it started automatically when you set
up the sender channel (when you set up the sender channel, you specified the receiver channel's IP
address).

Results
You have now created a receiver channel QM_ORANGE.QM_APPLE, on the receiving queue
manager QM_APPLE, and a sender channel QM_ORANGE.QM_APPLE, on the sending queue manager
QM_ORANGE. You have also started the sender channel, which automatically started the receiver
channel.

Creating the message channel using MQSC

Procedure
1. Open a command prompt on the receiving machine and follow these steps:
a) Start MQSC by typing the command:

runmqsc

A message tells you that an MQSC session has started.

b) Define a receiving channel by typing the following command:

define channel (QM_ORANGE.QM_APPLE) chltype (RCVR) trptype (TCP)

A message tells you when the channel has been created.

c) Open a new command window and check which ports are free. Enter the following command:

netstat -an

This shows you a list of running processes. Check the port number of each of the processes to see
if port 1414 is in use; you can find this by looking in the Local Address column. The information is
given in the form ip_address:port_being _used.
If port 1414 is not in use, use 1414 as the port number for your listener and sender channel later in
the verification. If it is in use, select an alternative port that is not in use; for example 1415 if this is
not being used by another process.

270 IBM MQ Explorer

 d) Verification requires you to start the default IBM MQ listener. By default, the listener will listen
on port 1414. If you found that port 1414 was free in step c, no action is required and you
can proceed to step e. If you must use a port other than 1414, alter the definition of the
SYSTEM.DEFAULT.LISTENER.TCP. For example, to use port 1415, enter the following command in
the MQSC window:

alter listener(system.default.listener.tcp) trptype(tcp) port(port_number)

Where port_number is the number of the port the listener should run on. This must be the same
as the number used when defining your sender channel in step 2b of this procedure.
e) In the MQSC window, start the default IBM MQ listener by entering the following command:

start listener(system.default.listener.tcp)

f) Stop MQSC by typing:

end

Some messages are displayed followed by the command prompt.

2. Open a command prompt on the sending machine and follow these steps:
a) Start MQSC by typing the command:

runmqsc

A message tells you that an MQSC session has started.

b) Define a sender channel by typing the following command:

define channel(QM_ORANGE.QM_APPLE) chltype(sdr) conname('con-name(port)') xmitq(QM_APPLE)

trptype(tcp)

The value con-name is the TCP/IP address of the receiver workstation. The value port is the port
on which the listener is running on the receiver machine, the default value is 1414.
c) Start the channel by typing the following command:

start channel (QM_ORANGE.QM_APPLE)

d) Stop MQSC by typing:

end

Some messages are displayed followed by the command prompt.

Results
You have now created all the IBM MQ objects required for messages to be sent from the sending queue
manager QM_ORANGE to the queue Q1 on the receiving queue manager QM_APPLE. The next task is to
send a test message.

Putting a test message on the queue

Put a test message on a remote queue using only the MQSC command-line interface.

Before you begin

Before putting a test message on the queue, you must already have completed the following tasks in this
tutorial:
• Creating the queue manager

Introduction to IBM MQ Explorer 271

 • Creating the queues
• Creating a message channel

About this task

Perform this task on the sending machine (the machine that hosts the queue manager QM_ORANGE).
The amqsput sample program is used to put a message onto the queue that you created:

• On Windows, the sample programs are installed by default with IBM MQ Server or Client.

• On Linux, the samples programs RPM need to be installed.

Procedure
1. Open a command prompt.
2. Start the amqsput sample program as follows:

• On Windows, type the command:

amqsput Q1 QM_ORANGE

• On Linux, change to the /opt/mqm/samp/bin directory and type the command:

./amqsput Q1 QM_ORANGE

The following messages are displayed:

Sample amqsput0 start

target queue is Q1
3. Type some message text on one or more lines, then press Enter twice.
The following message is displayed:

Sample amqsput0 end

Results
You have now created a test message and put it onto the remote queue. The next task is to verify that the
test message was received.

Verifying that the test message was sent

Before you begin

Before getting the test message from the queue, you must already have completed the other tasks in this
tutorial:
• Creating the queue manager
• Creating the queues
• Creating a message channel
• Putting a test message on the queue

About this task

This topic shows how to verify that the test message was sent.
You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface

272 IBM MQ Explorer

• IBM MQ Script Command (MQSC) command-line interface

Verifying that the test message was sent using IBM MQ Explorer

About this task

Perform this task on the receiving machine (the machine that hosts the queue manager QM_APPLE).
On the receiving queue manager:

Procedure
1. In the Navigator view, expand queue manager QM_APPLE.
2. Click the Queues folder.
3. In the Content view, right-click the queue Q1, then click Browse Messages.
The Message browser opens to show the list of the messages that are currently on Q1.
4. Double-click the last message in the list to view its properties dialog.

Results
On the Data page of the properties dialog, the Message data field displays the content of the message
in human-readable form.

Verifying that the test message was sent using MQSC

About this task

You perform this task on the receiving machine (the machine that hosts the queue manager QM_APPLE).
The amqsget sample program is used to get the message back from the queue.
Open a command prompt and follow these steps:

Procedure
Start the amqsget sample program as follows:

• On Linux, change to the MQ_INSTALLATION_PATH/samp/bin directory, where

MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed. Type the
command:

./amqsget Q1 QM_APPLE

• On Windows, type the command:

amqsget Q1 QM_APPLE

Results
The sample program starts and your message is displayed along with any other messages on this queue.
After a short pause, the sample program ends and the command prompt is displayed again.
You have now completed this tutorial.

Introduction to IBM MQ Explorer 273

Tutorial 3: Sending a message on a client-server configuration
A tutorial to set up messaging between client and server machines, sending a message from the client,
and verifying its receipt.

Before you begin

This tutorial builds upon IBM MQ objects that have been set up during the previous tutorial - you need to
complete “Tutorial 2: Sending a message to a remote queue” on page 266 first.
Before starting this tutorial, you need to find out the name which identifies the server which hosts queue
manager QM_ORANGE on the network from your system administrator.
You are currently in the IBM MQ Explorer help. To grant the client the access rights to put messages on to
a queue, see Preparing and running the sample programs in the main product documentation.

About this task

This tutorial shows you how to set up messaging between client and server machines. From the client
machine, you put a message on queue manager QM_ORANGE, which is hosted on a server machine.
QM_ORANGE sends the message to Q1 on QM_APPLE, which is hosted on another server machine.
Important: This tutorial shows you how to work with a client-server installation, where the client is a
third machine with IBM MQ Client installed, and the server is the machine which has the queue manager
QM_ORANGE defined on it.
You set up the server by creating a server-connection channel. You then set up the client by defining the
MQSERVER environment variable. Finally, you put a test message from the Client onto QM_ORANGE which
sends it to queue Q1 on QM_APPLE and you verify that the message was sent.
When you have completed this tutorial, you should have a basic understanding of how to set up
messaging on an IBM MQ MQI client-server configuration.

Setting up the server

About this task

In this part of the tutorial, you will set up the queue manager QM_ORANGE on the server machine to
enable client connections to it. This will involve configuring a server-connection channel.
This task can be achieved by using either:
• “Setting up the server using IBM MQ Explorer” on page 274
• “Setting up the server using MQSC” on page 275

Setting up the server using IBM MQ Explorer

About this task

On the server machine that hosts queue manager QM_ORANGE:

274 IBM MQ Explorer

Procedure
1. In the Navigator view, expand the Queue Managers folder.
2. Expand QM_ORANGE.
3. Right-click the Channels folder, then click New > Server-connection Channel.
The New Server-connection Channel wizard opens.
4. In the Name field, type CLIENT.QM_ORANGE then click Next.
5. Click MCA to open the MCA page.
6. In the MCA User ID field, type your Windows login name (or a user name in the mqm group).
7. Click Finish.

Results
The new server-connection channel is displayed in the Content view.

What to do next
For more information about the MCAUSER ID, see Access control for clients.

Setting up the server using MQSC

About this task

Open a command prompt on the receiving machine and follow these steps:

Procedure
1. Start MQSC by typing the command:

runmqsc QM_ORANGE

A message tells you that an MQSC session has started. MQSC has no command prompt.
2. Define a server-connection channel by typing the following command on one line:

define channel(CLIENT.QM_ORANGE) chltype(SVRCONN) trptype(TCP) mcauser('mqm')

If you are using Windows, type your Windows login name (or a valid mqm user name) in
place of mqm.
A message tells you when the channel has been created.
3. Stop MQSC by typing:

end

Some messages are displayed followed by the command prompt.

4. Start a listener by typing the following command:

runmqlsr -t tcp

Results
You have now finished setting up the server. The next task is to set up the client.

Introduction to IBM MQ Explorer 275

 Setting up the client on Windows and Linux

Before you begin

Before setting up the client to communicate with queue manager QM_ORANGE, you must ensure that the
IBM MQ MQI client has been installed on the client machine.

About this task

In this part of the tutorial, you must set up the client component on the server using the MQSERVER
environment variable. You must find out the network name of the machine which hosts queue manager
QM_ORANGE from your system administrator.
To set up the client on Windows or Linux, complete the steps for the platform that you are using:

• “Setting up the client on Windows” on page 276

• “Setting up the client on Linux” on page 276

Setting up the client on Windows

About this task

In this task, you will set up the client component using the MQSERVER environment variable. You will
need to find out the network name of the machine which hosts queue manager QM_ORANGE from your
system administrator.

Procedure
1. Open the Control Panel: Click Start > Settings > Control Panel
2. Double-click System.
3. Click the Advanced tab.
4. Click Environment Variables.
5. In the User Variables pane, click New.
6. Type MQSERVER into the Variable Name field.
7. Type CLIENT.QM_ORANGE/TCP/hostname into the Variable Value field, where hostname is the
computer name or IP address that identifies the machine hosting queue manager QM_ORANGE. If
you do not use the default port number 1414, you must also specify the port number where the
listener is listening. For example: MQSERVER=CLIENT.QM_ORANGE/TCP/hostname (1415)
8. Click OK.
The MQSERVER environment variable is visible in the User Variables pane.

Results
You have now set up the client and server components needed on your Windows machine.

Setting up the client on Linux

About this task

In this task, you will set up the client component using the MQSERVER environment variable. You will
need to find out the network name of the machine which hosts queue manager QM_ORANGE from your
system administrator.

Procedure
1. Log in as the user who will be running Express File Transfer, who must be a member of the mqm group.

276 IBM MQ Explorer

2. Open a command prompt
3. Type

cd $HOME

4. Use a text editor to edit the profile. This example assumes that you are using the bash shell, so you
need to edit the file $HOME/.bashrc. If you are using a different system shell, consult your system
documentation. Add the following text to the end of the file:

MQSERVER=CLIENT.QM_ORANGE/TCP/'hostname'; export MQSERVER

Replace hostname with the name that identifies the server machine on the network.
5. Close the command prompt.
6. Log out and log back in for the change to take effect.

Results
You have now set up the client and server components needed. The next task is to send a message from
the client to the server queue manager QM_ORANGE.

Sending a message from a client to a server

Before you begin

Before putting a test message on the queue, you must already have completed the following tasks in this
tutorial:
• “Setting up the server” on page 274
• “Setting up the client on Windows and Linux” on page 276.

About this task

In this part of the tutorial, you will send a message from the client to the server queue manager
QM_ORANGE, which uses the remote queue definition and other IBM MQ objects defined in earlier
tutorials to route the message onto queue manager QM_APPLE and to queue Q1.

On Windows, the sample programs are installed by default with IBM MQ Server or Client.

On Linux, the sample programs RPM will need to be installed.

Open a command prompt on the client and follow these steps:

Procedure
1. Start the amqsputc sample program as follows:

• On Linux, change to the MQ_INSTALLATION_PATH/samp/bin directory, where

MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed. Type
the command:

./amqsputc Q1

• On Windows, type the command:

amqsputc Q1

The following messages are displayed:

Introduction to IBM MQ Explorer 277

 Sample AMQSPUT0 start
target queue is Q1
2. Type some message text on one or more lines, then press Enter twice.
The following message is displayed:

Sample AMQSPUT0 end

Results
You have now created a test message and sent it to the server queue manager QM_ORANGE, which routes
it onto queue Q1 on queue manager QM_APPLE. The next task is to verify that the test message was
received.

Verifying that the test message was sent

Before you begin

Before getting the test message from the queue, you must already have completed the following tasks in
this tutorial:
• “Setting up the server” on page 274
• “Setting up the client on Windows and Linux” on page 276
• “Sending a message from a client to a server” on page 277.

About this task

This topic shows how to verify that the test message was sent.
You can perform this task using either of the following interfaces:
• The IBM MQ Explorer graphical interface
• IBM MQ Script Command (MQSC) command-line interface

Verifying that the test message was sent using IBM MQ Explorer

About this task

On the machine that hosts the queue manager QM_APPLE:

Procedure
1. In the Navigator view, expand QM_APPLE.
2. Click the Queues folder.
3. In the Content view, right-click Q1, then click Browse Messages.
The Message browser opens to show the list of messages on Q1.
4. Double-click the last message in the list to open its properties dialog.

Results
On the Data page of the properties dialog, the Message data field displays the content of the message
in human-readable form.

Verifying that the test message was sent using MQSC

About this task

The amqsget sample program is used to get the message back from the queue.
Open a command prompt and start the amqsget sample program as follows:

278 IBM MQ Explorer

 Procedure
Start the amqsget sample program as follows:

• On Linux, change to the MQ_INSTALLATION_PATH/samp/bin directory, where

MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed. Type the
following command:

./amqsget Q1

• On Windows, type the following command:

amqsget Q1

Results
The sample program starts, and your message is displayed along with any other messages on this queue.
After a pause of 15 seconds, the sample ends and the command prompt is displayed again.
You have now completed this tutorial.

Reference
This section of the Help deals with reference material such as Accessibility, Properties, and Icons for IBM
MQ Explorer.
The following topics list the reference material for IBM MQ Explorer.
• Accessibility in IBM MQ Explorer
• Icons in IBM MQ Explorer
• Views in IBM MQ Explorer
• Properties
• Status attributes
• Byte array dialog
• Strings in property dialogs

Accessibility in IBM MQ Explorer

Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.
When you use the administrative facilities that are provided by IBM MQ Explorer, you can use your
operating system's accessibility features to modify the behavior of the user interface. You can change the
key behavior, provide a high-contrast display, or control the pointer with keys instead of a mouse. For
more information, see the documentation for your operating system.
The fully accessible way of using IBM MQ is to use the command-line interface. For more information, see
Accessibility features for IBM MQ.
IBM MQ Explorer has been designed with accessibility in mind. The following features have been
implemented.
• IBM MQ Explorer uses icons to indicate the status of objects, such as queue managers. Screen readers
cannot interpret these icons, so there is an option to show a textual description of the icon. To select
this option, from within the IBM MQ Explorer click Window > Preferences > MQ Explorer and select
Show status of objects after object name.

Introduction to IBM MQ Explorer 279

 • In IBM MQ Explorer, there are several places where color is used to highlight parts of the interface.
If you have difficulty interpreting the default colors, you can change them. For more information, see
“Changing the colors” on page 221.
• In the Manage Authority Records dialogs, and in other dialogs that display object authorities, the
tables use icons to show whether an authority is granted. Screen readers cannot interpret these icons.
If you prefer, you can set the tables to use text instead of icons. For more information, see “Displaying
object authority settings as text” on page 226.

Icons in IBM MQ Explorer

IBM MQ Explorer uses icons to represent the different objects, such as queue managers, queues, and
channels.
IBM MQ Explorer alters the icons slightly to indicate the status of the objects, for example, running or
stopped.
The tables on this page list the following types of icons:
• Status
• Queue managers
• Queues
• Channels
• Other IBM MQ objects
• Queue manager clusters
• Queue sharing groups
• API exits
• JMS objects

Status icons in IBM MQ Explorer

The following table lists the status icons that are superimposed on to IBM MQ object icons in IBM MQ
Explorer to indicate the status of the object. To investigate the cause of an object being in an Alert or
Warning state, look at the status of the current object.

Icon Meaning
Up. The object is running.

Down. The object is not running.

Alert. The status of the object is indeterminate; for

example, the object is in the process of stopping or
starting.
Warning. The object is having problems connecting.
On queue managers in the Full Repository and Partial
Repository folders, this icon means that the queue
manager is suspended from the cluster.

Queue managers
The following table lists the icons that are used in IBM MQ Explorer to represent queue managers.
The queue manager icon is yellow when IBM MQ Explorer is connected to a queue manager; when it is not
connected, the icon is gray. Local queue managers are marked with an Up or Down icon to show whether
the queue manager is running or stopped.

280 IBM MQ Explorer

 Remote queue managers are distinct because their icons do not indicate whether they are running or not;
they indicate only whether they are connected to IBM MQ Explorer. A remote queue manager must be
running for IBM MQ Explorer to connect to it; if IBM MQ Explorer is disconnected from a remote queue
manager, it is not possible for IBM MQ Explorer to detect whether the remote queue manager is running.

Queue manager local or

Icon remote to Explorer? Explorer connected? Queue manager status
Local Yes Running

Local No Running

Local No Running as standby

Local No Stopped

Remote Yes Running

Remote No Unknown

Queue manager instances

Display queue manager instance status by selecting a remote queue manager in the navigator and clicking
Connection details > Manage instances.

Icon Connection status text Explanation

Connected The IBM MQ Explorer is connected and the queue manager is
running.
Not connected The IBM MQ Explorer has not attempted to connect to the queue
manager instance. Click Test connections to update the status of
the connection.
Not connection The instance is running as a standby.

Not available One of three reasons:

• Unknown host name or IP address.
• The queue manager is not listening on the port address.
• The IBM MQ Explorer has timed out waiting for a response from
the queue manager instance.

Different name The queue manager instance listening on the IP address

configured for the connection has a different queue manager
name.
Different UUID The queue manager instance listening on this IP address has a
different UUID.
The problem might be because the listener is connected to
a different queue manager with the same name, rather than
another instance of the same queue manager.
It might also be because the remote queue manager has been
deleted and re-created with the same name. It is no longer the
same queue manager.

Queues
The following table lists the icons that are use in IBM MQ Explorer to represent queues.

Introduction to IBM MQ Explorer 281

Icon Meaning
Local

Local queue that is shared in a cluster

Model

Remote queue definition

Remote queue definition of a queue that is shared in a

cluster
Alias

Alias queue that is shared in a cluster

Transmission

Channels
The following table lists the icons that are used in IBM MQ Explorer to represent channels.

Icon Meaning
Sender

Server

Receiver

Requester

Server-connection

Client-connection

Cluster-sender

Cluster-receiver

Other IBM MQ objects

The following table lists the icons that are used in IBM MQ Explorer to represent other IBM MQ objects.
Custom services can be in either running, stopped, alert, or warning states.

Icon Meaning
Topic

Subscription

Listener

Authentication information object

Namelist

282 IBM MQ Explorer

Icon Meaning
Process definition

Message

Custom service

Application connection

Queue manager clusters

The following table lists the icons that are used in IBM MQ Explorer to represent clusters.

Icon Meaning
Cluster

Cluster without a source provider

Full repository

Full repository suspended from the cluster

Full repository disconnected

Partial repository

Partial repository suspended from the cluster

Partial repository disconnected

Cluster-receiver channel

Cluster-sender channel

Local queue that is shared in a cluster

Remote queue definition of a queue that is shared in a

cluster
The number indicates the number of cluster queues in
the cluster.

The number indicates the number of instances of

cluster-sender channels between the two queue
managers.

The number indicates the number of instances of

cluster-receiver channels on the queue manager.

Introduction to IBM MQ Explorer 283

 Queue sharing groups
The following table lists the icons that are used in IBM MQ Explorer to represent queue sharing groups.
The channels can be in either running, stopped, alert, or warning states.

Icon Meaning
Queue sharing group

QSG authentication information object

QSG local queue

QSG model queue

QSG namelist

QSG process definition

QSG alias queue

QSG receiver channel

QSG remote queue definition

QSG requester channel

QSG sender channel

QSG server channel

QSG server-connection channel

QSG transmission queue

API Exits
The following table lists the icons that are used in IBM MQ Explorer to represent API exits.

Icon Meaning
Common

Template

Local

JMS objects
The following table lists the icons that are used in IBM MQ Explorer to represent JMS objects in the JNDI
namespace.

Header Header
Initial context; connected

Initial context; disconnected

Connection factory for MQ connections

284 IBM MQ Explorer

Header Header
Connection factory for realtime connections

Destination object for a queue

Destination object for a topic

Subcontext; connected

Subcontext; disconnected

Corrupted JNDI object

Views in IBM MQ Explorer

IBM MQ Explorer is a perspective in Eclipse Platform, which is built on Eclipse technology.
The IBM MQ Explorer perspective is a collection of views. The IBM MQ Explorer perspective contains two
main views:
1. “IBM MQ Explorer Navigator view” on page 285
2. “IBM MQ Explorer Content view” on page 293
Depending on which other plug-ins you have installed and enabled, the IBM MQ Explorer perspective
might also contain other views. You can also show any other available views in the IBM MQ Explorer
perspective by clicking Window > Show Views > Other... and selecting a view.
Related tasks
“Configuring IBM MQ Explorer” on page 192
Use this information to help you to configure your IBM MQ Explorer installation.

IBM MQ Explorer Navigator view

The Navigator view in IBM MQ Explorer displays all of the IBM MQ objects that you can administer and
monitor in IBM MQ Explorer.
The types of objects that you can administer and monitor in the Navigator view include objects that are on
other computers and on other platforms, such as AIX, Linux, and z/OS.

Objects and folders in the Navigator view

The Navigator view contains a hierarchy of objects and folders that contain the queue managers and
their objects. The following table contains descriptions of the objects and folders that are shown in the
Navigator view.

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
IBM MQ The IBM MQ object is Right-click the IBM Configuring IBM MQ
the root of the folder MQ object to perform
hierarchy and represents tasks that affect the
the installation of IBM MQ whole of IBM MQ
on the computer. on the local computer,
such as configuring IBM
MQ properties, starting
trace, or managing TLS
certificates.

Introduction to IBM MQ Explorer 285

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
Queue Managers The Queue Managers Click the Queue Queue managers
folder contains all of Managers folder to list
the queue managers the queue managers, and
that are on the local their attributes, in the
computer unless you have Content view. Right-click
hidden them. You can the Queue Managers
also add remote queue folder to perform tasks
managers, including z/OS such as creating a new
queue managers. You can queue manager, or adding
administer and monitor a remote queue manager
any queue manager using to IBM MQ Explorer.
IBM MQ as long as it
is shown in the Queue
Managers folder.
A queue manager Each queue manager Click the queue manager Queue managers
that is shown in the to display an overview
Queue Managers folder is of the queue manager's
represented by a queue attributes in the Content
manager object icon in view. Right-click the
the hierarchy. The objects queue manager to
that belong to a queue perform tasks such as
manager are organized in starting and stopping
folders under that queue the queue manager, or
manager. configuring the queue
manager's properties.
Expand the queue
manager to display the
folders that contain the
queue manager's objects.
Queues The Queues folder Click the Queues folder to Queues
contains all of the queues list the queue manager's
that are defined on the queues in the Content
queue manager. view. Right-click the
Queues folder to perform
tasks such as creating a
new queue.
Channels The Channels folder Click the Channels Channels
contains all of the folder to list the queue
channels that are defined manager's channels in the
on the queue manager Content view. Right-click
except for the client- the Channels folder to
connection channels. perform tasks such as
creating new channels.

286 IBM MQ Explorer

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
Client Connections The Client Connections Click the Client Channels
folder contains all of Connections folder
the client-connection to list the
channels that are defined queue manager's client-
on the queue manager. connection channels
in the Content view.
Right-click the Client
Connections folder to
perform tasks such as
creating a new client-
connection channel.
The Listeners folder Click the Listeners Listeners
contains all of the listener folder to list the queue
Listeners objects that you have manager's listener objects
defined on the queue in the Content view. Right-
manager. If you start click the Listeners folder
a listener service from to perform tasks such as
the command line, that creating a new listener
listener is not shown in object.
the Listeners folder. The
Listeners folder is not
available on z/OS queue
managers.
The Services folder Click the Services Services
contains all of the custom folder to list the
Services services that you have queue manager's custom
defined on the queue services in the Content
manager. The Services view. Right-click the
folder is not available on Services folder to perform
z/OS queue managers. tasks such as creating a
new custom service.
Process Definitions The Process Definitions Click the Process Process definitions
folder contains all of Definitions folder to list
the process definitions the process definitions
that are defined on the in the Content view.
queue manager. A process Right-click the Process
definition contains the Definitions folder to
details of an application perform tasks such as
that starts in response to creating a new process
a trigger event on a queue definition.
manager.
Namelists The Namelists folder Click the Namelists folder Namelists
contains all of the to list the namelists in
namelists that are defined the Content view. Right-
on the queue manager. click the Namelists folder
A namelist is a list of to perform tasks such as
the names of other MQ creating a new namelist.
objects.

Introduction to IBM MQ Explorer 287

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
Authentication The Authentication Click the Authentication Authentication
Information Information folder Information folder to information
contains all of list the authentication
the authentication information objects in
information objects that the Content view. Right-
are defined on the queue click the Authentication
manager. There are two Information folder to
types of authentication perform tasks such
objects: as creating a new
authentication object.
• CRL LDAP
authentication
object contains
the authentication
information that is
used to connect to
LDAP servers that hold
Certificate Revocation
Lists (CRLs). The queue
manager connects to
the CRL LDAP servers
when transporting data
that is encrypted using
TLS.

• On AIX,
Linux, and Windows
systems, IBM MQ
TLS support can
check for revoked
certificates using OCSP
(Online Certificate
Status Protocol). OCSP
is the preferred method.
IBM MQ classes for Java
and IBM MQ classes
for Java cannot use the
OCSP information in a
client channel definition
table file. However,
you can configure
OCSP as described
in Clustering: Using
REFRESH CLUSTER best
practices.

288 IBM MQ Explorer

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
The Storage Class folder Click the Storage Class Storage class
contains all of the storage folder to list the storage
Storage classes that are on classes in the Content
Class the queue manager. The view. Right-click the
messages that are on Storage Class folder to
queues that are not perform tasks such as
shared are stored on page creating a new storage
sets. Storage classes map class.
the queues to page sets.
The Storage Class folder
is available only on z/OS
queue managers.
The Queue Sharing Click the Queue Sharing Queue sharing groups
Groups folder contains Groups folder to list the
Queue all of the queue sharing queue sharing groups in
sharing groups groups that are defined on the Content view. Expand
the queue manager. The the Queue Sharing
Queue Sharing Groups Groups folder to display
folder is available only on the queue sharing groups
z/OS queue managers. that it contains.
Each queue sharing group Click the queue sharing Queue sharing groups
that is shown in the group to display an
A queue Queue Sharing Groups overview of the queue
sharing group folder is represented by sharing group's attributes
a node in the hierarchy. in the Content view.
Objects in a queue sharing Right-click the queue
group are available to all sharing group to perform
of the queue managers tasks such as deleting
that belong to the the queue sharing
queue sharing group. The group, or viewing the
objects that are in the queue sharing group's
queue sharing group are properties. Expand the
organized in folders under queue sharing group to
that queue sharing group. display the folders that
Queue sharing groups are contain the objects that
available only on z/OS are available to all of the
queue managers. queue managers in the
queue sharing group.
The Shared Queues Click the Shared Queues “IBM MQ queues” on page
folder contains all of the folder to list the shared 15
Shared queues that have the queues in the Content
Queues disposition Shared in the view. Right-click the
queue sharing group. All Shared Queues folder to
of the queue managers in perform tasks such as
the queue sharing group creating a new shared
can put and get from the queue.
shared queues without
needing channels. The
Shared Queues folder is
available only on z/OS
queue managers.

Introduction to IBM MQ Explorer 289

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
The Coupling Facility Click the Coupling
Coupling
Structures folder contains Facility Structures folder
facility structures
Coupling all of the coupling facility to list the coupling
Facility Structures structure objects that are facility objects in the
available in the queue Content view. Right-click
sharing group. Coupling the Coupling Facility
facility objects represent Structures folder to
physical coupling facility perform tasks such as
structures, which store creating a new coupling
the messages that are facility object to represent
on shared queues so a physical coupling facility
that any queue manager structure.
in the queue sharing
group can get the
messages. The Coupling
Facility Structures folder
is available only on z/OS
queue managers.
The Group Definitions Expand the Group Queue sharing groups
folder does not directly Definitions folder to
Group contain any MQ objects. display the object folders
Definitions The Group Definitions that it contains.
folder contains other
folders that contain MQ
objects in the queue
sharing group that have
the disposition Group,
which means that all the
queue managers in the
queue sharing group have
a copy of the objects. The
objects that are in folders
in the Group Definitions
folder are a subset of the
objects that belong to the
z/OS queue manager. You
cannot hide the Group
Definitions folder. The
Group Definitions folder
is available only on z/OS
queue managers.

290 IBM MQ Explorer

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
Queue Manager Clusters The Queue Manager Click the Queue Manager Queue manager clusters
Clusters folder contains Clusters folder to list the
all of the clusters that clusters in the Content
IBM MQ Explorer knows view. Right-click the
about. IBM MQ Explorer Queue Manager Clusters
knows about clusters folder to perform tasks
that belong to queue such as creating a new
managers in the Queue queue manager cluster.
Managers folder. The
Queue Manager Clusters
folder is available only
when a queue manager
in the Queue Managers
folder belongs to a cluster.
A cluster Each queue manager Click the queue Queue manager clusters
cluster that is shown manager cluster to view
in the Queue Manager information about it.
Clusters folder is Right-click the queue
represented by a node in manager cluster to
the hierarchy. The queue perform tasks such as
managers that belong to adding queue managers
the cluster are shown to it.
in folders in the Queue
Manager Clusters folder.
Queue manager clusters
are available to administer
in IBM MQ Explorer only
when a queue manager
in the Queue Managers
folder belongs to a cluster.
Full Repositories The Full Repositories Click the Full Queue manager clusters
folder contains all of Repositories folder to list
the queue managers that the queue managers that
host full repositories of host full repositories for
the cluster. The queue the cluster in the Content
managers in the Full view. Right-click the Full
Repositories folder store Repositories folder to add
a complete, up-to-date another queue manager
set of information about that hosts a full repository
the cluster. The Full to the cluster.
Repositories folder is
available only when a
queue manager in the
Queue Managers folder
belongs to a cluster.

Introduction to IBM MQ Explorer 291

Object or folder Purpose of the object or Tasks that you can Links to more
folder perform information
A queue manager that Each queue manager that Click the queue manager Queue manager clusters
hosts a full repository hosts a full repository for to list the cluster queues
the cluster is represented and cluster channels that
by a node in the are available on the
hierarchy. The queue queue managers. Right-
managers in the Full click the queue manager
Repositories folder store to perform tasks such
a complete, up-to-date as removing the queue
set of information about manager from the cluster,
the cluster. or share the queue
manager's queues in the
cluster.
Partial Repositories The Partial Repositories Click the Partial Queue manager clusters
folder contains all of Repositories folder to list
the queue managers that the queue managers that
host partial repositories host partial repositories
of the cluster. The queue for the cluster in the
managers in the Partial Content view. Right-click
Repositories folder store the Partial Repositories
only information about folder to add another
objects in the cluster that queue manager that hosts
those queue managers a partial repository to the
need to used. cluster.
A queue manager that Each queue manager that Click the queue manager Queue manager clusters
hosts a partial repository hosts a partial repository to list the cluster queues
for the cluster is and cluster channels that
represented by a node in are available on the
the hierarchy. The queue queue managers. Right-
managers in the Partial click the queue manager
Repositories folder store to perform tasks such
only information about as removing the queue
objects in the cluster that manager from the cluster,
those queue managers or share the queue
need to used. manager's queues in the
cluster.

Depending on which other plug-ins you have installed and enabled for IBM MQ Explorer, the Navigator
view might contain other folders and objects.
Related tasks
“Showing or hiding a queue manager” on page 81
By default, the Navigator view shows all of the queue managers on the computer on which IBM MQ
Explorer is installed. However, if you have any queue managers that you are not currently administering,
you can, if you wish, choose to hide them. You can also show and hide remote queue managers.
“Enabling installed plug-ins” on page 221
If a new plug-in that you install in IBM MQ Explorer is not enabled by default, you can enable it by using
the Preferences dialog.
Related reference
“Icons in IBM MQ Explorer” on page 280
IBM MQ Explorer uses icons to represent the different objects, such as queue managers, queues, and
channels.
“Views in IBM MQ Explorer” on page 285

292 IBM MQ Explorer

 IBM MQ Explorer is a perspective in Eclipse Platform, which is built on Eclipse technology.

IBM MQ Explorer Content view

The Content view in IBM MQ Explorer displays information about objects and properties.
When you click a folder in the Navigator view, the Content view displays the IBM MQ objects, and their
properties, that are in the folder. When you click a queue manager in the Navigator view, a summary, or
QuickView, of the queue manager's properties is displayed in the Content view.
When you select a queue manager set in the Navigator view, the Content view displays the grouped
queue managers, as well as if the set is automatic or manual.
You can customize and reorder the properties and objects that are displayed in the Content view by using
schemes and filters.

Gray cells in the Content view

Empty gray cells in the Content view indicate that the property is not relevant and cannot be set.
For example, the Scope attribute is not valid for model queues. If you click the Queues folder to
display its contents in the Content view, the Scope attribute cell is shaded gray for any model queues.
Similarly, the Transmission Queue attribute cell is shaded gray for all queue types except for remote
queue definitions, for which you can set the Transmission Queue attribute. If you have not set the
Transmission Queue attribute for a remote queue definition, the cell is empty and white. White cells
indicate that the property can be set.
You can change the color of these cells in the Preferences dialog. For more information, see “Changing
the colors” on page 221.
Related concepts
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
Related tasks
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.
“Configuring IBM MQ Explorer” on page 192
Use this information to help you to configure your IBM MQ Explorer installation.
“Enabling installed plug-ins” on page 221
If a new plug-in that you install in IBM MQ Explorer is not enabled by default, you can enable it by using
the Preferences dialog.
Related reference
“Icons in IBM MQ Explorer” on page 280
IBM MQ Explorer uses icons to represent the different objects, such as queue managers, queues, and
channels.
“Views in IBM MQ Explorer” on page 285
IBM MQ Explorer is a perspective in Eclipse Platform, which is built on Eclipse technology.

Preferences for IBM MQ Explorer

Use this information to help you to configure your IBM MQ Explorer installation.
You can customize the way that IBM MQ Explorer presents information to you, including the order of
columns in tables and the objects that are displayed in the Content view. You can also customize a range
of other preferences to suit your business needs. The availability of certain preferences depends on which
plugins you have that are installed and enabled for IBM MQ Explorer.

Introduction to IBM MQ Explorer 293

 Key settings can be configured in the Preferences dialog. To open the Preferences dialog: Click Window
> Preferences. Other settings can be configured as per the information in the following table:

Table 6. Options for configuring the settings for IBM MQ Explorer preferences
Type of setting Configuration task Where to find more information
Authorization Displaying object authority settings as “Displaying object authority settings as
service text text” on page 226
Client connections Remote queue managers; specifying “Specifying the default values used to
default values that are used to connect connect to remote queue managers” on
to remote queue managers page 223
TLS Key Repositories; specifying the “Specifying the default location and
default location and default password of default password of TLS certificates” on
TLS certificates page 87
TLS Options; specifying default security “Default security preferences” on page
preferences 161
Security exit; configuring a default “Configuring a default security exit” on
security exit page 160
User identification; enabling default user “Users and groups (entities) in the
identification authorization service” on page 149
Display settings Changing the colors “Changing the colors” on page 221
Defining schemes and filters from the Filtering the objects displayed in the
relevant content view Content view
Setting the order of columns in tables Changing the order of columns in tables
and the objects that are displayed
Changing the refresh frequency of queue “Changing the refresh frequency of
manager information queue manager information” on page
222
Displaying object authority settings as “Displaying object authority settings as
text text” on page 226
Enable Plug-ins Enabling installed plug-ins “Enabling installed plug-ins” on page
221
Managed File Configuring managed file transfer “Configuring Managed File Transfer
Transfer preferences” on page 299
Messages Configuring messages “Configuring message preferences” on
page 300
Passwords Setting password preferences “Passwords preferences” on page 163
Telemetry Configuring telemetry channels “Telemetry channels” on page 238
Tests Including hidden queue managers in “Including hidden queue managers in
test configurations test configurations” on page 226
Including SYSTEM objects when you run “Including SYSTEM objects when you
tests run tests” on page 225

294 IBM MQ Explorer

Filtering the objects displayed in tables
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.

About this task

An example of the filtering that you can do is that when the Content view displays the contents of a queue
manager's Queues folder, you might choose to display only the queues that have a name that starts with
saturn. Instead of creating a new filter for each type of object on each queue manager, you can create a
filter for a type of object, such as queues, on one queue manager, and then reuse the filter for queues on
other queue managers.
You can filter on the following criteria:
• The name of the object.
• The type of the object (queues and channels only).
• An attribute of the object (optional).
IBM MQ Explorer supplies and applies a standard filter for each type of object. For example, the
Standard for Queues filter includes all the queues so that you can be sure that you are viewing
all the queues on the queue manager, the Standard for Channels filter includes all the channels,
and so on. IBM MQ also supplies a selection of other useful filters; for example, an All queues with
messages filter displays only queues that have one or more messages.
To apply a different filter to a folder of objects:

Procedure
1. In the Content view or dialog that contains the table, click the small arrow next to the current filter
name. A menu is displayed.
2. If you want to apply one of the other supplied filters, in the menu, click the name of the filter. The
menu closes and the filter is applied to the table.
3. If you want to apply a different filter (that was not supplied with IBM MQ), click More Filters... The
Select Filter dialog opens displaying the filters that are available.
4. In the Apply filter list, click the filter that you want to apply, or click No filter to remove all filtering
from the table.
5. Click OK.

Results
The selected filter is applied to the selected folder.
Related concepts
“Define schemes to change the order of columns in tables” on page 217
When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.

Define schemes to change the order of columns in tables

When object data is displayed in IBM MQ Explorer in tables, you can customized the order of the columns
in the tables.
For example, queues have a large number of attributes; when you display the contents of a Queues folder
in the Content view, if you are not interested the creation date and time of the queues, you can choose
not to display those attributes, or you can move those columns to somewhere else in the table.
The changes that you make are saved as schemes so that you can apply the same set of changes to the
same type of objects on other queue managers too.

Introduction to IBM MQ Explorer 295

 IBM MQ Explorer supplies and applies standard schemes. Because IBM MQ for z/OS for
queue managers and objects can have slightly different attributes, each object scheme has settings
for the object on Multiplatform queue managers and for z/OS queue managers. The standard schemes
include all the attributes for objects of that type. For example, the Standard for Queues scheme
includes all the attributes for queues on Multiplatforms and z/OS platforms so that you can be sure that
you can see all the attributes for the queues that are listed.
To apply an existing scheme to a table:
1. In the Content view, or dialog that contains the table, click the small arrow next to the current scheme
name. A menu is displayed.
2. From the menu, click Select Scheme The Select Scheme dialog opens.
3. In the Select Scheme dialog, click the scheme that you want to apply. The attributes that the scheme
will display are listed in the dialog.
4. Click OK.
The selected scheme is applied to the folder of objects.
Related tasks
“Creating a scheme” on page 218
You can create schemes for most of the tables of data in IBM MQ Explorer.
“Editing an existing scheme” on page 219
You can edit any schemes that you created previously and you can also edit the schemes that are supplied
with IBM MQ Explorer; for example, the Standard for Queues scheme. After modifying the layout of
the status table, you can reset the width of the columns to their default values.
“Copying an existing scheme” on page 220
If there already exists a scheme that is similar to a scheme that you want to create, you can copy the
existing scheme and then edit it as required.
“Filtering the objects displayed in tables” on page 193
When object data is displayed in IBM MQ Explorer in tables, you can filter the data so that only the objects
in which you are interested are displayed.

Changing the refresh frequency of queue manager information

In IBM MQ Explorer, the information about local and remote queue managers is automatically refreshed
at set intervals. You can change the refresh frequency for a specific queue manager, or the default refresh
frequency for all new queue managers. You can also prevent a specific queue manager's information from
being refreshed automatically.

About this task

By default, the information that is displayed about remote queue managers is refreshed less frequently
than the information about local queue managers because of the increase in network traffic every time
that the information is requested from remote systems.
You can also prevent specific queue managers being refreshed automatically. For example, if you know
that a queue manager will remain stopped for a period of time, you could prevent IBM MQ Explorer
requesting information about it and so reduce the network traffic.
• “Changing the refresh frequency for a specific queue manager” on page 222
• “Changing the default refresh frequency for all new queue managers” on page 223
• “Preventing automatic refresh of a queue manager's information” on page 223

Changing the refresh frequency for a specific queue manager

About this task

To change the frequency with which information about a specific queue manager is refreshed:

296 IBM MQ Explorer

Procedure
1. In the Navigator view, right-click the queue manager, then click Connection Details > Set Refresh
Interval The Automatic Refresh dialog opens.
2. In the Automatic Refresh dialog, edit the value in the Interval field.
3. Optional: To reset the automatic refresh rate to the default value, click Apply Default.
4. Click OK to save the new refresh rate.

Results
The information about the queue manager is now automatically refreshed at the new rate.

Changing the default refresh frequency for all new queue managers

About this task

To change the frequency with which the information about local and remote queue managers is refreshed:

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. On the MQ Explorer page, in the Default Queue Manager Refresh Intervals fields, type the refresh
interval, in seconds, then click OK.

Results
All new queue managers that are added to IBM MQ Explorer are now refreshed at the new rate.

Preventing automatic refresh of a queue manager's information

About this task

To prevent queue manager information in IBM MQ Explorer from being refreshed automatically:

Procedure
1. In the Navigator view, right-click the queue manager, then click Connection Details > Set Refresh
Interval The Automatic Refresh dialog opens.
2. In the Automatic Refresh dialog, clear the check box, then click OK.

Results
The information about the queue manager is no longer refreshed automatically. To refresh the information
about the queue manager, click Refresh on the menu in the Content view.

Displaying object authority settings as text

In IBM MQ Explorer dialogs, object authorities are displayed as icons by default, but you can choose to
have them displayed as text instead.

About this task

In the Manage Authority Records dialogs, and in other dialogs that display object authorities, the tables
use icons to show whether an authority is granted. If you prefer, you can set the tables to use text instead
of icons.
To change the tables to use text instead of icons to show whether an authority is granted, complete the
following steps.

Introduction to IBM MQ Explorer 297

 Procedure
1. Open the Preferences dialog: Window > Preferences
2. Expand MQ Explorer.
3. On the Authorization Service page, click Display authorities as text.
4. Click OK to close the Preferences dialog.

Results
The next time that you open a dialog that displays object authorities, the tables will show authorities
using text instead of icons.
Related tasks
“Configuring IBM MQ Explorer” on page 192
Use this information to help you to configure your IBM MQ Explorer installation.
Related reference
“Accessibility in IBM MQ Explorer” on page 279
Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.

Changing the colors

You can change the colors that are used to highlight parts of the IBM MQ Explorer interface.

About this task

In IBM MQ Explorer, there are several places where color is used to highlight parts of the interface. For
example, in the Content view, cells that are not applicable to an object are colored gray; in the command
window that contains the command details of the Create Queue Manager wizard, sections of the text are
highlighted in different colors. In the Preferences dialog, you can change the colors that are used.
To change the color of cells that are not applicable:

Procedure
1. Open the Preferences dialog: Window > Preferences
2. In navigation tree of the Preferences dialog, expand MQ Explorer, then click Colors.
3. On the Colors page, click the palette button for the feature that you want to change. The palette button
in the Content View section of the page controls the color of cells that are not applicable (cells that are
colored gray by default); the palette buttons in the Command Details section of the page control the
color of the text and background in the command windows that are displayed in the Details window
when you create, delete, start, and stop a queue manager in IBM MQ Explorer.
4. In the palette, click the color that you want to use (or define a custom color), then click OK.
5. Click OK to close the Preferences dialog.

Results
The color that you selected is used.
Related tasks
“Configuring IBM MQ Explorer” on page 192
Use this information to help you to configure your IBM MQ Explorer installation.
Related reference
“Accessibility in IBM MQ Explorer” on page 279

298 IBM MQ Explorer

Accessibility features help a user who has a physical disability, such as restricted mobility or limited
vision, to use software products successfully.

Enabling installed plug-ins

If a new plug-in that you install in IBM MQ Explorer is not enabled by default, you can enable it by using
the Preferences dialog.

About this task

When you install a new plug-in in IBM MQ Explorer, whether the plug-in is supplied by IBM or by a third
party, if the plugin does not appear to be working in IBM MQ Explorer, it is likely that the plug-in is not
enabled by default.
To enable an installed plugin, complete the following steps.

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. In the navigation tree of the Preferences dialog, expand MQ Explorer, then click Enable plug-ins. A
list of the available plugins is displayed.
3. Select the check box next to the plug-in that you want to enable, then click OK.

Results
The plug-in is now enabled in IBM MQ Explorer. Any folders or menu items for example, that are related to
the plug-in are now available in IBM MQ Explorer.
You can also disable plug-ins that you do not use. For example, if you do not use clustering in your
messaging networks, you can clear the check box next to the Cluster Component plugin. The Cluster
Component plugin remains installed on your computer so that you can enable it in future. Because the
plug-in is still installed on your computer, the help that is associated with clustering is still available in the
help system and in the context-sensitive help.

Configuring Managed File Transfer preferences

The Managed File Transfer preferences that you can configure in IBM MQ Explorer include general
preferences and the default global configuration type. You can also select the level of functional fix pack
behavior that you want to enable.

About this task

To configure Managed File Transfer preferences within IBM MQ Explorer, complete one of the following
tasks:
• “Setting general preferences” on page 299
• “Overriding the default global configuration subscription type” on page 300
• “Selecting the level of fix pack function” on page 300

Setting general preferences

About this task

You can override the default time zone in which to display any date and time values in the Managed File
Transfer panels, and you can select the maximum number of log and progress messages to store and
retain in the plugin's state.

Introduction to IBM MQ Explorer 299

 Procedure
1. Click Window, and then click Preferences.
The Preferences dialog opens.
2. Click Managed File Transfer.
Managed file transfer settings appear.
3. To override the default time zone in which to display any date and time values in the Managed File
Transfer panels, choose your preferred time zone from the Time zone list.
4. To choose the maximum number of log and progress messages to store, select the appropriate values.
Defaults for each are 1000.

Overriding the default global configuration subscription type

About this task

You can override the type of subscription that is made when you are connecting to a globally configured
property set. You can configure subscriptions to be durable or non-durable. This setting determines
what happens when the plug-in disconnects from the coordination queue manager. Durable subscriptions
continue to exist while the plug-in is disconnected and continue to receive publications. Non-durable
subscriptions exist only if the connection to the queue manager is available.

Procedure
1. Click Window, and then click Preferences.
The Preferences dialog opens.
2. Click Managed File Transfer.
Managed file transfer settings appear.
3. Under Default global configuration subscription type, choose from either Durable or Non-durable.

Selecting the level of fix pack function

About this task

You can select the level of functional fix pack behavior that you want to enable. In addition to APAR fixes,
certain levels of IBM MQ Explorer Fix Packs contain new function or changes in behavior that are disabled
by default. To enable these changes, select the level of function that you want to move to. This setting
does not affect the application of fixes, which are always applied.

Procedure
1. Click Window, and then click Preferences.
The Preferences dialog opens.
2. Click Managed File Transfer.
Managed file transfer settings are displayed.
3. Select the level of function to which you want to move.

Configuring message preferences

You can configure browsing limits and set how message properties are displayed.

About this task

To configure message preferences within IBM MQ Explorer, complete one of the following tasks:
• “Configuring browsing limits” on page 301

300 IBM MQ Explorer

• “Showing message properties” on page 301

Configuring browsing limits

About this task

You can configure he following values:
• The maximum number of messages that can be browsed in the range 1 - 5000.
• The maximum number of bytes of data to be displayed per message in the range 0 - 16 384.
Important: Ensure that your system has enough random access memory (RAM) to display large numbers
of messages or system performance might be affected.

Procedure
1. Click Window, and then click Preferences.
The Preferences dialog opens.
2. Click Messages.
Messages settings appear.
3. Change the maximum number of messages that are browsed by either clicking the up or down arrows,
or by typing a new value. The default value is 500.
4. Change the maximum data bytes that are displayed by either clicking the up or down arrows, or by
typing a new value. The default value is 1000.

Showing message properties

About this task

You can set how message properties are displayed. You can show no message properties, or you can
show message properties as Named Properties, as an MQRFH2 structure in the message body, or as an
MQRFH2 structure in the message body compatible with IBM WebSphere MQ 6.0.

Procedure
1. Click Window, and then click Preferences.
The Preferences dialog opens.
2. Click Messages.
Messages settings appear.
3. To show no message properties, except those properties that are contained in the message descriptor
or extension, clear the Show message properties check box.
For more information, see “Named Properties page” on page 463.
4. To show message properties as Named Properties, select the as Named Properties check box.
Properties of the message, except those properties that are contained in the message descriptor or
extension, are represented in the Named Properties panel in name-value pairs, and the properties are
removed from the message data.
For more information, see the entry for MQGMO_PROPERTIES_IN_HANDLE in “Named Properties
page” on page 463.
5. To show message properties as an MQRFH2 structure in the message body, select the as an MQRFH2
structure in message body check box. Properties of the message, except those properties that are
contained in the message descriptor or extension, are represented in the MQRFH2 Properties panel
and the properties remain in the message data.
For more information, see the entry for MQGMO_PROPERTIES_FORCE_MQRFH2 in “MQRFH2
Properties page” on page 463.

Introduction to IBM MQ Explorer 301

 6. To show message properties as an MQRFH2 structure in the message body, select the as an MQRFH2
structure in message body, compatible with WebSphere MQ V6 check box. If the message contains
a property with a prefix of mcd., jms., usr., or mqext., all message properties, except those
properties that are contained in the message descriptor or extension, are represented in the MQRFH2
Properties panel and the properties remain in the message data. Otherwise, all properties of the
message, except those properties that are contained in the message descriptor or extension, are
discarded and not displayed.
For more information, see the entry for MQGMO_PROPERTIES_FORCE_MQRFH2 in “MQRFH2
Properties page” on page 463.

User identification
The user identification for all queue managers in a set can be changed. The user identification can be
overridden when you add a new remote queue manager.
The user identification preferences are part of the Preferences dialog, and they can be opened in the
following way:
1. Click Windows > Preferences.... The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand User identification. The default user identification settings dialogs are now accessible.

Select Enable default user identification to enable the Userid and Password fields.

Item Description
Enable user Select Enable user identification to enable the fields on this dialog.
identification
User When selected, the userid and password are passed to the server in a way compatible
identification with security exits created prior to IBM MQ 8.0.
compatibility
Mode
Userid The userid and password, when specified, are passed to the server, and can be used
either by:
• The queue manager, if configured to use connection authentication, or
• A server security exit, if using a client connection
to establish the identity of the IBM MQ Explorer user.
No password When selected, no password is passed to the server with the userid.
Prompt for When selected, the user is prompted for a password that is passed to the server with the
password userid. The prompting occurs as part of the connect operation.
Use saved When selected, the saved password is passed to the server with the userid.
password
Saved The saved password to be passed to the server with the userid
password

Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.
“Passwords preferences” on page 163

302 IBM MQ Explorer

You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Passwords preferences
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.
Passwords used by the IBM MQ Explorer to connect to resources (for example: opening TLS stores or
connecting to queue managers), can be stored in a file. The password file can be stored locally, to a
remote device, or to a removable device.
To open the Passwords preference panel:
1. Click Window > Preferences. The Preferences dialog opens.
2. Expand MQ Explorer.
3. Select Passwords to display the Passwords panel.

Item Description
Do not save Passwords are not stored to a file. This is the default value.
passwords
Save Passwords are saved to the file you specify. Select Save passwords to file and click
passwords Browse to select a location for the encrypted password file
to file
Use default You must use a key to open a password store. This is the default value.
key
User You must use a key to open a password store. Select User defined key then click Change
defined key to enter your password. The password must contain a minimum of 8 characters.

Related tasks
“Configuring a default security exit” on page 160
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.
“Configuring the client security details for a queue manager set” on page 160
The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.

Default security preferences

A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.
The default security preferences are part of the Preferences dialog, and they can be opened in the
following way:
1. Click Windows > Preferences.... The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand Client Connections. The default security settings dialogs are now accessible.

Introduction to IBM MQ Explorer 303

 Security Exit
Select Enable default security exit to set the default security exit for all client connections in the same
IBM MQ Explorer. The security exit for all the client-connected queue managers in a set can be changed.
The security exit can be overridden if you define a new security exit when you add a new remote queue
manager.
The Security Exit for all client-connected queue managers in a set can be changed. The TLS options can
be overridden when you add a new remote queue manager.

Item Description
Exit Specifies the name of the exit program to be run by the security exit. Exit name can be
name up to 1024 characters long and is case sensitive. Exit name can be a fully qualified java
class name found in the directory or jar file. Exit name can be a C exit, of the format:
dll_name(function_name). The default path for exits is always used to locate C exits, you
cannot specify the location of the exit library in this entry field unless no default path is set.
in Specifies the directory for the security exit (Java exits only).
directory
in jar Specifies the jar file for the security exit (Java exits only).
Exit data Exit data can be up to 32 characters long. If no value has been defined for that attribute,
this field is all blanks.

SSL/TLS Options
Select Enable default SSL options to enable the default SSL/TLS options for all client connections in the
same IBM MQ Explorer. The SSL/TLS options for all client-connected queue managers in a set can be
changed. The SSL/TLS options can be overridden when you add a new remote queue manager.

Item Description
SSL The CipherSpec identifies the combination of encryption algorithm and hash function used
CipherSp by an SSL/TLS connection. A CipherSpec forms part of a CipherSuite, which identifies the
ec key exchange and authentication mechanism as well as the encryption and hash function
algorithms.
The size of the key used during the handshake can depend on the digital certificate you use,
but some of the CipherSpecs supported by IBM MQ include a specification of the handshake
key size. Note that larger handshake key sizes provide stronger authentication. With smaller
key sizes, the handshake is faster.
For more information, see CipherSpecs and CipherSuites.

SSL FIPS Select Yes to use only FIPS-certified cipher suites. If you select Yes, then all TLS connections
required must use FIPS-certified cipher suites.

Select No to use any available cipher suites.

The default setting is No.
If you change this setting from Yes to No, or from No to Yes a dialog will be opened asking if
you want to restart MQ Explorer.
Any changes to this setting will not be applied until the MQ Explorer has been restarted.

304 IBM MQ Explorer

Item Description
SSL Type the number of bytes, from 0 to 999 999 999, that are sent and received within a TLS
reset conversation before the secret key is renegotiated. A value of 0 means that the secret key
count is never renegotiated. The number of bytes includes control information that is sent by the
message channel agent (MCA). If the value of this attribute is greater than 0 and the value of
the Heartbeat interval attribute in the Channel properties is greater than 0, the secret key is
also renegotiated before message data is sent or received following a channel heartbeat.
Peer The Distinguished Name (DN) of the queue manager to be used by TLS. The peer name
name is set to indicate that connections will only be allowed where the server is successfully
authenticated as a specific DN.

SSL/TLS Stores
Select Enable default SSL stores to work with the Trusted Certificate Store and the Personal Certificate
Store.
To configure IBM MQ Explorer with the location and password of the SSL/TLS certificate store, refer to:
“Specifying the default location and default password of TLS certificates” on page 87.
By enabling the default SSL/TLS stores, IBM MQ Explorer can use the certificates in the TrustStore and
KeyStore to connect to remote queue managers with a TLS-enabled connection.
The SSL/TLS Stores for all client-connected queue managers in a set can be changed. The SSL/TLS Stores
can be overridden when you add a new remote queue manager.
Related tasks
“Configuring a default security exit” on page 160
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.
“Configuring the client security details for a queue manager set” on page 160
The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.
Related reference
“Passwords preferences” on page 163
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Configuring a default security exit

A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit.

About this task

The default security definitions will be persisted in IBM MQ Explorer and will be automatically included in
Preferences in any import actions or export actions. The security exit details for each queue manager will
be persisted with the other connection details of the queue manager.
To configure the default security exit:

Procedure
1. Click Window > Preferences.
The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand Client Connections.
The default security settings dialogs are now accessible.

Introduction to IBM MQ Explorer 305

 4. Configure the security settings as required.

What to do next
The default security exit has now been configured. All new client connections in the same IBM MQ
Explorer now use the settings you have configured as a default. The settings can be overridden when
adding a new remote queue manager.
Related tasks
“Configuring the client security details for a queue manager set” on page 160
The client security details and security exit can be defined for all the client-connected queue managers in
a queue manager set.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.
“Passwords preferences” on page 163
You can store passwords to a file so that you do not have to enter them every time you want to connect to
resources.

Specifying the default location and default password of TLS certificates

You can configure IBM MQ Explorer to use TLS certificates in the TrustStore and KeyStore to connect to
remote queue managers with an TLS-enabled connection.

About this task

To configure IBM MQ Explorer with the location and password of the TLS certificate store, complete the
following tasks in IBM MQ Explorer on the computer from which you want to connect to the remote queue
manager:

Procedure
1. In IBM MQ Explorer, click Window > Preferences.
The Preferences dialog opens.
2. Expand MQ Explorer.
3. Expand Client Connections. The default security settings dialogs are now accessible.
4. Select SSL Key Repositories to display the SSL Key Repositories pane.
5. In the Trusted Certificate Store field, browse for the location of the TrustStore on the computer, and
in Personal Certificate Store field, browse for the location of the KeyStore on the computer.
The TrustStore and KeyStore contain the TLS certificates that are used with connections using client
channel definition tables. It is possible that the TrustStore and KeyStore are in the same location on
your computer.
6. (Optional) Click Enter password... in the Trusted certificate Store section to open the SSL Password
dialog; in the SSL Password dialog, type the password that IBM MQ Explorer will need to access the
store.
7. Click Enter password... in the Personal Certificate Store section to open the SSL Password dialog; in
the SSL Password dialog, type the password that IBM MQ Explorer will need to access the store.
8. Click OK to save your changes and to close the Preferences dialog.

Results
IBM MQ Explorer can now use the TLS certificates in the TrustStore and KeyStore to connect to remote
queue managers with an TLS-enabled connection.
Related tasks
“Showing a remote queue manager” on page 82

306 IBM MQ Explorer

If you want to administer a remote queue manager, you must connect IBM MQ Explorer to the remote
queue manager so that the queue manager is displayed in the Navigator view. You can create a
connection manually, or using a client channel definition table. You can also create a new security-
enabled connection, or connect using an existing connection.
“Creating a client channel definition table” on page 86
You can create a client channel definition table for a queue manager to make it easier to connect
instances of IBM MQ Explorer to the queue manager.
Related reference
“Default security preferences” on page 161
A security exit can be defined for all client connections in the same IBM MQ Explorer. This is known as a
default security exit and the preferences for the security exit are described here.

Telemetry channels
A Telemetry channel is a communication link between a queue manager on IBM MQ, and MQTT clients.
Each channel might have one or more telemetry devices connected to it.
For messages flowing from IBM MQ to MQTT clients, messages are taken from the default MQTT transmit
queue, and sent through the telemetry channel. Messages destined for specific MQTT clients are routed to
them using their client identifiers.

Advanced option
Telemetry channels have an option which sets the maximum number of client connections that can be
displayed in the Channel Status Content view. This option is called Max responses. The default value
is 500. Consider configuring this option before you start your queue manager. If your queue manager is
running, you must restart it to apply the advanced option changes.
To configure the maximum responses option, perform the following actions:
1. Click Window > Preferences.
2. Expand IBM MQ Explorer, then click Telemetry.
3. In the Max responses field, type the number of client connections to display at any one time.
4. Click OK.
Client connections on all telemetry channels up to the maximum response limit are shown in the Channel
Status Content view. If client connections exceed this limit, a warning is displayed within the Content
view. For example, if you set the maximum responses to 10 and you reach or exceed this number, the
following warning is displayed: The display has been limited to the first 10 responses.
Use a filter to select a subset of responses.
The Telemetry channel status window shows client connections specific to that channel. The maximum
response option limit applies only to client connections on this channel.
Related tasks
“Creating and configuring a telemetry channel” on page 243
A telemetry channel connects a number of MQTT clients to IBM MQ. Create one or more telemetry
channels on a queue manager. Each of these telemetry channels might have different configuration
settings, making it easier to manage the clients attached to them.
“Starting and stopping a telemetry channel” on page 250
“Viewing the status of a telemetry channel” on page 251
“Filtering Telemetry objects” on page 252

Introduction to IBM MQ Explorer 307

 If you are viewing several defined telemetry objects in the Content view, you might need a way to narrow
the search scope of these objects. Do this by using filters.

Including hidden queue managers in test configurations

Queue managers that are hidden in IBM MQ Explorer do not by default appear in the list of available
objects when you create new test configurations. However, you can choose to have hidden queue
managers included so that they listed as available queue managers against which you can run tests.

About this task

Queue managers that are currently hidden in IBM MQ Explorer are not currently of interest to you so, by
default, they are not included in the list of available objects when you create new test configurations.
To include hidden queue managers, complete the following steps.

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. In the navigation tree of the Preferences dialog, expand IBM MQ Explorer, then click Tests.
3. Select the Include hidden objects in the list of available objects check box.

Results
Next time you create or edit a test configuration, any hidden queue managers are listed as available queue
managers against which you can run the tests.

Including SYSTEM objects when you run tests

By default, SYSTEM objects are not included in test results, but you can choose to include them if
required.

About this task

Definitions of SYSTEM.DEFAULT objects are provided in IBM MQ as incomplete templates so, by default,
they are not included when you run tests. However, you can include them if you want.
To include SYSTEM objects in test results, complete the following steps.

Procedure
1. Click Window > Preferences to open the Preferences dialog.
2. In the navigation tree of the Preferences dialog, expand IBM MQ Explorer, then click Tests.
3. Select the Include SYSTEM objects in the test results check box.

Results
Next time you run tests against objects in IBM MQ Explorer, any available SYSTEM objects are also tested.

Properties
Use this information to find out about the properties that you can view and edit, including properties
that apply to the whole IBM MQ installation and the properties of an individual IBM MQ object such as a
queue, a queue manager, or a channel.
In IBM MQ Explorer, right-click any IBM MQ object, for example, a queue, a queue manager, or a channel,
then click Properties to view and edit the object's properties. The properties are displayed in a properties
dialog that is divided into pages according to the type of the properties, for example, TLS, exits, and
clusters.

308 IBM MQ Explorer

The following topics list all of the properties for IBM MQ objects. For each property, there is a description
of how to use it and why you might want to set it. The topics also include, where relevant, the equivalent
MQI call that you can use when programming applications, and the equivalent MQSC command that you
can enter on the command line.
• IBM MQ
• Queue managers
• Queues
• Channels, including client connections
• Listeners
• Topics
• Services
• Service definitions
• Subscriptions
• Process definitions
• Namelists
• Authentication information
• “Channel authentication record properties” on page 425

• Storage classes

• Queue sharing groups

• Coupling Facility structures

• Cluster queue manager
• Cluster queue
• Cluster topic
• Application connection
• Messages
• JMS connection factories
• JMS destinations
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

IBM MQ properties
IBM MQ properties apply to the whole IBM MQ installation.
The following tables list the properties that you can set for IBM MQ:
• General
• Extended
• Exits
• Default log settings
• ACPI
• Alert monitor
• Configuration information

Introduction to IBM MQ Explorer 309

 For each property, there is a brief description of when you might need to configure the property. The
properties in the IBM MQ properties dialog relate to stanzas in the configuration files.

General page
The following table lists the properties that you can set on the General page of the Properties for IBM MQ
dialog.

Property Description Stanza key

Default prefix To change the location of the directory that stores all the queue DefaultPrefix
manager data, type the full path to the new directory.
Default queue manager To specify a default name for new queue managers, type the Name
name name in this field.

Extended page
The following table lists the properties that you can set on the Extended page of the Properties for IBM
MQ dialog.

Property Description Stanza key

Default Ephemeral Prefix To change the location of the directory that stores all ephemeral DefaultEphem
queue manager data, type the full path to the new directory. eralPrefix
Convert EBCDIC newline EBCDIC code pages contain a newline (NL) character that is ConvEBCDICN
not supported by the ASCII code pages (although some ISO ewline
variants of ASCII contain an equivalent). If messages are sent
from a system that uses EBCDIC code pages (for example, a z/OS
system) to a system that uses ASCII, you can control how the
EBCDIC newline character is converted into ASCII format. The
default value is NL_TO_LF, which means that the EBCDIC NL
character (X'15') is converted to the ASCII line feed character
LF (X'0A') for all EBCDIC to ASCII conversions. To convert the
EBCDIC NL character according to the conversion tables on your
operating system, click TABLE. Note that the results of a TABLE
conversion can vary from platform to platform and from language
to language; even on the same platform the results might vary
if you use different coded character set identifiers (CCSIDs).
To convert ISO CCSIDs using the TABLE method and use the
NL_TO_LF method for all other CCSIDs, click ISO.
Cluster workload mode The cluster workload exit, CLWL, allows you to specify which CLWLMode
cluster queue in the cluster is to be opened in response to an
MQI call (for example MQOPEN or MQPUT). The default value
is SAFE, which means that the CLWL exit is run in a separate
process to the queue manager so that if there is a problem, the
integrity of the queue manager is preserved. However running the
CLWL exit as a separate process can have a detrimental effect
on performance. To improve performance by running the CLWL
exit in the same process as the queue manager, click FAST. Use
FAST mode only if you are certain that there are no problems with
your CLWL exit because if there is a problem in FAST mode, the
queue manager fails and the queue manager's integrity is at risk.
This value can be overridden for individual queue managers using
the cluster workload mode property. For more information, see
“Queue manager properties” on page 315.

310 IBM MQ Explorer

 Exits page
The following table lists the properties that you can set on the Exits page of the Properties for IBM MQ
dialog. To configure the exits that are common to all of the queue managers on this computer, edit the
properties on the Exits page.

Property Description Stanza key

Exits Default Path To change the location of channel exits for clients, and channel ExitsDefaultPa
exits and data conversion exits for servers, type the path to the th
new directory.
Common API Exits To configure a new common API exit for IBM MQ, click Add then ApiExitCommo
in the Properties dialog, type the details of the exit. To edit a n
common API exit that is already shown in the table, click Edit; to
remove an API exit from the table, click Remove.
Template API Exits To configure a new template API exit for IBM MQ, click Add then ApiExitTemplat
in the Properties dialog, type the details of the exit. To edit a e
template API exit that is already shown in the table, click Edit; to
remove an API exit from the table, click Remove.
Name Specifies the descriptive name of the API exit which is passed to Name
the API exit in the ExitInfoName field of the MQAXP structure.
This name must be unique and is limited to a length of 48
characters, and must contain only those characters that are valid
for the name of IBM MQ objects, such as queue names.
Type Specifies the type of exit: common, or template. (Not a
separate
stanza key.)
Sequence This property is an unsigned numeric value that defines the Sequence
sequence in which this API exit is called in comparison with
other API exits. An API exit with a low sequence number is called
before another API exit with a higher sequence number. The order
in which different API exits with the same sequence number are
called is undefined. It is perfectly value for there to be gaps in the
sequence numbers of the API exits defined for a queue manager.
Module Specifies the module that contains the code for the API exit. If Module
this field contains the full path name of the module it is used as is.
If this field contains just the module name, the module is located
using the same method as channel exits; that is, using the value
in the Exit default path field on the Exits page of the queue
manager properties dialog.
Function Specifies the name of the function entry-point into the module Function
that contains the code for the API exit. This entry-point is the
MQ_INIT_EXIT function. The length of this field is limited to
MQ_EXIT_NAME_LENGTH.
Data If this property is specified, leading and trailing blanks are Data
removed, the remaining string is truncated to 32 characters and
the result is passed to the exit in the ExitData field of the MQAXP
structure. If this property is not specified, the default value of 32
blanks is passed to the exit in the ExitData field of the MQAXP
structure.

Introduction to IBM MQ Explorer 311

 Default log settings
The following table lists the properties that you can set on the Default Log Settings page of the
Properties for IBM MQ dialog. To change the default log settings, edit the properties on the Default
Log Settings page. These settings are applied to all new queue managers by default.

Property Description Stanza key

Log type To enable the queue manager to recover when it is restarted, click LogType
Circular. If the queue manager uses circular logging, when the
log file is full, the file is overwritten starting from the beginning
of the file. To enable the queue manager to recover when it is
restarted and to enable media or forward recovery, click Linear. If
the queue manager uses linear logging, when the log file is full, a
new log file is started.
Log path To change the default location of the logs, type the full path LogPath
here. If you do not specify the path here, the default is a sub-
directory called Log in the DefaultPrefix, where DefaultPrefix is
the directory specified in the Default prefix property on the
General page of the Properties for IBM MQ dialog.
Log file pages Type the number, from 32 - 4095, of 4KB pages in the log file. For LogFilePages
example, if you type 256, the file size is 1MB.
Log primary files On AIX and Linux, type the number, from 2 to 510, of primary LogPrimaryFile
log files. The default value is 3. The total number of primary and s
secondary log files must not exceed 511 and must not be less
than 3.
On Windows, type the number, from 2 to 254, of primary log files.
The default value is 3. The total number of primary and secondary
log files must not exceed 255 and must not be less than 3.

Log secondary files On AIX and Linux, type the number, from 1 to 509, of secondary LogSecondary
log files. The default value is 3. The total number of primary and Files
secondary log files must not exceed 511 and must not be less
than 3.
On Windows, type the number, from 1 to 253, of secondary log
files. The default value is 3. The total number of primary and
secondary log files must not exceed 255 and must not be less
than 3.

Log buffer pages Type the number, from 0 - 512, of 4KB buffer pages for writing. If LogBufferPage
you specify 0, the queue manager selects the number itself. s
If you type a number from 1 to 17, the minimum of 18 is used. If
you type a number from 18 - 512, that number of pages is used. If
you change the value of this property, restart the queue manager
to detect the change.

312 IBM MQ Explorer

Property Description Stanza key
Log write integrity The method that the logger uses to reliably write log records. LogWriteIntegr
ity
The default value is TripleWrite. Note, that you can select
DoubleWrite, but if you do so, the system interprets this as
TripleWrite.
You should use SingleWrite, only if the file-system or device
hosting the IBM MQ recovery log explicitly guarantees the
atomicity of 4KB writes.
That is, when a write of a 4KB page fails for any reason, the
only two possible states are either the before image, or the after
image. No intermediate state should be possible.

Log management The method used to manage your logs. LogManagement applies LogManageme
only when LogType is LINEAR. nt
If you change the LogManagement value, the change does not
take effect until the queue manager is restarted.
There are three options.
Manual, where you manage the log extents manually. Specifying
this option means that the queue manager does not reuse or
delete log extents, even when they are no longer required for
recovery.
Automatic, where log extents are managed automatically by the
queue manager. Specifying this option means that the queue
manager is able to reuse or delete log extents as soon as they
are no longer required for recovery. No allowance is made for
archiving.
Archive, where log extents are managed by the queue manager,
but you must notify the queue manager when archiving of each
log extent is complete.
Specifying this option means that the queue manager is free to
reuse or delete a log extent, as soon as the queue manager has
been notified that an extent no longer required for recovery has
been archived.
The default value is Manual.

ACPI page
The following table lists the properties that you can set on the ACPI page of the Properties for IBM MQ
dialog. ACPI (Advanced Configuration and Power® Interface) is an operating system feature that allows
the computer to detect certain activity states and consequently to hibernate, that is to switch itself into a
low power mode with no programs running, and in such a manner as to allow a quick "wake up".
When ACPI wants to put the computer into hibernation it first sends a suspend request to all applications.
To control how IBM MQ responds to this request, set the Do dialog property on the ACPI page.

Property Description Stanza key

Do dialog The default value is Yes, which means that IBM MQ displays DoDialog
a message that asks the user whether to suspend the running
queue managers. To suspend IBM MQ without displaying this
message, click No.

Introduction to IBM MQ Explorer 313

Property Description Stanza key
Deny suspend If the Do dialog property is not set, or if it is set but the dialog DenySuspend
cannot be displayed (for example, if a laptop computer has its lid
closed) then Deny suspend controls the response. The default
value is No, which means that IBM MQ suspends, even if the
dialog cannot be displayed. To prevent IBM MQ suspending when
the dialog cannot be displayed, click Yes. This property can be
overruled by the Check channels running property.
Check channels running The default value is No, which means that IBM MQ does not CheckChannel
check whether there are any channels running, and responds as sRunning
directed by the Do dialog and Deny suspend properties. To
check whether there are any channels running, click Yes. If there
are no channels running, IBM MQ ignores the Do dialog and
Deny suspend properties. If there are channels running, IBM
MQ responds as directed by the Do dialog and Deny suspend
properties.

Alert monitor page

The Alert monitor is available only on Windows.

The following table lists the properties that you can set on the Alert monitor page of the Properties for
IBM MQ dialog. The Alert monitor is useful for problem determination. Alerts are raised by the services
when something goes wrong; for example, if a channel initiator service cannot start because a queue that
is needed has been deleted. To configure the alert monitor, edit the properties on the Alert monitor page.

Property Description Stanza key

Alert monitor notifies user The default value is No, which means that IBM MQ does not send Enable
alerts to the user when there is a problem. To configure IBM MQ
to send alerts when there is a problem, click Yes.
Alert monitor user Type the computer name or the user name to which IBM MQ Recipient
should send alerts.
Alert monitor icon added The default value is No, which means that the Alert Monitor icon TaskBar
to taskbar is not shown in the Windows system tray. To show the Alert
Monitor icon in the Windows system tray, click Yes.

Configuration information page

The following table lists the properties that are displayed on the Configuration information page of the
Properties for IBM MQ dialog. The properties on the Configuration information page are read-only.

Property Description
Install type Read-only. This property indicates whether you have
installed the Server or Client version of IBM MQ on this
computer.
mqjbnd05 loaded Read-only. This is the library that is required to
connect to local queue managers.
MQ Version Read-only. This is the version of IBM MQ installed on
this computer.
Build level Read-only. This is the build number of the IBM MQ
product that is installed on this computer.

314 IBM MQ Explorer

Property Description
Build type Read-only. This is the type of build of the IBM MQ
product that is installed on this computer.

Related tasks
“Configuring IBM MQ using IBM MQ Explorer” on page 12
In the Navigator view, you can use the Properties dialog to configure certain IBM MQ properties that
apply to the whole installation. If necessary, you can also configure the properties of individual queue
managers.

Queue manager properties

You can set properties for both local and remote queue managers.
The tables on this page list all the properties that you can set for local and remote queue managers.
For each property, there is a brief description of when you might need to configure the property.
Where relevant, the tables also give the equivalent MQSC parameter for the ALTER and DISPLAY QMGR
commands. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.
Those properties for a queue manager that are changed through MQSC using the ALTER QMGR commands
are the ones that are shown for both local and remote queue managers. Note, that the IBM MQ Explorer
does not show all the properties for remote queue managers.
Those properties that are defined in the qm.ini file, are the ones that are shown only for local queue
managers. For example, the specification for the Recovery Logs and the XA apply to the qm.ini file, and
so, is shown only for the local queue manager.
For lists of all the properties that you can set for both local and remote queue managers in the queue
manager's properties dialog see the following tables:
• General
• Extended

• Exits (Multiplatforms)
• Cluster
• Repository
• Communication
• Events
• SSL
• Statistics
• Online Monitoring

• Statistics Monitoring (Multiplatforms)

• Accounting Monitoring (Multiplatforms)

• Log (Multiplatforms)

• XA resource managers (Multiplatforms)

• Installable services (Multiplatforms)

• Channels

• TCP (Multiplatforms)

• LU6.2 (Multiplatforms)

Introduction to IBM MQ Explorer 315

 • NetBIOS (Multiplatforms)

• SPX (Multiplatforms)
• Publish/Subscribe

Some of these properties pages are available only on Multiplatforms queue managers.

Properties pages that are not available on z/OS queue managers are indicated.
The properties that are marked with an asterisk (*) update configuration files so you can view and edit
them when the queue manager is stopped. If you edit the marked properties when the queue manager
is running, you must stop and restart the queue manager so that the changes take effect. You can
edit the unmarked properties only when the queue manager is running. For more information about the
configuration properties, see qm.ini file stanzas and attributes.

The following tables list the system parameters that you can set for remote z/OS queue
managers. These properties are not displayed in the Queue Manager properties dialog. They are included
here because they are still properties of the queue manager. For more information, see Configuring z/OS
queue manager system parameters.

• Archive (z/OS)

• Archive tape (z/OS)

• Statistics monitoring (z/OS)

• Accounting monitoring (z/OS)

• Log (z/OS)

• Log copy (z/OS)

• Security (z/OS)

• Securityswitch (z/OS)

• System (z/OS)
For more information, see Administering IBM MQ and Administering IBM MQ using MQSC commands.

General
The following table lists the properties that you can set on the General page of the Queue Manager
properties dialog. The properties marked with an asterisk (*) on the General page relate to stanzas in the
configuration files.

Property Meaning MQSC

parameter
*Queue manager name Read-only. You cannot change the name of the queue manager QMNAME
after it has been created.
*Platform Read-only. This is the architecture of the platform on which the PLATFORM
queue manager is running.
Queue manager status Read-only. This property shows the status of the queue manager, STATUS
which can be 1 of the following options:
1. Running
2. Starting
3. Quiescing

316 IBM MQ Explorer

Property Meaning MQSC
parameter
Coded character set ID Read-only. This is the coded character set identifier (CCSID) for CCSID
the queue manager. The CCSID is the identifier that is used with
all character string fields defined by the API. The value must be
defined for use on your platform and must use a character set
that is appropriate to the platform.
Description Type a meaningful description of the purpose of the queue DESCR
manager. See Entering strings in IBM MQ Explorer.
*Command level Read-only. This is the function level of the queue manager. CMDLEVEL
Version Read only. This is the version of IBM MQ installed. The format is VERSION
VVRRMMFF:
• VV: Version
• RR: Release
• MM: Maintenance level
• FF: Fix level

The Startup property controls how the selected queue manager (Not
*Startup
is started. This property applies to Windows only. There are four applicable.)
options for the Startup property.
Select Automatic to start the queue manager automatically
when the IBM MQ Series service starts. This is the default value.
Select Automatic, permitting multiple instances of the queue
manager, to start the queue manager automatically when the IBM
MQ Series service starts. For more information, see the sax option
of CSQM507E.
Select Interactive (manual) to start the queue manager
manually through IBM MQ Explorer. The queue manager runs
under the logged on user (the interactive user). The queue
manager will automatically stop when the interactive user logs
off.
Select Service (manual) to start the queue manager manually
through IBM MQ Explorer. The queue manager runs as a child
of the MQ Services service. The queue manager will not
automatically stop when the interactive user logs off.

Command server control To configure the command server so that it starts automatically SCMDSERV
when the queue manager starts, click Queue Manager; to
configure the command server so that it does not start
automatically and must be started manually, click Manual.
Channel init control To configure the channel initiator so that it starts automatically SCHINIT
when the queue manager starts, click Queue Manager; to
configure the channel initiator so that it does not start
automatically and must be started manually, click Manual.

Extended
The following table lists the properties that you can set on the Extended page of the Queue
Manager properties dialog. The Default bind type property on the Extended page relates to the
DefaultBindType stanza key in the configuration files.

Introduction to IBM MQ Explorer 317

Property Meaning MQSC
parameter
Dead-letter queue Select the name of the queue that the queue manager uses as the DEADQ
dead-letter queue.
Trigger interval Type the number of milliseconds, from 0 to 999999999, that TRIGINT
the queue manager must wait between triggering messages for
a queue. This property is used only when the Trigger type
property in the Queue properties is set to First.
Max uncommitted Type the maximum number of uncommitted messages within a MAXUMSGS
messages syncpoint, from 1 to 999999999, to limit the number of messages
that can be retrieved and put within any single syncpoint. This
property is not used for messages that are put or retrieved
outside syncpoint.
Max handles Type the maximum number of open handles, from 0 to MAXHANDS
999999999, that any one task can have at the same time.
Max message length Type the maximum length of messages, from 32 KB to 100 MB, MAXMSGL
that is allowed on queues on the queue manager. The default
value is 4 MB (4 194 304 bytes). If you reduce the maximum
message length for the queue manager, you must also reduce the
maximum length of the SYTEM.DEFAULT.LOCAL.QUEUE definition,
and all other queues that are connected to the queue manager.
This ensures that the queue manager's limit is not less than
the limit of any of the queue manager's queues. If you do not
do this, and applications inquire only the value of the queue's
Max message length property, the applications might not work
properly.
Max properties length This value controls the size in bytes of the property data that MAXPROPL
can flow with messages in a V7 queue manager. If the size of
the properties exceeds the maximum properties length then the
message is rejected.
Max priority Read-only. This is the maximum priority of the queue manager, MAXPRTY
which is 9.
Message mark browse Type the time interval in milliseconds after which the queue MARKINT
interval manager automatically unmarks browsed messages. The interval
can be set to a maximum of 999999999 milliseconds. The
interval can also be set to Unlimited. The default value is 5000.
Attention: You should not reduce the value below the
default of 5000.

Command input queue Read-only. This is the name of the system-command input COMMANDQ
queue. Suitably authorized applications can put commands on
this queue.
Syncpoint Read-only. This property states whether syncpoint is available SYNCPT
with the queue manager. Syncpoint is always available on the
following platforms:

• AIX, Linux, and Windows

• z/OS
.

318 IBM MQ Explorer

Property Meaning MQSC
parameter
Distribution lists Read-only. This property states whether the queue manager DISTL
supports distribution lists. This property is valid only on
Multiplatforms.
AIX and Linux ( only) The Application group option specifies the application group that (Not
Application group clients connecting should belong to. The default is to not belong applicable.)
to an application group.
*Default bind type This is the default bind type that is used if the application does (Not
not specify a bind type on the MQCNO parameter of the MQCONNX applicable.)
call. Select SHARED, or ISOLATED.
*Error log size Specify the size of the queue manager error log at which the log is (Not
copied to the backup. The value must be 1048576 - 2147483648 applicable.)
bytes. The default value is 262144 bytes (256 KB).
*Excluded messages Your IBM MQ system might produce a large number of (Not
information messages if the system is heavily used. You can applicable.)
therefore exclude certain messages if required. Type the message
ID of each message that is not to be written to the queue
manager error log. Enter a comma-separated list of message IDs
from the following list:

• 7163 - Job started message (IBM i only)

• 7234 - Number of messages loaded
• 9001 - Channel program ended normally
• 9002 - Channel program started
• 9202 - Remote host not available
• 9524 - Remote queue manager unavailable
• 9528 - User requested closure of channel
• 9999 - Channel program ended abnormally

Introduction to IBM MQ Explorer 319

Property Meaning MQSC
parameter
*Suppressed messages Your IBM MQ system might produce a large number of (Not
information messages if the system is heavily used. You can applicable.)
prevent selected messages being sent to the console or to the
hardcopy log if required. Type the message ID of each message
that will be written to the queue manager error log only once
in a specified time interval. The time interval is specified in
the Suppressed Messages Interval property. Enter a comma-
separated list of message IDs from the following list:
• 7163 - Job started message (IBM i only)
• 7234 - Number of messages loaded
• 9001 - Channel program ended normally
• 9002 - Channel program started
• 9202 - Remote host not available
• 9524 - Remote queue manager unavailable
• 9528 - User requested closure of channel
• 9999 - Channel program ended abnormally
If the same message ID is specified in both the Excluded
Messages and the Suppressed Messages properties, the
message is excluded.

*Suppressed messages Type the time interval, in seconds, in which messages that are (Not
interval specified in the Suppressed Messages property will be written applicable.)
to the queue manager error log only once. The value must be 1 -
86400 seconds. The default value is 30 seconds.
Custom The Custom parameter is included for IBM use only, reserved CUSTOM
for the configuration of new features before separate properties
have been introduced. The possible values are a list of zero or
more properties-value pairs, in MQSC-style syntax, separated by
at least one space.
The property names and values are case-sensitive, and must
be specified in uppercase. The values can contain spaces,
parentheses and single-quotes (which must be escaped with
another single-quote). Other characters, including nested
parentheses (), can be included by enclosing them in two single-
quotes on either side. Examples of valid syntax are:
• CUSTOM('')
• CUSTOM('A(B)')
• CUSTOM('C(D) E(F)')
• CUSTOM('G(5000) H(''9.20.4.6(1415)'')')
The queue manager parses the value, but if the string cannot be
parsed according to these rules, or if it contains properties or
values that are not recognized, the queue manager ignores the
errors.

320 IBM MQ Explorer

Property Meaning MQSC
parameter
(z/OS only) When a queue manager makes an MQOPEN call SQQMNAME
Opening
for a shared queue and the queue manager that is specified
shared queues
in the ObjectQmgrName parameter of the MQOPEN call is
in the same queue sharing group as the processing queue
manager, the Opening shared queues property specifies
whether the ObjectQmgrName is used or whether the processing
queue manager opens the shared queue directly. Use the
queue manager specified in ObjectQmgrName means that the
ObjectQmgrName is used, and the appropriate transmission
queue is opened; Use the local queue manager means that
the processing queue manager opens the shared queue directly,
which can reduce the traffic in your queue manager network.
(z/OS only) Specify whether intra-group queuing is used. To use IGQ
Intra-group
the shared transmission queue (SYSTEM.QSG.TRANSMIT.QUEUE)
queuing
when queue managers within a queue sharing group exchange
messages, click Enabled; to use non-shared transmission queues
and channels when queue managers within a queue sharing
group exchanged messages, click Disabled. If you disable intra-
group queuing, the same mechanism for message transfer is used
as when the queue managers are not part of a queue sharing
group.
(z/OS only) Specify a user identifier to be used by the IGQ agent IGQUSER
IGQ user ID
to establish authority to put messages to a destination queue.
The queue manager must be a member of a queue sharing group
to use this property. To specify that the user ID of the receiving
queue manager within the queue sharing group is to be used as
the IGQ user ID, leave the field blank.
(z/OS only) Specify the type of authority checking and, therefore, IGQAUT
IGQ
the user identifiers, to be used by the IGQ agent. This establishes
authority check type
the authority to put messages to the destination queue. The
queue manager must be a member of a queue sharing group to
use this property. To specify that the default user ID is used to
establish authority, click Default; to specify that the IGQ user ID
and the ALT user ID is used to establish authority, click Alternate
or IGQ; to specify that only the IGQ user ID is used to establish
authority, click Only IGQ; to specify that the user ID from the
UserIdentifier field in the message descriptor, of a message on
the SYSTEM.QSG.TRANSMIT.QUEUE queue, is used to establish
authority, click Context.
(z/OS only) Type the approximate value in seconds that specifies EXPRYINT
Expiry
how often queues are scanned to discard expired messages. the
interval
value must be 1 - 99999999. The minimum scan interval is 5
seconds, even if you specify a lesser value 1 - 4. Specify an
interval of 0 to ensure that the queues are not scanned; this is
the default value.
(z/OS only) Specify whether the queue manager supports security SCYCASE
Security
profile names in mixed case or in uppercase only. Select Mixed
profile case
to specify that security names can be in uppercase or in mixed
case. Select Upper to specify that security profile names must be
in uppercase. This is the default value.

Introduction to IBM MQ Explorer 321

Property Meaning MQSC
parameter
(z/OS only) This property can have a value of either Enabled or GROUPUR
Group units
Disabled. The value can only be set to Enabled if the system has
of recovery
been configured correctly, otherwise an error is returned. Enabled
is the default value.
The system programmer must use the code specified to identify
which configuration check failed. They must then take corrective
action and then reissue the ALTER QMGR command.
When you enable group units of recovery (GROUPUR support) a
number of configuration checks are performed to ensure that the
configuration steps have been completed. You cannot enable this
support if any of these checks fail.
These checks are also performed when the queue manager starts
if the GROUPUR queue manager property is enabled. If one of
these checks fails during startup, then group units of recovery will
be disabled until you correct the error and re-enable the GROUPUR
queue manager property.
For more information, see CSQM507E.

(z/OS only) Specifies the action taken when the queue manager CFCONLOS
Loss of
loses connectivity to the administration structure or any CF
coupling facility
structures with CFCONLOS set to As queue manager. The two
connectivity
options are:
• Terminate. This is the default value. The queue manager
terminates when connectivity to CF structures is lost.
• Tolerate. The queue manager tolerates a loss of connectivity
to CF structures and does not terminate. Tolerate can only
be set if all queue managers in the queue sharing group are at
command level 710 or later.

Exits (Multiplatforms)

The following table lists the properties that you can set on the Exits page of the Queue Manager
properties dialog. To configure the queue manager to run user exits, edit the properties on the Exits
page. The properties on the Exits page relate to stanzas in the configuration files.

Property Meaning Stanza key

*Exit default path If the queue manager is 32 bit, type the path to the location in ExitsDefaultPa
which exits for this queue manager are stored by default. th
*Exit default path (64 bit) If the queue manager is 64 bit, type the path to the location in ExitsDefaultPa
which exits for this queue manager are stored by default. th64
*Local API Exits Add details of the local API exits that you want to use with this ApiExitLocal
queue manager.
*Name Specifies the descriptive name of the API exit that is passed to Name
the API exit in the ExitInfoName field of the MQAXP structure.
This name must be unique and is limited to a length of 48
characters, and must contain only those characters that are valid
for the name of IBM MQ objects, such as queue names.

322 IBM MQ Explorer

Property Meaning Stanza key
*Type Specifies the type of exit: queue manager, or override. (Not a
separate
stanza key.)
*Sequence This property is an unsigned numeric value that defines the Sequence
sequence in which this API exit is called in comparison with
other API exits. An API exit with a low sequence number is called
before another API exit with a higher sequence number. The order
in which different API exits with the same sequence number are
called is undefined. It is perfectly valid for there to be gaps in the
sequence numbers of the API exits defined for a queue manager.
*Module Specifies the module that contains the code for the API exit. If Module
this field contains the full path name of the module it is used as is.
If this field contains just the module name, the module is located
using the same method as channel exits; that is, using the value
in the Exit default path field on the Exits page of the queue
manager properties dialog.
*Function Specifies the name of the function entry-point into the module Function
that contains the code for the API exit. This entry-point is the
MQ_INIT_EXIT function. The length of this field is limited to
MQ_EXIT_NAME_LENGTH.
*Data If this property is specified, leading and trailing blanks are Data
removed, the remaining string is truncated to 32 characters, and
the result is passed to the exit in the ExitData field of the MQAXP
structure. If this property is not specified, the default value of 32
blanks is passed to the exit in the ExitData field of the MQAXP
structure.

Cluster
The following table lists the properties that you can set on the Cluster page of the Queue Manager
properties dialog. To configure the cluster properties of the queue manager, edit the properties on the
Cluster page.

Property Meaning MQSC

parameter
Cluster membership Read-only. This table lists the names of the clusters to which the (Not
queue manager belongs. applicable.)

Introduction to IBM MQ Explorer 323

Property Meaning MQSC
parameter
Cluster workload exit The exit is called when a message is put on a cluster queue. Type CLWLEXIT
the name of the cluster workload exit:

• On AIX and Linux systems, use the

format libraryname(functionname). The maximum length
is 128 characters.

• On Windows, use the format

dllname(functionname), where dllname is specified
without the .dll suffix. The maximum length is 128
characters.

• On z/OS, type the load module name. The

maximum length is 8 characters.

• On IBM i, use the format progname libname,

where progname occupies the first 10 characters, and
libname occupies the second 10 characters. Add spaces at
the end of shorter names to bring them up to 10 characters. The
maximum length is 20 characters.

Cluster workload data Type the data to be passed to the cluster workload exit when the CLWLDATA
exit is called. The maximum length of the data is 32 characters.
Cluster workload length Type the maximum number of bytes of message data that is CLWLLEN
passed to the cluster workload exit:

• On Windows, type a number from 0 to 104857600

(100 MB).
• On other platforms, type a number from 0 to 999999999.

Max outbound cluster Type the maximum number of outbound cluster channels. For CLWLMRUC
channels more information, see Distributed queuing and clusters.
Cluster workload mode The cluster workload exit, CLWL, allows you to specify which CLWLMode
cluster queue in the cluster is to be opened in response to an
MQI call (for example MQOPEN or MQPUT). The default value
is SAFE, which means that the CLWL exit is run in a separate
process to the queue manager so that if there is a problem, the
integrity of the queue manager is preserved. However, running the
CLWL exit as a separate process can have a detrimental effect on
performance. To improve performance by running the CLWL exit
in the same process as the queue manager, click FAST. Use FAST
mode only if you are certain that there are no problems with your
CLWL exit because if there is a problem in FAST mode, the queue
manager fails and the queue manager's integrity is at risk. The
value set for the queue manager will override the value set for the
machine-wide configuration.

324 IBM MQ Explorer

Property Meaning MQSC
parameter
CLWL use queue This property specifies whether the queue manager can choose CLWLUSEQ
from remote instances of cluster queues as well as local
instances. If the queue manager receives a message by way of
a cluster channel, the message is put on a local instance of the
cluster queue; if the queue manager receives a message locally
or by way of a non-cluster channel, and the value of this property
is Any, the message is put on either local or remote instances of
the cluster queue. To enable the queue manager to use remote
instances of cluster queues, click Any; to prevent the queue
manager using remote instances of cluster queues, click Local.
For more information, see Distributed queuing and clusters.
Default cluster The default transmission queue type that is used by clustering DEFCLXQ
transmission queue to transfer messages to other queue managers in the cluster.
Messages are transferred by cluster-sender channels.
The default value of this property is SCTQ. The
queue manager uses a single transmission queue to
transfer all cluster messages. The transmission queue is
SYSTEM.CLUSTER.TRANSMIT.QUEUE.
To send messages to each queue manager, in each cluster, using a
different transmission queue, set the value of Default cluster
transmission queue to Queue for each channel. The
queue manager automatically creates a transmission queue if
it needs one to send a message to another queue manager in
a cluster. The queue is permanent-dynamic. It is created from
the model queue SYSTEM.CLUSTER.TRANSMIT.MODEL.QUEUE.
The name of each transmission queue is
SYSTEM.CLUSTER.TRANSMIT.ChannelName. ChannelName is
the name of the cluster-sender channel that transfers messages
from the queue.

Repository
The following table lists the properties that you can set on the Repository page of the Queue Manager
properties dialog. To specify that the queue manager hosts the repository for one or more clusters, edit
the properties on the Repository page.

Property Meaning MQSC

parameter
Not a cluster full To specify that the queue manager is not a full repository for a (Not
repository cluster, select this option. applicable.)
Full repository for a To make this queue manager a full repository for just one cluster, REPOS
cluster select this option, then type the name of the cluster.
Full repository for a list of To make this queue manager a full repository for more than one REPOSNL
clusters cluster, select this option, then type the name of the cluster.

Communication
The following table lists the properties that you can set on the Communication page of the Queue
Manager properties dialog. To configure how the queue manager sends and receives messages, edit the
properties on the Communication page.

Introduction to IBM MQ Explorer 325

Property Meaning MQSC
parameter
Default transmission Type the name of the default transmission queue on which DEFXMITQ
queue messages that are destined for a remote queue manager are put if
there is no other suitable transmission queue defined. The queue
named must be a local transmission queue, but not the cluster
transmission queue.
Channel auto definition To enable receiver- and server-connection channels to be defined CHAD
automatically, click Enabled; to prevent receiver- and server-
connection channels being defined automatically, click Disabled.
Cluster-sender channels can always be defined automatically,
regardless of the setting of this property.
Channel auto definition The exit is called when an inbound request for an undefined CHADEXIT
exit receiver, server-connection, or cluster-sender channel is received.
The exit is also called when starting a cluster-receiver channel.
Type the name of the channel auto-definition exit:

• On AIX and Linux, use the format

libraryname(functionname). The maximum length is 128
characters.

• On Windows, use the format

dllname(functionname), where dllname is specified with
the .dll suffix. The maximum length is 128 characters.

• On IBM i, use the format progname libname,

where progname occupies the first 10 characters and libname
occupies the second 10 characters. Add spaces at the end of
shorter names to bring them up to 10 characters. The maximum
length is 20 characters.

• On z/OS, type the load module name. The

maximum length is eight characters.

Channel authentication To exercise more precise control over the access granted to CHLAUTH
connecting systems at a channel level, you can use channel
authentication records. IBM MQ queue managers are created
using channel authentication by default.
Reverse lookup of host Controls whether reverse lookup of the host name from a Domain REVDNS
name Name Server (DNS) is done for the IP address from which a
channel has connected. This property only has an effect on
channels using a transport type (TRPTYPE) of TCP.
If you are using channel authentication rules with
CHLAUTH(ENABLED) and you have defined any rules that use a
DNS host name in the ADDRESS field of the rule, these rules will
never match an inbound channel if REVDNS is set to DISABLED.
Changes to this parameter take effect the next time a channel
starts up. Channels that have already obtained host name
information by reverse looking up an IP address retain this
information.

IP address version To specify that the queue manager uses the IPv6 protocol, click IPADDRV
IPV6; to specify that the queue manager uses the IPv4 protocol,
click IPV4.

326 IBM MQ Explorer

Property Meaning MQSC
parameter
Activity recording If a queue manager application performs some work on behalf of ACTIVREC
a message in which activity reports were requested, the queue
manager can generate an activity report. You can use this activity
report to work out where the message went in the queue manager
network. To prevent queue manager applications generating
activity reports, click Disabled; to enable queue manager
applications to generate activity reports, click Message or Queue.
If you click Message, a queue manager application that generates
an activity report puts the report on the queue that the originator
of the message requested in the ReplyToQ and ReplyToQMgr
fields of the message descriptor; if you click Queue, a queue
manager application that generates an activity report puts the
report on the system queue SYSTEM.ADMIN.ACTIVITY.QUEUE. If
you make changes to this property, you must stop and restart any
channels to which you want the changes to apply.
Trace-Route recording You can use Trace-Route messages to determine the routes that ROUTEREC
messages take through a queue manager network. Participating
queue manager applications can generate information about
the route and put the information in activity reports. The
queue manager applications can also add the information to
the Trace-Route message itself, depending on the options set
in the Trace-Route message. The Trace-Route message can
then accumulate chronological information about the route.
The Activity recording property specifies on which queue
the activity reports are put. The Trace-route recording
property controls the accumulation of information in the Trace-
Route message itself. To prevent the queue manager appending
route information within the Trace-Route message and from
returning information in reply messages, click Disabled. To
enable queue manager applications to add the route information
to the Trace-Route message, click Message or Queue. If you
click Message and a queue manager application generates a
reply message containing the accumulated route information
from the Trace-Route message, the queue manager application
puts the reply message on the queue that the originator of
the message requested in the ReplyToQ and ReplyToQMgr fields
of the message descriptor; if you click Queue and a queue
manager application generates a reply message containing the
accumulated route information from the Trace-Route message,
the queue manager application puts the reply message on
the system queue SYSTEM.ADMIN.TRACE.ROUTE.QUEUE. If you
make changes to this property, you must stop and restart any
channels to which you want the changes to apply.

Events
The following table lists the properties that you can set on the Events page of the Queue Manager
properties dialog. To configure the queue manager to generate events in response to certain criteria, edit
the properties on the Events page.

Introduction to IBM MQ Explorer 327

Property Meaning MQSC
parameter
Authority events When an application tries to open a queue for which the AUTHOREV
application does not have the required authority, the queue
manager can generate an authorization event message. To
generate authorization event messages, click Enabled; to prevent
the queue manager generating authorization event messages,
click Disabled.
Inhibit events When an application tries to put a message on a queue that INHIBTEV
is put-inhibited, or to get a message from a queue that is
get-inhibited, the queue manager can generate an inhibit event
message. To generate inhibit event messages, click Enabled; to
prevent the queue manager generating inhibit event messages,
click Disabled.
Local events When an application or the queue manager has not been able to LOCALEV
access an object, for example because the object has not been
defined, the queue manager can generate a local event message.
To generate local event messages, click Enabled; to prevent the
queue manager generating local event messages, click Disabled.
Remote events When an application or the queue manager cannot access a REMOTEEV
queue on another queue manager, for example the transmission
queue is not correctly defined, the queue manager can generate a
remote event message. To generate remote event messages, click
Enabled; to prevent the queue manager generating remote event
message, click Disabled.
Start and stop events When a queue manager starts, or has been requested to stop STRSTPEV
or quiesce, the queue manager can generate a start and stop
event message. To generate start and stop event messages, click
Enabled; to prevent the queue manager generating start and stop
messages, click Disabled.

z/OS supports only start.

Performance events When a resource reaches a threshold condition, for example a PERFMEV
queue depth limit has been reached, the queue manager can
generate a performance event message. To generate performance
event messages, click Enabled; to prevent the queue manager
generating performance event messages, click Disabled.
Command events When an MQSC command or PCF command is executed CMDEV
successfully, the queue manager can generate command event
messages. To generate command event messages, click Enabled;
to prevent the queue manager generating command events,
click Disabled; to generate command event messages except
DISPLAY MQSC commands and Inquire PCF commands, click
No Display.
Channel events When the queue manager detects certain conditions on a CHLEV
channel, for example the channel starts or stops, the queue
manager can generate channel event messages. To generate
channel event messages, click Enabled; to prevent the queue
manager generating channel event messages, click Disabled.

328 IBM MQ Explorer

Property Meaning MQSC
parameter
Channel auto definition When a channel is automatically generated, the queue manager CHADEV
events can generate a channel auto-definition event message. To
generate channel auto-definition event messages, click Enabled;
to prevent the queue manager generating channel auto-definition
event messages, click Disabled.
SSL events When a channel that uses TLS security fails to establish an SSLEV
TLS connection, the queue manager can generate an SSL event
message. To generate SSL event messages, click Enabled; to
prevent the queue manager generating SSL event messages, click
Disabled.
Configuration events When an object is created or modified, the queue manager CONFIGEV
can generate a configuration event message. To generate
configuration event messages, click Enabled; to prevent the
queue manager generating configuration event messages, click
Disabled.
(z/OS only) When an IMS bridge starts or stops, the queue BRIDGEEV
Bridge
manager can generate a bridge event message. To generate
events
bridge event messages, click Enabled; to prevent the queue
manager generating bridge event messages, click Disabled.
Logger events When a queue manager is configured to use linear logging, the LOGGEREV
queue manager can be configured to generate a logger event
message when changes are written to the IBM MQ recovery log.
To generate logger event messages, click Enabled; to prevent
the queue manager generating logger event messages, click
Disabled.

SSL
The following table lists the properties that you can set on the SSL page of the Queue Manager properties
dialog. To configure the queue manager and its channels to use TLS security, edit the properties on the
SSL page.

Property Meaning MQSC

parameter
Key repository Type the full path to the key repository for the queue manager. SSLKEYR
Certificate label CERTLABL
CERTQSGL

Queue
sharing group certificate
label

Introduction to IBM MQ Explorer 329

Property Meaning MQSC
parameter
Revocation namelist Type the name of the revocation namelist. The revocation SSLCRLNL
namelist can contain a mixture of authentication information
objects from either, or both, of the following types:
• CRL LDAP authentication information objects, which store
connection information for LDAP servers that contain
Certification Revocation Lists (CRLs).
• Online Certificate Status Protocol (OCSP) authentication
information objects, which store connection information for
OCSP responders.

Cryptographic hardware To configure your cryptographic hardware, click Configure In the SSLCRYP
Cryptographic hardware settings dialog, enter the details of your
cryptographic hardware.
SSL Reset Count Type the number of unencrypted bytes, from 0 to 999999999, SSLRKEYC
that are sent and received within an TLS conversation before the
secret key is renegotiated. A value of 0 means that the secret
key is never renegotiated. The number of bytes includes control
information that is sent by the message channel agent (MCA).
If the value of this property is greater than 0 and the value of
the Heartbeat interval property in the Channel properties is
greater than 0, the secret key is also renegotiated before message
data is sent or received following a channel heartbeat.
SSL FIPS required To specify whether only FIPS-certified cryptographic algorithms SSLFIPS
are to be used (if the cryptography is performed in IBM MQ
rather than cryptographic hardware), click Yes. To specify that
any cryptographic algorithm can be used, click No.
OCSP authentication The OCSP authentication setting dictates the outcome of a N/A
connection in the event of an 'Unknown' response from the OCSP
call.
• Required: IBM MQ rejects the connection.
• Optional: The connection is allowed to succeed.
• Warn: The connection is also allowed to succeed and IBM MQ
issues a message of type AMQ9717 into the error logs.

OCSP check extensions The OCSP check extensions property controls whether the OCSP N/A
server details in AuthorityInfoAccess certificate extensions, are
used to perform a digital revocation check. There are 2 possible
values for the property:
• Yes: A digital certificate revocation check is performed. This is
the default value.
• No: A digital certificate revocation check is not performed.

SSL HTTP proxy name The SSL HTTP proxy name is either the host name or network N/A
address of the HTTP proxy server which is to be used by GSKit for
OCSP checks. This address can optionally be followed by a port
number, enclosed in parentheses. If you do not specify the port
number, the default HTTP port, 80, is used.

330 IBM MQ Explorer

Property Meaning MQSC
parameter
Suite B strength The Suite B strength property controls whether Suite B encryption SUITEB
is used. There are four possible values for the property:
• 128-bit
• 192-bit
• none
• 128-bit and 192-bit

Certificate validation The certificate validation policy property controls which TLS CERTVPOL
policy certificate validation policy is used to validate digital certificates
received from remote partners. There are two possible values for
the property:
• ANY
• RFC5280
Changes to this property take effect only after a refresh security
command has been issued. For information about how to refresh
security in the IBM MQ Explorer, see “Refreshing TLS security” on
page 168.

Statistics
The following table lists the properties on the Statistics page of the Queue Manager properties dialog.
The Statistics page displays the information about the history of the queue manager. You cannot edit any
of these properties.

Property Meaning MQSC

parameter
Creation date Read-only. This is the date on which the queue was created. CRDATE
Creation time Read-only. This is the time at which the queue was created. CRTIME
Alteration date Read-only. This is the date on which the queue's properties were ALTDATE
last altered.
Alteration time Read-only. This is the time at which the queue's properties were ALTTIME
last altered.
QMID Read-only. This is the internally-generated unique name of the QMID
queue manager.

Online monitoring
The following table lists the properties that you can set on the Online monitoring page of the Queue
Manager properties dialog. To collect data about the current performance of the queue manager's
channels and queues, edit the properties on the Online monitoring page.

Introduction to IBM MQ Explorer 331

Property Meaning MQSC
parameter
Channel monitoring This property specifies whether to collect online monitoring data MONCHL
about the current performance of channels hosted by the queue
manager. To switch off online monitoring data collection for the
queue manager's channels that have the value Queue Manager
in their Channel monitoring property, click Off; to switch off
online monitoring data collection for all the queue manager's
channels regardless of the setting of the channel's Channel
monitoring property, click None. To specify a low rate of data
collection, with a minimal effect on system performance, for
channels that have the value Queue Manager in their Channel
monitoring property, click Low; to specify a moderate rate of
data collection, with limited effect on system performance, for
channels that have the value Queue Manager in their Channel
monitoring property, click Medium; to specify a high rate of
data collection, with a likely effect on system performance, for
channels that have the value Queue Manager in their Channel
monitoring property, click High.
Queue monitoring This property specifies whether to collect online monitoring data MONQ
about the current performance of queues hosted by the queue
manager. To switch off online monitoring data collection for the
queue manager's queues that have the value Queue Manager in
their Queue monitoring property, click Off; to switch off online
monitoring data collection for all the queue manager's queues
regardless of the setting of the queue's Queue monitoring
property, click None. To specify a low rate of data collection, with
a minimal effect on system performance, for queues that have the
value Queue Manager in their Queue monitoring property,
click Low; to specify a moderate rate of data collection, with
limited effect on system performance, for queues that have the
value Queue Manager in their Queue monitoring property,
click Medium; to specify a high rate of data collection, with a
likely effect on system performance, for queues that have the
value Queue Manager in their Queue monitoring property,
click High.
Auto CLUSSDR monitoring This property specifies whether to collect online monitoring data MONACLS
about the current performance of auto-defined cluster-sender
channels. To inherit from the value of the queue manager's
Channel monitoring property, click Queue Manager; to
switch off data collection for auto-defined cluster-sender
channels on the queue manager, click None; to specify a low rate
of data collection with a minimal effect on system performance,
click Low (the data that is collected is unlikely to be the most
current); to specify a moderate rate of data collection with
limited effect on system performance, click Medium; to specify
a high rate of data collection with a likely effect on system
performance, click High (the data that is collected is the most
current available).

332 IBM MQ Explorer

Property Meaning MQSC
parameter
Activity trace override This property specifies whether applications can override the ACTVCONO
value of the queue manager property ACTVTRC. Valid values are
Enabled and Disabled. When Enabled is selected, applications
can override the settings of the ACTVTRC parameter by using
the options field of the MQCNO structure of the MQCONNX API
call. When Disabled is selected, applications cannot override the
settings of the ACTVTRC parameter. Disabled is the default value
for this parameter. Changes to this parameter are effective for
connections to the queue manager that occur after the change.
This parameter is valid only on Multiplatforms.
Activity trace This property specifies whether MQI application activity tracing ACTVTRC
information is to be collected. Valid values are On and Off.
When On is selected, MQI application activity tracing information
collection is enabled. If queue manager property ACTVCONO is
set to Enabled, the value of this parameter can be overridden
using the options field of the MQCNO structure. When Off is
selected, MQI application activity tracing information collection
is disabled. Off is the default value for this parameter. Changes
to this parameter are effective for connections to the queue
manager that occur after the change. This parameter is valid only
on Multiplatforms.

Statistics monitoring (Multiplatforms)

The following table lists the properties that you can set on the Statistics monitoring page of the Queue
Manager properties dialog. To collect statistical data on the activity of the queue manager, edit the
properties on the Statistics monitoring page.

For z/OS Statistics monitoring settings, see “Statistics monitoring (z/OS)” on page 350.

Property Meaning MQSC

parameter
MQI Statistics To collect MQI statistics data for the queue manager, click On; to STATMQI
prevent MQI statistics monitoring data collection for the queue
manager, click Off.
Queue Statistics This property specifies whether to collect statistics data about STATQ
the activity of queues hosted by the queue manager. To switch
on statistics data collection for the queue manager's queues,
click On; to switch off statistics data collection for the queue
manager's queues that have the value Queue Manager in
their Queue statistics property (see Queue properties), click
Off; to switch off statistics data collection for all the queue
manager's queues regardless of the setting of the queue's Queue
statistics property, click None.

Introduction to IBM MQ Explorer 333

Property Meaning MQSC
parameter
Channel Statistics This property specifies whether to collect statistics data about STATCHL
the activity of channels hosted by the queue manager. To
switch off statistics data collection for the queue manager's
channels that have the value Queue Manager in their Channel
statistics property (see Channel properties), click Off; to
switch off statistics data collection for all the queue manager's
channels regardless of the setting of the channel's Channel
statistics property, click None. To specify a low rate of data
collection, with a minimal effect on system performance, for
channels that have the value Queue Manager in their Channel
statistics property, click Low; to specify a moderate rate of
data collection, with limited effect on system performance, for
channels that have the value Queue Manager in their Channel
statistics property, click Medium; to specify a high rate of
data collection, with a likely effect on system performance, for
channels that have the value Queue Manager in their Channel
statistics property, click High.
Auto CLUSSDR Statistics This property specifies whether to collect statistics data about STATACLS
the activity of auto-defined cluster-sender channels. To inherit
from the value of the queue manager's Channel statistics
property, click Queue Manager; to switch off data collection
for auto-defined cluster-sender channels on the queue manager,
click None; to specify a low rate of data collection, click Low (the
data that is collected is unlikely to be the most current); to specify
a moderate rate of data collection, click Medium; to specify a high
rate of data collection, click High (the data that is collected is the
most current available).
Statistics Interval Type the interval, in seconds, between writing the statistics STATINT
monitoring data to the monitoring queue. The default value is
1800 seconds (30 minutes).

Accounting monitoring (Multiplatforms)

The following table lists the properties that you can set on the Accounting monitoring page of the Queue
Manager properties dialog. To collect data about the activity of a connection, edit the properties on the
Accounting monitoring page.

For z/OS Account monitoring settings, see Accounting monitoring on z/OS.

Property Meaning MQSC

parameter
MQI accounting To collect MQI accounting data for the queue manager, click On; ACCTMQI
to prevent MQI accounting monitoring data collection for the
queue manager, click Off.

334 IBM MQ Explorer

Property Meaning MQSC
parameter
Queue accounting This property specifies whether to collect accounting data about ACCTQ
the activity of connections for queues hosted by the queue
manager. To enable accounting data collection for the queue
manager's queues, click On; to disable accounting data collection
for the queue manager's queues that have the value Queue
Manager in their Queue accounting property (see Queue
properties), click Off; to disable accounting data collection for
all the queue manager's queues regardless of the setting of the
queue's Queue accounting property, click None.
Accounting interval Type the interval, in seconds, between writing the accounting ACCTINT
monitoring data to the monitoring queue. The default value is
1800 seconds (30 minutes).
Accounting conn override Applications can override the MQI accounting property and ACCTCONO
the Queue accounting property using the Connect options
in MQCONNX calls. To enable applications to override the
properties, click Enabled; to prevent applications overriding the
properties, click Disabled.

Log (Multiplatforms)

The following table lists the properties that you can set on the Log page of the Queue Manager properties
dialog. To configure the log settings for the queue manager, edit the properties on the Log page. The
properties on the Log page relate to stanzas in the configuration files.

For z/OS log settings, see Log (z/OS only).

Property Meaning Stanza key

*Log type Read-only. This property shows the type of logging that the queue LogType
manager uses. You cannot change the type of logging after the
queue manager is created.
*Log path Read-only. This property shows the location of the queue LogDefaultPat
manager's logs. You cannot change the value of the Log path h
property after the queue manager is created.
*Log file pages Read-only. This property shows the number of 4 KB pages in the LogFileSize
log file. For example, if the value is 256, the file size is 1 MB.
The default value is 4096, the file size 16 MB.

Introduction to IBM MQ Explorer 335

Property Meaning Stanza key
*Log primary files These are the log files that are allocated when the queue LogPrimaryFile
manager is created. s

On AIX and Linux, type the number,

from 2 to 510, of primary log files. The default value is 3. The total
number of primary and secondary log files must not exceed 511
and must not be less than 3.

On Windows, type the number, from 2 to 254, of

primary log files. The default value is 3. The total number of
primary and secondary log files must not exceed 255 and must
not be less than 3.
The value is examined when the queue manager is created or
started. You can change the value after the queue manager has
been created but the change is not effective until the queue
manager is restarted.

*Log secondary files These are the log files that are allocated when the primary files LogSecondary
are exhausted. Files

On AIX and Linux, type the number,

from 1 to 509, of secondary log files. The default value is 3. The
total number of primary and secondary log files must not exceed
511 and must not be less than 3.

On Windows, type the number, from 1 to 253, of

secondary log files. The default value is 3. The total number of
primary and secondary log files must not exceed 255 and must
not be less than 3.

*Log buffer pages Type the number, from 0 to 4096, of 4 KB buffer pages for writing. LogBufferPage
If you type a number from 1 to 17, the minimum of 18 (72 KB) s
is used. If you type a number from 18 to 4096, that number of
pages is used. If you type 0, the queue manager selects the size.

On Windows, for IBM WebSphere MQ 7.0 and later,

this is 512 (2048 KB).
The default value is 0 (Which the queue manager selects as 512
(2048 KB). If you change the value of this property, restart the
queue manager to apply the change.

*Log write integrity This is the method that the logger uses to reliably write log LogWriteIntegr
records. If you are using a non-volatile write cache (for example, ity
ssa write cache enabled), it is safe for the logger to write log
records in a single write, so click SingleWrite; if you need to
write log records with more integrity, click DoubleWrite to use an
additional write; if you need to write log records with complete
integrity but at the cost of performance, click TripleWrite to use
another additional write.

336 IBM MQ Explorer

Property Meaning Stanza key
Log management The method used to manage your logs. LogManagement applies LogManageme
only when LogType is LINEAR. nt
If you change the LogManagement value, the change does not
take effect until the queue manager is restarted.
There are three options.
Manual, where you manage the log extents manually. Specifying
this option means that the queue manager does not reuse or
delete log extents, even when they are no longer required for
recovery.
Automatic, where log extents are managed automatically by the
queue manager. Specifying this option means that the queue
manager is able to reuse or delete log extents as soon as they
are no longer required for recovery. No allowance is made for
archiving.
Archive, where log extents are managed by the queue manager,
but you must notify the queue manager when archiving of each
log extent is complete.
Specifying this option means that the queue manager is free to
reuse or delete a log extent, as soon as the queue manager has
been notified that an extent no longer required for recovery has
been archived.
The default value is Manual.

XA resource managers (Multiplatforms)

The following table lists the properties that you can set on the XA resource manager page of the Queue
Manager properties dialog. The XA resource manager page displays properties to edit if the queue
manager coordinates its own units of work along with database updates; for example, the name of the
resource manager (the database) and the location of the switch file, which helps IBM MQ communicate
with the database. The properties on the XA resource manager page relate to the XAResourceManager
stanza in the configuration files.

Property Meaning Stanza key

*Name Type the name of the resource manager (the database). Name
*SwitchFile Type the location of the switch file, which helps IBM MQ to SwitchFile
communicate with the database.
*XAOpenString You can type a string of data that IBM MQ passes in its calls to the XAOpenString
database manager's xa_open function. IBM MQ and the queue
manager call the xa_open function when the queue manager
starts and when you make the first call to MQBEGIN in your IBM
MQ application process. The default is a zero-length string.
*XACloseString You can type a string of data that IBM MQ passes in its calls to the XACloseString
database manager's xa_close function. IBM MQ and the queue
manager call the xa_close function when the queue manager
starts and when you make a call to MQDISC in your IBM MQ
application process, having earlier made a call to MQBEGIN. The
default is a zero-length string. It is common to have a zero-length
string.

Introduction to IBM MQ Explorer 337

Property Meaning Stanza key
*ThreadOfControl The queue manager uses this value for serialization purposes. ThreadOfContr
If the database client allows threads to call the XA functions ol
without serialization, the value for ThreadOfControl can be
THREAD. If the database client does not allow threads to call its
XA functions in this way, the value for ThreadOfControl must
be PROCESS. The default is PROCESS.

Installable services (Multiplatforms)

The following table lists the properties on the Installable services page of the Queue Manager properties
dialog. The Installable services page displays information about the installable services installed on your
computer. By default, only the authorization service, OAM, is shown. The properties on the Installable
services page relate to the Service stanza in the configuration files. For more information, see
Configuring services and components.

Property Meaning Stanza key

*Service name Read-only. This is the name of the service. Name
*Service entry points Read-only. This is the number of entry points that are defined EntryPoints
for the service, including the initialization and termination entry
points.
*Security policy Read-only. This is the security policy for the queue manager. SecurityPolicy
Default means that the default security policy is used; NTSIDs
Required means that a Windows security identifier is passed to
the OAM when performing security checks.
*ServiceComponents Read-only. This is a list of the service components installed on ServiceCompo
your computer. nents
*Name Read-only. This is the name of the component. component_na
me
*Service Read-only. This is the name of the installable service. service_name
*Data size Read-only. This is the size, in bytes, of the component data area size
passed to the component on each call. A value of 0 is used if no
component data is required.
*Module Read-only. This is the path to the module that contains the code module_name
for the component.

Channels
The following table lists the properties that you can set on the Channels page of the Queue Manager
properties dialog. To configure the behavior of the queue manager's channels, edit the properties on the
Channels page.

Channel properties for Multiplatforms

On Multiplatforms, the properties on the Channels page relate to stanzas in the configuration files. You
cannot edit this properties on remote distributed queue managers.

338 IBM MQ Explorer

Property Meaning Stanza key
*Max channels Type the maximum number of channels, from 1 to 9 999, that can MaxChannels
be current (including server-connection channels with connected
clients).

For z/OS, the value must be between 1 and 9999,

with a default value of 200.
For all other platforms, the value must be between 1 and 65535,
with a default value of 100.
On a production system, you could use, for example, the value
1000. If the value of this property is reduced, any current
channels that exceed the new limit continue to run until they stop.

*Max active channels Type the maximum number of channels that can be active at any MaxActiveCha
one time. The default is the value specified for the MaxChannels nnels
property.

For z/OS, the value must be between 1 and 9999.

For all other platforms, the value must be between 1 and 65535.

*Max initiators Type the maximum number of initiators allowed. The default and MaxInitiators
maximum value is 3.
*MQI bind type Select the type of connection that channels use to connect MQBindType
to applications. To connect using a standard connection, click
STANDARD; to connect without using an agent process, click
FASTPATH.
*Adopt new MCA This property specifies whether an orphaned MCA instance is AdoptNewMCA
adopted (restarted) when a new inbound channel request is Type
detected that matches the value of the Adopt new MCA check
property.
To adopt all channel types, type All. If a FASTPATH channel
cannot be safely ended, it is not ended and the adoption fails.
If you do not require orphaned channels to be adopted, type No.
*Adopt new MCA check This property specifies which elements are checked to determine AdoptNewMCA
whether an MCA should be adopted when a new inbound channel Check
is detected with the same name as an already active MCA. Type
one or more of the following values separated by commas:
• To check the queue manager name and the network address to
prevent your channels from being inadvertently shut down, type
ALL
• To check the network address, type ADDRESS
• To check the queue manager name, type NAME
• To check the user ID that the queue manager is running under,
type QM
• To do no checking, type NONE

*Adopt new MCA timeout Type the number of seconds, from 1 to 3600, that the new AdoptNewMCA
process must wait for the old process to end. The default value is Timeout
60.

Introduction to IBM MQ Explorer 339

Property Meaning Stanza key
*Pipeline length To allow an MCA to transfer messages using multiple threads, PipeLineLengt
type the number of concurrent threads that the channel will use. h
The default is 1; if you type a value greater than 1, it is treated as
2. Make sure that you configure the queue manager at both ends
of the channel to have a Pipeline length that is greater than 1.
Pipelining is effective only for TCP/IP channels.

Channel properties for z/OS

On z/OS, the channel properties are not configuration properties; they are just ordinary queue manager
properties like all the other properties in the z/OS queue manager properties dialog.

Property Meaning MQSC

parameter
Active channels Type the maximum number of channels, from 1 to 9999, that can ACTCHL
be active at any one time. The default value is 200. The value
must not be greater than the value of MAXCHL that defines the
maximum number of channels allowed.
Channel initiator adapters Specify the number of adapter subtasks, from 0 to 9999, to use CHIADAPS
for processing IBM MQ calls. As a guide, the ratio of adapters to
dispatchers should be approximately 8 to 5. However, if you have
only a small number of channels, you do not have to decrease
the value of this parameter from the default value. Suggested
settings: 8 (default) for a test system; 20 for a production system.
Specifying a value of 20 adapters gives greater parallelism of IBM
MQ calls. This is important for persistent messages. Specifying
fewer adapters might be better for nonpersistent messages.
Adopt new MCA check This property specifies which elements are checked to determine ADOPTCHK
whether an MCA should be adopted when a new inbound channel
is detected with the same name as an already active MCA. Enter
one or more of the following values separated by commas. To
check the queue manager name and the network address to
prevent your channels from being inadvertently shut down, click
ALL; to check the network address, click Network address; to
check the queue manager name, click Queue manager name; to
do no checking, click NONE.
Adopt new MCA type This property specifies whether an orphaned instance of an MCA ADOPTTYPE
of a particular channel type should be restarted automatically
when a new inbound channel request matching the adopt new
MCA check parameters is detected. This property is read-only.
Channel initiator Specify the number of dispatchers to use for the channel initiator, CHIDISPS
dispatchers from 1 to 9999. As a guideline, allow one dispatcher for every
50 current channels. If you have a small number of channels,
however, use the default value of 5. If you are using TCP/IP, the
maximum number of dispatchers used for TCP/IP is 100, even if
you specify a large value for this property. You are recommended
to specify a value of 20 on production systems in order to handle
up to 1000 active channels. Restart the channel initiator to apply
changes to this property.
Register with WLM This parameter is no longer used. It must have the value No. DNSWLM

340 IBM MQ Explorer

Property Meaning MQSC
parameter
Listener timer Specify the time interval, in seconds from 5 to 9999, between LSTRTMR
attempts by IBM MQ to restart the listener after an APPC
or TCP/IP failure. When the listener is restarted on TCP/IP, it
uses the same port and IP address as it used when it first
started. Changes to this property take effect for listeners that
are subsequently started. Listeners that are currently started are
unaffected by changes to this property.
Channels using LU6.2 Specify the maximum number of channels that can be current, or LU62CHL
clients that can be connected, that use the LU 6.2 transmission
protocol. Type a value from 0 to 9999. If you type 0, the LU 6.2
transmission protocol is not used. The value must not be greater
than the value of MAXCHL that defines the maximum number of
channels allowed.
Maximum channels Type the maximum number of channels, from 0 to 9999, that can MAXCHL
be current (including server-connection channels with connected
clients). The default value is 200. On a production system, you
could use, for example, the value 1000. If the value of this
property is reduced, any current channels that exceed the new
limit continue to run until they stop. The values of ACTCHL,
LU62CHL, and TCPCHL must not be greater than the maximum
number of channels.
Lowest port address Type the lowest port number, from 0 to 65535, to be used when OPORTMIN
binding outgoing channels. When all the port numbers between
the value of the Lowest port address property and the
Highest port address property have been used, outgoing
channel bind to any available port number. The default is 0,
which means that all outgoing channels bind to any available port
number. Changes to this property take effect for channels that
are subsequently started. Channels that are currently running are
unaffected by changes to this property.
Highest port address Type the highest port number, from 0 to 65535, to be used when OPORTMAX
binding outgoing channels. When all the port numbers between
the value of the Lowest port address property and the
Highest port address property have been used, outgoing
channel bind to any available port number. The default is 0,
which means that all outgoing channels bind to any available port
number. Changes to this property take effect for channels that
are subsequently started. Channels that are currently running are
unaffected by changes to this property.
Receive timeout Specify the approximate length of time that a TCP/IP channel RCVTIME
waits to receive data, including heartbeats, from its partner
before returning to the inactive state. This property applies
only to message channels, and not MQI channels. See also the
Receive timeout type property for more information.

Introduction to IBM MQ Explorer 341

Property Meaning MQSC
parameter
Receive timeout type Set this property to specify how the value of the Receive RCVTTYPE
timeout property is interpreted. To specify that the Receive
timeout value is a multiplier to be applied to the negotiated
Heartbeat interval value to determine how long a channel is
to wait, set the Receive timeout type property to Multiply,
then specify a Receive timeout value of zero or in the range
2 through 99 (if you specify zero, the channel does not time
out its wait to receive data from its partner); to specify that
Receive timeout value is the number of seconds to be added
to the negotiated Heartbeat interval value to determine
how long a channel is to wait, set Receive timeout type
to Add, then specify a Receive timeout value in the range 1
through 999999; to specify that the Receive timeout value is
the number of seconds that the channel is to wait, set Receive
timeout type to Equal, then specify an Receive timeout
value in the range zero through 999999 (if you specify zero,
the channel does not time out its wait to receive data from its
partner).
Minimum receive timeout Type the minimum length of time, in seconds from 0 to 999999, RCVTMIN
that a TCP/IP channel waits to receive data, including heartbeats,
from its partner before returning to an inactive state. This
property applies only to message channels, and not to MQI
channels. If you use the Receive timeout type property
to specify that the TCP/IP channel wait time is relative to the
negotiated value of the channel's Heartbeat interval value
and the resultant value is less than the value of this property, the
value of this property is used.
Channels using TCP Type the maximum number of channels that can be current, or TCPCHL
clients that can be connected, that use the TCP/IP transmission
protocol. Type a value from 0 to 9 999 (although note that TCP/IP
might not support as many as 9 999 channels). If you type 0,
the TCP/IP transmission protocol is not used. The value must not
be greater than the value of MAXCHL that defines the maximum
number of channels allowed.
TCP keepalive Specify whether the Keepalive facility is used to check that the TCPKEEP
other end of the connection is still available. If it is not available,
the channel is closed. To specify that the Keepalive facility is not
to be used, click No; to specify that the Keepalive facility is to
be used as specified in the TCP profile configuration data set,
click Yes (the interval is specified in the Keepalive Interval
property on the Extended page of the Channel properties).
TCP stack type To specify that the channel initiator uses only the TCP/IP address TCPSTACK
space that is specified in the TCP name property, click Single; to
specify that the channel initiator can use multiple TCP/IP address
spaces, and the default value is the value of the TCP name
property, click Multiple.

342 IBM MQ Explorer

Property Meaning MQSC
parameter
Channel initiator trace To specify that the channel initiator trace starts automatically, TRAXSTR
auto start click Yes; to specify that the channel initiator trace does not start
automatically, click No. Changes to this parameter take effect
when the channel initiator is restarted. If you need to start or stop
channel initiator trace without restarting the channel initiator, use
the Trace dialog after the channel initiator has started. To open
the Trace dialog, in the Navigator view, right-click IBM MQ, then
click Trace
Channel initiator trace Type the size, in megabytes from 2 to 2048, of the channel TRAXTBL
table size initiator's trace data space. Note that changes to this property
take effect immediately; any existing trace table contents are
lost. When you use large z/OS data spaces, ensure that sufficient
auxiliary storage is available on your system to support any
related z/OS paging activity. You might also need to increase the
size of your SYS1.DUMP data sets.
DNS group name This parameter is no longer used. DNSGROUP
LU group name Type the generic LU name to be used by the LU 6.2 listener that LUGROUP
handles inbound transmissions for the queue sharing group. The
maximum length of this parameter is 8 characters. If this name is
blank, the listener cannot be used. Changes to this property take
effect for listeners that are subsequently started. Listeners that
are currently started are unaffected by changes to this property.
LU name Type the name of the LU to use for outbound LU 6.2 LUNAME
transmissions. Set this to be the same as the name of the LU to
be used by the listener for inbound transmissions. The maximum
length of this parameter is 8 characters. If this name is blank, the
APPC/MVS default LU name should be used. This is variable, so
the LU name property should always be set if you are using LU
6.2.
LU6.2 member name Type the suffix of the APPCPM member of SYS1.PARMLIB. This
suffix suffix nominates the LUADD for this channel initiator.
TCP name Type the name of either the only, or the default, TCP/IP system TCPNAME
to be used, depending on the value of the TCP stack type
property. This is the name of the z/OS UNIX System Services
stack for TCP/IP, as specified in the SUBFILESYSTYPE NAME
parameter in the BPXPRMxx member of SYS1.PARMLIB. The
default value is TCPIP. The maximum length of this parameter
is eight characters. Changes to this parameter take effect when
the channel initiator is restarted.
Channel initiator service This parameter is reserved for use by IBM. CHISERVP
parm

TCP (Multiplatforms)

The following table lists the properties that you can set on the TCP page of the Queue Manager properties
dialog. If the queue manager uses the TCP/IP transport protocol to communicate with other queue
managers, edit the properties on the TCP page. The properties on the TCP page relate to stanzas in the
configuration files.

Introduction to IBM MQ Explorer 343

Property Meaning Stanza key
*TCP port Type the port number for TCP/IP sessions. The default is 1414. Port
The TCP port setting sets the qm.ini TCP port stanza for the queue
manager. This is used to control the two following things:
1. A channel with a CONNAME that does not specify a port
number uses this port number.
2. The command: runmqlsr -t tcp -m YOUR_QM_NAME uses
this port number where YOUR_QM_NAME is the name of your
queue manager.

*TCP library 1 Type the name of the TCP/IP socket's DLL. The default is Library1
WSOCK32.
*TCP library 2 If there are two TCP/IP sockets, type the name of the second Library2
TCP/IP socket's DLL; if there is only one TCP/IP socket, type the
same name as for the TCP library 1 property. The default is
WSOCK32.
*TCP keepalive TCP can check periodically that the other end of the connection KeepAlive
is still available. If the connection is not still available, the
connection is closed. To configure TCP to perform these checks,
click YES; to prevent TCP performing these checks, click NO. The
default is YES.
*TCP listener backlog Type the maximum number of outstanding connection requests. ListenerBackL
The default value is -1 which resolves to the default value on the og
operating system.

The default is 100 on Windows and

Linux (x86 and x86-64 platforms).

LU6.2 (Multiplatforms)

The following table lists the properties that you can set on the LU6.2 page of the Queue Manager
properties dialog. If the queue manager uses the LU 6.2 transport protocol to communicate with other
queue managers, edit the properties on the LU6.2 page. The properties on the LU6.2 page relate to
stanzas in the configuration files.

Property Meaning Stanza key

*LU6.2 TP name Type the TP name to start on the remote site. TPName
*LU6.2 library 1 Type the name of the APPC DLL. The default is WCPIC32. Library1
*LU6.2 library 2 If there are two APPCs, type the name of the second APPC DLL; Library2
if there is only one APPC, type the same name as for the LU6.2
library 1 property. The default is WCPIC32.
*LU6.2 local LU Type the name of the logical unit to use on local systems. LocalLU

NetBIOS (Multiplatforms)

The following table lists the properties that you can set on the NetBIOS page of the Queue Manager
properties dialog. If the queue manager uses the NetBIOS transport protocol to communicate with other

344 IBM MQ Explorer

 queue managers, edit the properties on the NetBIOS page. The properties on the NetBIOS page relate to
stanzas in the configuration files.

Property Meaning Stanza key

*NetBIOS local name Type the name by which this computer will be known on the local LocalName
area network (LAN).
*NetBIOS number of Type the number of sessions to allocate. The default is 1. NumSession
sessions
*NetBIOS number of Type the number of names to allocate. The default is 1. NumNames
names
*NetBIOS adapter number Type the number of the LAN adapter to use. The default is 0. AdapterNum
*NetBIOS number of Type the number of commands to allocate. The default is 1. NumCommand
commands s
*NetBIOS library 1 Type the name of the NetBIOS DLL. The default is NETAPI32. Library1

SPX (Multiplatforms)

The following table lists the properties that you can set on the SPX page of the Queue Manager
properties dialog. If the queue manager uses the SPX transport protocol to communicate with other
queue managers, edit the properties on the SPX page. The properties on the SPX page relate to stanzas in
the configuration files.

Property Meaning Stanza key

*SPX socket Type the SPX socket number in hex. The default is SE86. Socket
*SPX library 1 Type the name of the SPX DLL. The default is WSOCK32. Library1
*SPX library 2 If there is a second SPX, type the name of the second SPX DLL; Library2
if there is only one SPX, type the same name as for the SPX
library 1 property. The default is WSOCK32.
*SPX keepalive SPX can check periodically that the other end of the connection KeepAlive
is still available. If the connection is not still available, the
connection is closed. To configure SPX to perform these checks,
click YES; to prevent SPX performing these checks, click NO. The
default is YES.
*SPX board number Type the number of the LAN adapter to use. The default is 0. BoardNum

Publish/Subscribe
The following table lists the properties that you can set on the Publish/Subscribe page of the Queue
Manager properties dialog. The Publish/Subscribe page replaces the cfgmqbrk application that was
supplied with previous versions of IBM MQ. To configure the queue manager for publish/subscribe
messaging, edit the properties on the Publish/Subscribe page. The properties on the Publish/Subscribe
page relate to stanzas in the configuration files. For more information about the individual stanzas, see
Configuring services and components.

Introduction to IBM MQ Explorer 345

Property Meaning MQSC
Parameter
Publish/Subscribe mode The Publish/Subscribe mode is used to allow coexistence with PSMODE
Publish/Subscribe engines in earlier versions of the product. The
three options are:
Compatibility which means that the V7 Publish/Subscribe
engine is enabled, but the queued Publish/Subscribe interface is
disabled. This means that the V7 Publish/Subscribe engine can
coexist with the existing Publish/Subscribe engines. This is the
default value for existing queue managers.
Enable which means that the V7 Publish/Subscribe engine is
enabled and the queued Publish/Subscribe interface is enabled.
This is the default value for newly created queue managers.
Disabled which means that all Publish/Subscribe functions are
disabled.

Message Retry Count The number of times that the channel retries to connect to the MRRTY
remote queue manager before it decides that it cannot deliver
the message to the remote queue. This property controls the
action of the MCA only if the Message retry exit name property
is blank. If the Message retry exit name property is not blank,
the value of the Message retry count property is passed to the
exit for the exit's use but the number of times that the channel
retries to connect is controlled by the exit, not by the Message
retry count property. The maximum value is 999999999, and the
default value is 5.
Publish/Subscribe This option defines whether messages will be processed under PSSYNCPT
syncpoint syncpoint. The two options are:
If persistent. The message is processed under syncpoint if
the message is persistent. This is the default value.
Yes. All messages are processed under syncpoint.

Undelivered non- This property defines what the Pub/Sub engine should do with PSNPMSG
persistent input message non-persistent input messages that are not delivered. The two
options are:
Discard. The undelivered non-persistent message is discarded.
This is the default value.
Keep. The undelivered non-persistent message is not discarded.
The Pub/Sub Engine will continue to retry to process this
message at appropriate intervals and does not continue
processing subsequent messages.

346 IBM MQ Explorer

Property Meaning MQSC
Parameter
Undelivered non- This property defines what the Pub/Sub engine should do with PSNPRES
persistent response non-persistent responses that are not delivered. The four options
are:
Discard. The undelivered non-persistent response is discarded
if it cannot be placed on the reply queue.
Keep. The undelivered non-persistent response is not discarded
or put on the dead-letter queue. The Pub/Sub Engine will back
out the current operation and then retry it at appropriate intervals
and does not continue processing subsequent messages.
Normal. Non-persistent responses which cannot be placed on
the reply queue are put on the dead-letter queue. If they cannot
be placed on the DLQ then they are discarded. This is the default
value.
Safe. Non-persistent responses which cannot be placed on the
reply queue are put on the dead-letter queue. If the response
cannot be sent and cannot be placed on the dead-letter queue
then the Pub/Sub Engine will back out of the current operation
and then retry at appropriate intervals and does not continue
processing subsequent messages.

Tree lifetime The lifetime, in seconds of non-administrative topics. When this TREELIFE
non-administrative node no longer has any active subscriptions,
this parameter determines how long the queue manager will wait
before removing that node.
Only non-administrative topics that are in use by a durable
subscription remain after the queue manager is recycled. Specify
a value in the range 0 through 604000. A value of 0 means that
non-administrative topics are not removed by the queue manager.
The queue manager's initial default value is 1800.

Parent The name of the parent queue manager to which the local queue PARENT
manager is to connect as its child in a hierarchy. If the field
is left empty, then the queue manager has no parent queue
manager, and if there is an existing parent queue manager it is
disconnected.
Before a queue manager can connect to a queue manager as
its child in a hierarchy, channels must exist in both directions,
between the parent queue manager and the child queue manager.

Publish exit path The module name containing the publish exit code. The maximum N/A
length of this field is 128 characters. The default is no publish
exit.
Publish exit function The name of the function entry point into the module containing N/A
the publish exit code. The maximum length of this field is 128
characters.
Publish exit data If the queue manager is using a publish exit, it invokes the exit N/A
passing an MQPSXP structure as input. The data specified using
this property is provided in the ExitData field. The maximum
length of this field is 128 characters. The default is 32 blank
characters.

Introduction to IBM MQ Explorer 347

Property Meaning MQSC
Parameter
Publish/Subscribe Controls whether this queue manager participates in Publish/ PSCLUS
clustering Subscribe clustering. The two options are:
Enabled which means that this queue manager can participate
in Publish/Subscribe clustering. This is the default value for newly
created queue managers.
Disabled which means that this queue manager cannot
participate in Publish/Subscribe clustering.

Archive (z/OS)

The following table lists the queue manager's system log archive properties, or parameters, which are
displayed in the Initial table of the queue manager's Archive dialog. The values in the Initial table were
applied when the queue manager loaded the system parameter module at startup. You can temporarily
change and override some of the values while the queue manager is running; the new values are
displayed in the Set table. The parameters that you can override are marked with an asterisk (*). For
details of the properties in the Archive tape record table, see Archive tape.
The equivalent MQSC property for the SET ARCHIVE command is shown for each parameter. For more
information about the SET ARCHIVE command, see SET ARCHIVE.

Property Meaning MQSC

parameter
Parameter type This property shows which type of information is displayed in (Not
the table. The Initial table displays the initial values that were applicable.)
applied when the queue manager loaded the system parameter
module at startup. The Set table displays any values that have
been manually overridden since the queue manager started.
*Allocation unit Specify the unit in which primary and secondary space allocations ALCUNIT
are made: Cylinders, Tracks, or Blocks. The default is Blocks.
*Archive prefix 1 Specify the prefix for the first archive log data set name. See the ARCPFX1
Time stamp format property for a description of how the data
sets are named and for restrictions on the length of the prefix.
The default prefix is CSQARC1.
*Archive prefix 2 Specify the prefix for the second archive log data set name. See ARCPFX2
the Time stamp format property for a description of how the
data sets are named and for restrictions on the length of the
prefix. The default prefix is CSQARC2.
*Archive retention period Specify the retention period, in days from 0 to 9999, to be used ARCRETN
when the archive log data set is created. The default is 9999.
*Routing code Specify the list of z/OS routing codes for messages to the ARCWRTC
operator about archive log data sets. This field is ignored if the
value of the Waiting for reply property is No. Type up to
14 routing codes, each with a value from 1 to 16, separated by
commas. Specify at least one code.

348 IBM MQ Explorer

Property Meaning MQSC
parameter
*Waiting for reply Specify whether a message is to be sent to the operator and a ARCWTOR
reply is received before attempting to mount an archive log data
set. Other IBM MQ users might be forced to wait until the data
set is mounted, but they are not affected while IBM MQ is waiting
for the reply to the message. If the device needs a long time to
mount archive log data sets, for example a tape drive, click Yes; If
the device does not have long delays, for example DASD, click No.
*Block size Type the block size, from 4097 to 28672 (rounded up to the BLKSIZE
nearest multiple of 4 096), of the archive log data set. The block
size must be compatible with the device type that you specify
for the Archive unit 1 property. This parameter is ignored
for data sets that are managed by the storage management
subsystem (SMS).
*Catalog Specify whether archive log data sets are cataloged in the primary CATALOG
integrated catalog facility (ICF) catalog. To archive log data sets
that are cataloged, click Yes; to archive log data sets that are not
cataloged, click No. The default is No.
*Compact Specify whether data written to archive logs is to be compacted. COMPACT
This option applies only to a 3480 or 3490 device that has the
improved data recording capability (IDRC) feature. When this
feature is turned on, hardware in the tape control unit writes data
at a much higher density than normal, allowing for more data on
each volume. If you want the data to be compacted, click Yes; if
you do not use a 3480 device with the IDRC feature or a 3490
base model, with the exception of the 3490E, click No.
*Primary space allocation Specify the primary space allocation for DASD data sets in the PRIQTY
unit that you specified in the Allocation units property. The
value must be from 1 to 999. See z/OS System Setup Guide for a
guide to determining the necessary value.
*Secondary space Specify the secondary space allocation for DASD data sets in the SECQTY
allocation unit that you specified in the Allocation units property. The
value must be greater than zero.
*Protect Specify whether archive log data sets are to be protected by PROTECT
discrete ESM (external security manager) profiles when the data
sets are created. Click Yes to create discrete data set profiles
after the logs offload process ends. ESM protection must be
active for IBM MQ, the user ID associated with the IBM MQ
queue manager address space must have authority to create
these profiles, and the TAPEVOL class must be active if you are
archiving to tape. If you do not want to create profiles, click No.
*Quiesce interval Specify the maximum number of seconds, from 1 to 999, allowed QUIESCE
for the quiesce when an ARCHIVE LOG command is issued with
MODE(QUIESCE) specified.
*Time stamp format Specify whether the archive log data set name has a time stamp TSTAMP
in it. To include a time stamp in the name, click Yes or Extended,
depending on the format that you want to use. If you do not
want to include a time stamp in the name, click No. For more
information about the formats, see SET ARCHIVE.

Introduction to IBM MQ Explorer 349

Property Meaning MQSC
parameter
*Archive unit 1 Specify the device type or unit name of the device that is used to UNIT
store the first copy of the archive log data set.
*Archive unit 2 Specify the device type or unit name of the device that is used to UNIT2
store the second copy of the archive log data set.

Archive tape (z/OS)

The following table lists the archive tape properties, which are used in the queue manager's archive tape
records. The archive tape records are listed in the Archive tape records table in the queue manager's
Archive dialog. You cannot edit these values.

Parameter Meaning
Parameter type This property shows which type of information is
displayed in the table. The Initial table displays
the initial values that were applied when the queue
manager loaded the system parameter module at
startup. The Set table displays any values that have
been manually overridden since the queue manager
started.
Tape unit address The physical address of the tape unit that is allocated
to read the archive log.
Tape unit status The status of the tape unit. Busy means that the tape
unit is busy actively processing an archive log data
set; Premount means that the tape unit is active and
allocated for premounting; Available means that the
tape unit is available, inactive, and waiting for work;
Unknown means that the status of the tape unit is
unknown.
Log correlation ID The correlation ID associated with the user of the tape
that is being processed. This is blank if there is no
current user.
Tape volume serial number The volume serial number of the tape that is mounted.
Data set name The data set name on the tape volume that is being
processed, or was last processed.

Statistics monitoring (z/OS)

The following table lists the properties that you can set on the Statistics monitoring page of the Queue
Manager properties dialog. To collect statistical data on the activity of the queue manager, edit the
properties on the Statistics monitoring page.

350 IBM MQ Explorer

Property Meaning MQSC
parameter
Channel statistics This property specifies whether to collect statistics data about STATCHL
the activity of channels that are hosted by the queue manager.
The statistics data is written to SMF. To switch off statistics
data collection for the channels of the queue manager that
have the value Queue Manager in their Channel statistics
property, click Off. To switch off statistics data collection for all
the queue manager's channels regardless of the setting of the
channel's Channel statistics property, click None. To enable data
collection for channels that have the value Queue Manager in
their Channel statistics property, plus data collection for server-
connection channels, click Low, Medium, or High. For more
information about editing the Statistics page channel properties,
see “Statistics page” on page 388.
Auto CLUSSDR Statistics This property specifies whether to collect statistics data STATACLS
about the activity of auto-defined cluster-sender channels. The
statistics data is written to SMF. To inherit from the value of the
queue manager's Channel statistics property, click Queue
Manager; to switch off data collection for auto-defined cluster-
sender channels on the queue manager, click None; to enable
data collection, click Low, Medium; or High.
This property specifies whether to collect statistics data about STATQ
Queue
the activity of queues hosted by the queue manager. To turn on
Statistics
statistics data collection for the queue manager’s queues that
have the value Queue Manager in their Queue accounting
property (see Queue properties), click On; to turn off statistics
data collection for the queue manager’s queues that have the
value Queue Manager in their Queue accounting property,
click Off. To collect any queue statistics data, you must enable
statistics trace class 5 using the START TRACE command.

Accounting monitoring (z/OS)

The following table lists the properties that you can set on the Accounting monitoring page of the Queue
Manager properties dialog. To collect data about the activity of a connection, edit the properties on the
Accounting monitoring page.

Property Meaning MQSC

parameter
Queue accounting This property specifies whether to collect accounting data about ACCTQ
the activity of connections for queues hosted by the queue
manager. To turn on accounting data collection for the queue
manager's queues, click On; to disable accounting data collection
for the queue manager's queues that have the value Queue
Manager in their Queue accounting property (see Queue
properties), click Off; to turn off accounting data collection for
all the queue manager's queues regardless of the setting of the
queue's Queue accounting property, click None.

Log (z/OS)

Introduction to IBM MQ Explorer 351

 The following table lists the queue manager's system log properties, or parameters, which are displayed
in the Initial table of the queue manager's Log dialog. The values in the Initial table were applied when
the queue manager loaded the system parameter module at startup. You can temporarily change and
override some of the values while the queue manager is running; the new values are displayed in the Set
table. The parameters that you can override are marked with an asterisk (*). For details of the properties
in the Log copy record table, see Log copy.
The equivalent MQSC property for the SET LOG command is shown for each parameter. For more
information about the SET LOG command, see SET LOG.

Parameter Meaning MQSC

parameter
Parameter type This property shows which type of information is displayed in (Not
the table. The Initial table displays the initial values that were applicable.)
applied when the queue manager loaded the system parameter
module at startup. The Set table displays any values that have
been manually overridden since the queue manager started.
*Deallocation interval Specify the length of time, in minutes, that an allocated DEALLCT
archive read tape unit is allowed to remain unused before it is
deallocated. The value can be from zero to 1440. If the value
is zero, the tape unit is deallocated immediately; if the value is
1440, the tape unit is never deallocated.
*Log compression Specifies the log data compression technique for persistent COMPLOG
message logging.
NONE means that log compression is not enabled. This is the
default value.
RLE means that run-length encoding log compression is enabled.
ANY means that any compression algorithm supported by the
queue manager is enabled. In IBM WebSphere MQ 7.0.1 and
later, the only compression algorithm available for value ANY is
RLE.

*Maximum number of log Specify the maximum number of archive log volumes that can be MAXARCH
archives recorded in the BSDS.
*Maximum number of Specify the maximum number of dedicated tape units that can MAXRTU
tape units be allocated to read archive log tape volumes. This overrides
the value for MAXRTU set by CSQ6LOGP in the archive system
parameters. This, together with the Deallocation interval
property, allows IBM MQ to optimize archive log reading from
tape devices.
Input buffer size Specifies the size of input buffer storage for active and archive log INBUFF
data sets.
Output buffer size Specifies the size of output buffer storage for active and archive OUTBUFF
log data sets.
*Output buffer count Specifies the number of output buffers to be filled before they are WRTHRSH
written to the active log data sets.
Log archive Specifies whether archiving is on or off. Yes means that archiving OFFLOAD
is on; No means that archiving is off.
Dual logging used Specifies whether dual logging is being used. Yes means that dual TWOACTV
logging is being used; No means that dual logging is not being
used.

352 IBM MQ Explorer

Parameter Meaning MQSC
parameter
Dual archive logging used Specifies whether dual archive logging is being used. Yes means TWOARCH
that dual archive logging is being used; No means that dual
archive logging is not being used.
Dual BSDS used Specifies whether dual BSDS is being used. Yes means that dual TWOBSDS
BSDS is being used; No means that dual BSDS is not being used.
zHyperWrite enabled Specifies whether writes to active log data sets use zHyperWrite ZHYWRITE
if the data sets are zHyperWrite capable. Yes means that
zHyperWrite is being used; No means that zHyperWrite is not
being used.

Log copy (z/OS)

The following table lists the log copy properties, which are used in the queue manager's log copy records.
The log copy records are listed in the Log copy records table in the queue manager's Log dialog. You
cannot edit these values.

Parameter Meaning
Log copy number The number of the copy.
Log used The percentage of the active log data set that has
been used.
Data set name The data set name of the active log data set. If the
copy is not currently active, this is returned as blank.
zHyperWrite capable Whether the log data set is capable of being written
to, using zHyperWrite. You need to enable the queue
manager for zHyperWrite for this to occur.

Security (z/OS)

The following table lists the queue manager's system-wide security properties, or parameters. You can
change two of the values; the parameters that you can change are marked with an asterisk (*). For details
of the properties in the Security switch table, see Security switch.
The equivalent MQSC property for the ALTER SECURITY command is shown for each parameter. For more
information about the ALTER SECURITY command, see ALTER SECURITY.

Parameter Meaning MQSC

parameter
*Security timeout Type, in minutes from 0 to 10080 (one week), how long security TIMEOUT
information about an unused user ID and associated resources is
retained by IBM MQ. If you type 0, and the value of the Security
interval property is not zero, all such information is discarded by
the queue manager every Security interval.
*Security interval Type, in minutes from 0 to 10080 (one week), the interval INTERVAL
between checks for user IDs and their associated resources to
determine whether the Security timeout has expired. If you type
0, no user timeouts occur.

Introduction to IBM MQ Explorer 353

 Security switch (z/OS)

The following table lists the security switch properties, which are used in the queue manager's security
switch messages. The security switch messages (one per security switch) are listed in the Security
switch table in the queue manager's Security dialog. You cannot edit these values.

Parameter Meaning
Security switch The name of the security switch.
Security setting The current setting of the security switch, and whether
the profile that caused the setting is present. For
example, the security switch could be set off because
the relevant profile was not found.
Security profile The name of the profile that caused the current
security setting.

System (z/OS)

The following table lists the queue manager's system properties, or parameters, which are displayed in
the Initial table of the queue manager's System dialog. The values in the Initial table were applied when
the queue manager loaded the system parameter module at startup. You can temporarily change and
override some of the values while the queue manager is running; the new values are displayed in the Set
table. The parameters that you can override are marked with an asterisk (*).
The equivalent MQSC property for the DISPLAY SYSTEM command is shown for each parameter. For more
information about the DISPLAY SYSTEM command, see DISPLAY SYSTEM.

Parameter Meaning MQSC

parameter
Parameter type This property shows which type of information is displayed in (Not
the table. The Initial table displays the initial values that were applicable.)
applied when the queue manager loaded the system parameter
module at startup. The Set table displays any values that have
been manually overridden since the queue manager started.
Connection swap Whether or not batch jobs can currently be swapped out during CONNSWAP
some MQ API calls.
From IBM MQ 9.0 this keyword has no effect, as applications are
always made non-swappable during IBM MQ API calls. It is no
longer returned by IBM MQ 9.1, or later, queue managers, but has
been retained in IBM MQ Explorer for compatibility with IBM MQ
8.0, and earlier, queue managers.

Command user ID Specifies the default user ID for command security checks. CMDUSER
*Excluded operator A list of messages excluded from being written to any log. EXCLMSG
messages
Exit interval Specifies the time, in seconds, for which queue manager exits can EXITLIM
execute during each invocation.
Exit tasks Specifies how many started server tasks to use to run queue EXITTCB
manager exits.

354 IBM MQ Explorer

Parameter Meaning MQSC
parameter
*Checkpoint count Specify the number of log records, from 200 to 16000000, that LOGLOAD
IBM MQ writes between the start of one checkpoint and the next.
IBM MQ starts a new checkpoint after the number of records that
you specify has been written.
XCF group name Specifies the name of the XCF group to which this instance of IBM OTMACON =
MQ belongs. (Group)
XCF member name Specifies the name of the XCF member to which this instance of OTMACON =
IBM MQ belongs. (Member)
OTMA exit name Specifies the name of the OTMA destination resolution user exit OTMACON =
to be run by IMS. (Druexit)
OTMA interval Specifies the length of time, in seconds, that a user ID from IBM OTMACON =
MQ is considered previously verified by IMS. (Age)
OTMA Tpipe name prefix Specifies the prefix to be used for Tpipe names. OTMACON =
(Tpipepfx)
Defer index Specifies whether the queue manager restart completes before QINDXBLD
all indexes are built and defers building until later, or whether the
queue manager waits until all indexes are built. Yes means that
the queue manager restart completes before all indexes are built;
No means that the queue manager restart waits until all indexes
are built.
Coded character set ID Specifies the coded character set identifier for the queue QMCCSID
manager.
Queue sharing group Specifies the name of the queue sharing group to which the (Not
name queue manager belongs. applicable.)
Data-sharing group name Specifies the name of the Db2 data-sharing group to which the (Not
queue manager is to connect. applicable.)
Db2 name Specifies the name of the Db2 subsystem or group attachment to (Not
which the queue manager is to connect. applicable.)
Db2 tasks Specifies the number of Db2 server tasks to use. (Not
applicable.)
Db2 BLOB tasks Specifies the number of Db2 server tasks to be used for BLOBs. (Not
applicable.)
Write RACF audit records Specifies whether RACF audit records are written for RESLEVEL RESAUDIT
security checks that are performed during connection processing.
Yes means that RACF audit records are written; No means that
RACF audit records are not written.
Routing code Specifies the list of z/OS routing codes for messages that are not ROUTCDE
sent in direct response to an MQSC command. There can be 1 -
16 entries in the list.
Send accounting data to Specifies whether IBM MQ sends accounting data to SMF SMFACCT
SMF automatically when the queue manager starts. Yes means that
accounting data is sent automatically; No means that accounting
data is not sent automatically.

Introduction to IBM MQ Explorer 355

Parameter Meaning MQSC
parameter
Send statistics data to Specifies whether IBM MQ sends statistics data to SMF SMFSTAT
SMF automatically when the queue manager starts. Yes means that
statistics data is sent automatically; No means that statistics data
is not sent automatically.
From IBM MQ for z/OS 9.3, specify the interval, in minutes from ACCTIME
*SMF
0 to 1440, between consecutive gatherings of accounting data.
accounting interval
A special value of -1 can be set to signify the use of the SMF
minutes
statistics interval for accounting data.
If you specify a value of 0, accounting data is collected at the SMF
data collection broadcast. You should set this value alongside
SMF accounting interval seconds, or the seconds value defaults to
0.
Changes to this parameter take effect when the current interval
expires, unless the new interval is less than the unexpired portion
of the current interval, in which case accounting data is gathered
immediately and the new interval then takes effect.

From IBM MQ for z/OS 9.3 specify the seconds portion of the ACCTIME
*SMF
ACCTIME interval as a value between 00 and 59. You should
accounting interval
set this value alongside SMF accounting interval minutes or the
seconds
minutes value defaults to 0.
Changes to this parameter take effect when the current interval
expires, unless the new interval is less than the unexpired portion
of the current interval, in which case accounting data is gathered
immediately and the new interval then takes effect.

From IBM MQ for z/OS 9.3, specify the interval, in minutes from 0 STATIME
*SMF
to 1440, between consecutive gatherings of statistics data.
statistics interval minutes
If you specify a value of 0, statistics data is collected at the SMF
data collection broadcast. You should set this value alongside
SMF statistics interval seconds or the seconds value defaults to 0.
If you want to use the SMF data collection broadcast interval,
then ensure both this value and SMF statistics seconds are set to
0.
Changes to this parameter take effect when the current interval
expires, unless the new interval is less than the unexpired portion
of the current interval, in which case accounting data is gathered
immediately and the new interval then takes effect.

From IBM MQ for z/OS 9.3, specify the seconds portion of the STATIME
*SMF
STATIME interval as a value between 00 and 59. You should
statistics interval seconds
set this value alongside SMF statistics interval minutes, or the
minutes value defaults to 0.
Changes to this parameter take effect when the current interval
expires, unless the new interval is less than the unexpired portion
of the current interval, in which case accounting data is gathered
immediately and the new interval then takes effect.

Trace classes Specifies the classes for which tracing is started automatically. TRACSTR

356 IBM MQ Explorer

Parameter Meaning MQSC
parameter
*Trace table size Specify the default size, in 4 KB blocks from 1 to 999, of trace TRACTBL
table where the global trace facility stores IBM MQ trace records.
Storage for the trace table is allocated in the ECSA so you must
select this value with care. If there is any trace currently in
effect, the existing trace table continues to be used, and its
size is unchanged. A new global trace table is only obtained
when trace is restarted. If a new trace table is created with
insufficient storage, the old trace table continues to be used, and
the message CSQW153E is displayed.
Cluster cache type Specifies the type of cluster cache. Static means that a static (Not
cluster cache is used; Dynamic means that a dynamic cluster applicable.)
cache is used.
WLM interval Specifies the time, in minutes, between scans of the queue index WLMTIME
for WLM-managed queues.
WLM units Indicates whether WLM interval is in seconds or minutes. WLMTIMU
*Service parameter This parameter is reserved for use by IBM. SERVICE
setting
Operation mode Shows the operation mode for the queue manager. OPMODE =
(COMPAT,701)
From IBM MQ 9.1, this keyword is no longer returned by
queue managers. It has been retained in IBM MQ Explorer for For more
compatibility with IBM MQ 9.0, and earlier, queue managers. information
see DISPLAY
SYSTEM in the
IBM MQ 9.0
product
documentation
.

Security policies Indicates whether the security capabilities of Advanced Message SPLCAP
Security are available.
Maximum ACE pool size The maximum size of the ACE storage pool in KB in the range 0 ACELIM
(KB) - 999 999. An ACE is required for each connected application,
and some types of application require extra ACEs for processing.
Internal queue manager threads also require them. The ACE
storage pool is allocated in ECSA. For queue managers that use a
large quantity of ECSA storage, the ECSA storage allocation grows
linearly with the size of the ACE storage pool. A value of zero for
this parameter means that there is no limit on the size of the ACE
storage pool. In extreme circumstances, the ACE storage pool can
use all of the available ECSA storage, resulting in a system outage
for the LPAR.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553

Introduction to IBM MQ Explorer 357

 To include certain characters in a string, you must punctuate the string in a particular way.

IBM MQ queue properties

The properties that you can set for a queue depend on the type of queue. Different types of IBM MQ
queues have different properties. Some of the properties do not apply to all types of queue, some
properties are specific to cluster queues, and some properties are specific to z/OS queues.
The following tables list the properties that you can set for all types of queues:
• General
• Extended
• Cluster
• Triggering
• Events
• Storage
• Statistics
For each property, there is a brief description of when you might need to configure the property. The
tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY QUEUE commands.
For more information about MQSC commands, see The MQSC Commands.

General page
The following table lists the properties you can set on the General page of the Queue properties dialog.

Property Description MQSC

parameter
Queue name Read-only. You cannot change the name of the queue after it has QNAME
been created.
Queue type Read-only. You cannot change the type of the queue after it has QTYPE
been created.
QSG disposition (z/OS shared queue only) Read-only. The queue sharing group QSGDISP
disposition of the queue. Specifies the disposition of the object
(where it is defined and how it behaves). You cannot change the
disposition of a queue after it has been created. Queue manager
means that the object definition is available only to the queue
manager that hosts it; Group means that the object definition
is stored on the shared repository and each queue manager
in the queue sharing group has a copy of the definition; Copy
means that the object definition is the queue manager's copy of a
definition in the shared repository; Shared means that the object
definition is stored on the queue sharing group's coupling facility
and is available to all the queue managers in the queue sharing
group.
Description Type a meaningful description of the purpose of the queue. See DESCR
“Strings in property dialogs” on page 553.
Put messages To enable messages to be put on the queue, select Allowed; to PUT
prevent messages from being put on the queue, select Inhibited.
Get messages To enable messages to be got from the queue, select Allowed; to GET
prevent messages being got from the queue, select Inhibited.
Default priority Type the default priority, from 0 - 9, of messages that are put on DEFPRTY
the queue; 0 is the lowest priority.

358 IBM MQ Explorer

Property Description MQSC
parameter
Default persistence The default persistence of a new queue is Not persistent. DEFPSIST
Select Persistent to specify that messages created
by applications that use MQPER_PERSISTENCE_AS_Q_DEF
become persistent. Select Not Persistent to specify
that messages created by applications that use
MQPER_PERSISTENCE_AS_Q_DEF become non persistent.
Scope To put the queue in the cell directory and make the queue SCOPE
known to all the queue managers within the cell, select Cell; to
restrict the queue's scope so it does not extend beyond its queue
manager, select Queue Manager.
Usage To make the queue a local queue, select Normal; to make the USAGE
queue a transmission queue, select Transmission. Do not change
the Usage property while there are messages on the queue.
Base type Select the type of object (Queue or Topic) to which the alias TARGTYPE
queue resolves. The default value is Queue.
Remote queue Type the name of the queue to which the remote queue definition RNAME
points.
Remote queue manager Type the name of the queue manager that hosts the remote RQMNAME
queue.
Transmission queue Type the name of the transmission queue that the local queue XMITQ
manager uses to send messages to the remote queue manager.

Extended page
The following table lists the properties you can set on the Extended page of the Queue properties dialog.

Property Description MQSC

parameter
Max queue depth Type the maximum number of messages that are allowed on the MAXDEPTH
queue. Specify a value from 0 - 999999999.
Max message length Type the maximum length of a message, in bytes, that is allowed MAXMSGL
on the queue. On all platforms other than z/OS, specify a value
from 0 to the maximum message length for the queue manager.
See the Maximum message length property in Queue manager
properties. On z/OS, specify a value from 0 - 100 MB.
Shareability To share the queue so that more than one instance of an SHARE
application can open this queue for input, select Shareable; to
restrict the queue so that only one instance of an application can
open the queue at a time, select Not Shareable.
Default input open option To allow applications that open the queue for input to have DEFSOPT
exclusive access to the messages on the queue, select Exclusive;
to allow any number of applications that open the queue for input
to access the messages on the queue, select Shared.
Message delivery To specify to get messages from the queue in order of their MSGDLVSQ
sequence priority, select Priority. To specify to get messages from the
queue in the order that they were put on the queue, select FIFO
(first in, first out).

Introduction to IBM MQ Explorer 359

Property Description MQSC
parameter
Retention interval Type the number of hours from the date and time when it was RETINTVL
created (from 0 - 999999999) that the queue might be needed.
You can use this information to determine when the queue is
no longer required. The queue will not be deleted when it is no
longer required.
Index type To specify the type of index that the queue manager maintains to
increase the speed of MQGET operations on the queue, select one
of these five options:
None: No index is maintained. Use this when retrieving messages
sequentially. This is the default.
Group ID: An index of group identifiers is maintained. You
must use this index type if you want logical ordering of message
groups.
Correl ID: An index of correlation identifiers is maintained.
Use this when retrieving messages using the CorrelId field as a
selection criterion on the MQGET call.
Message ID: An index of message identifiers is maintained. Use
this when retrieving messages using the MsgId field as a selection
criterion on the MQGET call.
Message token: An index of message tokens is maintained.

Definition type For local queues, this property is read-only: Predefined means DEFTYPE
that the queue was created by an operator or an authorized
application sending a command message to the service queue;
Permanent dynamic means that the queue was created by an
application issuing an MQOPEN call with the name of a model
queue specified in the object descriptor (MQOD) and the queue
is permanent; Temporary dynamic means that the queue was
created by an application issuing an MQOPEN call, but the queue
is temporary; Shared dynamic (z/OS only) also means that the
queue was created by an application issuing an MQOPEN call,
but the queue is permanent and has the queue sharing group
disposition of Shared.
For model queues, this property is editable; To specify that a
permanent dynamic queue is created from this model queue,
select Permanent dynamic (on z/OS, the dynamic queue has
a disposition of Queue manager); to specify that a temporary
dynamic queue is created, select Temporary dynamic (on z/OS,
the dynamic queue has a disposition of Queue manager); on
z/OS only, to specify that a permanent dynamic queue is created
with a disposition of Shared, select Shared dynamic.

360 IBM MQ Explorer

Property Description MQSC
parameter
Default read ahead To configure read ahead at the queue level, select Yes. Non- DEFREADA
persistent messages are automatically read ahead by the
client, ahead of the application requesting them. Non-persistent
messages might be lost if the client ends abnormally or if the
client application does not consume all the messages it is sent.
To configure the queue so that non-persistent messages are not
automatically read ahead by the client, select No. This is the
default value. Messages are not automatically read ahead by the
client ahead of an application requesting them. Messages are only
read ahead if requested by the client. A maximum of one non-
persistent message might be lost if the client ends abnormally.
To disable read ahead at the queue level, select Disabled.
Messages are not read ahead by the client ahead of an application
requesting them, regardless of whether read ahead is requested
by the client application.

Default put response type The default response type for message puts. To specify that the DEFPRESP
response is put synchronously, select Synchronous. To specify
that the response is put asynchronously, select Asynchronous.
Distribution lists To allow distribution list messages to be put on the queue, select DISTL
Enabled. To prevent distribution list messages being put on the
queue, select Disabled.

Introduction to IBM MQ Explorer 361

Property Description MQSC
parameter
Property control This defines what happens to properties of messages that are PROPCTL
retrieved from queues using the MQGET command when the
(Only on Local queues,
MQGMO_PROPERTIES_AS_Q_DEF option is specified.
Alias queues, and Model
queues) To contain all the properties of the message, except those
contained in the message descriptor (or extension), select All.
The All value means that all properties of the message are
included with the message when it is sent to the remote queue
manager. The properties, except those properties in the message
descriptor (or extension), are placed in one or more MQRFH2
headers in the message data.
To allow applications that expect JMS related properties to be in
an MQRFH2 in the message data to continue to work unmodified,
select Compatibility. This is the default value. Compatibility
means that if the message contains a property with a prefix of
mcd., jms., usr., or mqext. then all message properties are
delivered to the application in an MQRFH2 header. Otherwise
all properties of the message, except those contained in the
message descriptor (or extension), are discarded and are no
longer accessible to the application.
To ensure that properties are always returned in the message
data in an MQRFH2 header, regardless of whether the application
specifies a message handle, select Force MQRFH2. A valid
message handle supplied in the MsgHandle field of the MQGMO
structure on the MQGET call is ignored. Properties of the message
are not accessible via the message handle.
To discard all the properties of a message, except those contained
in the message descriptor (or extension), select None. This value
prevents applications that do not support message properties
from being affected by the inclusion of any property in a message.
V6COMPAT - MQRFH2 headers are not modified by the properties
code. If message properties have been provided and are not
contained in the original MQRFH2 headers, they are returned
in a message handle or otherwise discarded. This behavior can
be overridden by supplying one of the MQGMO_PROPERTIES
options.
Note: For a transmission queue, which is a local queue with
Usage set to Transmission, the Property Control property
of the queue is irrelevant and it is the Property Control
property on the corresponding channel object that controls the
message property behavior.

362 IBM MQ Explorer

Property Description MQSC
parameter
Custom The Custom parameter is included for IBM use only, reserved CUSTOM
for the configuration of new features before separate properties
have been introduced. The possible values are a list of zero or
more properties-value pairs, in MQSC-style syntax, separated by
at least one space.
The property names and values are case-sensitive, and must
be specified in uppercase. The values can contain spaces,
parentheses and single-quotes (which must be escaped with
another single-quote). Other characters, including nested
parentheses (), can be included by enclosing them in two single-
quotes on either side. Examples of valid syntax are:
• CUSTOM('')
• CUSTOM('A(B)')
• CUSTOM('C(D) E(F)')
• CUSTOM('G(5000) H(''9.20.4.6(1415)'')')
The queue manager parses the value, but if the string cannot be
parsed according to these rules, or if it contains properties or
values that are not recognized, the queue manager ignores the
errors.

Cluster channel names Set the Cluster channel names parameter on a cluster CLCHNAME
transmit queue to override the default association of cluster-
sender channels with cluster transmission queues. You can
specify which cluster-sender channels transfer messages from
this transmission queue.
The default is for all cluster-sender channels to transfer
messages from a single cluster transmission queue,
SYSTEM.CLUSTER.TRANSMIT.QUEUE. You can change the
default for the queue manager, so that all cluster-sender channels
transfer messages from separate transmission queues. The
queue manager property is Default cluster transmission
queue. The queue manager creates separate transmission
queues automatically, when they are required. The queue
manager does not set the Cluster channel name parameter
Set the Cluster channel names parameter to the name
of a single cluster-sender channel, or to a generic name. A
generic name associates multiple cluster-sender channels with
this transmission queue. A generic name has wildcard characters,
"*", in any positions in the name. All cluster-sender channels that
match the name transfer messages from this transmission queue
and no other.
On z/OS, if this parameter is set, the queue must be shareable, be
indexed by correlation ID, and must not be a dynamic or a shared
queue.

Introduction to IBM MQ Explorer 363

Property Description MQSC
parameter
The maximum time, expressed in tenths of a second, until a CAPEXPRY
Cap expiry
message put using an object handle with this object in the
resolution path, becomes eligible for expiry processing.
For more information on message expiry processing, see
Enforcing lower expiration times.
integer
The value must be in the range one through to 999 999 999.
NOLIMIT
There is no limit on the expiry time of messages put using this
object. This is the default value.
Note that existing messages in the queue, prior to a change in
CAPEXPRY, are not affected by the change (that is, their expiry
time remains intact). Only new messages that are put into the
queue after the change in CAPEXPRY have the new expiry time.

Cluster page
The following table lists the properties you can set on the Cluster page of the Queue properties dialog. To
share the queue in one or more clusters, edit the properties on the Cluster page.

Property Description MQSC

parameter
Not shared in cluster To specify that this queue is not available to other queue (Not
managers via cluster connections, select this option. applicable.)
Shared in cluster To make this queue available to other queue managers in just one CLUSTER
cluster, select this option, then type the name of the cluster.
Shared in a list of clusters To make this queue available to other queue managers in more CLUSNL
than one cluster, select this option, then type the name of the
namelist that contains the list of clusters.
Default bind type This property specifies the binding to be used when the DEFBIND
application specifies MQ00_BIND_AS_Q_DEF on the MQOPEN
call, and the queue is a cluster queue. To bind the queue handle
to a specific instance of the cluster queue when the queue is
opened, select On open; to allow the queue manager to select a
specific queue instance when the message is put using MQPUT,
and to change that selection subsequently if necessary, select
Not fixed.
CLWL Queue rank This property is the Cluster Workload (CLWL) queue rank. Type CLWLRANK
the ranking of the queue in the cluster, from 0 - 9; 0 is the
lowest priority. For more information, see Distributed queuing and
clusters.
CLWL Queue priority This property is the Cluster Workload (CLWL) queue priority. Type CLWLPRTY
the priority of the queue in the cluster, from 0 - 9; 0 is the
lowest priority. For more information, see Distributed queuing and
clusters.

364 IBM MQ Explorer

Property Description MQSC
parameter
CLWL use queue The Cluster Workload (CLWL) use queue property. It defines the CLWLUSEQ
behavior of an MQPUT when the target queue has both a local
instance and at least one remote cluster instance. If the put
originates from a cluster channel, this property does not apply.
Select one of the following options:
Select Queue manager to use the value specified by the CLWL
use queue property of the queue manager that the selected
queue belongs to. This is the default value.
Select Any to use local and remote queues.
Select Local to use only local queues
For more information, see Distributed queuing and clusters.

Triggering page
The following table lists the properties you can set on the Triggering page of the Queue properties
dialog. To configure the queue for triggering, edit the properties on the Triggering page.

Property Description MQSC

parameter
Trigger control To enable triggering on the queue, select On, then configure the TRIGGER
other trigger properties for the queue; to disable triggering on the
queue, select Off.
Trigger type To trigger an event when the current depth of the queue goes TRIGTYPE
from 0 - 1, select First; to trigger an event when the queue depth
threshold is exceeded, select Depth; to trigger an event every
time a message is put on the queue, select Every.
Trigger depth Type the number of messages that must be put on the queue to TRIGDEPTH
trigger an event.
Trigger message priority Type the minimum priority, from 1 - 9, that a message must have TRIGMPRI
for it to count towards a trigger event. The queue manager ignores
messages with a lesser priority when it determines whether to
create a trigger message. To count all messages towards a trigger
event, type 0.
Trigger data Type free-form data for the queue manager to insert into the TRIGDATA
trigger message when the trigger event is caused by this queue.
The data has no significance to the queue manager. The data
is meaningful to either the trigger monitor application that
processes the initiation queue, or to the application that is started
by the trigger monitor.
Initiation queue Type the name of the initiation queue. When the criteria for a INITQ
trigger event are met, the queue manager puts a trigger message
on the initiation queue.

Introduction to IBM MQ Explorer 365

Property Description MQSC
parameter
Process name The local name of the IBM MQ process. This parameter is PROCESS
supported only on local and model queues.
This is the name of a process instance that identifies the
application started by the queue manager when a trigger event
occurs. The process does not have to be defined when the local
queue is defined, but it must be available for a trigger event to
occur.
If the queue is a transmission queue, then the process definition
contains the name of the channel to be started. This parameter
is optional, and if you do not specify a process name, then the
channel name is taken from the value specified for the TRIGDATA
parameter.

Events page
The following table lists the properties you can set on the Events page of the Queue properties dialog.
To configure the queue manager to generate events in response to certain criteria on the queue, edit the
properties on the Events page.

Property Description MQSC

parameter
Queue depth max events To generate a Queue Full event when a message is put to the QDPMAXEV
queue, but is rejected because the queue is already full, select
Enabled.
Queue depth high events To generate a Queue Depth High event when a message is put to QDPHIEV
the queue causing the queue depth to be greater than or equal
to the value of the Queue depth high limit property, select
Enabled.
Queue depth high limit This is the percentage value of the maximum queue depth that QDEPTHHI
is used as the queue depth high limit. Type the maximum queue
depth limit percentage with which the queue manager compares
the current queue depth to determine whether to generate a
Queue Depth High event.
Queue depth low events To generate a Queue Depth Low event when a message is QDPLOEV
retrieved from the queue causing the queue depth to be less than
or equal to the value of the Queue depth low limit property,
select Enabled.
Queue depth low limit This is the percentage value of the maximum queue depth that QDEPTHLO
is used as the queue depth low limit. Type the minimum queue
depth limit percentage with which the queue manager compares
the current queue depth to determine whether to generate a
Queue Depth Low event.
Queue service interval To generate a Queue Service Interval High event when a QSVCIEV
events check indicates that no messages have been retrieved from the
queue for at least the time indicated by the Queue service
interval property, select High; to generate a Queue Service
Interval OK event when a check indicates that messages have
been retrieved from the queue within the time indicated by the
Queue service interval property, select OK; to disable
Queue Service Interval events, select None.

366 IBM MQ Explorer

Property Description MQSC
parameter
Queue service interval Type the service interval, in milliseconds, from 0 - 999999999. QSVCINT
The queue manager uses this value to determine whether to
generate Queue Service Interval High or Queue Service Interval
OK events.

Storage page
The following table lists the properties you can set on the Storage page of the Queue properties dialog.
To configure how IBM MQ deals with messages that are backed out, edit the properties on the Storage
page.

Property Description MQSC

parameter
Backout requeue queue Type the name of the queue to which a message is transferred if BOQNAME
it is backed out more than the number of times specified in the
Backout threshold property.
Backout threshold Type the number of times that the message can be backed out BOTHRESH
before it is transferred to the backout queue you specified in the
Backout requeue queue property.
Harden get backout To ensure that the backout count (the number of times the HARDENBO
message has been retrieved by the MQGET call and then
subsequently backed out) is accurately retained if the queue
manager is restarted, select Hardened. Hardening the count has
a detrimental effect on performance, so select Hardened only if it
is essential that the count is accurate. If it is not essential that the
count is accurate, select Not hardened.
NPM class This property specifies the circumstances under which non- NPMCLASS
persistent messages on the queue are discarded. To specify that
non-persistent messages are discarded when the queue manager
is restarted, select Normal; this is valid only for non-shared
queues. To specify that the queue manager should try to persist
non-persistent messages for the lifetime of the queue, select
High; this is valid for non-shared and shared queues; the non-
persistent messages might still be lost in the event of a failure.
Storage class name This is the name of the storage class that maps the queue to a STGCLASS
page set. The queue's messages are stored on that page set. You
can change this property but the queue must first be empty and
closed. The storage class name must be entered in uppercase.
Coupling facility structure (z/OS shared queue only) This is the name of the coupling facility CFSTRUCT
name structure on which the queue's messages are stored. You can
change this property but the queue must first be empty and
closed.
The maximum size that the queue's file can grow to (in MAXFSIZE
Maximum
megabytes). When the queue file reaches this limit new messages
queue file size
cannot be put to the queue until some are removed.

Introduction to IBM MQ Explorer 367

 Statistics page
The following table lists the properties on the Statistics page of the Queue properties dialog. The
Statistics page displays information about the history of the queue. Not all of the properties can be
edited.

Property Description MQSC

parameter
Creation date Read-only. This is the date when the queue was created. CRDATE
Creation time Read-only. This is the time at which the queue was created. CRTIME
Open input count Read-only. This is the number of applications that are currently IPPROCS
connected to the queue to get messages from the queue.
Open output count Read-only. This is the number of applications that are currently OPPROCS
connected to the queue to put messages on the queue.
Current queue depth Read-only. This is the number of messages currently on the CURDEPTH
queue.
Alteration date Read-only. This is the date on which the queue's properties were ALTDATE
last altered.
Alteration time Read-only. This is the time at which the queue's properties were ALTTIME
last altered.
Queue monitoring You can configure IBM MQ to collect online monitoring data about MONQ
the current performance of the queue. To inherit the value of
the queue manager's Queue monitoring property (see “Queue
manager properties” on page 315), select Queue manager. If
the queue manager's Queue monitoring property is None, the
queue's Queue monitoring property is ignored.
If the queue manager's Queue monitoring property is not
None:
• To override the queue manager's settings and prevent data
collection for this queue, select Off.
• To collect data at a low rate, select Low.
• To collect data at a medium rate, select Medium.
• To collect data at a high rate, select High.
For more information, see Monitoring and performance.

Queue statistics You can configure IBM MQ to collect statistics data about STATQ
the activity of the queue. To inherit the value of the queue
manager's Queue statistics property (see “Queue manager
properties” on page 315), select Queue manager. If the queue
manager's Queue statistics property is None, the queue's
Queue statistics property is ignored. If the queue manager's
Queue statistics property is not None: to override the
queue manager's settings and prevent data collection for this
queue, select Off; to override the queue manager's settings and
collect data, select On. For more information, see Monitoring and
performance.

368 IBM MQ Explorer

Property Description MQSC
parameter
Queue accounting You can configure IBM MQ to collect statistics data about the ACCTQ
activity of connections for this queue. To inherit the value of the
queue manager's Queue accounting property (see “Queue
manager properties” on page 315), select Queue manager. If
the queue manager's Queue accounting property is None, the
queue's Queue accounting property is ignored. If the queue
manager's Queue accounting property is not None: to override
the queue manager's settings and prevent data collection for this
queue, select Off; to override the queue manager's settings and
collect data, select On. For more information, see Monitoring and
performance.

Related concepts
“IBM MQ queues” on page 15
A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Forcing changes to queue properties” on page 38
If the changes that you are making to the properties of a queue affect the operation of a queue manager
or another program, you might be asked to confirm whether you want to force the changes to the queue
properties.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.
“Topic properties” on page 391
An IBM MQ topic is an IBM MQ object that identifies what a publication is about. You can set properties
for topics. Some topic properties are specific to z/OS topics. Also, there are some properties that you can
alter only while you are creating a topic. You cannot modify these properties after the IBM MQ topic has
been created.
JMS Destination properties
You can view and set destination properties in the Destination properties dialog. The properties that are
available in the dialog depend on the type of destination.

Channel properties
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.
The following tables list all the properties that you can set:
• General
• Extended
• MCA
• Exits
• LU6.2
• Retry
• Message retry
• Cluster

Introduction to IBM MQ Explorer 369

 • SSL
• Load Balancing
• Statistics
Some of the properties do not apply to all types of channel:
• Some properties are specific to cluster channels.

• Some properties are specific to z/OS channels.

For each property, there is a brief description of when you might need to configure it. The tables also
give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY CHANNEL commands. For more
information about MQSC commands, see Administering IBM MQ using MQSC commands.

General page
The following table lists the properties that you can set on the General page of the Channel properties
dialog.

Property Meaning MQSC

parameter
Channel name Read-only. This is the name of the channel definition. CHANNEL
Type Read-only. This is the type of the channel definition. CHLTYPE
QSG disposition Read-only. This is the queue sharing group disposition of the QSGDISP
channel definition. You cannot change the disposition of a
channel definition after it has been created. Queue manager
means that the object definition is available only to the queue
manager that hosts it; Group means that the object definition
is stored on the shared repository and each queue manager
in the queue sharing group has a copy of the definition; Copy
means that the object definition is the queue manager's copy of a
definition in the shared repository.
Description Type a meaningful description of the purpose of the channel. See DESCR
“Strings in property dialogs” on page 553.
Queue manager name Type the name of the queue manager on which the channel is QMNAME
defined. For client-connection channels, type the name of the
queue manager to which an application that is running in the MQI
client environment can request connection.
Transmission protocol Select from the list the transport type that the channel uses. TRPTYPE

370 IBM MQ Explorer

Property Meaning MQSC
parameter
Connection name For all types of channel except cluster-receiver channels, type CONNAME
the name of the computer that hosts the target queue manager.
The format of the connection name depends on the transmission
protocol that is selected. For example, if you are using the
TCP/IP protocol and you know that the target queue manager
is connecting using a port number other than the IBM MQ
default of 1414, type computer_name(port_number), where
computer_name is the name or IP address of the computer that
hosts the target queue manager, and port_number is the port that
the target queue manager's listener is using.

For cluster-receiver channels on AIX, Linux, and

Windows, that use the TCP/IP transport protocol, do not specify
a value for this property; IBM MQ generates a name for using,
assuming the default port and the current IPv4 address of the
system. If the system does not have an IPv4 address, the current
IPv6 address of the system is used. For cluster-receiver channels
on other platforms, and for cluster-receiver channels that do not
use the TCP/IP transport protocol, type the name of the computer
that hosts the local queue manager.

Transmission queue Type the name of the transmission queue that corresponds to the XMITQ
queue manager at the receiver end of the channel.
Local communication If the channel uses TCP/IP and you want the channel to LOCLADDR
address use a particular IP address, port, or port range for outbound
communications, type the local communications address for
the channel. The channel binds to the address locally.
Use the format ipaddress(low-port, high-port), where
ipaddress is the IP address specified in IPv4 dotted decimal,
IPv6 hexadecimal, or alphanumeric host name format. For
example, 192.0.2.0 specifies the IPv4 address with any port;
192.0.2.0(1000) specifies the IPv4 address and a specific
port; 192.0.2.0(1000,2000) specifies the IPv4 address and
a range of ports; (1000) specifies a port only.
Cluster-sender channels: If you type a value in the Local
communication address field of a manually defined cluster-
sender channel, this value is overwritten with the values in the
full repository's cluster-receiver channel when communication
is established with the full repository queue manager. As well
as specifying the value in the manually defined cluster-sender
channel, you must write a channel auto-definition exit to force the
value of the Local communication address property into any
automatically defined cluster-sender channels.

Introduction to IBM MQ Explorer 371

Property Meaning MQSC
parameter

Cluster-receiver channels: Do not put an IP address in

the Local communication address field of a cluster-receiver
channel unless all of the queue managers are on the same
computer. This is because any queue manager that attempts to
connect to a queue manager with an IP address in the Local
communication address field of its cluster-receiver channel
has these values propagated to their auto-defined cluster-sender
channels. You can, however, put a port number or port range in
the Local communication address field of a cluster-receiver
channel if you want all the queue managers in a cluster to
use a specific port or range of ports for all their outbound
communications.

Overall channel status Read-only. This is the status of the channel. STATUS

Extended page
The following table lists the properties that you can set on the Extended page of the Channel Properties
dialog.

Property Meaning MQSC

parameter
Maximum message length Type the maximum length of a message that can be transmitted MAXMSGL
on the channel:
• On the following platforms, the value must be greater than or
equal to zero, and less than or equal to the maximum message
length of the queue manager:

– AIX

– IBM i

– Windows
– VSE/ESA
• On other Multiplatforms, the value must be greater than or
equal to zero, and less than or equal to 4,194,304 bytes.

• On IBM MQ for z/OS, the value must be greater

than or equal to zero, and less than or equal to 104,857,600
bytes.

Heartbeat interval Type the length of the heartbeat interval, which can be 0 - HBINT
999999. A value of zero means that no heartbeat exchange takes
place. Set the value to be less than the value of the Disconnect
interval property. The value that is used is the larger of the
values specified at the sending side and the receiving side. The
heartbeat interval is the time, in seconds, between heartbeat
flows passed from the sending MCA when there are no messages
on the transmission queue. The heartbeat exchange gives the
receiving MCA the opportunity to quiesce the channel.

372 IBM MQ Explorer

Property Meaning MQSC
parameter
Maximum instances This parameter is used on server-connection channels and AMQP MAXINST
channels. Maximum instances specifies the maximum number
of simultaneous instances of an individual server-connection
channel or AMQP channel.
The value can be a number in the range 0 - 999999999. The
default value is 999999999
A value of zero means that all client access is prevented.
If Maximum instances is set to a value which is less than the
number of instances of the server-connection channel currently
running, then new instances are prevented from starting until
sufficient existing instances stop running.
If a client connects on an AMQP channel with an ID that is already
connected (that is, it performs a client-takeover) the takeover will
succeed regardless of whether the number of connected clients
has reached MAXINST.

Maximum instances per This parameter is used on server-connection channels. Maximum MAXINSTC
client instances per client specifies the maximum number
of simultaneous instances of an individual server-connection
channel which can be started from a single client. In this context,
connections originating from the same remote network address
are regarded as coming from the same client.
The value can be a number 0 - 999999999. The default value is
999999999
A value of zero means that all client access is prevented.
Maximum instances differs from Maximum instances per
client in that Maximum instances is the maximum amount
of connections, but Maximum instances per client is the
maximum amount of connections that each client is allowed to
connect to the server.

Keep alive interval Type the length of the keep alive interval, 0 - 99999. This KAINT
property is ignored if the channel uses a transport type other than
TCP or SPX. The TCP Keep alive property must be set to Yes
on the Channels page of the Queue manager properties.

On z/OS queue managers, the Keep alive

interval property specifies the keep alive interval for the
individual channel.

On queue managers on multiplatforms, the Keep

alive interval property is used only if the channel connects
to a z/OS queue manager; to use the functionality provided by
the Keep alive interval property, set the Keep alive
interval property to Auto to use a value based on the
negotiated heartbeat interval value.

Introduction to IBM MQ Explorer 373

Property Meaning MQSC
parameter
Sequence number wrap The sequence number is the count of messages that are sent SEQWRAP
through the channel. The sequence number increments each time
a message is sent through the channel.

For z/OS using CICS, type the highest number in

the range 1 - 999999999, that the message sequence number
reaches before it restarts at 1.
For all other platforms, type the highest number in the range 100
- 999999999 that the message sequence number reaches before
it restarts at 1.
The value must be high enough that the number is not reissued
while it is being used by an earlier message. The two ends of the
channel must have the same sequence number wrap value when
the channel starts; otherwise you get an error.

Non-persistent message To specify that nonpersistent messages on a channel are not NPMSPEED
speed transferred within a transaction, select Fast. This means that
nonpersistent messages become available for retrieval far more
quickly than if they are part of a transaction. However, because
the nonpersistent messages are not part of a transaction,
they might be lost if, for example, the channel stops while
the messages are in transit. To prevent this happening, select
Normal.
Batch size Type the maximum number of messages to be sent before BATCHSZ
syncpoint is taken. The messages are always transferred
individually but are committed or backed out as a batch. Try the
default batch size of 50 and change the value only if you need to.
Message compression Click Edit to open the Edit Message Compression dialog. Select COMPMSG
the message compression techniques that are supported by the
channel definition in order of preference. The first technique that
is supported by the other end of the channel is used. None
means that no message compression is performed; RLE means
that message data compression is performed using run-length
encoding; ZLIBFAST means that message data compression
is performed using the zlib compression technique and a fast
compression time is preferred; ZLIBHIGH means that message
data compression is performed using the zlib compression
technique and a high level of compression is preferred; ANY
means that any compression technique that is supported by
the queue manager can be used. For more information, see
Distributed queueing and clusters.
Header compression Click Edit to open the Edit Header Compression dialog. Select COMPHDR
the header compression techniques that are supported by the
channel definition in order of preference. The first technique that
is supported by the other end of the channel is used. None
means that no header compression is performed; System means
that header compression is performed. For more information, see
Distributed queueing and clusters.
Batch interval Type the number of milliseconds, 0 - 999999999, during which BATCHINT
the channel keeps a batch open even if there are no messages on
the transmission queue.

374 IBM MQ Explorer

Property Meaning MQSC
parameter
Batch data limit Provide the limit in kilobytes, 0 - 999999, of the amount of data BATCHLIM
that is sent through a channel before taking a sync point. A value
of 0 means that no data limit is applied to batches over this
channel.
Disconnect interval Type the number of seconds, 0 - 999999, after the batch ends DISCINT
before the channel closes down. A value of 0 means that the
channel does not disconnect.
Data conversion To specify that the message is converted by the receiving CONVERT
application to the format that is required on the receiving system
(this is the typical method), select No; if the remote queue
manager is on a platform that does not support data conversion,
select Yes to specify that the message is converted before
transmission into the format that is required by the receiving
system.
Put authority This property specifies the type of security processing to be PUTAUT
carried out by the Message Channel Agent (MCA) when running
an MQPUT command to the target queue or an MQI call. To use
the default user ID, click Default; to use the alternate user ID
from the context information that is associated with the message,
click Context.
Batch heartbeat interval If the sending channel has had a communication from the BATCHHB
receiving channel within the Batch heartbeat interval, the
receiving channel is assumed to be still active, otherwise a
'heartbeat' is sent to the receiving channel to check. The sending
channel waits for a response from the receiving end of the
channel for an interval, based on the number of seconds specified
in the channel Heartbeat Interval (HBINT) property.
If the receiving end of the channel is not active, the batch can
be backed out rather than becoming in-doubt. By backing out
the batch, the messages remain available for processing so that
they can, for example, be redirected to another channel. Type
the number of seconds, 0 - 999999, that the sending end of
the channel waits for a response from the receiving end of the
channel before assuming that the receiving end of the channel is
inactive.
A value of 0 means that batch heartbeating is not used. For
more information, see “Configuring the channel to reduce the
opportunity of being put 'in-doubt'” on page 97.

Introduction to IBM MQ Explorer 375

Property Meaning MQSC
parameter
Default channel When you issue the START CHANNEL command without the DEFCDISP
disposition channel disposition keyword (CHLDISP), the channel is started
using the value of the Default channel disposition (DEFCDISP).
The three possible values are:
Private. This is the default value. Start as a private channel on
the local queue manager.
Shared. A receiving channel is shared if it was started in
response to an inbound transmission directed to the queue
sharing group. A sending channel is shared if its transmission
queue has a disposition of SHARED.
Fix shared. A sending channel is shared if its transmission
queue has a disposition of SHARED and the CONNAME is not
blank.
Property control If the message contains a property with a prefix of mcd., jms., PROPCTL
(Only on Sender channels, usr., or mqext. then all optional message properties (where the
Server channels, Cluster Support value is MQPD_SUPPORT_OPTIONAL), except those in
Sender channels, the message descriptor (or extension) are placed in one or more
and Cluster Receiver MQRFH2 headers in the message data before the message is sent
channels) to the remote queue manager. Otherwise all properties of the
message, except those in the message descriptor (or extension),
are removed from the message before the message is sent to the
remote queue manager.
If the message contains a property where the Support field of
the property descriptor is not set to MQPD_SUPPORT_OPTIONAL
then the message are rejected and treated in accordance with its
report options. If the message contains one or more properties
where the Support field of the property descriptor is set to
MQPD_SUPPORT_OPTIONAL but other fields of the property
descriptor are set to non-default values, then these properties
are removed from the message before the message is sent to the
remote queue manager.
None means that all properties of the message, except those
in the message descriptor (or extension), are removed from
the message before the message is sent to the remote
queue manager. If the message contains a property where
the Support field of the property descriptor is not set to
MQPD_SUPPORT_OPTIONAL then the message are rejected and
treated in accordance with its report options.

376 IBM MQ Explorer

Property Meaning MQSC
parameter
Sharing conversations Specifies the maximum number of conversations that can be SHARECNV
shared over a particular TCP/IP client channel instance (socket).
(Only on Server-
The possible values are:
connection channels
and Client-connection 0: Specifies no sharing of conversations over a TCP/IP socket. The
channels) channel instance runs in a mode before that of IBM WebSphere
MQ 7.0, with regard to:
• Administrator stop-quiesce
• Heartbeating
• Read ahead
1: Specifies no sharing of conversations over a TCP/IP socket.
Client heartbeating and read ahead are available, whether in an
MQGET call or not, and channel quiescing is more controllable.
2 - 999999999: The number of shared conversations. The
default value is 10.
If the client-connection SHARECNV value does not match the
server-connection SHARECNV value, then the lowest value is
used.
Pending reset sequence This is the sequence number from an outstanding request RESETSEQ
number and it indicates a user RESET CHANNEL command request is
outstanding. A value of zero indicates that there is no outstanding
RESET CHANNEL. The value can be in the range 1 - 999999999.
When the value of RESETSEQ is 0, the DISPLAY CHANNEL
command returns RESETSEQ(NO).

Use dead-letter queue Specifies whether the dead-letter queue is used when messages USEDLQ
cannot be delivered by channels. There are two possible values:
(Not on Client-
connection channels, • No means that messages that cannot be delivered by a channel
Server-connection are treated as a failure, and the channel either ends in
channels, or Telemetry accordance with the setting of Non-persistent message speed,
channels) or discards the messages.
• Yes means that if the queue manager Dead-letter queue
property provides the name of a Dead Letter Queue, then it is
used. Otherwise the behavior is as for No.

Port Specifies the port for the AMQP connection. The default port for PORT
AMQP 1.0 connections is 5672. If you are already using port
(On AMQP channels only)
5672, you can specify a different port.
Use client ID Specifies that the client ID is used for connection on an AMQP USECLTID
channel. Is set to Yes or No.
(On AMQP channels only)

AMQP keep alive Specifies the keep alive time in milliseconds. If the AMQP client AMQPKA
has not sent any frames within the keep alive interval, the
(On AMQP channels only)
connection is closed with a amqp:resource-limit-exceeded
AMQP error condition.

Introduction to IBM MQ Explorer 377

Property Meaning MQSC
parameter
Topic root Specifies the topic root for an AMQP channel. Use this property to TPROOT
ensure that an MQ Light application, when deployed to a queue
(On AMQP channels only)
manager, does not publish or subscribe to messages to or from
areas of the topic tree that are being used by other applications.
The default value for TPROOT is SYSTEM.BASE.TOPIC. With this
default value, the topic string that an AMQP client uses to publish
or subscribe has no prefix, and the client can exchange messages
with other MQ pub/sub applications.

Specifies the name of the model queue to be used while creating TMPMODEL
Temporary
a temporary queue (maximum length 48 characters).
Model Queue
The default is SYSTEM.DEFAULT.MODEL.QUEUE.
(On AMQP channels only)

The temporary queue name prefix to add to the beginning of the TMPQPRFX
Temporary
model queue when deriving a temporary queue name (maximum
Queue Prefix
length 32 characters).
(On AMQP channels only)
The default is AMQP.*

378 IBM MQ Explorer

Property Meaning MQSC
parameter
This defines the behavior for the Message Channel Agent when SPLPROT
Security
getting messages from a transmission queue, or putting to a
policy protection
target queue, in terms of applying AMS protection policies.
This is valid for channels of type sender, server, receiver and
requester. The possible values are:
Passthrough
Pass through, unchanged, any messages sent or received by
the message channel agent for this channel.
This value is valid for channels with a channel type of sender,
server, receiver, or requester, and is the default value.
Remove
Remove any AMS protection from messages retrieved from
the transmission queue by the message channel agent, and
send the messages to the partner.
When the MCA gets a message from the transmission queue,
if an AMS policy is defined for the transmission queue, it is
applied to remove any AMS protection from the message prior
to sending the message across the channel. If an AMS policy
is not defined for the transmission queue, the message is sent
as is.
This value is valid only for channels with a channel type of
sender or server.
As policy
Based on the policy defined for the target queue, apply AMS
protection to inbound messages prior to putting them on to
the target queue.
When the message channel agent receives an inbound
message, if an AMS policy is defined for the target queue, AMS
protection is applied to the message prior to the message
being put to the target queue. If an AMS policy is not defined
for the target queue, the message is put to the target queue as
is.
This value is valid only for channels with a channel type of
receiver, or requester.

MCA page
The following table lists the properties that you can set on the MCA page of the Channel properties
dialog. To configure how the Message Channel Agent (MCA) for this channel runs, edit the properties on
the MCA page.

Introduction to IBM MQ Explorer 379

Property Meaning MQSC
parameter
MCA user ID The message channel agent user identifier. If it is nonblank, it MCAUSER
is the user identifier that is to be used by the message channel
agent for authorization to access IBM MQ resources, including
(if PUTAUT is DEF) authorization to put the message to the
destination queue for receiver or requester channels.
If it is blank, the message channel agent uses its default user
identifier. The default user identifier is derived from the user ID
that started the receiving channel. The possible values are:

• On z/OS, the user ID assigned to the channel-

initiator started task by the z/OS started-procedures table.
• For TCP/IP, for platforms other than z/OS, the user ID from the
inetd.conf entry, or the user that started the listener.
• For SNA, for platforms other than z/OS, the user ID from the
SNA server entry or, in the absence of this the incoming attach
request, or the user that started the listener.
• For NetBIOS or SPX, the user ID that started the listener.
The maximum length of the string is:

• 64 characters on Windows.
For channels with a CHLTYPE of AMQP, before IBM MQ 9.2.0,
the MCAUSER user ID setting is only supported for user IDs up
to 12 characters in length. From IBM MQ 9.2.0, the 12 character
limit is removed.
• 12 characters on platforms other than Windows.

On Windows, you can optionally qualify a user

identifier with the domain name in the format user@domain.

MCA type To specify that the message channel agent (MCA) program runs MCATYPE
as a thread, select Thread; to specify that the MCA runs as a
process, select Process.
MCA name Read-only. You cannot edit this property because the MCA name MCANAME
is reserved and must only be set to blanks.

Exits page
The following table lists the properties that you can set on the Exits page of the Channel properties
dialog. To configure the channel to run user exits, edit the properties on the Exits page.

380 IBM MQ Explorer

Property Meaning MQSC
parameter
Send exit name Click Edit to open the Edit Send Exit Name dialog. Add the names SENDEXIT
of your send exit programs:

• On AIX and Linux, enter the names

of one or more exit programs. The maximum total length
of all the names together is 999 characters. Use the format
libraryname(functionname), where the maximum number
of characters in a name is 128.

• On Windows, enter the name of one or more exit

programs. The maximum total length of all the names together
is 999 characters. Use the format dllname(functionname),
where the maximum number of characters in a name is 128.

• On IBM i, enter the names of up to 10 exit

programs. Use the format programname libname, where
programname occupies the first 10 characters, and libname
occupies the second 10 characters. Add spaces at the end of
shorter names to bring them up to 10 characters.

• On z/OS, enter the names of up to 8 exit

programs. Use the load module name, where the maximum
number of characters in a name is 8.
• On other platforms, you can specify the name of only one send
exit program for each channel.

Send exit user data Type the data (maximum 32 characters) to be passed to the SENDDATA
channel send exit when the send exit program is called:

• On AIX, Linux, and Windows, type the data for one

or more exit programs. Separate the data with commas. The
maximum total length of the field is 999 characters.

• On IBM i, type up to 10 strings of data, each with a

length of 32 characters. The first string of data is passed to the
first send exit, the second string is passed to the second exit,
and so on.

• On z/OS, type up to 8 strings of data, each with a

length of 32 characters. The first string of data is passed to the
first send exit, the second string is passed to the second exit,
and so on.
• On other platforms, you can specify only one string of send exit
data for each channel.

Introduction to IBM MQ Explorer 381

Property Meaning MQSC
parameter
Receive exit name Click Edit to open the Edit Receive Exit Name dialog. Add the RCVEXIT
names of your receive exit programs:

• On AIX and Linux, enter the names

of one or more exit programs. The maximum total number of
characters in all the names together is 999 characters. Use the
format libraryname(functionname), where the maximum
number of characters in a string is 128.

• On Windows, enter the name of one or more exit

programs. Separate the names with commas. The maximum
total length of the field is 999 characters. Use the format
dllname(functionname), where the maximum number of
characters in a string is 128.

• On Windows, type the names of up to 10 exit

programs. Separate the names with commas. Use the format
programname libname, where programname occupies the
first 10 characters, and libname occupies the second 10
characters. Add spaces at the end of shorter names to bring
them up to 10 characters.

• On z/OS, type the names of up to 8 exit programs.

Separate the names with commas. Use the load module name,
where the maximum number of characters is 8.
• On other platforms, you can specify the name of only one send
exit program for each channel.

Receive exit user data Type the data (maximum 32 characters) to be passed to the RCVDATA
channel receive exit when the receive exit program is called:

• On AIX, Linux, and Windows, type the data for one

or more exit programs. Separate the data with commas. The
maximum total length of the field is 999 characters.

• On IBM i, type up to 10 strings of data, each with a

length of 32 characters. The first string of data is passed to the
first receive exit, the second string is passed to the second exit,
and so on.

• On z/OS, type up to 8 strings of data, each with a

length of 32 characters. The first string of data is passed to the
first receive exit, the second string is passed to the second exit,
and so on.
• On other platforms, you can specify only one string of receive
exit data for each channel.

382 IBM MQ Explorer

Property Meaning MQSC
parameter
Security exit name Type the name of the security exit program: SCYEXIT

• On AIX, Linux, and Windows, use the format

libraryname(functionname), where the maximum number
of characters in a string is 128.

• On IBM i, use the format programname

libname, where programname occupies the first 10 characters,
and libname occupies the second 10 characters. Add spaces at
the end of shorter names to bring them up to 10 characters.

• On z/OS, use the load module name, where the

maximum number of characters is 8.

Security exit user data Type the data (maximum 32 characters) to be passed to the SCYDATA
channel security exit when the channel security exit is called.
Message exit name Click Edit to open the Edit Message Exit Name dialog. Add the MSGEXIT
names of your message exit programs:

• On AIX and Linux, enter the names

of one or more exit programs. The maximum total length
of all the names together is 999 characters. Use the format
libraryname(functionname), where the maximum number
of characters in a name is 128.

• On Windows, enter the name of one or more exit

programs. The maximum total length of all the names together
is 999 characters. Use the format dllname(functionname),
where the maximum number of characters in a name is 128.

• On IBM i, enter the names of up to 10 exit

programs. Use the format programname libname, where
programname occupies the first 10 characters, and libname
occupies the second 10 characters. Add spaces at the end of
shorter names to bring them up to 10 characters.

• On z/OS, enter the names of up to 8 exit

programs. Use the load module name, where the maximum
number of characters in a name is 8.
• On other platforms, you can specify the name of only one
message exit program for each channel.

Introduction to IBM MQ Explorer 383

Property Meaning MQSC
parameter
Message exit user data Type the data (maximum 32 characters) to be passed to the MSGDATA
channel message exit when the channel message exit program
is called:

• On AIX, Linux, and Windows, type the data for one

or more exit programs. Separate the data with commas. The
maximum total length of the field is 999 characters.

• On IBM i, type up to 10 strings of data, each with a

length of 32 characters. The first string of data is passed to the
first channel message exit, the second string is passed to the
second exit, and so on.

• On z/OS, type up to 8 strings of data, each with a

length of 32 characters. The first string of data is passed to the
first channel message exit, the second string is passed to the
second exit, and so on.
• On other platforms, you can specify only one string of channel
message exit data for each channel.

LU6.2 page
The following table lists the properties that you can set on the LU6.2 page of the Channel properties
dialog. If the channel uses the LU 6.2 transport protocol, edit the properties on the LU6.2 page.

Property Meaning MQSC

parameter
Mode name Type the LU 6.2 mode name, which is the SNA mode name unless MODENAME
the value of the Connection name property on the General
page contains a side-object, in which case leave the Mode name
value blank. The maximum length is 8 characters.
TP name Type the name, or the generic name, of the MCA program that is TPNAME
run at the far end of the link.
User ID Type the user identifier that the MCA uses when attempting to USERID
initiate a secure LU 6.2 session with a remote MCA. The maximum
length is 12 characters; however, only the first 10 characters are
used.
Password Click Change channel password, then type in the Change PASSWORD
Password dialog the password that the MCA uses when it
attempts to initiate a secure LU 6.2 session with a remote MCA.
The maximum length is 12 characters.

Retry page
The following table lists the properties that you can set on the Retry page of the Channel properties
dialog. To configure how the channel behaves if the channel cannot connect to the remote queue
manager, edit the properties on the Retry page.

384 IBM MQ Explorer

Property Meaning MQSC
parameter
Short retry count Type the maximum number of times, 0 - 999999999 (or, for z/OS SHORTRTY
using CICS, 1 - 999999999), that the channel can try to connect
to a remote queue manager.
Short retry interval Type the approximate interval, in seconds, that the channel must SHORTTMR
wait before it tries again to connect to the remote queue manager
during the short retry count. A value of 0 means that the channel
tries again immediately.
Long retry count Type the maximum number of times, 0 - 999999999, that the LONGRTY
channel can try to connect to a remote queue manager. The
value of this property is used only when the count specified in
the Short retry count property has been exhausted and the
channel has still not successfully connected to the remote queue
manager.
Long retry interval Type the approximate interval, in seconds, that the channel must LONGTMR
wait before it tries again to connect to the remote queue manager
during the long retry count. A value of 0 means that the channel
tries again immediately.
Keep alive interval The value of the Keep alive interval property specifies the KAINT
time-out value of the channel. To base the keepalive value on
the value of the negotiated heartbeat interval, select Auto. If
the negotiated heartbeat interval is greater than zero, the Keep
alive interval is the negotiated heartbeat interval plus 60
seconds; if the negotiated heartbeat interval is zero, the Keep
alive interval is zero too. To specify a time-out value, type
the number of seconds, 0 - 99999. To disable KeepAlive on this
channel, type 0.

Message retry page

The following table lists the properties that you can set on the Message retry page of the Channel
properties dialog. To configure how the channel behaves if the channel fails the first time that it tries to
put a message on a remote queue, edit the properties on the Message retry page.

Property Meaning MQSC

parameter
Message retry count Type the number of times, 0 - 999999999, that the channel MRRTY
retries to deliver a message before it decides that it cannot
deliver the message to the remote queue. This property controls
the action of the MCA only if the Message retry exit name
property is blank. If the Message retry exit name property
is not blank, the value of the Message retry count property
is passed to the exit for the exit's use but the number of times
that the channel retries to deliver the message is controlled by
the exit, not by the Message retry count property.
Message retry interval Type the minimum length of time, in milliseconds, that the MRTMR
channel must wait before it can try again to put the message on
the remote queue.

Introduction to IBM MQ Explorer 385

Property Meaning MQSC
parameter
Message retry exit name Type the name of the channel message retry exit program: MRDATA

• On AIX and Linux, use the format

libraryname(functionname), where the maximum number
of characters in a string is 128.

• On Windows, use the format

dllname(functionname), where the maximum number of
characters in a string is 128.

• On IBM i, use the format programname

libname, where programname occupies the first 10 characters,
and libname occupies the second 10 characters. Add spaces at
the end of shorter names to bring them up to 10 characters.

• On z/OS, use the load module name, where the

maximum number of characters is 8.

Message retry exit user Type the data (maximum 32 characters) that is passed to the MREXIT
data channel message retry exit when the channel message retry exit
is called.

Cluster page
The following table lists the properties that you can set on the Cluster page of the Channel properties
dialog. To share the channel in one or more clusters, edit the properties on the Cluster page.
Note: Specify the cluster channel properties on the cluster-receiver channels at the target queue
managers. Any properties you specify on the matching cluster-sender channels are likely to be ignored.
See Cluster channels.

Property Meaning MQSC

parameter
Not shared in a cluster By default, this option is selected so that the channel is not Not applicable.
shared in any clusters.
Shared in cluster To share the channel in a cluster, select this option, then type CLUSTER
the name of the cluster. See “Strings in property dialogs” on page
553.
Shared in a list of clusters To share the channel in more than one cluster, select this option, CLUSNL
then type the name of the namelist object that contains the
names of the clusters. See “Strings in property dialogs” on page
553.
Network priority The value of this property indicates the channel priority for the NETPRTY
network connection. Type the value, 0 - 9; 0 is the lowest priority.
See NETPRTY channel property.
CLWL channel rank Type the rank of the channel in the cluster, 0 - 9; 0 is the lowest CLWLRANK
rank. See CLWLRANK channel property.
CLWL channel priority Type the priority of the channel in the cluster, 0 - 9; 0 is the lowest CLWLPRTY
priority. See CLWLPRTY channel property.

386 IBM MQ Explorer

Property Meaning MQSC
parameter
CLWL channel weight Type the weighting that is applied to the channel so that the CLWLWGHT
proportion of messages that is sent through the channel is
controlled. The value must be 1 - 99; 1 is the lowest weighting.
See CLWLWGHT channel property.

SSL page
The following table lists the properties that you can set on the SSL page of the Channel properties dialog.
To configure the channel to use SSL security, edit the properties on the SSL page.

Property Meaning MQSC

parameter
CertificateLabel Certificate label for this channel to use. The label identifies which CERTLABL
personal certificate in the key repository is to be sent to the
remote peer. If this property is blank, the certificate is determined
by the queue manager CertificateLabel property.
CipherSpec Type the name (maximum 32 characters) of the CipherSpec for a SSLCIPH
TLS connection. Both ends of the IBM MQ SSL channel definition
must have the same value in the CipherSpec property. For more
information, see the SSLCIPH property in DEFINE CHANNEL.
The value for this parameter is also used to set the value of
the Security Protocol property, which is an output field on the
Channel status attributes page.

Authentication of parties To specify that the channel must receive and authenticate an SSLCAUTH
initiating connections TLS certificate from an TLS client, select Required; to specify
that the channel is not required to receive and authenticate an
TLS certificate from an TLS client, select Optional; if you select
Optional and the peer TLS client sends a certificate, the channel
authenticates the certificate as normal.
Peer Issuer Name Certificate issuer Distinguished Name filter. This field contains a SSLCERTI
Distinguished Name filter which matches the Issuer DN of the
remote peer personal certificate. Peer Issuer Name is a key field
in the SSL Peer Map, that is, is used to match channel authority
records for inbound channel connections.
Accept only certificates Type the value of the Distinguished Name on the certificate from SSLPEER
with Distinguished Names the peer queue manager or client at the other end of the IBM MQ
matching these values channel. When the channel starts, the value of this property is
compared with the Distinguished Name of the certificate.
Accept only certificates This channel authentication record maps TLS Distinguished SSLPEERMAP
with Distinguished Names Names (DNs) to MCAUSER values. The SSLPEERMAP parameter
matching these values must be accompanied by an SSLPEER.

Load Balancing page

The following table lists the properties that you can set on the Load Balancing page of the Channel
properties dialog.

Introduction to IBM MQ Explorer 387

 MQSC
Property Meaning parameter
Weight The client channel weighting property is used to specify a CLNTWGHT
weighting to influence which client-connection channel definition
is used. The client channel weighting property is used so that
client channel definitions can be selected at random based
on their weighting when more than one suitable definition is
available.
When a client issues an MQCONN requesting connection to a
queue manager group, by specifying a queue manager name
starting with an asterisk, and more than one suitable channel
definition is available in the client channel definition table (CCDT),
the definition to use is randomly selected based on the weighting,
with any applicable CLNTWGHT(0) definitions selected first in
alphabetical order. Specify a value in the range 0 - 99. The
default is 0. A value of 0 indicates that no load balancing is
performed and applicable definitions are selected in alphabetical
order. To enable load balancing choose a value in the range 1 -
99 where 1 is the lowest weighting and 99 is the highest. The
distribution of messages between two or more channels with
non-zero weightings is approximately proportional to the ratio of
those weightings.

Affinity The channel affinity property is used so client applications that AFFINITY
connect multiple times using the same queue manager name can
choose whether to use the same client channel definition for each
connection. Use this property when multiple applicable channel
definitions are available. The possible values are:
PREFERRED. This is the default value. The first connection in a
process reading a client channel definition table (CCDT) creates a
list of applicable definitions based on the client channel weight,
with any definitions having a weight of 0 first and in alphabetical
order. Each connection in the process attempts to connect using
the first definition in the list. If a connection is unsuccessful
the next definition is used. Unsuccessful definitions with client
channel weight values other than 0 are moved to the end of the
list. Definitions with a client channel weight of 0 remain at the
start of the list and are selected first for each connection. Each
client process with the same host name creates the same list.
NONE. The first connection in a process reading a CCDT creates a
list of applicable definitions. All connections in a process select
an applicable definition based on the client channel weight, with
any definitions having a weight of 0 selected first in alphabetical
order.

Statistics page
The following table lists the properties that you can set on the Statistics page of the Channel properties
dialog. To configure the channel to collect monitoring or statistics data, edit the properties on the
Statistics page.

388 IBM MQ Explorer

Property Meaning MQSC
parameter
Alteration date Read-only. This is the date on which the queue properties were ALTDATE
last altered.
Alteration time Read-only. This is the time at which the queue properties were ALTTIME
last altered.
Channel monitoring You can configure IBM MQ to collect online monitoring data about MONCHL
the current performance of the channel. To inherit the value of the
queue manager's Channel monitoring property (see “Queue
manager properties” on page 315), click Queue manager. If the
queue manager's Channel monitoring property is None, the
queue's Channel monitoring property is ignored. If the queue
manager's Channel monitoring property is not None: to
override the queue manager settings and prevent data collection
for this channel, click Off; to collect data at a low rate, click Low;
to collect data at a medium rate, click Medium; to collect data at
a high rate, click High.
Channel statistics You can configure IBM MQ to collect statistics data about STATCHL
the activity of the channel. To inherit the value of the
queue manager's Channel statistics property (see Queue
Manager properties), click Queue manager. If the queue
manager's Channel statistics property is None, the queue's
Channel statistics property is ignored. If the queue
manager's Channel statistics property is not None, to
override the queue manager settings and prevent data collection
for this channel, click Off; to collect data at a low rate, click Low;
to collect data at a medium rate, click Medium; to collect data at
a high rate, click High.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Listener properties
You can set properties for all types of listeners. Some properties are specific to certain types of listener.
The following table lists all the properties that you can set.
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY LISTENER
commands. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.

General page
The following table lists the properties that you can set on the General page of the Listener properties
dialog.

Introduction to IBM MQ Explorer 389

Property Meaning MQSC
parameter
Listener name Read-only. You cannot change the name of the listener after it has LISTENER
been created.
Description Type a meaningful description of the purpose of the listener. See DESCR
Entering strings in MQ Explorer.
Control To configure the listener to start and stop when the queue CONTROL
manager starts and stops, click Queue Manager; to configure the
listener to start when the queue manager starts but not stopped
when the queue manager is stopped, click Queue Manager Start;
to configure the listener so that it does not start automatically and
must be started manually, click Manual.
Transmission protocol Read-only. This property shows the transport protocol that the TRPTYPE
listener uses. To use a different transport protocol, you must
create a new listener object; you cannot change the transport
protocol of an existing listener object.
Port Type the port number on which the listener listens for PORT
connections.
IP address Type the name of the computer on which the listener listens IPADDR
for connections. You can use any of the following formats:
IPv4 dotted decimal, IPv6 hexadecimal, or the fully qualified
host name, for example joho.hursley.ibm.com. If no value
is specified, the listener listens on all available IPv4 and IPv6
addresses.
TP Name Type the LU 6.2 transaction program name. TPNAME
Adapter Type the number of the adapter on which NetBIOS listens. The ADAPTER
default value is adapter 0.
Local Name Type the NetBIOS local name that the listener uses. The default LOCLNAME
value is defined by the protocol.
Name count Type the number of names that the listener can use. The default NTBNAMES
value is defined by the protocol.
Session count Type the number of sessions that the listener can use. The default SESSIONS
value is defined by the protocol.
Command count Type the number of commands that the listener can use. The COMMANDS
default value is defined by the protocol.
Backlog Type the maximum number of concurrent connection requests BACKLOG
that the listener supports. The default value is defined by the
protocol.
Socket Type the number of the SPX socket on which the listener listens SOCKET
for connections. The default value is hexadecimal 5E86.
Listener status Read-only. This property shows the current status of the listener, STATUS
which can be Running, Starting, or Stopping.
Alteration date Read-only. This property shows the date on which the listener's ALTDATE
properties were last altered.
Alteration time Read-only. This property shows the time at which the listener's ALTTIME
properties were last altered.

390 IBM MQ Explorer

 General page for z/OS listeners

Z/OS listener properties cannot be altered once the listener has been defined. The properties are set
when you add a new z/OS listener.

Property Meaning MQSC

parameter
Listener status Read-only. This property shows the current status of the listener, STATUS
which can Running, Starting, Retrying, or Stopping.
Transmission protocol Read-only. This property shows the transport protocol that the TRPTYPE
listener uses. To use a different transport protocol, you must
create a new listener; you cannot change the transport protocol of
an existing listener object.
Port number Read-only. The port number on which the listener listens for PORT
connections.
IP address Read-only. The name of the computer on which the listener IPADDR
listens for connections.
Inbound Read-only. This property Specifies the disposition of the inbound INDISP
transmissions that are to be handled. The possible values are:
Group or Queue Manager.
LU name Read-only. The LU name of the listener, you can set it when you LUNAME
define the listener.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Topic properties
An IBM MQ topic is an IBM MQ object that identifies what a publication is about. You can set properties
for topics. Some topic properties are specific to z/OS topics. Also, there are some properties that you can
alter only while you are creating a topic. You cannot modify these properties after the IBM MQ topic has
been created.
The following tables list all the properties for IBM MQ Topics.
For each property, there is a brief description of when you might need to configure the property. The
tables also give the equivalent MQSC parameters for the DEFINE, ALTER and DISPLAY TOPIC commands.
For more information about MQSC commands, see Administering IBM MQ using MQSC commands.

General
The following table lists the properties on the General page of the IBM MQ Topic Properties dialog.

Introduction to IBM MQ Explorer 391

 MQSC
Property Meaning parameter
Topic name This value cannot be changed after the topic has been created. TOPNAME
This parameter is required and cannot contain an empty string.
The unique identifier of the administrative topic definition to be
created. A maximum of 48 characters are allowed.
Topic name must not be the same as any other topic definition
defined on the selected queue manager.

Topic type This value is read only. This value defines whether the topic is N/A
local; Local, or in a cluster; Cluster.
Topic String This value cannot be changed after the topic has been created. TOPICSTR
This parameter is required and cannot contain an empty string.
The / character within this string has special meaning. It delimits
the elements in the topic tree. A topic string can start with
the / character but is not required to. A string starting with the /
character is not the same as the string which starts without the /
character.
Topic String must not be the same as any other topic string
already represented by another topic object definition. The
maximum length of a topic string is 10 240 characters.

Description This value is a string entered by the administrator. It contains DESC

descriptive information about the topic. It must contain only
displayable characters. A maximum of 64 characters.
If characters are used that are not in the coded character set
identifier (CCSID) for the selected queue manager, then they
might be translated incorrectly if the information is sent to
another queue manager.

Publish This property controls whether messages can be published to PUB

the topic. The default value is As parent. The 2 other options
available are:
Allowed which means that messages can be published to the
topic by an authorized application.
Inhibited which means that messages cannot be published to
the topic.

Subscribe This property controls whether messages can subscribe to the SUB
topic. The default value is As parent. The 2 other options
available are:
Allowed which means that subscriptions can me made to the
topic by an authorized application.
Inhibited which means that applications cannot subscribe to
the topic.

392 IBM MQ Explorer

 MQSC
Property Meaning parameter
Durable subscriptions This property controls whether the topic permits durable DURSUB
subscriptions to be made. The default value is As parent. The 2
other options available are:
Allowed which means that durable subscriptions can me made
to the topic by an application.
Inhibited which means that durable subscriptions cannot be
made to the topic by an application.

Default priority The default priority of messages published to the topic. The DEFPRTY
default value is As parent.
The default priority can be set from 0 (the lowest priority) to 9
(the highest priority)

Default persistence The default persistence of a new topic is As parent. Select DEFPSIST
Persistent to specify that messages created by applications
that use MQPER_PERSISTENCE_AS_Q_DEF become persistent.
Select Not Persistent to specify that messages created by
applications that use MQPER_PERSISTENCE_AS_Q_DEF become
nonpersistent.
Model durable queue This value is a string entered by the administrator. It contains MDURMDL
the name of the model queue used for durable subscriptions that
request that the queue manager manages the destination of its
publications.
A maximum of 48 characters are allowed for the name.
If this field is blank, then it is treated as As parent
If you are specifying a model queue for a clustered topic, you
must ensure that the queue is defined on every queue manager
in the cluster where a durable subscription using this topic can be
made.
The dynamic queue created from this model has a prefix of
SYSTEM.MANAGED.DURABLE

Model non-durable queue This value is a string entered by the administrator. It contains the MNDURMDL
name of the model queue used for nondurable subscriptions that
request that the queue manager manages the destination of its
publications.
A maximum of 48 characters are allowed for the name.
If this field is blank, then it is treated as As parent
If you are specifying a model queue for a clustered topic, you
must ensure that the queue is defined on every queue manager in
the cluster where a non-durable subscription using this topic can
be made.
The dynamic queue created from this model has a prefix of
SYSTEM.MANAGED.NDURABLE

Introduction to IBM MQ Explorer 393

 MQSC
Property Meaning parameter
QSG disposition The queue sharing group disposition of the topic. You can set the QSGDISP
queue sharing group disposition to one of three values:
• Queue manager means that the object definition is available
only to the queue manager that hosts it.
• Group means that the object definition is stored on the shared
repository and each queue manager in the queue sharing group
has a copy of the definition.
• Copy means that the object definition is the queue manager's
copy of a definition in the shared repository.
The field is displayed as read only when you are displaying the
properties of a topic.
Default put response type The default response type for message puts. The default value is DEFPRESP
As parent. The 2 other options available are:
Synchronous which means the response is put synchronously.
Asynchronous which means the response is put
asynchronously.

Non-persistent message The delivery method for non-persistent messages published to NPMSGDLV
delivery this topic. The 4 options are:
As parent The delivery mechanism used is based on the setting
of the first parent administrative node found in the topic tree
relating to this topic. This is the default supplied with IBM MQ, but
your installation might have changed it.
To all available subscribers Non-persistent messages
are delivered to all subscribers that can accept the message.
Failure to deliver the message to any subscriber does not prevent
other subscribers from receiving the message.
To all durable subscribers Non-persistent messages
must be delivered to all durable subscribers. Failure to deliver a
non-persistent message to any non-durable subscribers does not
return an error to the MQPUT call. If a delivery failure to a durable
subscriber occurs, no other subscribers receive the message and
the MQPUT calls fails.
To all subscribers Non-persistent messages must be
delivered to all subscribers, irrespective of durability for the
MQPUT call to report success. If a delivery failure to any
subscriber occurs, no other subscribers receive the message and
the MQPUT call fails.

394 IBM MQ Explorer

 MQSC
Property Meaning parameter
Persistent message The delivery method for persistent messages published to this PMSGDLV
delivery topic. The four options are:
As parent The delivery mechanism used is based on the setting
of the first parent administrative node found in the topic tree
relating to this topic. This is the default supplied with IBM MQ, but
your installation might have changed it.
To all available subscribers Persistent messages are
delivered to all subscribers that can accept the message. Failure
to deliver the message to any subscriber does not prevent other
subscribers from receiving the message.
To all durable subscribers Persistent messages must be
delivered to all durable subscribers. Failure to deliver a persistent
message to any non-durable subscribers does not return an error
to the MQPUT call. If a delivery failure to a durable subscriber
occurs, no other subscribers receive the message and the MQPUT
calls fails.
To all subscribers Persistent messages must be delivered
to all subscribers, irrespective of durability for the MQPUT call to
report success. If a delivery failure to any subscriber occurs, no
other subscribers receive the message and the MQPUT call fails.

Wildcard operation This value controls the behavior of wildcard subscriptions with WILDCARD
respect to the topic. The 2 values are:
Block. Subscriptions made to a wildcard topic less specific than
the topic string for this topic object, do not receive publications
made to this topic or to topic strings more specific that this topic.
Passthrough. Subscriptions made to a wildcard topic less
specific than the topic string for this topic object receive
publications made to this topic and to topic strings more specific
than this topic. This is the default value.

Use dead-letter queue Specifies whether the dead-letter queue is used when publication USEDLQ
messages cannot be delivered to their correct subscriber queue.
There are three possible values:
• No means that publication messages that cannot be delivered
to their correct subscriber queue are treated as a failure to
put the message, and the application's MQPUT to a topic fails
in accordance with the settings of Non-persistent message
delivery and Persistent message delivery.
• Yes means that if the queue manager Dead-letter queue
property provides the name of a Dead Letter Queue, then it is
used. Otherwise the behavior is as for No.
• As parent means that the decision to use the Dead Letter
Queue is based on the setting of the closest administrative topic
object in the topic tree. This is the default supplied with IBM MQ
but your installation might have changed it.

Introduction to IBM MQ Explorer 395

 MQSC
Property Meaning parameter
Custom The Custom parameter is included for IBM use only, reserved CUSTOM
for the configuration of new features before separate properties
have been introduced. The possible values are a list of zero or
more properties-value pairs, in MQSC-style syntax, separated by
at least one space.
The property names and values are case-sensitive, and must
be specified in uppercase. The values can contain spaces,
parentheses and single-quotes (which must be escaped with
another single-quote). Other characters, including nested
parentheses (), can be included by enclosing them in two single-
quotes on either side. Examples of valid syntax are:
• CUSTOM('')
• CUSTOM('A(B)')
• CUSTOM('C(D) E(F)')
• CUSTOM('G(5000) H(''9.20.4.6(1415)'')')
The queue manager parses the value, but if the string cannot be
parsed according to these rules, or if it contains properties or
values that are not recognized, the queue manager ignores the
errors.

The maximum time, expressed in tenths of a second, until a CAPEXPRY

Cap expiry
message published to a topic which inherits properties from this
object, remains in the system until it becomes eligible for expiry
processing.
For more information on message expiry processing, see
Enforcing lower expiration times.
integer
The value must be in the range one through to 999 999 999.
NOLIMIT
There is no limit on the expiry time of messages put to this
topic.
ASPARENT
The maximum message expiry time is based on the setting of
the closest parent administrative topic object in the topic tree.
This is the default value.

Distributed Pub/Sub
The following table lists the properties on the Distributed Pub/Sub page of the IBM MQ Topic Properties
dialog.

396 IBM MQ Explorer

Property Meaning MQSC
parameter
Proxy subscription Proxy-subscriptions are associated with the queue manager PROXYSUB
behavior name that created them. Publications are only forwarded to
directly connected queue managers if a proxy-subscription exists
that includes the publication topic. The two options for this value
are:
Force. This forces the sending of a wild-carded proxy-
subscription for the topic string associated with this topic object
from every queue manager in the cluster to every other queue
manager in the pub/sub topology, regardless of whether any
local subscriptions have been made. Once this forced proxy
subscription has been propagated throughout the topology,
any new subscriptions immediately receive any publications
from other connected queue manager without suffering latency,
although all publications are propagated to all other queue
managers in the cluster regardless of whether a subscription has
requested them or not.
Setting this value at a given level in the topic tree also prevents
proxy subscriptions being generated for individual topic strings
at subsequent levels in the topic tree, reducing the proxy
subscription overhead.
First use. For each unique topic string at or beneath this
topic object, a proxy subscription is asynchronously sent to all
neighboring queue managers in the following scenarios:
• When a local subscription is created.
• When a proxy subscription is received that must be propagated
to further directly connected queue managers.

Publication scope The scope of publications can be controlled administratively using PUBSCOPE
the PUBSCOPE topic attribute. The attribute can be set to one of
the following 3 values:
• As parent. This is the default value. The publication scope is
set to the same value as the parent queue manager.
• Queue manager. The publication is only delivered to local
subscribers.
• All. The publication is delivered to local subscribers and
remote subscribers by directly connected queue managers.

Subscription scope The scope of subscriptions can be controlled administratively SUBSCOPE

using the SUBSCOPE topic attribute. The attribute can be set to
one of the following 3 values:
• As parent. This is the default value. The subscription scope is
set to the same value as the parent queue manager.
• Queue manager. The subscription receives only local
publications, and proxy subscriptions are not propagated to
remote queue managers.
• All. A proxy subscription is propagated to remote queue
managers, and the subscriber receives local and remote
publications.

Introduction to IBM MQ Explorer 397

Property Meaning MQSC
parameter
Multicast This property controls whether the topic is considered to be MCAST
transmittable with multicast or not. There are four possible
values:
As parent. The multicast property of the topic is inherited from
the parent.
Disabled. No multicast traffic is allowed at this node.
Enabled. Multicast traffic is allowed at this node.
Only. Only subscriptions from a multicast capable client are
allowed.

Communication The communication information object name. As there are more COMMINFO
information than one topics in the tree which require the same multicast
transmission properties, consider having these properties in a
separate object which can be referenced.

Cluster
The following table lists the properties on the Cluster page of the IBM MQ Topic Properties dialog.

Property Meaning MQSC

parameter
Cluster name To make a topic a cluster topic, you configure this property. When CLUSTER
you do this, any topic used by a publisher or subscriber at that
point or in the topic tree is shared across all queue managers
in the cluster, and messages published to a clustered branch of
the topic tree are automatically routed to subscriptions on other
queue managers in the cluster.
Cluster object state The current state of this topic object in this cluster. The values CLSTATE
can be as follows:
ACTIVE
The cluster topic is correctly configured and being adhered to
by this queue manager.
PENDING
Only seen by a hosting queue manager, this state is reported
when the topic has been created but the full repository has
not yet propagated it to the cluster. This might be because the
host queue manager is not connected to a full repository, or
because the full repository has deemed the topic to be invalid.
INVALID
This clustered topic definition conflicts with an earlier
definition in the cluster and is therefore not currently active.
ERROR
An error has occurred with respect to this topic object.
This parameter is typically used to aid diagnosis when multiple
definitions of the same clustered topic are defined on different
queue managers, and the definitions are not identical.

398 IBM MQ Explorer

Property Meaning MQSC
parameter
Cluster route The routing behavior to use for topics in the cluster defined by the CLROUTE
CLUSTER parameter. There are two possible values:
DIRECT
When you configure a direct routed clustered topic on a queue
manager, all queue managers in the cluster become aware
of all other queue managers in the cluster. When performing
publish and subscribe operations, each queue manager then
connects directly to all the others.
TOPICHOST
When you use topic host routing, all queue managers in the
cluster become aware of the cluster queue managers that
host the routed topic definitions. When performing publish
and subscribe operations, queue managers in the cluster
connect only to these topic host queue managers, and not
directly to each other. The topic host queue managers are
responsible for routing publications from queue managers on
which publications are published to queue managers with
matching subscriptions.

Statistics
The following table lists the properties on the Statistics page of the IBM MQ Topic Properties dialog.

Property Meaning MQSC

parameter
Alteration date This value cannot be changed, it is provided for information ALTDATE
purposes only.
This is the date on which the topic properties were last altered.

Alteration time This value cannot be changed, it is provided for information ALTTIME
purposes only.
This is the time at which the topic properties were last altered.

Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Comparing the properties of two objects” on page 39
You can compare the properties of an object with another object of the same type; for example, compare
a queue with another queue, a topic with another topic, or a channel with another channel.

Service properties
You can configure properties for custom service objects in the Service properties dialog.
The following table lists all the properties that you can set.
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY SERVICE
commands. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.

Introduction to IBM MQ Explorer 399

 General page
The following table lists the properties that you can set on the General page of the Service properties
dialog.

Property Meaning MQSC

parameter
Service name Read-only. This property shows the name of the service. SERVICE
Description Type a meaningful description of the purpose of the service. See DESCR
Entering strings in IBM MQ Explorer.
Service control To configure the service to start and stop automatically when CONTROL
the queue manager starts and stops, click Queue Manager; to
configure the service to start automatically when the queue
manager starts but not to stop when the queue manager stops,
click Queue Manager Start; to configure the service so that you
must manually start and stop it, click Manual.
Start command Type the fully-qualified path to the start command program STARTCMD
that runs when the service starts; for example, C:\Program
Files\IBM\WebSphere MQ\bin\runmqchi.exe
Start args Type any arguments that are to be passed to the program when it STARTARG
starts.
Stop command Type the fully-qualified path to the stop command program that STOPCMD
runs when the service stops.
Stop args Type any arguments that are to be passed to the program when it STOPARG
stops.
StdOut Type the path to the file to which the standard output of the STDOUT
service program is written. If the file does not exist when the
service program is started, the file is created; if the file already
exists, the new standard output is appended to the existing file.
If the value of this property is blank, the standard output is
discarded.
StdErr Type the path to the file to which the standard error of the service STDERR
program is written. If the file does not exist when the service
program is started, the file is created; if the file already exists, the
new standard error is appended to the existing file. If the value of
this property is blank, the standard error is discarded.
Service type To enable only one instance of the service to run at a time, click SERVTYPE
Server; to enable multiple instances of the service to run at a
time, click Command.
Service status Read-only. This property shows the current status of the service. STATUS

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553

400 IBM MQ Explorer

 To include certain characters in a string, you must punctuate the string in a particular way.

IBM MQ service definition properties

You can set properties and attributes for service definitions while creating a new service definition, or
when editing an existing service definition.
Some attributes will only be available when the service definition is of a specific binding type or message
exchange pattern. Follow these links to view the properties for the individual property pages of a service
definition:
• General
• Operation
• Input destination
• Input message schema
• Input message header
• Output destination
• Output message schema
• Output message header
For each attribute, there is a brief description of when you might need to configure the attribute.

General page
The following table lists the attributes you can set on the General page of the Service definition
properties dialog.

Attribute Description
Namespace Specifies the namespace for the service. There is
already a temporary default value assigned.
Name A unique name for the new Service Definition. The
service definition name is not case sensitive, but a
mixed-case service definition name is retained.
Message exchange pattern The Message Exchange Pattern describes the direction
of messages sent and received during the invocation of
a service. There are two possible selections:
• One-Way means that a message is sent one way
only.
• Request-Response means that a message is sent
and a response is received.

Binding type Specifies the version of the IBM MQ service definition

specification.
Comment Specify a comment to annotate the service in the
WSDL file.

Operation page
The following table lists the attributes you can set on the Operation page of the Service definition
properties dialog. Each service definition has only 1 operation.

Introduction to IBM MQ Explorer 401

Attribute Description
Operation name Specifies the name of the operation. This property
must have a value to create a service definition.
Action Used by the service provider to dispatch service
requests. For example: Allowing multiple services to
be deployed using a single destination, enabling a
service provider to dispatch the requests arriving on
the destination appropriately.
When the binding type is MQ, Action specifies
targetAction.

Comment Specify a comment to annotate the operation in the

WSDL file.

Input destination page

The following table lists the attributes you can set on the Input Destination page of the Service
definition properties dialog. The input pages define the details of the message that the service expects,
and the destination where it will be retrieved from.

Attribute Description
Input destination name Specifies the name of the destination queue or the
destination topic to which the request is sent, for
example:
The queue-dest or topic-dest particle of an IBM MQ
IRI, such as:

msg/queue/INS.QUOTE.REPLY

Destination queue manager name Specifies the name of the destination queue manager.
Connection queue manager Specifies the name of the queue manager to which the
requesting service connects to. This corresponds to
the QmgrName parameter used on the MQCONN() and
MQCONNX() calls.
Client connection properties The client connection properties specify detailed
bindings which can include information about how
a service requester binds to a specific machine or
channel. Being able to specify client-bindings and
channel names is useful in some circumstances,
but over-specifying the service might be restrictive
however. A solution to this problem is to minimize
the amount of binding information incorporated into
a service definition and allow underlying infrastructure
or IBM MQ to route messages where possible.

402 IBM MQ Explorer

Attribute Description
Channel table name Specifies the name of the client channel table file
which is used to identify the channel connection.
• If Channel table name is not specified, then
Channel table library is ignored.
• If either of the MQSERVER or MQCHLTAB
environment variables are set in the environment
where the client application is running, then
Channel table name is ignored.

Channel table library Specifies the path to the client channel table.
• If either MQSERVER or MQCHLLIB environment
variables are set in the environment where the
client application is running, then Channel table
library is ignored.
• If Channel table name is not specified, then
Channel table library is ignored.

Client channel connection name Specifies the connection string used when a service
requester makes an IBM MQ MQI client-binding
connection. For TCP/IP, the connection is in the form
of a host name followed by a port number, for
example:

OS2ROG3(1822)

If the port number is not specified, a default value of

1414 is used.
• If the Client channel connection name is
specified, then the Client channel name and
Client channel transport type must also be
specified.
• If either MQSERVER or MQCHLTAB environment
variable are set in the environment where the
client application is running, then Client channel
connection name is ignored.

Client channel name Specifies the channel used when an IBM MQ service
requester make an IBM MQ MQI client-binding
connection.
• If the Client channel connection name is
specified, then the Client channel name and
Client channel transport type must also be
specified.
• If either MQSERVER or MQCHLTAB environment
variable are set in the environment where the
client application is running, then Client channel
name is ignored.

Introduction to IBM MQ Explorer 403

Attribute Description
Client channel transport type Specifies the transport type to be used when an IBM
MQ service requester makes an IBM MQ MQI client-
binding connection.
• If the Client channel connection name is
specified, then the Client channel name and
Client channel transport type must also be
specified.
• If either MQSERVER or MQCHLTAB environment
variable are set in the environment where the client
application is running, then Transport type is
ignored.
There are two different selectable values:
• TCP. Used to specify the TCP/IP transport protocol.
This is the default value.
• LU62. Used to specify the LU6.2 transport protocol.

Input message schema page

The following table lists the attributes you can set on the Input message schema page of the Service
definition properties dialog. They allow the schema for the message payload to be defined.

Attribute Description
Inbound data type Specifies the expected inbound data type. For simple
types, this can be modelled using the built-in XML
xsd types such as xsd:string or xsd:int. For more
complex types, a data type can be imported from an
external file by specifying the Import schema file
and Import namespace for the data type.
Import schema file Specifies the schema file to be imported.
Import namespace Specifies the namespace to be imported.

Input message header page

The following table lists the attributes you can set on the Input message header page of the Service
definition properties dialog. The input pages define the details of the message that the service expects,
and the destination where it will be retrieved from. Some of the properties only apply to service
definitions of an MQ binding type.

Attribute Description
CCSID Specifies the Coded Character Set ID which
corresponds to the CodedCharSetId field in the MQMD
structure. If this value is not specified, then the
service requester and service provider uses the
value which corresponds to the character set of the
message data.

404 IBM MQ Explorer

Attribute Description
Format Specifies the format name of the message data. This
property corresponds to the MQRFH2 format field,
or the MQMD format field if there is no MQRFH2 is
present. The value must be a character string between
0 and 8 characters long consisting of the A-Z and 0-9
characters.
The Format can be set to any value according to the
guidelines in the Format field.

User properties Specifies the user defined data carried in IBM MQ

service messages. Values must be specified in the
format allowed for RFH2 folder elements; in a series
of triplets encoded using an XML-like syntax such as:

<name dt="datatype">value</name>

The dt="datatype" element is optional, and if it is

omitted, it is treated as a string, allowing elements to
be specified as:

<name>value</name>

For example:

<myprop1>value1</myProp1><myprop2>value2</
myProp2><myprop3 dt="i4">99</myProp3>

For further information on the allowed data types and

formatting, see NameValueData ( MQCHARn ). It is not
recommended to include security sensitive properties
such as UserId or passwords.
Message type Specifies the type of message that is sent. This
property corresponds to the MsgType in the MQMD
structure. The five possible values are:
• Unspecified which means that no value is set,
therefore the value is taken from the value of the
Message exchange pattern. This is the default
value.
• Request which means that the message is one that
requires a reply. This value indicate that the service
uses a request-response message exchange pattern.
• Reply which means that the message is a reply to a
request.
• Report which means that the message is a report.
• Datagram which means that the service is a one-
way message exchange and there will not be a reply.
If no value is specifies, the value is set according to
the Message Exchange Pattern.

Introduction to IBM MQ Explorer 405

Attribute Description
Persistence Specifies whether the message is persistent or not,
and it corresponds to the Persistence field in the MQMD
structure. The three possible values are:
• Not persistent which means that the messages
are not persistent.
• Persistent which means that the messages are
persistent.
• Queue default which means that the queue
manager determines the message persistence from
the definition of the destination that the message is
put to. This is the default value.

Message ID Specifies the Message identifier which corresponds to

the MsgId field in the MQMD structure.
The Message ID allows certain specialized IBM MQ
applications to be described as services (for example:
applications that share an input queue and select
the messages intended for them based on a pre-
defined msgId value). Predefined msgIds in service
definitions might lead to problems such as when a
request-response Message Exchange Pattern return
the request's msgId.
The Message Id can be either a character string or a
binary value. Binary values must be a string of up to 24
pairs of two-character hexadecimal values.
Click Edit to open a dialog and enter a value as text or
bytes

Correlation ID Specifies the Correlation ID corresponds to the

CorrelId field in the MQMD structure. The Correlation
ID can be either a character string or a binary value.
Binary values must be a string of up to 24 pairs of
two-character hexadecimal values.
Click Edit to open a dialog and enter a value as text or
bytes

Expiry Specifies the message lifetime. It must be a signed

integer, and it is measured in tenths of a second. The
Expiry range is from 1 to 2 147 483 647.
A special value of Unlimited is used to indicate that
the message does not expire. The value of -1 is written
to the WSDL file.
A value of Unspecified means that no value is
written to the WSDL file. This is the default value.

406 IBM MQ Explorer

Attribute Description
Priority Specifies the priority associated with the message and
corresponds to the priority field in the MQMD structure.
It must be specified as an integer between 0 and 9,
with 0 as the lowest priority and 9 as the highest
priority.
A special value of Unlimited is used to indicate that
the message priority is taken from the definition of the
first queue that the message is put to. The value of -1
is written to the WSDL file.
A value of Unspecified means that no value is
written to the WSDL file. This is the default value.

Encoding Specifies the numeric encoding of message data,

which corresponds to the Encoding field in the MQMD
structure:
• Integer allows you to select Normal or Reversed
• Decimal allows you to select Normal or Reversed
• Float allows you to select Normal, Reversed, or
S390
• Mnemonic specifies the 3 character mnemonic
based on the other values selected. R = Reversed,
N = Normal, and 3 = S390.
• Value specifies the numeric value of the selections
and mnemonic.

Report options Specifies how the message and correlation identifiers

in the reply message or fault message are set by
the service provider. This property corresponds to the
Report field in the MQMD structure. There are four
possible values:
• New message ID indicates that if a report or reply
is generated as a result of this message, a new
msgId is generated for the report or reply message.
• Pass Message ID indicates that if a report or reply
is generated as a result of this message, then the
msgId of this message is copied to the msgId of the
report or reply message.
• copy Message ID to Correlation ID
indicates that if a report or reply is generated as
a result of this message, then the msgId of this
message is copied to the correlId of the report or
reply message.
• Pass Correlation ID indicates that if a report
or reply is generated as a result of this message,
then the correlId of this message is copied to the
correlId of the report or reply message.

Output destination page

The following table lists the attributes you can set on the Output destination page of the Service
definition properties dialog. The output pages define the details of the message that the service will send

Introduction to IBM MQ Explorer 407

 in response to the input message, and the destination where it will be put. The output destination name
must be prefixed with 'msg/queue/' for queues, or 'msg/topic/' for topics.

Attribute Description
Output destination name Specifies the name of the destination queue or the
destination topic to which the response message
is sent, and corresponds to the ReplyToQ and
ReplyToQMgr fields of the MQMD structure. The
Destination Name must take the form of either the
queue-dest or topic-dest particle of an IBM MQ URI,
such as:

msg/queue/INS.QUOTE.REPLY

Destination queue manager name Specifies the name of the destination queue manager.
Connection queue manager Specifies the name of the queue manager to which the
requesting service connects to. This corresponds to
the QmgrName parameter used on the MQCONN() and
MQCONNX() calls.
Client connection properties The client connection properties specify detailed
bindings which can include information about how
a service requester binds to a specific machine or
channel. Being able to specify client-bindings and
channel names is useful in some circumstances,
but over-specifying the service might be restrictive
however. A solution to this problem is to minimize
the amount of binding information incorporated into
a service definition and allow underlying infrastructure
or IBM MQ to route messages where possible.
Channel table name Specifies the name of the client channel table file
which is used to identify the channel connection.
• If Channel table name is not specified, then
Channel table library is ignored.
• If either of the MQSERVER or MQCHLTAB
environment variables are set in the environment
where the client application is running, then
Channel table name is ignored.

Channel table library Specifies the path to the client channel table.
• If either MQSERVER or MQCHLLIB environment
variables are set in the environment where the
client application is running, then Channel table
library is ignored.
• If Channel table name is not specified, then
Channel table library is ignored.

408 IBM MQ Explorer

Attribute Description
Client channel name Specifies the connection string used when a service
requester makes an IBM MQ MQI client-binding
connection. For TCP/IP, the connection is in the form
of a host name followed by a port number, for
example:

OS2ROG3(1822)

If the port number is not specified, a default value of

1414 is used.
• If the Client channel connection name is
specified, then the Client channel name and
Client channel transport type must also be
specified.
• If either MQSERVER or MQCHLTAB environment
variable are set in the environment where the
client application is running, then Client channel
connection name is ignored.

Client channel connection name Specifies the channel used when an IBM MQ service
requester make an IBM MQ MQI client-binding
connection.
• If the Client channel connection name is
specified, then the Client channel name and
Client channel transport type must also be
specified.
• If either MQSERVER or MQCHLTAB environment
variable are set in the environment where the
client application is running, then Client channel
name is ignored.

Client channel transport type Specifies the transport type to be used when an IBM
MQ service requester makes an IBM MQ MQI client-
binding connection.
• If the Client channel connection name is
specified, then the Client channel name and
Client channel transport type must also be
specified.
• If either MQSERVER or MQCHLTAB environment
variable are set in the environment where the client
application is running, then Transport type is
ignored.
There are two different selectable values:
• TCP. Used to specify the TCP/IP transport protocol.
This is the default value.
• LU62. Used to specify the LU6.2 transport protocol.

Output message schema page

The following table lists the attributes you can set on the Output message schema page of the Service
definition properties dialog. They allow the schema for the message payload to be defined.

Introduction to IBM MQ Explorer 409

Attribute Description
Outbound data type Specifies the expected outbound data type
Import Schema File Specifies the schema file to be imported
Import Namespace Specifies the namespace to be imported

Output message header page

The following table lists the attributes you can set on the Output message header page of the Service
definition properties dialog. The output pages define the details of the message that the service will send
in response to the input message, and the destination where it will be put. Some of the properties only
apply to service definitions of an MQ binding type.

Attribute Description
CCSID Specifies the Coded Character Set ID which
corresponds to the CodedCharSetId field in the MQMD
structure. If this value is not specified, then the
service requester and service provider uses the
value which corresponds to the character set of the
message data.
Format Specifies the format name of the message data. This
property corresponds to the MQRFH2 format field,
or the MQMD format field if there is no MQRFH2 is
present. The value must be a character string between
0 and 8 characters long consisting of the A-Z and 0-9
characters.
The Format can be set to any value according to the
guidelines in the Format field.

User properties Specifies the user defined data carried in IBM MQ

service messages. Values must be specified in the
format allowed for RFH2 folder elements; in a series
of triplets encoded using an XML-like syntax such as:

<name dt="datatype">value</name>

The dt="datatype" element is optional, and if it is

omitted, it is treated as a string, allowing elements to
be specified as:

<name>value</name>

For example:

<myprop1>value1</myProp1><myprop2>value2</
myProp2><myprop3 dt="i4">99</myProp3>

For further information on the allowed data types and

formatting, see NameValueData ( MQCHARn ). It is not
recommended to include security sensitive properties
such as UserId or passwords.

410 IBM MQ Explorer

Attribute Description
Message type Specifies the type of message that is sent. This
property corresponds to the MsgType in the MQMD
structure. The five possible values are:
• Unspecified which means that no value is set,
therefore the value is taken from the value of the
Message exchange pattern. This is the default
value.
• Request which means that the message is one that
requires a reply. This value indicate that the service
uses a request-response message exchange pattern.
• Replay which means that the message is a reply to
a request.
• Report which means that the message is a report.
• Datagram which means that the service is a one-
way message exchange and there will not be a reply.
If no value is specifies, the value is set according to
the Message Exchange Pattern.
Persistence Specifies whether the message is persistent or not,
and it corresponds to the Persistence field in the MQMD
structure. The three possible values are:
• Not persistent which means that the messages
are not persistent.
• Persistent which means that the messages are
persistent.
• Queue default which means that the queue
manager determines the message persistence from
the definition of the destination that the message is
put to. This is the default value.

Message ID Specifies the Message identifier which corresponds to

the MsgId field in the MQMD structure.
The Message ID allows certain specialized IBM MQ
applications to be described as services (for example:
applications that share an input queue and select
the messages intended for them based on a pre-
defined msgId value). Predefined msgIds in service
definitions might lead to problems such as when a
request-response Message Exchange Pattern return
the request's msgId.
The Message Id can be either a character string or a
binary value. Binary values must be a string of up to 24
pairs of two-character hexadecimal values.
Click Edit to open a dialog and enter a value as text or
bytes

Introduction to IBM MQ Explorer 411

Attribute Description
Correlation ID Specifies the Correlation ID corresponds to the
CorrelId field in the MQMD structure. The Correlation
ID can be either a character string or a binary value.
Binary values must be a string of up to 24 pairs of
two-character hexadecimal values.
Click Edit to open a dialog and enter a value as text or
bytes

Expiry Specifies the message lifetime. It must be a signed

integer, and it is measured in tenths of a second. The
Expiry range is from 1 to 2 147 483 647.
A special value of Unlimited is used to indicate that
the message does not expire. The value of -1 is written
to the WSDL file.
A value of Unspecified means that no value is
written to the WSDL file. This is the default value.

Priority Specifies the priority associated with the message and

corresponds to the priority field in the MQMD structure.
It must be specified as an integer between 0 and 9,
with 0 as the lowest priority and 9 as the highest
priority.
A special value of Unlimited is used to indicate that
the message priority is taken from the definition of the
first queue that the message is put to. The value of -1
is written to the WSDL file.
A value of Unspecified means that no value is
written to the WSDL file. This is the default value.

Encoding Specifies the numeric encoding of message data,

which corresponds to the Encoding field in the MQMD
structure:
• Integer allows you to select Normal or Reversed
• Decimal allows you to select Normal or Reversed
• Float allows you to select Normal, Reversed, or
S390
• Mnemonic specifies the 3 character mnemonic
based on the other values selected. R = Reversed,
N = Normal, and 3 = S390.
• Value specifies the numeric value of the selections
and mnemonic.

412 IBM MQ Explorer

Attribute Description
Report options Specifies how the message and correlation identifiers
in the reply message or fault message are set by
the service provider. This property corresponds to the
Report field in the MQMD structure. There are four
possible values:
• New message ID indicates that reports or replies
generated as a result of this message, a new msgId
is generated for the report or reply message.
• Pass Message ID indicates that if a report or reply
is generated as a result of this message, then the
msgId of this message is copied to the msgId of the
report or reply message.
• copy Message ID to Correlation ID
indicates that if a report or reply is generated as
a result of this message, then the msgId of this
message is copied to the correlId of the report or
reply message.
• Pass Correlation ID indicates that if a report
or reply is generated as a result of this message,
then the correlId of this message is copied to the
correlId of the report or reply message.

Related tasks
“Creating a new service definition” on page 198
The service definition wizard simplifies the process of creating service definitions and is integrated into
the IBM MQ Explorer. The service definition wizard is deprecated in IBM MQ 8.0
“Adding a service definition repository” on page 197
Use this information to create a new service definition repository.
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

IBM MQ subscription properties

You can set properties for all types of subscriptions. Some of the properties do not apply to all types of
subscriptions, some properties are specific to z/OS subscriptions.
The following tables list all the properties that you can set:
• General
• Extended
• Statistics
For each property, there is a brief description of when you might need to configure the property. The
tables also give the equivalent MQSC parameters for the DEFINE, ALTER and DISPLAY SUB commands.
For more information about MQSC commands, see Administering IBM MQ using MQSC commands.

General page
The following table lists the properties you can set on the General page of the Subscription properties
dialog.

Introduction to IBM MQ Explorer 413

Property Meaning MQSC
parameter
Subscription name Read-only. You cannot change the name of the subscription after SUBNAME
it has been created.
Topic name The name of the topic object used by the subscription. The TOPICOBJ
topic name provides an optional topic root. A maximum of 48
characters are allowed.
Topic string This specifies a fully qualified topic name or wildcard topic set for TOPICSTR
the subscription.
The slash (/) character within this string has special meaning. It
delimits the elements in the topic tree. A topic string can start
with the (/) character but is not required to. A string starting with
the (/) character is not the same as the string which starts without
the (/) character.

Wildcard usage The scheme is used when interpreting any wildcard characters WSCHEMA
contained in the Topic string. The two values are:
TOPIC: Wildcard characters represent portions of the topic
hierarchy.
CHAR: Wildcard characters represent portions of strings.

Scope The scope determines whether this subscription is forwarded to SUBSCOPE

other queue managers, so that the subscriber receives messages
published at those other queue managers. The two values are:
ALL
The subscription is forwarded to all queue managers
directly connected through a publish/subscribe collective or
hierarchy.
QMGR
The subscription forwards messages published on the topic
only within this queue manager.
Note: Individual subscribers can only restrict SUBSCOPE. If
the parameter is set to ALL at topic level, then an individual
subscriber can restrict it to QMGR for this subscription. However,
if the parameter is set to QMGR at topic level, then setting an
individual subscriber to ALL has no effect.

Destination class The Destination class specifies whether the destination used by DESTCLAS
the subscription is a managed destination. The two values are:
MANAGED: The destination is managed.
PROVIDED: The destination is a queue. This is the default value.

Destination queue The destination queue manager for messages published to the DESTQMGR
manager subscription.
Destination name Specifies the name of the alias, local, remote, or cluster queue to DEST
which messages for this subscription are put.

414 IBM MQ Explorer

Property Meaning MQSC
parameter
Correlation identifier The value of Correlation identifier will be put into the DESTCORL
message descriptor of all messages sent to the subscription. If no
Note: It is not
Correlation identifier parameter is specified, messages
possible to set
will be placed on the destination with a CorrelId of MQCI_NONE.
the DESTCORL
A blank value (default) results in a system generated correlation property
identifier being used. programmatica
lly with JMS.
If set to
'000000000000000000000000000000000000000000000000'
(48 zeros) the CorrelId set by the publishing application will
be maintained in the copy of the message delivered to the
subscription, unless messages are propagated across a publish/
subscribe hierarchy.

Durable A durable subscription is not deleted when the creating DURABLE

application closes its subscription handle. The subscription's
Durable parameter can be either Yes or No. When Durable
is set to Yes, then the subscriptions are not deleted when the
creating application closes its subscription handle.
Type The Type of subscription indicates how the subscription was SUBTYPE
created. The subscription types are:
API: Subscription created through an MQSUB API request.
ADMIN: Subscription created through a DEF SUB MQSC or PCF
command. ADMIN is also used to indicate that a subscription has
been modified through administrative command.
PROXY: Subscription created internally for routing publications
through a queue manager network.
Subscriptions of type PROXY are not modified to ADMIN when
alterations are attempted.
The Type cannot be modified.

Properties Properties determines how pub/sub related message PSPROP

properties are added to messages sent to the subscription. The
available options are:
Compatibility: Publish / subscribe properties are added to the
message to maintain compatibility with IBM WebSphere MQ 6.0
Publish / Subscribe.
Message properties: Publish / subscribe properties are added
as message properties.
None: Publish / subscribe properties are not added to the
message.
RFH2: Publish / subscribe properties are added to the message
within an RFH 2 header.

User data The value of User data can be optionally passed as a message USERDATA
property in a message sent to the subscription.
Selector The Selector is an SQL92 string that is applied to messages SELECTOR
published on the named topic to select whether they are eligible
for the subscription.

Introduction to IBM MQ Explorer 415

Property Meaning MQSC
parameter
Selector type The type of SelectionString that has been specified. This display SELTYPE
property is calculated and is not associated with an object. The
selector type will be filterable (for example, with a WHERE clause)
to allow an administrator to display only internal or only external
selectors.

Extended page
The following table lists the properties you can set on the Extended page of the Subscription properties
dialog.

Property Meaning MQSC

parameter
Variable user ID Specifies whether users other than the creator of the VARUSER
subscription, can connect to it and take ownership of the
subscription. The two values are:
ANY: Other users can connect to the subscription if the other user
has the correct topic authority checks and destination authority
checks. This is the default value.
FIXED: Other users cannot connect to the subscription.

User Specifies the user profile that owns this subscription. SUBUSER
Application identity data The value of Application identity data will be used for PUBAPPID
messages sent to the subscription. If Application identity
data is not specified, then an empty default value is used.
Accounting token The value of Accounting token will be used for messages sent PUBACCT
to the subscription. If Accounting token is not specified, then
the default value MQACT_NONE is used.
Publish priority The Publish priority determines the manner in which PUBPRTY
pub/sub related message properties are added to the messages
sent to the subscription. The options available are:
As published which means the priority of the message sent to
this subscription and is taken from that supplied in the published
message.
As queue defined which means the priority of the message
sent to this subscription and is taken from the default priority of
the queue defined as the destination.
Priority-value which enables you to specify a priority ranging 0 - 9.

Subscription ID The value of Subscription ID is assigned by the queue SUBID

manager as an all time unique identifier for the subscription. This
identifier can be used as an alternative to SUBNAME as the target
for DISPLAY, ALTER, and DELETE MQSC commands when it is
not possible to provide the SUBNAME due to its format, or if no
SUBNAME was provided for an application created subscription.

416 IBM MQ Explorer

Property Meaning MQSC
parameter
Expiry The time to live of the subscription from the creation date and EXPIRY
time. Expiry is measured in tenths of a second. The two values
are:
Unlimited which means the subscription will never expire, or
the user can type their own value which is measured in tenths of a
second. Zero is the default value.

Request only Request only indicates whether the subscriber will poll for REQONLY
updates via MQSUBPRQ API. The two values are:
All which means that all publications are delivered to the
subscription. this is the default value.
On request which means that publications are only delivered to
the subscription in response to MQSUBPRQ API.

Subscription level This is the level associated with the subscription. Publications SUBLEVEL
will only be delivered to this subscription if it is in the set of
subscriptions with the highest SubLevel value less than or equal
to the PubLevel used at publication time. The value must be in the
range 0 - 9. Zero is the lowest level.

Statistics page
The following table lists the properties on the Statistics page of the Subscription properties dialog. The
Statistics page displays information about the history of the subscription. The information displayed on
the Statistics page is read-only and cannot be altered by the user.

Property Meaning MQSC

parameter
Creation Date Read-only. This is the date on which the subscription was created. CRDATE
Creation Time Read-only. this is the time at which the subscription was created. CRTIME
Alteration Date Read-only. This is the date on which the subscription's properties ALTDATE
were last altered.
Alteration Time Read-only. This is the time at which the subscription's properties ALTTIME
were last altered.

Related concepts
“Publishers and subscribers” on page 98
Publishers and subscribers are applications that send and receive messages (publications) using the
publish/subscribe method of messaging. Publishers and subscribers are decoupled from one another so
that publishers do not know the destination of the information that they send, and subscribers do not
know the source of the information that they receive.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
“Forcing changes to queue properties” on page 38

Introduction to IBM MQ Explorer 417

 If the changes that you are making to the properties of a queue affect the operation of a queue manager
or another program, you might be asked to confirm whether you want to force the changes to the queue
properties.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Process definition properties

You can set properties for process definitions. Some properties do not apply to all types of process
definitions. Some of the properties are specific to z/OS process definitions.
The following tables list all the properties that you can set for process definitions:
• General
• Statistics
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY PROCESS
commands. For more information, see ALTER PROCESS and DISPLAY PROCESS

General page
The following table lists the properties that you can set on the General page of the Process Definition
properties dialog.

Property Meaning MQSC

parameter
Process name Read-only. You cannot change the name of the process definition PROCESS
after it has been created.
Description Type a meaningful description of the purpose of the process DESCR
definition. See Entering strings in MQ Explorer.
Application type Select the type of application that starts when the initiation queue APPLTYPE
receives the trigger message.
System-defined applications are in the range zero through 65
535. For user-defined applications, type in the range 65 536
through 999 999 999.
Only specify application types (other than user-defined types)
that are supported on the platform at which the command is
executed:
• z/OS supports CICS (default), DOS, IMS, MVS™, OS2, AIX, Linux,
Windows, Windows NT, and DEF.
• OS/400® supports OS/400 (default), CICS, and DEF.
• Tandem NSK supports NSK.
• UNIX supports AIX (default), Linux, OS2, DOS, Windows, CICS,
and DEF.
• Windows NT supports Windows NT (default), DOS, Windows,
OS2, AIX, Linux, CICS, and DEF.

Application ID Type the name of the application to be started. Usually, this is the APPLICID
fully-qualified file name of the executable object. The maximum
length is 256 characters. For a CICS application, type the CICS
transaction ID; for an IMS application, type the IMS transaction
ID.

418 IBM MQ Explorer

Property Meaning MQSC
parameter
Environment data Type the environment information that is relevant to the ENVRDATA
application being started. The maximum length is 128 characters.
User data Type the user information that is relevant to the application being USERDATA
started. The maximum length is 128 characters.
QSG disposition Read-only. This is the queue sharing group disposition of the QSGDISP
process definition. You cannot change the disposition of a process
definition after it has been created. Queue manager means that
the object definition is available only to the queue manager that
hosts it; Group means that the object definition is stored on the
shared repository and each queue manager in the queue sharing
group has a copy of the definition; Copy means that the object
definition is the queue manager's copy of a definition in the
shared repository.

Statistics page
The following table lists the properties that you can set on the Statistics page of the Process Definitions
properties dialog. The Statistics page displays information about the history of the process definitions.
You cannot edit any of these properties.

Property Meaning MQSC

parameter
Alteration date Read-only. This is the date on which the process definition's ALTDATE
properties were last altered.
Alteration time Read-only. This is the time at which the process definition's ALTTIME
properties were last altered.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Namelist properties
You can set properties for namelists. Some of the properties are specific to z/OS namelists.
The following tables list the properties that you can set:
• General
• Statistics
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY NAMELIST
commands. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.

General page
The following table lists the properties that you can set on the General page of the Namelist properties
dialog.

Introduction to IBM MQ Explorer 419

Property Meaning MQSC
parameter
Namelist name Read-only. You cannot change the name of the namelist after it NAMELIST
has been created.
Description Type a meaningful description of the purpose of the namelist. See DESCR
Entering strings in MQ Explorer.
Names Type the list of names of objects that are associated with NAMES
the namelist. The objects must be defined on the local queue
manager. See Entering strings in MQ Explorer.
Name count Read-only. This is the number of names in the namelist. NAMCOUNT
QSG disposition Read-only. This is the queue sharing group disposition of the QSGDISP
namelist. You cannot change the disposition of a namelist after
it has been created. Queue manager means that the object
definition is available only to the queue manager that hosts
it; Group means that the object definition is stored on the
shared repository and each queue manager in the queue sharing
group has a copy of the definition; Copy means that the object
definition is the queue manager's copy of a definition in the
shared repository.

Statistics page
The following table lists the properties that you can set on the Statistics page of the Namelist properties
dialog. The Statistics page displays information about the history of the namelist. You cannot edit any of
these properties.

Property Meaning MQSC

parameter
Alteration date Read-only. This is the date on which the namelist's properties ALTDATE
were last altered.
Alteration time Read-only. This is the time at which the namelist's properties ALTTIME
were last altered.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Authentication information properties

You can set properties for all types of authentication information objects. Some of the properties do
not apply to all types of authentication information objects, and some properties are specific to z/OS
authentication information objects.
The following tables list the properties that you can set:
• General
• LDAP
• OCSP
• LDAP User Repository

420 IBM MQ Explorer

 • LDAP Authorization
• User ID + Password
• Statistics
For each property, there is a brief description of when you might need to configure it. The tables also give
the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY AUTHINFO commands. For more
information about MQSC commands, see Administering IBM MQ using MQSC commands.

General page
The following table lists the properties that you can set on the General page of the Authentication
Information properties dialog.

Property Meaning MQSC

parameter
Authinfo name Read-only. You cannot change the name of an authentication AUTHINFO
information object after it has been created.
Authinfo type Read-only. You cannot change the type of an authentication AUTHTYPE
information object after it has been created.
Description Type a meaningful description of the purpose of the DESCR
authentication information object. See Entering strings in MQ
Explorer.
QSG disposition Read-only. The queue sharing group disposition of the QSGDISP
authentication information object. You cannot change the
disposition of an authentication information object after it has
been created. Queue manager means that the object definition
is available only to the queue manager that hosts it; Group means
that the object definition is stored on the shared repository and
each queue manager in the queue sharing group has a copy of
the definition; Copy means that the object definition is the queue
manager's copy of a definition in the shared repository.

LDAP page
The following table lists the properties that you can set on the LDAP page of the CRL LDAP or IDPW
LDAP Authentication Information properties dialog. The LDAP page displays the name and authentication
information for the LDAP server.

Property Meaning MQSC

parameter
LDAP Server Name Type the host name, IPv4 dotted decimal address, or IPv6 CONNAME
hexadecimal notation of the host on which the LDAP server
is running, with an optional port number. If you specify the
connection name as an IPv6 address, only systems that are
running IBM WebSphere MQ 6.0 authentication information
objects. with an IPv6 stack are able to resolve this address.
If the authentication information object is part of the queue
manager's CRL namelist, ensure that any clients that are using
the client channel table that is generated by the queue manager
are capable of resolving the connection name. On z/OS, to use a
connection name that resolves to an IPv6 network address, the
level of z/OS must support IPv6 for connecting to an LDAP server.

Introduction to IBM MQ Explorer 421

Property Meaning MQSC
parameter
User ID Type the Distinguished Name of the user who is accessing the LDAPUSER
LDAP server, with the following limitations:
• On Multiplatforms, the maximum length is 1024 characters.
• On z/OS, the maximum length is 256 characters.
• If you use asterisks (*) in the user name, they are treated as
literal characters, and not as wildcards, because the LDAP user
ID is a specific name and not a string used for matching.

Password Type the password that is associated with the Distinguished LDAPPWD
Name of the user who is accessing the LDAP server. The
maximum length is 32 characters.

OCSP page
The following table lists the properties that you can set on the OCSP page of the OCSP Authentication
Information properties dialog.

Property Meaning MQSC

parameter
OCSP responder URL The URL at which the OCSP responder can be contacted. OCSPURL
This property takes priority over a URL in an AuthorityInfoAccess
(AIA) certificate extension.

LDAP User Repository page

The following table lists the properties that you can set on the LDAP User Repository page of the IDPW
LDAP Authentication Information properties dialog.

Property Meaning MQSC

parameter
Equivalent short user A field in the LDAP user record to be used as a short user name SHORTUSR
for this connection.
User ID base DN The base DN used to locate user records in an LDAP server. BASEDNU
Use secure Whether the connection to the LDAP server will be made using SECCOMM
communication TLS.
User Object Class The LDAP object class used for user records in the LDAP CLASSUSR
repository.
Qualifying user field A qualification to allow user IDs provided by applications to be USRFIELD
identified as a field in the LDAP user record.

LDAP Authorization
The following table lists the properties that you can set on the LDAP Authorization page of the IDPW
LDAP Authentication Information properties dialog.

422 IBM MQ Explorer

Property Meaning MQSC
parameter
Authorization method Whether authorization is done using user IDs and groups from the AUTHORMD
Operating System or from LDAP. The possible values are:
Operating System. Authorization is done using user IDs and
groups from the Operating System.
Search group. Authorization is done using user IDs and groups
from LDAP. The group entry in the LDAP repository contains an
property listing the Distinguished Name of all the users who
belong to the group.
Search user. Authorization is done using user IDs and groups
from LDAP. The user entry in the LDAP repository contains an
property listing all the Distinguished Name of the groups to which
the user belongs.
Search group short name. Authorization is done using user
IDs and groups from LDAP. The group entry in the LDAP repository
contains an property listing the short user name of all the users
who belong to the group.

Allow nested groups Whether nested groups are allowed. The possible values are: NESTGRP
No. Nested groups are not allowed.
Yes. Nested groups are allowed. The group list is searched
recursively to enumerate all groups a user belongs to.

Group base DN The base DN used to locate group records in an LDAP server. BASEDNG
Group object class The LDAP object class used for group records in the LDAP CLASSGRP
repository.
Qualfying group field A qualification to allow group to be identified as a field in the GRPFIELD
LDAP group record.
Group membership field Name of the property used within an LDAP user or group record to FINDGRP
determine group membership.

User ID + Password page

The following table lists the properties that you can set on the User ID + Password page of the IDPW OS
or IDPW LDAP Authentication Information properties dialog.

Introduction to IBM MQ Explorer 423

Property Meaning MQSC
parameter
Check locally bound Whether connections made by using local bindings, connections CHCKLOCL
connections must supply a user ID and password for validation. The possible
values are:
None. No user ID and password are required.
Optional. No user ID and password are required but if provided,
they are checked.
Required for administrators. User ID and password are
required for privileged users.
Required for all. User ID and password are required for all
users.
Setting CHCKLOCL to Required for administrators or
Required for all results in the inability to locally administer
the queue manager by way of the runmqsc commands unless you
specify the -u UserID parameter on the runmqsc command
line. If you do not specify this parameter, you see error message
AMQ8135: Not authorized. Similarly, when you run IBM MQ
Explorer on your local system, you might see error AMQ4036:
Access not permitted when you are attempting to connect to
a queue manager.
To specify a user name and password, right-click the local queue
manager object, and select Connection Details > Properties
from the menu. In the UserID section, enter the user name and
password, and then click OK.

Check client connections Whether connections made using client connections must supply CHCKCLNT
a user ID and password for validation. The possible values are:
None. No user ID and password are required.
Optional. No user ID and password are required but if provided,
they will be checked.
Required for administrators. User ID and password are
required for privileged users.
Required for all. User ID and password are required for all
users.

Adopt the authenticated Whether to adopt the user ID that was provided with a password ADOPTCTX
user as the context for this connection. The possible values are:
Yes. The validated user ID will be adopted as the context for
this connection. If the user ID presented is an LDAP user ID, and
authorization checks are done using operating system user IDs,
the SHORTUSR associated with the user entry in LDAP will be
adopted as the credentials for authorization checks to be done
against.
No. The validated user ID will not be adopted as the context for
this connection.

424 IBM MQ Explorer

Property Meaning MQSC
parameter
Authentication failure This property specifies how long to delay before returning the FAILDLAY
delay failure return code to the application, for example, if no response
is received by a mqmconnx request. This is the length of time in
seconds, which can be 0 - 60. A value of zero means that no delay
is added.

Statistics page
The following table lists the properties that you can set on the Statistics page of the Authentication
Information properties dialog. The Statistics page displays information about the history of the
authentication information object. You cannot edit the values of any of these properties.

Property Meaning MQSC

parameter
Alteration date Read-only. This is the date on which the authentication ALTDATE
information object properties were last altered.
Alteration time Read-only. This is the time at which the authentication ALTTIME
information object properties were last altered.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Channel authentication record properties

You can set properties for channel authentication record objects.
The following tables list the properties that you can set:
• General
• Address
• Block address
• Block user
• Queue manager
• SSL peer
• Client user
• Extended
• Statistics
For each property, there is a brief description of when you might need to configure it. The tables also
give the equivalent MQSC parameter for the SET CHLAUTH and DISPLAY CHLAUTH commands. For more
information about MQSC commands, see Administering IBM MQ using MQSC commands.

General page
The following table lists the properties that you can set on the General page of the Channel
Authentication Records properties dialog.

Introduction to IBM MQ Explorer 425

Property Meaning MQSC
parameter
Channel profile Channel profile name. See SET CHLAUTH. PROFILE
Type Can be Address Map, Block Address List, Block User List, Queue TYPE
Manager Map, SSL Peer Map or User Map. See SET CHLAUTH.
Description Type a meaningful description of the purpose of the channel DESCR
authentication record. See Entering strings in MQ Explorer.

Address page
The following table lists the properties that you can set on the Address page of the Channel
Authentication Records properties dialog.
Note:
This parameter is valid with the property TYPE(ADDRESSMAP), TYPE(QMGRMAP), TYPE(SSLPEERMAP)
and TYPE(USERMAP).

Property Meaning MQSC

parameter
Address Specifies the filter to be used to compare with the IP address ADDRESS
of the partner queue manager or client at the other end of the
channel. For SET command this parameter is mandatory with
TYPE(ADDRESSMAP). See SET CHLAUTH.

Block address page

The following table lists the properties that you can set on the Block address page of the Channel
Authentication Records properties dialog.
Note:
This parameter is only valid with the property TYPE(BLOCKADDR).

Property Meaning MQSC

parameter
Address list A list of IP address patterns which are blocked from connecting to ADDRLIST
this queue manager using any channel. See SET CHLAUTH.

Block user page

The following table lists the properties that you can set on the Block user page of the Channel
Authentication Records properties dialog.
Note:
This parameter is only valid with the property TYPE(BLOCKUSER).

Property Meaning MQSC

parameter
User list A list of user IDs that are blocked from use of this channel or set USERLIST
of channels. See SET CHLAUTH.

426 IBM MQ Explorer

 Queue manager page
The following table lists the properties that you can set on the Queue manager page of the Channel
Authentication Records properties dialog.
Note:
This parameter is only valid with the property TYPE(QMGRMAP).

Property Meaning MQSC

parameter
Remote queue manager Specifies the remote partner queue manager name pattern. See QMNAME
SET CHLAUTH.

SSL peer page

The following table lists the properties that you can set on the SSL peer page of the Channel
Authentication Records properties dialog.
Note:
This parameter is only valid with the property TYPE(SSLPEERMAP).

Property Meaning MQSC

parameter
Peer name The value of the Distinguished Name on the certificate from the SSLPEER
peer queue manager or client at the other end of the IBM MQ
channel. When the channel starts, the value of this property is
compared with the Distinguished Name of the certificate. See SET
CHLAUTH.
SSL/TLS issuer's If this optional parameter is specified, it only allows connections SSLCERTI
Distinguished Name from partner queue managers for which the certificate was issued
by a Certificate Authority with a matching Distinguished Name.
See SET CHLAUTH.

Client user page

The following table lists the properties that you can set on the Client user page of the Channel
Authentication Records properties dialog.
Note:
This parameter is only valid with the property TYPE(USERMAP).

Property Meaning MQSC

parameter
Client user ID Specifies the client asserted user ID. See SET CHLAUTH. CLNTUSER

Extended page
The following table lists the properties that you can set on the Extended page of the Channel
Authentication Records properties dialog. See SET CHLAUTH.

Property Meaning MQSC

parameter
User source Source of the user ID to be used for MCAUSER at run time. USERSRC
Possible values are Channel, Map and No access.

Introduction to IBM MQ Explorer 427

Property Meaning MQSC
parameter
MCA user ID Message channel user ID to be used when the inbound MCAUSER
connection matches the SSL DN, IP address, client asserted user
ID or remote queue manager name supplied. This property is
enabled only when User source selected is Map.
Warning Indicates whether this record should operate in warning mode. WARN
Possible values are Yes or No.
Check client connection Specifies whether the connection that matches this rule and is CHCKCLNT
being allowed in with USERSRC(CHANNEL) or USERSRC(MAP),
must also specify a valid user ID and password.
Custom This property is reserved for the configuration of new features CUSTOM
before separate properties have been introduced.

Statistics page
The Statistics page of the Channel Authentication Records properties dialog displays read-only
information showing when the properties of the channel authentication record were last changed. You
cannot edit the values of these properties. See DISPLAY CHLAUTH.

Property Meaning MQSC

parameter
Alteration date Read-only. This is the date on which the authentication ALTDATE
information object properties were last altered.
Alteration time Read-only. This is the time at which the authentication ALTTIME
information object properties were last altered.

Related reference
Channel authentication records
SET AUTHREC
Message channel agent user identifier (MCAUSER)
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Multicast Communication Information object properties

You can set properties for Multicast communication information objects.
The following tables list the properties that you can set:
• General
• Statistics
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY COMMINFO
commands. For more information about MQSC commands, see The MQSC Commands.

General page
The following table lists the properties that you can set on the General page of the communication
information object properties dialog.

428 IBM MQ Explorer

Property Meaning MQSC
parameter
Communication Read only after it has been defined. The name of the COMMINFO
Information communications information object. The name must not be the
same as any other communications information object name
currently defined on this queue manager. For more information,
see Rules for naming IBM MQ objects.
Type Read only after it has been defined. The type of the TYPE
communications information object. The only type supported is
MULTICAST.
Description Plain text comment. The description provides descriptive DESCR
information about the communication information object when
an operator issues the DISPLAY COMMINFO command. For more
information, see DISPLAY COMMINFO.
The description must contain only displayable characters. The
maximum length is 64 characters. In a DBCS installation, it can
contain DBCS characters (subject to a maximum length of 64
bytes).
Note: If characters are used that are not in the coded character
set identifier (CCSID) for this queue manager, they might be
translated incorrectly if the information is sent to another queue
manager.

Group address The group IP address or DNS name. It is the administrator's GRPADDR
responsibility to manage the group addresses.
It is possible for all multicast clients to use the same
group address for every topic; only the messages that match
outstanding subscriptions on the client are delivered.
Using the same group address can be inefficient because
every client must examine and process every multicast packet
in the network. It is more efficient to allocate different IP
group addresses to different topics or sets of topics, but
this requires careful management, especially if other non-MQ
multicast applications are in use on the network. The default
value is 239.0.0.0.

Port The port number to transmit on. The default port number is 1414 PORT
Message history The maximum message history is the amount of message history MSGHIST
that is kept by the system to handle retransmissions in the case of
NACKs (negative acknowledgments).
A value of 0 gives the least level of reliability. The default value is
100 messages.

Introduction to IBM MQ Explorer 429

Property Meaning MQSC
parameter
Coded character set ID The coded character set identifier that messages are transmitted CCSID
on. Specify a value in the range 1 through 65535, or set it to As
published which is the default value.
The CCSID must specify a value that is defined for use on
your platform, and use a character set that is appropriate to
the platform. If you use this parameter to change the CCSID,
applications that are running when the change is applied continue
to use the original CCSID. Because of this, you must stop and
restart all running applications before you continue. This includes
the command server and channel programs.
To do this, stop and restart the queue manager after making the
change. This parameter is valid only on the following platforms:

• AIX

• IBM i

• Linux

• Windows
For details of the supported CCSIDs for each platform, see Code
page conversion.

Encoding The encoding that the messages are transmitted in. ENCODING
• As published. This is the default value.
• Reversed
• Normal
• S390
• TNS
• encoding

New subscriber history The new subscriber history controls whether a subscriber joining NSUBHIST
a publication stream receives as much data as is currently
available, or receives only publications made from the time of the
subscription.
• None. A value of None causes the transmitter to transmit only
publication made from the time of the subscription. This is the
default value.
• ALL. A value of ALL causes the transmitter to retransmit as
much history of the topic as is known. In some circumstances,
this can give a similar behavior to retained publications.

Monitor interval How frequently, in seconds, that monitoring information is MONINT

(milliseconds) updated. If events messages are enabled, this parameter also
controls how frequently event messages about the status of
the Multicast handles created using this COMMINFO object are
generated.
A value of 0 means that there is no monitoring. The default value
is 60.

430 IBM MQ Explorer

Property Meaning MQSC
parameter
Communication events Controls whether event messages are generated for Multicast COMMEV
handles that are created using this COMMINFO object. Events
will only be generated if they are enabled using the MONINT
parameter. The three possible values are:
• Disabled. Publications from applications not using Multicast
are not bridged to applications that do use Multicast. This is the
default value.
• Enabled. Publications from applications not using Multicast are
bridged to applications that do use Multicast.
• Exception. Event messages are written if the message
reliability is below the reliability threshold. The reliability
threshold is set to 90.

Multicast bridge Controls whether publications from applications not using BRIDGE
Multicast are bridged to applications using Multicast. Bridging
does not apply to topics that are marked as MCAST(ONLY). As
these topics can only be Multicast traffic, it is not applicable to
bridge to the queue publish/subscribe domain. The two possible
values are:
• Disabled. Publications from applications not using Multicast
are not bridged to applications that do use Multicast. This is the
default for i5/OS.
• Enabled. Publications from applications not using Multicast are
bridged to applications that do use Multicast. This is the default
for platforms other than i5/OS.

Multicast heartbeat The heartbeat interval is measured in milliseconds, and specifies MCHBINT
interval (milliseconds) the frequency at which the transmitter notifies any receivers that
there is no further data available. The default value is 2000
milliseconds.

Introduction to IBM MQ Explorer 431

Property Meaning MQSC
parameter
Multicast property control The multicast properties control how many of the MQMD MCPROP
properties and user properties flow with the message.
• All. All user properties and all the fields of the MQMD are
transported. This is the default value.
• Reply. Only user properties, and MQMD fields that deal with
replying to the messages, are transmitted. These properties are:
– MsgType
– MessageId
– CorrelId
– ReplyToQ
– ReplyToQmgr
• User. Only the user properties are transmitted.
• None. No user properties or MQMD fields are transmitted.
• Compatible. This value causes the transmission of the
message to be done in a compatible mode to RMM. This allows
some inter-operation with the current XMS applications and
Broker RMM applications.

XMS .NET Multicast

messaging (using RMM) was deprecated from IBM MQ 9.2 and
is removed at IBM MQ 9.3.

Statistics page
The following table lists the properties that you can set on the Statistics page of the Communication
Information properties dialog. The Statistics page displays information about the history of the
communication information object. You cannot edit any of these properties.

Property Meaning MQSC

parameter
Alteration date Read-only. This is the date on which the communication ALTDATE
information object's properties were last altered.
Alteration time Read-only. This is the time at which the communication ALTTIME
information object's properties were last altered.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.

Storage class properties

You can set properties for storage classes. Storage classes are available only on z/OS.
The following table lists the properties that you can set.
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY STGCLASS
commands. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.

432 IBM MQ Explorer

 General page
The following table lists the properties that you can set on the General page of the Storage class
properties dialog.

Property Meaning MQSC

parameter
Storage class name Read-only. You cannot change the name of the storage class after STGCLASS
it has been created.
Description Type a meaningful description of the purpose of the storage class. DESCR
See Entering strings in MQ Explorer.
PageSet ID This is the page set identifier that the storage class is associated PSID
with. Type a number, from 00 to 99, two characters long. If this
property is blank, the value is taken from the default storage
class, SYSTEMST.
QSG disposition Read-only. The queue sharing group disposition of the storage QSGDISP
class. You cannot change the disposition of a storage class after
it has been created. Queue manager means that the object
definition is available only to the queue manager that hosts
it; Group means that the object definition is stored on the
shared repository and each queue manager in the queue sharing
group has a copy of the definition; Copy means that the object
definition is the queue manager's copy of a definition in the
shared repository.
XCF group name If you are using the IMS bridge, this is the name of the XCF XCFGNAME
group to which the IMS system belongs. Type a name from 1 to 8
characters long. The first character must be an uppercase letter
from A to Z; subsequent characters must be uppercase letters
from A to Z, numbers from 0 to 9, or both.
XCF member name If you are using the IMS bridge, this is the XCF member name XCFMNAME
of the IMS system within the XCF group that is specified in the
XCF group name property. Type a name from 1 to 16 characters
long. The first character must be an uppercase letter from A to
Z; subsequent characters must be uppercase letters from A to Z,
numbers from 0 to 9, or both.
Passticket appl name This is the application name that is passed to RACF when PASSTKTA
authenticating the passticket that is specified in the MQIIH
header. If you do not specify a value, the validation process
uses the z/OS Batch Job Profile Name, which means that RACF
validates using a profile in the form of MVSxxxx, where xxxx is
the SMFID of the z/OS system on which the queue manager is
running.
Alteration date Read-only. This is the date on which the storage class's properties ALTDATE
were last altered.
Alteration time Read-only. This is the time at which the storage class's properties ALTTIME
were last altered.

Related tasks
“Configuring queue managers and objects” on page 37

Introduction to IBM MQ Explorer 433

 You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.

Queue sharing group properties

You cannot edit the values of any queue sharing group properties.
The following tables list all the properties for queue sharing groups.
For each property, there is a brief description of what it means. The equivalent MQSC command
is DISPLAY GROUP, which returns information about the queue sharing group to which a queue
manager belongs. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.
You cannot edit the values of any of these properties.

Property Meaning
Queue sharing group name The name of the queue sharing group.
Queue manager name The name of the queue manager.
Queue manager number The number, generated internally, of the queue
manager in the group.
Db2 name The name of the Db2 subsystem or group to which the
queue manager is to connect.
Queue manager status The current status of the queue manager. Active
means that the queue manager is running; Inactive
means that the queue manager is not running,
having terminated normally; Failed means that the
queue manager is not running, having terminated
abnormally; Created means that the queue manager
has been defined to the group, but has not yet been
started; Unknown means that the status cannot be
determined.
Db2 connection status The current status of the connection to Db2.
Command level The command level supported by the queue manager.
Queue manager CPF The command prefix of the queue manager.

Related concepts
“Queue sharing groups” on page 32
Queue sharing groups exist only on z/OS queue managers. A queue sharing group is a group of queue
managers that can access the same shared queues. Each member of the queue sharing group has access
to the same set of shared queues.

Coupling facility structure properties

You can set properties for coupling facility structures. Coupling facility structures are available only on
z/OS.
For each property, there is a brief description of when you might need to configure the property.
The tables also give the equivalent MQSC parameter for the DEFINE, ALTER and DISPLAY CFSTRUCT
commands. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.

434 IBM MQ Explorer

 General page
This table lists the properties that you can set on the General page of the Coupling facility structure
properties dialog.

Property Meaning MQSC

parameter
Coupling facility name Read-only. You cannot change the name of the coupling facility CFSTRUCT
structure after it has been created.
Coupling facility Type a meaningful description of the purpose of the coupling DESCR
description facility structure. See “Strings in property dialogs” on page 553.
Level Read-only. The functional capability level for this coupling facility CFLEVEL
application structure.
Recovery Read-only. This property specifies whether coupling facility RECOVER
structure recovery is supported for the application structure.
Loss of coupling facility Specifies the action taken when the queue manager loses CFCONLOS
connectivity connectivity to the CF structures with. The three options are:
• As queue manager. The action taken is based on the setting
of the queue manager CFCONLOS property.
• Tolerate. The queue manager tolerates a loss of connectivity
to CF structures and does not terminate.
• Terminate. The queue manager terminates when connectivity
to CF structures is lost.
This parameter is only valid from CFLEVEL(5) or later. Setting
this property for a structure at a CFLEVEL earlier than 5 results in
PCF reason code MQRCCF_PARM_CONFLICT being returned.
Automatic recovery Specifies the automatic recovery action when a queue manager RECAUTO
detects that the structure has failed. Or when a queue manager
loses connectivity to the structure and no systems in the SysPlex
have connectivity to the Coupling Facility that the structure is
allocated in. The value can be any of the following values:
• Yes. The structure and associated shared message data sets
are automatically recovered.
• No. The structure is not automatically recovered.
This parameter is valid only from CFLEVEL(5) or later. Setting
this parameter for a structure at a CFLEVEL earlier than 5 results
in PCF reason code MQRCCF_PARM_CONFLICT being returned.
Alteration date Read-only. The date on which the coupling facility structure's ALTDATE
properties were last altered.
Alteration time Read-only. The time at which the coupling facility structure's ALTTIME
properties were last altered.
Status Read-only. The current status of the coupling facility structure. STATUS

Message offload page

This table lists the properties that you can set on the Message offload page of the Coupling facility
structure properties dialog.

Introduction to IBM MQ Explorer 435

Property Meaning MQSC
parameter
Offload If required, select where the message data for a shared queue OFFLOAD
is stored. This can be Db2, SMDS (shared message data set) or
None if no offload is required.
Offload rule 1 threshold Edit this value to represent your initial threshold for the used OFFLD1TH
(%) capacity of the coupling facility structure. For example 70%
would represent that the offload would be triggered when 70%
of the coupling facility structure storage was used.
Offload rule 1 size Edit this value to represent the size of messages selected to be OFFLD1SZ
offloaded when the capacity threshold specified in the Offload
rule 1 is reached. All messages exceeding the size specified will
be selected to be offloaded. For example 32k would indicate that
all messages exceeding 32k would be offloaded.
Offload rule 2 threshold Edit this value to represent your secondary threshold for the OFFLD2TH
(%) used capacity of the coupling facility structure. For example 80%
would indicate that the offload would be triggered when 80% of
the coupling facility structure storage was used.
Offload rule 2 size Edit this value to represent the size of messages selected to be OFFLD2SZ
offloaded when the capacity threshold specified in the Offload
rule 2 is reached. All messages exceeding the size specified will
be selected to be offloaded. For example 4k would indicate that
all messages exceeding 4k would be offloaded.
Offload rule 3 threshold Edit this value to represent your final threshold for the used OFFLD3TH
(%) capacity of the coupling facility structure. For example 90%
would represent that the offload would be triggered when 90%
of the coupling facility structure storage was used.
Offload rule 3 size Edit this value to represent the size of messages selected to be OFFLD3SZ
offloaded when the capacity threshold specified in the Offload
rule 3 is reached. All messages exceeding the size specified will
be selected to be offloaded. For example 0k would indicate that
all remaining messages would be offloaded.
Generic data set name Edit this value to provide the generic data set name to be used DSGROUP
for the group of shared message data sets associated with this
structure.
Logical block size Edit this value to provide the logical block size, which is the unit DSBLOCK
that shared message data set space is allocated to individual
queues
Number of buffers Edit this value to provide the number of buffers to be allocated in DSBUFS
each queue manager for accessing shared message data sets.
Expand data set Edit this parameter to control whether the queue manager should EXPAND
expand a shared message data set when it becomes nearly full,
and further blocks are required in the data set.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553

436 IBM MQ Explorer

 To include certain characters in a string, you must punctuate the string in a particular way.

Cluster queue manager properties

The Cluster Queue Manager properties dialog shows the properties of the cluster-sender and cluster-
receiver channels on the selected cluster queue manager. You cannot edit any of the properties in the
Cluster Queue Manager properties dialog.
Cluster queue managers are queue managers that are members of a cluster. The term cluster queue
manager is also used to refer to the records that each queue manager in a cluster maintains about other
queue managers and objects in the cluster, in particular, the cluster-sender and cluster-receiver channels.
The Cluster Queue Manager properties dialog shows the properties of the cluster-sender and cluster-
receiver channels on the selected cluster queue manager. The following tables list the properties that
are displayed in the properties dialog. These properties vary from the properties shown for the same
channels in the Channel properties dialog (see Channel properties).
• General
• Extended
• MCA
• Exits
• LU6.2
• Retry
• Message retry
• Cluster
• SSL
• Statistics
You cannot edit any of the properties in the Cluster Queue Manager properties dialog.
The tables give the equivalent MQSC parameter for the DISPLAY CLUSQMGR command. For more
information about MQSC commands, see Administering IBM MQ using MQSC commands.

General page
The following table lists the properties on the General page of the Cluster Queue Manager properties
dialog.

Property Meaning MQSC

parameter
Channel name The name of the channel definition. CHANNEL
Channel status This is the current status of the channel. STATUS
Connection name For cluster-sender channels, this the name of the computer that CONNAME
hosts the target queue manager. For cluster-receiver channels,
this is the name of the computer that hosts the local queue
manager. The format of the connection name depends on the
transmission protocol that is selected.
Description A description of the cluster channel. DESCR

Introduction to IBM MQ Explorer 437

Property Meaning MQSC
parameter
Local communication If the channel uses TCP/IP and the channel uses a particular LOCLADDR
address IP address, port, or port range for outbound communications,
the local communications address for the channel is specified.
The channel binds to the address locally. The format used
is ipaddress(low-port, high-port), where ipaddress
is the IP address specified in IPv4 dotted decimal, IPv6
hexadecimal, or alphanumeric host name format. For example,
192.0.2.1 specifies the IPv4 address with any port;
192.0.2.1(1000) specifies the IPv4 address and a specific
port; 192.0.2.1(1000,2000) specifies the IPv4 address and
a range of ports; (1000) specifies a port only.
Suspend This shows whether the queue manager is suspended from the SUSPEND
cluster or not (as a result of the SUSPEND QMGR command). Yes
means that the queue manager is suspended.
Transmission protocol The transport type that the channel uses. TRPTYPE
Version The version of the IBM MQ installation that the cluster queue VERSION
manager is associated with. The version has the following format:
VVRRMMFF
VV: Version
RR: Release
MM: Maintenance level
FF: Fix level

Extended page
The following table lists the properties on the Extended page of the Cluster Queue Manager properties
dialog.

Property Meaning MQSC

parameter
Maximum message length The maximum length of a message, in bytes, that can be MAXMSGL
transmitted on the channel.
Heartbeat interval The length of the heartbeat interval in seconds. A value of zero HBINT
means that no heartbeat exchange takes place. The value that
is used is the larger of the values specified at the sending side
and the receiving end of the channel. The heartbeat interval is
the time, in seconds, between heartbeat flows passed from the
sending MCA when there are no messages on the transmission
queue. The heartbeat exchange gives the receiving MCA the
opportunity to quiesce the channel.
Sequence number wrap The sequence number is the count of messages that are sent SEQWRAP
through the channel. The sequence number increments each time
a message is sent through the channel. This property shows the
highest message sequence number that can be reached before it
restarts at 1. The two ends of the channel must have the same
sequence number wrap value when the channel starts; otherwise
you get an error.

438 IBM MQ Explorer

Property Meaning MQSC
parameter
Non-persistent message This shows whether non-persistent messages are sent as part NPMSPEED
speed of a transaction. Fast means that non-persistent messages are
not sent as part of a transaction and so become available for
retrieval far more quickly than if they are part of a transaction;
Normal means that non-persistent messages are sent as part of
a transaction, which reduces the risk of losing the messages if the
channel stops while the messages are in transit.
Batch size The maximum number of messages to be sent before syncpoint BATCHSZ
is taken. The messages are always transferred individually but are
committed or backed out as a batch.
Disconnect interval The number of seconds after the batch ends before the channel DISCINT
(seconds) closes down. On all platforms except for z/OS, a value of 0 means
that the channel does not disconnect. On z/OS, a value of 0
means that the channel disconnects immediately.
Data conversion This shows whether the message is converted before CONVERT
transmission to the format required by the receiving system. Yes
means that the message is converted before transmission; No
means that the message is converted by the receiving application
to the format that is required on the receiving system (this is the
typical method).
Batch interval The number of milliseconds during which the channel keeps a BATCHINT
(milliseconds) batch open even if there are no messages on the transmission
queue.
Batch heartbeat interval The batch heartbeat interval allows the sending end of the BATCHHB
(milliseconds) channel to verify that the receiving end of the channel is still
active just before the sending end of the channel commits a
batch of messages. If the receiving end of the channel is not
active, the batch can be backed out rather than becoming in-
doubt. By backing out the batch, the messages remain available
for processing so that they can, for example, be redirected to
another channel. This property shows the number of seconds that
the sending end of the channel waits for a response from the
receiving end of the channel before assuming that the receiving
end of the channel is inactive. A value of 0 means that batch
heartbeating is not used. For more information, see Reducing the
likelihood of a channel being in doubt.
Put authority This property specifies the type of security processing to be PUTAUT
carried out by the Message Channel Agent (MCA) when running
an MQPUT command to the target queue or an MQI call. Default
means that the default user ID is used; Context means that the
alternate user ID from the context information that is associated
with the message is used.

Introduction to IBM MQ Explorer 439

Property Meaning MQSC
parameter
Message compression This shows the message compression techniques that are COMPMSG
supported by the channel definition, in order of preference. The
first technique that is supported by the other end of the channel
is used. None means that no message compression is performed;
RLE means that message data compression is performed using
run-length encoding; ZLIBFAST means that message data
compression is performed using the zlib compression technique
and a fast compression time is preferred; ZLIBHIGH means
that message data compression is performed using the zlib
compression technique and a high level of compression is
preferred; ANY means that any compression technique that
is supported by the queue manager can be used. For more
information, see Distributed queueing and clusters.
Header compression This shows the header compression techniques that are COMPHDR
supported by the channel definition, in order of preference. The
first technique that is supported by the other end of the channel
is used. None means that no header compression is performed;
System means that header compression is performed. For more
information, see Distributed queueing and clusters.
Property control This defines what happens to properties of messages that are PROPCTL
about to be sent to a V6 or earlier queue manager. The value has
to be changed from Compatibility to Force to preserve the
V6 behavior of propagating the RFH2 to the caller. The possible
values are:
All means that all properties of the message are included with
the message when it is sent to the remote queue manager. The
properties, except those in the message descriptor (or extension),
are placed in one or more MQRFH2 headers in the message data.
Compatibility. This is the default value; it allows applications
which expect JMS related properties to be in an MQRFH2 header
in the message data to continue to work unmodified.
If the message contains a property with a prefix of mcd., jms.,
usr., or mqext. then all optional message properties (where the
Support value is MQPD_SUPPORT_OPTIONAL), except those in
the message descriptor (or extension) are placed in one or more
MQRFH2 headers in the message data before the message is sent
to the remote queue manager. Otherwise all properties of the
message, except those in the message descriptor (or extension),
are removed from the message before the message is sent to the
remote queue manager.

440 IBM MQ Explorer

Property Meaning MQSC
parameter

If the message contains a property where the Support field of

the property descriptor is not set to MQPD_SUPPORT_OPTIONAL
then the message are rejected and treated in accordance with its
report options. If the message contains one or more properties
where the Support field of the property descriptor is set to
MQPD_SUPPORT_OPTIONAL but other fields of the property
descriptor are set to non-default values, then these properties
are removed from the message before the message is sent to the
remote queue manager.
None means that all properties of the message, except those
in the message descriptor (or extension), are removed from
the message before the message is sent to the remote
queue manager. If the message contains a property where
the Support field of the property descriptor is not set to
MQPD_SUPPORT_OPTIONAL then the message are rejected and
treated in accordance with its report options.

Batch data limit Provide the limit in kilobytes, from 0 - 999999, of the amount of BATCHLIM
data that should be sent through a channel before taking a sync
point. A value of 0 means that no data limit is applied to batches
over this channel.
Use dead-letter queue Specifies whether the dead-letter queue is used when messages USEDLQ
cannot be delivered by channels. There are two possible values:
• No means that messages that cannot be delivered by a channel
are treated as a failure, and the channel either ends in
accordance with the setting of Non-persistent message speed,
or discards the messages.
• Yes means that if the queue manager Dead-letter queue
property provides the name of a Dead Letter Queue, then it is
used. Otherwise the behavior is as for No.

MCA page
The following table lists the properties on the MCA page of the Cluster Queue Manager properties dialog.
The properties show how the Message Channel Agent (MCA) for the selected channel runs.

Property Meaning MQSC

parameter
MCA user ID The user identifier to be used by the message channel agent USERID
when attempting to start a secure LU 6.2 session with a remote
message channel agent.
MCA type This shows how the message channel agent (MCA) program runs. MCATYPE
Thread means that the MCA runs as a thread; Process means
that MCA runs as a process.
MCA name The Message channel agent name. MCANAME

Exits page
The following table lists the properties on the Exits page of the Cluster Queue Manager properties dialog.
The properties configure the user exits that are run by the selected channel.

Introduction to IBM MQ Explorer 441

Property Meaning MQSC
parameter
Security exit name The name of the security exit program. SCYEXIT
Message exit name The names of your message exit programs. MSGEXIT
Send exit name The names of your send exit programs. SENDEXIT
Receive exit name The names of your receive exit programs. RCVEXIT
Security exit user data The data that is passed to the channel security exit when the SCYDATA
channel security exit is called.
Message exit user data The data that is passed to the channel message exit when the MSGDATA
channel message exit program is called.
Send exit user data The data that is passed to the channel send exit when the send SENDDATA
exit program is called.
Receive exit user data The data that is passed to the channel receive exit when the RCVDATA
receive exit program is called.

LU6.2 page
The following table lists the properties on the LU6.2 page of the Cluster Queue Manager properties dialog.

Property Meaning MQSC

parameter
Mode name The LU 6.2 mode name. MODENAME
TP name The name, or the generic name, of the MCA program that is run at TPNAME
the far end of the link.
User ID The user identifier that the MCA uses when attempting to initiate USERID
a secure LU 6.2 session with a remote MCA.
Password The password that the MCA uses when it attempts to initiate a PASSWORD
secure LU 6.2 session with a remote MCA.

Retry page
The following table lists the properties on the Retry page of the Cluster Queue Manager properties dialog.
The properties configure how the channel behaves if the channel cannot connect to the remote queue
manager.

Property Meaning MQSC

parameter
Short retry count The maximum number of times that the channel can try to SHORTRTY
connect to a remote queue manager.
Short retry interval The approximate interval, in seconds, that the channel must wait SHORTTMR
before it tries again to connect to the remote queue manager
during the short retry count. A value of 0 means that the channel
tries again immediately.
Long retry count The maximum number of times that the channel can try to LONGRTY
connect to a remote queue manager. The value of this property
is used only when the count specified in the Short retry
count property has been exhausted and the channel has still not
successfully connected to the remote queue manager.

442 IBM MQ Explorer

Property Meaning MQSC
parameter
Long retry interval The approximate interval, in seconds, that the channel must wait LONGTMR
before it tries again to connect to the remote queue manager
during the long retry count. A value of 0 means that the channel
tries again immediately.
Keep alive interval The value of the Keep alive interval property specifies the KAINT
time-out value of the channel. Auto means that the keepalive
value is based on the value of the negotiated Heartbeat
interval. If a value is specified and the negotiated Heartbeat
interval is greater than zero, the Keep alive interval
is the negotiated Heartbeat interval plus 60 seconds; if
the negotiated Heartbeat interval is zero, the Keep alive
interval is zero too. A value of 0 means that KeepAlive on this
channel is disabled.

Message retry page

The following table lists the properties on the Message retry page of the Cluster Queue Manager
properties dialog. The properties configure how the channel behaves if the channel fails the first time
that it tries to put a message on a remote queue

Property Meaning MQSC

parameter
Message retry count The number of times that the channel retries to connect to the MRRTY
remote queue manager before it decides that it cannot deliver the
message to the remote queue. This property controls the action
of the MCA only if the Message retry exit name property is
blank. If the Message retry exit name property is not blank, the
value of the Message retry count property is passed to the
exit for the exit's use but the number of times that the channel
retries to connect is controlled by the exit, not by the Message
retry count property.
Message retry interval The minimum length of time, in milliseconds, that the channel MRTMR
must wait before it can try again to put the message on the
remote queue.
Message retry exit name The name of the channel message-retry exit program. MRDATA
Message retry exit user The data that is passed to the channel message retry exit when MREXIT
data the channel message retry exit is called.

Cluster page
The following table lists the properties on the Cluster page of the Cluster Queue Manager properties
dialog.

Property Meaning MQSC

parameter
Cluster name The name of the cluster in which the selected channel definition
is shared.
Cluster queue manager The name of the queue manager that hosts the selected channel
definition.

Introduction to IBM MQ Explorer 443

Property Meaning MQSC
parameter
Definition type This shows how the channel was defined. Cluster-sender DEFTYPE
means that the channel was defined as a cluster-sender channel
from an explicit definition; Auto cluster-sender means that
the channel was defined as a cluster-sender channel by auto-
definition alone; Auto explicit cluster-sender means
that the channel was defined as a cluster-sender channel by
auto-definition and an explicit definition; Cluster-receiver
means that the channel was defined as a cluster-receiver channel
from an explicit definition.
Queue manager type This shows the function of the queue manager in the cluster. QMTYPE
Repository means that the queue manager is a full repository
for the cluster; Normal means that the queue manager is a partial
repository for the cluster.
QMID The internally generated unique name of the cluster queue QMID
manager.
Network priority The value of this property indicates the channels priority for the NETPRTY
network connection; 0 is the lowest priority.
CLWL channel rank The rank of the channel in the cluster; 0 is the lowest rank. For CLWLRANK
more information, see Distributed queuing and clusters.
CLWL channel priority The priority of the channel in the cluster; 0 is the lowest priority. CLWLPRTY
For more information, see Distributed queuing and clusters.
CLWL channel weight The weighting that is applied to the channel so that the proportion CLWLWGHT
of messages that is sent through the channel is controlled; 1
is the lowest weighting. For more information, see Distributed
queuing and clusters.
Transmission queue The cluster-sender channel is transferring messages from this XMITQ
transmission queue.
The name is one of the following transmission queues:
SYSTEM.CLUSTER.TRANSMIT.QUEUE
The default cluster transmission queue. The queue is
shared between cluster-sender channels. The queue is
used if the queue manager property, Default cluster
transmission queue is set to SCTQ, and no transmission
queue has its parameter Cluster channel name set to
resolve to this cluster-sender channel. The queue is also
used if the version of the queue manager is less than IBM
WebSphere MQ 7.5.
SYSTEM.CLUSTER.TRANSMIT.ChannelName
The transmission queue is created by the queue manager, in
response to setting the queue manager property, Default
cluster transmission queue to Queue for each
channel. By default, the queue is not shared between
cluster-sender channels.
User-defined transmission queue
The transmission queue parameter, Cluster channel
name is manually set to resolve to this cluster-sender
channel. Multiple cluster-sender channels might transfer
messages from this transmission queue.

444 IBM MQ Explorer

 SSL page
The following table lists the properties on the SSL page of the Cluster Queue Manager properties dialog.
The properties configure the channel to use TLS security.

Property Meaning MQSC

parameter
SSL CipherSpec The name of the CipherSpec for an TLS connection. Both ends of SSLCIPH
the IBM MQ TLS channel definition must have the same value in
the SSL CipherSpec property.
Accept only certificates The value of the Distinguished Name on the certificate from the SSLPEER
with Distinguished Names peer queue manager or the client at the other end of the IBM MQ
matching these values channel. When the channel starts, the value of this property is
compared with the Distinguished Name of the certificate.
Authentication of parties This parameter specifies how the channel authenticates TLS SSLCAUTH
initiating connections clients. Required means that the channel must receive and
authenticate an TLS certificate from an TLS client; Optional
means that the channel is not required to receive and
authenticate an TLS certificate from an TLS client. If the value is
Optional and the peer TLS client sends a certificate, the channel
authenticates the certificate as normal.

Statistics page
The following table lists the properties on the Statistics page of the Cluster Queue Manager properties
dialog. The Statistics page shows the date and time on which the cluster queue manager was last altered.

Property Meaning MQSC

parameter
Alteration date The date on which the queue's properties were last altered. ALTDATE
Alteration time The time at which the queue's properties were last altered. ALTTIME

Related reference
“Channel properties” on page 369
You can set properties for all types of channels, including client-connection channels. Some properties
are specific to certain types of channel.
“Cluster queue properties” on page 445
When you view the cluster queues that belong to a queue manager in a cluster, you can double-click the
cluster queue and view its properties in the Cluster Queue properties dialog. You cannot edit any of the
properties in the Cluster Queue properties dialog.

Cluster queue properties

When you view the cluster queues that belong to a queue manager in a cluster, you can double-click the
cluster queue and view its properties in the Cluster Queue properties dialog. You cannot edit any of the
properties in the Cluster Queue properties dialog.
The following tables list the properties that are displayed in the Cluster Queue properties dialog. These
properties vary from the properties shown for the same queues in the Queue properties dialog (see Queue
properties).
• General
• Cluster
• Statistics

Introduction to IBM MQ Explorer 445

 For each property, there is a brief description of what it means. The tables also give the equivalent MQSC
parameter for the DISPLAY QCLUSTER command. For more information about MQSC commands, see
Administering IBM MQ using MQSC commands.

General page
The following table lists the properties on the General page of the Cluster Queue properties dialog.

Property Meaning MQSC

parameter
Queue name The name of the cluster queue.
Queue type Unlike in the Queue properties dialog, the Queue type property QTYPE
just shows that the queue is a cluster queue. See the Cluster page
of the Cluster queue properties dialog for whether the cluster
queue is a local, remote, or alias queue.
Description A description of the cluster queue. DESCR
Put messages This shows whether queue managers can put messages on the PUT
cluster queue. Allowed means that queue managers can put
messages on the cluster queue; Inhibited means that queue
managers cannot put messages on the cluster queue.
Default priority The default priority of messages that are put on the cluster queue, DEFPRTY
where 9 is the highest priority.
Default persistence This shows whether messages that are put on this cluster DEFPSIST
queue persist when the queue manager is stopped and
restarted. Persistent means that the messages persist; Not
persistent means that messages are lost when the queue
manager is stopped and restarted.

Cluster page
The following table lists the properties on the Cluster page of the Cluster Queue properties dialog. The
Cluster page shows the properties of the cluster queue that are relevant to the cluster.

Property Meaning MQSC

parameter
Cluster name The name of the cluster in which the cluster queue is shared. CLUSTER
Default bind type The default message binding. DEFBIND
Cluster queue type This is the type of queue that the cluster queue represents: CLUSQT
Alias, Local, Queue manager (the cluster queue represents
a queue manager alias), Remote queue definition.
Cluster queue manager The name of the queue manager that hosts the cluster queue. CLUSQMGR
QMID The internally generated unique name of the queue manager that QMID
hosts the cluster queue.
CLWL channel rank The rank of the queue in the cluster for purposes of cluster CLWLRANK
workload distribution; 0 is the lowest rank. For more information,
see Distributed queuing and clusters.
CLWL channel priority The priority of the queue in the cluster for purposes of CLWLPRTY
cluster workload distribution; 0 is the lowest priority. For more
information, see Distributed queuing and clusters.

446 IBM MQ Explorer

 Statistics page
The following table lists the properties on the Statistics page of the Cluster Queue properties dialog. The
Statistics page shows the date and time on which the cluster queue was last altered.

Property Meaning MQSC

parameter
Alteration date This is the date on which the queue's properties were last altered. ALTDATE
Alteration time This is the time at which the queue's properties were last altered. ALTTIME

Related reference
“IBM MQ queue properties” on page 358
The properties that you can set for a queue depend on the type of queue. Different types of IBM MQ
queues have different properties. Some of the properties do not apply to all types of queue, some
properties are specific to cluster queues, and some properties are specific to z/OS queues.
“Cluster queue manager properties” on page 437
The Cluster Queue Manager properties dialog shows the properties of the cluster-sender and cluster-
receiver channels on the selected cluster queue manager. You cannot edit any of the properties in the
Cluster Queue Manager properties dialog.

Cluster topic properties

You can set properties for cluster topics. However, you can alter some properties only while you are
creating a new cluster topic. You cannot alter these properties once the cluster topic has been created.
To configure a standard cluster of queue managers for publish/subscribe messaging, you define one or
more administered topic objects on a queue manager in the cluster. To make the topic a cluster topic, you
configure the Cluster name property. When you do this, any topic used by a publisher or subscriber, from
that point on in the topic tree, is shared across all queue managers in the cluster. Messages published to
a clustered branch of the topic tree are automatically routed to subscriptions on other queue managers in
the cluster.
The following tables list all the properties for IBM MQ cluster topics. Some of the properties listed in these
tables can only be altered while creating a new topic, and cannot be modified once the IBM MQ cluster
topic has been created.
For each property, there is a brief description of when you might need to configure it. The tables also give
the equivalent MQSC parameter for use with (for example) the DISPLAY TCLUSTER command. For more
information about MQSC commands, see Administering IBM MQ using MQSC commands.

General
The following table lists the properties on the General page of the Cluster topic Properties dialog.

MQSC
Property Meaning parameter
Topic name This value cannot be changed once the topic has been created. TOPNAME
This parameter is required and cannot contain an empty string.
The unique identifier of the administrative topic definition to be
created. A maximum of 48 characters are allowed.
Name must not be the same as any other topic definition defined
on the selected queue manager.

Topic type This value is read only. This value displays whether the topic is N/A
local; Local, or in a cluster; Cluster.

Introduction to IBM MQ Explorer 447

 MQSC
Property Meaning parameter
Topic String This value cannot be changed once the topic has been created. TOPICSTR
This parameter is required and cannot contain an empty string.
The / character within this string has special meaning. It delimits
the elements in the topic tree. A topic string can start with
the / character but is not required to. A string starting with the /
character is not the same as the string which starts without the /
character.
Topic String must not be the same as any other topic string
already represented by another topic object definition. The
maximum length of a topic string is 10 240 characters.

Description This value is a string entered by the administrator. It contains DESC

descriptive information about the topic. It must contain only
displayable characters. A maximum of 64 characters.
If characters are used that are not in the coded character set
identifier (CCSID) for the selected queue manager, then they
might be translated incorrectly if the information is sent to
another queue manager.

Publish This property controls whether messages can be published to PUB

the topic. The default value is As parent. The 2 other options
available are:
Allowed which means that messages can be published to the
topic by an authorized application.
Inhibited which means that messages cannot be published to
the topic.

Subscribe This property controls whether messages can subscribe to the SUB
topic. The default value is As parent. The 2 other options
available are:
Allowed which means that subscriptions can me made to the
topic by an authorized application.
Inhibited which means that applications cannot subscribe to
the topic.

Durable subscriptions This property controls whether the topic permits durable DURSUB
subscriptions to be made. The default value is As parent. The 2
other options available are:
Allowed which means that durable subscriptions can me made
to the topic by an application.
Inhibited which means that durable subscriptions cannot be
made to the topic by an application.

Default priority The default priority of messages published to the topic. The DEFPRTY
default value is As parent.
The default priority can be set from 0 (the lowest priority) to 9
(the highest priority)

448 IBM MQ Explorer

 MQSC
Property Meaning parameter
Default persistence The default persistence of a new topic is As parent. Select DEFPSIST
Persistent to specify that messages created by applications
that use MQPER_PERSISTENCE_AS_Q_DEF become persistent.
Select Not Persistent to specify that messages created by
applications that use MQPER_PERSISTENCE_AS_Q_DEF become
non persistent.
Default put response type The default response type for message puts. The default value is DEFPRESP
As parent. The 2 other options available are:
Synchronous which means the response is put synchronously.
Asynchronous which means the response is put
asynchronously.

Non-persistent message The delivery method for non-persistent messages published to NPMSGDLV
delivery this topic. The four options are:
As parent The delivery mechanism used is based on the setting
of the first parent administrative node found in the topic tree
relating to this topic. This is the default supplied with IBM MQ, but
your installation might have changed it.
To all available subscribers Non-persistent messages
are delivered to all subscribers that can accept the message.
Failure to deliver the message to any subscriber does not prevent
other subscribers from receiving the message.
To all durable subscribers Non-persistent messages
must be delivered to all durable subscribers. Failure to deliver a
non-persistent message to any non-durable subscribers does not
return an error to the MQPUT call. If a delivery failure to a durable
subscriber occurs, no other subscribers receive the message and
the MQPUT calls fails.
To all subscribers Non-persistent messages must be
delivered to all subscribers, irrespective of durability for the
MQPUT call to report success. If a delivery failure to any
subscriber occurs, no other subscribers receive the message and
the MQPUT call fails.

Introduction to IBM MQ Explorer 449

 MQSC
Property Meaning parameter
Persistent message The delivery method for persistent messages published to this PMSGDLV
delivery topic. The four options are:
As parent The delivery mechanism used is based on the setting
of the first parent administrative node found in the topic tree
relating to this topic. This is the default supplied with IBM MQ, but
your installation might have changed it.
To all available subscribers Persistent messages are
delivered to all subscribers that can accept the message. Failure
to deliver the message to any subscriber does not prevent other
subscribers from receiving the message.
To all durable subscribers Persistent messages must be
delivered to all durable subscribers. Failure to deliver a persistent
message to any non-durable subscribers does not return an error
to the MQPUT call. If a delivery failure to a durable subscriber
occurs, no other subscribers receive the message and the MQPUT
calls fails.
To all subscribers Persistent messages must be delivered
to all subscribers, irrespective of durability for the MQPUT call to
report success. If a delivery failure to any subscriber occurs, no
other subscribers receive the message and the MQPUT call fails.

Wildcard operation This value controls the behavior of wildcard subscriptions with WILDCARD
respect to the topic. The two values are:
Block. Subscriptions made to a wildcard topic less specific than
the topic string for this topic object will not receive publications
made to this topic or to topic strings more specific that this topic.
Passthrough. Subscriptions made to a wildcard topic less
specific than the topic string for this topic object will receive
publications made to this topic and to topic strings more specific
than this topic. This is the default value.

Distributed Pub/Sub
The following table lists the properties on the Distributed Pub/Sub page of the Cluster topic Properties
dialog.

450 IBM MQ Explorer

Property Meaning MQSC
parameter
Proxy subscription Proxy-subscriptions are associated with the queue manager PROXYSUB
behavior name that created them. Publications are only forwarded to
directly connected queue managers if a proxy-subscription exists
that includes the publication topic. The two options for this value
are:
Force. This forces the sending of a wild-carded proxy-
subscription for the topic string associated with this topic object
from every queue manager in the cluster to every other queue
manager in the pub/sub topology, regardless of whether any
local subscriptions have been made. Once this forced proxy
subscription has been propagated throughout the topology,
any new subscriptions immediately receive any publications
from other connected queue manager without suffering latency,
although all publications are propagated to all other queue
managers in the cluster regardless of whether a subscription has
requested them or not.
Setting this value at a given level in the topic tree also prevents
proxy subscriptions being generated for individual topic strings
at subsequent levels in the topic tree, reducing the proxy
subscription overhead.
First use. As the various topologies of the pub/sub queue
managers have an interconnected nature, there could be a short
delay in the propagation of the proxy-subscription depending on
the topology complexity. This means that once a subscription
is made, remote publications will not necessarily be received
immediately.

Publication scope The scope of publications can be controlled administratively using PUBSCOPE
the PUBSCOPE topic attribute. The attribute can be set to one of
the following 3 values:
• As parent. This is the default value. The publication scope is
set to the same value as the parent queue manager.
• Queue manager. The publication is only delivered to local
subscribers.
• All. The publication is delivered to local subscribers and
remote subscribers by directly connected queue managers.

Subscription scope The scope of subscriptions can be controlled administratively SUBSCOPE

using the SUBSCOPE topic attribute. The attribute can be set to
one of the following 3 values:
• As parent. This is the default value. The subscription scope is
set to the same value as the parent queue manager.
• Queue manager. The subscription receives only local
publications, and proxy subscriptions are not propagated to
remote queue managers.
• All. A proxy subscription is propagated to remote queue
managers, and the subscriber receives local and remote
publications.

Introduction to IBM MQ Explorer 451

 Cluster
The following table lists the properties on the Cluster page of the Cluster topic Properties dialog.

Property Meaning MQSC

parameter
Cluster name To make a topic a cluster topic, you configure this property. When CLUSTER
you do this, any topic used by a publisher or subscriber at that
point or in the topic tree is shared across all queue managers
in the cluster, and messages published to a clustered branch of
the topic tree are automatically routed to subscriptions on other
queue managers in the cluster.
Cluster object state The current state of this topic object in this cluster. The values CLSTATE
can be as follows:
ACTIVE
The cluster topic is correctly configured and being adhered to
by this queue manager.
PENDING
Only seen by a hosting queue manager, this state is reported
when the topic has been created but the full repository has
not yet propagated it to the cluster. This might be because the
host queue manager is not connected to a full repository, or
because the full repository has deemed the topic to be invalid.
INVALID
This clustered topic definition conflicts with an earlier
definition in the cluster and is therefore not currently active.
ERROR
An error has occurred with respect to this topic object.
This parameter is typically used to aid diagnosis when multiple
definitions of the same clustered topic are defined on different
queue managers, and the definitions are not identical.

Cluster queue manager This is the name of the queue manager in the cluster that owns N/A
the cluster topic.
Cluster route The routing behavior to use for topics in the cluster defined by the CLROUTE
CLUSTER parameter. There are two possible values:
DIRECT
When you configure a direct routed clustered topic on a queue
manager, all queue managers in the cluster become aware
of all other queue managers in the cluster. When performing
publish and subscribe operations, each queue manager then
connects directly to all the others.
TOPICHOST
When you use topic host routing, all queue managers in the
cluster become aware of the cluster queue managers that
host the routed topic definitions. When performing publish
and subscribe operations, queue managers in the cluster
connect only to these topic host queue managers, and not
directly to each other. The topic host queue managers are
responsible for routing publications from queue managers on
which publications are published to queue managers with
matching subscriptions.

452 IBM MQ Explorer

Property Meaning MQSC
parameter
QMID The internally generated unique name of the cluster queue QMID
manager. To avoid any ambiguity, it is preferable to use QMID
(Queue manager identifier) rather than QMNAME.

Statistics
The following table lists the properties on the Statistics page of the Cluster topic Properties dialog.

Property Meaning MQSC

parameter
Alteration date This value cannot be changed, it is provided for information MQCA_ALTER
purposes only. ATION_DATE
This is the date on which the topic's properties were last altered.

Alteration time This value cannot be changed, it is provided for information MQCA_ALTER
purposes only. ATION_TIME
This is the time at which the topic's properties were last altered.

Related tasks
“Creating and configuring queue managers and objects” on page 13
You can create, configure, and delete queue managers and objects in IBM MQ Explorer by using the
Navigator view and Content view.
“Comparing the properties of two objects” on page 39
You can compare the properties of an object with another object of the same type; for example, compare
a queue with another queue, a topic with another topic, or a channel with another channel.

Application connection properties

The properties for application connections are displayed in the Application Connection properties dialog.
You cannot edit the values of any of these properties.
The following tables list all the properties for application connections:
• General
• Unit of work
• Handle
For each property, there is a brief description of what it means. The tables also give the equivalent
MQSC parameter for the DISPLAY CONN command. For more information about MQSC commands, see
Administering IBM MQ using MQSC commands.

General page
The following table lists the properties on the General page of the Application Connection properties
dialog.

Introduction to IBM MQ Explorer 453

Property Meaning MQSC
parameter
Application name A string containing the tag of the application connected to the APPLTAG
queue manager. It is one of the following: a z/OS batch job name,
a TSO USERID, a CICS APPLID, an IMS region name, a channel
initiator job name, an OS/400 job name, a Linux or AIX process, a
Windows process. The application name represents the name of
the process or job that has connected to the queue manager. In
the instance that this process or job is connected via a channel,
the application name represents the remote process or job rather
than the local channel process or job name.
Application type A string indicating the type of the application that is connected to APPLTYPE
the queue manager. Batch means an application using a batch
connection; RRSBATCH means an RRS-coordinated application
using a batch connection; CICS means a CICS transaction; IMS
means an IMS transaction; CHINIT means a channel initiator;
System means a queue manager; User means a user application.
Process ID The identifier of the process that opened the queue. This property PID
is not valid on z/OS.
Thread ID The identifier of the thread within the application process that TID
has opened the queue. An asterisk indicates that this queue was
opened with a shared connection. This property is not valid on
z/OS.
User ID The user identifier that is associated with the handle. USERID
Options These are the connection options that are currently used by this CONNOPTS
application connection.
Channel name The name of the channel that owns the handle. If there is no CHANNEL
channel associated with the handle, this value is empty. This
value is shown only when the handle belongs to the channel
initiator.
Connection name The connection name that is associated with the channel that CONNAME
owns the handle. If there is no channel associated with the
handle, this value is empty. This value is shown only when the
handle belongs to the channel initiator.
PSB name This is the 8-character name of the program specification block PSBNAME
(PSB) that is associated with the running IMS transaction.
Connection ID This is the 24-byte unique connection identifier that allows IBM CONN and
MQ to reliably identify an application. When the application first EXTCONN
connects to the queue manager, the queue manager sets the
connection identifier.

Unit of work page

The following table lists the properties on the Unit of work page of the Application Connection properties
dialog. The Unit of work page displays information that is available about the unit of work associated with
the selected connection.

454 IBM MQ Explorer

Property Meaning MQSC
parameter
Unit of work type The type of unit of recovery as seen by the queue manager. It is URTYPE
one of the following: CICS (z/OS only); XA; RRS (z/OS only); IMS
(z/OS only); Queue manager.
Unit of work start date This is the date that the transaction associated with the UOWSTDA
connection was started.
Unit of work start time This is the time that the transaction associated with the UOWSTTI
connection was started.
Origin unit of work ID The unit of recovery identifier, which was assigned by the NID
originator. It is an 8-byte value.
Origin name This identifies the originator of the thread, except in the case NID
where the Application type property is set to RRSBATCH, when it
is omitted.
Log extent name This is the file name of the log extent to which the transaction UOWLOG
associated with this connection first wrote.
First log access date This is the date that the transaction associated with the UOWLOGDA
connection first wrote to the log.
First log access time This is the time that the transaction associated with the UOWLOGTI
connection first wrote to the log.
Unit of work state The state of the unit of work. None means that there is no unit of UOWSTATE
work; Active means that the unit of work is active; Prepared
means that the unit of work is in the process of being committed;
Unresolved means that the unit of work is in the second phase
of a two-phase commit operation, IBM MQ holds resources on
its behalf and external intervention is required to resolve it. This
might be as simple as starting the recovery coordinator (such
as CICS, IMS, or RRS) or it might involved a more complex
operation such as using the RESOLVE INDOUBT command. The
Unresolved value can occur only on z/OS.
Queue manager unit of The unit of recovery assigned by the queue manager. On z/OS, QMURID
work ID this is an 8 byte log RBA, while on other platforms, this is
an 8 byte transaction identifier, displayed as 16 hexadecimal
characters.
External unit of work ID The external unit of recovery identifier associated with the EXTURID
connection. It is the recovery identifier known in the external
syncpoint coordinator. Its format is determined by the value of
the UOW type property.

Introduction to IBM MQ Explorer 455

Property Meaning MQSC
parameter
Asynchronous state The state of the asynchronous consumer on this object handle. ASTATE
There are five possible values:
Active: An MQCB call has set up a function to call back to
process messages asynchronously and the connection handle has
been started so that asynchronous message consumption can
proceed.
Inactive: An MQCB call has set up a function to call back to
process messages asynchronously but the connection handle has
not yet been started, or has been stopped or suspended, so that
asynchronous message consumption cannot currently proceed.
Suspended: The asynchronous consumption callback has been
suspended so that asynchronous message consumption cannot
currently proceed on this object handle. This can be either
because an MQCB call with Operation MQOP_SUSPEND has
been issued against this object handle by the application, or
because it has been suspended by the system. If it has been
suspended by the system, as part of the process of suspending
asynchronous message consumption the callback function will be
called with the reason code that describes the problem resulting
in suspension. This will be reported in the Reason field in the
MQCBC structure that is passed to the callback function. For
asynchronous message consumption to proceed, the application
must issue an MQCB call with the Operation parameter set to
MQOP_RESUME.

Susptemp: The asynchronous consumption callback has been

temporarily suspended by the system so that asynchronous
message consumption cannot currently proceed on this object
handle. As part of the process of suspending asynchronous
message consumption, the callback function will be called
with the reason code that describes the problem resulting in
suspension. This will be reported in the Reason field in the
MQCBC structure passed to the callback function. The callback
function will be called again when asynchronous message
consumption is resumed by the system, when the temporary
condition has been resolved.
None: An MQCB call has not been issued against this handle,
so no asynchronous message consumption is configured on this
handle. This is the default value.

Units of recovery (z/OS only) This parameter is used to filter the list of connections URDISP
disposition returned. There are 3 options to choose from:
• All means that all connections are returned. This is the default
value.
• Group means that the connections returned will consist only of
those in the group to which the command was targeted.
• Queue manager means that the connections returned will
consist only of those on the queue manager to which the
command was targeted.

456 IBM MQ Explorer

 Handle page
The following table lists the properties on the Handle page of the Application Connection properties
dialog. The Handle page displays information about the object that the selected application has opened.

Property Meaning MQSC

parameter
Connection ID This is the 24-byte unique connection identifier that allows IBM CONN and
MQ to reliably identify an application. When the application first EXTCONN
connects to the queue manager, the queue manager sets the
connection identifier.
Object name This is the name of the object that the connection has opened. OBJNAME
Object type This is the type of the object that the connection has opened; for OBJTYPE
example, Queue, Channel, Storage Class.
Open options These are the options used by the connection to open the object. OPENOPTS

Bind as queue definition means that the application

opened the queue to get messages using the queue-defined
default; Input shared means that the application opened the
queue to get messages with shared access; Input exclusive
means that the application opened the queue to get messages
with exclusive access; Browse means that the application
opened the queue to browse the messages on the queue; Output
means that the application opened the queue to put messages
on the queue; Inquire means that the application opened the
object to get a list of the object's properties; Set means that the
application opened the queue to set the queue's properties.
Bind on open means that application the local queue manager
bound the queue handle to a particular instance of the destination
queue when the queue was opened so that all messages put
using this handle are sent to the same instance of the destination
queue, and by the same route; Bind not fixed means that the
local queue manager did not bind the queue handle to a particular
instance of the destination queue, so successive MQPUT calls
using this handle might result in the messages being sent to
different instances of the destination queue, or being sent to
the same instance but by different routes; Bind as queue
default means that the local queue manager bound the queue
handle in the way defined by the queue's Default bind type
property.

Introduction to IBM MQ Explorer 457

Property Meaning MQSC
parameter

Save all context means that context information from any

message retrieved using this handle is associated with this
handle; Pass identity context means that the identity
context information from a message can be passed to the
processed message when it is put on the queue; Pass all
context means that the identity and origin context information
from a message can be passed to the processed message
when it is put on the queue; Set identity context means
that the application can set the identity context information
associated with a message when it is put on the queue; Set
all context means that the application can set the identity and
origin context information associated with a message when it is
put on the queue. For more information about message context,
see Message context.
Alternate user authority means that the MQOPEN call
was validated against the user ID specified in the call; Fail if
quiescing means that the MQOPEN call would have failed if the
queue manager was in quiescing state.

QSG disposition Read-only. The queue sharing group disposition of the object. QSGDISP
Queue manager means that the object definition is available
only to the queue manager that hosts it; Group means that
the object definition is stored on the shared repository and
each queue manager in the queue sharing group has a copy
of the definition; Copy means that the object definition is the
queue manager's copy of a definition in the shared repository;
Shared means that the object definition is stored on the queue
sharing group's coupling facility and is available to all the queue
managers in the queue sharing group.
Handle state The current state of the handle. Active means that an API call HSTATE
from this connection is currently in progress for this object. If the
object is a queue, this condition can arise when an MQGET WAIT
call is in progress. If there is an MQGET signal outstanding, this
does not mean, by itself, that the handle is active. Inactive means
that no API call from this connection is currently in progress for
this object. If the object is a queue, this condition can arise when
no MQGET WAIT call is in progress.
Topic string The resolved topic string. This parameter is relevant for handles TOPICSTR
with OBJTYPE(TOPIC). For any other object type, this parameter
is blank.
Subscription name The application's unique subscription name that is associated SUBNAME
with the handle. This parameter is relevant only for handles
of subscriptions to topics. Not all subscriptions will have a
subscription name.
Subscription ID The internal, all-time unique identifier of the subscription. This SUBID
parameter is relevant only for handles of subscriptions to topics.
Not all subscriptions show up in DISPLAY CONN; only those that
have current handles open to the subscription show up. You can
use the DISPLAY SUB command to see all subscriptions.

458 IBM MQ Explorer

Property Meaning MQSC
parameter
Destination queue The destination queue manager for messages that are published DESTQMGR
manager to this subscription. This parameter is relevant only for handles
of subscriptions to topics. If DEST is a queue that is hosted on
the local queue manager, this parameter will contain the local
queue manager name. If DEST is a queue that is hosted on a
remote queue manager, this parameter will contain the name of
the remote queue manager.
Destination name The destination queue for messages that are published to this DEST
subscription. This parameter is only relevant for handles of
subscriptions to topics.
Asynchronous state The state of the asynchronous consumer on this object handle. ASTATE
There are five possible values:
Active: An MQCB call has set up a function to call back to
process messages asynchronously and the connection handle has
been started so that asynchronous message consumption can
proceed.
Inactive: An MQCB call has set up a function to call back to
process messages asynchronously but the connection handle has
not yet been started, or has been stopped or suspended, so that
asynchronous message consumption cannot currently proceed.
Suspended: The asynchronous consumption callback has been
suspended so that asynchronous message consumption cannot
currently proceed on this object handle. This can be either
because an MQCB call with Operation MQOP_SUSPEND has
been issued against this object handle by the application, or
because it has been suspended by the system. If it has been
suspended by the system, as part of the process of suspending
asynchronous message consumption the callback function will be
called with the reason code that describes the problem resulting
in suspension. This will be reported in the Reason field in the
MQCBC structure that is passed to the callback function. For
asynchronous message consumption to proceed, the application
must issue an MQCB call with the Operation parameter set to
MQOP_RESUME.

Susptemp: The asynchronous consumption call back has been

temporarily suspended by the system so that asynchronous
message consumption cannot currently proceed on this object
handle. As part of the process of suspending asynchronous
message consumption, the callback function will be called
with the reason code that describes the problem resulting in
suspension. This will be reported in the Reason field in the
MQCBC structure passed to the callback function. The callback
function will be called again when asynchronous message
consumption is resumed by the system, when the temporary
condition has been resolved.
None: An MQCB call has not been issued against this handle,
so no asynchronous message consumption is configured on this
handle. This is the default value.

Introduction to IBM MQ Explorer 459

Property Meaning MQSC
parameter
Read ahead The read ahead connection status. There are four possible values: READA
No: Read ahead of non-persistent messages is not enabled for
this object. This is the default value.
Yes: Read ahead of non-persistent message is enabled for this
object and is being used efficiently.
Backlog: Read ahead of non-persistent messages is enabled for
this object. Read ahead is not being used efficiently because the
client has been sent a large number of messages which are not
being consumed.
Inhibited: Read ahead was requested by the application but
has been inhibited because of incompatible options specified on
the first MQGET call.

Related tasks
“Viewing and closing connections to applications” on page 172
You can use the Application Connections dialog to find out which applications are currently connected
to a specific queue manager, and which queue manager objects an application is currently accessing. You
can also use this dialog to close a connection.

Message properties
Message properties are displayed in the Message properties dialog. You cannot edit any of the message
properties.
The following tables list the properties of IBM MQ messages that you can put and get from queues:
• General
• Report
• Context
• Identifiers
• Segmentation
• Named Properties
• MQRFH2 Properties
• Data
• Dead-letter header
For each property, there is a brief description of meaning of the property. The tables also show the MQMD
form of the name, as used in the API. This is described in MQMD - Message descriptor.

General page
The following table lists the properties on the General page of the Message properties dialog.

Property Meaning MQMD form

Position Read-only. The current position in the queue of the message. (Not
applicable.)

460 IBM MQ Explorer

Property Meaning MQMD form
Message type Read-only. This is the type of the message: Datagram means MsgType
that the message does not require a reply; Request means that
the message requires a reply; Reply means that the message
is a reply to an earlier request message; Report means that
the message is reporting on some expected or unexpected
occurrence, usually related to some other message. For example,
a request message that contained data that was not valid.
Priority Read-only. This is the priority of the message. The lowest priority Priority
is 0.
Persistence Read-only. This indicates whether the message is persistent or Persistence
nonpersistent. If the message is persistent, it survives system
failures and restarts of the queue manager. If the message
is nonpersistent, it survives a restart only if it is present on
a queue having the NPMCLASS(HIGH) property. However, even
with the NPMCLASS(HIGH) property a message does not survive
a QMGR class. Nonpersistent messages on queues having the
NPMCLASS(NORMAL) property are discarded at queue manager
restart, even if the message is found on the auxiliary storage
during the restart procedure.
Put date/time Read-only. This is the date when the message was put. PutDate;
PutTime
Expiry Read-only. This is the period of time, in tenths of a second, after Expiry
which the message becomes eligible to be discarded if it has not
already been removed from the target queue. The expiry interval
is set by the application that put the message.
Reply-to queue Read-only. This is the name of the message queue to which the ReplyToQ
application that issued the get request for the message should
send the reply and report messages.
Reply-to queue manager Read-only. This is the name of the queue manager on which the ReplyToQmgr
reply-to queue is defined.
Backout count Read-only. This is the number of times the message has BackoutCount
previously been returned by the MQGET call as part of a unit of
work, and subsequently backed out.

Report page
The following table lists the properties on the Report page of the Message properties dialog. A report is
a message about another message, used to inform the application about expected or unexpected events
that relate to the original message. The Report page displays the properties related to report messages.
For more information, see Report options and message flags.

Property Meaning MQMD form

Report Read-only. This field is where the sender application specifies Report
whether report messages are required, whether the application
data is to be included in the report messages, and also how the
message and correlation identifiers in the report or reply message
are to be set.
Feedback Read-only. This is used only with report messages to indicate the Feedback
nature of the report.

Introduction to IBM MQ Explorer 461

Property Meaning MQMD form
Original length Read-only. This is used only with report messages to indicate the OriginalLength
length of the original message to which the report relates.

Context page
The following table lists the properties on the Context page of the Message properties dialog. The
Context page displays information from the sender application about the message.

Property Meaning MQMD form

User identifier Read-only. This is the user identifier of the application that UserIdentifier
originated the message.
Application type Read-only. This is the type of application that put the message, PutApplType
for example, CICS or AIX.
Put application name Read-only. This is the name of the application that put the PutApplName
message. This name might appear truncated.
Application identity data Read-only. This is information that is defined by the application ApplIdentityDa
suite, and can be used to provide information about the message ta
or its originator.
Application origin data Read-only. This is information that is defined by the application ApplOriginData
suite, and can be used to provide additional information about the
origin of the message.
Accounting token Read-only. This is information that allows the application to AccountingTok
appropriately charge work that is done as a result of the message. en

Identifiers page
The following table lists the properties on the Identifiers page of the Message properties dialog. The
Identifiers page displays identification information that is associated with the message.

Property Meaning MQMD form

Message identifier Read-only. This is the message identifier, which is used to MsgId
distinguish one message from another.
Message identifier bytes Read-only. This is the message identifier in byte form. MsgId
Correlation identifier Read-only. This is the correlation identifier, which the application CorrelId
can use to relate one message to another, or to relate the
message to other work that the application is performing.
Correlation identifier Read-only. This is the correlation identifier in byte form. CorrelId
bytes
Group identifier Read-only. This is the group identifier, which is used to identify GroupId
the particular message group or logical message to which the
physical message belongs.
Group identifier bytes Read-only. This is the group identifier in byte form. GroupId

Segmentation page
The following table lists the properties on the Segmentation page of the Message properties dialog. The
Segmentation page displays the properties related to segmenting large messages.

462 IBM MQ Explorer

Property Meaning MQMD form
Logical sequence number Read-only. This is the sequence number of the logical message MsgSeqNumbe
within the group. Sequence numbers start at 1, and increase by r
1 for each new logical message in the group, up to a maximum
of 999,999,999. A physical message that is not in a group has a
sequence number of 1.
Offset Read-only. This is the offset of data in the physical message from Offset
the start of the logical message.
Flags Read-only. These are the message flags that specify properties of MsgFlags
the message, or control its processing.

Named Properties page

The following table lists the properties on the Named Properties page of the Message properties
dialog. The Named Properties page is present only when you have selected as Named Properties
on the Message properties page of the Preferences dialog, and if the selected message has properties.
Properties of the message, except those contained in the message descriptor or extension, must be
represented in the Named Properties panel in name value pairs, and the properties are removed from the
message data.
The MQGMO Option is MQGMO_PROPERTIES_IN_HANDLE, for more information on the relevant Get
Message Options see“MQ Get Message Options” on page 465.
For more information on the Preferences dialog, see Configuring MQ Explorer.

Property Meaning
Name Read-only. The name of the message property.
Value Read-only. This is the actual value of the named
property.

MQRFH2 Properties page

The following table lists the properties on the MQRFH2 Properties page of the Message properties
dialog. There are 2 ways to make the MQRFH2 Properties page visible:
• Select as an MQRFH2 structure in message body on the Messages page of the Preferences
dialog.
Properties of the message, except those contained in the message descriptor or extension, must be
represented in the MQRFH2 Properties and the properties remain in the message data. The MQGMO
Option is MQGMO_PROPERTIES_FORCE_MQRFH2, for more information on the relevant Get Message
Options see “MQ Get Message Options” on page 465.
• Select as an MQRFH2 structure in message body compatible with WebSphere MQ V6 on
the Messages page of the Preferences dialog. The MQRFH2 Properties page will only be visible if the
message contains a property with a prefix of mcd, jms, usr, or mqext
If the message contains a property with a prefix of mcd, jms, usr, or mqext, all message properties,
except those contained in the message descriptor or extension, must be represented in the MQRFH2
Properties panel and the properties remain in the message data. Otherwise, all properties of the
message, except those contained in the message descriptor or extension, are discarded and not
displayed. The MQGMO Option is MQGMO_PROPERTIES_IN_COMPATIBILITY, for more information on
the relevant Get Message Options see“MQ Get Message Options” on page 465.
For more information on the Preferences dialog, see Configuring MQ Explorer.

Introduction to IBM MQ Explorer 463

 As the MQRFH2 structure is nested xml, the MQRFH2 Properties page displays the MQRFH2 properties
in a tree view. All properties with the same synonym are grouped under the synonym tree which can be
expanded to display all the properties, and collapsed to hide all the properties.

Property Meaning
Name Read-only. The name of the message property.
Value Read-only. This is the actual value of the named
property.

Data page
The following table lists the properties on the Data page of the Message properties dialog. The Data page
displays the message data itself and information about the data format.

Property Meaning MQMD form

Data length Read-only. This is the length of the original message. OriginalLength
Format Read-only. This is the name that the sender of the message has Format
used to indicate to the receiver the nature of the data in the
message.
Coded character set Read-only. This is the coded character set identifier of the CodedCharSet
identifier character data in the application message data. Id
Encoding Read-only. This is the numeric encoding of numeric data in the Encoding
message. This value does not apply to numeric data in the MQMD
structure itself.
Message data Read-only. This is the message data in human readable ASCII (Not
text. applicable.)
Message data bytes Read-only. This is the message data in hexadecimal format. (Not
applicable.)

Dead-letter header page

The following table lists the properties on the Dead-letter header page of the Message properties dialog.
The Dead-letter header page is present only when the message has a dead-letter header.

Property Meaning MQMD form

Reason This identifies the reason why the message was placed on Reason
the dead-letter (undelivered message) queue instead of on the
original destination queue.
Destination queue The name of the message queue that was the original destination DestQName
for the message.
Destination queue The name of the queue manager that was the original destination DestQMgrNam
manager for the message. e
Original encoding This specifies the numeric encoding of the data that follows the Encoding
MQDLH structure (usually the data from the original message); it
does not apply to numeric data in the MQDLH structure itself.
Original CCSID This specifies the character set identifier of the data that CodedCharSet
follows the MQDLH structure (usually the data from the original Id
message); it does not apply to character data in the MQDLH
structure itself.

464 IBM MQ Explorer

Property Meaning MQMD form
Original format This specifies the format name of the data that follows the Format
MQDLH structure (usually the data from the original message).
Put application type The type of application that put the message. This is part of the PutApplType
origin context of the message. For more information on message
context, see Message context.
Put application name The name of the application that put the message on the PutApplName
dead-letter queue. The format of the name depends on the
Put Application Type property. This name might appear
truncated.
Put date The date when the message was put on the dead-letter queue. PutDate
Put time The time when the message was put on the dead-letter queue. PutTime

Related tasks
“Sending test messages” on page 71
You can use a test message to check whether an application or a queue manager can put a message on a
queue. You can also browse messages that are already on a queue or clear messages from a queue.

MQ Get Message Options

MQ Get Message options control the action of MQGET.
You can specify none, one, or more of the options described later in this section. If you need more than
one option, the values can be:
• Added (do not add the same constant more than once), or
• Combined using the bitwise OR operation (if the programming language supports bit operations).
The initial value of the Options field is MQGMO_NO_WAIT plus MQGMO_PROPERTIES_AS_Q_DEF.

Property options
The following options relate to the properties of the message:
MQGMO_PROPERTIES_AS_Q_DEF
Properties of the message, except the properties contained in the message descriptor (or extension)
must be represented as defined by the PropertyControl queue property. If a MsgHandle is
provided this option is ignored and the properties of the message are available using the MsgHandle,
unless the value of the PropertyControl queue property is MQPROP_FORCE_MQRFH2.
This is the default action if no property options are specified.
MQGMO_PROPERTIES_IN_HANDLE
Properties of the message must be made available using the MsgHandle. If no message handle is
provided the call fails with reason MQRC_HMSG_ERROR.
MQGMO_NO_PROPERTIES
No properties of the message, except the properties contained in the message descriptor (or
extension) are retrieved. If a MsgHandle is provided it is ignored.
MQGMO_PROPERTIES_FORCE_MQRFH2
Properties of the message, except the properties contained in the message descriptor (or extension)
must be represented using MQRFH2 headers. This provides compatibility with earlier versions for
applications which are expecting to retrieve properties but are unable to be changed to use message
handles. If a MsgHandle is provided it is ignored.

Introduction to IBM MQ Explorer 465

 MQGMO_PROPERTIES_COMPATIBILITY
If the message contains a property with a prefix of "mcd.", "jms.", "usr.", or "mqext.", all
message properties are delivered to the application in an MQRFH2 header. Otherwise all properties of
the message, except the properties contained in the message descriptor (or extension), are discarded
and are no longer accessible to the application.

Default option
If none of the options described previously is required, the following option can be used:
MQGMO_NONE
Use this value to indicate that no other options have been specified; all options assume their default
values. MQGMO_NONE aids program documentation; it is not intended that this option is used with
any other, but because its value is zero, such use cannot be detected.

Connection details properties

You can view and set properties for connections in the Connection Details properties dialog.
To view connection details properties, right-click on the queue manager, select Connection details, and
then click Properties. The following tables list all the properties that you can set:
• General
• Security exit
• Userid
• SSL key repositories
• SSL options

General page
The following table lists the properties that you can set on the General page of the Connection Details
properties dialog.

Item Description
Queue manager name Read-only. The name of the local queue manager.
Connection type Read-only. The type of connection. The three possible
values are:
1. Local. A local connection.
2. Client. A client connection.
3. Indirect. A connection through another queue
manager.

Connection name Read-only. The connection name that is associated

with the channel that owns the handle. If no channel
is associated with the handle, this value is empty. This
value is shown only when the handle belongs to the
channel initiator.
Channel name Read-only. The name of the channel definition.
Refresh interval (seconds) The frequency with which IBM MQ Explorer refreshes
its information about the queue manager.

466 IBM MQ Explorer

Item Description
Autoreconnect The configuration of the connection to each queue
manager so that IBM MQ Explorer automatically
connects to it at startup or reconnects to it if
the connection is lost; for example, if the network
connection to a remote queue manager fails.
Important: You can enable either the Autoreconnect
property, or the Prompt for password property,
described on the “Userid page” on page 467, but not
both.

Wait interval The number of seconds that IBM MQ Explorer waits

for messages on the reply queue.
Expiry interval The number of seconds that messages remain on
the reply queue. This queue is the one that IBM
MQ Explorer is using to communicate with the queue
manager.

Security exit page

The following table lists the properties that you can set on the Security exit page of the Connection
Details properties dialog.

Item Description
Exit Specifies the name of the exit program to be run by the security exit. Exit name can be
name up to 1024 characters long and is case sensitive. Exit name can be a fully qualified java
class name found in the directory or jar file. Exit name can be a C exit, of the format:
dll_name(function_name). The default path for exits is always used to locate C exits, you
cannot specify the location of the exit library in this entry field unless no default path is set.
in Specifies the directory for the security exit (Java exits only).
directory
in jar Specifies the jar file for the security exit (Java exits only).
Exit data Exit data can be up to 32 characters long. If no value has been defined for that attribute,
this field is all blanks.

Userid page
The following table lists the properties that you can set on the Userid page of the Connection Details
properties dialog.

Item Description
Enable Select Enable user identification to enable the fields on this dialog.
user
identifica
tion
User When selected, the userid and password are passed to the server in a way compatible with security
identifica exits created prior to IBM MQ 8.0.
tion
compatib
ility Mode

Introduction to IBM MQ Explorer 467

Item Description
Userid The userid and password, when specified, are passed to the server, and can be used either by:
• The queue manager, if configured to use connection authentication, or
• A server security exit, if using a client connection
to establish the identity of the IBM MQ Explorer user.
No When selected, no password is passed to the server with the userid.
password
Prompt When selected, the user is prompted for a password that is passed to the server with the userid.
for The prompting occurs as part of the connect operation.
password
Important: You can enable either the Prompt for password property, or the Autoreconnect
property, described on the “General page” on page 466, but not both.

Use When selected, the saved password is passed to the server with the userid.
saved
password
Saved The saved password to be passed to the server with the userid.
password

SSL key repositories page

The following table lists the properties that you can set on the SSL key repositories page of the
Connection Details properties dialog.

Item Description
Trusted Certificate Store The location of the truststore on the computer. In
the Trusted Certificate Store field, browse for the
location of the truststore on the computer. The
truststore and keystore contain the TLS certificates
that are used with connections that use client channel
definition tables. It is possible that the truststore and
keystore are in the same location on your computer.
Personal Certificate Store The location of the truststore on the computer. In
the Personal Certificate Store field, browse for the
location of the keystore on the computer.

For more information about configuring IBM MQ Explorer with the default location and password of the
TLS certificate store, see “Specifying the default location and default password of TLS certificates” on
page 87.

SSL options page

The following table lists the properties that you can set on the SSL options page page of the Connection
Details properties dialog.

Item Description
SSL FIPS required Read-only. If set to No (the default), any available
cipher suite can be used. If set to Yes, then only FIPS-
certified cipher suites can be used.

468 IBM MQ Explorer

Item Description
SSL CipherSpec The SSL CipherSpec identifies the combination of
encryption algorithm and hash function that is used
by a TLS connection. A CipherSpec forms part of a
cipher suite, which identifies the key exchange and
authentication mechanism and the encryption and
hash function algorithms.
The size of the key that is used during the TLS
handshake can depend on the digital certificate you
use, but some of the CipherSpecs supported by IBM
MQ include a specification of the handshake key
size. Larger handshake key sizes provide stronger
authentication. With smaller key sizes, the handshake
is faster.

SSL reset count The number of bytes, 0 - 999 999 999, that are
sent and received within a TLS conversation before
the secret key is renegotiated. A value of 0 means
that the secret key is never renegotiated. The number
of bytes includes control information that is sent by
the message channel agent (MCA). If the value of
this property is greater than 0 and the value of the
Heartbeat interval property in the Channel properties
is greater than 0, the secret key is also renegotiated
before message data is sent or received following a
channel heartbeat.
Peer name The Distinguished Name (DN) of the queue manager
to be used by TLS. The peer name is set to indicate
that connections are allowed only where the server is
successfully authenticated as a specific DN.

Connection factory properties

You can view and set connection factory properties in the Connection Factory properties dialog. The
properties that are available in the dialog depend on which messaging provider the connection factory
uses.
The following tables list all the properties that you can set:
• General
• Connection
• Reconnection
• Channels
• SSL
• Exits
• Broker
• Temporary queues
• Temporary topics
• Subscriber
• Extended
• Advanced tuning

Introduction to IBM MQ Explorer 469

 For each property, there is a brief description of when you might need to configure the property. The
tables also give the equivalent long and short names to use in the JMS Administration command line
tool. The properties that are available in the Properties dialog depend on which messaging provider the
connection factory uses. For more information about the JMS Administration command line tool, see
Configuring JMS objects using the administration tool.

General page
The following table lists the properties that you can set on the General page of the Connection Factory
properties dialog.

Property Meaning Long name Short name

Name This is the name of the NAME
object.
Description Type a description of the DESCRIPTION DESC
object.
Class name This shows the class
name that is implemented
by the connection factory.
Messaging provider This shows whether the
connection factory uses
MQ transport (Bindings
or Client) or Real-time
transport (Direct or
Direct HTTP). Real-time
transport is not available
in IBM MQ 8.0. If you
are using IBM MQ 8.0
you can define Real-time
transport, but it fails when
an attempt is made to
create a connection.

470 IBM MQ Explorer

Property Meaning Long name Short name
Transport This shows the transport TRANSPORT TRAN
type used for the
connection. Bindings is
a direct connection to the
queue manager that is
on the same computer as
the JMS client; Client
is a client connection
using TCP/IP (the queue
manager can be on
the same or different
computer); Direct is a
direct connection to a
broker of IBM Integration
Bus; Direct HTTP is a
direct connection using
HTTP tunneling. Although
this field is read-only,
you can change the
transport type if there is
an alternative transport
type available for the
messaging provider; for
more information, see
Changing the transport
type used for connections.

Introduction to IBM MQ Explorer 471

Property Meaning Long name Short name
Provider version Select, or type, PROVIDERVERSION PVER
the version, release,
modification level and
fix pack of the queue
manager to which this
client is intended to
connect. If you type the
value, use one of the
following formats:
• V.R.M.F
• V.R.M
• V.R
• V
where V, R, M and F
are integer values greater
than or equal to zero.
A value of "8" or greater
indicates that this is
intended as an IBM
MQ 8.0 ConnectionFactory
for connections to an
IBM MQ 8.0 queue
manager. The default
value, unspecified,
allows connections to
any level of queue
manager, determining the
applicable properties and
functionality available
based on the queue
manager's capabilities.

For more information

about troubleshooting
problems that can arise
when you are connecting
to a queue manager with a
specific provider version,
see JMS provider version
troubleshooting.

Client identifier The client identifier is CLIENTID CID

used to uniquely identify
the application connection
for durable subscriptions.
Type an identifier for the
client

472 IBM MQ Explorer

Property Meaning Long name Short name
Max buffer size Type the maximum MAXBUFFSIZE MBSZ
number of received
messages that can be
stored in an internal
message buffer while
waiting to be processed
by the client application.
This property applies only
when the Transport
property has the value
Direct and Direct
HTTP. The default is 1000.

Connection page
The following table lists the properties that you can set on the Connection page of the Connection
Factory properties dialog. Edit the properties on the Connection page to set the connection details for
connections created by this connection factory.

Property Meaning Long name Short name

Application name Specify the name by APPLICATIONNAME APPNAME
which the application
identifies itself. For
more information, see
Specifying the application
name in supported
programming languages.
Base queue manager Select or type the name QMANAGER QMGR
of the queue manager
to connect to. If your
application uses a client
channel definition table
to connect to a queue
manager, see Client
channel definition table.
Connection list CLIENTRECONNECTHOST CRHOSTS
Comma separated list
S
of HOSTNAME(PORT)
connection addresses.
The list is tried in order,
once per each connection
retry attempt.
HOSTNAME can be a DNS
name or IP address.
PORT defaults to 1414.

Host name Type the host name or IP HOSTNAME HOST

address of the computer
that hosts the queue
manager or, for a direct
connection to a broker,
the computer that hosts
the broker.

Introduction to IBM MQ Explorer 473

Property Meaning Long name Short name
Port Type the port number on PORT -
which the queue manager
or broker listens. The
default is 1414 if the
Transport property is
set to Client; the default
is 1506 if the Transport
property is set to Direct
or Direct HTTP.
Proxy host name Type the host name of the PROXYHOSTNAME PHOST
proxy server for a direct
connection.
Proxy port Type the port number PROXYPORT PPORT
of the proxy server for
a direct connection. The
default is 443.
Coded character set ID Type the coded character CCSID CCS
set ID (CCSID) to be
used on connections. For
optimum performance,
the value of this property
should be the same
as the value of the
Coded Character Set ID
attribute (Queue manager
properties) of the base
queue manager.

474 IBM MQ Explorer

Property Meaning Long name Short name
Multicast Specify whether MULTICAST MULTI
messages are delivered
to message consumers
using multicast transport.
Multicast transport is
applicable only to topic
destinations and can
be used only when
the connection factory
uses Direct IP transport.
Direct IP transport is not
available in IBM MQ 8.0.
If you are using IBM MQ
8.0 you can define Direct
IP transport, but it fails
when an attempt is made
to create a connection.
The default value is
Disabled, which means
that messages are not
delivered to a message
consumer using multicast
transport.
Click Enabled to deliver
messages to the message
consumer using multicast
transport. The topic must
be configured for reliable
multicast in the broker; a
reliable quality of service
is used if the topic is
configured for reliable
multicast.

Introduction to IBM MQ Explorer 475

Property Meaning Long name Short name

Click Reliable to deliver

messages to the message
consumer using multicast
transport with a reliable
quality of service. The
topic must be configured
for reliable multicast in
the broker; if the topic
is not configured for
reliable multicast, you
cannot create a message
consumer for the topic.
Click Not reliable to
deliver messages using
multicast transport but
without using a reliable
quality of service. The
topic must be configured
for multicast in the broker;
a reliable quality of
service is not used, even if
the topic is configured for
reliable multicast.

476 IBM MQ Explorer

Property Meaning Long name Short name
Local address For a connection to a LOCALADDRESS LA
queue manager, specify
either the local network
interface to be used, or
the local port (or range of
local ports) to be used, or
both. The channel binds to
the address locally. Use
the format
ipaddress(low-port,
high-port), where
ipaddress is the IP
address specified in IPv4
dotted decimal, IPv6
hexadecimal, or
alphanumeric host name
format. For example,
127.0.0.1 specifies the
IPv4 address with any
port; 127.0.0.1(1000)
specifies the IPv4 address
and a specific port;
127.0.0.1(1000,2000
) specifies the IPv4
address and a range of
ports; (1000) specifies a
port only. If you are using
a direct connection to a
broker, this property is
relevant only when
multicast is used. Specify
the local network
interface to be used, as an
IP address or as a host
name, but do not specify
any port number.

Introduction to IBM MQ Explorer 477

Property Meaning Long name Short name
Connect options Select how the application CONNOPT CNOPT
connects to the queue
manager.
Click Standard for the
nature of the binding
between the application
and the queue manager
to depend on the platform
on which the queue
manager is running and
how the queue manager is
configured.
Click Shared for the
application and the local
queue manager agent to
run in separate units of
execution but share some
resources.
Click Isolated for the
application and the local
queue manager agent to
run in separate units of
execution.
Click Fastpath for the
application and the local
queue manager agent to
run in the same unit of
execution.
Click Serial queue
manager for the
application to request
exclusive use of the
connection tag within
the scope of the queue
manager.
Click Serial queue
sharing group for the
application to request
exclusive use of the
connection tag within
the scope of the queue
sharing group to which the
queue manager belongs.

478 IBM MQ Explorer

Property Meaning Long name Short name

Click Restricted queue

manager for the
application to request
shared use of the
connection tag but
restricting the shared use
of the connection tag
within the scope of the
queue manager.
Click Restricted queue
sharing group for the
application to request
the shared use of
the connection tag but
restricting the shared use
of the connection tag
within the scope of the
queue sharing group to
which the queue manager
belongs.
The Standard,
Shared, Isolated, and
Fastpath options are
ignored if the JMS
application connects
using a client
connection.
The Shared, Isolated,
and Fastpath options
are ignored by IBM MQ
for z/OS queue managers;
the Serial queue
manager, Serial
queue sharing
group, Restricted
queue manager, and
Restricted queue
sharing group options
are supported only by
IBM MQ for z/OS queue
managers.

This is a tag that CONNTAG CNTAG

the queue manager
Connection associates with the
tag resources that are
updated by the
application within a unit of
work while the application
is connected to the queue
manager. The connection
tag is supported only by
IBM MQ for z/OS queue
managers.

Introduction to IBM MQ Explorer 479

Property Meaning Long name Short name
Share conversations Click Yes (the default SHARECONVALLOWED SCA
allowed value) to specify that
a client connection can
share its socket with other
JMS connections from the
same process to the same
queue manager, if the
channel definitions match.
Otherwise, click No.

480 IBM MQ Explorer

 Reconnection page
Property Meaning Long name Short name
Options Do not reconnect CLIENTRECONNECTOPTI CROPT
The application will ONS
not be reconnected.
Reconnect
The application can
reconnect to any
queue manager.
Use the reconnect
option only if there
is no affinity between
the client application
and the queue
manager with which it
initially established a
connection.
Reconnect to the same
queue manager
The application can
reconnect, but only to
the queue manager
to which it originally
connected.
Use this value
if a client can
be reconnected,
but there is an
affinity between the
client application,
and the queue
manager to which
it first established a
connection.
Choose this value
if you want a
client to automatically
reconnect to the
standby instance of a
highly available queue
manager.
Automatic client
reconnect is not
supported by IBM MQ
classes for Java.

Timeout Interval in seconds before CLIENTRECONNECTTIME CRT

reconnection retries OUT
cease. The default is 1800
seconds (30 minutes).

Introduction to IBM MQ Explorer 481

 Channels page
The following table lists the properties that you can set on the Channel page of the Connection Factory
properties dialog. Edit the properties on the Channel page to configure how the JMS client connects to
the queue manager.

Property Meaning Long name Short name

Channel Select or type the name CHANNEL CHAN
of the server-connection
channel to use to connect
the client to the queue
manager. To use Select to
enter the name, you must
have already entered a
value for the Base Queue
Manager property on the
Connection page, and the
selected queue manager
must be running. You
must set a value for either
the Channel property
or for the Client
Channel Definition
Table URL property but
not both.
Client channel definition Enter the uniform CCDTURL CCDT
table URL resource locator (URL)
that identifies the name
and location of the file
that contains the client
channel definition table
and specifies how the
file can be accessed. You
must set a value for either
the Channel property
or for the Client
Channel Definition
Table URL property but
not both.
Header compression Click Edit then select COMPHDR HC
the list of techniques
that can be used for
compressing header data
on a connection.
Message compression Click Edit then select the COMPMSG MC
list of techniques that can
be used for compressing
message data on a
connection.

SSL page
The following table lists the properties that you can set on the SSL page of the Connection Factory
properties dialog. Edit the properties on the SSL page to configure the TLS details for securing client
connections and direct connections to the broker.

482 IBM MQ Explorer

Property Meaning Long name Short name
Direct SSL authentication To enable TLS DIRECTAUTH DAUTH
authentication for a
direct connection, click
Certificate. To disable
authentication, user
name authentication, and
password authentication,
click Basic.
CipherSuite Select the CipherSuite to SSLCIPHERSUITE SCPHS
use for an TLS connection.
The CipherSuite must
match the CipherSpec
of the server-connection
channel that is specified
in the Channel property
on the Channels page.
If you do not
select a CipherSuite,
the FIPS Required,
Certificate
Revocation List,
Peer Name, and Reset
Count properties are
ignored.
FIPS required Click Yes to specify that SSLFIPSREQUIRED SFIPS
an TLS connection must
use a CipherSuite that
is supported by the IBM
Java JSSE FIPS provider
(IBMJSSEFIPS). Click No
if an TLS connection can
use any CipherSuite.
Certificate revocation list Enter a list of certificate SSLCRL SCRL
revocation list servers to
check for TLS certificate
revocation.
Peer name Type a distinguished name SSLPEERNAME SPEER
skeleton that must match
that provided by the
queue manager. The TLS
peer name must also
match the TLS peer name
of the server-connection
channel that is specified
in the Channel property
on the Channels page.
Reset count Enter the total number of SSLRESETCOUNT SRC
bytes sent and received
by a connection before
the secret key that is
used for encryption is
negotiated.

Introduction to IBM MQ Explorer 483

 Exits page
The following table lists the properties that you can set on the Exits page of the Connection Factory
properties dialog. User exits are code modules that you provide yourself to do additional processing on
the message data (for example, encryption or data compression). Edit the properties on the Exits page to
change the default location of client exit code modules that are run when called.

Property Meaning Long name Short name

Send exit name Enter the name of the SENDEXIT SDX
channel send exit or the
sequence of send exits to
be run in succession. Each
entry in the list must be
either the name of a class
that implements the IBM
MQ Java interface
MQSendExit (for a channel
send exit written in Java),
or a string in the format
libraryName(entryPointNa
me) (for a channel send
exit not written in Java).
Send exit initialization Enter the user data that SENDEXITINIT SDXI
is passed to channel
send exits when they are
called. You can enter one
or more items of user data
separated by commas.
Receive exit name Enter the name of the RECEXIT RCX
channel receive exit, or a
sequence of receive exits,
to be called. Each entry in
the list must be either the
name of a class that
implements the IBM MQ
Java interface
MQReceiveExit (for a
channel receive exit
written in Java), or a string
in the format
libraryName(entryPointNa
me) (for a channel receive
exit not written in Java).
Receive exit initialization Enter the user data that RECEXITINIT RCXI
is passed to channel
receive exits when they
are called. You can enter
one or more items of
user data separated by
commas.

484 IBM MQ Explorer

Property Meaning Long name Short name
Security exit name Type either the name of a SECEXIT SCX
class that implements the
IBM MQ Java interface
MQSecurityExit (for a
channel security exit
written in Java) or a string
in the format
libraryName(entryPointNa
me) (for a channel security
exit not written in Java).
Security exit initialization Type the user data that SECEXITINIT SCXI
is passed to the channel
security exit when it is
called.

Broker page
The following table lists the properties that you can set on the Broker page of the Connection Factory
properties dialog. Edit the properties on the Broker page to provide details of the publish/subscribe
broker.

Property Meaning Long name Short name

Broker subscription This property can be used BROKERSUBQ BSUB
message queue in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Select or type the name of
the queue from which
non-durable subscription
messages are received.
The default queue is
SYSTEM.JMS.ND.SUBSC
RIBER.QUEUE. To use
Select to enter the name,
you must have already
selected a value for the
Base Queue Manager
property on the
Connection page, and the
selected queue manager
must be running.

Introduction to IBM MQ Explorer 485

Property Meaning Long name Short name
Broker CC subscription This property can be used BROKERCCSUBQ CCSUB
message queue in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Select or type the name of
the queue from which
non-durable subscription
messages are retrieved
for a
ConnectionConsumer. The
default queue is
SYSTEM.JMS.CC.SUBSC
RIBER.QUEUE. To use
Select to enter the name,
you must have already
selected a value for the
Base Queue Manager
property on the
Connection page, and the
selected queue manager
must be running.
For more information,
see the BROKERSUBQ
property.

Broker control queue This property can be used BROKERCONQ BCON

in an IBM MQ JMS client
but has no effect on anc
IBM MQ, or later, queue
manager.
Select or type the name
of the broker's control
queue. To use Select to
enter the name, you must
have already selected a
value for the Broker
Queue Manager property
on the Connection page,
and the selected queue
manager must be running.

486 IBM MQ Explorer

Property Meaning Long name Short name
Publication stream This property can be used BROKERPUBQ BPUB
in an IBM MQ JMS client
but has no effect on an
IBM MQ, or later, queue
manager.
Select or type the name of
the queue where
published messages are
sent (the stream queue).
The default queue is
SYSTEM.BROKER.DEFAU
LT.STREAM. To use Select
to enter the name, you
must have already
selected a value for the
Broker Queue
Manager property on the
Connection page, and the
selected queue manager
must be running.
Broker version This property can be used BROKERVER BVER
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Select the version of the
broker being used. Click
V1 to use an IBM MQ
publish/subscribe broker
or IBM Integration Bus in
compatibility mode; this
is the default value if
the Transport property
is set to Bindings or
Client. Click V2 to
use IBM Integration Bus
in native mode; this
is the default value if
the Transport property
is set to Direct or
DirectHTTP.

Introduction to IBM MQ Explorer 487

Property Meaning Long name Short name
Publication This property can be used PUBACKINT PAI
acknowledgment interval in an IBM MQ JMS client
but has no effect on an
IBM MQ, or later, queue
manager.
Enter the number of
messages that are
published by a publisher
before the IBM MQ
JMS client requests an
acknowledgment from the
broker. If you decrease
the value of this property,
the client requests
acknowledgments more
often and, therefore,
the performance of the
publisher decreases. If
you raise the value, the
client takes a longer time
to throw an exception
if the broker fails. This
property is relevant only if
the Transport property
has the value Bindings
or Client. The default
value is 25.

Temporary queues page

The following table lists the properties that you can set on the Temporary queues page of the Connection
Factory properties dialog. Edit the properties on the Temporary queues page to specify how the JMS
temporary queues are dynamically defined.

Property Meaning Long name Short name

Temporary model queue Select or type the name TEMPMODEL TM
of the model queue from
which JMS temporary
queues are created. To
use Select to enter the
name, you must have
already selected a value
for the Base Queue
Manager property on the
Connection page, and the
selected queue manager
must be running.

488 IBM MQ Explorer

Property Meaning Long name Short name
Temporary queue prefix Type the prefix that is TEMPQPREFIX TQP
used to form the name
of an IBM MQ dynamic
queue. The rules for
forming the prefix are the
same as those for forming
the contents of the
DynamicQName field in an
IBM MQ object descriptor
(MQOD) but the last non-
blank character must be
an asterisk (*). If no
value is specified for the
property, the value used
is AMQ.*. On
z/OS systems, the value
used is CSQ.*.

Temporary topics page

The following table lists the properties that you can set on the Temporary topics page of the Connection
Factory properties dialog. Edit the properties on the Temporary topics page to specify how the JMS
temporary topics are dynamically defined.

Property Meaning Long name Short name

Temporary topic prefix Type the prefix that is TEMPTOPICPREFIX TTP
used to form the name of
a temporary topic. When
creating temporary topics,
JMS generates a topic
string of the form TEMP/
TEMPTOPICPREFIX/
unique_id, or if this
property uses the
default value, just
TEMP/unique_id.

Subscriber page
The following table lists the properties that you can set on the Subscriber page of the Connection Factory
properties dialog. Edit the properties on the Subscriber page to manage subscribers and subscriptions.

Introduction to IBM MQ Explorer 489

Property Meaning Long name Short name
Message selection This property can be used MSGSELECTION MSEL
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
To specify that message
selection is done by the
JMS client application,
click Client. To specify
that message selection
is done by the broker,
click Broker. If the
Transport property on
the General page has the
value Direct, message
selection is always done
by the broker and the
value of the Message
Selection property
is ignored. Message
selection by the broker
is not supported when
the Broker Version
property on the Broker
page has the value V1.
Sparse subscriptions This property can be used SPARSESUBS SSUBS
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
This property controls the
message retrieval policy
of a TopicSubscriber
object. To specify that
subscriptions receive
frequent matching
messages, click No. To
specify that subscriptions
receive infrequent
matching messages, click
Yes.

490 IBM MQ Explorer

Property Meaning Long name Short name
Subscription store This property can be used SUBSTORE SS
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Select the location where
IBM MQ JMS should store
persistent data relating to
active subscriptions. To
store subscription
information on the queues
SYSTEM.JMS.ADMIN.QUE
UE and
SYSTEM.JMS.PS.STATUS.
QUEUE, click Queue. To
store subscription
information in the publish/
subscribe broker and not
on queues, click Broker.
To dynamically select a
queue-based or broker-
based subscription store
depending on the release
levels of IBM MQ and the
publish/subscribe broker
that is installed, click
Migrate, which is selected
by default. For more
information about
subscription stores, see
Writing IBM MQ classes
for JMS applications.
Cleanup level This property can be used CLEANUP CL
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Select the cleanup level
for subscription stores for
which the Subscription
Store property on the
Broker page is set to
Broker or Migrate.
Cleanup interval This property can be used CLEANUPINT CLINT
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Type the number of
milliseconds interval
between background runs
of the publish/subscribe
cleanup utility.

Introduction to IBM MQ Explorer 491

Property Meaning Long name Short name
Clone support Specify whether two CLONESUPP CLS
or more instances of
the same durable topic
subscriber can run
simultaneously. Note that
enabling clone support
contravenes the JMS 1.1
specification. To specify
that only one instance of
a durable topic subscriber
can run at a time,
click Disabled. This is
the default value. To
specify that two or more
instances of the same
durable topic subscriber
can run simultaneously,
each instance running in
a separate Java virtual
machine (JVM), click
Enabled.
Status refresh interval This property can be used STATREFRESHINT SRI
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Type the number of
milliseconds interval
between refreshes of the
long-running transaction
that detects when a
subscriber loses its
connection to the
queue manager. This
property is relevant only
if the Subscription
Store property on
the Broker page has
the value Queue. For
more information about
subscription stores, see
Writing IBM MQ classes
for JMS applications.

492 IBM MQ Explorer

Property Meaning Long name Short name
Wildcard format Specify which version of WILDCARDFORMAT WCFMT
wildcard syntax is to be
used.
Click Only character
wildcards to use
only character wildcards
(for consistency with
applications that
previously used Broker
Version 1; see the Broker
version property).
Click Only topic
wildcards to use only
topic level wildcards,
which are used in Broker
Version 2.

Extended page
The following table lists the properties that you can set on the Extended page of the Connection
Factory properties dialog. Edit the properties on the Extended page to change further properties of the
connection factory object.

Property Meaning Long name Short name

Message batch size This property can be used MSGBATCHSZ MBS
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Type the maximum
number of messages to
be taken from a queue
in one packet when using
asynchronous message
delivery. The default is 10.
Message retention Specify whether the MSGRETENTION MRET
connection consumer
keeps unwanted
messages on the input
queue. To keep unwanted
messages on the input
queue, click Yes. To
deal with unwanted
messages according to
their disposition options,
click No.

Introduction to IBM MQ Explorer 493

Property Meaning Long name Short name
Polling interval This property can be used POLLINGINT PINT
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Type the number of
milliseconds interval that
elapses before each
message listener tries
again to get a message
from its queue when
each message listener
within a session has
no suitable message on
its queue. The default
is 5000. If there is
frequently no suitable
message available for any
of the message listeners
in the session, consider
increasing the value of the
property.

494 IBM MQ Explorer

Property Meaning Long name Short name
Rescan interval This property can be used RESCANINT RINT
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
Type the number of
milliseconds interval
before the IBM MQ JMS
client returns to the
beginning of the queue
when searching for a
suitable message. When
a message consumer
in the point-to-point
domain uses a message
selector to select which
messages it wants to
receive, the IBM MQ
JMS client searches the
IBM MQ queue for
suitable messages in the
sequence determined by
the Message Delivery
Sequence property of
the queue (see Queue
properties). When the
client finds a suitable
message and delivers it to
the consumer, the client
resumes the search for
the next suitable message
from its current position
in the queue. The client
continues to search the
queue in this way until
it reaches the end of the
queue, or until the interval
of time in milliseconds,
as determined by the
value of this property, has
expired. In each case,
the client returns to the
beginning of the queue
to continue its search,
and a new time interval
commences.

Introduction to IBM MQ Explorer 495

Property Meaning Long name Short name
Fail if quiesce To specify that calls to FAILIFQUIESCE FIQ
certain methods fail if
the queue manager is in
a quiescing state, click
Yes. If an application
detects that the queue
manager is quiescing, the
application can complete
its immediate task and
close the connection,
allowing the queue
manager to stop. To
specify that no method
call fails because the
queue manager is in
a quiescing state, click
No. If you click No,
an application cannot
detect that the queue
manager is quiescing so
the application might
continue to perform
operations against the
queue manager and,
therefore, prevent the
queue manager from
stopping.
Syncpoint all gets To specify that all gets SYNCPOINTALLGETS SPAG
should be performed
under syncpoint, click
Yes. To specify that
all gets should not
be performed under
syncpoint, click No.

496 IBM MQ Explorer

Property Meaning Long name Short name
Target client matching Specify whether a reply TARGCLIENTMATCHING TCM
message, sent to the
queue identified by the
JMSReplyTo header field
of an incoming message,
has an MQRFH2 header
only if the incoming
message has an MQRFH2
header. To specify that
if an incoming message
does not have an MQRFH2
header, the Target
Client property on
the destination queue
is set to MQ, click
Yes. If the incoming
message does have an
MQRFH2 header, the
Target Client property
is set to JMS instead.
To specify that the
Target Client property
of the destination queue
is always set to JMS, click
No.
Asynchronous error check Type the number of SENDCHECKCOUNT SCC
interval send calls to allow
between checking for
asynchronous put errors,
within a single non-
transacted JMS session.
The minimum value is
0; the value can be any
positive integer.

Advanced tuning page

The following table lists the properties that you can set on the Advanced tuning page of the Connection
Factory properties dialog. Edit the properties on the Advanced tuning page to configure advanced
settings. For most systems, the default settings are appropriate.

Introduction to IBM MQ Explorer 497

Property Meaning Long name Short name
Process duration This property can be used PROCESSDURATION PROCDUR
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
To specify that a
subscriber can give no
guarantee about how
quickly it can process any
message it receives, click
Unknown (the default
value). To specify that a
subscriber guarantees to
process any message it
receives before returning
control to the IBM MQ
JMS client, click Short.
Optimistic publication This property can be used OPTIMISTICPUBLICATIO OPTPUB
in an IBM MQ JMS client N
but has no effect on an
IBM MQ queue manager.
To specify that when
a publisher publishes a
message, the IBM MQ
JMS client does not return
control to the publisher
until it has completed all
the processing associated
with the call and can
report the outcome
to the publisher, click
No (the default value).
To specify that when
a publisher publishes
a message, the IBM
MQ JMS client returns
control to the publisher
immediately, before it
has completed all the
processing associated
with the call and can
report the outcome to
the publisher, click Yes
(the IBM MQ JMS client
reports the outcome
only when the publisher
commits the message).

498 IBM MQ Explorer

Property Meaning Long name Short name
Outcome notification This property can be used OUTCOMENOTIFICATION NOTIFY
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
To specify that when a
subscriber acknowledges
or commits a message,
the IBM MQ JMS client
does not return control
to the subscriber until
it has completed all
the processing associated
with the call and can
report the outcome to the
subscriber, click Yes (the
default value). To specify
that when a subscriber
acknowledges or commits
a message, the IBM
MQ JMS client returns
control to the subscriber
immediately, before it has
completed the call and
can report the outcome to
the subscriber, click No.
Receive isolation This property can be used RECEIVEISOLATION RCVISOL
in an IBM MQ JMS client
but has no effect on an
IBM MQ queue manager.
To specify that a
subscriber receives only
the messages on the
subscriber queue that
have been committed,
click Committed (the
default value). To specify
that a subscriber can
receive messages that
have not been committed
on the subscriber queue,
click Uncommitted. The
value of Uncommitted
has an effect only if
the Process Duration
property has the value
Short.

Related reference
“Strings in property dialogs” on page 553

Introduction to IBM MQ Explorer 499

 To include certain characters in a string, you must punctuate the string in a particular way.

Destination properties
You can view and set destination properties in the Destination properties dialog. The properties that are
available in the dialog depend on the type of destination.
The following tables list all the properties that you can set for destinations:
• General
• Message handling
• Broker
• Producers
• Consumers
• Extended
For each property, there is a brief description of when you might need to configure the property. The
tables also give the equivalent long and short names to use in the JMS Administration command-line
tool. The properties that are available in the Properties dialog depend on the type of destination;
queue destinations have some different properties from topic destinations. For more information, see
Configuring JMS objects using the administration tool.

General page
The following table lists the properties that you can set on the General page of the Destination properties
dialog.

Table 7. . General page properties

Property Meaning Long name Short name
Name This shows the name of NAME
the object.
Description Type a description of the DESCRIPTION DESC
object.
Class name This shows the class
name that is implemented
by the destination.
Messaging provider This shows the transport
that is supported by the
destination object and can
be either IBM MQ or Real-
time transport. Real-time
transport is not available
in IBM MQ 8.0. If you
are using IBM MQ 8.0
you can define Real-time
transport, but it fails when
an attempt is made to
create a connection.
Queue manager Select or type the name QMANAGER QMGR
of the queue manager
that hosts the destination
queue.

500 IBM MQ Explorer

Table 7. . General page properties (continued)
Property Meaning Long name Short name
Queue Select the name of the QUEUE QU
queue that is represented
by the destination.
Topic Type the name of the TOPIC TOP
topic that this destination
represents.

Message handling page

The following table lists the properties that you can set on the Message handling page of the Destination
properties dialog. Edit the properties on the Message handling page to configure what happens to
messages that are sent to the destination.

Table 8. . Message handling page properties

Property Meaning Long name Short name
Expiry Specify the period after EXPIRY EXP
which messages at the
destination expire. To
specify that expiry can
be defined by the
JMS client application,
click Application. To
specify that no expiry
occurs, click Unlimited.
Otherwise, type the
number of milliseconds
before the messages
expire.

Introduction to IBM MQ Explorer 501

Table 8. . Message handling page properties (continued)
Property Meaning Long name Short name
Persistence Specify the persistence PERSISTENCE PER
of messages that are
sent to the destination.
To specify that the
persistence is defined by
the JMS application, click
Application. To specify
that the persistence takes
the value of the queue's
default value, click Queue
default. To specify that
messages are persistent,
click Persistent. To
specify that messages are
not persistent, click Not
persistent. To specify that
nonpersistent messages
on the queue are
not discarded when
the queue manager
restarts following a
quiesced or immediate
shutdown, click High
(nonpersistent messages
might be discarded,
however, following a
preemptive shutdown or a
failure).
Priority Specify the priority for PRIORITY PRI
messages that are sent
to the destination. To
specify that the priority
is defined by the JMS
client application, click
Application. To specify
that the priority takes
the value of the queue
default, click Queue
default. Otherwise, type
the priority, from 0 to 9.

502 IBM MQ Explorer

Table 8. . Message handling page properties (continued)
Property Meaning Long name Short name
MQMD Message Context Specify the context when MDMSGCTX MDCTX
sending messages to a
destination. There are
three options to choose
from:
Default: The MQOPEN
API call and the MQPMO
structure specifies no
explicit message context
options. This is the default
value.
Set All Context: The
MQOPEN API call
specifies the message
context option
MQOO_SET_ALL_CONTEX
T and the MQPMO
structure specifies
MQPMO_SET_ALL_CONTE
XT.
Set Identity
Context: The MQOPEN
API call specifies the
message context option
MQOO_SET_IDENTITY_CO
NTEXT and the MQPMO
structure specifies
MQPMO_SET_IDENTITY_C
ONTEXT.

MQMD Write Enabled Specify whether a JMS MDWRITE MDW

application can set the
values of MQMD fields.
There are two options to
choose from:
No: All JMS_IBM_MQMD*
properties are ignored
and their values are not
copied into the underlying
MQMD structure. This is
the default value.
Yes: All
JMS_IBM_MQMD*
properties are processed.
Their values are copied
into the underlying MQMD
structure.

Introduction to IBM MQ Explorer 503

Table 8. . Message handling page properties (continued)
Property Meaning Long name Short name
MQMD Read Enabled Specify whether a JMS MDREAD MDR
application can extract
the values of MQMD
fields. There are two
options to choose from:
No: When sending
messages, the
JMS_IBM_MQMD*
properties on a sent
message are not updated
to reflect the updated
field values in the
MQMD. When receiving
messages, none of
the JMS_IBM_MQMD*
properties are available
on a received message,
even if the sender has set
some or all of them. This
is the default value.
Yes: When sending
messages, all of
the JMS_IBM_MQMD*
properties on a sent
message are updated to
reflect the updated field
values in the MQMD,
including those properties
that the sender did
not explicitly set. When
receiving messages, all
of the JMS_IBM_MQMD*
properties are available
on a received message,
including those properties
that the sender did not
explicitly set.

504 IBM MQ Explorer

Table 8. . Message handling page properties (continued)
Property Meaning Long name Short name
Message Body Specify whether a JMS MSGBODY MBODY
application processes the
MQRFH2 of an IBM MQ
message as part of the
JMS message body. There
are three options to
choose from:
Unspecified: When
sending messages; IBM
MQ classes for JMS
does or does not
generate and include
an MQRFH2 header,
depending on the value
of WMQ_TARGET_CLIENT.
When receiving messages,
it acts as if the value is set
to JMS. This is the default
value.
JMS: When sending
messages; IBM MQ
classes for JMS
automatically generates
an MQRFH2 header and
includes it in the IBM
MQ message. When
receiving messages; IBM
MQ classes for JMS
set the JMS message
properties according to
values in the MQRFH2
(if present); it does not
present the MQRFH2 as
part of the JMS message
body.
MQ: When sending
messages; IBM MQ
classes for JMS does
not generate an MQRFH2.
When receiving messages;
IBM MQ classes for JMS
presents the MQRFH2 as
part of the JMS message
body.

Introduction to IBM MQ Explorer 505

Table 8. . Message handling page properties (continued)
Property Meaning Long name Short name
Receive conversion Configures use RECEIVECONVERSION RCNV
of MQGMO_CONVERT
optioN. When requesting
messages, selects if
conversion is to be
carried out in the queue
manager by specifying
MQGMO_CONVERT on the
MQGET, or in the client
application.
Receive CCSID Requested CCSID to RECEIVECCSID RCCS
convert the message to.
Used when the IBM MQ
classes for JMS are
requesting the queue
manager to perform
conversion (for example
by specifying
WMQ_RECEIVE_CONVERS
ION_QMGR as the
argument to
setReceiveConversion).
The value of this property
is the CCSID which the
queue manager is
requested to convert the
message to. The default
value is CCSID 1208.

Broker page
The following table lists the properties that you can set on the Broker page of the Destination properties
dialog. Edit the properties on the Broker page to provide details of the publish/subscribe broker.

506 IBM MQ Explorer

Table 9. . Broker page properties
Property Meaning Long name Short name
Broker durable If the queue manager BROKERDURSUBQ BDSUB
subscription queue that the JMS client is
connecting to is the same
one that is used by the
publish subscribe broker,
you can select a queue
from the broker queue
manager. The selected
queue manager must be
running.
If this is not the case, then
you must type the name
of the queue from which
durable subscription
messages are retrieved
for. The default queue is
SYSTEM.JMS.D.SUBSCRIB
ER.QUEUE.

Broker CC durable If the queue manager BROKERCCDURSUBQ CCDSUB

subscription message that the JMS client is
queue connecting to is the same
one that is used by the
publish subscribe broker,
you can select a queue
from the broker queue
manager. The selected
queue manager must be
running.
If this is not the case, then
you must type the name
of the queue from which
durable subscription
messages are retrieved
for a
ConnectionConsumer. The
default queue is
SYSTEM.JMS.D.CC.SUBSC
RIBER.QUEUE.

Introduction to IBM MQ Explorer 507

Table 9. . Broker page properties (continued)
Property Meaning Long name Short name
Publication stream Select or type the name of BROKERPUBQ BPUB
the queue to which
published messages are
sent (the stream queue).
The default queue is
SYSTEM.BROKER.DEFAUL
T.STREAM. To use Select
to enter the name, you
must have already
selected a value for the
Broker Publication
Queue Manager
property, and the selected
queue manager must be
running.

Broker publication queue Select or type the name BROKERPUBQMGR BPQM

manager of the queue manager that
owns the queue to which
messages published on
the topic are sent.
Broker version Select the version of the BROKERVER BVER
broker being used. Click
V1 to use an IBM MQ
publish/subscribe broker,
or IBM Integration Bus in
compatibility mode; this
is the default value if
the Transport property
is set to Bindings or
Client. Click V2 to use a
broker of IBM Integration
Bus in native mode; this
is the default value if
the Transport property
is set to Direct or
DirectHTTP.

Producers page
The following table lists the properties that you can set on the Producers page of the Destination
properties dialog. Edit the properties on the Producers page to change further properties of the
destination object.

508 IBM MQ Explorer

Table 10. . Producers page properties
Property Meaning Long name Short name
Allow asynchronous puts Specify whether message PUTASYNCALLOWED PAA
producers are allowed
to use asynchronous
puts to send messages
to this destination.
To determine whether
message producers are
allowed by referring to
the queue or topic
definition, click As
destination (default). To
allow asynchronous puts,
click Enabled; to disallow
asynchronous puts, click
Disabled.

Consumers page
The following table lists the properties that you can set on the Consumers page of the Destination
properties dialog. Edit the properties on the Consumers page to change further properties of the
destination object.

Table 11. . Consumers page properties

Property Meaning Long name Short name
Allow read ahead Specify whether message READAHEADALLOWED RAA®
consumers and queue
browsers are allowed to
use read ahead to get
non-persistent messages
from this destination
into a client buffer
before receiving them.
To determine whether
read ahead is allowed by
referring to the queue or
topic definition, click As
destination (default). To
allow read ahead, click
Enabled; to disallow read
ahead, click Disabled.

Introduction to IBM MQ Explorer 509

Table 11. . Consumers page properties (continued)
Property Meaning Long name Short name
Read ahead close policy For messages being READAHEADCLOSEPOLIC RACP
delivered to an Y
asynchronous message
listener, specify what
should happen to
messages on the client
proxy queue when the
message consumer is
closed. To specify that all
messages on the client
proxy queue are delivered
to the application's
MessageListener before
returning, click Deliver
all (default). To
specify that the
current MessageListener
invocation only completes
before returning,
potentially leaving further
messages on the client
proxy queue to be
discarded, click Deliver
current.
Wildcard format Specify which version of WILDCARDFORMAT WCFMT
wildcard syntax is to be
used.
Click Only character
wildcards to use
only character wildcards
(for consistency with
applications that
previously used Broker
Version 1; see the Broker
version property).
Click Only topic
wildcards to use only
topic level wildcards,
which are used in Broker
Version 2.

Extended page
The following table lists the properties that you can set on the Extended page of the Destination
properties dialog. Edit the properties on the Extended page to change further properties of the
destination object.

510 IBM MQ Explorer

Table 12. . Extended page properties
Property Meaning Long name Short name
Coded character set ID Type the coded CCSID CCS
character set ID (CCSID)
to be used for
destinations.
Encoding Select the encoding ENCODING ENC
scheme used for
this destination. For
more information, see
Configuring JMS objects
using the administration
tool.
Fail if quiesce Specify whether calls FAILIFQUIESCE FIQ
to certain methods fail
if the queue manager
is in a quiescing state.
To specify that calls to
certain methods fail if
the queue manager is
in a quiescing state,
click Yes. This means
that if an application
detects that the queue
manager is quiescing,
the application can
complete its immediate
task and close the
connection, allowing
the queue manager
to stop. To specify
that no method calls
fail because the queue
manager is in a
quiescing state, click
No. This means that
an application cannot
detect that the queue
manager is quiescing,
so the application might
continue to perform
operations against the
queue manager and,
therefore, prevent the
queue manager from
stopping.

Introduction to IBM MQ Explorer 511

 Table 12. . Extended page properties (continued)
Property Meaning Long name Short name
Multicast Specify whether MULTICAST MCAST
messages are delivered
to message consumers
that are using
multicast transport.
Multicast transport is
applicable only to topic
destinations and can
be used only when
the connection factory
uses Direct IP transport.
Direct IP transport is not
available in IBM MQ 8.0.
If you are using IBM
MQ 8.0 you can define
Direct IP transport, but
it fails when an attempt
is made to create a
connection.
The default value is
As Connection Factory,
which means that the
value of the connection
factory's Multicast
property is used.
Click Enabled to
deliver messages to
the message consumer
that is using multicast
transport. The topic
must be configured for
reliable multicast in the
broker; a reliable quality
of service is used if the
topic is configured for
reliable multicast.

512 IBM MQ Explorer

Table 12. . Extended page properties (continued)
Property Meaning Long name Short name
Multicast (continued) Click Reliable to MULTICAST MCAST
deliver messages to
the message consumer
that is using multicast
transport with a reliable
quality of service. The
topic must be configured
for reliable multicast,
in the broker; if the
topic is not configured
for reliable multicast,
you cannot create a
message consumer for
the topic.
Click Not reliable to
deliver messages to
the message consumer
that is using multicast
transport but without
using a reliable quality
of service. The topic
must be configured for
multicast in the broker;
a reliable quality of
service is not used, even
if the topic is configured
for reliable multicast.
Target client Click JMS to specify TARGCLIENT TC
that the target of the
message is a JMS
application.
Click MQ to specify
that the target of the
message is a non-JMS
IBM MQ application.

Introduction to IBM MQ Explorer 513

 Table 12. . Extended page properties (continued)
Property Meaning Long name Short name
ReplyTo destination Specify the format of the REPLYTOSTYLE RTOST
style JMSReplyTo field.
Click Default to use
the default value.
The default value
is equivalent to the
information in the RFH2
unless the JVM system
property has been set.
Click MQMD to use
the value supplied in
the MQMD. This will
populate the queue
manager field with the
value from the MQMD.
Click RFH2 to use the
value supplied in the
RFH2 header. If the
sending application set
a JMSReplyTo value then
that value will be used.

Receive conversion Configures use RECEIVECONVERSION RCNV

of MQGMO_CONVERT
option. When requesting
messages, selects if
conversion is to be
carried out in the queue
manager by specifying
MQGMO_CONVERT on
the MQGET, or in the
client application.
Receive CCSID Requested CCSID to RECEIVECCSID RCCS
convert the message to.
Used when the IBM MQ
classes for JMS are
requesting the queue
manager to perform
conversion (for example
by specifying
WMQ_RECEIVE_CONVE
RSION_QMGR as the
argument to
setReceiveConversion).
The value of this
property is the CCSID
which the queue
manager is requested to
convert the message to.
The default value is
CCSID 1208.

514 IBM MQ Explorer

 Related concepts
“JMS destinations (queues and topics)” on page 177
A JMS destination is an object (a JMS queue or a JMS topic) that represents the target of messages that
the client produces and the source of messages that the client consumes. In point-to-point messaging,
destinations represent queues; in publish/subscribe messaging, destinations represent topics.
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related reference
“Strings in property dialogs” on page 553
To include certain characters in a string, you must punctuate the string in a particular way.
“IBM MQ queue properties” on page 358
The properties that you can set for a queue depend on the type of queue. Different types of IBM MQ
queues have different properties. Some of the properties do not apply to all types of queue, some
properties are specific to cluster queues, and some properties are specific to z/OS queues.
“Topic properties” on page 391
An IBM MQ topic is an IBM MQ object that identifies what a publication is about. You can set properties
for topics. Some topic properties are specific to z/OS topics. Also, there are some properties that you can
alter only while you are creating a topic. You cannot modify these properties after the IBM MQ topic has
been created.

Status attributes
In IBM MQ Explorer, you can view the current status of IBM MQ objects. For example, you can find out
whether a channel is running, or you can find out when the last message was put on a certain queue. You
can also view the saved status of a channel.
The following topics list all of the status attributes for IBM MQ objects. For each attribute, there is a
description of what the attribute shows.
• Queue managers
• Queue manager Pub/Sub Engines
• Queues
• Topics
• Subscriptions
• Topic subscribers
• Topic publishers
• Channels
• Listeners
• Custom services

• Coupling facility
• “Display SMDS status attributes” on page 552
Related tasks
“Viewing the status of objects” on page 171

Introduction to IBM MQ Explorer 515

 You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

Queue manager status attributes

The status attributes of multiplatform queue managers, and z/OS queue managers.

Multiplatform queue manager status attributes

The following table lists the status attributes of multiplatform queue managers, and gives the equivalent
MQSC parameter for the DISPLAY QMSTATUS command. For more information about MQSC commands,
see Administering IBM MQ using MQSC commands.

Table 13. Multiplatform queue manager status attributes

Attribute Meaning MQSC
parameter
Queue manager name The name of the queue manager.
Queue manager status The status of the queue manager, which can be: Starting, STATUS
Running, or Quiescing.
Connection count The current number of connections to the queue manager. CONNS
Channel initiator status The status of the channel initiator, which can be: Stopped, CHINIT
Starting, Running, or Stopping.
Command server status The status of the command server, which can be: Stopped, CMDSERV
Starting, Running, or Stopping.
Installation description Description of the installation associated with the queue manager. INSTDESC
Installation name Name of the installation associated with the queue manager. INSTNAME
Installation path Path of the installation associated with the queue manager. INSTPATH
Archive log extent name Name of the oldest log extent for which the queue manager is ARCHLOG
waiting for archive notification.
Archive size The amount of space occupied, in megabytes, by log extents no ARCHSZ
longer required for restart or media recovery, but waiting to be
archived.
Whether the queue manager is a member of an automatic cluster. AUTOCLUS
Automatic
cluster type
Current log extent name The name of the log extent that is being written to at the time that CURRLOG
you open the status dialog.
The size of the dedicated queue manager data file system in MB, DATFSSZ
Data file
rounded up.
system size
The percentage of the dedicated queue manager data file system DATFSUSE
Data file
that is full, rounded up to the nearest percent.
system usage
The path of the queue manager data directory. DATPATH
Queue
manager data path
The name of the host that the queue manager is running on from HOSTNAME
Host name
the perspective of IBM MQ.

516 IBM MQ Explorer

Table 13. Multiplatform queue manager status attributes (continued)
Attribute Meaning MQSC
parameter
The name of the local Native HA instance when the queue INSTANCE
Native HA
manager is part of a Native HA group.
instance name
The size of each log file in KB LOGEXTSZ
Log extent
size
The size of the dedicated recovery log file system in MB, rounded LOGFSSZ
Log file
up.
system size
The percentage of the dedicated recovery log file system that is LOGFSUSE
Log file
full, rounded up to the nearest percent.
system usage
Log in use The percentage of the primary log space in use for restart LOGINUSE
recovery at this point in time.
The number of primary log files. LOGPRIM
Log
primaries
Log path The path of the queue manager event log. The path is of this LOGPATH
format:

installationlocation\WebSphere MQ\log\queuemanager\active\

where installationlocation is the location where IBM MQ is

installed, and queuemanager is the name of the queue manager.
The maximum number of secondary log files. LOGSEC
Log
secondaries
The date for the last log record recovered when the queue LOGSTRDA
Log start
manager was started.
date
The log sequence number (LSN) for the last log record recovered LOGSTRL
Log start
when the queue manager started.
LSN
The time for the last log record recovered when the queue LOGSTRTI
Log start
manager was started.
time
The type of logging: circular, linear, or replicated. LOGTYPE
Log type
Log utilization A percentage estimate of how well the queue manager workload LOGUTIL
is contained within the primary log space.
Restart recovery log The name of the oldest log extent required by the queue manager RECLOG
extent name to perform restart recovery.
Media recovery log extent The name of the oldest log extent required by the queue manager MEDIALOG
name to perform media recovery.
Media size Size of the log data required for media recovery in megabytes. MEDIASZ
Whether the queue manager file system is encrypted or not. QMFSENC
Queue
manager file systems
encrypted

Introduction to IBM MQ Explorer 517

Table 13. Multiplatform queue manager status attributes (continued)
Attribute Meaning MQSC
parameter
The total size of the queue manager data and recovery log file QMFSSZ
Queue
systems in MB, rounded up.
manager file systems size
The percentage of the queue manager data and recovery log file QMFSUSE
Queue
systems that are full, rounded up to the nearest percent.
manager file systems
usage
How many of the configured instances are in-sync with the active QUORUM
Total Native
instance and the total number of configured instances of the
HA instances
queue manager.
Restart recovery size Size of the log data required for restart recovery in megabytes. RECSZ
Reuse size The amount of space occupied, in megabytes, by log extents REUSESZ
available to be reused.
Start date The date on which the queue manager was started. STARTDA
Start time The time at which the queue manager was started. STARTTI
The name of the uniform cluster that the queue manager is a UNICLUS
Uniform
member of, or blank otherwise.
cluster name

z/OS queue manager status attributes

Channel initiator
The following table lists the channel initiator status attributes of z/OS queue managers. The equivalent
MQSC command is DISPLAY CHINIT. For more information about MQSC commands, see Administering
IBM MQ using MQSC commands.

Table 14. Channel initiator status attributes of z/OS queue managers.

Attribute Meaning
TCP name The TCP system name.
Active adapters The number of active adapter subtasks.
Active adapters requested The requested number of adapter subtasks.
Active dispatchers The number of active dispatchers.
Active dispatchers requested The requested number of dispatchers.
Active SSL tasks The number of active TLS server subtasks.
Active SSL tasks requested The requested number of TLS server subtasks.
Current® channel connections The number of current channel connections.
Channel connections requested The requested number of channel connections.
Current TCP/IP channels The number of current TCP/IP channel connections.
Current LU6.2 channels The number of current LU6.2 channel connections.
Active channel connections The number of active channel connections.

518 IBM MQ Explorer

Table 14. Channel initiator status attributes of z/OS queue managers. (continued)
Attribute Meaning
Active channel connections requested The requested number of active channel connections
Active channels paused The number of active channel connections that have
been paused, waiting to become active, because the
limit for active channels has been reached.
Active channels started The number of active channel connections that have
started.
Active channels stopped The number of active channel connections that have
stopped, requiring manual intervention.
Active channels retrying The number of active channel connections that are
attempting to reconnect following a temporary error.
Channel initiator status The status of the channel initiator, which can be:
Stopped, Starting, Running, or Stopping.

Log
The following table lists the log status attributes of z/OS queue managers. The equivalent MQSC
command is DISPLAY LOG. For more information about MQSC commands, see Administering IBM MQ
using MQSC commands.

Table 15. Log status attributes of z/OS queue managers.

Attribute Meaning
Parameter type This attribute shows which type of information is
displayed in the table.
Queue manager start time The time that the queue manager was started.
Queue manager start date The date on which the queue manager was started.
RBA of queue manager start The Relative Byte Address (RBA) from which logging
began when the queue manager was started.
RBA of log The Relative Byte Address (RBA) of the most recently
written log record.
Logging suspended Specifies whether logging is suspended.
Status of the offload task The status of the offload task. Alloc archive
means that the offload task is busy allocating the
archive data set, which could indicate that a tape
mount request is pending; Copying BSDS means that
the offload task is busy copying the BSDS data set;
Busy means that the offload task is busy with other
processing; Available means that the offload task is
waiting for work.
Active logs The number of active log data sets.
Full active logs The total number of full active log data sets that have
not yet been archived.

Usage
The following tables list the Usage status attributes of z/OS queue managers. For each attribute, there is
a brief description of what information the attribute shows. The equivalent MQSC command is DISPLAY

Introduction to IBM MQ Explorer 519

 USAGE, which displays information about the current state of a page set, or displays information about
the log data sets. For more information about MQSC commands, see Administering IBM MQ using MQSC
commands.

Table 16. Dataset records usage for z/OS queue managers.

Attribute Meaning
Usage type This attribute shows which type of information is
displayed in the table.
RBA of log The Relative Byte Address (RBA) of the most recently
written log record.
Data set type The type of data set, and circumstance. Oldest
Active UOW means that the log data set contains
the start RBA of the oldest active unit of work for
the queue manager; Oldest pageset recovery
means that the log data set contains the oldest restart
RBA of any page set for the queue manager; Oldest
CF struc recovery means that the log data set
contains the LRSN which matches the time of the
oldest current backup of any CF structure in the queue
sharing group.
LRSN of log The Log Record Sequence Number (LRSN) of the most
recently written log record.
Data set name The name of the data set.

Table 17. Buffer Pool records usage for z/OS queue managers.
Attribute Meaning
Usage type This attribute shows which type of information is
displayed in the table.
Buffer pool ID The buffer pool identifier, which identifies the buffer
pool being used by the page set.
Buffers defined The number of buffers defined for the buffer pool.
Page class The type of virtual storage pages used for backing the
buffers in the buffer pool. The values for page class
are:
• Pageable 4 KB pages
• Fixed 4 KB pages

Buffer pool location Information about the LOCATION value for individual
buffer pools. The values for LOCATION are:
• Above the bar (64 bit storage)
• Below the bar (31 bit storage)
• Switching to above the bar (64 bit storage)
• Switching to below the bar (31 bit storage)

Free buffers The number of unused buffers in the buffer pool.

Free buffers (%) The percentage of unused buffers in the buffer pool.

520 IBM MQ Explorer

Table 18. Page set records usage for z/OS queue managers.
Attribute Meaning
Usage type This attribute shows which type of information is
displayed in the table.
Expand type How the queue manager expands a page set when it
becomes nearly full, and further pages are required
within it. None means that no further page set
expansion is to take place. User means that the
secondary extent size that was specified when the
page set was defined is used. If no secondary extent
size was specified, or it was specified as zero, then
no dynamic page set expansion can take place.
System means that the secondary extent size that
was specified when the page set was defined is
ignored. Instead, the queue manager sets a value that
is approximately 10 per cent of the current size of the
page set. The new extent size is rounded up to the
nearest cylinder of DASD. If no secondary extend size
was specified, or was specified as zero, dynamic page
set expansion can still take place. The queue manager
sets a value that is approximately 10 per cent of the
current size of the page set. The new extent size
is rounded up depending on the characteristics of
the DASD. If the value is User or System, page set
expansion occurs when the space in the page is 90
per cent used, and is performed asynchronously to any
other page set activity. At restart, if a previously used
page set has been replaced with a data set that is
smaller, it is expanded until it reaches the size of the
previously used data set. Only one extent is required
to reach this size.
Page set ID The page set identifier. This is an optional number
from 00 to 99. An asterisk on its own specifies all page
set identifiers.
Pages The total number of 4 KB pages in the page set.
Unused pages The number of pages that are not use (that is,
available page sets).
Pages holding persistent data The number of pages holding persistent data. These
pages are being used to store object definitions and
persistent message data.
Pages holding nonpersistent data The number of pages holding nonpersistent data.
These pages are being used to store nonpersistent
message data.
Extents used at restart The number of extents used by the page set at restart.
Expand count The number of times the page set has been
dynamically expanded since restart. The maximum
number of times the page set can be expanded is 123,
provided that enough space is available.

Introduction to IBM MQ Explorer 521

Table 18. Page set records usage for z/OS queue managers. (continued)
Attribute Meaning
Page set status The current status of the page set. Available means
that the page set is available; Defined means that
the page set has been defined but has never been
used; Offline means that the page set is currently
not accessible by the queue manager, for example
because the page set has not been defined to the
queue manager; Not defined means that the page
set is not defined to the queue manager.
Buffer pool ID The buffer pool identifier, which identifies the buffer
pool being used by the page set.

Table 19. Shared message data set records usage for z/OS queue managers.
Attribute Meaning
Status The status of the shared message data set records for
the selected queue manager.
Application structure This is the name of the application structure for the
selected queue manager.
Offloaded messages This shows the number of shared messages in the
structure for which the message data has been stored
in the data set owned by this queue manager.
Total blocks This is the current total size of the owned data set
in logical blocks, including blocks used to store the
space map.
Total data blocks This is the total number of blocks in the owned data
set which can be used to store data, excluding those
used to store the space map.
Used data blocks This is the number of blocks in the owned data set
which are currently in use (that is, one or more pages
of those blocks contain active message data).
Used part (%) This is the percentage of used data blocks to the total
data blocks.
Block size (KB) This shows the size of each buffer in KB. This is equal
to the logical block size of the shared message data
set.
Total buffers This is the number of buffers in the pool
In use buffers This is the number of buffers which are currently being
used by requests to transfer data to or from the data
set.
Saved buffers This is the number of buffers which are free but
currently contain saved data for recently accessed
blocks.

522 IBM MQ Explorer

Table 19. Shared message data set records usage for z/OS queue managers. (continued)
Attribute Meaning
Empty buffers This is the number of buffers which are free and
empty. When a new buffer is required, empty buffers
are used first, but if there are no empty buffers, the
least recently used saved buffer is reset to empty and
used instead.
Reads saved (%) This is he percentage of read requests (during the
current statistics interval) where the current block was
found in a saved buffer, avoiding the need to read the
data from the data set.
Lowest free This is the smallest number of free buffers during the
current statistics interval.
Wait rate (%) This is the percentage of requests to acquire a buffer
which had to wait for a free buffer.

Related concepts
“Queue managers” on page 14
A queue manager is a program that provides messaging services to applications. Applications that use the
Message Queue Interface (MQI) can put messages on queues and get messages from queues. The queue
manager ensures that messages are sent to the correct queue or are routed to another queue manager.
Related tasks
“Viewing the status of objects” on page 171
You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.
Related reference
“Queue manager Publish/Subscribe Engine status attributes” on page 524
The status attributes of the queue manager Publish/Subscribe Engine.

Native HA queue manager status attributes

The status attributes of Native HA queue managers.

The following table lists the status attributes of Native HA queue managers, and gives the equivalent
MQSC parameter for the DISPLAY QMSTATUS command. For more information about MQSC commands,
see Administering IBM MQ using MQSC commands. Other status attributes applicable to the queue
manager are described in “Queue manager status attributes” on page 516.

Table 20. Native HA queue manager status attributes

Attribute Meaning MQSC
parameter
Backlog How many KB of recovery log data the active instance in a BACKLOG
Native HA configuration has written that have not yet been
acknowledged by the named instance. This is how ‘out of sync’
the named instance currently is.
Active connections Whether the instance in a Native HA configuration currently has a CONNACTV
pair of active connections to the active instance.
Group initial date The date of the last log record recovered when the Native HA HAINITDA
group initially became active.

Introduction to IBM MQ Explorer 523

Table 20. Native HA queue manager status attributes (continued)
Attribute Meaning MQSC
parameter
Group initial LSN The log sequence number (LSN) of the last log record recovered HAINITL
when the Native HA group initially became active.
Group initial time The time of the last log record recovered when the Native HA HAINITTI
group initially became active.
Native HA instance name The name of the local Native HA instance when the queue INSTANCE
manager is part of a Native HA group.
In-sync Whether this instance is currently considered in-sync with the INSYNC
active instance in a Native HA configuration.
Replication address The network address and port to use when sending data to and REPLADDR
from the specified instance in a Native HA configuration.
Role The current role of the instance in the Native HA group. Can be ROLE
ACTIVE, REPLICA, or UNKNOWN.

Queue manager Publish/Subscribe Engine status attributes

The status attributes of the queue manager Publish/Subscribe Engine.
For each attribute, there is a brief description of what the attribute shows. The table also gives the
equivalent MQSC parameter. For more information about MQSC commands, see Administering IBM MQ
using MQSC commands.

This table lists the status attributes in the Local section:

Attribute Meaning MQSC
parameter
Queue manager name The name of the local queue manager. QMNAME
Status The current status of the Publish/Subscribe Engine on the local STATUS
queue manager. The status value can be:
Active which means the Publish/Subscribe Engine and the
queued Publish/Subscribe interface are running. It is possible to
Publish/Subscribe via the MQI and the queues being monitored
by the queued Publish/Subscribe interface.
Starting which means the Publish/Subscribe Engine is
initializing and is not yet operational.
Stopping which means the Publish/Subscribe Engine is
stopping.
Compatability The Publish/Subscribe Engine is running but the
queued Pub/Sub interface is not active. Any messages put to the
queues monitored by the queued Pub/Sub interface will not be
processed.
Error which means there is an error with the connection from
the Publish/Subscribe Engine to the local queue manager. The
error logs will contain more information about the error.
Inactive which means the Publish/Subscribe Engine is not
active.

524 IBM MQ Explorer

This table lists the status attributes in the Local section: (continued)
Attribute Meaning MQSC
parameter
Sub count Shows the total number of subscriptions against the local topic SUBCOUNT
tree.
Topic count Shows the total number of topic nodes in the local topic tree. TPCOUNT
If the number is growing it might indicate that a shorter tree
life is required, or that a redesign of the topics themselves is
required.

This table lists the status attributes in the Parent section:

Attribute Meaning MQSC
parameter
Queue manager name The name of the parent queue manager. QMNAME
Status The current status of the Publish/Subscribe Engine on the parent STATUS
queue manager. The status value can be:
Active which means the connection with the parent queue
manager is active.
Starting which means the queue manager is attempting to
request that another queue manager become its parent.
Stopping which means the queue manager is disconnecting
from its parent.
Refused which means the connection has been refused by the
parent queue manager. This might be caused my the parent
queue manager already having another child queue manager of
the same name.
Error which means there is an error with the connection from
the Publish/Subscribe Engine to the parent queue manager.
Possible reasons for the error are: The transmit queue is not
defined, or the transmit queue put is disabled.
Sub count Queue manager relations are not inquired for parents, and no SUBCOUNT
value is returned.
Topic count Queue manager relations are not inquired for parents, and no TPCOUNT
value is returned.

This table lists the status attributes in the Children section:

Attribute Meaning MQSC
parameter
Queue manager name The name of the child queue manager. QMNAME

Introduction to IBM MQ Explorer 525

This table lists the status attributes in the Children section: (continued)
Attribute Meaning MQSC
parameter
Status The current status of the Publish/Subscribe Engine on the child STATUS
queue manager. The status value can be:
Active which means the connection with the child queue
manager is active.
Starting which means that another queue manager is
attempting to request that this queue manager become its parent.
Stopping which means the child queue manager is
disconnecting.
Error which means there is an error with the connection
from the Publish/Subscribe Engine to the child queue manager.
Possible reasons for the error are: The transmit queue is not
defined, or the transmit queue put is disabled.
Sub count Queue manager relations are not inquired for children, and no SUBCOUNT
value is returned.
Topic count Queue manager relations are not inquired for children, and no TPCOUNT
value is returned.

Related concepts
“Queue managers” on page 14
A queue manager is a program that provides messaging services to applications. Applications that use the
Message Queue Interface (MQI) can put messages on queues and get messages from queues. The queue
manager ensures that messages are sent to the correct queue or are routed to another queue manager.
Related tasks
“Viewing the status of objects” on page 171
You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.
Related reference
“Queue manager status attributes” on page 516
The status attributes of multiplatform queue managers, and z/OS queue managers.

Queue status attributes

The status attributes of queues and handles that are accessing the queues.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY QSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attribute Meaning MQSC

parameter
Queue name The name of the queue.
Current queue depth The number of messages currently on the queue. CURDEPTH
Open input count This is the number of applications that are currently connected to IPPROCS
the queue to get messages from the queue.
Open output count This is the number of applications that are currently connected to OPPROCS
the queue to put messages on the queue.

526 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Uncommitted messages This indicates whether there are any uncommitted changes (puts UNCOM
and gets) pending for the queue. If there are uncommitted
changes pending, the value is a number corresponding to the
number of uncommitted messages that there are pending (1, 2, 3,
4, 5, etc). If there are no uncommitted changes pending, the value
is No. For z/OS shared queues, the value applies
only to the queue manager that is generating the reply. The value
does not apply to all of the queue managers in the queue sharing
group.
Media recovery log extent The name of the oldest log extent required by the queue to MEDIALOG
name perform media recovery.
Queue monitoring The log extent or journal receiver needed for media recovery of MONQ
the queue. On queue managers on which circular logging is in
place, this attribute has no value. This attribute is valid on AIX,
Linux, and Windows.
Queue time The interval, in microseconds, between messages being put on QTIME
the queue and then being destructively read. The maximum
displayable value is 999 999 999; if the interval exceeds this
value, 999 999 999 is displayed. The interval is measured
from the time that the message is placed on the queue until
it is destructively retrieved by an application and includes the
following times:
• Time when the putting application has put the message, and the
time when the message is available, for example, the message
is committed.
• Time the message is on the queue waiting to be processed.
The cell displays two values: a value based on recent activity
over a short period of time, and a value based on activity
over a longer period of time. These values depend on the
configuration and behavior of your system and the levels of
activity within it, and serve as an indicator that your system
is performing normally. A significant variation in these values
might indicate a problem with your system. For z/OS
queues that have the disposition Shared, the value shown is for
measurements collected on this queue manager only.
Oldest message age The age, in seconds, of the oldest message on the queue. MSGAGE
Last put date The date on which the last message was put to the queue LPUTDATE
since the queue manager started. When no put date is available,
perhaps because no message has been put to the queue since
the queue manager was started, the value is shown as a
blank. For z/OS queues that have the disposition
Shared, the value shown is for measurements collected on this
queue manager only.

Introduction to IBM MQ Explorer 527

Attribute Meaning MQSC
parameter
Last put time The time at which the last message was put to the queue LPUTTIME
since the queue manager started. When no put time is available,
perhaps because no message has been put to the queue since
the queue manager was started, the value is shown as a blank.
For z/OS queues that have the disposition Shared,
the value shown is for measurements collected on this queue
manager only.
Last get date The date on which the last message was retrieved from the queue LGETDATE
since the queue manager started. A message being browsed
does not count as a message being retrieved. When no get date
is available, perhaps because no message has been retrieved
from the queue since the queue manager was started, the value
is shown as a blank. For z/OS queues that have
the disposition Shared, the value shown is for measurements
collected on this queue manager only.
Last get time The time at which the last message was retrieved from the queue LGETTIME
since the queue manager started. A message being browsed
does not count as a message being retrieved. When no get time
is available, perhaps because no message has been retrieved
from the queue since the queue manager was started, the value
is shown as a blank. For z/OS queues that have
the disposition Shared, the value shown is for measurements
collected on this queue manager only.
The current size of the file used by this queue (in megabytes). CURFSIZE
Current file
size
The maximum size that the queue file is currently able to grow to CURMAXFS
Current
(in megabytes). This value can be lower than the configured value
maximum file size
of MAXFSIZE if the queue file has not yet been reconfigured by
the queue manager to support larger files.

Queue handle status objects

The following table lists the queue handle status attributes, which are shown in the second table in the
Queue status dialog.

Attribute Meaning MQSC

parameter
Queue name The name of the queue.

528 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Application name A string containing the tag of the application connected to the APPLTAG
queue manager. It is one of the following:

• a z/OS batch job name

• a TSO USERID, a CICS APPLID

• an IMS region name

• a channel initiator job name

• an IBM i job name

• an AIX, Linux, and Windows process
The application name represents the name of the process or
job that has connected to the queue manager. In the instance
that this process or job is connected through a channel, the
application name represents the remote process or job rather
than the local channel process or job name.
Process ID The identifier of the process that opened the queue. This attribute PID
is not valid on z/OS.
Thread ID The identifier of the thread within the application process that TID
has opened the queue. An asterisk indicates that this queue was
opened with a shared connection. This attribute is not valid on
z/OS.
Application type A string indicating the type of the application that is connected to APPLTYPE
the queue manager. Batch means an application using a batch
connection; RRSBATCH means an RRS-coordinated application
using a batch connection; CICS means a CICS transaction; IMS
means an IMS transaction; CHINIT means a channel initiator;
System means a queue manager; User means a user application.
Application description A string containing a description of the application, where it is APPLDESC
known, connected to the queue manager. If the application is
not recognized by the queue manager the description returned
consists of blanks. The application description is filterable (for
example with a WHERE clause) to allow an administrator to
display only certain connections.
Browse access This indicates whether the handle is providing browse access to BROWSE
the queue. If the handle is providing browse access, the value is
Yes; if the handle is not providing browse access, the value is No.
Inquire access This indicates whether the handle is providing inquire access to INQUIRE
the queue. If the handle is providing inquire access, the value is
Yes; if the handle is not providing inquire access, the value is No.
Input access This indicates whether the handle is providing input access to the INPUT
queue. No means that the queue is not open for input; Shared
means that the queue is open for shared input; Exclusive
means that the queue is open for exclusive input.
Output access This indicates whether the handle is providing output access to OUTPUT
the queue. If the handle is providing output access, the value is
Yes; if the handle is not providing output access, the value is No.

Introduction to IBM MQ Explorer 529

Attribute Meaning MQSC
parameter
Set access This indicates whether the handle is providing set access to the SET
queue. If the handle is providing set access, the value is Yes; if
the handle is not providing set access, the value is No.
User ID The user identifier that is associated with the handle. USERID
Channel name The name of the channel that owns the handle. If there is no CHANNEL
channel associated with the handle, this value is empty. This
value is shown only when the handle belongs to the channel
initiator.
Connection name The connection name that is associated with the channel that CONNAME
owns the handle. If there is no channel associated with the
handle, this value is empty. This value is shown only when the
handle belongs to the channel initiator.
Unit of work type The type of unit of recovery as seen by the queue manager. URTYPE
It is one of the following: CICS (z/OS only);
XA; RRS (z/OS only); IMS (z/OS only);
Queue manager.
Queue manager unit of The unit of recovery assigned by the queue manager. This is QMURID
work ID an 8 byte transaction identifier, displayed as 16 hexadecimal
characters. On z/OS, this is an 8 byte log RBA,
displayed as 16 hexadecimal characters.
Asynchronous state The state of the asynchronous consumer on this object handle. ASTATE
There are five possible values:
Active: An MQCB call has set up a function to call-back to
process messages asynchronously and the connection handle has
been started so that asynchronous message consumption can
proceed.
Inactive: An MQCB call has set up a function to call-back to
process messages asynchronously but the connection handle has
not yet been started, or has been stopped or suspended, so that
asynchronous message consumption cannot currently proceed.
Suspended: The asynchronous consumption call-back has been
suspended so that asynchronous message consumption cannot
currently proceed on this object handle. This can be either
because an MQCB call with Operation MQOP_SUSPEND has been
issued against this object handle by the application, or because
it has been suspended by the system. If it has been suspended
by the system, as part of the process of suspending asynchronous
message consumption the call-back function is called with the
reason code that describes the problem resulting in suspension.
This is reported in the Reason field in the MQCBC structure that
is passed to the call-back function. For asynchronous message
consumption to proceed, the application must issue an MQCB call
with the Operation parameter set to MQOP_RESUME.

530 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Susptemp: The asynchronous consumption call-back has been
temporarily suspended by the system so that asynchronous
message consumption cannot currently proceed on this object
handle. As part of the process of suspending asynchronous
message consumption, the call-back function is called with the
reason code that describes the problem resulting in suspension.
This is reported in the Reason field in the MQCBC structure
passed to the call-back function. The call-back function is called
again when asynchronous message consumption is resumed by
the system, when the temporary condition has been resolved.
None: An MQCB call has not been issued against this handle,
so no asynchronous message consumption is configured on this
handle. This is the default value.

External unit of work ID The external unit of recovery identifier associated with the URID
connection. It is the recovery identifier known in the external sync
point coordinator. Its format is determined by the value of the
Unit Of Work type attribute.
A 4-character address-space identifier of the application that is ASID
identified by the Application name attribute. It distinguishes
Address- duplicate values of Application name. This value is displayed
space ID only when the queue manager that owns the queue is running on
z/OS, and the Application type attribute does not have the
value System.
The 8-character name of the program specification block (PSB) PSBNAME
associated with the running IMS transaction (z/OS only). You
Program can use the Program specification block name and
specification block name Program specification table ID attributes to purge the
transaction using IMS commands. A value is displayed only when
the Application type attribute has the value IMS.
The 4-character IMS program specification table (PST) region PSTID
identifier for the connected IMS region (z/OS only). A value is
Program displayed only when the App type attribute has the value IMS.
specification table ID
A 4-character CICS transaction identifier (z/OS only). A value is TRANSID
displayed only when the App type attribute has the value CICS.
CICS
transaction ID

Related concepts
“IBM MQ queues” on page 15
A queue is a container for messages. Business applications that are connected to the queue manager that
hosts the queue can retrieve messages from the queue or can put messages on the queue.
Related tasks
“Viewing the status of objects” on page 171

Introduction to IBM MQ Explorer 531

 You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

Topic status attributes

The status attributes of topics.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY TPSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attribute Meaning MQSC

parameter
Topic String The Topic String identifies the topic node. It matches TOPICSTR
information from a publisher to a subscriber interested in that
information.
Publish Indicates whether publications are allowed or not. PUB
Subscribe Indicates whether subscriptions are allowed or not. SUB
Durable subscriptions Indicates whether durable subscriptions are allowed or not. DURSUB
Default priority Displays the default priority of messages published to the topic. DEFPRTY
Default persistence Displays the default persistence of messages published to the DEFPSIST
topic.
Model durable queue This is the managed model queue for durable subscriptions. MDURMDL
Model non-durable queue This is the managed model queue for non-durable subscriptions. MNDURMDL
Default put response type The default response type for message puts. The default value is DEFPRESP
As parent. The 2 other options available are:
Sync which means the response is put synchronously.
Async which means the response is put asynchronously.

Admin topic name Administrative topic objects are a required in order to be able to N/A
define attributes for certain portions of the topic tree, and to set
up authority checking on specific topics.
Subscriber count This is the number of subscribers for this topic string, including SUBCOUNT
durable subscribers who are not currently connected.
Publisher count The number of applications currently publishing to the topic. PUBCOUNT
Retained publication Indicates if the publication is retained or not. MQIACF_RETA
INED_PUBLIC
ATION
Non-persistent message The delivery method for non-persistent messages published to NPMSGDLV
delivery this topic.

Persistent message The delivery method for persistent messages published to this PMSGDLV
delivery topic.

532 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Publication scope The scope of publications can be controlled administratively using PUBSCOPE
the PUBSCOPE topic attribute. The attribute can be set to one of
the following 3 values:
• As parent. This is the default value. The publication scope is
set to the same value as the parent queue manager.
• Queue manager. The publication is only delivered to local
subscribers.
• All. The publication is delivered to local subscribers and
remote subscribers by directly connected queue managers.

Subscription scope The scope of subscriptions can be controlled administratively SUBSCOPE

using the SUBSCOPE topic attribute. The attribute can be set to
one of the following 3 values:
• As parent. This is the default value. The subscription scope is
set to the same value as the parent queue manager.
• Queue manager. The subscription receives only local
publications, and proxy subscriptions are not propagated to
remote queue managers.
• All. A proxy subscription is propagated to remote queue
managers, and the subscriber receives local and remote
publications.

Cluster name This is the name of the cluster to which the topic belongs. CLUSTER
Use dead-letter queue Specifies whether the dead-letter queue is used when publication USEDLQ
messages cannot be delivered to their correct subscriber queue.
There are 2 possible values:
• No means that publication messages that cannot be delivered
to their correct subscriber queue are treated as a failure to
put the message, and the application's MQPUT to a topic fails
in accordance with the settings of Non-persistent message
delivery and Persistent message delivery.
• Yes means that if the queue manager Dead-letter queue
attribute provides the name of a Dead Letter Queue, then it is
used. Otherwise the behavior is as for No.

Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Viewing the status of objects” on page 171
You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.
Related reference
“Status attributes” on page 515

Introduction to IBM MQ Explorer 533

 In IBM MQ Explorer, you can view the current status of IBM MQ objects. For example, you can find out
whether a channel is running, or you can find out when the last message was put on a certain queue. You
can also view the saved status of a channel.

Subscription status attributes

The status attributes of subscriptions.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY QSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attribute Meaning MQSC

parameter
Name This is the application's unique subscription identifier. SUB
Identifier Identifier is assigned by the queue manager as a unique SUBID
identifier for this subscription.
User Id The user identifier that is associated with the subscription. SUBUSER
Durable The subscription's Durable parameter can be either Yes or DURABLE
No. When Durable is set to Yes, then the subscriptions are
not deleted when the creating application closes its subscription
handle.
Type The Type of subscription indicates how the subscription was SUBTYPE
created. The subscription types are:
API: Subscription created by using an MQSUB API request.
ADMIN: Subscription created by using a DEF SUB MQSC or PCF
command. ADMIN is also used to indicate that a subscription has
been modified by using an administrative command.
PROXY: Subscription created internally for routing publications
through a queue manager network.

Connection ID The currently active CONNID that has opened this subscription. It ACTCONN
is used to detect local publications.
Resume date The date of the most recent MQSUB which connected to this RESMDATE
subscription.
Resume time The time of the most recent MQSUB which connected to this RESMTIME
subscription.
Date of last publication The date on which a message was last sent to the destination LMSGDATE
specified by the subscription.
Time of last publication The time on which a message was last sent to the destination LMSGTIME
specified by the subscription.
Message count The number of messages put to the destination specified by this NUMMSGS
subscription since it was created, or since the queue manager
was restarted, whichever is more recent. This number might not
reflect the total number of messages that are, or have been,
available to the consuming application. This is because it might
also include publications that were partially processed but then
undone by the queue manager due to a publication failure, or
publications that were made within syncpoint that were rolled-
back by the publishing application.

534 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Multicast reliability Indicator of the reliability of the multicast messages. The values MCASTREL
indicator (%) are expressed as a percentage. A value of 100 indicates that
all messages are being delivered without problems. A value less
than 100 indicates that some of the messages are experiencing
network issues.
To determine the nature of these issues, you can enable
event message generation, using the COMMEV parameter of the
COMMINFO objects, and examine the generated event messages.
Two values are returned:
• The first value is based on recent activity over a short period of
time.
• The second value is based on activity over a longer period of
time. If no measurement is available the values are shown as
blanks.

Related tasks
“Creating a new subscription” on page 107
You can create a new subscription to subscribe to a topic for an IBM WebSphere MQ 7.0, or later, queue
manager.
“Viewing the status of objects” on page 171
You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.
Related reference
“Status attributes” on page 515
In IBM MQ Explorer, you can view the current status of IBM MQ objects. For example, you can find out
whether a channel is running, or you can find out when the last message was put on a certain queue. You
can also view the saved status of a channel.

Topic status attributes for subscribers

For a given topic, the set of attributes that hold subscriber status information.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY TPSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attribute Meaning MQSC

parameter
Topic String The Topic String identifies the topic node. It matches TOPICSTR
information from a publisher to a subscriber interested in that
information.
Subscription ID Identifier is assigned by the queue manager as a unique identifier SUBID
for the subscription.
User The user identifier that is associated with the subscription. SUBUSER
Durable Indicates whether durable subscriptions are allowed or not. DURSUB

Introduction to IBM MQ Explorer 535

Attribute Meaning MQSC
parameter
Type The Type of subscription indicates how the subscription was SUBTYPE
created. The subscription types are:
API: Subscription created via an MQSUB API request.
ADMIN: Subscription created via a DEF SUB MQSC or PCF
command. ADMIN is also used to indicate that a subscription has
been modified via administrative command.
PROXY: Subscription created internally for routing publications
through a queue manager network.

Connection ID The currently active CONNID that has opened this subscription. It ACTCONN
is used to detect local publications.
Resume date The date of the most recent MQSUB which connected to this RESMDATE
subscription.
Resume time The time of the most recent MQSUB which connected to this RESMTIME
subscription.
Message count The number of messages put to the destination specified by this NUMMSGS
subscription since it was created, or since the queue manager
was restarted, whichever is more recent. This number might not
reflect the total number of messages that are, or have been,
available to the consuming application. This is because it might
also include publications that were partially processed but then
undone by the queue manager due to a publication failure, or
publications that were made within syncpoint that were rolled-
back by the publishing application.
Multicast reliability Indicator of the reliability of the multicast messages. The values MCASTREL
indicator (%) are expressed as a percentage. A value of 100 indicates that
all messages are being delivered without problems. A value less
than 100 indicates that some of the messages are experiencing
network issues.
To determine the nature of these issues, you can enable
event message generation, using the COMMEV parameter of the
COMMINFO objects, and examine the generated event messages.
Two values are returned:
• The first value is based on recent activity over a short period of
time.
• The second value is based on activity over a longer period of
time. If no measurement is available the values are shown as
blanks.

Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Viewing the status of objects” on page 171

536 IBM MQ Explorer

 You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.
Related reference
“Status attributes” on page 515
In IBM MQ Explorer, you can view the current status of IBM MQ objects. For example, you can find out
whether a channel is running, or you can find out when the last message was put on a certain queue. You
can also view the saved status of a channel.
“Topic status attributes for publishers” on page 537
For a given topic, the set of attributes that hold publication status information.

Topic status attributes for publishers

For a given topic, the set of attributes that hold publication status information.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY TPSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attribute Meaning MQSC

parameter
Topic String The Topic String identifies the topic node. It matches TOPICSTR
information from a publisher to a subscriber interested in that
information.
Date of last publication The date on which a message was last sent to the destination LSMGDATE
specified by the subscription.
Time of last publication The time on which a message was last sent to the destination LSMGTIME
specified by the subscription.
Publish count The number of applications currently publishing to the topic. PUBCOUNT
Connection ID The currently active CONNID that has opened a subscription. It is ACTCONN
used to detect local publications.
Multicast reliability Indicator of the reliability of the multicast messages. The values MCASTREL
indicator (%) are expressed as a percentage. A value of 100 indicates that
all messages are being delivered without problems. A value less
than 100 indicates that some of the messages are experiencing
network issues.
To determine the nature of these issues, you can enable
event message generation, using the COMMEV parameter of the
COMMINFO objects, and examine the generated event messages.
Two values are returned:
• The first value is based on recent activity over a short period of
time.
• The second value is based on activity over a longer period of
time. If no measurement is available the values are shown as
blanks.

Related concepts
“Topics” on page 16
A topic identifies what a publication is about. A topic is a character string that describes the subject of the
information that is published in a Publish/Subscribe message. As a subscriber, you can specify a topic or
range of topics by using wildcards to receive the information that you require.
Related tasks
“Viewing the status of objects” on page 171

Introduction to IBM MQ Explorer 537

 You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.
Related reference
“Status attributes” on page 515
In IBM MQ Explorer, you can view the current status of IBM MQ objects. For example, you can find out
whether a channel is running, or you can find out when the last message was put on a certain queue. You
can also view the saved status of a channel.
“Topic status attributes for subscribers” on page 535
For a given topic, the set of attributes that hold subscriber status information.

Channel status properties

Displays the properties that show a channel's status. Two views are available: current status and saved
status.
A channel's current status is updated continuously as messages are sent and received. A channel's saved
status is updated only at the following times:
• For all channels:
– When the channel enters or leaves Stopped or Retrying state
• For a sending channel:
– Before requesting confirmation that a batch of messages has been received
– When confirmation is received
• For a receiving channel:
– Just before confirming that a batch of messages has been received
• For a server-connection channel:
– No data is saved
Therefore, a channel that has never been current cannot have any saved status. The properties that are
displayed for a channel's saved status are a subset of the properties that are displayed for a channel's
status. These common properties are marked with an asterisk (*) in the following table.
For each property, there is a brief description of what information the property shows. The table also gives
the equivalent MQSC parameter for the DISPLAY CHSTATUS command. For more information about MQSC
commands, see Administering IBM MQ using MQSC commands.

Property Meaning MQSC

parameter
Batch size The batch size that is being used for this session. BATCHSZ
Batches The number of batches completed since the channel started. BATCHES
Buffers received The number of transmission buffers received. This includes BUFSRCVD
transmissions to receive control information only.
Buffers sent The number of transmission buffers sent. This includes BUFSSENT
transmission to send control information only.
Bytes received The number of bytes received since the channel started. This BYTSRCVD
includes control information received by the Message Channel
Agent.
Bytes sent The number of bytes sent since the channel started. This includes BYTSSENT
control information sent by the Message Channel Agent.
*Channel monitoring The current level of monitoring data collection for the channel. MONCHL
*Channel name The name of the channel definition. CHANNEL

538 IBM MQ Explorer

Property Meaning MQSC
parameter
*Channel status The status of the channel, which can be Starting, Binding, STATUS
Initializing, Running, Stopping, Retrying, Paused,
Stopped, or Requesting.
Channel substate The action that the channel is currently performing. SUBSTATE
*Channel type The type of the channel, which can be Sender, CHLTYPE
Server, Receiver, Requester, Cluster-sender, Cluster-
receiver, Server-connection.
Compression rate The compression rate achieved, displayed to the nearest percent. COMPRATE
This displays a short-term indicator and a long-term indicator.
These values are reset every time the channel is started and are
displayed only when the channel is running.
Compression time The amount of time per message, in microseconds, spent during COMPTIME
compression or decompression. This property displays a short-
term indicator and a long-term indicator. These values are reset
every time the channel is started and are displayed only when the
channel is running.
*Conn name The connection name for which status information is displayed for CONNAME
the channel.
Current conversations The number of conversations that are currently being shared over This is
a particular TCP/IP client channel instance (socket). ephemeral
information,
and has no
associated
MQSC
parameter.
*Current LUWID The logical unit of work identifier that is associated with the CURLUWID
current batch, for a sending or a receiving channel. For a sending
channel, when the channel is in doubt it is the LUWID of the
in-doubt batch. For a saved channel instance, this parameter has
meaningful information only if the channel instance is in doubt.
However, the parameter value is still returned when requested,
even if the channel instance is not in doubt. It is updated with the
LUWID of the next batch when this is known.
*Current messages For a sending channel, this is the number of messages that have CURMSGS
been sent in the current batch. The value is incremented as each
message is sent, and when the channel becomes in doubt it is
the number of messages that are in doubt. For a saved channel
instance, this parameter has meaningful information only if the
channel instance is in doubt. However, the parameter value is still
returned when requested, even if the channel instance is not in
doubt. For a receiving channel, it is the number of messages that
have been received in the current batch. It is incremented as each
message is received. The value is reset to zero, for both sending
and receiving channels, when the batch is committed.

Introduction to IBM MQ Explorer 539

Property Meaning MQSC
parameter
*Current sequence For a sending channel, this is the message sequence number of CURSEQNO
number the last message sent. It is updated as each message is sent, and
when the channel becomes in doubt it is the message sequence
number of the last message in the in-doubt batch. For a saved
channel instance, this parameter has meaningful information only
if the channel instance is in doubt. However, the parameter value
is still returned when requested, even if the channel instance is
not in doubt. For a receiving channel, it is the message sequence
number of the last message that was received. It is updated as
each message is received.
Exit time The amount of time, displayed in microseconds, that each EXITTIME
message spent processing user exits. The cell displays two
values: a value based on recent activity over a short period
of time, and a value based on activity over a longer period of
time. These values depend on the configuration and behavior
of your system, as well as the levels of activity within it, and
serve as an indicator that your system is performing normally. A
significant variation in these values may indicate a problem with
your system. They are reset every time the channel is started and
are displayed only when the channel is running.
Header compression Whether the header data that is sent by the channel is COMPHDR
compressed. Two values are shown: The default header data
compression value negotiated for the channel, and the header
data compression value that was used for the last message that
was sent. If no message has been sent through the channel, the
second value is blank.
Heartbeat interval The heartbeat interval that is being used for this session. HBINT
*Indoubt status Whether the channel is currently in doubt. This is only YES INDOUBT
while the sending Message Channel Agent is waiting for an
acknowledgment that a batch of messages that it has sent has
been successfully received. It is NO at all other times, including
the period during which messages are being sent, but before an
acknowledgment has been requested. For a receiving channel,
the value is always NO.
Keep alive interval The length of the keep alive interval, 0 - 99999. This property is KAINT
ignored if the channel uses a transport type other than TCP or
SPX. The TCP Keep alive property must be set to Yes on the
Channels page of the Queue manager properties.

On z/OS queue managers, the Keep alive

interval property specifies the keep alive interval for the
individual channel.
On queue managers on other platforms, the Keep alive
interval property is used only if the channel connects to a z/OS
queue manager; to use the functionality provided by the Keep
alive interval property, set the Keep alive interval
property to Auto to use a value based on the negotiated
heartbeat interval value.

*Last LUWID The number of the last logical unit of work that was committed by LSTLUWID
the channel.

540 IBM MQ Explorer

Property Meaning MQSC
parameter
Last message date The date when the last message was sent or MQI call was LSTMSGDA
handled.
Last message time The time when the last message was sent or MQI call was LSTMSGTI
handled. For a sender or server, this is the time the last message
(the last part of it if it was split) was sent. For a requester or
receiver, it is the time the last message was put to its target
queue. For a server-connection channel, it is the time when the
last MQI call completed.
*Last sequence number The number of the last message in the last batch that was LSTSEQNO
committed by the channel.
Local address The local communications address for the channel. The value LOCLADDR
depends on the transport type of the channel. Currently, only
TCP/IP is supported.
Long retries left The number of long retry wait start attempts left. This applies LONGRTS
only to sender or server channels.
Max conversations Only available on Server-connection channels and Client- SHARECNV
connection channels. Specifies the maximum number of
(In MQSC this
conversations that can be shared over a particular TCP/IP client
parameter is
channel instance (socket). The possible values are:
known as
0: Specifies no sharing of conversations over a TCP/IP socket. The "Sharing
channel instance runs in a mode before that of IBM WebSphere conversations"
MQ 7.0, with regard to: )
• Administrator stop-quiesce
• Heartbeating
• Read ahead
1: Specifies no sharing of conversations over a TCP/IP socket.
Client heartbeating and read ahead are available, whether in an
MQGET call or not, and channel quiescing is more controllable.
2 - 999999999: The number of shared conversations. The
default value is 10.
If the client-connection Max conversations value does not match
the server-connection Max conversations value, then the lowest
value is used.
MCA job name The name of the job currently serving the channel. On JOBNAME
Multiplatforms, the format is the concatenation of the process
identifier and the thread identifier of the MCA program displayed
in hexadecimal.

This information is not available on z/OS.

MCA status The status of the Message Channel Agent, which is Running or MCASTAT
Not running.
MCA user ID The user ID used by the MCA. This can be the user ID that is set MCAUSER
in the channel definition, the default user ID for MCA channels,
a user ID specified by a security exit, or, if the channel is a server-
connection channel, a user ID transferred from a client.

Introduction to IBM MQ Explorer 541

Property Meaning MQSC
parameter
Message compression The technique used to compress the message data sent by COMPMSG
the channel. Two values are shown: the default message data
compression value negotiated for the channel, and the message
data compression value used for the last message that was sent.
If no message has been sent through the channel, the second
value is blank.
*Messages The number of messages that have been sent or received (or, for MSGS
server-connection channels, the number of MQI calls handled)
since the channel was started.
Messages available The number of messages that are queued on the transmission XQMSGSA
queue and are available to the channel for MQGETs.
Network time The amount of time, displayed in microseconds, to send an end NETTIME
of batch request to the remote end of the channel and receive a
response. This is the time between sending the last message in a
batch and receiving the end of batch acknowledgment, minus the
processing time of the end of batch request at the remote end.
There are two elements that make up the network time:
• The time that the data flowed on the network.
• Delays at the remote end until the end of batch request is
processed. If the channel processing at the remote end is
delayed, for example, processing is retrying a put, then the
processing of the end of batch request will be delayed and
leads to an increase in NETTIME.
The cell displays two values: a value based on recent activity over
a short period of time, and a value based on activity over a longer
period of time. These values depend on the configuration and
behavior of your system, as well as the levels of activity within it,
and serve as an indicator that your system is performing normally.
A significant variation in these values may indicate a problem with
your system. They are reset every time the channel is started and
are displayed only when the channel is running. This parameter
applies only to sender, server, and cluster-sender channels.
NPM speed The nonpersistent message handling technique that is being used NPMSPEED
for this session.
Queue manager name The name of the queue manager on which the channel is defined. QMNAME
For client-connection channels, this is the name of the queue
manager to which an application that is running in the MQI client
environment can request connection.
Remote product The remote partner product identifier. This is the product RPRODUCT
identifier of the IBM MQ code running at the remote end of the
channel. This field is available in IBM MQ 9.0 and later.
Remote queue manager The queue manager name, or queue sharing group name, of the RQMNAME
remote system.
Remote version The version of the IBM MQ code running at the remote end of the RVERSION
channel. If the remote version is blank, the remote partner is at
version 6 or earlier.

542 IBM MQ Explorer

Property Meaning MQSC
parameter
Security protocol Security protocol currently in use on the channel. Set SECPROT
automatically, based on the value you set for the SSL CipherSpec
property. The value can be NONE, TLSV1, TLSV12, TLSV13.
*Short peer name The Distinguished Name of the peer queue manager or client SSLPEER
at the other end of the channel. The maximum length is 256
characters, so longer Distinguished Names are truncated.
Short retries left The number of short retry wait start attempts left. This applies SHORTRTS
only to sender or server channels.
SSL cert issuer name The full Distinguished Name of the issuer of the remote SSLCERTI
certificate. The issuer is the Certificate Authority that issued the
certificate. The maximum length is 256 characters, so longer
Distinguished Names are truncated.
SSL cert user ID The local user ID associated with the remote certificate. SSLCERTU
SSL Cipher Spec The name of the Cipher Spec for a TLS connection. Both ends of SSLCIPH
the IBM MQ SSL channel definition must have the same value in
the Cipher Spec property. For more information, see the SSLCIPH
property in DEFINE CHANNEL.
The value for this parameter is also used to set the value of the
Security Protocol property.

SSL key reset date The date on which the previous successful TLS secret key was SSLKEYDA
reset. The count of TLS secret key resets is reset when the
channel instance ends.
Note: TLS 1.3 key resets are integral to TLS 1.3, and not
communicated to applications. As a result, on z/OS queue
managers, for receiver channels, this value will not be set when
the channel is communicating using a TLS 1.3 CipherSpec. On
distributed queue managers this value will not be accurate, and
might even be set to zero at either end of a channel, when the
channel is communicating using a TLS 1.3 CipherSpec.
For more information, see Resetting SSL and TLS secret keys.
SSL key reset time The time at which the previous successful TLS secret key was SSLKEYTI
reset. The count of TLS secret key resets is reset when the
channel instance ends.
Note: TLS 1.3 key resets are integral to TLS 1.3, and not
communicated to applications. As a result, on z/OS queue
managers, for receiver channels, this value will not be set when
the channel is communicating using a TLS 1.3 CipherSpec. On
distributed queue managers this value will not be accurate, and
might even be set to zero at either end of a channel, when the
channel is communicating using a TLS 1.3 CipherSpec.
For more information, see Resetting SSL and TLS secret keys.

Introduction to IBM MQ Explorer 543

Property Meaning MQSC
parameter
SSL key resets The number of successful TLS key resets. The count of TLS secret SSLRKEYS
key resets is reset when the channel instance ends.
Note: TLS 1.3 key resets are integral to TLS 1.3, and not
communicated to applications. As a result, on z/OS queue
managers, for receiver channels, this value will not be set when
the channel is communicating using a TLS 1.3 CipherSpec. On
distributed queue managers this value will not be accurate, and
might even be set to zero at either end of a channel, when the
channel is communicating using a TLS 1.3 CipherSpec.
For more information, see Resetting SSL and TLS secret keys.
Start date The date when this channel started (in the form yyyy-mm-dd). CHSTADA
Start time The time when this channel started (in the form hh.mm.ss). CHSTATI
Stop requested Whether a user stop request is outstanding. The value is Yes or STOPREQ
No.
*Transmission queue The name of the transmission queue for which status information XMITQ
is displayed for the specified channel.
Xmit batch size The size of the batches transmitted over the channel. Two values XBATCHSZ
are displayed: a value based on recent activity over a short period
of time, and a value based on activity over a longer period of
time. These values depend on the configuration and behavior
of your system, as well as the levels of activity within it, and
serve as an indicator that your system is performing normally.
A significant variation in these values might indicate a problem
with your system. The values are reset every time the channel is
restarted and are displayed only when the channel is running.
Xmit queue time The time, in microseconds, that messages remained on the XQTIME
transmission queue before being retrieved. The time is measured
from when the message is put on the transmission queue until
it is retrieved to be sent on the channel and, therefore, includes
any interval caused by a delay in the putting application. The cell
displays two values: a value based on recent activity over a short
period of time, and a value based on activity over a longer period
of time. These values depend on the configuration and behavior
of your system, as well as the levels of activity within it, and
serve as an indicator that your system is performing normally.
A significant variation in these values might indicate a problem
with your system. The values are reset every time the channel is
started and are displayed only when the channel is running.

Related concepts
“Channels” on page 20
IBM MQ can use three different types of channels: a message channel, an MQI channel, and an AMQP
channel.
Related tasks
“Viewing the status of objects” on page 171

544 IBM MQ Explorer

 You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

Listener status attributes

The status attributes of listeners.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY LSSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attributes Meaning MQSC

parameter
Listener name The name of the listener.
Description A descriptive comment of the listener. DESCR
Listener status The current status of the listener, which can be Running, STATUS
Starting, or Stopping.
PID The operating system process identifier associated with the PID
listener.
Channel count The current number of connections to the listener. CURCONNS
Start date The date on which the listener was started. STARTDA
Start time The time at which the listener was started. STARTTI

Related concepts
“Listeners” on page 24
A listener is an IBM MQ process that listens for connections to the queue manager.
Related tasks
“Viewing the status of objects” on page 171
You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

Service status attributes

The status attributes of custom services.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY SVSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Attributes Meaning MQSC

parameter
Service name The name of the service.
Description A descriptive comment of the service. DESCR
Service status The current status of the service, which can be Running, STATUS
Starting, or Stopping.
PID The operating system process identifier associated with the PID
service.
Start date The date on which the service was started. STARTDA
Start time The time at which the service was started. STARTTI

Introduction to IBM MQ Explorer 545

 Related concepts
“Custom services” on page 31
Custom services are services that you create to run commands automatically.
Related tasks
“Viewing the status of objects” on page 171
You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

Coupling facility structure status attributes

The status attributes of coupling facility (CF) structures.
For each attribute, there is a brief description of what information the attribute shows. The table also
gives the equivalent MQSC parameter for the DISPLAY CFSTATUS command. For more information about
MQSC commands, see Administering IBM MQ using MQSC commands.

Summary
This table lists the attributes in the Summary Status dialog, which displays the summary status
information for the CF application structure.

Attribute Meaning MQSC

parameter
Coupling facility name The name of the CF structure.
Type The type of status information that is being displayed. Summary TYPE
means that it is summary status information for the CF
application structure; Connect means that it is connection
status information for each CF application structure for each
active queue manager; Backup means that it is backup status
information for each CF application structure.

546 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Status The status of the CF application structure. If the value of Status STATUS
type is Summary:
• Active means that the structure is active.
• Failed means that the structure has failed.
• Not Found means that the structure is not allocated in the
coupling facility but has been defined to Db2.
• Backup means that the structure is in the process of being
backed up.
• Recover means that the structure is in the process of being
recovered.
If the value of Status type is Connect:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been connected to
this queue manager.
If the value of Status type is Backup:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been backed up.
• Backup means that the structure is in the process of being
backed up.
• In recover means that the structure is in the process of being
recovered.

Max size The size, in kilobytes, of the CF application structure. SIZEMAX

Size used The percentage of the CF application structure that is in use. SIZEUSED
Max entries The number of CF list entries defined for this CF application ENTSMAX
structure.
Entries used The number of CF list entries defined for this CF application ENTSUSED
structure that are in use.
Fail date The date on which this CF application structure failed. If Status FAILDATE
type is Connect, this is the date on which the queue manager
lost connectivity to this application structure. For the other values
of Status type, this is the date on which this CF application
structure failed. This value is shown only when the value of
Status is Failed or In recover.
Fail time The time that this CF structure failed. If Status type FAILTIME
is Connect, this is the time that the queue manager lost
connectivity to this application structure. For the other values of
Status type, this is the time that this CF application structure
failed. This value is shown only when the value of Status is
Failed or In recover.

Introduction to IBM MQ Explorer 547

Attribute Meaning MQSC
parameter
Offload use This indicates whether offloaded large message data potentially
exists in shared message data sets, Db2 or both. If Offload
use is None, no offloaded large messages are present. In the
case thatOffload use is SMDS, offloaded large messages can
exist in shared message data sets. Where Offload use is DB2,
offloaded can exist in Db2. Finally if Offload use is Both,
offloaded large messages can exist both in shared message data
sets and in Db2.

Connect
This table lists the attributes in the Connect Status dialog, which displays the connection status
information for each CF application structure for each active queue manager.

Attribute Meaning MQSC

parameter
Coupling facility name The name of the CF structure.
Queue manager name The queue manager name. QMNAME
System name The name of the z/OS image of the queue manager that last SYSNAME
connected to the CF application structure. These can be different
across queue managers depending on your configuration setup.
Status The status of the CF application structure. If the value of Status STATUS
type is Summary:
• Active means that the structure is active.
• Failed means that the structure has failed.
• Not Found means that the structure is not allocated in the
coupling facility but has been defined to Db2.
• Backup means that the structure is in the process of being
backed up.
• Recover means that the structure is in the process of being
recovered.
If the value of Status type is Connect:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been connected to
this queue manager.
If the value of Status type is Backup:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been backed up.
• Backup means that the structure is in the process of being
backed up.
• In recover means that the structure is in the process of being
recovered.

548 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Fail date The date on which this CF application structure failed. If Status FAILDATE
type is Connect, this is the date on which the queue manager
lost connectivity to this application structure. For the other values
of Status type, this is the date on which this CF application
structure failed. This value is shown only when the value of
Status is Failed or In recover.
Fail time The time that this CF structure failed. If Status type FAILTIME
is Connect, this is the time that the queue manager lost
connectivity to this application structure. For the other values of
Status type, this is the time that this CF application structure
failed. This value is shown only when the value of Status is
Failed or In recover.

Backup
This table lists the attributes in the Backup Status dialog, which displays the backup status information
for each CF application structure.

Attribute Meaning MQSC

parameter
Coupling facility name The name of the CF structure.
Queue manager name The queue manager name. QMNAME
Status The status of the CF application structure. If the value of Status STATUS
type is Summary:
• Active means that the structure is active.
• Failed means that the structure has failed.
• Not Found means that the structure is not allocated in the
coupling facility but has been defined to Db2.
• Backup means that the structure is in the process of being
backed up.
• Recover means that the structure is in the process of being
recovered.
If the value of Status type is Connect:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been connected to
this queue manager.
If the value of Status type is Backup:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been backed up.
• Backup means that the structure is in the process of being
backed up.
• In recover means that the structure is in the process of being
recovered.

Introduction to IBM MQ Explorer 549

Attribute Meaning MQSC
parameter
Backup date The date on which the last successful backup was taken for this BKUPDATE
CF application structure.
Backup time The end time of the last successful backup taken for this CF BKUPTIME
application structure.
Backup size The size, in megabytes, of the last successful backup taken for BKSIZE
this CF application structure.
Start RBA The backup data set start RBA for the start of the last successful BKUPSRBA
backup taken for this CF application structure.
End RBA The backup data set end RBA for the end of the last successful BKUPERBA
backup taken for this CF structure.
Log queue manager name A list of queue managers, the logs of which are required to LOGS
perform a recover.
Fail date The date on which this CF application structure failed. If Status FAILDATE
type is Connect, this is the date on which the queue manager
lost connectivity to this application structure. For the other values
of Status type, this is the date on which this CF application
structure failed. This value is shown only when the value of
Status is Failed or In recover.
Fail time The time that this CF structure failed. If Status type FAILTIME
is Connect, this is the time that the queue manager lost
connectivity to this application structure. For the other values of
Status type, this is the time that this CF application structure
failed. This value is shown only when the value of Status is
Failed or In recover.

SMDS
This table lists the attributes in the Backup Status dialog, which displays the backup status information
for each CF application structure.

Attribute Meaning MQSC

parameter
Coupling facility name The name of the CF structure.
Queue manager name The queue manager name. QMNAME
Access The current availability state of the shared message data set. ACCESS
Valid availability states are Enabled, Suspended or Disabled
Fail date The date on which this CF application structure failed. If Status FAILDATE
type is Connect, this is the date on which the queue manager
lost connectivity to this application structure. For the other values
of Status type, this is the date on which this CF application
structure failed. This value is shown only when the value of
Status is Failed or In recover.

550 IBM MQ Explorer

Attribute Meaning MQSC
parameter
Fail time The time that this CF structure failed. If Status type FAILTIME
is Connect, this is the time that the queue manager lost
connectivity to this application structure. For the other values of
Status type, this is the time that this CF application structure
failed. This value is shown only when the value of Status is
Failed or In recover.
Recovery date The recovery start date. If recovery is currently enabled for the RCVDATE
data set, this indicates the date when it was activated, in the form
yyy-mm-dd.
Recovery time The recovery start time. If recovery is currently enabled for the RCVTIME
data set, this indicated the time when it was activated, in the form
hh.mm.ss,
Status The status of the CF application structure. If the value of Status STATUS
type is Summary:
• Active means that the structure is active.
• Failed means that the structure has failed.
• Not Found means that the structure is not allocated in the
coupling facility but has been defined to Db2.
• Backup means that the structure is in the process of being
backed up.
• Recover means that the structure is in the process of being
recovered.
If the value of Status type is Connect:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been connected to
this queue manager.
If the value of Status type is Backup:
• Active means that the structure is active.
• Failed means that the structure has failed.
• None means that the structure has never been backed up.
• Backup means that the structure is in the process of being
backed up.
• In recover means that the structure is in the process of being
recovered.

Related concepts
“Coupling facility structures” on page 33
The coupling facility objects in IBM MQ Explorer represent coupling facility structures on a physical
coupling facility. Coupling facility structures store the messages that are on shared queues. Each coupling
facility structure used by IBM MQ is dedicated to a specific queue sharing group, but a coupling facility
can hold structures for more than one queue sharing group.
Related tasks
“Viewing the status of objects” on page 171

Introduction to IBM MQ Explorer 551

 You can display the current status of any object that can be in different states, in IBM MQ Explorer. For
IBM MQ channels, you can also view the saved status.

Display SMDS status attributes

Information about the interaction between the shared message data sets (SMDS) for the named structure
and the queue manager. The displayed properties are read only properties.

Display SMDS
This table lists the read only properties that are shown on the Display SMDS page of the coupling facility
structures dialog.

Property Meaning MQSC

parameter
Queue manager name Read only: Name of the queue manager associated with the SMDS
shared message data set.
Coupling facility name Read only: Name of coupling facility associated with the shared CFSTRUCT
message data set.
Number of buffers Read only: This value displays the current setting on buffers DSBUFS
allocated for accessing shared message data sets.
Expand data set Read only: This value provides information on the current setting DSEXPAND
for the expansion of the data set.

Display SMDS connections

This table lists the read only properties that are shown on the Display SMDS connections page of the
coupling facility structures dialog.

Property Meaning MQSC

Parameter
Queue manager name Read only: Name of queue manager associated with the shared SMDSCONN
message data set.
Coupling facility name Read only: Name of coupling facility associated with the shared CFSTRUCT
message data set.
Availability Read only: This value displays the availability of the data set AVAIL
connection as seen by the queue manager.
Expansion status Read only: This value displays the data sets automatic expansion EXPANDST
status.
Open mode Read only: This value displays the mode in which the data set is OPENMODE
currently open by the queue manager.
Status Read only: This value displays the connection status as seen by STATUS
the queue manager.

Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“Strings in property dialogs” on page 553

552 IBM MQ Explorer

 To include certain characters in a string, you must punctuate the string in a particular way.

Byte array dialog

The Byte array dialog is used to define or edit a byte array property of an IBM MQ object.
The Byte array dialog is launched from several sources, for example: from the Subscription properties
dialog. The length of the byte array varies depending on which property you are defining, for example:
A subscription's Correl ID is a maximum of 24 bytes long, but a subscription's Accounting token is a
maximum of 32 bytes long.
When using the Byte array dialog, you have the choice of defining the array by entering text or bytes.

Attribu
te Meaning
Text The byte array appears as text in this field. If you want to edit or define the text, then edit this field.
Bytes The byte array appears as bytes in this field. If you want to edit or define the bytes, then edit this
field.

Related concepts
“Objects in IBM MQ Explorer” on page 13
In IBM MQ Explorer, all of the queue managers and their IBM MQ objects are organized in folders in the
Navigator view.
Related tasks
“Configuring queue managers and objects” on page 37
You can configure many of the properties of queue managers and their objects from IBM MQ Explorer
using the properties dialogs.
Related reference
“IBM MQ subscription properties” on page 413
You can set properties for all types of subscriptions. Some of the properties do not apply to all types of
subscriptions, some properties are specific to z/OS subscriptions.

Strings in property dialogs

To include certain characters in a string, you must punctuate the string in a particular way.
Some of the properties you can set in the property pages are strings, in particular, the Description,
Cluster name, and Cluster namelist properties.
To include certain characters (space, comma (,), single quotation marks (' '), and double quotation marks
(" ")), you must punctuate the string in special ways.
Punctuate Description strings as follows:
• To enter a description without any commas or quotation marks, just type the string. For example, My
queue
• To include a comma in a description, enclose the whole string in either single or double quotation
marks. For example, "Beware, this is John's queue"
• To include quotation marks, either enclose the string in the other type of quotation marks, or repeat the
quotation marks twice. For example, "Beware, this is John's ""special"" queue"
Punctuate Cluster name and Namelist properties as follows:
• Do not use a space or a comma in a cluster name. Use an underscore (_) instead. For example,
cluster_1
• Type lists of cluster names separated by either spaces or commas. For example, cluster_1
cluster_2 cluster_3,cluster_4 When the namelist is viewed, the delimiters are all commas
and no spaces. So the example looks like this: cluster_1,cluster_2,cluster_3,cluster_4

Introduction to IBM MQ Explorer 553

Identifying durable subscriptions to the SYSTEM.FTE topic
If your enterprise is using the Managed File Transfer plugin, supplied with IBM MQ Explorer, you can use
the plugin to monitor various features on your managed file transfer network.
If the plugin has been configured to use a durable subscription to the SYSTEM.FTE topic on the
coordination queue manager, then that subscription will have a unique name that allows you to identify
the IBM MQ Explorer instance and user that has created it.
The subscription name used by the Managed File Transfer plugin always has the following format:
MQExplorer_MFT_Plugin_hostname_UUID
Where hostname is the name of the system where the IBM MQ Explorer that created the subscription
is running, and UUID is an identifier which is unique to that user and IBM MQ Explorer instance.
The Managed File Transfer plugin persists the name of the durable subscription it is using in a file called
dialog_settings.xml, which can be found in the following directory:

• User_home\IBM\WebSphereMQ\workspace-
installation_name\.metadata\.plugins\com.ibm.wmqfte.explorer\

• $HOME/IBM/WebSphereMQ/workspace-
installation_name/.metadata/.plugins/com.ibm.wmqfte.explorer
Inside this file, look for the UI_SETTINGS_SUBSCRIPTIONS section, and you should see the subscription
name displayed after the value attribute. The following code is an example of what you see:

<xml version="1.0" encoding="UTF-8"?>

<section name = "Workbench">
<section name = "UI_SETTINGS_TRANSFER_LOG">
<item key = "LOCALE" value="en">
<list key ="COLUMNS">
<item value =""/>
<item value ="Source"/>
<item value ="Destination"/>
<item value ="Completion State"/>
<item value ="Owner"/>
</list>
</section>
<section name = "UI_SETTINGS_SUBSCRIPTIONS"
<item key = "LOG_SUBNAME" value= "MQExplorer_MFT_Plugin_host1_a14d17fe-58ff-430b-
bae5-5a944917f537"/>
</section>
<section name = "TRANSFER_PROGRESS_VIEW_SETTINGS">
<item key = "LOCALE" value="en">
<list key ="COLUMNS">
<item value =""/>
<item value ="Source"/>
<item value ="Destination"/>
<item value ="Current File"/>
<item value ="File Number"/>
<item value ="Progress"/>
<item value ="Rate"/>
<item value ="Started"/>
</list>
</section>
</section>

Note: If you use IBM MQ Explorer to monitor multiple managed file transfer networks, the same durable
subscription name is used for each of the durable subscriptions that are created.
For example, if you manage two Managed File Transfer networks, with the name of the coordination queue
managers for the networks being your_IDFTEQM and your_IDMFTQM respectively, using the Managed File
Transfer plugin, you can view the subscriptions for each coordination queue manager.
In the IBM MQ Explorer Navigator pane, expand the Queue Managers drop down and you see the two
coordination queue managers your_IDFTEQM and your_IDMFTQM.
Expand the drop down for each of these queue managers, and you see a list of objects for each queue
manager, including Subscriptions. If you click on Subscriptions for each of these queue managers

554 IBM MQ Explorer

 in turn, and view the Content pane, you see that each queue manager contains durable subscriptions
to the SYSTEM.FTE topic that have the name: MQExplorer_MFT_Plugin_host1_a14d17fe-58ff-430b-
bae5-5a944917f537
This indicates that both durable subscriptions are being used by the same user, who is using the Managed
File Transfer plugin on a system with the hostname host1.

Extending IBM MQ Explorer

You can extend the IBM MQ Explorer by writing one, or more, Eclipse plug-ins.
The IBM MQ Explorer is Eclipse based, and as such acquires all its functionality, and perspective
information, through various plug-ins supplied with IBM MQ. To extend the IBM MQ Explorer you must to
write one, or more, Eclipse plug-ins. Through writing a plug-in you can extend the function of the IBM MQ
Explorer in the following ways:
• Add further menu options to existing pop-up menus and associate actions with them.
• Add tree nodes to the navigation view, and associated content pages.
When writing a plugin, you need to supply the following resources:
A plugin.xml file
Specify extension points in a plugin.xml file. Use the extension points to extend the functionality of
the IBM MQ Explorer. There are many types of extension point available within the IBM MQ Explorer
and Eclipse. Each type of extension point is used to extend the IBM MQ Explorer in a different way.
Most extension points are associated with a Java archive (JAR) file. For more information on the
extension points available, see “Utilizing extension points” on page 556.
A set of Java archive (JAR) files
Write classes that implement the functionality specified by the extension points that you declared in
the plugin.xml file. Package the classes in JAR files, so that every JAR file is associated with at least
one extension point.
IBM MQ supplies sample Eclipse plug-ins called simple, and menu. The simple plug-in uses all the
extension points provided in the IBM MQ Explorer to extend the Explorer in a number of basic ways. The
simple plug-in can be used as a basis for writing your own Eclipse plug-ins. For instructions of how to
import the simple plugin, see “Writing an Eclipse plug-in for IBM MQ Explorer” on page 556.
Information on how to write Eclipse plug-ins is available in the Platform Plug-in Developers Guide, found in
the online Eclipse help. See https://help.eclipse.org/latest/index.jsp?nav=%2F2 for more information.
Related concepts
“Writing an Eclipse plug-in for IBM MQ Explorer” on page 556
How to write an Eclipse plug-in for IBM MQ Explorer by using the extension points that are available to
extend the IBM MQ Explorer functionality.
“Applying plug-ins to IBM MQ Explorer” on page 560
You can either run a plug-in with IBM MQ Explorer from the Eclipse workbench, or apply updates from a
plug-in to IBM MQ Explorer permanently.

Importing the sample Eclipse plug-ins

Instructions for importing the sample Eclipse plug-ins.
To import the sample Eclipse plug-ins, complete the following steps:
1. Install the IBM MQ Explorer into an Eclipse environment, as described in “Installing IBM MQ Explorer
into Eclipse environments” on page 10
2. Open the Plug-in Development perspective.
3. Click File > Import to open the Import wizard.
In the Import wizard, complete the following steps:
a. Click Plug-in Development > Plug-ins and Fragments.

Introduction to IBM MQ Explorer 555

 b. Select the Projects with source folders check box and click Next.
c. Select one or more from:
com.ibm.mq.explorer.sample.simple
com.ibm.mq.explorer.sample.menus
com.ibm.mq.explorer.jmsadmin.sample.menus
com.ibm.mq.explorer.tests.sample
d. Click the Add button, then click Finish.
4. If you selected com.ibm.mq.explorer.tests.sample in the previous step you need to returned to the
Import wizard and complete the following steps:
a. Click Plug-in Development > Plug-ins and Fragments.
b. Select the Binary projects check box and click Next.
c. Select the com.ibm.mq.runtime plugin.
d. Click the Add button, then click Finish.
You have now imported the sample Eclipse plug-ins.

Writing an Eclipse plug-in for IBM MQ Explorer

How to write an Eclipse plug-in for IBM MQ Explorer by using the extension points that are available to
extend the IBM MQ Explorer functionality.
Note: It is assumed that you have the prerequisite knowledge detailed in “Extending IBM MQ Explorer”
on page 555.
To write an Eclipse plug-in for the IBM MQ Explorer, you must use the extension points available to
extend the functionality of the IBM MQ Explorer. The most common extension points are described, and
accompanied by a number of code extracts from the simple plug-in to provide basic implementation
examples. You must import the simple plug-in if you want access to the code that it contains. For
instructions on how to import the simple plugin, see “Importing the sample Eclipse plug-ins” on page
555.
The environment in which the IBM MQ Explorer is extended is an event driven interface. For example,
when a Register extension point is extended with an instance of a user-written class that extends the
IExplorerNotify interface, the user-written class will be called back when an event occurs. For example,
when a queue manager is created. Many of these notifications include a MQExtObject as one of their
arguments. An MQExtObject relates to the IBM MQ object that caused the event. A user-written class can
call any of the MQExtObject public methods to find out about the object.
The IExplorerNotify interface, the associated MQExtObject, and other external definitions are
documented in IBM MQ Explorer Javadoc documentation. For information on how to access the IBM
MQ Explorer Javadoc documentation, see “API Reference” on page 561.
Related concepts
“Utilizing extension points” on page 556
Instructions on how to use the extension points available in Eclipse plug-ins for the IBM MQ Explorer.

Utilizing extension points

Instructions on how to use the extension points available in Eclipse plug-ins for the IBM MQ Explorer.
For further information on using extension points see https://help.eclipse.org/latest/index.jsp?nav=%2F2
then select Programmer's Guide.
For information on how to include an extension point, see Plugging into the workbench->Basic
workbench extension points using actions in the Programmers Guide.
Through utilizing the available extension points, you can extend the function of the IBM MQ Explorer in
the following ways:

556 IBM MQ Explorer

• Register extension points.
• Add further menu options to existing menus and associate actions with them.
• Add tree nodes to the navigation view and associate content pages with them.
• Add property tabs to property dialogs and associate property pages with them.
Multiple extension points of the same type can be included in a single plugin. The extension points that
you use will be dependent on the way in which you intend to extend the functionality of the IBM MQ
Explorer. However, every plug-in for the IBM MQ Explorer must use the register extension point.
Related concepts
“Register a plugin-in with IBM MQ Explorer” on page 557
How to use the register extension point to register a plugin-in with IBM MQ Explorer and enable notify
events.
“Add tree node” on page 558
A tree node extension point is used to add a tree node to the navigation view and associate it with a
content page.
“Add content page” on page 559
A content page extension point is used to add a content page to the content view. A content page can be
associated with a tree node.
“Add a pop-up menu item” on page 559
You can use a pop-up menu extension point to add pop-up menu items to the IBM MQ Explorer.
“Adding a property tab to an Eclipse property dialog” on page 560
A property tab extension point is used to add a property tab to a property dialog and an associated
property page.

Register a plugin-in with IBM MQ Explorer

How to use the register extension point to register a plugin-in with IBM MQ Explorer and enable notify
events.
The register extension point is used for the following:
• To allow your plug-in to register itself with the IBM MQ Explorer. Every plug-in for the IBM MQ Explorer
must include this extension point in plugin.xml. With out it, any function your plug-in adds to the IBM
MQ Explorer will not be activated.
• To enable notify events.
The following code extract is taken from the file, plugin.xml, from the simple plug-in and shows a basic
implementation of the register extension point:

<extension
id="com.ibm.mq.explorer.sample.simple"
name="Simple Sample"
point="com.ibm.mq.explorer.ui.registerplugin">
<pluginDetails
pluginId="com.ibm.mq.explorer.sample.simple"
name="Simple"
class="com.ibm.mq.explorer.sample.simple.SimpleNotify"
enabledByDefault="true"
description="a very simple sample plug-in to Explorer"
vendor="IBM">
</pluginDetails>
</extension>

Related concepts
“Enabling and disabling a plugin” on page 558
How to enable and disable plugin-ins that contain the register extension point.
“Notify events” on page 558

Introduction to IBM MQ Explorer 557

 Within the IBM MQ Explorer, when an IBM MQ object is created, or manipulated, a Java object relating to
the IBM MQ object can be generated.

Enabling and disabling a plugin

How to enable and disable plugin-ins that contain the register extension point.
All plug-ins that contain the register extension point can be enabled, or disabled, within the IBM MQ
Explorer by doing the following:
1. From the IBM MQ Explorer toolbar click, Window -> Preferences.
2. Expand IBM MQ Explorer.
3. Click Enable plug-ins.
All registered plug-ins are displayed.
4. Select all plug-ins that should be enabled.
5. Click OK.

Notify events
Within the IBM MQ Explorer, when an IBM MQ object is created, or manipulated, a Java object relating to
the IBM MQ object can be generated.
These Java objects can be used to find the name, type, and other externalized attributes of an IBM MQ
object.
For Java objects to be generated, the register extension point must specify a class. In the plugin.xml
file from the simple plugin, the class specified is as follows:

class="com.ibm.mq.explorer.sample.simple.SimpleNotify"

This class contains a number of object specific methods. When an IBM MQ object is created, or
manipulated, the appropriate method from the notify class is called. This class can be used as a basis for
writing your own class. For the methods that this class must contain refer to the IBM MQ Explorer Javadoc
documentation. For information on how to access the IBM MQ Explorer Javadoc documentation, see “API
Reference” on page 561.

Add tree node

A tree node extension point is used to add a tree node to the navigation view and associate it with a
content page.
The following code extract is taken from the file, plugin.xml, from the simple plug-in and shows a basic
implementation of the tree node extension point:

<extension
id="com.ibm.mq.explorer.samples.simpleTreeNode"
name="Simple TreeNode"
point="com.ibm.mq.explorer.ui.addtreenode">
<treeNode
pluginId="com.ibm.mq.explorer.sample.simple"
name="com.ibm.mq.explorer.sample.simple"
class="com.ibm.mq.explorer.sample.simple.SimpleTreeNodeFactory"
treeNodeId="com.ibm.mq.explorer.sample.simple"
sequence="888">
</treeNode>
</extension>

As well as declaring the tree node extension point in plugin.xml, the following classes are needed:
• A class that contains a method that checks the ID of any incoming tree node to determine whether to
add sub nodes to it. This class must implement com.ibm.mq.explorer.ui.extensions.ITreeNodeFactory,
and IExecutableExtension. For the methods that this class must contain, refer to the IBM MQ
Explorer Javadoc documentation. For information on how to access the IBM MQ Explorer Javadoc
documentation, see “API Reference” on page 561.

558 IBM MQ Explorer

 A working example of this class is available in the simple plugin, called SimpleTreeNodeFactory.java
• A class that contains methods that return information about any new tree nodes, such as the name, ID,
and the associated content page class. This class must extend com.ibm.mq.ui.extensions.TreeNode. For
the methods that this class must contain refer to the IBM MQ Explorer Javadoc.
A working example of this class is available in the simple plugin, called SimpleTreeNode.java.

Add content page

A content page extension point is used to add a content page to the content view. A content page can be
associated with a tree node.
The following code extract is taken from the file, plugin.xml, from the simple plug-in and shows a basic
implementation of the content page extension point:

<extension
id="com.ibm.mq.explorer.sample.simpleContentPage"
name="Simple ContentPage"
point="com.ibm.mq.explorer.ui.addcontentpage">
<contentPage
pluginId="com.ibm.mq.explorer.sample.simple"
name="com.ibm.mq.explorer.sample.simple"
class="com.ibm.mq.explorer.sample.simple.SimpleContentPageFactory"
contentPageId="com.ibm.mq.explorer.sample.simple">
</contentPage>
</extension>

As well as declaring the content page extension point in plugin.xml, the following classes are needed:
• A class that contains methods that perform a number of functions such as return the content
page id, create the content page, and set the object to draw the page. This class must extend
com.ibm.mq.ui.extensions.ContentsPage. The class com.ibm.mq.explorer.ui.extensions.ContentTitleBar
can be used to create a title for the content page consistent with the other content pages in the IBM
MQ Explorer. For the methods that this class must contain, refer to the IBM MQ Explorer Javadoc
documentation. For information on how to access the IBM MQ Explorer Javadoc documentation, see
“API Reference” on page 561.
A working example of this class is available in the simple plugin, called SimpleContentPage.java.
• A class that contains a method that returns an instance of the class extending ContentPage. This class
must implement com.ibm.mq.explorer.ui.extensions.IContentPageFactory, and IExecutableExtension.
For the methods that this class must contain refer to the IBM MQ Explorer Javadoc documentation.
A working example of this class is available in the simple plugin, called SimpleContentPageFactory.java

Add a pop-up menu item

You can use a pop-up menu extension point to add pop-up menu items to the IBM MQ Explorer.
The following code extract is taken from the plugin.xml file, which you can find in the simple plugin,
and shows a basic implementation of the pop-up menu extension point:

<extension
id="com.ibm.mq.explorer.sample.simple.object1"
name="Object1"
point="org.eclipse.ui.popupMenus">
<objectContribution
objectClass="com.ibm.mq.explorer.ui.extensions.MQExtObject"
id="com.ibm.mq.explorer.sample.simple.obj1">
<visibility>
<and>
<pluginState
value="activated"
id="com.ibm.mq.explorer.ui">
</pluginState>
<objectClass
name="com.ibm.mq.explorer.ui.extensions.MQExtObject">
</objectClass>
<objectState
name="PluginEnabled"

Introduction to IBM MQ Explorer 559

 value="com.ibm.mq.explorer.sample.simple">
</objectState>
</and>
</visibility>
<action
label="Simple: Sample action on any MQExtObject"
class="com.ibm.mq.explorer.sample.simple.MenuActions"
menubarPath="additions"
id="com.ibm.mq.explorer.sample.simple.obj.action1">
</action>
</objectContribution>
</extension>

You can add menu items by using the Eclipse Platform extension point org.eclipse.ui.popupMenus.
The <visibility> attribute in the preceding extract contains the elements that control the conditions
under which the pop-up menu item is displayed. These conditions include tests on the plug-in state, the
type of object, and the state of the object. For example, a content menu item can be displayed for local
queues only, or for remote queue managers only.

Adding a property tab to an Eclipse property dialog

A property tab extension point is used to add a property tab to a property dialog and an associated
property page.
The following code extract is taken from the file plugin.xml, from the simple plugin, and shows a basic
implementation of the property tab extension point:

<extension
id="com.ibm.mq.explorer.samples.simplePropertyTab"
name="Simple Property Tab"
point="com.ibm.mq.explorer.ui.addpropertytab">
<propertyTab
class="com.ibm.mq.explorer.sample.simple.SimplePropertyTabFactory"
objectId="com.ibm.mq.explorer.queuemanager"
pluginId="com.ibm.mq.explorer.sample.simple"
name="com.ibm.mq.explorer.sample.simple"
propertyTabId="com.ibm.mq.explorer.sample.simple.propertyTab"
propertyTabName="Simple Sample Property Tab"/>
</extension>

As well as declaring the property tab extension point in plugin.xml, the following classes are needed:
• A class that contains a method that creates and returns a property page to
be displayed when a user clicks the property tab. This class must implement
com.ibm.mq.explorer.ui.extensions.IPropertyTabFactory. For the methods that this class must contain
refer to the IBM MQ Explorer Javadoc documentation. For information on how to access the IBM MQ
Explorer Javadoc documentation, see “API Reference” on page 561.
A working example of this class, called SimplePropertyTabFactory.java, is available in the simple plugin.
• A class used for creating the property page must extend com.ibm.mq.ui.extensions.PropertyPage. For
the methods that this class must contain refer to the IBM MQ Explorer Javadoc documentation.
A working example of this class, called SimplePropertyPage.java, is available in the simple plugin.

Applying plug-ins to IBM MQ Explorer

You can either run a plug-in with IBM MQ Explorer from the Eclipse workbench, or apply updates from a
plug-in to IBM MQ Explorer permanently.
To run plug-ins with IBM MQ Explorer from the Eclipse workbench, complete the following steps:
1. Select the plug-in from the Package Explorer.
2. Click Run > Run As > Eclipse Application.
A new Eclipse workbench opens.
3. In the new Eclipse workbench, open the IBM MQ Explorer perspective.

560 IBM MQ Explorer

 4. In the Explorer preferences section, select the "Enable plug-ins" page and enable the relevant
sample plug-in or plug-ins.
To permanently apply updates to IBM MQ Explorer provided by a plugin, complete the following steps:
1. With a file browser, find the plug-in file that provides the functionality extensions to IBM MQ Explorer.
2. Copy the plug-in file, and paste it into MQExplorer\eclipse\dropins within your IBM MQ
installation directory. For example, on Windows: C:\Program Files\IBM\WebSphere MQ\
or /opt/mqm on Linux x86-64 platforms.
3. Restart IBM MQ Explorer.
The updates provided by the plug-in are applied to IBM MQ Explorer.

API Reference
Reference information for the IBM MQ Explorer API.
The API Reference information is available only in the installed IBM MQ Explorer.
To access this information, Launch IBM MQ Explorer, then visit this topic in the embedded Help
documentation.

Introduction to IBM MQ Explorer 561

562 IBM MQ Explorer
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation
Software Interoperability Coordinator, Department 49XA
3605 Highway 52 N
Rochester, MN 55901
U.S.A.

© Copyright IBM Corp. 2007, 2023 563

 Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this information and all licensed material available for it are provided
by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or
any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform
for which the sample programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming interface information

Programming interface information, if provided, is intended to help you create application software for
use with this program.
This book contains information on intended programming interfaces that allow the customer to write
programs to obtain the services of WebSphere MQ.
However, this information may also contain diagnosis, modification, and tuning information. Diagnosis,
modification and tuning information is provided to help you debug your application software.
Important: Do not use this diagnosis, modification, and tuning information as a programming interface
because it is subject to change.

Trademarks
IBM, the IBM logo, ibm.com®, are trademarks of IBM Corporation, registered in many jurisdictions
worldwide. A current list of IBM trademarks is available on the Web at "Copyright and trademark
information"www.ibm.com/legal/copytrade.shtml. Other product and service names might be trademarks
of IBM or other companies.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or
both.

564 Notices
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
This product includes software developed by the Eclipse Project (https://www.eclipse.org/).
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.

Notices 565
566 IBM MQ Explorer
IBM®

Part Number:

(1P) P/N: