2 SPAG - Renovation & Analysis

2.1 Introduction

2.1.1 What does it do?

SPAG is a multi-purpose tool for analyzing and improving Fortran programs. It combines restructuring and re-formatting with translation to Fortran 95, and both static and dynamic analysis in a single powerful package. SPAG offers facilities which go beyond the sum of these parts. For example:

• SPAG can restructure 'rats-nest' Fortran 66 to modern and structured Fortran 95, or apply a final polish to well written modern code.
• SPAG can automatically insert explicit type declarations for IMPLICITly typed variables.
• Alternatively, SPAG rewrite the declarations from scratch using either Fortran 77 or Fortran 95 declaration style. Legacy data types, such as REAL*8 and INTEGER*4 can be converted to modern standard Fortran using using information in the standard ISO_FORTRAN_ENV module.
• SPAG can identify, and optionally remove unused variables and code fragments.
• SPAG can change variable names in a simple and safe way.
• SPAG can convert back and forth between the Fortran 77 and Fortran 95 versions of control constructs such as DO WHILE, ENDDO, CYCLE, EXIT and SELECT CASE. SPAG can also convert between the new and old source forms, and the new and old declaration styles.
• SPAG can implement local conventions and preferences by using upper and lower case to distinguish different types of symbol.
• SPAG can create Fortran 95 modules to replace Fortran 77 COMMON blocks and INCLUDE files. It can also create Fortran 95 interface blocks to facilitate compiler argument checking.
• Working with GXCHK (see chapter 3), SPAG can analyse the calling and data access patterns in non-modular legacy Fortran code, and produce a design template for conversion to modern Fortran with modules.
• SPAG can translate VAX structures to Fortran 95 derived types.
• SPAG can insert probes to perform a dynamic analysis of your program as it runs. Dynamic analysis can identify many bugs which are not apparent to a static analyzer, but, at present dynamic analysis is not compatible with some Fortran 95 features, including pointers and array language.
• SPAG can insert probes into your source code which time individual subprograms and automatically produce a report whenever a run completes.
• SPAG can insert probes to identify untested code and computational hot-spots. The results can be inserted, as comments, back into the original code.
• SPAG can write out symbol table files for reference, or for input to other QA and analysis programs, such as GXCHK (see chapter 3).
• SPAG understands Fortran 95 (which includes Fortran 77 as a subset), VAX Fortran, and many common extensions, such as Cray pointers, ENCODE/DECODE etc. SPAG also understands almost all of Fortran 2003, including the object oriented programming extensions.

2.1.2 Code Restructuring

SPAG can unscramble spaghetti Fortran 66 code, and convert it to modern and structured Fortran 95.

When SPAG restructures a program, it does not change its meaning, or even the order in which statements are executed; it does change the way the program logic is written down, making it much easier to understand and maintain. Old-fashioned control constructs (such as GOTO, arithmetic IF, computed GOTO etc.) are eliminated, or replaced by block IFs, DO loops with EXIT and CYCLE etc. SPAG also rearranges blocks of code so that logically related sections are physically close, and jumps in control flow are minimized. The algorithms used to do this draw on a deep analysis of the program structure.

2.1.3 Code Replication

Sometimes, rearrangement is not enough. Spaghetti programmers often made their programs more complex in order to re-use a few bytes of code - perhaps to avoid putting 'N=0' more than once. SPAG can undo the damage by replicating small code fragments where this improves the restructured code.

2.1.4 Dispatch Loops and Internal Subroutines

In some cases a final restructuring stage may be necessary to remove the last few GOTOs. SPAG can rationalise the most complex spaghetti by breaking the code into separately addressable blocks which are relocated within a SELECT CASE construct, the whole being executed within an outer dispatch loop. Transfers between blocks are effected by setting the value of the CASE variable after each block is executed, and cycling the dispatch loop. This effectively imposes a known structure on even the most unruly code.

A similar result may be acheived by moving the separately addressable blocks mentioned above into internal subroutines. GOTOs are replaced by CALLs to those internal subroutines, and in some cases they may be called recursively. This can be very effective, but carries a risk: there can be cases in which the recursion is arbitrarily deep, which may lead to stack overflow when the restructured program is executed. This is rare in practice, but users need to be aware of the risk.

SPAG offers both the above options, and a hybrid in which internal subroutines are preferred if recursion is not needed.

2.1.5 Translation to Fortran 95

In addition to translating source form, declaration style, and control constructs to Fortran 95, SPAG can also convert COMMON blocks and INCLUDE files to Fortran 95 modules. It can also create a module containing an INTERFACE block for each subprogram, and insert appropriate USE statements in calling subprograms. Fortran 95 compilers can use these constructs to perform argument checking.

2.1.6 Adding or Rewriting Declarations

Most older Fortran programs use IMPLICIT typing. That is to say that variables are not formally declared at the head of each subprogram, as they are in Pascal or C, but are simply assigned a type according to their initial letter. SPAG provides the means to convert such programs to explicit typing, which in Fortran is enforced using the IMPLICIT NONE statement. It does this by adding explicit declarations for all undeclared variables at the head of each subprogram. Explicit typing allows your compiler to detect errors which might otherwise remain undetected for years.

SPAG can also rewrite your declarations from scratch using either Fortran 77 or Fortran 95 declaration style. When SPAG does this, it groups declarations in a logical order. For example, dummy argument declarations form a separate section. When using the Fortran 95 declaration style, arrays with the same dimension are grouped together.

If declarations are rewritten in the Fortran 95 style, SPAG can add INTENT clauses, based on the way the argument is used within the current subprogram.

2.1.7 Translation of VAX Structures

Fortran 95 provides an ISO standard alternative to the VAX Fortran STRUCTURE and RECORD statements. SPAG can translate between the two forms. Features, such as UNIONs, which are not available in standard Fortran 95 are left unchanged, in a form suitable for a compiler which provides them as an extension.

2.1.8 Clutter Removal

Old programs often contain 'dead code' which can never be executed, and variables which are declared but never used. SPAG identifies and, optionally, removes this clutter.

2.1.9 Renaming Variables

SPAG provides a simple and safe method for systematically changing the names of symbols within a program. SPAG guards against the danger of choosing a new name which is already in use, and re-formats the source code as required.

2.1.10 Define a Corporate Style

SPAG contains a powerful code beautifier, with dozens of options controlling spacing, labels, indentation, use of CONTINUE etc. There is also an 'AS-IS' option for preserving the format of painstakingly hand-formatted declaration statements. SPAG can help make programs self-documenting, by using case to distinguish different types of symbol. For example, local variables may be lower case, PARAMETERs upper case, dummy arguments capitalized etc. (e.g. local, PARAM, Dummyarg, COMvar). All this gives project managers a powerful tool for defining and enforcing a corporate 'house programming style', making it easier for your programmers to work with each other's code, and with code from other sources.

2.1.11 Dynamic Analysis

If a bug is defined as 'an incorrect value in a storage location', then there is a large subset (perhaps 30%) which can be defined as 'an undefined value in a storage location', and many of the remainder may cause that condition as a knock-on effect. The 'Dynamic Analysis' option of plusFORT is a tool for diagnosing these errors at run-time. Probes are inserted in the source code before any operation which depends on the value of a data item. If the data item is undefined, the probes write details of the error to a log-file for later analysis. Source code for the probes is supplied.

A static analyzer such as GXCHK can detect a few of these errors, but the majority can only be detected at run-time. In fact static and dynamic analysis complement each other well - each excels where the other is deficient.

2.1.12 Coverage Analysis

In addition to testing for the definition status of variables and arrays, SPAG can insert probes to measure the time spent in individual subprograms, and monitor what code is executed. Over a series of runs, the probes identify untested code blocks and computational hot-spots. The CVRANAL utility produces a report which summarizes these results, and, if required, inserts usage counts back into the original code as comments (e.g. as end-of-line comments).

2.1.13 Symbol Table Files

SPAG optionally generates symbol table files which provide valuable information about data usage within subprograms. These files are used by GXCHK, the global cross check program (see Chapter 3), to generate an overview of data usage within an entire program.

Symbol tables are plain ASCII text files, the format of which is described in detail in Appendix A. Users are encouraged to develop their own applications using these files as input. For example it would be a simple matter to write a program to check conformance to local variable naming conventions.

2.2 Source Language

SPAG supports ISO standard Fortran 95 (and 77), VAX Fortran and IBM VS Fortran. SPAG also understands Fortran 2003, with a few minor exceptions, such as the ASSOCIATE construct. In addition, almost all the extensions supported by the major Windows, Mac and Linux compilers are supported.

Two minor exceptions to the above are:

• SPAG does not recognize the PDP style representation of octal constants (e.g. "36). However SPAG does recognize the newer and preferred form ('36'O).
• SPAG does not recognize hexadecimal constants of the form Z01FC233A ('Z' followed by hex digits). IBM's VS Fortran allows this form in DATA initialization statements. This extension pre-dates Fortran 77 and can result in ambiguity (e.g. ZABCD in a DATA statement could be a hex constant or a PARAMETER value).

An up to date summary of limitations and support for newer Fortran standards may be found in the READ.ME file in the plusFORT installation release directory.

2.3 Organizational Considerations

SPAG is designed to fit into any Fortran programming environment. However, in order to get the most from it, you may find it advantageous to observe the following guidelines:

• Keep the source and object code for each program or library in a separate directory, and avoid putting anything else in that directory. This makes it easy to identify all the code for a given program. If you have several versions of a program, keep them in separate directories.
• In Fortran 77 code, use INCLUDE files for declarations of COMMON variables and global PARAMETERs. Avoid using INCLUDE files for anything else. INCLUDE files should not contain IMPLICIT statements. Select a file-naming convention which allows you to distinguish easily between subprogram files and INCLUDE files (e.g. give INCLUDE files a different extension).
• Keep each subprogram in a separate file whose name is the same as the subprogram name. Use QMERGE and QSPLIT if you want to combine several subprograms in a single file.
• Give all subprograms a name. In particular, make sure that all main programs begin with a PROGRAM statement and that all BLOCK DATA segments are given a name.

2.4 The SPAG Command Line

SPAG can be run from a command prompt, or using PFFE, the plusFORT IDE.

From a command prompt, simply type spag followed by the name of the file(s) you wish to process. You can use wild-cards to specify more than one file. For example:

      SPAG A*.FOR B*.f90

      spag a*.f b*.f90

processes the contents of all files in the current directory which fit either wildcard.

It is generally simpler and better to use a single invocation of spag for multiple files, rather than separate invocations for each file. This is because spag performs a pre-scan of the input code which allows it to see a larger context. In particular, it reorders the input files, so that modules are processed before routines that USE them. Ordinarily - when using a compler for example - this reordering must be arranged externally - perhaps using a makefile, but SPAG's automatic reordering renders this unnecessary.

Under Windows, .for is assumed if no extension is specified (b* is treated as b*.for). The default file name is *.for. Thus, if you just type SPAG, all .for files in the current directory are processed.

On Linux and Mac, the extension must be specified, and there is no default file name.

By default, SPAG uses the filename extension to infer which source form is used. Thus, .for and .f files are assumed to use the old fixed source form, whereas SPAG assumes that .f90 and .f95 files use the newer free source form first defined in the Fortran 90 standard. For the fixed source form, SPAG analyses the source code to determine whether it conforms strictly to the standard (no tabs or long lines, possible sequence numbers in columns 73-80), or whether the more relaxed VAX-style format (long lines and tabs) should be assumed. This behaviour can be changed using configuration option 140.

The operation of SPAG may be modified by command line switches. Currently the following switches are available:

For example

      spag a*.f90 log=NEW.log fig=MARY.fig 1=1 60=1 sym=NEW.smb

This command causes SPAG to analyze all files in the current directory whose name fits the template a*.f90. A copy of all screen output is sent to NEW.log. Configuration options are read from MARY.fig, but the controls on records 1 and 60 are both set to 1 (re-format only, and leave specification statements unchanged). All symbol tables are written to the file NEW.smb. The way modified source code is output depends on items 10, 231 and 232 of the configuration data.

2.5 The SPAG Configuration File

The configuration file is a plain text file which provides the means by which users may customize SPAG to their own requirements and preferences. You can use an installation default configuration file, or create your own by copying one of the supplied versions and editing it using your standard editor.

PFFE, the plusFORT IDE includes a comprehensive editor for SPAG configuration files (including context-sensitive links to this manual). Many users find it easier to work using that editor, even when using the command line to invoke spag.

The file consists of data records and comment records. Any record with a space in column 1 is a comment record; all others are data records. Data records consist of an integer item number, followed by an '=' character and a value. They are terminated by a space character (optionally followed by a comment) or by the end-of-record. For items 1 to 199, the value is a simple integer. For items 200 to 299, the value is a text string. Records may appear in any order. Items 300 and up are ignored.

A small section from a typical configuration file is shown below. The significant parts are 1=3, 2=2 and 3=3, which set configuration items 1, 2 and 3 to 3, 2 and 3 respectively. The reaminder is commentary.

  #====================================#
  #======== Global Run Control ========#
  #====================================#

1=3    Type of Run
         0=no source output
         1=beautify only
         2=and relabel
         3=and restructure
         4=dynamic analysis

2=2    Symbol Table Ouptut
        -1=no symbol table
         0=generate table
         1=write to file
         3=Verbose

3=3    Clutter Checks
         0=no clutter checks
         1=checks only
         2-5=remove clutter

There are three sample configuration files in the plusFORT installation directory:

The meaning of each data item is explained in detail in the next section.

2.6 SPAG Configuration Data

! item 20 = 0
      GOTO (10,20,30),i
 10   x = a
      GOTO 40
 20   x = b
      GOTO 40
 30   x = c
 40   CONTINUE

! item 20 = 1
      IF  ( i.EQ.2 ) THEN
         x = b
      ELSEIF( i.EQ.3 ) THEN
         x = c
      ELSE
         x = a
      ENDIF

! item 20 = 2
      SELECT CASE (i)
      CASE (2)
         x = b
      CASE (3)
         x = c
      CASE DEFAULT
         x = a
      END SELECT

! item 22 = 0
       IF ( i ) 10,20,30
 10    x = a
       GOTO 40
 20    x = b
       GOTO 40
 30    x = c
 40    CONTINUE

! item 22 = 1
       IF ( i.LT.0 ) THEN
          x = a
       ELSEIF ( i.EQ.0 ) THEN
          x = b
       ELSE
          x = c
       ENDIF

! item 23 = 0
      IF ( q1 ) GOTO 10
      x = a
      y = b
      GOTO 20
 10   x = b
      y = a
 20   CONTINUE

! item 23 = 1
      IF ( q1 ) THEN
         x = b
         y = a
      ELSE
         x = a
         y = b
      ENDIF

! Before conversion
 10   IF ( i.GE.0 ) THEN
         READ * , I
         CALL sub(i)
         GOTO 10
      ENDIF

! After conversion
      DO WHILE ( i.GE.0 )
         READ * , I
         CALL sub(i)
      ENDDO

! Before conversion
 5    IF ( i.GE.0 ) THEN
         READ * , i
         CALL sub(i)
         IF ( q ) GOTO 5
         CALL sub(i+1)
      ENDIF

! After conversion
      DO WHILE ( i.GE.0 )
         READ * , i
         CALL sub(i)
         IF ( .NOT.q ) THEN
            CALL sub(i+1)
            EXIT
         ENDIF
      ENDDO

! Before conversion
 10   READ(9,END=100) z
      PRINT * , z
      GOTO 10

! After conversion
      DO
         READ(9,END=100) z
         PRINT * , z
      ENDDO

! Item 25 = 0
      DO i = 1 , 80
         ch = str(i:i)
         IF ( ch.EQ.' ' ) THEN
            IF ( lt.LE.0 ) GOTO 10
            GOTO 99999
         ELSEIF ( alp(ch) ) THEN
            nalp = nalp + 1
         ENDIF
         lt = lt + 1
 10   ENDDO
99999 END

! Item 25 = 3
      DO i = 1 , 80
         ch = str(i:i)
         IF ( ch.EQ.' ' ) THEN
            IF ( lt.LE.0 ) CYCLE
            EXIT
         ELSEIF ( alp(ch) ) THEN
            nalp = nalp + 1
         ENDIF
         lt = lt + 1
      ENDDO
      END

! original
       GOTO (10,20,30),i
       goto 50
 10    x = a
       GOTO 40
 20    x = b
       GOTO 40
 30    n = 0
       GOTO 50
 40    n = n + 1
 50    end

! item 26 = 0
      IF ( i.EQ.1 ) THEN
         x = a
         GOTO 100
      ELSEIF ( i.EQ.2 ) THEN
         x = b
         GOTO 100
      ELSEIF ( i.EQ.3 ) THEN
         n = 0
      ENDIF
      GOTO 99999
 100  n = n + 1
99999 END

! item 26 = 1
      IF ( i.EQ.1 ) THEN
         x = a
         n = n + 1
      ELSEIF ( i.EQ.2 ) THEN
         x = b
         n = n + 1
      ELSEIF ( i.EQ.3 ) THEN
         n = 0
      ENDIF
      END

! Item 27 = 0
      DO 10 i = 1 , 100
         IF ( q1 ) GOTO 20
 10   CONTINUE
      GOTO 30
 20   CALL sub1
 30   CALL sub2

! Item 27 = 1
      DO 10 i = 1 , 100
         IF ( q1 ) THEN
            CALL sub1
            GOTO 20
         ENDIF
 10   ENDDO
 20   CALL sub2

! original code
 11   call sub0
      If ( q1) then
         goto 10
      else
         call sub1
         call sub2
         goto 11
      endif
 10   return
      end

! Item 28 = 0
 100  CALL sub0
      IF ( q1 ) THEN
         RETURN
      ELSE
         CALL sub1
         CALL sub2
         GOTO 100
      ENDIF
      END

! Item 28 = 1
 100  CALL sub0
      IF ( .NOT.q1 ) THEN
         CALL sub1
         CALL sub2
         GOTO 100
      ENDIF
      RETURN
      END

      GOTO 200
! The following statement could never be executed
      WRITE(22,100) a,b,c
100   FORMAT(3F5.3)
200   PRINT *,a,b,c

!  VAX Structures
   structure /date/
   union
      map
         integer d , m , y
      end map
      map
         integer ddmmyy(3)
      end map
   end union
   end structure

   record /date/ today
   today.d = 20
   print * , today.ddmmyy(1)

!  Fortran 95 Derived Types
   TYPE DATE
      UNION
         MAP
            INTEGER D , M , Y
         ENDMAP
         MAP
            INTEGER DDMMYY(3)
         ENDMAP
      ENDUNION
   END TYPE DATE

   TYPE (DATE) today
   today%d = 20
   PRINT * , today%ddmmyy(1)

   INTEGER :: spag_nextblock_1
   spag_nextblock_1 = 1
   SPAG_DispatchLoop_1: DO
      SELECT CASE (spag_nextblock_1)
      CASE (1)
         block 1
         IF ( cond ) THEN
            SPAG_next_block_1 = 2
         ELSEIF ( cond2 ) THEN
            SPAG_next_block_1 = 3
         ENDIF
      CASE (2)
         block 2
         SPAG_next_block_1 = 3
      CASE (3)
         block 3
         IF ( cond2 ) EXIT SPAG_DispatchLoop_1  
         block 3 continued
         IF ( cond1 ) THEN
            SPAG_next_block_1 = 2
         ELSEIF ( cond2 ) THEN
            SPAG_next_block_1 = 1
         ENDIF
      CASE (4)
         ...
      END SELECT
   ENDDO SPAG_DispatchLoop_1

! item 41 = 0
      DO 10 i = 100 , 1 , -1
         IF ( qa(i) ) GOTO 12
 10   CONTINUE
 12   last = i

! item 41 = 1
      DO 10 i = 100 , 1, -1
         IF ( qa(i) ) GOTO 12
 10   CONTINUE
 12   CONTINUE
      last = i

! Item 42 = 1
      IF ( Q1 ) THEN
         X = Y
      ENDIF

! Item 42 = 2
      IF ( Q1 ) X = Y  

      IF ( a.EQ.b ) THEN
      ELSE
         X = Y
         ..
      ENDIF

      IF ( a.NE.b ) THEN
         X = Y
         ..
      ENDIF

! Item 45 = 1
      DO 100 i = 1 , n
         sum = sum + x(i)
 100  CONTINUE

! Item 45 = 3
      DO i = 1 , n
         sum = sum + x(i)
      ENDDO

      PARAMETER vdim=10

      PARAMETERVDIM = 10

      INTEGER FUNCTION random

      INTEGER functionrandom

      IF(a.GT.b)CALLsub

      IF(a.GT.b)CALL sub 

      COMMON /abc/ a,b,c
      ASSIGN 22 TO xx

      IF (a.GT.b) CALL sub

      IF (c.GT.d) THEN
      WRITE (*,*) a,b,c

      ! Item 67 = 0
            Y = X+(A*B-C)

      ! Item 67 = 1
            Y = X + (A*B-C)

      ! Item 67 = 2
            Y = X + (A*B - C)

      ! Misleading use of spacing
            Y = X+(A * B-C)

      ! Item 68 = 0
            Z=X*Y

      ! Item 68 = 1
            Z = X*Y

      ! Item 69 = 0
            QSW = b.GT.a.AND.b.LT.c

      !  Item 69 = 1
            QSW = b.GT.a .AND. b.LT.c

      !  Item 69 = -1
            QSW = b .GT. a .AND. b .LT. c

      ! Item 71 = 0
            IF (Q1) THEN

      ! Item 71 = 1
            IF ( Q1 ) THEN

      ! item 73 = 0
            zname = '*.'//zextn

      ! item 73 = 1
            zname = '*.' // zextn

            INTEGER i , j

            INTEGER i
            INTEGER j

     DATA zalph/'ABCDEFGHIJKLM
    &NOPQRSTUVWXYZ'/

      !*==TEST1.NEW

      !***_Start_of_Executable_Program

2.7 Using SPAG

2.7.1 Control Flow Restructuring

One of the primary functions of SPAG, the one that gives it its name, is the restructuring of control flow within subprograms. Obsolete constructs, such as GOTO, arithmetic IF and computed GOTO are replaced by block IFs, DO loops with EXIT and CYCLE, and SELECT CASE constructs. When restructuring is turned on (by setting item 1 to 3), SPAG's default settings are generally sufficient for most inputs. However the output can be tuned in various ways:

• Item 27 is set to 0 by default. This prohibits code relocation into an indexed DO loop, because SPAG cannot currently be sure whether the relocated code changes the DO loop variable. That would be a technical violation of the ISO standard, and compilers may, quite properly, report an error when it happens. However in most cases the relocated code does not alter the DO loop variable, and even if it did, the violation is a technical one, because the loop is exited immediately after the relocated code is executed.

  If item 27 is instead set to 1, you may be able to improve the restructured code somewhat, but run the risk that the SPAGged code may trigger a compiler error.

• Item 26 is set to 1 by default. This allows individual statements to be replicated if it appears that it may help inprove program structure. If it is set to 0, SPAG will typically find other ways (extra internal subroutines, or dispatch loop cases) to change the structure, which may or may not be preferred.

• The use of an !-ANCHOR directive (see section 2.7.10) in the input code forces SPAG to leave the following statement in place, and may result in a different output structure.

• Item 31 allows users to select between two alternatives - dispatch loops and internal subroutines - for removing GOTOs that remain after first stage restructuring. The following example illustrates the difference:

  Before Restructuring
  FUNCTION IUNITS(JDIF,KDIF,JU,KU,IP) INTEGER IP,IUNITS,JDIF,JU,KDIF,KU IUNITS=1 IF(JDIF)20,30,40 20 JU=-1 IF(KDIF)50,60,70 30 JU=0 KU=KDIF/IABS(KDIF) IP=4 RETURN 40 JU=1 IF(KDIF)70,60,50 50 IF(JDIF-KDIF)100,51,100 51 KU=JU IP=3 RETURN 60 KU=0 IP=4 RETURN 70 IF(JDIF+KDIF)100,71,100 71 KU=-JU IP=3 RETURN 100 IUNITS=0 RETURN END

  spag iunits.for 31=1 (Dispatch Loops)

  spag iunits.for 31=2 (Internal Subroutines)

  FUNCTION iunits(Jdif,Kdif,Ju,Ku,Ip) IMPLICIT NONE INTEGER Ip , iunits , Jdif , Ju , Kdif , Ku INTEGER :: spag_nextblock_1 spag_nextblock_1 = 1 SPAG_DispatchLoop_1: DO SELECT CASE (spag_nextblock_1) CASE (1) iunits = 1 IF ( Jdif<0 ) THEN Ju = -1 IF ( Kdif<0 ) THEN ELSEIF ( Kdif==0 ) THEN spag_nextblock_1 = 2 CYCLE SPAG_DispatchLoop_1 ELSE spag_nextblock_1 = 3 CYCLE SPAG_DispatchLoop_1 ENDIF ELSEIF ( Jdif==0 ) THEN Ju = 0 Ku = Kdif/iabs(Kdif) Ip = 4 RETURN ELSE Ju = 1 IF ( Kdif<0 ) THEN spag_nextblock_1 = 3 CYCLE SPAG_DispatchLoop_1 ENDIF IF ( Kdif==0 ) THEN spag_nextblock_1 = 2 CYCLE SPAG_DispatchLoop_1 ENDIF ENDIF IF ( Jdif/=Kdif ) THEN iunits = 0 RETURN ELSE Ku = Ju Ip = 3 RETURN ENDIF CASE (2) Ku = 0 Ip = 4 RETURN CASE (3) IF ( Jdif+Kdif/=0 ) THEN iunits = 0 ELSE Ku = -Ju Ip = 3 RETURN ENDIF EXIT SPAG_DispatchLoop_1 END SELECT ENDDO SPAG_DispatchLoop_1 END FUNCTION iunits

  FUNCTION iunits(Jdif,Kdif,Ju,Ku,Ip) IMPLICIT NONE INTEGER Ip , iunits , Jdif , Ju , Kdif , Ku iunits = 1 IF ( Jdif<0 ) THEN Ju = -1 IF ( Kdif<0 ) THEN ELSEIF ( Kdif==0 ) THEN CALL spag_block_1 RETURN ELSE CALL spag_block_2 RETURN ENDIF ELSEIF ( Jdif==0 ) THEN Ju = 0 Ku = Kdif/iabs(Kdif) Ip = 4 RETURN ELSE Ju = 1 IF ( Kdif<0 ) THEN CALL spag_block_2 RETURN ENDIF IF ( Kdif==0 ) THEN CALL spag_block_1 RETURN ENDIF ENDIF IF ( Jdif/=Kdif ) THEN iunits = 0 RETURN ELSE Ku = Ju Ip = 3 RETURN ENDIF CONTAINS SUBROUTINE spag_block_1 Ku = 0 Ip = 4 RETURN END SUBROUTINE spag_block_1 SUBROUTINE spag_block_2 IF ( Jdif+Kdif/=0 ) THEN iunits = 0 ELSE Ku = -Ju Ip = 3 RETURN ENDIF END SUBROUTINE spag_block_2 END FUNCTION iunits

• In general, the internal subroutine approach produces clearer code for simple cases like this. In more complex cases, the opposite is true. Internal subroutines may then be called recursively, and it's harder to understand what is going on. There is no limit in principle to how deep the recursion may go. The default for Item 31 is 2, which seeks to get the best of both worlds.

SPAG does not currently restructure some structures which cause a GOTO-like jump. These are:

• The assigned GOTO statement
• END=label and ERR=label clauses in I/O statements.
• Subprogram with "alternate returns"

2.7.2 Adding Declarations

Most older Fortran programs are written in an 'implicitly typed' environment. That is to say that variables are not formally declared at the head of each procedure as they are in Pascal or C; instead, variables are implicitly declared simply by using them. The compiler determines the type of the variable from the first letter of its name. For example, variables whose name begins with the letter 'I' are normally of type INTEGER.

No doubt this appeared to the pioneers who created Fortran as an advantage, and at first sight it may appear that the compiler is simply doing automatically what the programmer would otherwise have to do by hand. We now know that it is all too easy for the compiler to create variables in a way not intended by the programmer. A simple example illustrates the point:

        I0 = 0
        DO 10 i = 1.100
           READ *,j
           IO = I0 + j
   10   CONTINUE

In this example, the variable I0 is mis-typed as IO on line 4, and as a result a spurious new variable IO is created. Moreover, the second statement is, despite appearances, an assignment to the spurious REAL variable DO10I (spaces are not significant in Fortran). A language which requires explicit declarations would have spotted that IO and DO10I had not been declared, and reported an error at compile-time. But mis-spelling is not the only problem. Even commoner is confusion between local and COMMON variables. For example, if you INCLUDE a file which declares a COMMON variable named K, in a routine which has a local variable called K, all manner of obscure symptoms are possible.

Fortran can be made to require explicit typing. The IMPLICIT NONE statement, which disables implicit typing, is standard Fortran 95, but even Fortran 77 compilers generally accept it. Its use can be thoroughly recommended. As an alternative, some compilers have a compiler switch to disable implicit typing without resort to IMPLICIT NONE.

SPAG provides the means for converting existing, implicitly typed programs to explicitly typed programs for use with IMPLICIT NONE. It does this by adding explicit declarations for all undeclared variables at the head of each subprogram and INCLUDE file. Doing this by hand on a large program could take weeks - enough to make the switch impractical. However, the fact that SPAG can do it quickly doesn't mean it should be done carelessly; for example, there would be little point in doing it as a regular routine, as the benefits of explicit typing are then lost. Ideally, the declarations inserted by SPAG should be checked for spurious entries caused by past mistakes. However, explicit typing will help prevent future errors even if some past errors remain.

The 'auto-declarer' feature of SPAG is activated by setting item 4 of spag.fig greater than 0. If it is set to 1, declarations are inserted for all undeclared variables, parameters, dummy arguments and functions other than intrinsic functions (whose names are read from a file - see item 210 of spag.fig). Intrinsic functions are excluded because their type may vary (e.g. MIN may be REAL in one place and INTEGER in another). If item 4 of spag.fig is set to 2, SPAG also inserts an IMPLICIT NONE statement, and removes any pre-existing IMPLICITs (provided that they are not in an INCLUDEd file).

For example, given the following code:

      SUBROUTINE STATE(U1,U2,U3,U4,U,V,Rho,P,E,T,Mx,My)
      IMPLICIT REAL*8(A-H,O-Z)
      PARAMETER (NX=150,NY=150)
      DIMENSION U(NX,NY) , Rho(NX,NY) , V(NX,NY) , E(NX,NY)
      DIMENSION P(NX,NY) , U1(NX,NY) , U2(NX,NY) , U3(NX,NY) ! comment
      DIMENSION U4(NX,NY) , T(NX,NY)
      gma = DBLE(14)/DBLE(10)
      one = DBLE(1)
      p5 = DBLE(5)/DBLE(10)
      gcn = (gma-one)
      rr = 287.0
      DO i = 1 , Mx
         DO j = 1 , My
            Rho(i,j) = U1(i,j)
            E(i,j) = U4(i,j)/U1(i,j)
            U(i,j) = U2(i,j)/U1(i,j)
            V(i,j) = U3(i,j)/U1(i,j)
            P(i,j) = gcn*Rho(i,j)                                       &
     &               *(E(i,j)-p5*(V(i,j)*V(i,j)+U(i,j)*U(i,j)))
            T(i,j) = P(i,j)/(Rho(i,j)*rr)
         ENDDO
      ENDDO
      CALL SUB2(U4)
      CONTINUE
      END

then if item 4 is set to 2, SPAG produces:

SUBROUTINE state(U1,U2,U3,U4,U,V,Rho,P,E,T,Mx,My)
   IMPLICIT NONE
!*** Start of declarations inserted by SPAG
   REAL*8 E , gcn , gma , one , P , p5 , Rho , rr , T , U , U1 , U2 , U3 , U4 , V
   INTEGER i , j , Mx , My , NX , NY
!*** End of declarations inserted by SPAG
   PARAMETER (NX=150,NY=150)
   DIMENSION U(NX,NY) , Rho(NX,NY) , V(NX,NY) , E(NX,NY)
   DIMENSION P(NX,NY) , U1(NX,NY) , U2(NX,NY) , U3(NX,NY)    ! comment
   DIMENSION U4(NX,NY) , T(NX,NY)
   gma = dble(14)/dble(10)
   one = dble(1)
   p5 = dble(5)/dble(10)
   gcn = (gma-one)
   rr = 287.0
   DO i = 1 , Mx
      DO j = 1 , My
         Rho(i,j) = U1(i,j)
         E(i,j) = U4(i,j)/U1(i,j)
         U(i,j) = U2(i,j)/U1(i,j)
         V(i,j) = U3(i,j)/U1(i,j)
         P(i,j) = gcn*Rho(i,j)*(E(i,j)-p5*(V(i,j)*V(i,j)+U(i,j)*U(i,j)))
         T(i,j) = P(i,j)/(Rho(i,j)*rr)
      ENDDO
   ENDDO
   CALL sub2(U4)
END SUBROUTINE state

2.7.3 Rewriting Declarations

SPAG can also rewrite the declaration section of a subprogram from scratch, using either Fortran 77 or Fortran 95 declaration style. This is done by setting item 4 of the configuration data to 4 or 6 respectively.

For the example above, if item 4 is set to 6 and item 16 to 1, SPAG produces:

SUBROUTINE state(U1,U2,U3,U4,U,V,Rho,P,E,T,Mx,My)
   USE ISO_FORTRAN_ENV
   IMPLICIT NONE
!
! PARAMETER definitions rewritten by SPAG
!
   INTEGER , PARAMETER :: NX = 150 , NY = 150
!
! Dummy argument declarations rewritten by SPAG
!
   REAL(REAL64) , INTENT(IN) , DIMENSION(NX,NY) :: U1
   REAL(REAL64) , INTENT(IN) , DIMENSION(NX,NY) :: U2
   REAL(REAL64) , INTENT(IN) , DIMENSION(NX,NY) :: U3
   REAL(REAL64) , DIMENSION(NX,NY) :: U4
   REAL(REAL64) , INTENT(INOUT) , DIMENSION(NX,NY) :: U
   REAL(REAL64) , INTENT(INOUT) , DIMENSION(NX,NY) :: V
   REAL(REAL64) , INTENT(INOUT) , DIMENSION(NX,NY) :: Rho
   REAL(REAL64) , INTENT(INOUT) , DIMENSION(NX,NY) :: P
   REAL(REAL64) , INTENT(INOUT) , DIMENSION(NX,NY) :: E
   REAL(REAL64) , INTENT(OUT) , DIMENSION(NX,NY) :: T
   INTEGER , INTENT(IN) :: Mx
   INTEGER , INTENT(IN) :: My
!
! Local variable declarations rewritten by SPAG
!
   REAL(REAL64) :: gcn , gma , one , p5 , rr
   INTEGER :: i , j
   EXTERNAL sub2
!
! End of declarations rewritten by SPAG
!
   gma = dble(14)/dble(10)                                   ! comment
   one = dble(1)
   p5 = dble(5)/dble(10)
   gcn = (gma-one)
   rr = 287.0
   DO i = 1 , Mx
      DO j = 1 , My
         Rho(i,j) = U1(i,j)
         E(i,j) = U4(i,j)/U1(i,j)
         U(i,j) = U2(i,j)/U1(i,j)
         V(i,j) = U3(i,j)/U1(i,j)
         P(i,j) = gcn*Rho(i,j)*(E(i,j)-p5*(V(i,j)*V(i,j)+U(i,j)*U(i,j)))
         T(i,j) = P(i,j)/(Rho(i,j)*rr)
      ENDDO
   ENDDO
   CALL sub2(U4)
END SUBROUTINE state

SPAG breaks the declarations into four labelled sections, any of which may be absent:

• PARAMETERs. These are placed at the start of the declaration section, and remain in their original order (in case the definitions are interdependent). Here and elsewhere, constant expressions are not evaluated, but are preserved in their original forms.
• COMMON variables. If necessary, dimensioning information is moved from the COMMON statement to the type declaration.
• Dummy Arguments. SPAG optionally adds INTENT statements based on how the argument is actually used in the subprogram. For example arguments which are never modified are specified in an INTENT(IN) statement. In the above example U4 has no intent is added, because U4 may be changed in sub2.
• Local variables. In the Fortran 95 version, arrays with identical type and dimension information are grouped together so that the dimension data is specified only once.

Because of the fundamental nature of the rewriting process, it is not possible to retain comments in their original relation to declarations. Thus, in the above example, comments which were attached to the old declarations are grouped together after the rewritten code.

The original code uses REAL*8 which is a common extension, but not ISO standard Fortran. SPAG has converted the code to standard FORTRAN using the kind definitions from the standard ISO_FORTRAN_ENV module.

SPAG cannot rewrite declarations containing some Fortran 2003 features, such as abstract interfaces and bound procedures. SPAG issues a warning message, and suppresses rewriting if this situation occurs.

INCLUDE statements from the original code are, depending on item 14 of spag.fig, rewritten as modules, or placed before the first rewritten declaration. As a result:

• Declarations in the INCLUDEd file may not depend on local declarations. In particular, a local PARAMETER may not be referenced in an INCLUDEd file. However, PARAMETERs from INCLUDEd files may be used in local declarations.
• INCLUDEd files should not contain executable statements, statement functions or DATA statements, or Fortran statement ordering rules may be violated.

2.7.4 Converting INCLUDE files to MODULEs "on the fly"

SPAG can convert INCLUDE files containing COMMON blocks and associated declarations into modern Fortran modules on the fly - as it processes the corresponding INCLUDE statement. If item 14 of spag.fig is set to 1, SPAG automatically converts INCLUDE statements to USE statements. This option should not be used if INCLUDE files contain other code, such as executable code, or local variable declarations, or INTERFACE declarations.

On the first occurrence of an INCLUDE file SPAG creates a file containing the corresponding MODULE. The INCLUDE files should not be explicitly listed as input files for SPAG - they are discovered because of their presence in the INCLUDE statement.

SPAG derives the module name from the INCLUDE file name by discarding the directory and extension, and prefacing the two characters i_. For example, an INCLUDE file called f:\include\abc.inc will be translated to a module called i_abc. This module is written to a file called \moddir\i_abc.xyz, where \moddir\ is the directory specified in item 229 (or 236), and .xyz is the extension specified in item 237.

To be translated correctly, the INCLUDE file must contain only INCLUDE, PARAMETER, COMMON and EQUIVALENCE statements, together with associated type and dimension statements. There should be no EQUIVALENCE statements outside the INCLUDE file that refer to its contents. SPAG will issue an error message if these rules are violated.

An advantage of this method is that SPAG sees the full context, avoiding the ambiguity that can arise when an INCLUDE file is processed in isolation. A problem is that, in the current implementation, comments from the INCLUDE file are not transferred to the MODULE.

2.7.5 Converting isolated INCLUDE files

SPAG can also process INCLUDE files in isolation. When SPAG encounters an input with no subprogram or END statement, it assumes it is an INCLUDE file, and converts it to a MODULE, by adding or rewriting declarations as specified in item 4 of spag.fig, and adding MODULE and END MODULE statements. Each INCLUDE file should be processed in a separate run. In order for this to work correctly, it is necessary to ensure that INCLUDE file contains sufficient information to define the type and nature of every symbol in it.

For example, if an INCLUDE file contains the single statement

       COMMON /ABC/  XX(N),I,J,K

we cannot determine the type of any of the variables. We know that XX is an array, but I, J and K may be too. We can infer that N is an INTEGER PARAMETER, but we don't know its value, or whether it is a 1, 2 or 4 byte INTEGER. It is even possible that the same INCLUDE file means different things in different places.

In cases like this, it is best to insert extra statements to fill in the missing information. For example, if you insert the two lines:

        IMPLICIT LOGICAL(A-J,O-Z),INTEGER*2 (K-N)
        PARAMETER (N=200)

then SPAG will be able to do a much better job. You should remove the redundant IMPLICIT statement when SPAG has finished (we recommend that IMPLICIT statements should never be placed in INCLUDE files).

The objective is to ensure that before processing, each INCLUDE file is self-contained, and not reliant on context to define its meaning. In fact this is a good principle in general: if all INCLUDE files are constructed this way, many subtle bugs are eliminated (e.g. the size of XX varies because there are multiple non-identical definitions of N).

A disadvantage of this method is that the user must also convert the INCLUDE statements to USE statements

SPAG currently has no mechanism for converting BLOCKDATA segments which initialize COMMON variables to a form which is compatible with MODULEs.

2.7.6 COMMON block Modules

SPAG can also translate COMMON blocks to MODULEs on the fly - as it processes the host subroutine. This option is activated by setting item 13 of spag.fig greater than 0. However it is strongly recommended that this should not be done unless you have previously checked by hand that every instance of a COMMON block is identical. In particular:

• For each COMMON block, every definition must be identical - not only the variable types and array sizes, but also the variable names.
• PARAMETERs may not be used in COMMON array declarations.
• No COMMON variable may occur in an EQUIVALENCE statement.
• COMMON blocks must not occur inside and outside an INCLUDE file.

SPAG may not warn if these conditions are not met, and may produce invalid code as a result.

Despite these limitations, this facility can save a lot of work if the conditions are met, by automatically separating and removing declarations associated with COMMON blocks from the host subprograms.

SPAG derives the module name from the COMMON block name by discarding the '/'s, and prefacing the two characters c_. For example, a COMMON block called /HELLO/ will be translated to a module called c_hello. This module is written to a file called \moddir\c_hello.xyz, where \moddir\ is the directory specified in item 236, and .xyz is the extension specified in item 237.

2.7.7 Interface Modules

If item 15 of spag.fig is set to 1, SPAG creates modules containing interfaces for every subroutine or function it processes. It also inserts appropriate USE statements at the head of the calling subprograms. Together, these changes make it possible for a Fortran 95 compiler to check that the arguments in every subprogram reference match the corresponding dummy arguments.

At first sight, this may seem a pointless exercise, as plusFORT manages the same checks, and more, without any help from the user! However the modules can also be passed to others, and this will allow them to check interfaces without having access to the source code.

If the called subprogram name is abc, the interface module name will be s_abc, and it will be stored in a file as specified by items 11, 236 and 237 of spag.fig.

If the program calls a subprogram that has not been processed by SPAG, there is no interface module to satisfy the reference in the calling subprogram's USE statement. In this case, the user must either provide an interface module to satisfy the reference, or remove the USE statement.

The facilities described in this and the following two sections may be used as a prelude to a more thorough reorganization along modular lines. Section 3.7 describes facilities offered by plusFORT to assist ib a high-level restructuring exercise of that type.

2.7.8 Removing Clutter

As programs are developed, variables, parameters, COMMON blocks and code fragments fall into disuse. Programmers are often reluctant to remove such 'clutter' because of the possibility of un-looked for side effects. However over a period, clutter can make programs more obscure and difficult to maintain than they need be. SPAG can remove many types of clutter, and identify many others. Specifically, SPAG can remove the following (provided they are not defined in an INCLUDEd file):

• unused and uninitialized local variables (if item 3 of spag.fig > 1).
• unused PARAMETERs and local variables initialized in a type statement (if item 3 of spag.fig > 2).
• unused COMMON blocks (if item 3 of spag.fig > 3).
• unused INCLUDE files (if item 3 of spag.fig > 4).
• inaccessible code fragments (if item 29 of spag.fig > 0).

If item 3 is set to 1, and item 29 to 0, SPAG identifies, but does not remove the above.

ISO standard Fortran allows compilers to allocate memory for COMMON blocks dynamically. Theoretically, a COMMON block becomes undefined if it is not referenced by any executing subprogram. In practice, most, if not all current compilers treat COMMON blocks as static, and many users would be confused and dismayed if they did not!

If SPAG removes an unreferenced COMMON block, the point at which the COMMON theoretically becomes undefined may also be altered. If you wish to avoid this possibility, specify the COMMON block name in a SAVE statement, set item 3 of the SPAG configuration data to 3 or less, or ensure that all COMMONs are specified in the main PROGRAM (SPAG never removes COMMONs or INCLUDEs from a main program or BLOCK DATA).

SPAG identifies, but cannot remove

• unused dummy arguments.
• local variables which are assigned a value or initialized in a DATA statement, but never referenced.
• local variables which are used, but never assigned a value.

The GXCHK program which uses the symbol tables written by SPAG to construct a global symbol table for an entire program identifies clutter on a program-wide basis (e.g. globally unused COMMON variables).

2.7.9 Renaming Symbols

SPAG provides a simple and safe method for systematically changing the names of symbols within a program. SPAG guards against the danger of choosing a new name which is already in use, and re-formats the source code appropriately. The rename facility is activated by setting item 5 of spag.fig to 1, and specifying the name of a file containing details of the required changes in item 211.

A sample rename file is shown below. The file consists of a series of sections, separated by blank lines. The first line of each section specifies the scope of the following instructions. The remaining lines in the section specify the before and after names, separated by spaces, of the symbol to be renamed. If the scope is '*', the changes are applied without restriction. This could be used, for example, to change specific function names, such as AMAX0, to the generic form (MAX). If the scope is a file-name surrounded by apostrophes, the changes are made only if the specified file is INCLUDEd in the current subprogram. Note that the INCLUDE file itself is not changed - only the references to it in the current subprogram. If the scope is a subprogram name, the changes are made only within the specified subprogram.

Example Rename File

   *
    AMOD10         mod
    AMIN1          min

    'test1.prv'
    fchsta         firstc
    zsyst          zzzsys
    /pkchAR/       /pkcomm/

    swstx2
    ityp           jtyp
    jtyp           ityp
    lopbr          lclbr
    lclbr          lopbr

    swfrag
    oxo            xox

2.7.10 The 'ASIS' Directive

In some circumstances, it may be desirable to suppress the re-formatting of statements. This is particularly true when a long declaration has been carefully aligned by hand to give a particular visual effect. SPAG allows you to suppress re-formatting by inserting a directive of the form

      !-ASIS

in the source code. This directive governs only the immediately following statement. Compilers treat the directive as a comment. C-ASIS and *-ASIS are accepted as alternatives in fixed format source code.

For example

      !-ASIS
            DATA XOX /  1 , 0 , 1
           &         ,  0 , 1 , 0
           &         ,  1 , 0 , 1 /

!-ASIS can be used safely with any declaration statement. However it is, in general, not safe to use !-ASIS with executable statements or others, such as FORMAT, which may be labelled. In such cases SPAG leaves the statement label unchanged, even if the code is re-labelled. In other cases the original code may no longer be appropriate. For example, SPAG may reverse the logic in a block IF statement, or convert it to an ELSEIF. These changes will not be apparent in the output code if !-ASIS is used on executable statements. Despite these problems, we have, because of user demand, decided to retain the option of using !-ASIS on executable statements. SPAG issues a warning for every unsafe usage; it is up to the user to hand-check code when such a warning is issued.

Item 60 of the configuration file allows you to specify that all declaration statements should be treated as though prefaced by !-ASIS This switch is suppressed if item 4 specifies that declarations are to be rewritten.

2.7.11 The ANCHOR Directive

Occasionally, it may be desirable to prevent the relocation of a block of statements. This can be done by inserting a !-ANCHOR directive immediately before the first statement of the block. The first statement of a block is preceded by a conditional or unconditional control transfer, such as an IF or GOTO statement. Subsequent statements in the block are always executed if first is executed. The anchored statement must be an executable statement. Note that even when a statement is anchored, it is possible that surrounding code may be relocated in such a way that it appears to move. C-ANCHOR and *-ANCHOR are accepted as alternatives in fixed format source code.

2.7.12 Comments in Restructured Code

Comments are presumed to be attached to the statement that follows them, and as the code is restructured, are moved around in the same way as that statement. End-of-line comments are an exception, and are attached to the statement with which they share a line. Another exception is comments preceding statements which are removed from the program (e.g. CONTINUE or GOTO statements which are not needed in the unscrambled code). These are attached to the statement following the redundant statement. The net result is that SPAG preserves comments and usually puts them in the right place.

2.7.13 Using Case to make Programs more Readable

Because of its antiquity, Fortran has always been an upper-case language. Even today, some Fortran programmers stick entirely to upper-case, even though mixed case is permitted by every major compiler (and is standard Fortran 95). This is a shame, because an important opportunity to make programs self-documenting is being missed. SPAG can be configured to make full use of case to distinguish different types of symbol. For example you can make special symbols (such as PARAMETERs and subprogram names) upper case; symbols which refer to global data (such as COMMON variables and dummy arguments) could be capitalized (e.g. Arg); and local variables could be lower case. A scheme like this helps programmers to know what they are looking at without constant reference to the declaration section.

2.7.14 Symbol Table Output

If item 2 of spag.fig is set to 2, SPAG generates symbol table files which provide valuable information about data usage within subprograms. These files are used by GXCHK, the global cross check program, to generate an overview of data usage within an entire program. The process is analogous to the more familiar procedure of compiling and linking. The symbol tables are analogous to object files, and GXCHK works like a linker to combine them into a single global report. Indeed, the AUTOMAKE tool, which automates compiling and linking can also be used to rebuild the global report file.

Symbol tables are plain ASCII text files, the format of which is described in detail in Appendix A. Users are encouraged to develop their own applications using these files as input. For example it would be a simple matter to write a program to check conformance to local variable naming conventions.

2.7.15 Some Pitfalls

• When SPAG converts an arithmetic IF or computed GOTO into an equivalent block IF, it may produce code which can execute a FUNCTION reference more often than in the original code. Apart from efficiency considerations, this is undesirable because the function may have side effects which alter the results obtained. SPAG issues a warning message when this possibility arises. Functions which are identified as safe (see items 12 and 210 of the configuration file) will not trigger a warning. A simple and safe fix is to place the result of the function reference in a local temporary variable, which is used in the following arithmetic IF or computed GOTO.

     IF ( A1*FUNC(X) ) 100,200,300

  becomes

      TEMP = A1*FUNC(X)
      IF ( TEMP ) 100,200,300

• SPAG leaves some Fortran flow control structures unmodified (apart from re-labelling). These include ASSIGN and assigned GOTO, END= and ERR= in I/O statements, and alternate returns in CALL statements.
• When SPAG re-formats long statements, it may increase the number of continuation lines. In extreme cases, this could result in a statement having more than the 39 continuation lines allowed by the ISO standard (19 for Fortran 77).
• Some versions of the IBM mainframe VS Fortran compiler do not allow block IF statements to be nested more than 25 deep, and count each ELSEIF statement as an extra level of nesting. SPAG sometimes produces code which exceeds this limit, particularly when translating computed GOTO statements into block IFs. Translation of computed GOTOs can be suppressed by changing item 20 in the configuration file.

2.8 Dynamic Analysis

2.8.1 What is it?

Dynamic analysis is a simple procedure for validating the operation of a program at run-time. It involves setting up a test version of your program containing extra checking code. This test program is compiled and linked in the normal way. The executable code appears to the user to operate in exactly the same way as the original, though it is larger and slower. If the checking code detects an error, it writes details to a log-file (probes.log), and continues execution. The programmer can then view the log-file at leisure after the run completes.

2.8.2 Worked Example

The example below shows how dynamic analysis works:

      SUBROUTINE QKNUM(Ival,Pos)
      INTEGER Ival , Pos , vals(50) , ios
      READ(11,*,IOSTAT=ios) vals
      IF ( ios.EQ.0 ) THEN
         DO Pos = 1 , 50
            IF ( Ival.EQ.vals(Pos) ) RETURN
         ENDDO
      ENDIF
 100  Pos = 0
      END

QKNUM is a simple routine which reads a list of 50 integers from a data file; the position of the first in the list with value Ival is returned in Pos. If none is equal to Ival, or if an error or end-of-line condition occurs while reading the list, Pos is returned as 0.

Most of the time, QKNUM will probably work well. Compilers and static analyzers are unlikely to find anything wrong with it, but nevertheless, it does contain a logical flaw. If the data file contains:

 2,9,,11,20*44,26*

Then items 1, 2 and 4 to 24 are assigned values. Items 3 and 25 to 50 remain unchanged from their initial (undefined) value. The result of the test on line 6

 IF ( Ival.EQ.vals(Pos) ) RETURN

is therefore undefined, and the program will behave unpredictably.

Whilst this particular bug is not common, it does illustrate, in a compact example, two features which are common to many bugs, and which defeat static analysis:

• Dependence on external data. The way a program executes depends on what data it gets. A static analyzer cannot know that.
• Use of arrays. Static analyzers normally treat arrays as amorphous blobs of data: if any part of an array is defined, then the whole array is assumed to be defined.

A version of QKNUM modified to perform a dynamic analysis might appear as follows:

      SUBROUTINE QKNUM(Ival,Pos)
      INTEGER Ival , Pos , vals(50) , ios
! insert 'undefined' value in ios
      CALL UNDFI(ios)
! insert 'undefined' value in every element of vals
      CALL UNDFIA(vals,50)
      READ(11,*,IOSTAT=ios) vals
! check that ios is defined
      IF ( ios.EQ.UNDEF ) CALL ERROR
      IF ( ios.EQ.0 ) THEN
         DO Pos = 1 , 50
! check that Ival and vals(Pos) are defined
            IF ( Ival.EQ.UNDEF ) CALL ERROR
            IF ( vals(pos).EQ.UNDEF ) CALL ERROR
            IF ( Ival.EQ.vals(Pos) ) RETURN
         ENDDO
      ENDIF
 100  Pos = 0
      END

The modified code contains a new section which initializes all local variables to a special 'undefined' value. This section is executed immediately after QKNUM is entered. Dummy arguments and COMMON variables are NOT initialized - they are assumed to be initialized higher up the call tree.

In addition a test is inserted wherever the value of a variable is used. For example, the test

 IF ( Ival.EQ.vals(Pos) ) RETURN

is meaningless if either Ival or vals(Pos) is undefined. The code therefore contains tests for both items. The variable Pos is also used, and, at first sight it may appear necessary to check Pos before testing vals(Pos). However, in this case we can deduce that Pos must be defined because it is a DO loop variable.

A version of QKNUM modified in this way will log an error when the input data leaves elements of vals undefined.

2.8.3 Dynamic Analysis using SPAG

When the dynamic analysis option of SPAG is activated (by setting item 1 of the configuration data to 4), it modifies the program to perform a dynamic analysis. The details differ from the above example, but the principles are identical. The modifications are automatic and require no user intervention. SPAG knows about variables initialized in DATA or type statements, and does not re-initialize them. It also distinguishes static variables (specified using SAVE) from others. Static variables are initialized only once - when first entering the subprogram that defines them. Other local variables are re-initialized to the undefined value every time a subprogram is entered. If item 36 of the configuration data is set to 1, all local variables are assumed to be static. This is probably the safest starting point for programs of unknown history.

The SPAG Dynamic analysis tool works with Fortran 77 and Fortran 95 input code. However the instrumentation may currently be incomplete when certain Fortran 95 features, such as derived types, are present. Although the instrumented code is fully functional, dynamic analysis may not report some illegal uses of undefined data involving these cases. SPAG does deal correctly with many Fortran 95 features, such as allocatable arrays and array sections.

The instrumentation code inserted by SPAG may make use of the standard Fortran 95 SIZE and KIND intrinsic functions. If the target code overrides the default meaning of those symbols, for example by using them as variable names, the resulting code will fail to compile. In such cases some manual intervention may be required to resolve the conflict.

2.8.4 COMMON Variables

One area which may benefit from a little attention from the user is the initialization of COMMON variables to the undefined value. If this is not done, the instrumented dynamic analysis code will be fully functional, but will not report errors involving COMMON variables that have not been initialized.

SPAG inserts code to initialize COMMON variables at the start of the main program immediately after the program starts. It follows that all COMMON variables must be available within the main program. This may require some hand-edits to your program, perhaps to insert some INCLUDE statements in the main program. SPAG does not do this automatically, but GXCHK (see Chapter 3) will tell you of any COMMON blocks which are not specified in the main program.

2.8.5 Initialized COMMON Variables

One final precaution is necessary: COMMON variables may be initialized using DATA statements in a BLOCKDATA subprogram. Many compilers also allow COMMON variables to be initialized in other ways, for example, in type statements within a subprogram. We must ensure that the initialization code generated by SPAG does not overwrite these genuine initializations in BLOCKDATAs or elsewhere.

This is achieved by running GXCHK (see Chapter 3) after SPAG has finished. If COMMON variables are initialized anywhere in the source code, GXCHK modifies the dynamic analysis version of the main program to remove the statements which would overwrite the initialization. This process is automatic, and requires no user intervention.

2.8.6 Summary

The steps required to perform a dynamic analysis of a Fortran program using SPAG and GXCHK are as follows:

• Make sure that every COMMON variable is specified in the main program.
• Run SPAG with the dynamic analysis option activated.
• Run GXCHK on the symbol tables produced by this SPAG run. Check the output for error messages.
• Compile and link the SPAGged code with probes.f90. You may have to add switches to tell the compiler to ignore argument mismatch errors. For example when using gfortran, compile with the -fallow-argument-mismatch switch. This is necessary because probes.f90 needs to access memory without regard to its type, in a way that Fortran does not normally allow. Before SPAG finishes, it copies probes.f90 from the plusFORT release directory to the directory specified in item item 229 of the configuration data.
• Run the program in the normal way, on as many test data sets as possible. After each run, review the contents of the log-file probes.log.

2.8.7 False Positives

It is possible, though extremely rare in practice, for the probes to report an error when there is none. This happens if the 'undefined' bit pattern occurs as the normal result of a calculation within the program. For 32 and 64 bit data items, this possibility is vanishingly small. Even for 8 and 16 bit data, it happens sufficiently rarely that, for most users, the benefits of the test will outweigh the inconvenience of checking for false positives.

Item 35 of the SPAG configuration data specifies the minimum size (in bytes) of numeric and logical data items to be tested using dynamic analysis.

Item 35 does not apply to CHARACTER strings, because their length is not generally known until run-time. Instead, there is a test within the probe itself. Users may modify the source code of the probe as required (see Appendix B).

2.8.8 Mixed Code

Code containing dynamic analysis probes can be mixed freely with normal code. Similarly, the use of external object files and libraries presents no problems. Of course, checks will only be performed within instrumented code, and checks are inneffective when applied to data which has not been intitialized to the undefined value.

2.8.9 EQUIVALENCE & Dynamic Analysis

Dynamic analysis is not put off by EQUIVALENCEd data, or by COMMON blocks whose structure varies from one subprogram to another (provided that the version which appears in the main program includes the entire data area).

2.8.10 Static or Dynamic?

SPAG and GXCHK offer facilities for both static and dynamic analysis, and the two are complimentary. Each excels where the other is deficient.

A static analyzer checks all your code, whether it executes or not; it produces useful results without the need to perform test runs; it produces documentation which is of general use to managers and staff working on the program. On the other hand, a static analyzer cannot hope to predict the effect of external data on your program's execution, or to monitor the status of every byte of memory.

Dynamic analysis, on the other hand, operates when your program is running with real data, and can monitor memory at the byte level. The main disadvantage of dynamic analysis is that, unlike static analysis, it does not check all your code, only the parts that execute in a given run.

This disadvantage can be overcome to some degree by using coverage analysis (see Section 2.9 and Chapter 4) to ensure that your test program exercises all of your source code.

Working together, static, dynamic, and coverage analysis provide an unrivalled health check for your programs.

2.9 Coverage Analysis

SPAG contains facilities for inserting probes into Fortran source code for the purpose of analyzing the run-time performance. These probes may be used to detect execution hot-spots, identify untested code-blocks, or provide a profile of CPU usage.

If item 6 of the configuration data is set to 2, SPAG prepares your code for coverage analysis testing by:

• Writing a special test version of your program which contains probes to monitor control flow. The test version should be compiled in the normal way, and linked with the plusFORT probe routines (see Appendix B). The program will execute normally, albeit somewhat more slowly.
• Writing files containing a coverage information block for each subprogram. The coverage information block specifies the start line number of every linear code block, and how many times it has been executed. At the end of every coverage analysis run, these files are updated to show the cumulative usage of every code block. A separate program called CVRANAL (see Chapter 4) may be used to annotate the source code (so that usage counts appear as comments in columns 73-80), and produce a concise summary of hot-spots and untested code.
• Copying the probe source code (probes.f90) from the plusFORT release directory to the directory specified in item item 229 of the configuration data.
• By default, versions 7.10 and later of plusFORT set item item 229 to the name of a directory into which SPAG will write output files, including the coverage analysis data files. If this default behaviour is over-ridden, and item item 229 is not set, you must, in addition, set item 234 to specify the name of the directory where SPAG will store the coverage analysis data files. It is recommended that you create a directory especially for this purpose before running SPAG. The directory should be specified using an absolute path (not a relative one). This ensures that the test program can always find the data files.

A weaker form of program tracing is invoked by setting item 6 of the SPAG configuration data to 1. With this setting, tracing takes place only at the subprogram level, and no coverage analysis data files are produced. In conjunction with the plusFORT probe routines this is sufficient to produce a profile of CPU usage by subprogram like that shown below. By default, the report is written to a file called probes.log. However, this and other details can be adjusted by modifying the source of the probe routines which may be found in the installation directory.

  ------------------------------------------------
 |                 Timing Reports                 |
 |     Job completed after      35.71 seconds     |
 |    Routines taking >1% of total shown below    |
  ------------------------------------------------

              MATTEST          4 calls   0% --------------------------------------------------
                   NF          1 calls   0% --------------------------------------------------
                 NFCG          4 calls   4% **------------------------------------------------
           NF3DPRECON        137 calls   3% **----------------------------------------
           NF2DPRECON      27381 calls   9% *****-----------------------------------
             TRISOLVE    5763813 calls  72% ************************************
              SPMMULT        141 calls  11% ******
              GETGI3D          4 calls   0% -
              GETGI2D        396 calls   0% -

(* excludes called routines, - includes them)
    5791881 Intervals timed

See Appendix B for further details.

Either form of coverage analysis depends on data written when the test program finishes. If the program is interrupted, or if execution is halted by a routine which does not contain probes, the required data is not written, and coverage analysis fails for this run (though no damage is done to the data files). This can happen if you call a system routine (e.g. CALL EXIT) to halt execution. The problem may be avoided by inserting a call to the program termination probe, SPAG_PR_EXI, just before the call to EXIT.

      CALL SPAG_PR_EXI
      CALL EXIT(16) 

If dynamic analysis (section 2.8) is activated, item 6 is automatically set to 1.

2.10 Processing Fortran 95 Modules

The USE statement in Fortran 95 allows a subprogram to import data and interfaces from a separately compiled module. It is in many ways analagous to an INCLUDE statement, and is generally recommended as a superior replacement for both INCLUDE and COMMON. In order to interpret USE correctly, SPAG must import information about the external module. It does this by reading the symbol table generated when SPAG processed the module. This gives rise to 2 problems:-

• SPAG needs to know the location of the symbol file.

  To do this, SPAG maintains a ASCII text file called PFMODULE.KEY. This file contains records which specify the location of each module USEd by source code in the current directory. For example

        TRAJECTORY : traject.smb

  specifies that the symbol table for module TRAJECTORY is in the file traject.smb.

  As SPAG processes source code, it automatically inserts records in PFMODULE.KEY for every module it encounters. When SPAG encounters a USE statement, it consults this file to find the module data.

  An exception to this rule is that SPAG will not automatically find modules from a different directory. In this case it is recommended that the locations of modules be inserted in PFMODULE.KEY using a text editor.

        GPS_COORDS : gps\coordmod.smb

• The module must already have been processed by SPAG.

By default SPAG automatically reorders input files to ensure that modules are processed before code that USEs them (see Item 9). This works well if both MODULE and USEr are processed by SPAG in a single run. It is recommended that, wherever possible, multiple input files, possibly using wildcards, should be processed in a single, rather than multiple invocations of spag.

If SPAG encouters a USE statement for a module that has not been not processed in the current run, it looks in PFMODULE.KEY to find the location of the symbol data for that module. If it finds that there is no entry, because the module has not been processed yet, it reports an error. It's also possible that, if a module is changed, SPAG may use an obselete symbol table, and produce incorrect results while appearing to work correctly. This is similar to the problem, familiar to most Fortran programmers, that occurs when modules are not compiled before code that USEs them.

The plusFORT AUTOMAKE tool provides an alternative solution to this problem (just as it does for compilers). It is recommended for cases where SPAG must be invoked separately for each input file. The plusFORT installation directory contains a batch/shell file called Autospag, which uses AUTOMAKE to run SPAG in such a way that the processing order requirements are satisfied. A small configuration file called autospag.fig should be placed in the source directory. A typical case, in which all .f90 files are to be processed, and the symbol table files have the .smb extension would be handled by the following configuration file:

      COMPILE=@spag %fi
      OBJEXT=SMB
      FILES=*.f90
      NOQUITONERROR

Then to run SPAG on all .f90 files in the current directory, simply type Autospag. More complicated cases can be handled with suitable changes to autospag.fig (see the AUTOMAKE documentation)