ftnchop(1)
ftnchop - Invokes the program unit problem isolator
As shipped in IRIX 6.5. First release of IRIX 6.5.
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 FTNCHOP_LIST. It then executes the program or shell script named FTNCHOP_TEST. This program or shell script links the program by using the list in FTNCHOP_LIST, 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 FTNCHOP_TEST 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 FTNCHOP_LIST 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 FTNCHOP_LIST 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 FTNCHOP_TEST 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 FTNCHOP_STAT. 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 FTNCHOP_STAT. 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 FTNCHOP_TEST 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. FTNCHOP_LIST List of files to be tested by ftnchop. FTNCHOP_TEST Name of test script called by ftnchop. SEE ALSO f90(1) and ftnsplit(1) This man page is available only online.