Tools

Advanced use of scandetail and scansummary

This document explains how to use the file scanners for maximum efficiency and effectiveness during the source code transition process, including:

	» Excluding classifications, types, severities, and identifiers of impacts
	» Changing the location of the output reports
	» Examples
	» See also

Excluding classifications, types, severities, and identifiers of impacts

Impacts are categorized by classification, type, and severity. For more information, see Filtering Options in scandetail(1).

During any source code transition process, you can narrow the results of your scans by excluding classifications, types, severities, and identifiers that are not relevant to your situation. You can put these options, and any other options that you want to apply to all scans, into your $HOME/.scanrc file.

Depending on your source base, you may want to include or exclude certain identifiers.

Changing the location of the output reports

Each time you run a file scanner, it produces an output report. By default, this output report is written in the current working directory, overwriting any existing report using the same (default) name. However, you can specify the file path and base name of the output report with the -p prefix option. This option specifies a prefix that replaces stk in the default output file name (stk_detail.html or stk_summary.html).

Depending on your scanning scenario, you may want to have the output report(s) written to different locations:

• When you are investigating the scope of your transition, you typically perform a single global scan. The output report should be written into either the current working directory or a directory where you are collecting output reports.
• When you are scanning individual files for transition impacts, you may perform multiple scans across directories. Multiple output reports could be grouped in a single directory.

Examples

This section contains examples showing the use of the file scanners during each phase of a source code transition.

investigating the scope of your transition

The goal of scanning during the investigation process is to scan the entire source base in a single scan to collect global statistics about any areas that have potential source code transition problems.

You may want to create a directory in which to save the investigation output report(s). For example, in the POSIX shell (sh):

export INV_DIR=$HOME/stkinv

Example 1: Scan a source base contained in two directory trees.

scansummary -p $INV_DIR/src_base_name \
-r root1 -r root2

Where:

• -p option saves the output in an HTML file named $INV_DIR/src_base_name_summary.html
• -r options specify root directories to scan recursively.

Example 2: Perform two scans to separate investigating critical problems from non-critical problems. Scan a C source base that is to be ported to HP-UX 11.x 32-bit only.

First, scan for Critical severity problems:

scansummary -p $INV_DIR/src_base_name.crit \
-C CBL4,F90 -C 64,32,IPF +S Cr -T En \
-r root1 -r root2

Where:

• -p option saves the output in an HTML file named $INV_DIR/src_base_name.crit_summary.html
• -C CBL4,F90 option excludes all language classification impacts except the C language
• -C 64,32,IPF option excludes all classifications related to 64-bit or IPF
• +S Cr option includes only Critical severity impacts
• -T En option excludes Enhancement impacts
• -r options specify root directories to scan recursively
• The output report is saved in a single file so that it is easy to make global edits and to analyze critical problems

Second, scan for Non-critical severity problems:

scansummary -p $INV_DIR/src_base_name.non.crit \
-C CBL4,F90 -C 64,32,IPF +S Nc -T En \
-r root1 -r root2

Where:

• -p option saves the output in an HTML file named $INV_DIR/src_base_name.non.crit_summary.html
• -C CBL4,F90 option excludes all language classification impacts except the C language
• -C 64,32,IPF option excludes all classifications related to 64-bit or IPF
• +S Nc option includes only Non-critical severity impacts
• -T En option excludes Enhancement impacts
• -r options specify root directories to scan recursively
• The output report is saved in a single file so that it is easy to make global edits and to analyze non-critical problems

Example 3: Scan an HP-UX 11.00 source base using a list of files, and sort impacts by classification:

scansummary -p $INV_DIR/src_base_name.class \
-s class -O 11.00 -f filelist

Where:

• -p option saves the output in an HTML file named $INV_DIR/src_base_name.class_summary.html
• -s class option sorts by impact classification
• -O 11.00 option specifies the HP-UX release to transition from
• -f option specifies a file containing a list of source files to scan (one per line)

qualifying source code

The goal of scanning during the qualification process is to scan an application's source base to determine whether there are binary compatibility problems. Create a directory to save the qualification output reports in. For example, in the POSIX shell (sh):

export QUAL_DIR=$HOME/stkqual

Example 1: Scan a C application source base contained in two directories.

scansummary -p $QUAL_DIR/application_name \
-T En +C BI app_dir1/*akef* app_dir2/*akef* \
app_dir1/*{.h,.c} app_dir2/*{.h,.c}

Where:

• -p option saves the output in an HTML file named $QUAL_DIR/application_name_summary.html.
• -T En option excludes Enhancement impacts
• +C BI option includes only Binary Compatibility impacts
• app_dir1/*akef* and appdir2/*akef* specify the Makefiles in the two source directories
• app_dir1/*{.h,.c} and app_dir2/*{.h,.c} specify the C include and C source files in the two source directories

porting source code

The goal of scanning during the porting process is to scan an application's or library's source base directory by directory to collect detailed information about impacts and where they occur in the source files. You may want to exclude some classifications and types to minimize irrelevant impacts.

Create a directory to save the planning output reports in. For example, in the POSIX shell (sh):

export PLAN_DIR=$HOME/stkplan

Example 1: A non-threaded C++ application has two directories in its source base. Scan the source base directory by directory.

cd dir1_name
scandetail -T En,Ns -C CBL4,F90 -C TH *.H *.C

Where:

• -T En,Ns option excludes Enhancement and Non-standard impact types
• -C CBL4,F90 option excludes all language classification impacts except C/C++
• -C TH option excludes Threads impacts
• *.H *.C specify the C++ include files and C++ source files in the first directory
• The output is written in HTML format to scan_detail.html

Change to the second directory and repeat the above scan:

cd dir2_name 
scandetail -T En,Ns -C CBL4,F90 -C TH *.H *.C

Example 2: Scan a directory of scripts only for command, path, and argument identifiers that have changed:

scandetail -p $PLAN_DIR/commands +Y C,P,A \
scripts_dir/*

Where:

• -p option saves the output in an HTML file named $PLAN_DIR/commands_detail.html
• +Y C,P,A option includes command, path, and argument identifiers
• scripts_dir/* specifies the files in the script directory

Example 3: Scan a 10.20 C application's source base that is to be ported to HP-UX 11i 64-bit:

scandetail -p $PLAN_DIR/64-bit -O 10.20-11i +C 64,32 -o text \
source_files

Where:

• -p option saves the output in a file named $PLAN_DIR/64-bit_detail.txt
• -O 10.20-11i excludes HP-UX 11i Version 1.5/1.6 impacts
• +C 64,32 option excludes all classes except 64-bit and 32-bit interoperability with 64-bit impacts
• -o text options specifies the output to be in text format
• source_files specifies the C application's source files

Note that you cannot use -C to exclude some classes, and +C to specify others.

Example 4: Scan a single non-threaded Fortran source file that is being ported from HP-UX 10.20 to HP-UX 11.00 32-bit that contains no networking code.

scandetail -T En -S Nc -O 10.20-11.00 -C CBL4 \
-Y Cc,Cf,Ck -C TH,NW,64,32 source_file

Where:

• -T En option excludes Enhancement impacts
• -S Nc option excludes Non-critical impacts
• -O 10.20-11.00 option specifies source and destination platforms
• -C CBL4 option excludes all language classification impacts except Fortran
• -Y Cc,Cf,Ck option excludes all COBOL identifier types
• -C TH,NW,64,32 option excludes Threads, Networking, 64-bit, and 32-bit interoperability impacts
• source_file specifies the Fortran application's source file that is being changed.

Example 5: Scan a source base for threads-related problems. Include the common source and the HP-UX sections but exclude the IBM AIX, Sun Solaris, and SGI IRIX sections.

scandetail -U AIX,SUN5,IRIX +C TH -r root1

Where:

• -U AIX,SUN5,IRIX option excludes source inside #ifdef AIX, #ifdef SUN5, and #ifdef IRIX
• +C TH option includes threads impacts
• -r option specifies the root directory to scan recursively

Example 6: Scan a C source file that does not conform to POSIX and other API standards.

scandetail +T Ns -C CBL4,F90 source_file

Where:

• +T Ns option includes only Non-standard impacts
• -C CBL4,F90 option excludes all language classification impacts except for the C language
• source_file specifies the C application's source file that is being checked

See also

For more information on using scandetail and scansummary, see:
	» Using scandetail and scansummary
	» Customizing Your Scan
	» scandetail(1)
For information on file scanner error messages, see:
	» File Scanner Error Messages