Floppy and Flow User's Guide

This is the master version of the Floppy and Flow User's Guide. If you want to download the distribution kits, then they are hosted at the netlib library, which is maintained at ORNL.

Floppy was written by Julian Bunn and is based on a program by Hans Grote called FLOP.

1 Introductory Remarks

This document describes the use of FLOPPY and FLOW on VMS, VM/CMS and Unix operating systems. It refers to Floppy Version 7.0 and upwards.

FLOPPY is a software tool that takes as input a file of FORTRAN 77 code and checks it according to various "coding conventions". Floppy can "tidy" the source FORTRAN, producing a new file with indented DO-loops, block IF-s, and so on. Floppy can be used to generate HTML from the Fortran program. In this case, a new file is written where each module and include file name in the source Fortran is replaced by an HTML Anchor. The format of the source is preserved when the document is browsed by an HTML browser. FLOPPY can also be used to write a binary summary file which is then used as input to the FLOW program.

The FLOW program takes the binary summary file produced by FLOPPY, and can produce various reports on the structure of the original FORTRAN program.

In summary, FLOPPY

  • checks FORTRAN coding conventions,
  • "tidies" FORTRAN source,
  • produces an HTML version of the FORTRAN source,
  • produces a summary file for FLOW.

And the FLOW program

  • produces various reports on the structure of FORTRAN code,
  • allows an interactive exploration of the structure,
  • shows COMMON block variable usage,
  • checks consistency of arguments between calls.

(Please note that FLOPPY is based on FLOP (FORTRAN Language Orientated Parser).)

2 Introduction to Floppy

Have you ever wondered whether the FORTRAN 77 code you are writing conforms to some accepted coding conventions ? Probably not, but you may still be interested in using FLOPPY to see if it does! Before using FLOPPY to check your FORTRAN, you should use a good compiler to compile the source form (preferably with the ANSI switch enabled), and verify that there are no compilation errors. If there are, then the results from using FLOPPY will be unreliable.

In this version of Floppy, some common language extensions are also understood. These are:

  • Mixed case source form (e.g. "Program MyProg")
  • In-line comments (e.g. "real v ! velocity value")
  • The INCLUDE directive (e.g. "include 'params.h'")
  • DO, DO WHILE, ENDDO (e.g. "do i=1,4")

FLOPPY treats non-standard FORTRAN statements (such as REWRITE) as comments, and will ignore them completely.

FLOPPY processes the FORTRAN routine by routine and statement by statement. When all routines have been processed, various global checks are made (e.g. for EXTERNAL functions that are not declared). One useful by-product of this treatment is the identification of COMMON blocks declared in subprograms where they are not used, and consistency checks between argument lists for calls and module declarations. FLOPPY is quite quick, particularly for short programs where the number of checks is disproportionately smaller than for larger ones. It is thus recommended to use Floppy for short programs, early on in the software development cycle, rather than submit very large programs later. In this way the number of corrections that may need to be made at any time will be smaller, and thus easier to come to terms with!

3 WARNINGS FROM FLOPPY

When a FORTRAN statement which does not conform to one or more of the specified conventions is identified by Floppy, a warning message is printed describing the error, together with the offending statement. Figure 1 shows some warnings generated by FLOPPY.

!!! WARNING ... NOT ENOUGH (<3) COMMENT LINES AT START OF MODULE 
8. IF(IF(L).EQ.1) GOTO66 
!!! STATEMENT HAS NO BLANK AFTER "GOTO" 
16. WRITE(*,21) J 
!!! STATEMENT SHOULD NOT HAVE LUN="*" 
21. STOP 
!!! STATEMENT SHOULD BE PRECEDED BY A "WRITE" 
22. 999 END 
!!! STATEMENT SHOULD NOT HAVE LABEL 
!!! 5 STATEMENT WARNING(S) IN THIS MODULE 
BEGIN GLOBAL CHECKS WITHIN THIS MODULE 
!!! MIXED MODE EXPRESSION (BAD OPERATOR IS MARKED) IF(I*2.0)="3" ^ 
!!! WARNING ... VARIABLE IF CLASHES WITH FORTRAN KEY-WORD IF 
!!! 2 GLOBAL WARNING(S) IN THIS MODULE 

By default, only the statements at fault are printed, but, optionally, you may specify that all the FORTRAN statements are printed out (this is useful for programs where the context of the statement may clarify the error). FLOPPY will only print subprogram headers for those subprograms in which convention breaks have been discovered. All output from FLOPPY may either be viewed directly at the terminal or, optionally, sent to a disk file for inspection at a later time.

4 CONVENTIONS THAT MAY BE CHECKED BY FLOPPY

Here follows the list of coding conventions which may at present be checked by FLOPPY. The conventions in the STANDARD set are marked by an asterisk (*).


 * 1 Avoid comment lines after end of module 

 * 2 End all program modules with the END statement 

 * 3 Declared COMMON blocks must be used in the module 

 * 4 COMPLEX and DOUBLEPRECISION vars at end of COMMON 

 * 5 COMMON block definitions should not change 

 * 6 Variable names should be 6 or fewer characters long 

   7 Variables in COMMON should be 6 characters long 

   8 Variables not in COMMON should be <6 characters  

 * 9 Integer variables should begin with I to N  

 * 10 Variable names should not equal FORTRAN keywords  

 * 11 Avoid comment lines before module declaration  

 * 12 Module names should not equal intrinsic functions  

 * 13 Each module should declare IMPLICIT NONE  

 * 14 Module should begin with at least 3 comment lines 

  15 Comment lines should begin with a C  

 * 16 No comment lines between continuations  

 * 17 Avoid non-standard variable types eg INTEGER*2  

 * 18 Avoid multiple COMMON definitions per line  

 * 19 Do not dimension COMMON variables outside COMMON  

 * 20 Avoid embedded blanks in variable names  

 * 21 Avoid embedded blanks in syntactic entities  

 * 22 Avoid the use of PRINT statements (use WRITE)  

  23 Do not give the END statement a label  

 * 24 Avoid WRITE(* construction  

  25 Avoid WRITE statement in a FUNCTION  

 * 26 Avoid the use of PAUSE statements  

 * 27 Statement labels should not begin in column 1  

 * 28 Always preceede STOP by a descriptive WRITE  

 * 29 Avoid the use of ENTRY in FUNCTIONS  

 * 30 Avoid using I/O in FUNCTIONs  

  31 Avoid the use of the alternate RETURN statement  

 * 32 COMMON block names should not equal variable names  

 * 33 Avoid use of obsolete CERN library routines  

  34 Avoid FUNCTION names the same as intrinsics  

 * 35 Local functions should be declared EXTERNAL  

 * 36 Module names should all be different  

 * 37 Avoid expressions of mixed mode eg A="B/I"  

 * 38 Length of passed CHARACTER variables should be *  

 * 39 Order of statements should conform !  

 * 40 Separate Statement Functions by comment lines  

 * 41 No names in Statement Function definitions elsewhere  

   42 Use LLT,LGT etc to compare CHARACTER vars. in IFs  

   43 Variables (not COMMON, not PARAMs) <6 characters  

 * 44 Passed arguments should be dimensioned * in module  

   45 Variables in COMMON should be>=6 characters long 

   46 Avoid the use of the ENTRY statement 

5 NAMES TO IGNORE

Occasionally your FORTRAN program may contain references to subroutines or variables over which you have no control (e.g. subroutines in link libraries). The warnings associated with these variables or subroutines may be therefore rather academic (you may not be able to change them). FLOPPY thus allows you to suppress the warnings associated with either particular variables, or whole subroutines. This is done by giving FLOPPY a list of "names to ignore" (you may specify up to fifty variable names and fifty subroutine names in the current version of Floppy). The file containing the list of names to ignore is saved on disk, and may be re-used in a future FLOPPY run. As an example, you may have an OpenVMS file called TEST.FOR which contains various subroutines, amongst them SUBROUTINE OPAL, and references to the 6-character variables RINPAN and DRIDER, which do not appear in a COMMON block and therefore should be less than 6 characters long (if you happen to follow this particular convention). You are aware of this error and wish to suppress those warnings from FLOPPY. You also want to suppress all warnings from SUBROUTINE OPAL for other reasons. You type the following FLOPPY command (on the OpenVMS system):

             $ FLOPPY TEST.FOR /IGNORE=(#OPAL,RINPAN,DRIDER)
The syntax is similar for the other supported operating systems.

6 SPECIAL PROCESSES FOR EXPERIMENTS AT CERN

At present there are three 'special processes' available in FLOPPY. These are special sets of coding conventions that suit the ALEPH and ATLAS experiment collaborations: The process ALEPH will cause the set of coding conventions to those defined by the ALEPH collaboration. The process GALEPH (the ALEPH Monte Carlo program) is intended for people using FLOPPY to check programs that reference GEANT variables; it essentially causes FLOPPY to ignore variable names beginning 'G.....' or 'IG....'. The process ATLAS will cause the set of coding conventions to be those defined by the ATLAS collaboration.

7 TIDYING YOUR FORTRAN

FLOPPY allows you to "tidy" your FORTRAN source in the following ways: GROUPF (VM/CMS,OpenVMS) -F (Unix)

Group all FORMAT statements at the end of each subprogram.

INDENT (VM/CMS,OpenVMS) -j (Unix)

Indent DO-loops and IF-clauses.

GOTOS (VM/CMS,OpenVMS) -G (Unix)

Tabulate GOTOs to the right hand side of the source form.

STMNTS (VM/CMS) RENUMS (OpenVMS) -s (Unix)

Renumber all statement labels.

RENUMF (VM/CMS) FORMAT OpenVMS) -r (Unix)

Renumber all FORMAT labels. In the case where you choose to use any of these options, a new FORTRAN file will be written containing the changes. The following example shows the result of tidying a small subroutine using Floppy.


                   Before tidying                       After tidying
                   --------------                       -------------

                   PROGRAM BAD                          PROGRAM BAD
                   DIMENSION IF(10)                     DIMENSION IF(10)
                   I=5                                  I=5
              66   J=7                               10 J=7
                   DO 43 K=1,I                          DO 30 K=1,I
                   IF(K-J.EQ.2) THEN                       IF(K-J.EQ.2) THEN
                   DO 11 L=1,2                                DO 20 L=1,2
                   IF(IF(L).EQ.1) GOTO66                         IF(IF(L).EQ.1)         GOTO 10
               21  FORMAT(1X,I2)                     20       CONTINUE
               11  CONTINUE                                                             GOTO 10
                   GOTO 66                                 ELSE
                   ELSE                                       IF(IF(K).EQ.IF(J)) THEN
                   IF(IF(K).EQ.IF(J)) THEN                       IF(K)=1
                   IF(K)=1                                       WRITE(6,500) J
                   WRITE(6,21) J                                 J=5
                   J=5                                        ENDIF
                   ENDIF                                   ENDIF
                   ENDIF                             30 CONTINUE
                43 CONTINUE                             STOP
                   STOP                             500 FORMAT(1X,I2)
                   END                                  END

8 GENERATING HTML FROM FORTRAN

Floppy may be used to generate HTML from a FORTRAN program. This can be useful for documenting code. The procedure is to first run Floppy with the HTML (and maybe ANCHOR) qualifier present. This generates a file (an anchor dictionary) containing all possible anchor names in the source (these are all subroutine, function, program names, and all include files). This file is then edited (or processed using some other tool) to add a correspondence between anchor name and text string to be inserted. For example, the statement

                   CALL MATRIX

will give rise to an anchor name MATRIX in the anchor dictionary. The dictionary might then be edited to contain:

             MATRIX <A HREF="/usr/guides/matrix.html">MATRIX</A>

and Floppy re-run with the HTML and ANCHORS qualifiers present. The resulting HTML file will then contain:

                   CALL MATRIX

Which, when browsed using a browser like Mosaic, will allow the viewer to click on the text string MATRIX and view the MATRIX userguide.

If the anchor dictionary already exists from a previous run of Floppy, then the anchor names are read in, and any new possible anchor points are appended by Floppy to the file.

If the ANCHOR qualifier is not present, then no dictionary is used, and the output HTML file will contain only local references, and dummy references for modules. For example, if the example code "PROGRAM BAD" (see above) is processed by Floppy with the HTML option, the following HTML file is produced:

             <HEADER>
             <TITLE>PROGRAM BAD</TITLE>
             </HEADER>
             <BODY>
             <H1>PROGRAM BAD</H1>

             <PRE>

                   PROGRAM <A HREF=#BAD>BAD</A>
                   DIMENSION <A NAME=IF>IF</A>(10)
                   <A HREF=#I>I</A>=5
              66   <A HREF=#J>J</A>=7
                   DO 43 <A HREF=#K>K</A>=1,<A HREF=#I>I</A>
                   IF(<A HREF=#K>K</A>-<A HREF=#J>J</A>.EQ.2) THEN
                   DO 11 <A HREF=#L>L</A>=1,2
                   IF(<A HREF=#IF>IF</A>(<A HREF=#L>L</A>).EQ.1) GOTO66
               21  FORMAT(1X,I2)
               11  CONTINUE
                   GOTO 66
                   ELSE
                   IF(<A HREF=#IF>IF</A>(<A HREF=#K>K</A>).EQ.<A HREF=#IF>IF</A>
                   (<A HREF=#J>J</A>)) THEN
                   <A HREF=#IF>IF</A>(<A HREF=#K>K</A>)=1
                   WRITE(6,21) <A HREF=#J>J</A>
                   <A HREF=#J>J</A>=5
                   ENDIF
                   ENDIF
                43 CONTINUE
                   STOP
                   END

             </PRE>
             </BODY>

9 DESCRIPTION OF THE FLOPPY QUALIFIERS OR OPTIONS

CHECKS (VM/CMS,OpenVMS) -c (Unix)

Define the coding convention checks to be made. If no list is given, then the checks marked by a '*' in Section 2.2 are made. If the qualifier value is 99 then all checks are made. If /NOCHECKS (OpenVMS) or CHECKS NONE (VM/CMS) or -cn (Unix) is specified then no checks are made. If a qualifier value is negative, then that check number is not made. Thus to make all the checks except numbers 3 and 31, specify /CHECKS=(99,3,-31) on VMS, CHECKS 99,-3,-31 on VM/CMS or -c99,-3,-31 on Unix.

DISK (VM/CMS only)

Cause the output normally viewed at the terminal to be written to a file on disk. This file will have type FLOPLIS.

HTML (VM/CMS,OpenVMS) -H (Unix)

Specify that Floppy is to generate HTML from the Fortran. On Unix, a given filename will be used as the Anchor Dictionary (see below).

ANCHORS (VM/CMS,OpenVMS) -A (Unix)

Use an anchor dictionary. The dictionary should consist of text records which specify the Fortran module name to be anchored, and the text for the anchor to use. See above for a full description of how to use the HTML converter.

TREE (VM/CMS,OpenVMS) -t (Unix)

Cause a summary output file to be produced, containing a packed description of the source FORTRAN. The summary file contains such information as the list of all FORTRAN module names, their arguments, calling list, and so on. The file is unformatted; it should be used as input to the auxiliary tool called FLOW, and is unreadable at the terminal.

OUTPUT (VM/CMS) -n (Unix)

Cause the reformatted FORTRAN output to be written on the filename specified. If no filename is given, then the output Fortran is written to a file called OUTPUT FORTRAN (VM/CMS).

OUTPUT (OpenVMS)

Cause the output from FLOPPY (normally viewed at the terminal) to be sent to a disk file. If filename is not specified the output file will have the stem name of the source FORTRAN file, with a type of FLOPLIS .

FULL (VM/CMS,OpenVMS) -f (Unix)

Cause all source FORTRAN statements to be output, as opposed to only those breaking the specified coding conventions.

IGNORE (VM/CMS,OpenVMS) -i (Unix)

Specify a list of FORTRAN module and variable names to be ignored when the coding convention checks are made. Specify module names by preceeding the name with a # sign e.g. #MINUIT, specify variable names normally.

SPECIAL (VM/CMS,OpenVMS) -S (Unix)

Specify that a special version of FLOPPY be used. The default "special" version is STANDARD, which causes those checks marked by a '*' (see CHECKS) to be implemented. STANDARD : Use the standard checks. ALEPH : Use the ALEPH standard checks. GALEPH : Variables beginning with G..... or xG.... are ignored. ATLAS : Use the ATLAS checks.

LOG (OpenVMS) -l (Unix)

Show a summary of the FLOPPY command parsing.

OLD (VM/CMS,OpenVMS) -o (Unix)

Each time FLOPPY is run, an "IGNORE" file is written with the user specifications for that particular run. If the OLD qualifier is used, one may specify an already existing "IGNORE" file. If the filename is omitted, then the filename used is obtained from the stem of the source FORTRAN file and the type FLOPIGN . Note that this qualifier does not affect the use of TIDY as the FORTRAN tidying parameters are not stored in the "IGNORE" file.

TIDY (VM/CMS,OpenVMS, derived for Unix)

Write a new file of FORTRAN after re-formatting the input according to the qualifiers specified. The TIDY qualifier must be accompanied by at least one of the following qualifiers. If all you want to do is TIDY your Fortran, then use the (/NOCHECKS or CHECKS NONE or -cn) qualifier as well. See Section 1.4 for a description of the tidying options.

10 FLOPPY ON OPENVMS

The format of the FLOPPY command on OpenVMS (VAX or Alpha) is:

               FLOPPY  filename  [/qualifiers]

Where "filename" specifies the name of the input file of FORTRAN upon which the coding convention checks are to be made. You may use wild-cards in the filename; if more than one file is found matching the specification, then the files will be internally concatenated. If you are using FLOPPY to tidy your Fortran (see /TIDY option), then "filename" may be a file where the COMMON block declarations are hidden in INCLUDE statements. This will not jeopardize the indentation of DO loops and IF clauses, nor the re-numbering of statement labels.

For full information on the available qualifiers, please see above.

Examples

Some examples of the use of Floppy on OpenVMS are given below.
               $ FLOPPY myfile
Make all the standard coding convention checks on the FORTRAN
file myfile.for.

               $ FLOPPY /TREE /NOCHECKS myfile
Produce an output file for FLOW, and make no checks.

               $ FLOPPY /IGNORE=(FRED,#MICHEL) myfile
Make all the available checks, but ignore the variable called
FRED and the subroutine called MICHEL.

               $ FLOPPY /CHECKS=(1,5,25,3) /FULL myfile
Check conventions 1,3,5 and 25, and list all lines from the
source FORTRAN.

               $ FLOPPY /CHECKS=(99,-1,-2,-20) my*.for
Check all conventions except numbers 1,2 and 20. Use all files
beginning 'MY' and with filetype .FOR.

               $ FLOPPY /NOLOG /OUT=output.lis  myfile
Send the FLOPPY output to a listing file, and disable the command parsing information.

               $ FLOPPY /NOCHECKS /TIDY /INDENT=2 myfile
Produce a new FORTRAN file with all DO and IF clauses indented
by two spaces. No coding convention checking is done. The new
Fortran file will be called FORTRAN.FOR.

               $ FLOPPY /TIDY /STMNTS=(START=10,STEP=5) /FORTRAN=out.for myfile
Renumber statements starting at 10 (10, 15, 20 etc.) and write
the new FORTRAN to the file OUT.FOR.

               $ FLOPPY /NOCHECKS /HTML /ANCHOR myfile
Generate an HTML file corresponding to the source Fortran,
called myfile.html, and write a new file called myfile.htmldict
containing the list of all anchor points found in the code.

              $ FLOPPY /NOCHECKS /HTML /ANCHOR myfile
Now the file myfile.htmldict exists, it is read by Floppy and
used to generate anchor points for the module names in the
source.

11 FLOPPY ON VM/CMS

Type "FLOPPY" to activate the program in full screen mode, or "FLOPPY fn ft fm ( options)" to activate the program in line mode. The FLOPPY panel obtained by typing "FLOPPY" is shown below:

             <=> FLOPPY VERSION 7.00 <=======> CODING CONVENTION CHECKER <====>

               Name of source Fortran file not yet given
                                                       FN        FT      FM
                               Source  FORTRAN  ==>            FORTRAN   A
             ----------------------------------------------------------------------
             Existing FLOPPY parameter file     ==>            FLOPIGN   A
             Checks to be made              ==>  STANDARD
             Specify names to ignore        ==>  NO
             Generate HTML file from source ==>  NO
               ( ==>  OUTPUT    Dictionary      ==>            ANCHORS   A      )
             Generate a file for FLOW       ==>  NO
             Send FLOPPY Output to disk     ==>  YES
             List all source FORTRAN lines  ==>  NO
             ----------------------------------------------------------------------
             Tidy Fortran?  ==> NO      Output  ==>  OUTPUT   FORTRAN   A
              a) Adjust GOTOs to right of page  ==>  NO
              b) Indent DO/IF clauses           ==>  NO       Spaces  ==>  3
              c) Group FORMATs at routine ends  ==>  NO
              d) Renumber FORMAT statements     ==>  NO       Start   ==>  500
                                                              Step    ==>  10
              e) Renumber all other statements  ==>  NO       Start   ==>  10
                                                              Step    ==>  10

             PF1: Help  (on  cursor)   PF2: Enter  a  CMS  Command     PF3: Exit

The default FLOPPY options are highlighted in the panel, and you may change these according to your requirements. By positioning the cursor on the item with which you want help, and pressing the PF1 key, FLOPPY will access the HELP file at the correct line. In addition, you may enter any CMS command whilst in the FLOPPY panel by first pressing the PF2 key. This is useful for example when you forget the whereabouts of your source Fortran file; press PF2 then enter "FILELIST * FORTRAN *". After execution of the command you will be asked if you want to return to the FLOPPY panel.

Alternatively, FLOPPY may be invoked in line-mode, in which case the format of the command is as shown below

             +--------+--------------------------------------------------------------+
             |        |                                                              |
             | FLOPPY | [ ? | fn [ft [fm]] [( Options ]]                             |
             |        |                                                              |
             |        | Options:                                                     |
             |        |                                                              |
             |        | [CHECKS [STANDARD|NONE|ALEPH|GALEPH|                         |
             |        |          ATLAS|ONLINE|LIST|number_list]]                     |
             |        | [DISK]                                                       |
             |        | [FULL]                                                       |
             |        | [GOTOS]                                                      |
             |        | [GROUPF]                                                     |
             |        | [IGNORE]                                                     |
             |        | [INDENT    spaces]                                           |
             |        | [OLD       fn ft fm]                                         |
             |        | [OUTPUT    fn ft fm]                                         |
             |        | [RENUMF    start_value[,step_value]]                         |
             |        | [RENUMS    start_value[,step_value]]                         |
             |        | [TIDY]                                                       |
             |        | [HTML]                                                       |
             |        | [ANCHORS   {IN|OUT}                                          |
             |        | [DICT      fn ft fm]                                         |
             |        | [TREE]                                                       |
             +--------+--------------------------------------------------------------+

12 FLOPPY ON UNIX

Floppy operates on a single input file of Fortran code.
    floppy [-l] [-c checks] [-f] [-o old] [-i names] [-j number] [-F] [-G]
           [-r start,step] [-s start,step] [-n new] [-t] [-H dictionary] [-A] [file]

13 Introduction to Flow

FLOW uses a file produced by FLOPPY from your FORTRAN to analyse the flow of control between the modules, and produces a program control structure file, a common block usage file. an argument consistency file, and various other forms of reports. The output from the FLOW program is suitable for inclusion in a document such as a user's guide.

It is also possible to produce a pseudo-structure-chart in PostScript format. Users are warned that, for charts containing more than about a dozen modules, the chart might be rather unreadable, as it is hard to optimize the module positions to minimize line crossings etc. whilst preserving the right call sequences. It is intended that this will be useful for "reverse engineering", i.e. verifying that the SASD designed Structure Chart corresponds with the actual structure of the Fortran source.

An example structure chart (for the FLOW Program itself) is shown below.


           ********************              ProTre             ********************
                                             ======

                                Meaning of Symbols:
                                -------------------
                                .   ==> terminal node in the tree
                                *   ==> external procedure
                                >   ==> subtree node, expanded below
                                +   ==> multiply called terminal node
                                ]   ==> procedure calling only externals
           -------------------------------------------------------------------------
                                ?   ==> module is in IF clause
                                (   ==> module is in DO loop

           *************************************************************************
           EXTERNAL procedure names will not appear
           =============
           Node name ==> FLOW
           =============
            FLOW                                                 :
                |-----PRODES                                     :Steer the FLOW program
                          |-----INIARR   +                       :Initialise arrays
                          |-----RDFLOP   >                       :Read the data from FLOPPY
                          |-----EXTERN                           :Find names of external routines
                          |         |-----RDFLOP   >             :Read the data from FLOPPY
                          |?----PROTRE                           :Produce the FLOW diagram
                          |         |-----SEARCH   +             :Finds the index for a routine name
                          |         |-----LENOCC   ]             :
                          |         |?----LENOCC   ]             :
                          |         |?----LENOCC   ]             :
                          |         |??---LENOCC   ]             :
                          |         |??---LENOCC   ]             :

                          |?----PROCHT                           :Produce the graphics SC
                          |         |-----SEARCH   +             :Finds the index for a routine name
                          |         |-----GRINIT                 :Close the graphics package
                          |         |         |-----LENOCC   ]   :
                          |         |-----CHTBOX   +             :Plots a box
                          |         |-----SEARCH   +             :Finds the index for a routine name
                          |         |((---CHTBOX   +             :Plots a box
                          |         |((---GTX                    :Plots the text at a given positi
                          |         |         |-----LENOCC   ]   :
                          |         |((---SEARCH   +             :Finds the index for a routine name
                          |         |((---CHTLIN   ]             :Calculate and plot box intersect
                          |         |(((--GRCLOSE                :Close the graphics package
                          |                   |-----LENOCC   ]   :
                          |?----PROCOM                           :Produce the COMMON block table
                          |         |-----LENOCC   ]             :
                          |         |-----LENOCC   ]             :
                          |?----PROQRY                           :Interactively look at the tree
                                    |-----CASCHG   >             :Convert any lower case to upper
                                    |-----SEARCH   +             :Finds the index for a routine name
                                    |-----CASCHG   >             :Convert any lower case to upper
           =============
           Node name ==> RDFLOP
           =============
            RDFLOP                                               : Read the data from FLOPPY
                |-----TABENT                                     : Enter data into tables
                          |((??-LENOCC   ]                       :
                          |(----SEARCH   +                       : Finds the index for a routine name
           =============
           Node name ==> CASCHG
           =============
            CASCHG                                               : Convert any lower case to upper
                |-----LENOCC   ]                                 :

Modules that are called inside DO-loops are prefixed by one or more ('s, and those called conditionally are prefixed by one or more ?'s. In the FLOW shown, all external subprograms (e.g. UCOPY or SIN etc.) have been eliminated; this is an option.

The same information may be shown graphically (in PostScript) by using the Graphics option of Flow.

An example COMMON-block usage chart is shown below:

          Figure 3:  The COMMON Block Table for the Flow Program itself
           ********************              ProCom             ********************
                                             ======

                                Module names appear along x-axis
                                COMMON block names along y-axis

                                  ==> COMMON used in module
                                  ==> COMMON not used (but is DECLARED)
                                <>  ==> COMMON not DECLARED
           *************************************************************************

                     C C C F E G G G I L P P P P P R S T M A L N R M I
                     A H H L X R R T N E R R R R R D E A I B E I E A N
                     S T T O T I C X I N O O O O O F A B N S N N A X D
                     C B L W E N L   A O C C D Q T L R E       T L   E
                     H O I   R I O   R C H O E R R O C N             X
                     G X N   N T S   R C T M S Y E P H T
                    +---------------------------------------------------------------
           LUNIT    |  Y Y   Y Y   Y       Y   Y Y                                  |
           JOBCO1   |          Y Y       N   N                                      |
           JOBCOM   |          N                                                    |
           TABLE1   |                Y               Y                              |
           TABLES   |                Y                                              |
           FLOPP1   |                          N   Y   Y                            |
           FLOPPY   |                          N                                    |
           IGNORE   |                            Y                                  |
                    +---------------------------------------------------------------

In the COMMON block chart, the routine names appear along the top of the table, and the COMMON block names down the side. If the COMMON block is declared in a routine, and at least one variable used in that routine, then a "Y" appears in the corresponding row and column of the table. If a COMMON block is declared but not used in a routine, then an "N" appears.

An example Argument Chart is shown below:


           ********************              ProArg             ********************
                                             ======
                                Meaning of Argument Type Symbols:
                                ---------------------------------
                                I   ==> Integer argument
                                R   ==> Real argument
                                D   ==> Double precision argument
                                C   ==> Character argument
                                L   ==> Logical argument
                                K   ==> Complex argument type
                                P   ==> Procedure name argument
                                *   ==> alternate return
                                $   ==> Floppy failed to assign type
           -------------------------------------------------------------------------
           Module CASCHG (CC)          Convert any lower case to upper
           Module CHTBOX (RRRR)          Plots a box
                --> ! Possible bad call by Module PROCHT with argument types ($$$$)
                --> ! Possible bad call by Module PROCHT with argument types (RR$$)
           Module CHTLIN (RRRRRR)          Calculate and plot box intersect
           Module EXTERN ( )          Find names of external routines
           Module GRINIT (RRC)          Close the graphics package
           Module GRCLOSE ( )          Close the graphics package
           Module GTX (RRC)          Plots the text at a given positi
                --> ! Possible bad call by Module PROCHT with argument types ($$$)
           Module INIARR ( )          Initialise arrays
           Module LENOCC (C)
                --> ! Called badly by Module PROARG with argument types (R)
                --> ! Called badly by Module PROARG with argument types (R)
           Module PROARG ( )          Show the argument types in calls
           Module PROCHT ( )          Produce the graphics SC
           Module PROCOM ( )          Produce the COMMON block table
           Module PRODES ( )          Steer the FLOW program
           Module PROQRY ( )          Interactively look at the tree
           Module PROTRE ( )          Produce the FLOW diagram
           Module RDFLOP (I)          Read the data from FLOPPY
           Module SEARCH (C)          Finds the index for a routine na
           Module TABENT (I)          Enter data into tables
           Module NOHEADER (MAIN)
           Module NOHEADER (*)

For each module in the source, the declared argument types in the module are checked against the argument types in the other modules which invoke the module in question. If there is a discrepancy, then a warning message is printed. In some cases, Floppy is unable to firmly associate a type to a variable. In such cases the argument type is represented as a "$", and a definitive check cannot be made (e.g. in Module GTX in the example).

14 DESCRIPTION OF THE FLOW QUALIFIERS/OPTIONS

The meaning of the options is described below:

Input File

Specifies the name of a binary file produced using the TREE option in FLOPPY.

QUERY(VM/CMS,OpenVMS) -q (Unix)

Enter the interactive exploration facility of FLOW. You will be shown the full list of module names in the source, and can then specify one of them to see which modules it calls, and which modules call it. In this way you can move freely around the tree.

STRUCTURE_CHART(VM/CMS,OpenVMS) -s (Unix)

Specifies that a text file be written containing the calling tree of the source FORTRAN. The tree shows modules local to the code and external, and indicates whether they appear in IF or DO clauses. Stub modules (no calls), external modules (not local), multiply-called modules and sub-trees are all clearly indicated. If the FORTRAN source contained lines after each module declaration of the form:

                C! This is a short comment

then these comments are shown against each module name in the tree.

GRAPHICS(VM/CMS,OpenVMS) -g (Unix)

Specifies that a PostScript file be written, which, when interpreted, will show the SASD-like structure chart of the source FORTRAN. It is recommended NOT to ask for EXTERNALS with this option. An attempt is made to optimize the positions of modules on the page, in order to minimise line crossings etc.. But this is often unsuccessful!

NODE (VM/CMS,OpenVMS) -n (Unix)

Specifies the top node in either the text or graphics structure chart. This is useful for restricting the output to a particular sub-tree of interest. The value nodename must be a PROGRAM, SUBROUTINE or FUNCTION name in the source FORTRAN.

NOEXTERNALS(VM/CMS,OpenVMS) -E (Unix)

Specifies that modules external to the source FORTRAN (e.g. SIN, COS, INDEX etc.) not be shown in the tree. The default is to show externals. This qualifier is to be used with the Query and Chart options.

COMMON_TABLE(VM/CMS,OpenVMS) -c (Unix)

Specifies that a table be written containing, on the y-axis the names of all COMMON blocks, and on the x-axis all the module names, contained in the source FORTRAN. At each place in the table a 'Y' indicates that the COMMON block appears in that module, and at least one variable from it is used in the module, a 'N' indicates that the COMMON block is declared but not used, and a blank indicates that the COMMON block is not declared in that module.

IGNORE (OpenVMS) -i (Unix)

Specifies that the given list of module names is to be excluded from treatment when the Structure_Chart (-s) option is used.

15 FLOW ON OPENVMS

The FLOW command is invoked by:
             $ FLOW  filename /qualifier  [/qualifiers]
Where the 'filename' is the file produced by FLOPPY when the
/TREE qualifier is used. Some examples are given below:
Create a structure chart called STRUCTURE.CHT showing the calling sequence in myfile.FOR:

             $ FLOW myfile /STRUCTURE=STRUCTURE.CHT

Create a structure chart, ignoring all external procedure names
(like VZERO, SIN, etc) and start the chart at subroutine INIJOB:

             $ FLOW myfile /STRUC /NOEXT /NODE=INIJOB

Enter the interactive exploration facility of FLOW

             $ FLOW myfile /QUERY

Check the argument consistency

             $ FLOW myfile /ARG

16 FLOW ON VM/CMS

Type "FLOW" to activate the program in full screen mode, or "FLOW ( options)" for line-mode. The FLOW panel is shown below:

             ====> FLOW VERSION 2.00 <=========> Analyse Fortran Code <======>

              Fill in the blank field(s) as required.

              Input for FLOW
                    Binary file from FLOPPY           ==>

              Interactively explore the calling tree  ==>

              Structure  Chart
                     Node name at top of chart        ==>
                      (Default is main program)
                     File for text chart              ==>
                     File for graphical chart         ==>
                     Include EXTERNALs in chart ?     ==>

              COMMON block table file                 ==>

              ARGUMENT consistency file               ==>

             PF1: Help   PF2: Enter  a  CMS  Command     PF3: Exit

The format of the line-mode FLOW command is shown below:

             +--------+---------------------------------------------------------+
             | FLOW   | [ ? | fn [ ft [ fm]]]  [( Options ]]                    |
             |        | Options:                                                |
             |        | [QUERY]                                                 |
             |        | [EXTERNALS]                                             |
             |        | [NODE name]                                             |
             |        | [STRUCTURE_CHART   fn [ft [fm]]]                        |
             |        | [GRAPHICS          fn [ft [fm]]]                        |
             |        | [COMMON_TABLE      fn [ft [fm]]]                        |
             |        | [ARGUMENTS         fn [ft [fm]]]                        |
             +--------+---------------------------------------------------------+

17 FLOW ON UNIX

The FLOW program is invoked by
      flow [-l] [-c [COMMON chart]] [-q] [-n node] [-s [structure chart]]
           [-A [argument chart]] [-g [graphics chart]] [-E] [-i ignore list] file

18 TABLE OF FILENAMES USED BY FLOPPY/FLOW

Listed below are the files which are used when you run FLOPPY. Some of these files will only appear if you select a particular FLOPPY option (shown in Status column).

                                      Unix
          VMS file-     IBM file-     File-
          name__________name__________name________Description_______________________Status

          fn.FOR        fn FOR-       your.f      The source FORTRAN                Required
                        TRAN

          fn.FLOPFOR    OUTPUT        your.f.out  The "tidied" FORTRAN              Optional
                        FORTRAN

          fn.FLOPLIS    fn FLO-       stdout      The FLOPPY output                 Optional
                        PLIS

          fn.FLOPIGN    fn FLOP-      your.f.old  The list of names to be ig-       Optional
                        IGN                       nored by Floppy, and the Rule
                                                  list

          fn.FLOPTRE    fn FLOP-      your.f.floptThe FLOPPY output file for        Optional
                        TRE                       FLOW

          fn.HTML       fn HTML       your.html   The HTML version of the           Optional
                                                  source

          fn.HTMLDICT   fn HTML-      your.htmldicThe HTML Anchor dictionary        Optional
                        DICT

          PROTRE.DAT    FILE          protre.dat  The FLOW text chart               Optional
                        PROTRE

          PROCOM.DAT    FILE          procom.dat  The FLOW COMMON block usage       Optional
                        PROCOM                    chart

          ARGMNTS.DAT   FILE          argmnts.dat The module Argument chart         Optional
                        ARGMNTS

          FLOW.PS       fn LISTPS     flow.ps     The FLOW PostScript Structure     Optional
                                                  Chart

19 PROBLEMS AND INSTALLATION

 

If you have problems using FLOPPY or FLOW, or if you discover bugs, then please contact the author: julian.bunn@cern.ch.

20 ACKNOWLEDGMENTS

I wish to thank Hans Grote for his invaluable help with implementing FLOPPY on top of FLOP. I also wish to thank Juergen Knobloch and Mike Metcalf for many helpful suggestions for improvements to the original version of FLOPPY. I am indebted to Paolo Palazzi and Steve Fisher for their help and advice on the implementation of the original FLOW program. Bertrand Rousseau gave many valuable suggestions for the HTML option, the idea for which came from Paolo Palazzi.

21 References

H.Grote "FLOP User's Guide and Reference Manual", Long WriteUp Q902 (1988)

FLOPPY in full screen mode uses the IBM package IOS3270, a screen management facility for full-screen terminals, which is not standard REXX.