Appendix B - Probe Routines

When the dynamic analysis or coverage analysis facility of plusFORT is used, it is necessary to link a set of probe routines into your executable file. Suitable routines are contained in the source code file probes.f90 in the plusFORT installation directory. This document describes those routines. The supplied source code is well commented, and it should be quite possible for experienced users to modify the routines to suit local requirements. When compiling and linking 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.

Dynamic Analysis

For each data type in a program, two routines are required:

a routine which sets a variable of the given type to a special 'undefined' value.
a routine which examines a variable or array element of the given type to determine whether it contains the 'undefined' value. If it does, the routine reports an error, and resets the variable to 0 to allow continued processing.

For example, for the two routines for scalar INTEGER data types are:

 SUBROUTINE SPAG_UD_IGEN(IntKind,Ivar)               ! Undefine an INTEGER(IntKind) variable
 SUBROUTINE SPAG_QD_IGEN(IntKind,Zname,IntVar,Lnum)  ! Check INTEGER(IntKIND) item is defined.

Note that the first two parts of the subroutine names are formed from items 238, and 240 or 242 of the SPAG configuration data.

Coverage Analysis

If coverage analysis is active, SPAG inserts the following statements to trace program execution:

a call to SPAG_PR_ENT (or as specified in item 243 of the SPAG configuration data) before the first executable statement in the main program. SPAG_PR_ENT takes three CHARACTER*(*) arguments, containing the name of the subprogram being entered, the name of the file which contains the source code, and the name of the directory containing coverage data (.cvr) files.
calls to SPAG_PR_EXI (or as specified in item 244 of the SPAG configuration data) before every STOP statement, and, if necessary, before the END statement in the main program. SPAG_PR_EXI has no arguments.
a call to SPAG_SB_ENT (or as specified in item 245 of the SPAG configuration data) before the first executable statement in every SUBROUTINE and FUNCTION. SPAG_SB_ENT take two CHARACTER*(*) arguments, containing the name of the subprogram being entered, and the name of the file which contains the source code.
calls to SPAG_SB_EXI (or as specified in item 246 of the SPAG configuration data) before every RETURN statement, and, if necessary, before the END statement in SUBROUTINEs and FUNCTIONs. SPAG_SB_EXI has no arguments.
calls to SPAG_BL_ENT (or as specified in item 247 of the SPAG configuration data) at the start of every linear code block (i.e. a set of a adjacent statements which are always executed in sequence). SPAG_BL_ENT has a single integer argument, the line number (in the original source code) of the first statement in the linear code block. These calls are omitted if item 6 of the SPAG configuration data is set to 1 in stead of 2.

These routines call other routines to handle the input, storage and output of coverage data:

SPAG_CV_INIT	called by SPAG_PR_ENT	initialises the coverage data system.
SPAG_CV_SLOT	called by SPAG_PR_ENT and SPAG_SB_ENT	uses a hashing algorithm to compute a unique number for each subprogram.
SPAG_CV_READ	called by SPAG_PR_ENT and SPAG_SB_ENT	read data from a coverage data file.
SPAG_CV_WRITE	called by SPAG_PR_EXI	writes updated versions of coverage data files.
SPAG_CV_OPEN	called by SPAG_CV_READ and SPAG_CV_WRITE	locates and opens a coverage data file.

Subprogram Timing Analysis

The versions of SPAG_PR_ENT, SPAG_PR_EXI, SPAG_SB_ENT and SPAG_SB_EXI supplied with plusFORT include calls to routines which measure the time spent in each subprogram, and, at the end of the run, produce a histogram showing the subprograms which take most time. These routines are:

SPAG_CK_INI	called by SPAG_PR_ENT	initialises the timing sub-system.
SPAG_CK_ON(Zname)	called by SPAG_PR_ENT and SPAG_SB_ENT	turns specified clock on.
SPAG_CK_OFF	called by SPAG_SB_EXI and SPAG_PR_EXI	turns off the last clock to be switched on.
SPAG_CK_RPT	called by SPAG_PR_EXI	writes timing reports to the log file. An sample report is shown below.
SPAG_CP_TIC	called by all SPAG_CK_ routines	returns the current CPU usage in 'ticks'.

Example Timing Report

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

Note the distinction between times including and excluding called routines. For example, 6% of the total time is spent executing NF3DPRECON (represented by 3 '*'s), but another 70% is spent in routines called by NF3DPRECON (represented by 35 '-'s). Inspection of the code reveals that NF2DPRECON is called from NF3DPRECON, and TRISOLVE is called from NF2DPRECON.

If there is a very large number of calls to a particular routine, it is quite possible that the probes themselves will significantly affect execution times. The effect can be reduced by selectively removing calls to SPAG_SB_ENT and SPAG_SB_EXI from low level routines.