The IBMMQ data adapter allows access to IBM WebSphere® MQ servers and the ability to query metrics from key MQ entities such as Queue Managers, Queues and Channels. Place raw metrics into RTView functions to calculate SLAs and then present data in dashboards, reports and automated alerts. These metrics can be used to monitor the health and internal state of the MQ servers.
To properly create applications that monitor and manage the health of a JMS implementation you need to know the status of the JMS servers. Realizing the status of JMS servers involves metrics analysis (i.e.: number of consumers, producers, topics and queues), as well as message information (i.e.: rate and queue depth). Access to JMS server metrics is not part of the JMS standard, so a special data source must be provided with each commercial
This section includes:
§ “System Requirements and Setup - IBMMQ” on page 513
§ “Attach to IBMMQ Data” on page 514
§ “Application Options - IBMMQ” on page 519
§ “RTView Deployment - IBMMQ” on page 521
§ “Command Line Options - IBMMQ” on page 522
System Requirements and Setup - IBMMQ
In addition to basic “System Requirements”, the IBMMQ data source requires IBM WebSphere® MQ and is only available if you include your IBM WebSphere MQ provider's IBM WebSphere MQ jars in “RTV_USERPATH”. See the README_sysreq.txt file in your installation’s home directory for the current version(s) supported.
In the Display Viewer Applet, attachments to IBM WebSphere MQ data require the use of the Data Server.
In addition to general environment variables (see “Setup”), you must include the IBM WebSphere MQ jars in “RTV_USERPATH”:
|
Name |
Description |
Example |
|---|---|---|
|
RTV_USERPATH |
Location of these IBM WebSphere MQ jars: com.ibm.mq.jar, connector.jar, com.ibm.mq.pcf-6.0.jar. Note: If RTV_USERPATH already exists, append IBM WebSphere MQ jars to it. |
C:\Program Files\IBM\WebSphere MQ\Java\lib\com.ibm.mq.jar;C:\Program Files\IBM\WebSphere MQ\Java\lib\connector.jar;C:\Program Files\IBM\WebSphere MQ\Java\lib\com.ibm.mq.pcf-6.0.jar Note: com.ibm.mq.pcf-6.0.jar can be obtained from the MS0B: IBM WebSphere MQ Java classes for PCF support pack: http://www-1.ibm.com/support/docview.wss?rs=203&uid=swg24000668&loc=en_US&cs=utf-8&lang=en |
Note: The IBMMQ data source may not be licensed in your RTView installation.
From the Object Properties window you can access the Attach to IBMMQ Data dialog, which allows you to query IBM MQ Objects for selected metrics on one or more MQ servers. Once a property has been attached to a metric, it receives continuous updates.
To bring up the Attach to IBMMQ Data dialog, right-click on the Property Name from the Object Properties window and select Attach to Data>IBMMQ. The Attach to IBMMQ Data dialog provides several drop down menus. If the drop down menu does not contain the item you require, type your selection into the text field.
|
Field Name |
Description |
|
Connection |
Select name of a connection from the drop down menu. Connections can be defined on the “IBMMQ Connections Tab” of the Applications Options dialog. Enter * to select all defined connections. Data is queried across defined connections and is updated as it is returned from individual connections. Since the data is updated asynchronously, it is recommended that attached data are applied to caches in order to aggregate. |
|
Object (Type) |
Select type of object to be queried from the drop down menu. Choose from the following: Connections -- Defined connections used by the data source. Queue Manager -- Queue Manager object used by this connection. Channel Names -- List of named channels used by the Queue Manager. Channel Status -- Channel Status information for named channels. Channels -- Channel attributes for named channels. Queue Names -- List of named Queues used by the Queue Manager. Queues -- Inquired Queue Attributes for named Queues. Note: If the named Queue is a Model Queue, then (as per the API) a dynamic queue is created on the server and an error message is displayed that identifies the cause, disconnects, and marks the connection invalid to prevent re-occurrences. If this happens, investigate the Queues data attachment and modify it so that model queues are not referenced by the Queues query or use the Queues (PCF) query instead. Queues (PCF) -- Queue Attributes for named Queues queried using PCF (Program Control Format) messages. |
|
Names |
Enter an object name associated with the specified Object (Type) or click on the Enter * to select all object names associated with the specified Object (Type) or a value of * can be used to select object names that share a similar prefix (e.g. SYSTEM.DEF*). Multiple object names can be entered manually as a semicolon (;) delimited list (i.e. name1;name2;name3). If your object name contains a space or a semicolon, then the entire name must be enclosed in single quotes. |
|
Columns |
Select a column from the drop down menu. Click on the |
|
Filter Rows |
Check box to indicate whether or not to filter rows. See “Row Filtering” for more information. |
|
Filter Column |
Name of the column to use as a filter. Multiple column names should be entered as a semicolon (;) delimited list (i.e. col1;col2;col 3). If your column name contains a space or a semicolon, then the entire name must be enclosed in single quotes. |
|
Filter Value |
Value that the Filter Column must equal. Multiple filter values should be entered as a nested list, where values for a given column are separated by commas within a semicolon (;) delimited list (i.e. val1,val2;val3,val4;val5,val6). If your filter value contains a space or a semicolon, then the entire value must be enclosed in single quotes. When * is entered as a filter field value, data for all values in the specified filter column will be used to update the object property. When "*" is entered, only the literal comparative value will be used. These are only allowed for objects which display tabular data. |
|
Update Mode |
Specify which mode to use to update the Connection: Poll Every Default Poll Interval -- Update connection each Default Poll Interval. See the “IBMMQ Options Tab” in the Application Options dialog for information on setting the Default Poll Interval. This is the default Update Mode. Every Poll Interval -- Update connection each Poll Interval. If this option is selected, you must specify a Poll Interval. Poll On Demand -- Update connection each time a display that uses this data attachment is opened and each time a substitution string that appears in the data attachment has changed. Poll Once (Static Data) -- Poll for data only once. Select if the data returned by this attribute or operation is static. |
|
Poll Interval |
Specify the interval (in seconds) to update connection. This option is only available if the Update Mode selected is Every Poll Interval. Note: Because the Poll Interval is superseded by the General Update Period, the amount of time elapsed between updates may be longer than the value entered. For example, if the General Update Period is 2 seconds and the Poll Interval is 5 seconds, the connection will be updated every 6 seconds. See “General Tab” for more information. |
|
Data Server |
Select to read data through your configured Data Server and not directly from the The IBMMQ data source. Default - Select the default Data Server you configured in the Application Options>“Data Server Tab”. None - Bypass data being redirected through the specified data server(s) for this attachment and instead attach directly to the data source. Named Data Servers - Select a Named Data Server that you configured in Application Options>Data Server. See “Data Server Tab” for more information. Multi-Server Attachment - To configure multiple data servers, enter a semicolon (;) delimited list containing two or more Named Data Servers (e.g. ds101;ds102). Each name specified must correspond with a Named Data Server that you configured in Application Options>Data Server. It is also possible to specify __default and __none (e.g. __default;ds101;ds102). Note: The values __default and __none begin with two underscore characters. Alternatively, a value of * can be entered to specify all data servers, including __default and __none. When multiple data servers are specified, the data attachment will be directed to each data server in the list. For tabular data attachments, a column named DataServerName will be added as the first column of the table and contain the name of the server from which the data was received. A multi-server attachment will receive data independently from each of the servers it specifies, so in most cases it will be necessary to combine the tables received into a single table. This can be accomplished in two ways: 1. The multi-server attachment can be applied to a local cache that has the DataServerName column specified as an index column. The current table of that cache will contain the combination of the tables received from all servers. Note: It may also be necessary to configure cache row expiration settings to remove defunct rows. 2. The multi-server attachment can be applied as the Table argument of the RTView function named Combine Multi-Server Tables. See “Tabular Functions” for more information. |
When an object property has been attached to data, the Property Name and Value in the Object Properties window will be displayed in green. This indicates that editing values from the Object Properties window is no longer possible. To remove the data attachment and resume editing capabilities in the Object Properties window, right-click on the Property Name and select Detach from Data. You will recognize that an object property has been detached from the data source when the Property Name and Value are no longer green.
Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid.
The following describes the significance of the Attach to IBMMQ Data validation colors:
|
Blue |
Unknown |
Cannot validate entry.* |
|
White |
Valid state |
Entry is valid. |
|
Red |
Invalid state |
Entry is not valid. |
*If a Connection is validated as Unknown, RTView will attempt to validate it when you click OK or Apply.
The Substitutions feature allows you to build open-ended displays in which data attachments depend on values defined at the time the display is run. For example, a generic connection value such as $conn is used instead of a defined connection or $names instead of a list of names. Later when the display is running, $conn is defined by a specific named connection and $names by data from a specific set of named objects, such as queues relating to a particular application. In this way, a single display can be reused to show data from a number of different sources. For more information on creating displays using substitution values, see “Substitutions”.
To bring up the Select Object Name(s) dialog, click on the 
button in the Names field (or right-click in the Names field and choose Select Object Names). The dialog should contain a list of available object names.
Note: In order to populate the list of available names, you must first select a valid Object (Type).
To add a name, make a selection from the Available Object Name(s) list and click on the Add button. If the item you require is not listed, you can type your selection into the Enter Object Name field. Click the Remove button to delete an item previously added to the Selected Object Name(s) list. You can control the order of items in this list with the Move Up and Move Down buttons.
Validation colors indicate whether selected object names are valid. However if even one name selected is invalid, the Names field in the Attach to IBMMQ Data dialog will register as invalid.
To bring up the Select Columns dialog, click on the 
button in the Columns field (or right-click in the Columns field and click Select Columns). The dialog should contain a list of Available Columns.
Note: In order to populate the listing of available columns, you must first select a valid Object (Type) and Name(s).
To add a column, make a selection from the Available Columns list and click on the Add button. If the item you require is not listed, you can type your selection into the Enter Column Name field. Click the Remove button to delete an item previously added to the Selected Columns list. You can control the order of items in the Selected Columns list with the Move Up and Move Down buttons.
Validation colors indicate whether selected columns are valid. However, if even one column selected is invalid, the Columns field in the Attach to IBMMQ Data dialog will register as invalid.
The following describes Attach to IBMMQ Data dialog commands:
|
Command |
Description |
|---|---|
|
OK |
Applies values and closes the dialog. |
|
Apply |
Applies values without closing the dialog. |
|
Reset |
Resets all fields to last values applied. |
|
Clear |
Clears all fields. Detaches object from data source (once Apply or OK is selected). |
|
Cancel |
Closes the dialog with last values applied. |
To access the Application Options dialog, select Tools>Options in the Display Builder.
Options specified in IBMMQ options tabs can be saved in an initialization file (IBMMQOPTIONS.ini). On startup, the initialization file is read by the Display Builder, Display Viewer, Display Server, Data Server and Historian to set initial values. If no directory has been specified for your initialization files and IBMADMOPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “RTV_JAVAOPTS” for more information.
Note: Options specified using command line arguments will override values set in initialization files. See “Command Line Options - IBMMQ” for more information.
There are two Application Options tabs for IBMMQ: “IBMMQ Connections Tab” and “IBMMQ Options Tab”.
This tab allows you to add or remove connections and set your default connection.
When you add an IBMMQ connection to the list it will be highlighted in yellow indicating that RTView has not connected to it. To attempt to connect, click OK, Apply, or Save. If the background remains yellow, then RTView was unable make a connection. Check that your connection was setup correctly and that the server is running.
Note: Regardless of which tab you are currently working from in the Application Options dialog, each time you click OK, Apply, or Save, RTView will attempt to connect to all unconnected connections.
|
Field Name |
Description |
|
Default Connection |
Name of connection used as the default for data attachments. Select from drop down menu to change default setting. |
|
Add Connection |
Click to open the Add IBMMQ Connection dialog. To edit, select a connection from the list and double-click. Connections that are updating objects in a current display cannot be renamed. 
Connection Name -- Name to use when referencing this IBMMQ connection. This name will appear in the Connections drop down menu of the “Attach to IBMMQ Data” dialog. Host -- Name or IP address of the host computer. Port -- Port number of the connection. Channel -- Client Channel to use for this connection (use SYSTEM.DEF.SVRCONN) Model Queue Name -- Named model queue of the connection. Wait Interval -- Wait interval (in seconds) between attempts to create a connection. Expiry -- The time (in seconds) in which the attempt to connect to the IBMMQ data source will expire. The default value is -1, which means the connection will not expire. Max Retries -- Maximum number of subsequent connection retry attempts. A retry will only be attempted when the initial connection failed or when a broken connection error has occurred. When a successful connection has been made, the connection attempt counter is reset to zero. If Max Retries is set to 0, only an initial connect attempt is made for this connection. If Max Retries is set to -1, unlimited connection attempts will be made until a connection is established. This may be useful when MQ servers are cycled for maintenance, or the servers are expected to be down for a period and a connection is wanted when the servers come back up. Retry Interval -- Minimum interval (in seconds) between connection retry attempts. |
|
Remove Connection |
Select a connection from the list and click Remove Connection to delete. Connections that are updating objects in a current display cannot be removed. |
This tab allows you to control how often defined connections will be queried.
|
Field Name |
Description |
|
Default Poll Interval |
Enter the time in seconds to control how often the defined connections will be queried. Default is 0, which queries according to the General Update Period specified in Application Options on the “General Tab”. Because the Default Poll Interval is superseded by the General Update Period, the amount of time elapsed between updates may be longer than the value entered. For example, if the General Update Period is 2 seconds and the Default Poll Interval is 5 seconds, the connection will be updated every 6 seconds. |
This page contains details about the deployment process that are specific to your data source. Please go to the Deployment section of this documentation for instructions on how to implement your RTView deployment option. Return to this page whenever you are instructed to refer to deployment information that is specific to your data source.
The IBMMQ data source has additional “System Requirements and Setup”.
Data Source Configuration File
RTView saves general application settings as well as data source configuration options in initialization files that are read at startup. If no directory has been specified for your initialization files and files are not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “Application Options” and “RTV_JAVAOPTS” for more information.
Include the following initialization file when you deploy RTView with this data source:
|
File Name |
Description |
|
IBMMQOPTIONS.ini |
Contains data source options for IBMMQ. |
Note: Options specified using command line and applet parameters override values set in these initialization files.
Rich Client Browser Deployment Setup for Direct Data Connection
This deployment is not supported by your data source. Use the Data Server to supply data to displays with IBMMQ data attachments. See “Rich Client Browser with Direct Data Connection” for more information.
In addition to General Options, the following command line arguments are enabled with the IBMMQ data source when you run RTView applications from a Windows Command Prompt or UNIX terminal window. See “Command Line Options: Display Builder and Display Viewer” for more information.
Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").
|
Name |
Description |
|
-ibmmqtrace:N |
Enable data source specific tracing. N is an Integer and higher numbers yield more trace output. Default is no tracing enabled (i.e. -ibmmqtrace:0). Example: -ibmmqtrace:6 |
|
-ibmmqoption:MQTrace=N |
Enable low level internal IBMMQ communication library tracing. N is an Integer and higher numbers yield more trace output. Default is no tracing enabled (i.e. -ibmmqoption:MQTrace=0). Example: -ibmmqoption:MQTrace=1 |
button to open the 
button to open the