© Copyright by Grail Software Solutions 2012, 2015
Topic Dashboard
Starter Edition
User’s Guide
Clients Version 2.0.0
Graham Alderson & Phil Blake
Contents
Change History ........................................................................................................................................ 4
Version 2.0.0 ....................................................................................................................................... 4
Version 1.0.1 ....................................................................................................................................... 4
Introduction ............................................................................................................................................ 5
Install ....................................................................................................................................................... 6
Minimum Requirements ..................................................................................................................... 6
Supported Environments .................................................................................................................... 6
Install Topic Dashboard....................................................................................................................... 7
Upgrade Topic Dashboard ...................................................................................................................... 7
Uninstall Topic Dashboard ...................................................................................................................... 7
Starting Topic Dashboard........................................................................................................................ 8
Using Topic Dashboard ......................................................................................................................... 13
Changing Settings for Publisher ........................................................................................................ 15
Changing Settings for Subscriber ...................................................................................................... 16
Topic Dashboard Preferences ............................................................................................................... 17
GSS Topic Dashboard ........................................................................................................................ 17
Default Connection ........................................................................................................................... 18
Message Viewer ................................................................................................................................ 20
MQ Light support in IBM MQ v8 ........................................................................................................... 22
Menus ................................................................................................................................................... 24
File → Connect to a queue manager... ......................................................................................... 24
File → Select topic......................................................................................................................... 24
File → GSS trace → Options... ....................................................................................................... 24
File → GSS trace → Start ............................................................................................................... 24
File → GSS trace → Stop ............................................................................................................... 24
File → Exit...................................................................................................................................... 24
Window → Show View → GSS Publisher ...................................................................................... 24
Window → Show View → GSS Subscriber .................................................................................... 24
Window → Show View → Error Log ............................................................................................. 25
Window → Reset Perspective ....................................................................................................... 25
Window → Navigation → Show View Menu ................................................................................ 25
Window → Navigation → Maximize Active View or Editor .......................................................... 25
Window → Navigation → Minimize Active View or Editor ........................................................... 25
© Copyright by Grail Software Solutions 2012, 2015
Page 2
Window → Navigation → Next View ............................................................................................ 25
Window → Navigation → Previous View ...................................................................................... 25
Window → Preferences ................................................................................................................ 25
Help → Help Contents................................................................................................................... 25
Help → Search............................................................................................................................... 25
Help → Dynamic Help ................................................................................................................... 25
Help → Contact us ........................................................................................................................ 25
Help → About GSS Topic Dashboard ............................................................................................ 25
Trademarks ........................................................................................................................................... 27
Appendix A ............................................................................................................................................ 28
Appendix B ............................................................................................................................................ 29
Appendix C ............................................................................................................................................ 30
© Copyright by Grail Software Solutions 2012, 2015
Page 3
Change History
Version 2.0.0
Grail Software Solutions (GSS) Topic Dashboard Starter Edition v2.0.0 has the following
enhancements:
1. Now an Eclipse™ RCP application, making it much easier to install/uninstall.
2. A message viewer has been added to view message data published and consumed.
 Contents of the viewer can be paused
 Messages can be cleared
 Messages can be exported to a file
3. Only 2 subscribers are now shown by default, but more can be added.
4. New preferences to
 Set message rate graphical type for each view
 Show Message Viewer
 Control use of the default connection
 Control contents of the Message Viewer
5. The published message size can be set.
Version 1.0.1
GSS Topic Dashboard Starter Edition v1.0.1 has the following enhancements:
1. Auto-reconnect to a queue manager using previously defined connection details.
When using the ‘Connect to a Queue Manager’ wizard, there is a new option on a
connection details page to enable this new feature, so the next time the Topic Dashboard
client application is started, it will attempt to connect to the same queue manager using the
same connection details. If the connection fails then the wizard can be launched from a
context menu on the ‘File’ menu. See Starting GSS Topic Dashboard for more information.
2. Added new menu option ‘Contact Us...’ on the Help menu.
This will launch the system default browser and show the GSS Contact Us web page.
3. Eclipse 4.2.2 now supported.
A new option has also been added to the start of Eclipse™ in the sample start up script.
Instructions for upgrading from v1.0.1 can be found in chapter Upgrade GSS Topic Dashboard.
© Copyright by Grail Software Solutions 2012, 2015
Page 4
Introduction
GSS Topic Dashboard Starter Edition v2.0.0 is an Eclipse™ RCP application. There is an earlier
version of Topic Dashboard which can be installed in the IBM® MQ Explorer and that is described in
another document.
This version runs as an IBM® MQ Client connecting to a queue manager. Client connections to a
queue manager will be administered by the IBM® MQ Administrator.
Topic Dashboard can be used to publish (PUB) messages on a topic and subscribe (GET) publications
on the same or different topic. Initially each Topic Dashboard has one publisher and two
subscribers. Further subscribers can be added. Each action has its own view on the dashboard.
A Message Viewer can be used to show messages published and consumed.
A different topic string can be selected on the same queue manager when the views are not
publishing and consuming messages. A new instance of the Topic Dashboard is needed to connect to
a different queue manager.
Using IBM® MQ 8.0.0.3 with an optional installable component for IBM® MQ Light, an application
like GSS Topic Dashboard for MQ Light can connect to the same MQ environment as Topic
Dashboard. The messages seen in the Message Viewer of the GSS Subscriber view can be a mixture
of publications from the GSS Publisher and messages from the GSS Topic Dashboard for MQ Light
application. See MQ Light support in IBM MQ v8 for more information.
© Copyright by Grail Software Solutions 2012, 2015
Page 5
Install
Minimum Requirements
Minimum requirements to use GSS Topic Dashboard Client version is



Windows 7®
IBM® MQ Client 7.0.1.8
Java™ Runtime Environment (JRE) 7
Supported Environments
There are many environments that the Topic Dashboard Client version could potentially be run in –
combinations of the various versions of Windows®, JRE’s, an IBM® MQ Client and the operating
systems they all support.
As a small company with limited time and resources, at present we have only tested the Topic
Dashboard Client version in the following environments:





Windows® 7 SP1
Windows® 8.1
JRE 8 (from Oracle®)
IBM® MQ Client 7.5.0.2 and 8.0.0.3
connecting to a queue manager on IBM® MQ 7.5.0.2 and 8.0.0.3
While we would expect the Topic Dashboard Client version to install and run correctly in other
environments, for example on other versions of Windows® or on the various Linux® distributions, as
they are currently untested we would not be able to guarantee this is the case. For this reason, at
present we have not provided a start-up script for the Topic Dashboard Client version for use on
Linux®.
© Copyright by Grail Software Solutions 2012, 2015
Page 6
Install Topic Dashboard
Before installing the Topic Dashboard, a JRE and an IBM® MQ Client
(www.ibm.com/support/docview.wss?rs=171&uid=swg27007198#3) need to be installed first. Full
installation instructions can be found with these products.
A file called GssTopicDashboardClient.zip contains the Topic Dashboard RCP application and can be
downloaded from www.grailsoftwaresolutions.co.uk/download
Unzip the file into a location of your choice, for example, c:\GSS\ and make sure the file is unzipped
with the option to maintain the sub-directory structure. The output directory structure will look like:
GSS/
StartGssTopicDashboardClient.cmd
eclipse/
configuration/
plugins/
.eclipseproduct
eclipse.exe
The contents of the ‘configuration’ and ‘plugins’ directories are not listed as this is not relevant to
the use of the Topic Dashboard. They contain information and code necessary to run the RCP
application.
Upgrade Topic Dashboard
As Topic Dashboard is now shipped as an RCP application, the previous version can just be
uninstalled.
Uninstall Topic Dashboard
Delete the files and directories from the GSS folder, as created during the install process.
© Copyright by Grail Software Solutions 2012, 2015
Page 7
Starting Topic Dashboard
To start the Topic Dashboard, locate the StartGssTopicDashboardClient.cmd in the directory created
during the install process. This command can be run from a command line or Windows® Explorer.
Running StartGssTopicDashboardClient.cmd will display the Topic Dashboard splash screen
The first time the Topic Dashboard is run, a license agreement dialog is shown. Press the ‘Accept’
button to continue or the ‘Decline’ button to close the application.
© Copyright by Grail Software Solutions 2012, 2015
Page 8
After the ‘Accept’ button has been pressed on the license agreement dialog a wizard is shown to
allow connection to a queue manager.
© Copyright by Grail Software Solutions 2012, 2015
Page 9
If the wizard detects a local queue manager, then ‘on this computer’ option is selected, otherwise
‘on a different computer using a simple client connection’ is selected.
© Copyright by Grail Software Solutions 2012, 2015
Page 10
The ‘making a simple client connection’ page will also remember previous connection details,
making the connection to the same queue manager much quicker, not having to retype the same
connection details each time.
Select ‘Use this connection each time this application is started’ so the next time the Topic
Dashboard is started, it will use these connection details to connect to the target queue manager.
This action can be controlled using the Preferences. Note if a password is required for the
connection then a password prompt will be shown.
Pressing the ‘Finish’ button will try to connect to the remote queue manager, passing details of the
user currently logged into Windows®.
To change the user details, press the ‘Next’ button instead of the ‘Finish’ button to display a page
showing the userid and password to be passed with the connection details. This defaults to the
logged in userid. If details from a previous connection were used on the previous page, then the
page will show the saved userid. Note passwords are not persisted with connection details.
Pressing the ‘Finish’ button will try to connect to the remote queue manager. If the connection is
successful then a topic selection dialog is displayed. An error dialog will be shown if the connection
failed.
© Copyright by Grail Software Solutions 2012, 2015
Page 11
This dialog has an entry field where you can type the name of the topic string to be used. If the
userid in use has the authority to query the names of the topic objects on the queue manager, then
a drop down list below the entry field will show the available topic strings. The contents of the drop
down list will be filtered as you type characters into the entry field. You can double-click an entry in
the drop-down list to replace the contents of the entry field with that name. Press the ‘OK’ button
when the topic string has been entered.
© Copyright by Grail Software Solutions 2012, 2015
Page 12
Using Topic Dashboard
Initially the Topic Dashboard contains two views, one to publish (PUB) messages on the selected
topic and two to consume (GET) publications on the same topic.
Each view has a default graphical representation of the action and this can easily be changed by
selecting a different icon on the view tool bar or view menu. Preferences are available to control the
initial content of each view.
Press the ‘Start’ button on the Publisher view to generate messages and publish them on the
selected topic. Press the ‘Start’ button on the Subscriber view and publications will be consumed
from the selected topic.
The publisher and subscribers in the same Dashboard share the same connection to the queue
manager. The subscriber does not perform a get-with-wait as this will stop other activity on the
connection. Each subscriber will keep consuming publications until there are no more to consume
and then it will wait (see Settings dialog below for setting the wait interval). Closing a view after the
‘Start’ button has been pressed will stop the current activity.
The action of publishing and consuming publications has default values and can be controlled by
using the ‘Settings...’ button.
Each subscriber view can change the default topic string and also launch another Subscriber view.
© Copyright by Grail Software Solutions 2012, 2015
Page 13
Actions on the Message Viewer tool bar can be used to





Pause messages appearing in the viewer. Messages will continue to be published and
consumed, just not shown in the viewer.
Resume messages appearing in the viewer. Only newly published and consumed messages
will be added to the viewer.
Delete message(s) from the viewer. This is only enabled when Pause has been pressed.
Select one or more messages to be deleted. All messages will be deleted if none selected.
Export messages to a file. Select one or more messages to be exported. All messages will be
exported if none selected.
The ‘+’ and ‘-’ actions are only applicable for array of byte messages. Press ‘+’ to expand all
byte messages that have more than 1 line of data and ‘-’ to collapse any expanded
messages.
© Copyright by Grail Software Solutions 2012, 2015
Page 14
Changing Settings for Publisher
The ‘Settings...’ button on the Publisher view shows ‘Publisher – Settings’ dialog.
Message size is the size of each published message. The message text is ‘GSS test publication for
IBM MQ #’ with a message number added at the end of the string. Increasing the size of the message
will add padding characters to each message. The pad character is an asterisk (*).
Generate persistent messages can be selected to publish persistent messages.
Minimum interval between each message published is used to control the delay between each
published message.
Limit the number of messages published can be selected to automatically stop the Publisher view
when the number of published messages is reached.
© Copyright by Grail Software Solutions 2012, 2015
Page 15
Changing Settings for Subscriber
The ‘Settings...’ button on the Subscriber view shows the ‘Subscriber - Settings’ dialog.
Minimum interval before trying to get a message can be used to control the delay before trying to
consume the next publication.
© Copyright by Grail Software Solutions 2012, 2015
Page 16
Topic Dashboard Preferences
To manage Topic Dashboard preferences select ‘Preferences...’ from the main ‘Window’ menu.
GSS Topic Dashboard
The contents of each view can be controlled at start up. The message rate can be shown graphically
as a graph, a dial, a meter or as figures. The Message Viewer is shown by default.
These selections can be changed for each individual view after the view is first shown, using the
appropriate action on the action bar.
© Copyright by Grail Software Solutions 2012, 2015
Page 17
Default Connection
A default connection can be defined when using the ‘Connect to a Queue Manager’ wizard and is
used when the Topic Dashboard is started. The use of a default connection can be controlled using
these preferences.
If ‘Always use it’ is selected, the next time Topic Dashboard is started it will use the default
connection. Note, if a password is required for the connection then a password prompt will be
shown.
If ‘Ask whether to use it’ is selected, the next time Topic Dashboard is started it will show a prompt
to use the default connection. If the user declines to use the default connection, the ‘Connect to a
Queue Manager’ wizard is shown.
If ‘Ignore it’ is selected, the next time Topic Dashboard is started it will ignore the default connection
and show the ‘Connect to a Queue Manager’ wizard.
Press the ‘Delete Default Connection...’ button to remove the default connection details.
© Copyright by Grail Software Solutions 2012, 2015
Page 18
If there is no default connection, then the following preference information is shown.
© Copyright by Grail Software Solutions 2012, 2015
Page 19
Message Viewer
The content of the message viewer can controlled using the Options preferences.
Use the first slider to change the number of messages shown in the viewer. When this number is
reached, oldest messages are removed in favour of the newer ones.
String messages (those defined with a message format of MQFMT_STRING) can be shown as a string
or as an array of bytes. All other formats will be shown as an array of bytes.
The second and third sliders can be used change the length of messages shown in the viewer. Note,
the last column in the Message Viewer will show the actual number of bytes in the message.
© Copyright by Grail Software Solutions 2012, 2015
Page 20
The font for the messages shown in the viewer can also be changed. This will change all messages.
© Copyright by Grail Software Solutions 2012, 2015
Page 21
MQ Light support in IBM MQ v8
IBM® MQ 8.0.0.3 has an optional installable service to allow IBM® MQ Light applications to connect
to an MQ environment. Using this feature it is possible to connect an MQ Light application (such as
the Topic Dashboard for MQ Light) to the same MQ environment as Topic Dashboard and show the
MQ Light messages and MQ publications in the same Message Viewer.
Start Topic Dashboard and connect to an MQ v8 queue manager and specify a topic, for example,
Sports. Start Topic Dashboard for MQ Light and connect to the MQ Light service associated with the
same queue manager. Specify the same topic, ‘Sports’. Start the GSS Publisher and GSS Subscriber in
Topic Dashboard. Start the GSS Sender and GSS Receiver in Topic Dashboard for MQ Light.
The following picture of Topic Dashboard shows MQ Light messages in the Message Viewer of GSS
Subscriber alongside publications from the GSS Publisher.
© Copyright by Grail Software Solutions 2012, 2015
Page 22
The following picture of Topic Dashboard for IBM MQ Light shows MQ publications in the Message
Viewer of GSS Receiver alongside messages from the GSS Sender.
Note Topic Dashboard for MQ Light can be downloaded from
www.grailsoftwaresolutions.co.uk/download
© Copyright by Grail Software Solutions 2012, 2015
Page 23
Menus
The Topic Dashboard menu bar has 3 main menus, File, Window and Help.
File → Connect to a queue manager...
This menu item will be enabled if the Topic Dashboard was started and the connection wizard did
not connect to a queue manager. It launches the Connect to a Queue Manager wizard.
File → Select topic...
This menu item will be enabled if there is a connection to a queue manager and the publisher and
subscribers are stopped. It displays the Select Topic dialog.
File → GSS trace → Options...
This menu item will be enabled if there is no location defined for the GSS trace file or GSS trace has
not been started. A dialog is shown to define the location for the GSS trace file and to choose
whether to start GSS trace the next time the Topic Dashboard is started. Note that GSS trace should
only be used under the guidance of Grail Software Solutions to help diagnose any problems.
File → GSS trace → Start
This menu item will be enabled if a location has been defined for the GSS trace file and GSS trace has
not been started. Note that GSS trace should only be used under the guidance of Grail Software
Solutions to help diagnose any problems.
File → GSS trace → Stop
This menu item will be enabled if GSS trace has been started. Note that GSS trace should only be
used under the guidance of Grail Software Solutions to help diagnose any problems.
File → Exit
This will stop any actions on a topic, disconnect from the queue manager and close the dashboard.
Window → Show View → GSS Publisher
This menu item will give focus to the GSS Publisher view. If the view is closed, then it will be opened.
Window → Show View → GSS Subscriber
This menu item will give focus to the GSS Subscriber view. If the view is closed, then it will be
opened.
© Copyright by Grail Software Solutions 2012, 2015
Page 24
Window → Show View → Error Log
This menu item will give focus to the Eclipse™ Error Log view. If the view is closed, then it will be
opened. Note this view should only be used under the guidance of Grail Software Solutions to help
diagnose any problems.
Window → Reset Perspective
This menu item will reset the perspective back to its original state, showing the GSS Publisher view
and GSS Subscriber views in their default locations. Any other opened views will be closed.
Window → Navigation → Show View Menu
This menu item will open the view menu for the view that currently has focus.
Window → Navigation → Maximize Active View or Editor
This menu item will maximize the view that currently has focus.
Window → Navigation → Minimize Active View or Editor
This menu item will minimize the view that currently has focus.
Window → Navigation → Next View
This menu item will give focus to the next view from that which currently has focus.
Window → Navigation → Previous View
This menu item will give focus to the previous view from that which currently has focus.
Window → Preferences
This menu item will open the Topic Dashboard preferences window
Help → Help Contents
This menu item will open the Eclipse™ help Infocenter.
Help → Search
This menu item will open the Eclipse™ help tray view, with a search field.
Help → Dynamic Help
This menu item will open the Eclipse™ help tray and show the online help for the currently selected
view.
Help → Contact us
This menu item will open the system default browser and show the GSS Contact Us web page.
Help → About GSS Topic Dashboard
This menu item displays the following dialog providing information about the Topic Dashboard.
© Copyright by Grail Software Solutions 2012, 2015
Page 25
© Copyright by Grail Software Solutions 2012, 2015
Page 26
Trademarks
The following are trademarks of International Business Machines Corporation, registered in many
jurisdictions worldwide.
IBM
The following is a trademark of Microsoft Corporation, registered in many jurisdictions worldwide.
Windows
The following are trademarks of Eclipse Foundation, Inc.
Eclipse
Built on Eclipse
The following is a registered trademark of Linus Torvalds in the U.S. and other countries.
Linux
© Copyright by Grail Software Solutions 2012, 2015
Page 27
Appendix A
This is a complete list of Topic Dashboard icons.
GSS Publisher view
GSS Subscriber view
Add a new GSS Subscriber Viewer
Hide or show a Message Viewer
Pause adding messages to the Message Viewer
Resume adding messages to the Message Viewer
Expand all messages in the Message Viewer
Collapse all messages in the Message Viewer
Clear messages from the Message Viewer
Export messages from the Message Viewer
Show message rate in a graph
Show message rate as a dial
Show message rate as a meter
Show message rate as figures
© Copyright by Grail Software Solutions 2012, 2015
Page 28
Appendix B
This is a list of enhancements and additional features that may be included in future versions of the
Topic Dashboard (in no particular order):







Allow byte data to be sent
Allow user defined strings to be sent
Allow user defined bytes (a file) to be sent
Different message viewer preferences for the Publisher and Subscriber views
Support SSL connections
'Restore Defaults' button on each settings dialog
Pause/Resume buttons on t
© Copyright by Grail Software Solutions 2012, 2015
Page 29
Appendix C
This is a list of system messages generated by Topic Dashboard.
GSS3505
Explanation
Response
Unexpected error, reason code {0}.
An unexpected error has occurred after pressing the start button.
It is recommended you run a GSS trace of the problem and send the trace file to
GSS for further analysis (info@grailsoftwaresolutions.co.uk).
GSS3507
Explanation
Response
Topic {0} does not exist.
The topic does not exist on the connected queue manager.
Choose a different topic.
GSS3508
User does not have {0} authority for topic {1}. Press OK to continue or Cancel to
select another topic.
The message shows which authority (PUB or SUB) is missing on the selected topic.
Choosing to continue will stop one or more features of the Topic Dashboard from
working, depending on which authority is missing. The MQ administrator should be
contacted to give the appropriate authority.
Explanation
Response
GSS3509
Explanation
Response
GSS3510
Explanation
Response
GSS3512
Explanation
Response
User does not have {0} or {1} authority for topic {2}. Press OK to continue or Cancel
to select another queue.
The message shows which 2 authorities (PUB and SUB) are missing on the selected
topic.
Choosing to continue will stop one or more features of the Queue Dashboard from
working, depending on which authorities are missing. The MQ administrator should
be contacted to give the appropriate authority.
User does not have sufficient authority for topic {0}.
Topic Dashboard will check the user has PUB and SUB authority on the selected
topic. This message is shown due to some other missing authority.
Choosing to continue will stop one or more features of the Topic Dashboard from
working, depending on which authorities are missing. The MQ administrator should
be contacted to check the queue manager error log for more information.
To connect to {0} using the Default Connection press OK. To make a different
connection press Cancel
There is a default connection for Topic Dashboard and the preference to ‘Ask
whether to use it’ has been set. This prompt is displayed when Topic Dashboard is
started or the ‘Connect to a Queue Manager’ wizard is launched.
Press OK to use the default connection or Cancel to show the ‘Connect to a Queue
Manager’ wizard. Alternatively, change the Default Connection preference to stop
this prompt from being shown.
© Copyright by Grail Software Solutions 2012, 2015
Page 30