Tools

This page contains:

	» Overview
	» Getting started with scansummary
	» Refining the scansummary report
	» Locating impacts using scandetail
	» Refining the scandetail report
	» Scanning unrecognized file types
	» See also

• scanwizard is a command line-based interactive tool which acts as a front-end for scansummary and scandetail and helps you choose the most useful options for scanning your source code.
• scansummary reports the number of instances of API impacts and a brief description of each impact identified in your source files. scansummary helps you understand the magnitude of your application transition, and indicates potential problems you will need to resolve.
• scandetail reports the file name, line number, and a brief description of each API impact identified in your source files. scandetail lets you pinpoint each impact in your source files.

The STK filescanner commands are installed in the directory /opt/STK/bin/.  Add this directory to your PATH environment variable or use this this path prefix when running the scanwizard, scansummary, or scandetail commands.

The STK client configuration file /etc/opt/STK/config/client) contains options that control how a file is recognized based on file name, file extension, and interpreter name (#! line in scripts).

By default, the file scanners recognize the following file types and apply a ruleset to search for specific language constructs:

Within these source files, the file scanners can help you locate any changed or obsolete:

• functions, subroutines (Fortran), or callables (COBOL)
• commands
• path names
• macros
• structures and structure members
• header files
• language keywords and compiler directives
• libraries
• variables and specifiers (Fortran)

The file scanners can also identify opportunities for using enhanced features of HP-UX.

As shown in the figure below, the file scanners generate reports that provide links to detailed impact pages describing each impact and its solution. The impact pages in turn link to impact classification overviews and manual reference pages, which provide additional background information.

To scan your files with scansummary:

1. If you want to keep all your reports in one directory, designate a directory for the output report files that are created when you run scansummary and set an environment variable to point to this directory.
2. Create a summary report. Type:

   scansummary -s class -p $INV_DIR/stk.investigation \
   source_files
   

   You can list multiple individual files for source_files. Wildcards (*) are also accepted. The output of this scan is saved in $INV_DIR/stk.investigation_summary.html (as specified by the -p option), and is sorted by impact classification (as specified by the -s option).

To refine the scansummary output report by filtering any unnecessary information:

1. Examine your scansummary output report. For help in understanding the report, see Interpreting the Output Reports.
2. Click the link for each impact in the report to view the HTML pages explaining the impact and its solution.
3. Determine if you can exclude any impacts that are not applicable to your source base. If you can, perform the scan again filtering out the impacts.
4. After eliminating the irrelevant classifications and impacts, scan your source files again, without the -s class option, to see the total number of impacts:

   scansummary -p $INV_DIR/stk.investigation \
   source_files
   

The most generic form of scandetail is:

scandetail source_file

You can list multiple files. Wildcards (*) are also accepted. For example:

scandetail one_file.cc one_header.hh another_file.cc

scandetail *.cc

scandetail *.cc *.hh Make*

By default, the file scanners, scandetail and scansummary, report every instance of all identifier types and impact classifications, severities, and types. You can filter this output by:

• using command line options as described in scandetail(1)
• modifying the .scanrc file as described in Customizing Your Scan

For example, there are options that allow you to:

• include or exclude classifications of impacts that are not relevant (+C, -C)
• specify the operating system version you are porting from (-O)
• include or exclude impact severities (+S, -S)
• include or exclude impact types (+T, -T)
• include or exclude selected identifier types (+Y, -Y)
• include or exclude a particular impact (+I, -I)

When specifying options, either on the command line or in the .scanrc file, use:

• a minus sign to exclude one or more items from all possible types, classifications, and severities
• a plus sign to include only the types, classifications, and severities that you specify.

For example, to run a detailed scan on all your .cc files and identify only critical, obsolete impacts from HP-UX version 11.00 to the most recent release, type:

• scandetail +S Cr +T Ob -O 11.00 *.cc

A file can be scanned only if it:

• is a regular file (not a directory, device file, or binary).
• can be opened and read (that is, the file exists, is not empty, and has read permission)
• is not an executable (that is, the file does not have the magic number of an executable)

Files that do not match the criteria described in the overview are scanned using a more general ruleset. These more general rules ensure that the file scanners do not miss important impacts.

When the file type is unknown, over-reporting frequently occurs because the file scanners report impacts for any word that matches the name of an identifier in the file scanner database. To solve this problem, specify the file type by doing one of the following:

• For scripts, include #!script_language_path as the first line of the file. For example, for a Perl script, assuming that Perl is located at /usr/bin/perl, include #!/usr/bin/perl at the top of the script.
• Modify the STK client configuration file so that the file scanners recognize the file. The STK client configuration file has several options that control how a file is recognized based on its name, extension and #! line. For example, if you use .perl as an extension to identify your Perl scripts, you can add .perl to the variable SCRIPT_EXTENSIONS. If the extensions you designate are listed on other *_EXTENSIONS lines that are not relevant to your situation, you should remove them.

To exclude files of unknown type, use the -u option. For more information, see the -u option in scandetail(1).