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. But 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 (77 or 95), or apply a final polish to well written modern code. Progress can be monitored using 'Before and After' complexity metrics.
• 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.
• SPAG can insert explicit type declarations for IMPLICITly typed variables, or rewrite the declarations from scratch using either Fortran 77 or Fortran 95 declaration style.
• SPAG can translate VAX structures to Fortran 95 derived types.
• 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 Fortran 77, and code with Fortran 95 extensions 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 make re-formatted code even clearer by using upper and lower case to distinguish different types of symbol.
• 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.
• SPAG can use dynamic analysis to identify variables by their contents at run-time. This facility can, for example, be used to identify variables containing dates, as an aid to Year 2000 compliance testing.
• 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 77, VAX Fortran, and almost all Fortran 95, together with many common extensions, such as Cray pointers, ENCODE/DECODE etc.

2.1.2 Code Restructuring

SPAG can unscramble spaghetti Fortran 66 code, and convert it to modern and structured Fortran 77 or 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, but that is only the beginning. 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.

SPAG does not always remove all GOTOs. Sometimes, this could only be done by replicating large tracts of code, with a consequent reduction in readability and maintainability. SPAG concentrates on code rearrangement, with occasional replication of small code fragments. This is the approach programmers invariably take when faced with the task of restructuring by hand, and it works well in practice.

2.1.4 Translation to Fortran 95

In addition to translating source form, declaration style, and control constructs to Fortran 95, SPAG can also translate COMMON blocks and INCLUDE files to Fortran 95 modules. SPAG 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.5 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 when they are first used. SPAG provides the means to convert such programs to explicit typing, which in Fortran is usually enforced using the IMPLICIT NONE statement. It does this by adding explicit declarations for all undeclared variables at the head of each subprogram and INCLUDE file. 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.

2.1.6 Translation of VAX Structures

Fortran 95 provides an ANSI 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.7 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.8 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.9 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 leaders 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.

SPAG also allows you to use many VAX and Fortran 95 features in your programs, and then, when necessary, to convert back to Fortran 77. This allows you to benefit from the use of DO WHILE, DO ENDDO, SELECT CASE etc. without compromising portability.

2.1.10 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.

The Dynamic Analysis feature of plusFORT was inspired by the /UNDEF option in the FTN77 compiler from Salford Software. A similar facility was also implemented in the WATFIV run-time system on IBM mainframe computers. Other implementations are surprisingly rare.

2.1.11 Dynamic Memory Monitoring

SPAG implements a form of dynamic analysis which is geared toward finding variables with a particular type of content at run-time. For example, variables containing dates can be identified, even if their name provides no clue as to their function. This unique capability makes SPAG an ideal tool for Year 2000 compliance and similar testing. A more conventional Year 2000 date variable scan is implemented in GXCHK.

2.1.12 Coverage Analysis

In addition to testing for the definition status of variables and arrays, SPAG can insert probes to monitor what code is executed, and over a series of runs, to 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. in columns 73-80).

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 fully supports ANSI standard Fortran 77, DEC VAX Fortran and IBM VS Fortran. In addition, almost all the extensions supported by the major UNIX and PC 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).

In addition, SPAG supports almost all of Fortran 90 and 95. A summary of Fortran 95 features known to be unsupported may be found in the READ.ME file in the plusFORT installation release directory.

The following useful Fortran 95 features are almost universally available even in Fortran 77 compilers, and their use can be wholeheartedly recommended even to those not intending to switch to Fortran 95.

• The INCLUDE statement. Probably the most important for large programs - INCLUDE statements are vital for COMMON block definitions and globally used PARAMETERs.
• IMPLICIT NONE. Enforces the crucial discipline of declaring all variables explicitly.
• DO..ENDDO and DO WHILE. These extensions to the DO statement make labels redundant, except in FORMAT statements.
• Lower case in symbol names. Can greatly improve the readability of code.
• The use of symbol names with more than six characters.

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).
• Declare every COMMON block (via an INCLUDE file) in the main program, even if they are not used there. This is a necessary step if you wish to perform a dynamic analysis, but is desirable in any case. Note that according to the ANSI standard, a COMMON block which is not declared in the main program may become undefined.
• 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

To start a run, 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.

Under DOS/Windows and VMS, .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.

Under UNIX, the extension must be specified, and there is no default file name.

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

For example

      spag a*.f 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*.f. 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.

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
         5=Dynamic Memory Monitoring

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)

! 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

     DATA zalph/'ABCDEFGHIJKLM
    &NOPQRSTUVWXYZ'/

      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

      !*==TEST1.NEW

      !***_Start_of_Executable_Program

2.7 Using SPAG

2.7.1 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 better; the problem is 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).

2.7.2 Adding Declarations to INCLUDEd files

Declarations must be added to INCLUDEd files in a separate run. SPAG can process isolated INCLUDE files, though some warnings will be generated (no END statement, variables not used etc.).

When SPAG adds declarations to a subprogram, it has all the information required to determine the type and nature of every symbol in it. Some of this information may be contained in INCLUDEd files. However, when SPAG adds declarations to an incomplete source code, such as an INCLUDE file, it may find that some information is missing.

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)
        INCLUDE 'dims.inc'

where dims.inc contains PARAMETER definitions (including one for N), 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).

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 example, given the following code fragment:

     PARAMETER (MXOB=50)
     PARAMETER (MXAT=MXOB)
     PARAMETER (MXANG=80)
     COMMON /ODDS  / NNOBS,NATOMS,NANGLS,SC(2) 
C  comment 1
     REAL*8 X(MXAT),Y(MXAT),Z(MXAT),CHGE(MXAT)
     INTEGER IP(MXOB),IQ(MXOB),NAT(MXAT),ITYP(MXAT)
     INTEGER ITA(3,MXANG)
     REAL*8 AKT(MXOB),ALO(MXOB),AKA(MXANG),AAO(MXANG)
     INTEGER IWORK(MXAT)
   !  comment 2
     INTEGER*2 TOSPN(MXAT)
     INTEGER MXIT,I
     REAL*8 RMSMIN,ENGMIN,RMS,ENERG1,ENERGY
     RMSMIN = 0.0

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

C*** Start of declarations rewritten by SPAG
C
C PARAMETER definitions
C
      INTEGER MXOB , MXAT , MXANG
      PARAMETER (MXOB=50,MXAT=MXOB,MXANG=80)
C
C COMMON variables
C
      INTEGER NANgls , NAToms , NNObs
      REAL*8 SC(2)
      COMMON /ODDS  / NNObs , NAToms , NANgls , SC
C
C Dummy arguments
C
      REAL*8 Energy , Engmin , Rmsmin
      REAL*8 Alo(MXOB)
C
C Local variables
C
      REAL*8 aao(MXANG) , aka(MXANG) , akt(MXOB) ,
     &       chge(MXAT) , energ1 , rms , x(MXAT) ,
     &       y(MXAT) , z(MXAT)
      INTEGER i , ip(MXOB) , iq(MXOB) , ita(3,MXANG) ,
     &        ityp(MXAT) , iwork(MXAT) , mxit , nat(MXAT)
      INTEGER*2 tospn(MXAT)
C
C*** End of declarations rewritten by SPAG
C
C  comment 1
   !  comment 2
      Rmsmin = 0.0

If item 4 is set to 36, SPAG produces:

!*** Start of declarations rewritten by SPAG
!
! PARAMETER definitions
!
      INTEGER , PARAMETER :: MXOB = 50 , MXAT = MXOB , &      &                       MXANG = 80
!
! COMMON variables
!
      INTEGER :: NANgls , NAToms , NNObs
      REAL(R8KIND) , DIMENSION(2) :: SC
      COMMON /ODDS  / NNObs , NAToms , NANgls , SC
!
! Dummy arguments
!
      REAL(R8KIND) :: Energy , Engmin , Rmsmin
      REAL(R8KIND) , DIMENSION(MXOB) :: Alo
      INTENT (OUT) Rmsmin
!
! Local variables
!
      REAL(R8KIND) , DIMENSION(MXANG) :: aao , aka
      REAL(R8KIND) , DIMENSION(MXOB) :: akt
      REAL(R8KIND) , DIMENSION(MXAT) :: chge , x , y , z
      REAL(R8KIND) :: energ1 , rms
      INTEGER :: i , mxit
      INTEGER , DIMENSION(MXOB) :: ip , iq
      INTEGER , DIMENSION(3,MXANG) :: ita
      INTEGER , DIMENSION(MXAT) :: ityp , iwork , nat
      INTEGER(I2KIND) , DIMENSION(MXAT) :: tospn
!
!*** End of declarations rewritten by SPAG
!
!  comment 1
   !  comment 2
      Rmsmin = 0.0 

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. In the Fortran 95 version, 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.
• 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.

INCLUDE statements from the original code are, depending on item 4 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 Interface Modules

If item 4 of spag.fig is set appropriately, 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.

2.7.5 Include File Modules

SPAG can also translate INCLUDE files to Fortran 95 modules. Each INCLUDE file is translated the first time it is encountered in a run,.

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 236, and .xyz is the extension specified in item 237.

To be translated correctly, an INCLUDE file must:

• Contain only INCLUDE, PARAMETER and COMMON statements, together with associated type and dimension statements. SPAG will issue an error message if this rule is violated.
• Be self-contained. For example an INCLUDE file which contains the single statement:

     COMMON /aaa/ x(n)

  is not self-contained, because the type of x, and the type and value of n are undefined. In one context, x may be REAL, and n may be an INTEGER PARAMETER with a value of 100. In another, x may be a LOGICAL array, and n may be 2000. The module written by SPAG will assume that the context in the first occurrence of the INCLUDE file is universal.

  To make the above INCLUDE file self-contained, one might add two statements as shown below:

      REAL x
      INCLUDE 'dims.inc'
      COMMON /aaa/ x(n)

  where the type and value of n are defined in dims.inc (which must itself be self-contained).

2.7.6 COMMON block Modules

SPAG can also translate COMMON blocks which are not contained in an INCLUDE file to Fortran 95 modules. However it is strongly recommended that COMMON blocks be put into INCLUDE files before translation is attempted. This is because the conditions required for correct translation of an isolated COMMON are stricter than for INCLUDE files. For a COMMON block to be translated correctly:

• Every definition of the COMMON 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.

SPAG derives the module name from the COMMON block name by discarding the '/'s, and prefacing the two characters c_. For example, an INCLUDE file 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 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.

ANSI 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.8 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.9 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. Note that 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.10 The ANCHOR Directive

Occasionally, it may be desirable to force SPAG to leave a particular statement in position. This can be done by inserting a !-ANCHOR directive immediately before the statement in question. C-ANCHOR and *-ANCHOR are accepted as alternatives in fixed format source code. The anchored statement must be an executable statement, and must have a label. 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.

2.7.11 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.12 Using Case to make Programs more Readable

Because of its antiquity, Fortran has always been an upper-case language. Even today, many 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.13 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.14 VMS Text Libraries

VMS VAX Fortran permits source code to be INCLUDEd from VMS text libraries, using an INCLUDE statement of the form:

      INCLUDE 'LIBNAME(MEMBER)'

Although SPAG cannot read text libraries, INCLUDE statements of this form can be used. SPAG interprets the above example as being equivalent to

      INCLUDE 'MEMBER.FOR'

Thus, if the VMS command

  LIBRARY/EXTRACT=MEMBER
         /OUTPUT=MEMBER.FOR LIBNAME.TLB

is used before SPAG is run, SPAG will behave correctly. Note that the files containing the extracted library members may be in a separate directory, provided that the directory is specified in the INCLUDE file search list (see item 215 of the SPAG configuration data). Note too that a leading '$' in the member name is removed. Thus ($foriosdef) is treated as foriosdef.for.

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. Note that 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 ANSI 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, 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. Note that 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 input code, and with some Fortran 95 extensions. Most programs which use Fortran 90 or 95 features cannot be instrumented. In particular, SPAG does not (in this context) deal correctly with derived types, pointers, allocatable arrays, and array language.

2.8.4 COMMON Variables

One area which may require a little attention from the user is the initialization of COMMON variables to the undefined value.

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 and the source code for the probes (taken from the plusFORT release directory).
• 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 so infrequently 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. The only restriction is that GXCHK must process the source code of all subprograms that initialize COMMON data.

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 we are often asked which is best. The answer is that 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 removed 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.
• In addition to setting item 6, you should also use 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 (see Appendix B).

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, PR$EXI, just before the call to EXIT.

      CALL PR$EXI
      CALL EXIT(16) 

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

2.10 Dynamic Memory Monitoring

If SPAG Configuration item 1 is set to 5, SPAG prepares source code for a special sort of dynamic analysis, originally geared towards finding the date associated problems which were expected to occur on or around the year 2000. The instrumented program executes normally, but as it runs, every variable or array element, used in any way, is checked for data which could be date related. A report is written to the file probes.log. The same technique can be used for other similar tasks - for example, to find the parts of a program that deal with with currency transactions

Most tools for detecting Year 2000 problems rely largely on finding date references in the source code, for example in the form of variable or subprogram names such as IDATE or LEAP. This approach, which is implemented in GXCHK, may fail if the programmer has not chosen names which reflect the variable's usage. SPAG's analysis is different, and can detect date variables, even if their name is unrelated to their function. For example, if the programmer has used a variable called K2 to store a 2 digit year, SPAG will spot it, because it looks at the contents of the variable at run-time, rather than at the source code.

All that's required to perform a Year 2000 check is to instrument the source code using SPAG (with item 1 of the configuration data set to 5), and then compile and run the program as normal. An additional source file called probes.y2k must be compiled and linked with the instrumented code.

This form of dynamic analysis is much simpler than the standard type, because variables do not have to be initialized, and there is no need to run GXCHK before starting the analysis.

When the run is complete the file probes.log contains a summary of the variables which could be date related, together with their values, and the line in the source code where they are set. The probe routines contain logic to ensure that multiple reports of the same type are condensed to a single report.

Inevitably, many of the reports will be false positives; a variable may contain the value 1998, and yet not be a date variable. In practice, you'll probably need to do several runs, tuning the criteria to isolate problem code. There are two ways to eliminate these false positives:

• Modify the code in probes.y2k which checks for date related values. The relevant code is in subroutines QD$CH, QD$I2 and QD$I4 at the start of the file. The logic of these routines is very simple.
• Modify the instrumented code by removing calls to QD$CH, QD$I2 and QD$I4 which have proved to be the source of false positives. The reports in probes.log should enable you to find the required line.

2.11 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.

When SPAG looks in PFMODULE.KEY to find the location of the symbol data for a particular module, it may find that there is no entry, because the module has not been processed yet. In this case SPAG reports an error. This is similar to the problem, familiar to most Fortran 90/95 programmers, that occurs when modules are not compiled before code that USEs them.

It is possible to overcome this problem by repeatedly re-running SPAG until the modules are all processed. However this can take some time, particularly if USEs are nested to any depth. In addition if a module is changed, SPAG may use an obselete symbol table, and produce incorrect results while appearing to work correctly.

The plusFORT AUTOMAKE tool provides a solution to this problem (just as it does for compilers). 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)