Outputs from scans and formats

When you a run a scan, IBM® Prerequisite Scanner produces output for the following console and human-readable file formats: output to the command window, informational and debugging log files, and text and XML files for the results.

Prerequisite Scanner saves the scan results and log file to the ips_output_dir directory. You can set this directory by using the outputDir input parameter when you run the tool. If you do not set this parameter, the default output location is ips_root.

Note: Prerequisite Scanner creates temporary files during its execution, but these files are deleted before the tool completes its execution. These temporary files are in the ips_output_dir/temp subdirectory. The tool also deletes the ips_output_dir/temp subdirectory, unless the subdirectory contains the debug files that are generated on UNIX systems only.

You can also use the parameter to specify a location, if you choose to run Prerequisite Scanner from a mounted CD, DVD, or read-only file system and network drive.

Important: If the output directory does not exist, Prerequisite Scanner creates the directory. You must have write permissions to create or write to the output directory in which Prerequisite Scanner saves the files.

Command line output

When you run the Prerequisite Scanner script, you can set the optional detail parameter and its optional -s option. It indicates the detail level of the results in the command window. If you do not set the detail parameter, the tool displays only the PASS, WARNING, or FAIL result in the command window.

Figure 1. Running the script without setting the detail parameter on Windows systems

Prerequisite Scanner also saves the detailed results to the ips_output_dir/result.txt file regardless of whether you set the detail parameter.

Note: The tool also saves the detailed results to the XML file if you specify the optional configHomeDir parameter.

Prerequisite Scanner generates returns codes dependent on the results of the scan and whether it must exit because of errors. These return codes are written to the log files and the error return codes are also displayed in the command window. For example, if the Prerequisite Scanner fails to run the scan because it cannot read the configuration file, it generates a return code of 2. If the overall result of the scan is WARNING, it generates a return code of 3.

When you set the detail parameter without the -s option, the detailed results contain:

The version of Prerequisite Scanner
The version of the operating system on which the tool was run
The type of scan and scenario
- Prerequisite scans: Scenario: Prerequisite Scan
The name of the products or components for which the prerequisite or health checks were run
For each prerequisite property: the name of the property that is checked, the PASS, WARN, or FAIL result, the actual value, and expected value
For all components: the name of the general property that is checked, the PASS, WARN, or FAIL result, the actual value, and the expected value
The overall PASS, WARNING, or FAIL result, with the overall scan results of every scanned product and component that is specified as a comma-separated list within () brackets
Note: Any failure of an individual check results in the failure of the overall scan. Any warning for an individual check results in a warning result for the overall scan.
Any WARNING or ERROR messages that occur while you run the scan
An information message that specifies the environment variables associated with section evaluation in the configuration files of the scanned products or components:
Environment Variable Settings: [Environment_Variable_Name=Environment_Variable_Value,Environment_Variable_Name=Environment_Variable_Value, ...]
- Environment_Variable_Name is the name of the environment variable.
- Environment_Variable_Value is the value that was set for the environment variable, or [Not found] if no value was set.

Figure 2. Running the script and setting the detail parameter on UNIX systems

When you set the detail parameter with the -s option, the shortened results contain:

For any check that fails: the name of the prerequisite property that is checked, the FAIL result, the actual value, and expected value
For any check that has a warning severity: the name of the prerequisite property that is checked, the WARN result, the actual value, and expected value
The overall PASS, WARNING, or FAIL result, with the overall scan results of every scanned product and component that is specified as a comma-separated list within () brackets
Note: Any failure of an individual check results in the failure of the overall scan. Any warning for an individual check results in a warning result for the overall scan.

Aggregating memory and disk space prerequisite properties

You can run Prerequisite Scanner to simultaneously check for the prerequisites of one or many products or components, when you specify multiple product codes as input parameters. Prerequisite Scanner aggregates the results of memory and disk space prerequisite checks in the Aggregated Properties for Scanned Products section of the output, if the associated prerequisite properties were specified in any of the configuration files.

The general prerequisite properties are as follows:

Total amount of physical memory that is available in the target environment, that is:
Memory
Disk space of the file systems for the following prerequisite properties:
Platform Prerequisite properties
UNIX and Linux
os.space.home

os.space.opt

os.space.tmp

os.space.usr

os.space.var
Windows Disk

Platform	Prerequisite properties
UNIX and Linux	`os.space.home` `os.space.opt` `os.space.tmp` `os.space.usr` `os.space.var`
Windows	`Disk`

Note: If opt, usr, and var were not defined as file systems on the target computer, Prerequisite Scanner does not display the expected values and returned results for these prerequisite properties in the collated section.

These prerequisite properties support the expected value range, which represents the minimum expected value for the prerequisite property, minimum_property_value, and the recommended expected value, recommended_property_value. If any of these prerequisite properties have an expected value range in the configuration files, Prerequisite Scanner handles the aggregation of the expected value ranges and single property values as follows:

Calculates the aggregated minimum property value, represented by aggregated_minimum_property_value, by adding minimum property values and single property values together:
```
aggregated_minimum_property_value = minimum_property_value + minimum_property_value_n + property_value + property_value_n
```
Calculates the aggregated recommended property value, represented by aggregated_recommended_property_value, by adding recommended property values and single property values together:
```
aggregated_recommended_property_value = recommended_property_value + minimum_property_value_n + property_value +property_value_n
```
Compares and evaluates the actual value with the aggregated expected value range by using the severity checking mechanism, which sets a different severity level and returns a different result depending on whether the actual value is below, within, or above the specified aggregated range as follows
Actual value < aggregated_minimum_property_value

When the actual value is less than the aggregated minimum expected value, the implicit severity level is FAIL. The scan returns a FAIL result.

(Actual value >= aggregated_minimum_property_value) AND (Actual value < aggregated_recommended_property_value)

When the actual value is equal to or greater than the aggregated minimum expected value and is less than the aggregated recommended expected value, the implicit severity level is WARN. The scan returns a WARN result.

Actual value >= aggregated_recommended_property_value

When the actual value is greater than or equal to the aggregated recommended expected value, the scan returns a PASS result.

Prerequisite Scanner does not display the aggregated section, if memory or disk space prerequisite properties do not exist in the configuration files.

Prerequisite Scanner handles the comparison and display of disk space values in the aggregated section of the scan results differently from the main section. See Units of measurement in output.

Debugging log file output on Windows systems

Prerequisite Scanner outputs processing information, warning and error messages, and the scan results in the ips_output_dir/precheck.log file. When you run the Prerequisite Scanner script and set the optional debug parameter, Prerequisite Scanner outputs additional debugging messages in this file.

Figure 3. precheck.log file

Debugging log file output on UNIX systems

When you run the Prerequisite Scanner script and set the optional debug parameter, Prerequisite Scanner outputs detailed processing and debugging information and the scan results in the ips_output_dir/precheck.log file. It also outputs informational, warning, and error messages to the file.

If you do not set the optional parameter, Prerequisite Scanner outputs the scan results, informational, warning, and errors messages in the ips_output_dir/precheck.log file by default.

Attention: Before Prerequisite Scanner Version 1.2.0.1, the tool logged the debugging information in the ips_output_dir/temp/prs.debug file. This file is now deprecated, with the contents logged to the precheck.log file

Figure 4. precheck.log on UNIX systems

Attention: Before Prerequisite Scanner Version 1.2.0.1, Prerequisite Scanner supported an optional trace parameter that logged the trace information in the ips_output_dir/temp/prs.trc file. The input parameter and trace file are deprecated. If you specify the trace parameter in the command window, a warning message is displayed.

Text file output

Prerequisite Scanner outputs detailed scan results in the ips_output_dir/result.txt file. It saves the results to the text file regardless of whether you set the detail parameter.

Figure 5. result.txt file on Windows systems

Figure 6. result.txt file on UNIX systems

XML file output

Prerequisite Scanner outputs detailed scan results in the ips_output_dir/result.xml file when you specify the optional xmlResult input parameter. You can use it to indicate to the tool to output the results to the XML result file in addition to the plain text result file. It saves the results to the XML file regardless of whether you set the detail parameter.

Figure 7. result.XML file on Windows systems

Developers can use the Prerequisite Scanner API to parse and read the XML file.