Getting Started

Running Gems

Run Gems by launching rungems.cmd

If your TIBCO home directory is not \tibco then you will need to edit rungems.cmd appropriately. For example if your TIBCO home directory is C:\tibhome then set the TIBEMS_ROOT variable to the EMS install directory under the TIBCO home directory:

set TIBEMS_ROOT=C:\tibhome\ems\8.1

To run, Gems requires the following:

Ensure the java executable is available in your path, or edit the rungems.cmd file and set the path appropriately.

Customising The Display

The gems.props configuration file contains various properties for customising the workspace. For example the default workspace size can be configured using the DisplayWidth, and DisplayHeight properties.

See Configuration Properties for a complete list of available properties.

Running Gems as a Monitoring Tool

To run Gems in "view only" mode as a pure monitoring tool launch runsimplegems.cmd

Edit simplegems.props to hide any nonessential displays, and to restrict monitoring views to application specific set of queues and topics.

Configuring EMS Server Connections

Gems supports simultaneous connections to multiple EMS servers. A new EMS Server may be added using the "Add New EMS Server" option on the Edit menu, or alternatively these can be configured in the servers.xml file.

To create a new server connection in the servers.xml file and add a new ConnectionNode element with the mandatory attributes "alias" "url" and "user" The list of available attributes are as follows:

ConnectionNode elements can be grouped in the tree view by specifying custom elements. For example, to group test and dev environments separately:

<MyProject>
    <DEV>
        <ConnectionNode alias="DEV-EMS1"....
        </ConnectionNode>
        <ConnectionNode alias="DEV-EMS2"....
        </ConnectionNode>
    </DEV>
    <TEST>
        <ConnectionNode alias="TEST-EMS1"....
        </ConnectionNode>
        <ConnectionNode alias="TEST-EMS2"....
        </ConnectionNode>
    </TEST>
</MyProject>

The ConnectionNode element may also contain WarnLimits and ErrorLimits child elements. These elements can be used to configure limit values for the Server Monitor screen, indicating when values should be marked amber (warning) and red (error). See the servers.xml file for an example.

Custom icons can be displayed in the tree view by specifying the path to an icon file, for example:

<MyProject icon="images/myImage1.gif">
    <DEV icon="images/myImage2.gif">

Note: After editing the file Gems needs to be restarted for any configuration changes to take effect.

Main Display

The Gems workspace is divided into two main sections. On the left-hand side of the workspace the tree view shows a hierarchical view of configured EMS server connections and their contained objects. The right-hand side of the workspace the tabbed view show detailed information for the selected node from the tree view.

Main Display
Figure 1 - Main Display

Note: In the tabbed view; the table data can be sorted by clicking on the column headers, or Control-clicking to apply secondary sorting.

When starting Gems the tabbed view shows the server monitor display. The server monitor display shows a consolidated table view of all EMS server connections with its current state and various statistical information, including:

These values can be highlighted when configurable limits are reached, either amber (for warning) or red (for error). These limits can be configured for each server connection in the servers.xml file.

To view totals for all displayed servers select "Show Server Totals" from the View menu.

To view the server monitor display select the root node in the tree view on the left-hand side of the workspace.

The display is updated every 20 seconds by default. This can be changed in the property configuration file. However, since every refresh implies communicating to the server to request updated information and thus using a low refresh value may impact server performance.

Monitoring Server Events

An event monitor for each EMS server may be configured using the Event Monitor Editor (on Edit menu) or in the servers.xml file to subscribe to $sys.monitor events. The example below shows subscriptions for limit events (e.g. queue maxmsgs limit reached) and error events such as connection errors and route errors. See EMS documentation for full list of $sys.monitor topics.

  <ConnectionNode alias="EMS-SERVER" url="tcp://localhost:7222" user="admin" password="" autoConnect="true">
    <EventMonitor maxDisplayedEvents="50" enabled="true">
      <EventSubscription monitorTopic="$sys.monitor.limits.*"/>
      <EventSubscription monitorTopic="$sys.monitor.*.error"/>
      <EventSubscription monitorTopic="$sys.monitor.server.warning"/>
    </EventMonitor>
  </ConnectionNode>

Events are shown on the Event Monitor Display, and further information about the event may be viewed by double clicking on the event row. Events may be cleared via the right mouse button pop-up menu.

Destinations may also be monitored, e.g. a subscription of $sys.monitor.Q.r.MyErrorQueue will generate a monitor event when a message is sent to MyErrorQueue. The original message sent to MyErorrQueue can be retrieved by double clicking on the event message to open the event message window then selecting "View Original Message..." from the Message menu.

      <EventSubscription monitorTopic="$sys.monitor.Q.r.MyErrorQueue"/>

Another example use of event monitoring is to highlight any messages that do not have properties set correctly. E.g. to check that a destination should only be used for non-persistent messages a selector may be specified to check the mode property in the monitor message, as shown below. For list of available monitor message properties see Appendix B in the EMS Users Guide.

      <EventSubscription monitorTopic="$sys.monitor.Q.r.MyNonPersistentQ" selector="mode='PERSISTENT'"/>

Note: The event monitor is disabled for standby servers and is not started automatically following an FT switch.

Saving Configuration

Select "Save Config..." from the File menu to save the current configuration to the servers.xml file. Any EMS server passwords will be encrypted and the configuration XML may be edited manually, however any manual changes will not take affect until Gems is restarted.