FTNCHOP(1) Last changed: 7-23-97
NAME
ftnchop - Invokes the program unit problem isolator
SYNOPSIS
ftnchop [-G] [-B] [-g gdir] [-b dir] [-r] [-v] [-V] LIST
IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems
DESCRIPTION
The ftnchop utility is a program that isolates problems to object file
level by using a mix-and-match technique. This utility is most useful
with programs that contain several source files. To run the ftnchop
utility you need to have one working version of a program and one
version that is not working. When run, ftnchop finds the object files
that are causing the program to malfunction. Debugging efforts can
then be concentrated to those files.
The ftnchop utility works by selecting object files from two
directories gdir and bdir, whose default names are GOOD and BAD. It
reads the list of object files from file LIST, one file name per line
with no trailing blanks. To make a trial run, ftnchop prefixes object
file names with gdir/ or bdir/ and writes them to a file named
FTNCHOPLIST. It then executes the program or shell script named
FTNCHOPTEST. This program or shell script links the program by using
the list in FTNCHOPLIST, tests it, and returns an exit status of zero
if the test passed and a non-zero exit status if the test failed.
Depending on the return value, ftnchop will change the list and call
FTNCHOPTEST again until it has found one file in bdir that is causing
the failure. At this point ftnchop will run another test to determine
if that was the only bad file. If not, ftnchop will repeat the test
process with the remaining files until all bad files are found.
Before doing any mixing, ftnchop checks the boundary conditions by
making one run with all good files and another run with all bad files.
These checks can be skipped if you specify the -G and -B options,
respectively. If these checks are skipped and the boundary conditions
are not correct, that is if the program with all good files fails or
if the program with all bad files passes, ftnchop can return
inaccurate information.
The ftnchop command accepts the following options:
-G Specifies that ftnchop skip checking boundry
conditions on good files.
-B Specifies that ftnchop skip checking boundry
conditions on bad files.
-g gdir Specifies name of directory containing the good
files. Default is GOOD.
-b gdir Specifies name of directory containing the bad files.
Default is BAD.
-r Restarts ftnchop from the point where the test run
was aborted. Must be the only option on the command
line.
-v Specifies that the entire contents of FTNCHOPLIST is
printed. Default is to print a single line that
lists the name of the bad file.
-V Displays version, date, and time of the ftnchop
executable running on your system. If this is the
only option specified on the command line, the
utility exits after printing the information; the
tool itself is not started.
NOTES
Depending on the number of files and the length of the test run,
ftnchop can take several hours to complete.
All object files and test files must remain unmodified during the
entire run. The test script must be written carefully so that it does
not depend on any previous run in any way.
By default ftnchop prints just one message line for each bad file
found:
##### FOUND BAD FILE file
It is advisable to print the contents of FTNCHOPLIST to keep a record
of the entire run.
The ftnchop utility makes no distinction between a test failure and a
script failure. If the script FTNCHOPTEST has a syntax error, or if
the f90 comand fails for any reason, ftnchop assumes a test failure.
If the -G switch is not specified, the utility stops as soon as it
finds the all-good file test failing. Otherwise it will find all the
files to be bad and return inaccurate information. Therefore, it is
advisable to watch the starting of a ftnchop run to make sure it is
progressing correctly.
While ftnchop is running a test, it writes state information to a file
called FTNCHOPSTAT. If a run aborts for any reason, you can restart
ftnchop from that point by entering the following command:
ftnchop -r
This causes ftnchop to read state information from FTNCHOPSTAT. This
state information includes the names of the good and bad directories
and all the options.
ftnchop does not require that files be object files.
EXAMPLES
A typical situation occurs when a large program made of several object
files works when compiled without optimization but not when compiled
with optimization. To use ftnchop to locate the problem, create two
directories, for example O0 and O2. Keep all unoptimized object files
in directory O0 and optimized files in directory O2. Then create an
automated method of determining the success of a program test run.
One way would be to create a shell script named FTNCHOPTEST that
causes the program to print TEST PASSED at the end of a successful run
but return a message of TEST FAILED upon an unsuccessful run. The
shell script would look like the following script:
echo ================= TESTING WITH: ==================
cat FTNCHOP_LIST
f77 -o prog `cat FTNCHOP_LIST`
prog > RESULT
tail -l RESULT > t1
if grep t1 'RUN COMPLETED'
then
echo TEST PASSED
exit 0
else
echo TEST FAILED
exit 1
fi
Make sure the script has executable permission. Make a file
containing the names of all constituent files, one per line, by using
the following format:
/bin/ls O0 > OLIST
The execute the ftnchop command as follows:
ftnchop -gO0 -bO2 OLIST > FTNCHOP.RES
After the run is complete, enter the following grep command to find
the bad files:
grep FOUND FTNCHOP.RES
Another example of failure can occur when a program gets an exception
error and dumps core memory. In this case the test that a failure
occurred may be the existence of a core file, as shown in the
following example:
rm -f core # remove from any previous runs
prog > RESULT
if test -f core
then
exit 1
else
exit 0
fi
FILES
BAD Default name of the directory containing the
"bad" files.
GOOD Default name of the directory containing the
"good" files.
FTNCHOPLIST List of files to be tested by ftnchop.
FTNCHOPTEST Name of test script called by ftnchop.
SEE ALSO
f90(1) and ftnsplit(1)
This man page is available only online.