Floppy and Flow User's Guide

  • Introductory Remarks and Acknowledgements
  • Introduction to Floppy
  • Warnings from Floppy
  • Conventions that may be checked by Floppy
  • Names to Ignore
  • Special processes for experiments at CERN
  • Tidying your Fortran
  • Generating HTML from Fortran
  • Description of the Floppy qualifiers or options
  • Floppy on OpenVMS
  • Floppy on VM/CMS
  • Floppy on Unix
  • Introduction to Flow
  • Description of the Flow qualifiers or options
  • Flow on OpenVMS
  • Flow on VM/CMS
  • Flow on Unix
  • Table of filenames used by Floppy/Flow
  • Problems and installation
  • Acknowledgments
  • References
  • 1 Introductory Remarks and Acknowledgements

    This document describes the use of FLOPPY and FLOW on the VXCERN, CERNVM, and DXCERN machines in the CERN Computer Centre. 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

    Floppy and Flow are not yet available via anonymous ftp from nic.funet.fi (128.214.248.6) in /pub/languages/fortran as floppy7.tar.Z and flow3.tar.Z.

    If you have problems using FLOPPY or FLOW, or if you discover bugs, then please contact the author: julian@vxcern.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.