IBM® Support Assistant Lite Tool for WebSphere InterChange Server Quick Start Guide ----------------- Introduction ------------ The IBM® Support Assistant Lite for WebSphere® InterChange Server tool is provided as an aid for troubleshooting IBM WebSphere InterChange Server and other IBM software products. The tool focuses on automatic collection of problem data for the various categories of problems encountered by IBM software products. Information pertinent to a type of problem is collected and analyzed to help identify the origin of the problem under investigation. The tool assists customers by reducing the amount of time it takes to collect and send the appropriate logs and other supporting files to IBM Support. In this quick start guide, we tell you how to get up and running with the IBM Support Assistant Lite for WebSphere InterChange Server. Step-by-Step ------------ In most cases, the following sequence of steps will get you up and running with the tool. If you run into problems, or if you would like more information on any of these steps, you can refer to the sections below that follow this one. 1. Install the tool by extracting the files from the archive file that you downloaded. Extract the tool to any directory you choose. See the sections below for details of how to perform the extractions. 2. Run the tool in either the Swing GUI mode or the command-line console mode. 3. Once you have started the tool, follow the instructions below for interacting with it as it performs a collection. Tool Installation ----------------- Installing the Tool ------------------- In all cases, installation of the IBM Support Assistant Lite tool is simply a matter of extracting the files from the archive that you downloaded. The files can be extracted to any file system location you choose on the system where you will be running the tool. Extraction on Windows® ------------------------ Once you have downloaded the ISALiteForWICS_Win.zip archive, you can use any zip utility to unzip it to your chosen target directory. The operation will create a subdirectory \ISALite in this target directory. Extraction on Linux®, AIX®, HP-UX®, and Solaris® ------------------------------------------------ Once you have chosen the target directory where you want to install the tool, you can use the following procedure to install it. 1. Download the ISALiteForWICS_Unix.tar file to the target directory you chose. 2. Navigate to this directory and issue the command tar –xvf ISALiteForWICS_Unix.tar.gz to extract the .tar file. 3. This will create a subdirectory /ISALite under your target directory. Tool Usage ---------- Setting the JAVA_HOME Environment Variable ------------------------------------------ Regardless of whether you will be using the IBM Support Assistant Lite tool in Swing GUI mode or in command-line console mode, you use the same procedure to start it: you invoke the appropriate launch script from a command line. In the case of a Windows system, these launch scripts are batch files. For the other environments, they are shell scripts. Since the tool is implemented as a Java application, the IBM Support Assistant Lite tool requires a JRE at the level 1.4.2 or higher, you must first make sure that a suitable JRE is installed on the system where the tool will be running. The tool will try to automatically locate the path to your Java by searching the PATH and CLASSPATH environmental variables and assign it to JAVA_HOME automatically. But in cases, it is unable to find then the tool will error out but indicate that it’s unable to find the Java. In such cases it is necessary to set the JAVA_HOME environment variable before the tool can start. You will need to issue an operating-system-specific command to set the JAVA_HOME variable to point to your installed JRE. For example, if you have jdk1.4.2 installed at c:\jre1.4.2 on a Windows platform, you would set JAVA_HOME using the following command: SET JAVA_HOME=c:\jre1.4.2 On a Linux, AIX, HP-UX, or Solaris platform, the exact command syntax to set JAVA_HOME varies depending on which shell you are using. For example, if you are using bash shell and you have the JDK installed in /opt/jre142, you would set JAVA_HOME using the following command: export JAVA_HOME=/opt/jre142 Starting the Tool in Swing GUI Mode ----------------------------------- ISALite in Swing GUI mode can be started by issuing the correct launch script: • For the Windows environment, it will be the runISALite.bat script in the tool's \ISALite directory. • For the Linux, AIX, HP-UX, and Solaris environments, it will be the runISALite.sh script in the tool's /ISALite directory. Starting the Tool in Command-Line Console Mode ---------------------------------------------- ISALite in command -line console mode can be started by issuing the correct launch script: • For the Windows environment, it will be the runISALiteConsole.bat script in the tool's \ISALite directory. • For the Linux, AIX, HP-UX, and Solaris environments, it will be the runISALiteConsole.sh script in the tool's /ISALite directory. Interacting with the Tool in Swing GUI Mode --------------------------------------------- Once the IBM Support Assistant Lite for WebSphere InterChange Server tool has been started in swing GUI mode, the graphical interface will be displayed. Before the tool can be used to perform data collection and analysis, you must first select a problem type in the Problem Type window. In the initial view, the tree is collapsed to show only its top-level folders. You can expand the top-level folders to reveal the folders nested below them. Continue expanding folders until the problem type you want is revealed, then highlight it. Other than Problem Type, the only input field value that you must supply on the main GUI is a filename for the data collection zip file. At this point, the filename can be anything you want: you might, for example, use the filename Install_failed_2007_01_03. If you do not supply it, the tool will automatically append the “zip” extension to it. If you have a PMR open for the problem you're performing the collection for, however, and if you'll be letting the tool FTP the collection results in to IBM Support automatically, then at the FTP step the tool will enforce a specific file-naming convention required by IBM Support: The file name must begin with three specific fields: ....zip. An example of a filename of this type would be 2345.345.000.Genral.zip. For compatibility with a previous format, commas are also accepted in place of the first three periods (but not in place of the fourth one prior to the “zip” extension). However, periods are the preferred delimiter. Figure 3 shows the tool with the Problem Type highlighted and the Output Filename/Path field filled in. With these values filled in the next step is to press the Collect Data button. As it proceeds with collecting the data for the first time the ISALite for WebSphere InterChange Server will prompt you with a dialog box requesting information regarding the Server and other related products. The details requested are: -------------------------- Values Requested Type ----------------- ----- 1. WebSphere InterChange Server root directory..........Required 2. WebSphere InterChange Server Logs directory..........Required 3. WebSphere MQ root directory..........................Optional 4. WebSphere InterChange Server ORB trace directory.....Optional 5. WebSphere InterChange Server Heap dumps directory....Optional 6. Preference for Archive logs collection (7 latest files will be collected)....................Yes Default 7. Archive logs directory...............................Required if Yes to 6 8. Preference to send collected files to IBM automatically each time?.............................Yes Default 9. Preference to collect Repository file from running server.............................Yes Default 10. WebSphere InterChange Server Name....................Required if Yes to 9 11. WebSphere InterChange Server User Name...............Required if Yes to 9 12. Output file name for the collected repository........Required if Yes to 9 Once ISALite has got all the information it will create a configuration file called ISALite_WICS_Config.xml: • In Windows under \ISALite\properties\SSBTEG • In AIX, Linux, HP-UX environments /ISALite/properties/SSBTEG This configuration XML file will be used for further collections. Hence there will be no further prompts for input. However, ISALite will prompt you for inputs during collection only under 2 circumstances 1. The required files for a particular collection scenario are not present in the specified location. 2. The repository collection always prompts you to enter the password for the WebSphere InterChange Server user specified in the configuration. When the tool completes the data collection operations, it can FTP the results to IBM Support. The name of the zip file the tool sends to IBM Support via FTP will be the filename entered in the Output Filename/Path box, with the server hostname and current timestamp appended to it. Example: if the Output Filename/Path filename used was 12345.345.000.GeneralCollection.zip, the name of the zip file sent to IBM would be 12345.345.000.GeneralCollection.zip -.zip Interacting with the Tool in Command-Line Console Mode ------------------------------------------------------ The console mode provides you with command-line control of the IBM Support Assistant Lite tool’s collection scripts. The tool includes the same features as Swing GUI mode, when you interact with it in console mode. Once the IBM Support Assistant Lite for WebSphere InterChange Server tool has been started in console mode, the tool will start in a text based mode. Before the tool can be used to perform data collection and analysis, you must specify an output filename for the collection. The name of the file can be anything you want: you might, for example, use the filename Install_failed_2007_01_03. If you do not supply it, the tool will automatically append the “zip” extension to it. If you have a PMR open for the problem you're performing the collection for, however, and if you'll be letting the tool FTP the collection results in to IBM Support automatically, then at the FTP step the tool will enforce a specific file-naming convention required by IBM Support: The file name must begin with three specific fields: ....zip. An example of a filename of this type would be 12345.555.000.logs.zip. For compatibility with a previous format, commas are also accepted in place of the first three periods (but not in place of the fourth one prior to the “zip” extension). However, periods are the preferred delimiter. Figure 5 shows the tool with the Output Filename/Path field filled in. At the next step you must enter the Problem Type name or associated number. You can expand the top-level collection options to reveal the options nested below them. Continue expanding the given options until the problem type you want is revealed, then enter the number of the option. Once you enter your option the ISALite data collection will begin. If you are starting the ISALite for the first time in either the Console mode or Swing GUI mode it will prompt you to enter the configuration parameters for the collection. In Swing mode you will be seeing a pop of dialog box but in Console mode you will be prompted to enter values one by one. Default values will be highlighted in between <> brackets. The details requested are: -------------------------- Values Requested Type ----------------- ----- 1. WebSphere InterChange Server root directory..........Required 2. WebSphere InterChange Server Logs directory..........Required 3. WebSphere MQ root directory..........................Optional 4. WebSphere InterChange Server ORB trace directory.....Optional 5. WebSphere InterChange Server Heap dumps directory....Optional 6. Preference for Archive logs collection (7 latest files will be collected)....................Yes Default 7. Archive logs directory...............................Required if Yes to 6 8. Preference to send collected files to IBM automatically each time?.............................Yes Default 9. Preference to collect Repository file from running server.............................Yes Default 10. WebSphere InterChange Server Name....................Required if Yes to 9 11. WebSphere InterChange Server User Name...............Required if Yes to 9 12. Output file name for the collected repository........Required if Yes to 9 Once ISALite has got all the information it will create a configuration file called ISALite_WICS_Config.xml: • In Windows under \ISALite\properties\SSBTEG • In AIX, Linux, HP-UX environments /ISALite/properties/SSBTEG. This configuration XML file will be used for further collections. Hence there will be no further prompts for input. However, ISALite will prompt you for inputs during collection only under 2 circumstances 1. The required files for a particular collection scenario are not present in the specified location. 2. The repository collection always prompts you to enter the password for the WebSphere InterChange Server user specified in the configuration. When the tool completes the data collection operations, it can FTP the results to IBM Support. The name of the zip file the tool sends to IBM Support via FTP will be the filename entered in the Output Filename/Path box, with the server hostname and current timestamp appended to it. Example: if the Output Filename/Path filename used was 12345.555.000.logs.zip, the name of the zip file sent to IBM would be 12345.555.000.logs.zip --.zip. Reference for the Collection Types ---------------------------------- Details for each WebSphere InterChange Server data collection type can be found in their corresponding Technotes: Collection Types Technotes -------------------------- General Problem: ---------------- http://www.ibm.com/support/docview.wss?uid=swg21378394 Hang Problem: -------------- http://www.ibm.com/support/docview.wss?uid=swg21379996 Out-Of-Memory Problem: ---------------------- http://www.ibm.com/support/docview.wss?uid=swg21380001 ORB Problem: ------------ http://www.ibm.com/support/docview.wss?uid=swg21380003 Edit Data Collection Settings: ------------------------------ http://www.ibm.com/support/docview.wss?uid=swg21378374 Validation of the Collection Zip File Name ------------------------------------------- The automation at the IBM Support FTP site ftp.ecurep.ibm.com is entirely dependent on the file naming convention described on the IBM Support Assistant Lite tool’s main GUI. If it receives a file with a name that doesn’t follow this convention, then that file is never seen by IBM Support. Consequently, before the tool invokes an FTP operation to send a collection zip file to ftp.ecurep.ibm.com, it validates the collection zip file’s name against the convention. If the file name isn’t in the correct form, you will be presented with a pop-up window so that you can correct the file name. The current file naming convention for the FTP site is the one documented here, where the individual fields in the composite file name are separated by periods. Previously, however, the convention was to use commas as the separators. Since the FTP site still handles files named according to the previous convention, the IBM Support Assistant Lite tool’s validation logic accepts both periods and commas as delimiters. Trademarks ---------- The following terms are trademarks of the IBM Corporation in the United States or other countries or both: AIX IBM The IBM logo WebSphere Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. HP-UX is a registered trademark of Hewlett-Packard Company. Other company, product, or service names may be trademarks or service marks of others.