# (C) COPYRIGHT International Business Machines Corp., 2007, 2012
# All Rights Reserved * Licensed Materials - Property of IBM

-----------------------------------------------------------------------------
IBM Support Assistant Data Collector Tool
-----------------------------------------------------------------------------

Description
-----------------------------------------------------------------------------

The IBM Support Assistant Data Collector (ISADC) Tool provides automatic data 
collection for IBM products. The tool is pre-configured to locate important 
diagnostic data on your computer system and copy it into a Collector file. An 
example of diagnostic data is a log file generated by your IBM product that 
contains a detailed history of events occurring during product operation. Such 
a file can be useful in determining the nature and cause of a software problem. 
Other examples of diagnostic data include initialization files, configuration 
files, operating system version, disk space, and network connections.The tool 
can be run in GUI mode or in a command-line console mode. The console mode 
provides you with command-line control of the IBM Support Assistant Data 
Collector collection scripts.  The tool includes several features to assist 
you when you interact with it in console mode, including one that lets you 
record your responses from a console-mode session in a file and then use the 
file to drive subsequent executions of the same collection script.  

Tool Installation and Usage
-----------------------------------------------------------------------------
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.	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 GUI mode or the command-line console mode.  
 - Follow the procedure described below for setting the JAVA_HOME environment 
   variable. Once you have done this, you can then execute the launch script.
 - Once you have started the tool, follow the instructions below for 
   interacting with it as it performs a collection.

Installing the Tool
-----------------------------------------------------------------------------
In all cases, installation of the IBM Support Assistant Data Collector tool is 
simply a matter of extracting the files from the archived .zip file or
tar.gz file. The files can be extracted to any file system location you 
choose on the system where you will be running the tool. This will create a 
sub-directory isadc under your target directory.


Tool Usage
-----------------------------------------------------------------------------
Setting the JAVA_HOME Environment Variable

The IBM Support Assistant Data Collector tool can run in GUI mode or in 
command-line console mode. For command-line mode, 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, it is necessary that 
Java can be located before the command-line tool can start. If Java is not 
available on the PATH, you will have to set the JAVA_HOME environment variable 
manually. The IBM Support Assistant Data Collector tool requires a JRE at the 
level 1.5 or higher, so you must first make sure that a suitable JRE is 
installed on the system where the tool will be running. If it is, then you will 
need to issue an operating-system-specific command to set the JAVA_HOME 
variable to point to this JRE. The Microsoft JVM/JDK and gij (GNU libgcj) are 
not supported. 

For example, if on a Windows platform you have jre1.5 installed at
c:\jre1.5, you would set JAVA_HOME using the following command:

SET JAVA_HOME=c:\jre1.5

NOTE: Do not use quotes in the value of the SET command, even if your value has 
whitespace characters.

On a Linux, AIX, or Solaris, if you have the JRE installed in
/opt/jre15, you would set JAVA_HOME using the following command:

export JAVA_HOME=/opt/jre15


Starting the Tool in Web GUI Mode
-----------------------------------------------------------------------------
For Web GUI mode, open the index.html file located in the isadc sub-directory 
into your favorite web browser.The tool has been tested with Firefox (3.6 and
higher), and Internet Explorer (v8 and higher).


Starting the Tool in Command-Line Console Mode
-----------------------------------------------------------------------------
If a GUI is not available, the tool should be started in command line mode. 
Simply execute the launch script from the command line (isadc/isadc.bat or 
isadc/isadc.sh).

The following command line options are available for ISADC

isadc [-outfilezip <file> [-force]] [-useHome] 
      [-silent <file> | -record <file>] [-promptForProxy]

 -force              force overwrite of collection output zip file
 -outputzip <file>   zip file to write collection results to
 -promptForProxy     prompt for proxy configuration
 -record <file>      write collection responses to file specified
 -silent <file>      execute collection in silent mode and read responses
                     from the file specified
 -useHome            write collection meta-data to user home directory

Files are written to the installation directory
-----------------------------------------------------------------------------
By default, the ISADC installation directory is used for storing files created 
during execution.  On some systems, the ISADC installation directory will be 
read only.  In this instance, use the -useHome parameter (console mode only). 
This parameter will cause temporary files to be written to the systems 
temporary directory and persistent files written to the user home directory.

NOTE: After extracting the install .zip/.tar.gz file,  the user which extracted 
the file must run a collection before any other user attempts to run a 
collection using the -useHome parameter.  Doing so will ensure proper setup has 
been done prior to execution by any other non admin/root user.   
	
Interacting with the Tool
-----------------------------------------------------------------------------
Once the IBM Support Assistant Data Collector tool has been started in a web 
browser, 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 
from the main window. With the problem type selected the next step is to press 
the Start button. As it proceeds, the collection script will ask you for any 
additional information it needs to complete its collection activities. A script 
may also ask you for configuration information, for information about the 
sequence of events leading up to the problem you are dealing with, or for your 
preferences regarding how it should complete the collection. Once it has all 
the information it needs, the script will proceed with the remainder of the 
collection.

When the tool completes the data collection, you can send the results to IBM 
Support. You can choose between FTP, which is not encrypted and HTTPS, which is 
encrypted, for the file transfer. The name of the zip file the tool sends to 
IBM Support will be displayed in the collection status area.

When IBM Support Assistant Data Collector runs in text mode, there are no 
selection lists or entry fields for user input. Instead, available choices are 
presented as numbered lists and you enter the number of your selection followed 
by the Enter key. Input fields are transformed into prompts, at which you enter 
your response and press Enter. When the data collection is complete, the output 
is another ZIP file.  The output ZIP file can be sent to IBM Support or 
examined locally.

To stop the collector tool, type the quit option in text mode, or close the 
browser window in GUI mode.

The tool will prompt for file names. On Unix platforms, using "~" as a 
designation of the user's HOME directory is not supported.  If a "~" is used, a 
sub-directory under the present working directory by the name of "~" will be 
referenced.


Determining version information
-----------------------------------------------------------------------------
By default, the version of the tool (and its various sub-components) is printed 
to the console from which it was launched.  When running in GUI mode, version 
information can also be found using the Help->About menu option. If Java is not 
available, or the Java application is unable to start, you can also get the 
version of the tool by running the launch scripts with the "-version" option.

*NOTE: When using the "-version" option, the launch scripts will print out the 
version information without actually invoking the tool.

Viewing Inventory file
-----------------------------------------------------------------------------
The tool can collect inventory information of the current system.  Inventory 
information is automatically placed in the collection ZIP file if available. 
The output is an inventory file (isadc/inventory/inventory_rcf.xml), that is 
best viewed with a web browser.

Known Issues
-----------------------------------------------------------------------------
The installation of IBM Support Assistant Data Collector should not be done 
into a directory that includes white space characters including spaces on 
Solaris platforms.

The installation of IBM Support Assistant Data Collector should not be done 
into a directory that includes period '.' characters on Windows platforms.

Stand alone (or file:// protocol) execution of the IBM Support Assistant 
Data Collector is not supported for Chrome browsers. Support for collections
using Chrome is only supported in hosted or http:// mode. 