======================================================================= IBM Tivoli Monitoring for Business Integration: WebSphere MQ Message Manager Console - Version 5.1.0 ======================================================================= Licensed Materials - Property of IBM IBM Tivoli Monitoring for Business Integration: WebSphere MQ (C) Copyright IBM Corp. 2002 All Rights Reserved US Government Users Restricted Rights - Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. ======================================================================= CONTENTS ======== 1 Introduction 2 Description of Release 3 Software Requirements 4 Installing Message Manager 5 Uninstalling Message Manager 6 Starting and Stopping Message Manager 7 Using Message Manager 8 Getting Assistance 9 Log Files 10 Known Problems 1 INTRODUCTION ============ This readme file describes how to install, configure, and use the IBM Tivoli Monitoring for Business Integration: WebSphere MQ Message Manager Console - Version 5.1.0, hereafter referred to as Message Manager. 2 DESCRIPTION OF RELEASE ====================== Message Manager is a JAVA application implemented as a WebSphere MQ client that manages messages on a queue. Message Manager enables you to do the following: . Browse a message . Move a message to another queue . Copy a message to another queue . Delete a message . Save a message to a file . Import data from a file into a message . Export data into a file from a message 3 SOFTWARE REQUIREMENTS ===================== Message Manager requires the following software: . Java Runtime Environment (1.3.1) NOTE: For Windows, the JRE must be the "all languages". The U.S. English only does not supply the needed i18n.jar. . WebSphere MQ SupportPacs o MA88: WebSphere MQ classes for Java and MQSeries classes for Java Message Service (included in WebSphere MQ 5.3) o MS0B: WebSphere MQ Java classes for PCF . IBM WebSphere MQ version 5.2, 5.2.1, or 5.3 NOTE: The mm4wmq.cmd and the mm4wmq.sh command scripts add the required MA88 and MS0B jar files to the classpath. The mm4wmq.cmd command script hardcodes the following MA88 jar files: com.ibm.mq.jar, com.ibm.mqbind.jar, com.ibm.mqjms.jar, connector.jar, fscontext.jar, jms.jar, jndi.jar, jta.jar, ldap.jar, providerutil.jar. 4 INSTALLING MESSAGE MANAGER ========================== To install Message Manager, use one of the following executables: . For IBM AIX 4.3.3, 5.1, and 5.2 setupaix.bin . For HP-UX 11.0 and 11i setuphp11x.bin . For Sun Solaris 2.6, 2.7, and 2.8 setupsolarisSparc.bin . For Microsoft Windows NT 4.0 SP6+ and Microsoft Windows 2000 Server and Advanced Server Edition setupwin32.exe The Java(tm) Virtual Machine (JVM) must installed to enable the executables to run. To install Message Manager, follow these steps: 1. Run the appropriate setup executable from the command line to search for the JVM and to display the Installer dialog. 2. Complete the Installer dialog prompts as follows: a. Directory Name: Enter the full path name of the directory in which you want to install Message Manager. Click Next. b. Enter full directory path for logging: Accept the default value or enter the full directory path for the log file. Click Next. c. Enter full directory path to com.ibm.mq.jar: Use the Browse button or enter the full path name of the directory in which the com.ibm.mq.jar file is installed. d. Enter full directory path to com.ibm.mq.pcf.jar: Use the Browse button or enter the full path name of the directory in which the com.ibm.mq.pcf.jar file is installed. Click Next. 3. Click Finish to exit the installation wizard. During installation, the mm4wmq.sh and mm4wmq.cmd files set the following environment variables: MM_PATH=Installation directory MM_LOG_PATH=Log directory MM_JAVA_LIBRARY_PATH=MA88 directory MM_PCF_PATH=MS0B directory The installation process installs the following product files in the specified installation directory: com.windriver.browser.exe or com.windriver.browser.bin ib5projs.jar jhall.jar jlog.jar mm4wmq.cmd mm4wmq.jar mm4wmq.sh ps_default_hs.jar ua_swing.jar uil.jar A subdirectory named _uninst is also created in the installation directory. The _uninst subdirectory contains the following files: uninstall.dat uninstall.jar uninstaller.exe or uninstaller.bin The product size is approximately 10.3 MB, depending on the platform on which you installed Message Manager. 5 UNINSTALLING MESSAGE MANAGER ============================ To uninstall Message Manager, enter the following command at the command line: uninstaller.exe The Uninstaller dialog is displayed. Respond to the dialog prompts to uninstall Message Manager. 6 STARTING AND STOPPING MESSAGE MANAGER ===================================== To start Message Manager, enter one of the following commands at the command line: mm4wmq OR mm4wmq -m qmgrname -h hostname [-p port] OR mm4wmq -f cfg_file [-d qmgrname] OR mm4wmq -F where: -m qmgrname Specifies the name of the queue manager for the queues you want to manage -h hostname Specifies the TCP/IP host name of the machine where the queue manager resides. You can specify a simple host name (such as, myhost), a fully qualified host name (such as, myhost@ibm.com), or an IP address (such as, 9.20.2.1). -p port (Optional) Specifies the port number that the channel listener for the queue manager is using. If you do not specify a port number, the default port number is 1414. -f cfg_file Specifies the name of the file that contains a list of queue manager names for the queues you want to manage. Specify each queue manager name on a separate line in the file in the following format: qmgrname:host:port If you do not specify a port number, the default port number is 1414. See the section on Using Message Manager for more information about creating the configuration file. -d qmgrname (Optional) Specifies the name of the queue manager that Message Manager connects to when you start Message Manager. -F Starts Message Manager without displaying any queue manager names. NOTE: If you start Message Manager with the mm4wmq command without parameters, Message Manager starts in the same way as the last time you started it. To stop Message Manager, select Exit from the Console menu on the Message Manager console. 7 USING MESSAGE MANAGER ===================== The Message Manager console is designed as a Property Notebook that uses an Explorer-type interface. The Message Manager console contains a title bar, a menu bar, a tool bar, a status bar, and a workspace that is comprised of a navigation area (a tree panel) and a work area. 7.1 Menu Bar The menu bar consists of the following menu items: Console - Alt-c New... Ctrl-N Open... Ctrl-O Save... Ctrl-S Save As... Exit Alt-F4 Edit - Alt-E Cut Ctrl-X Copy Ctrl-C Paste Ctrl-V Delete... View - Alt-V Show System Objects Refresh F5 Action - Alt-A For the Message Manager View and Queue Manager List View: Add Definition For the Queue Manager View Connect Disconnect Change Definition Delete Definition Add Definition For the Queue List View Add Definition For the Queue View: Save Message... Add Definition Properties Note: The Action menu items are also available on context menus. Click a queue manager, a queue, or a message in the navigation area or in one of the views in the Message Manager console and then right-click to display the context menu. Help - Shift-F1 or Alt-H Open User Assistant Shift-F1 Table of Contents Index Search About Message Manager Console 7.2 The Tool Bar The tool bar provides icons that enable quick access to the following functions: Cut, Copy, Paste, Delete, Refresh, and Help. These icons have four states: Normal (enabled), Roll-over emphasis, Selected (pushed in) and Unavailable (disabled). 7.3 The Workspace The workspace, which is comprised of a navigation area and the work area, represents the queue managers for the queues you want to manage. The workspace functions, which are available from the Console menu, are: New, Open, Save, and Save As. The Open, Save, and Save As functions work with a configuration file. The configuration file is a text file that includes the queue manager names that you want displayed in the Message Manager Console workspace. You can create the configuration file in the following ways: - Create the configuration file with any text editor. Specify each queue manager name on a separate line in the file in the following format: qmgrname:host:port The port number is optional. If you do not specify a port number, the default port number is 1414. Here is an example of a configuration file: someqmgr:somehost:someport someqmgr2:somehost someqmgr3:anotherhost.domainname:someport3 someqmgr4:anotherhost - Select Add Definition (one or more times) from the Action menu on the Message Manager Console. Complete the Add Definition dialog for each queue manager definition you are adding. The port number is optional. If you do not specify a port number on the Add Definition dialog, the default port number is 1414. When you have finished adding definitions for the queue managers you want to include in this configuration file, select Save from the Console menu to save the configuration in the configuration file that is open or select Save As from the Console menu to save the configuration in a new configuration file. 7.3.1 New ======================================================================= To clear the workspace, select New from the Console menu. The navigation area displays only the Message Manager node, the navigation area title displays "File: NEW", and the work area displays an empty Message Manager View. 7.3.2 Open To open a saved Workspace, select Open from the Console menu. Then select a configuration file from the Open dialog and select Open. The navigation area displays a tree view containing the queue manager node, the navigation area title displays "File: config_filename", and the work area displays the list of queue managers in the configuration file. 7.3.3 Save and Save As To save a modified Workspace, select Save or Save As from the Console menu. Then enter a configuration file name in the Save dialog and select Save. If a configuration file is already open, the Save option saves the configuration in that configuration file. 7.4 The Navigation Area The navigation area is the left pane on the Message Manager Console. It contains a navigation tree consisting of a root node (named Message Manager) Queue Manager List node (named Queue Managers), Queue Manager nodes (the names of the queue managers), Queue List nodes (named Queues), and Queue nodes (the names of each queue) in a hierarchical structure that links the queue nodes to their queue manager node. Click any node to display the corresponding view (Message Manager View, Queue Manager List View, and so forth) in the work area. Double-click any node to expand or collapse the navigation view. When you expand the Message Manager node, the Queue Managers node is displayed. When you expand the Queue Managers node, the queue manager names are displayed. To expand the view for a specific queue manager, click the appropriate queue manager name. Then right-click and select Connect from the context menu. The Queues node is displayed. Double-click the Queues node to display a the queue names. Click a queue name to display the Queue View and a list of the messages in the queue in the work area. Right-click any node to display the context menu, which contains the same menu options as the Action menu for that particular view. 7.5 The Work Area The work area is the right pane on the Message Manager Console. It displays the view that corresponds to the node you selected in the navigation area. The names of these views are: Message Manager View, Queue Manager List, Queue Manager View, Queue List, and Queue View. 7.5.1 Message Manager View The Message Manager View is displayed when you click the Message Manager node in the navigation area. It contains the Queue Managers node if you have defined one or more queue managers. This view is empty and is the default view when no queue managers are defined. 7.5.2 Queue Manager List The Queue Manager List view is displayed when you click the Queue Managers node in the navigation area. The Queue Manager List view contains a list of queue managers defined, the host name of each queue manager, and the port number for each queue manager. From this view, you can connect to or disconnect from a queue manager, and add, change, or delete a queue manager definition. To display the Queue Manager view for a specific queue manager, double-click a queue manager in the list in the work area, click a queue manager in the navigation area, or click a queue manager in the work area and select Properties from the Action menu or from the context menu. 7.5.2.1 Connect To connect to a queue manager, click a queue manager from the navigation area or from the Queue Manager List view in the work area. Then select Connect from the Action menu or from the context menu or click the Connect icon on the tool bar. To connect to a WebSphere MQ queue manager, ensure that the following requirements are met: . The port defined in the Message Manager queue manager definition must match the port that the channel listener uses. . The WebSphere MQ queue manager channel listener must be started. . The WebSphere MQ queue manager command server must be started. . A server connection channel named MM.SERVER.CHANNEL must be defined for the queue manager. If the queue manager's auto channel definition is ENABLED, then this will be created automatically. . (For zOS/OS390 only) A model queue named MM.REPLY.QUEUE.MODEL with DEFTYPE(TEMPDYN) must be defined for the queue manager. NOTE: 1. Most WebSphere MQ reason codes 2059 and 2009 are a result of one of the first four requirements not being met. 2. WebSphere MQ reason code 2085 is usually a result of the MM.REPLY.QUEUE.MODEL not being defined for zOS/OS390 queue managers. 7.5.2.2 Disconnect To disconnect from a queue manager, click a queue manager from the navigation area or from the Queue Manager List view in the work area. Select Disconnect from the Action menu or from the context menu or click the Disconnect icon on the tool bar. 7.5.2.3 Add Definition To add a new queue manager definition to the present configuration, select Add Definition from the Action or the context menu in any view. The Add Definition dialog is displayed with input fields for the queue manager name, host name, and port number (optional). When you select a field, information about how to complete the field is displayed in the left section of the dialog. After adding a definition, the Queue Manager List view and the navigation area, if the tree is expanded, are refreshed to display the new queue manager. Select Save from the Console menu to save this configuration in the configuration file that is open, or select Save As from the Console menu to save this configuration in a new configuration file. 7.5.2.4 Change Definition To change a queue manager definition, click a queue manager name from the navigation area or from the Queue Manager List view in the work area. Select Change Definition from the Action menu or from the context menu. The queue manager must be disconnected to change the definition. A Change Definition dialog is displayed with name of the queue manager, the host name, and port number (optional). Make the appropriate change and select Enter. 7.5.2.5 Delete Definition To delete a queue manager definition, click a queue manager name from the navigation area or from the Queue Manager List view in the work area. Select Delete Definition from the Action menu or from the context menu. The queue manager must be disconnected to delete the definition. A confirmation dialog is displayed. 7.5.3 Queue Manager View To display the Queue Manager View, click a queue manager name in the navigation area. It contains a Queues Node if one or more queues are listed when you connect to the queue manager or when you refresh the view. This view is empty if the queue manager has no queues. 7.5.4 Queue List View To display the Queue List View, click a Queues node in the navigation area. It contains a list of queues, the queue type, and the current queue depth. To display the Queue View, double-click a queue in the work area or click a queue in the navigation area or in the work area and select Properties from the Action menu or from the context menu. You can click the Refresh icon on the tool bar or select the Refresh option from the View menu to refresh the list of queues. To include system queues in the Queue List View, select Show System Objects from the View menu. 7.5.5 Queue View The Queue View is displayed when you click a queue in the navigation area. It contains a list of messages on the queue and includes the message type, put time, put date, and length. You can browse, move or copy a message to another queue, delete a message from the queue or save a message to a file. To display the Message View for a particular message, double-click a message in the list or click a message and select Properties from the Action menu or from the context menu. You can click the Refresh icon on the tool bar or select the Refresh option on the View menu to refresh the list of messages. NOTES: 1. The number and size of the messages on a queue affect the time required to display the Queue View. For example, the time required to display the Queue View for a queue that contains many large messages is longer than the time required to display the Queue View for a queue that contains a small number of messages. 2. The longest message that can be browsed, moved, copied, or deleted is determined by the limit set for the queue or the queue manager, whichever is lower. 7.5.5.1 Browse Message To browse a message, click a message and select Properties from the Action menu or from the context menu. You can also double-click a message to display the Message View. 7.5.5.2 Move Message To move one or more messages to another queue, click one or more messages from the list and select Cut from the Edit menu or from the context menu. Click the queue to which you want to move the messages and then select Paste from the Edit menu or from the context menu. To move a message to another queue, you can use the left mouse button to drag a message onto a different queue. NOTES: 1. If you move a message segment, ensure that you move all messages that belong to the same logical group. 2. Ensure that you move a message to the appropriate queue type, for example, from one transmission queue to another transmission queue. Although you can move a message from one queue type, such as a transmission queue, to a different queue type, such as a system queue, the results are unpredictable. 7.5.5.3 Copy Message To copy one or more messages, click one or more messages from the list and select Copy from the Edit menu or from the context menu. Then click the queue to which you want to copy the message and select Paste from the Edit menu or from the context menu. To copy a message, you can use the Ctrl key in combination with the left mouse button to drag the message onto a different queue. NOTES: 1. If you copy a message segment, ensure that you copy all messages that belong to the same logical group. 2. Ensure that you copy a message to the appropriate queue type, for example, from one transmission queue to another transmission queue. Although you can copy a message from one queue type, such as a transmission queue, to a different queue type, such as a system queue, the results are unpredictable. 7.5.5.4 Delete Message To delete one or more messages, click one or more messages from the list and select Delete Message from the Action menu or from the context menu. A confirmation dialog is displayed. 7.5.5.5 Filtering and Sorting You can filter and sort all views, with the exception of the Message Manager View. Click the title column header of any column and select Filter or Sort from the context menu. The Filter submenu has the following selections: Show Filter Row, Hide Filter Row, Edit Filter, Apply Filter, Unapply Filter and Clear All Filters. The Sort submenu has the following selections: Edit Sort, Sort Ascending, Sort Descending, Clear Sort, Clear All Sorts. Select Show Filter Row to display the filter row directory below the Title column header Select the filter row in any column to display the Edit Filter dialog in which you can enter the filter criteria. When a filter has been set, the apply/unapply bar is displayed below the filter row. The apply/unapply bar displays a line (apply) or a disconnected line (unapply). Click the apply/unapply bar to toggle between apply or unapply. Select Edit Sort to set the sort order for each column. You can also use the up and down arrows in the Title column header or the Sort Ascending or Sort Descending options from the context menu to sort the column in ascending or descending order. 7.5.6 Message View To display the Message View, double-click a message in the Queue View message list or click a message and then select Properties from the Action menu or from the context menu. The contents of the Message and Message Descriptor is displayed in a notebook style with the following tabs: General, Context, Identifiers, Segmentation, Report, and Message Data. The following list describes the tabs and their fields: General: Message Type, Message Priority, Message Persistence, Put Date, Put Time, Expiry Interval, Reply-To Queue, Reply-To Queue Manager, and Backout Count Context: User ID, Put-Application Type, Put-Application Name, Application Identity Data, Application Origin Data, Accounting Token Identifiers: Message ID, Correlation ID, Group ID (both Text, if displayable, and Hex fields are shown) Segmentation: Logical Sequence Number, Offset, Message Flags: Segmentation allowed, Message is a member of a group, Message is the last logical message in a group, Message is a segment of a logical message, Message is the last segment of a logical message Report: Options for Report Messages: Report, Positive action notification reports required, Negative action notification reports required, Confirm-on-arrival reports required, Confirm-on-delivery reports required, Expiration reports required, Exception reports required, Discard message on non-delivery; Feedback Code; Original Length Message Data: Message Length, Format, Coded Character Set ID, Encoding, and 32KB of the message data in Hexadecimal, or Text, if displayable. The following headers are also displayed individually as a tabbed notebook panel if one or more are found sequentially as the first items in the message data: Dead Letter Header: Structure Id, Structure Version Number, Reason Code, Original Destination Queue, Original Destination Queue Manager, Encoding, Coded Character Set Id, Format, Put Application Type, Put Application Name, Put Date, Put Time Transmission Queue Header: Structure id, Structure Version Number, Destination Queue, Destination Queue Manager Rules and Formatting Header: Structure ID, Structure Version Number, Structure Length, Encoding, Coded Character Set ID, Format, Flags; For Version 1: Name Value String For Version 2: CCSID for Name Value Data, Length of Name Value Data, Name Value Data 7.5.6.1 Save a message to a file To save a message to a file, double-click a message in the Queue View. Click the Message Data tab in the Message View, then click the Export Message Data button. On the Export Message Data dialog, navigate to the appropriate directory and type the name of the file in which you want to save the message. Then click Save. 7.5.6.2 Import data from a file into a message To import data from a file into a message, double-click a message in the Queue View. Click the Message Data tab in the Message View, then click the Import Message Data button. On the Import Message Data dialog, navigate to the appropriate directory and select the name of the file that contains the data you want to import into the message. Click Open. From the Message View, click Save message to queue and close. On the Retain dialog, click Yes if you want to keep the original message in addition to this message, or click No if you want to replace the original message with this message. 8 GETTING ASSISTANCE ================== Message Manager uses the User Assistant to display helpful information. The User Assistant is an online reference tool that provides information about the Message Manager window that is open and procedures that you can follow. The User Assistant tool bar provides icons that enable quick access to the following functions: - Previous Topic - Next Topic - Table of Contents - Topic Index - Message Index - Search - Print Topic 8.1 Opening the User Assistant To open the User Assistant, do one of the following: - Click the question mark in the upper right corner of a Message Manager window. - Select one of the following options from the Help menu: -- Open User Assistant Opens the User Assistant. If the User Assistant is already open, this option closes the User Assistant. -- Table of Contents Opens the User Assistant table of contents. -- Index Opens the User Assistant topic index. -- Search Opens the User Assistant Find function. - Press the F1 key. 8.2 Getting Assistance for Messages Message Manager console messages have the prefix CTQ followed by a message number. To get information about the message, click the Message Index icon in the User Assistant, then click the message number. 9 LOG FILES ========= An error log file, MM_message.log, and an audit trail file, MM_trace.log, are stored in the path set by the MM_LOG_PATH environment variable configured in the mm4wmq.sh and mm4wmq.cmd files. When you start Message Manager, the existing log files are renamed to .bak files. Only one backup file is kept for each log file. The MM_message.log contains error messages and exceptions. The MM_trace.log, to be used for problem determination with Customer Service, provides low-level trace information related to running Message Manager. 10 Known Problems ============== 1. UnsupportedEncodingException: Cp500 or Cp437, etc (Windows platform only) PROBLEM: This problem occurs when the Java i18n.jar file is not installed in the Java jre/lib directory. SOLUTION: The Windows JRE for "all languages" must be installed, and not the JRE "U.S. English only". 2. Unable to load message catalog - mqji PROBLEM: This problem occurs when the MA88 message catalog files are not located in the same directory as the MA88 jar files. In some versions of WebSphere MQ this may be the case. SOLUTION: Search for the "mqji.properties" file. Add the appropriate directory to the CLASSPATH, or edit the mm4wmq.sh (UNIX) or mm4wmq.cmd (WINDOWS) file as follows: where the mqji.properties file is found in c:\dir1\subdir2 mm4wmq.sh # ------------------------------------------------------------- # Add MA88 Path to path # ------------------------------------------------------------- CLASSPATH=$MM_JAVA_LIBRARY_PATH:$CLASSPATH CLASSPATH=c:\dir1\subdir2:$CLASSPATH mm4wmq.cmd rem ----------------------------------------------------------- rem Add MA88 Path to path rem ----------------------------------------------------------- set CLASSPATH=%MM_JAVA_LIBRARY_PATH%;%CLASSPATH% set CLSSSPATH=c:\dir1\subdir2;%CLASSPATH% 3. Cut function fails for zOs (OS/390) queue managers. PROBLEM: The Cut function fails for messages on zOs (OS/390) queue managers. WORKAROUND: Copy/Paste message to target queue and then delete original message from source queue. 4. Drag and Drop not functional in Java 1.4.x. PROBLEM: Drag and drop does now work in Java 1.4.x due to change between Java 1.3.x and Java 1.4 of drag and drop function. WORKAROUND: Use Cut/Copy and Paste