Fortran Programming Guide

Chapter 5 Program Analysis and Debugging

This chapter presents a number of Sun Fortran compiler features that facilitate program analysis and debugging.

Global Program Checking

The f77 compiler's -Xlistx options provide a valuable way to analyze a source program for inconsistencies and possible runtime problems. The analysis performed by the compiler is global, across subprograms.

-Xlistx reports errors in alignment, agreement in number and type for subprogram arguments, common block, parameter, and various other kinds of errors.

-Xlistx also can be used to make detailed source code listings and cross-reference tables.

Note -

The f90 compiler provides only a subset of the --Xlist options described here. A conventional cross-reference map is produced, but complete global program checking is not performed.

GPC Overview

Global program checking (GPC), invoked by the -Xlistx option, does the following:

Enforces type-checking rules of Fortran more stringently than usual, especially between separately compiled routines

Enforces some portability restrictions needed to move programs between different machines or operating systems

Detects legal constructions that nevertheless might be suboptimal or error-prone

Reveals other potential bugs and obscurities

In particular, global checking reports problems such as:

Interface problems
- Conflicts in number and type of dummy and actual arguments
- Wrong types of function values
- Possible conflicts due to data type mismatches in common blocks between different subprograms

Usage problems
- Function used as a subroutine or subroutine used as a function
- Declared but unused functions, subroutines, variables, and labels
- Referenced but not declared functions, subroutines, variables, and labels
- Usage of unset variables
- Unreachable statements
- Implicit type variables
- Inconsistency of the named common block lengths, names, and layouts

How to Invoke Global Program Checking

The -Xlist option on the command line invokes the compiler's global program analyzer. There are a number of -Xlistx suboptions, as described in the sections that follow.

Example: Compile three files for basic global program checking:

demo% f77 -Xlist  any1.f  any2.f  any3.f

In the preceding example, the compiler:

Produces output listings in the file any1.lst

Compiles and links the program if there are no errors

Screen Output

Normally, output listings produced by -Xlistx are written to a file. To display directly to the screen, use -Xlisto to write the output file to /dev/tty.

Example: Display to terminal:

demo% f77 -Xlisto /dev/tty  any1.f

Default Output Features

The -Xlist option provides a combination of features available for output. With no other -Xlist options, you get the following by default:

The listing file name is taken from the first input source or object file that appears, with the extension replaced by .lst

A line-numbered source listing

Error messages (embedded in listing) for inconsistencies across routines

Cross-reference table of the identifiers

Pagination at 66 lines per page and 79 columns per line

No call graph

No expansion of include files

File Types

The checking process recognizes all the files in the compiler command line that end in .f, .f90, .for, .F, or .o. The .o files supply the process with information regarding only global names, such as subroutine and function names.

Analysis Files (`.fln` Files)

Programs compiled with --Xlist options have their analysis data built into the binary files automatically. This enables global program checking over programs in libraries.

Alternatively, the compiler will save individual source file analysis results into files with a .fln suffix if the -Xlistflndir option is also specified. dir indicates the directory to receive these files.

demo% f77 -Xlistfln/tmp *.f

Some Examples of `--Xlist` and Global Program Checking

Here is a listing of the Repeat.f source code used in the following examples:

demo% cat Repeat.f
       PROGRAM repeat
         pn1 = REAL( LOC ( rp1 ) )
         CALL subr1 ( pn1 )
         CALL nwfrk ( pn1 )
         PRINT *, pn1
       END ! PROGRAM repeat

       SUBROUTINE subr1 ( x )
         IF ( x .GT. 1.0 ) THEN
          CALL subr1 ( x * 0.5 )
         END IF
       END

       SUBROUTINE nwfrk( ix )
         EXTERNAL fork
         INTEGER prnok, fork
         PRINT *, prnok ( ix ), fork ( )
       END

       INTEGER FUNCTION prnok ( x )
         prnok = INT ( x ) + LOC(x)
       END

       SUBROUTINE unreach_sub()
         CALL sleep(1)
       END

Example: Use -XlistE to show errors and warnings:

demo% f77 -XlistE -silent Repeat.f
demo% cat Repeat.lst
FILE  "Repeat.f"
program  repeat
     4             CALL nwfrk ( pn1 )
                                  ^
**** ERR  #418:  argument "pn1" is real, but dummy argument is
                 integer*4 
                 See: "Repeat.f" line #14
     4             CALL nwfrk ( pn1 )
                                  ^
**** ERR  #317:  variable "pn1" referenced as integer*4 across
                 repeat/nwfrk//prnok in line #21 but set as real 
                 by repeat in line #2
subroutine  subr1
    10              CALL subr1 ( x * 0.5 )
                             ^
**** WAR  #348:  recursive call for "subr1". See dynamic calls:
                 "Repeat.f" line #3
subroutine  nwfrk
    17             PRINT *, prnok ( ix ), fork ( )
                                     ^
**** ERR  #418:  argument "ix" is integer*4, but dummy argument 
                 is real
                 See: "Repeat.f" line #20
subroutine  unreach_sub
    24           SUBROUTINE unreach_sub()
                                      ^
**** WAR  #338:  subroutine "unreach_sub" isn't called from program

Date:     Wed Feb 24 10:40:32 1999
Files:         2 (Sources: 1; libraries: 1)
Lines:        26 (Sources: 26; Library subprograms:2)
Routines:      5 (MAIN: 1; Subroutines: 3; Functions: 1)
Messages:      5 (Errors: 3; Warnings: 2)
demo%

Compiling the same program with --Xlist also produces a cross-reference table on standard output:

         C R O S S   R E F E R E N C E   T A B L E
  Source file:   Repeat.f
Legend:
D        Definition/Declaration
U        Simple use
M        Modified occurrence
A        Actual argument
C        Subroutine/Function call
I        Initialization: DATA or extended declaration
E        Occurrence in EQUIVALENCE
N        Occurrence in NAMELIST

         P R O G R A M   F O R M
 Program
 -------
repeat          <repeat>        D      1:D 

 Functions and Subroutines
 -------------------------
fork     int*4  <nwfrk>        DC     15:D     16:D     17:C 

int      intrinsic
                <prnok>         C     21:C 

loc      intrinsic
                <repeat>        C      2:C 
                <prnok>         C     21:C 

nwfrk           <repeat>        C      4:C 
                <nwfrk>         D     14:D 

prnok    int*4  <nwfrk>        DC     16:D     17:C 
                <prnok>        DM     20:D     21:M 

real     intrinsic
                <repeat>        C      2:C 

sleep           <unreach_sub>            C     25:C 

subr1           <repeat>        C      3:C 
                <subr1>        DC      8:D     10:C 
unreach_sub     <unreach_sub>            D     24:D

Output from compiling f77-Xlist Repeat.f (Continued)

 Variables and Arrays
 --------------------

ix       int*4  dummy
                <nwfrk>        DA     14:D     17:A 

pn1      real*4 <repeat>      UMA      2:M      3:A      4:A      5:U 

rp1      real*4 <repeat>        A      2:A 

x        real*4 dummy
                <subr1>        DU      8:D      9:U     10:U 
                <prnok>       DUA     20:D     21:A     21:U 

----------------------------------------------------------------------

Date:     Tue Feb 22 13:15:39 1995
Files:         2 (Sources: 1; libraries: 1)
Lines:        26 (Sources: 26; Library subprograms:2)
Routines:      5 (MAIN: 1; Subroutines: 3; Functions: 1)
Messages:      5 (Errors: 3; Warnings: 2)
demo%

In the cross-reference table in the preceding example:

ix is a 4-byte integer:
- Used as an argument in the routine nwfrk
- At line 14, used as a declaration of argument
- At line 17, used as an actual argument

pn1 is a 4-byte real in the routine repeat:
- At line 2, modified
- At line 3, argument
- At line 4, argument
- At line 5, used

rp1 is a 4-byte real in the routine, repeat. At line 2, it is an argument.

x is a 4-byte real in the routines subr1 and prnok:
- In subr1, at line 8, defined; used at lines 9 and 10
- In prnok, at line 20, defined; at line 21, used as an argument

Suboptions for Global Checking Across Routines

The basic global cross-checking option is -Xlist with no suboption. It is a combination of suboptions, each of which could have been specified separately.

The following sections describe options for producing the listing, errors, and cross-reference table. Multiple suboptions may appear on the command line.

Suboption Syntax

Add suboptions according to the following rules:

Append the suboption to -Xlist.
Put no space between the -Xlist and the suboption.
Use only one suboption per -Xlist.

`--Xlist` and its Suboptions

Combine suboptions according to the following rules:

The most general option is -Xlist (listing, errors, cross-reference table).
Specific features can be combined using -Xlistc, -XlistE, -XlistL, or -XlistX.
Other suboptions specify further details.

Example: Each of these two command lines performs the same task:

demo% f77  -Xlistc  -Xlist  any.f

demo% f77  -Xlistc  any.f

The following table shows the reports generated by these basic --Xlist suboptions alone:

Table 5-1 Xlist Suboptions


Generated Report	Option
Errors, listing, cross-reference	`-Xlist`
Errors only	`-Xlist``E`
Errors and source listing only	`-Xlist``L`
Errors and cross-reference table only	`-Xlist``X`
Errors and call graph only	`-Xlist``c`

The following table summarizes all -Xlist suboptions.

Table 5-2 Summary of --Xlist Suboptions


Option	Action
`-Xlist` (no suboption)	Shows errors, listing, and cross-reference table
`-Xlist``c`	Shows call graphs and errors (f77 only)
`-Xlist``E`	Shows errors
`-Xlist``err``[nnn]`	Suppresses error `nnn` in the verification report
`-Xlist``f`	Produces fast output (f77 only)
`-Xlist``fln``dir`	Puts t`he` `.fln` files in `dir` (f77 only)
`-Xlist``h`	Shows errors from cross-checking stop compilation (f77 only)
`-Xlist``I`	Lists and cross-checks `include` files
`-Xlist``L`	Shows the listing and errors
`-Xlist``l``n`	Sets page breaks
`-Xlist``o` `name`	Renames the `-Xlist` output report file
`-Xlist``s`	Suppresses unreferenced symbols from cross-reference (f77 only)
`-Xlist``v``n`	Sets checking "strictness" level (f77 only)
`-Xlist``w``[nnn]`	Sets the width of output lines
`-Xlist``war``[nnn]`	Suppresses warning nnn in the report
`-Xlist``X`	Shows just the cross-reference table and errors

`-Xlist` Suboption Reference

This section describes the --Xlist suboptions. As noted, some are only available with f77.

`-f77: -Xlistc` -- Show call graphs and cross-routine errors

Used alone, --Xlistc does not show a listing or cross-reference. It produces the call graph in a tree form, using printable characters. If some subroutines are not called from MAIN, more than one graph is shown. Each BLOCKDATA is printed separately with no connection to MAIN.

The default is not to show the call graph.

`--XlistE` - Show cross-routine errors

Used alone, --XlistE shows only cross-routine errors and does not show a listing or a cross-reference.

`- -Xlisterr[nnn]` - Suppress error `nnn`

Use --Xlisterr to suppress a numbered error message from the listing or cross-reference.

For example: -Xlisterr338 suppresses error message 338. If nnn is not specified, all error messages are suppressed. To suppress additional specific errors, use this option repeatedly.

`f77: -Xlist-f` - Produce faster output

Use --Xlistf to produce source file listings and a cross-checking report and to verify sources, but without generating object files.

The default without this option is to generate object files.

`f77:` -`Xlist-flndir` - Put `.fln` files into `dir` directory

Use --Xlistfln to specify the directory to receive .fln source analysis files. The directory specified (dir) must already exist. The default is to include the source analysis information directly within the object .o files (and not generate .fln files).

`f77: -Xlist-h` - Halt on errors

With --Xlisth, compilation stops if errors are detected while cross-checking the program. In this case, the report is redirected to stdout instead of the *.lst file.

`-Xlist-I` - List and cross-check include files

If -XlistI is the only suboption used, include files are shown or scanned along with the standard -Xlist output (line numbered listing, error messages, and a cross-reference table).

Listing--If the listing is not suppressed, then the include files are listed in place. Files are listed as often as they are included. The files are:
- Source files
- #include files
- INCLUDE files

Cross-Reference Table--If the cross reference table is not suppressed, the following files are all scanned while the cross reference table is generated:
- Source files
- #include files
- INCLUDE files
  
  The default is not to show include files.

`-Xlist-L` - Show listing and cross routine errors

Use --XlistL to produce only a listing and a list of cross routine errors. This suboption by itself does not show a cross reference table. The default is to show the listing and cross reference table.

`-Xlist-ln` - Set the page length for pagination to `n` lines

Use --Xlistl to set the page length to something other than the default page size. For example, -Xlistl45 sets the page length to 45 lines. The default is 66.

With n=0 (-Xlistl0) this option shows listings and cross-references with no page breaks for easier on-screen viewing.

`-Xlist-o` `name` - Rename the `-Xlist` output report file

Use --Xlisto to rename the generated report output file. (A space between o and name is required.) With --Xlisto name,the output is to name.lst .

To display directly to the screen, use the command: -Xlisto /dev/tty

`f77: -Xlist-s` - Suppress unreferenced identifiers

Use --Xlists to suppress from the cross reference table any identifiers defined in the include files but not referenced in the source files.

This suboption has no effect if the suboption -XlistI is used.

The default is not to show the occurrences in #include or INCLUDE files.

`f77: -Xlist-vn` - Set level of checking strictness

n is 1,2, 3, or 4. The default is 2 (-Xlistv2):

-Xlistv1

Shows the cross-checked information of all names in summary form only, with no line numbers. This is the lowest level of checking strictness--syntax errors only.

-Xlistv2

Shows cross-checked information with summaries and line numbers. This is the default level of checking strictness and includes argument inconsistency errors and variable usage errors.

-Xlistv3

Shows cross-checking with summaries, line numbers, and common block maps. This is a high level of checking strictness and includes errors caused by incorrect usage of data types in common blocks in different subprograms.

-Xlistv4

Shows cross-checking with summaries, line numbers, common block maps, and equivalence block maps. This is the strictest level of checking with maximum error detection.

`-Xlist-w[nnn]` - Set width of output line to `n` columns

Use --Xlistw to set the width of the output line. For example, -Xlistw132 sets the page width to 132 columns. The default is 79.

`-Xlist-war[nnn]` - Suppress warning nnn in the report

Use --Xlistwar to suppress a specific warning message from the output reports. If nnn is not specified, then all warning messages are suppressed from printing. For example, -Xlistwar338 suppresses warning message number 338. To suppress more than one, but not all warnings, use this option repeatedly.

`-Xlist-X` - Show cross-reference table and cross routine errors

--XlistX produces a cross reference table and cross routine error list but no source listing.

Some Examples Using Suboptions

Example: Use -Xlistwarnnn to suppress two warnings from a preceding example:

demo% f77 -Xlistwar338  -Xlistwar348 -XlistE -silent Repeat.f
demo% cat Repeat.lst
FILE  "Repeat.f"
program  repeat
     4             CALL nwfrk ( pn1 )
                                  ^
**** ERR  #418:  argument "pn1" is real, but dummy argument is 
                 integer*4 
                 See: "Repeat.f" line #14
     4             CALL nwfrk ( pn1 )
                                  ^
**** ERR  #317:  variable "pn1" referenced as integer*4 across
                 repeat/nwfrk//prnok in line #21 but set as real 
                 by repeat in line #2
subroutine  nwfrk
    17             PRINT *, prnok ( ix ), fork ( )
                                     ^
**** ERR  #418:  argument "ix" is integer*4, but dummy argument 
                 is real
                 See: "Repeat.f" line #20

Date:     Wed Feb 24 10:40:32 1999
Files:         2 (Sources: 1; libraries: 1)
Lines:        26 (Sources: 26; Library subprograms:2)
Routines:      5 (MAIN: 1; Subroutines: 3; Functions: 1)
Messages:      5 (Errors: 3; Warnings: 2)
demo%

Example: Explain a message and find a type mismatch in program ShoGetc.f:

demo% cat ShoGetc.f 
      CHARACTER*1 c
      i = getc(c)
      END
demo% f77 -silent ShoGetc.f							   Compile program	
demo% a.out                   Program waits for input...						
Z                    Type "Z" on keyboard. This causes run-time message. Why?
 Note: IEEE floating-point exception flags raised: 
    Invalid Operation; 
 See the Numerical Computation Guide, ieee_flags(3M) 
demo% f77 -XlistE -silent ShoGetc.f  Compile with Global Program Checking
demo% cat ShoGetc.lst                and view listing
FILE  "ShoGetc.f"
program  MAIN
     2          i = getc(c)
                ^
**** WAR  #320:  variable "i" set but never referenced
     2          i = getc(c)
                       ^
**** ERR  #412:  function "getc" used as real but declared as 
                 integer*4 
        Here is the error - function must be declared INTEGER.

     2          i = getc(c)
                         ^
**** WAR  #320:  variable "c" set but never referenced
demo% cat ShoGetc.f      Modify program to declare getc INTEGER and run again.
      CHARACTER*1 c
      INTEGER getc
      i = getc(c)
      END
demo% f77 -silent ShoGetc.f
demo% a.out
Z                        Type "Z" on keyboard
demo%                    Now no error.

Special Compiler Options

Some compiler options are useful for debugging. They check subscripts, spot undeclared variables, show stages of the compile-link sequence, display versions of software, and so on.

The Solaris linker has additional debugging aids. See ld(1), or run the command ld -Dhelp at a shell prompt to see the online documentation.

Subscript Bounds (`-C`)

The -C option adds checks for out-of-bounds array subscripts.

If you compile with -C, the compiler adds checks at runtime for out-of-bounds references on each array subscript. This action helps catch some situations that cause segmentation faults.

Example: Index out of range:

demo% cat indrange.f
      REAL a(10,10)
      k = 11
      a(k,2) = 1.0
      END
demo% f77 -C -silent indrange.f
demo% a.out
 Subscript out of range on file indrange.f, line 3, procedure MAIN. 
 Subscript number 1 has value 11 in array a. 
 Abort (core dumped) 
demo%

`f77`: Undeclared Variable Types (`-u`)

The -u option checks for any undeclared variables. (Not available with f90.)

The -u option causes all variables to be initially identified as undeclared, so that all variables that are not explicitly declared by type statements, or by an IMPLICIT statement, are flagged with an error. The -u flag is useful for discovering mistyped variables. If -u is set, all variables are treated as undeclared until explicitly declared. Use of an undeclared variable is accompanied by an error message.

Version Checking (`-V`)

The -V option causes the name and version ID of each phase of the compiler to be displayed. This option can be useful in tracking the origin of ambiguous error messages and in reporting compiler failures, and to verify the level of installed compiler patches.

Interactive Debugging With `dbx` and Sun WorkShop

The Sun WorkShop provides a tightly integrated development environment for building and browsing, as well as debugging applications written in Fortran, C, and C++.

The Sun WorkShop debugging facility is a window-based interface to dbx, while dbx itself is an interactive, line-oriented, source-level symbolic debugger. Either can be used to determine where a program crashed, to view or trace the values of variables and expressions in a running code, and to set breakpoints.

Sun WorkShop adds a sophisticated graphical environment to the debugging process that is integrated with tools for editing, building, and source code version control. It includes a data visualization capability to display and explore large and complex datasets, simulate results, and interactively steer computations.

For details, see the Sun manuals Using Sun WorkShop and Debugging a Program With Sun WorkShop, and the dbx(1) man pages.

The dbx program provides event management, process control, and data inspection. You can watch what is happening during program execution, and perform the following tasks:

Fix one routine, then continue executing without recompiling the others
Set watchpoints to stop or trace if a specified item changes
Collect data for performance tuning
Graphically monitor variables, structures, and arrays
Set breakpoints (set places to halt in the program) at lines or in functions
Show values--once halted, show or modify variables, arrays, structures
Step through a program, one source or assembly line at a time
Trace program flow--show sequence of calls taken
Invoke procedures in the program being debugged
Step over or into function calls; step up and out of a function call
Run, stop, and continue execution at the next line or at some other line
Save and then replay all or part of a debugging run
Examine the call stack, or move up and down the call stack
Program scripts in the embedded Korn shell
Follow programs as they fork(2) and exec(2)

To debug optimized programs, use the dbx fix command to recompile the routines you want to debug:

Compile the program with the appropriate -On optimization level.

Start the execution under dbx.

Use fix -g any.f without optimization on the routine you want to debug.

Use continue with that routine compiled.

Some optimizations will be inhibited by the presence of --g on the compilation command. For example, --g suppresses the automatic inlining usually obtained with- -O4. --g cancels any parallelization option (--autopar, --explicitpar, --parallel), as well as --depend and --reduction. Debugging is facilitated by specifying --g without any optimization options. See the dbx documentation for details.

`f77`: Viewing Compiler Listing Diagnostics

Use the error utility program to view compiler diagnostics merged with the source code. error inserts compiler diagnostics above the relevant line in the source file. The diagnostics include the standard compiler error and warning messages, but not the -Xlist error and warning messages.

Note -

The error utility rewrites your source files and does not work if the source files are read-only, or are in a read only directory.

error(1) is included as part of a "developer" installation of the Solaris operating environment; it can also be installed from the package, SUNWbtool.

Facilities also exist in the Sun WorkShop for viewing compiler diagnostics. Refer to Using Sun WorkShop.

Chapter 5 Program Analysis and Debugging

Global Program Checking

GPC Overview

How to Invoke Global Program Checking

Screen Output

Default Output Features

File Types

Analysis Files (.fln Files)

Some Examples of --Xlist and Global Program Checking

Suboptions for Global Checking Across Routines

Suboption Syntax

--Xlist and its Suboptions

-Xlist Suboption Reference

-f77: -Xlistc -- Show call graphs and cross-routine errors

--XlistE - Show cross-routine errors

- -Xlisterr[nnn] - Suppress error nnn

f77: -Xlist-f - Produce faster output

f77: -Xlist-flndir - Put .fln files into dir directory

f77: -Xlist-h - Halt on errors

-Xlist-I - List and cross-check include files

-Xlist-L - Show listing and cross routine errors

-Xlist-ln - Set the page length for pagination to n lines

-Xlist-o name - Rename the -Xlist output report file

f77: -Xlist-s - Suppress unreferenced identifiers

f77: -Xlist-vn - Set level of checking strictness

-Xlist-w[nnn] - Set width of output line to n columns

-Xlist-war[nnn] - Suppress warning nnn in the report

-Xlist-X - Show cross-reference table and cross routine errors