

                         USER'S MANUAL


                         FORTRAN-lint


                     SOURCE CODE ANALYZER


                          Version 4.32



















               Cleanscape Software International



                    2231 Mora Drive, Suite E

                  Mountain View, CA 94040-1548

          Tel: (650) 864-9600    Fax: (650) 864-9500

                  E-mail: lint@cleanscape.net


                  FORTRAN-lint USER'S MANUAL

                 A SOURCE LEVEL CODE ANALYZER

                    For FORTRAN PROGRAMMING

                    On UNIX and VMS SYSTEMS

                        September 1998

                         Version 4.32

     Note: Licensed users may photocopy for distribution.

          Direct comments concerning this manual to:

                Cleanscape Software International
      2231 Mora Drive, Suite E, Mountain View, CA 94040-1548
           Tel: (650) 864-9600   Fax: (650) 864-9500
                  E-mail: lint@cleanscape.net

                      Copyright 1987-1999

                           Cleanscape

NOTICE OF COPYRIGHTS

Copyrighted by Cleanscape as an unpublished work. All rights reserved.
In claiming any  copyright protection which may be applicable,  Clean-
scape reserves and  does not waive any  other rights that  it may have
(by agreement,  statutory or common law, or otherwise) with respect to
this material.  See Notice of Proprietary Rights.

NOTICE OF PROPRIETARY RIGHTS

This manual and the material  on which it is recorded are the property
of Cleanscape.  Its use,  reproduction,  transfer and/or disclosure to
others,  in this or any other form,  is prohibited except as permitted
by a written  License Agreement with  Cleanscape.  Cleanscape reserves
the right to update this document without prior notification.

FORTRAN-lint is a  registered trademark of  Cleanscape Software Inter-
national.
Xlint is a trademark of Cleanscape Software International.
SunOS is a registered trademark of Sun Microsystems, Incorporated.
UNIX is a registered trademark of AT&T Bell Laboratories.
DEC, ULTRIX, VAX, and VMS are registered trademarks of  Digital Equip-
ment.

Table of Contents

1. Introduction

2. Getting Started

2.1 Analyzing Programs
2.2 Managing the Output
2.3 Call Trees and Cross Reference Tables

3. Command Reference

3.1 Command-Line Options
3.2 Summary of Options
3.3 Configuration Files
3.4 Environment Variables / Logicals

4. FORTRAN-lint Source Conventions

4.1 Source Format
4.2 Include Files
4.3 'C' Preprocessor  (UNIX only)
4.4 CDD and DBMS Support  (VMS only)
4.5 FORTRAN-77 Extensions
4.6 Fortran 90 Extensions
4.7 Specifying FORTRAN Dialect
4.8 Default Sizes
4.9 High Performance Fortran (HPF)

5. Controlling Analysis

5.1 Setting the Scope
5.2 Message Classification
5.3 Selecting Analysis Level
5.4 Suppressing Individual Messages
5.5 Portability Checking

6. Analysis Output

6.1 Overview
6.2 Summary Mode
6.3 Analysis Output
6.4 Statistics Output
6.5 Exit Status

7. Call Trees

7.1 Overview
7.2 Tree Options
7.3 Call Tree Format
7.4 Call Tree Content
7.5 Recursion
7.6 Dummy Routines
7.7 Entry Points
7.8 Fortran 90 Internal Subprograms

8. Cross Reference

8.1 Overview
8.2 Layout
8.3 Format  Selection
8.4 Content Selection

9. Library Support

9.1 Overview
9.2 Creating Library Files
9.3 Library Precedence
9.4 Library Shells
9.5 Miscellaneous Library Issues

10. Database Files

10.1 Overview
10.2 Creating Database Files
10.3 Using    Database Files

11. Xlint Introduction

12. Learning About Xlint

12.1 Screen Layout
12.2 File Menu
12.3 Search Menu
12.4 Build Menu
12.5 Source Window
12.6 Lint Window
12.7 Tree Window
12.8 Cross Reference Window
12.9 Control Panel
12.10 Mouse Functions

13. Database Files and Xlint

13.1 Overview
13.2 Loading Database Files
13.3 Rebuilding Database Files under Xlint

14. Xlint: Getting Started

14.1 Configuration Setup
14.2 Running Xlint
14.3 Sample Sessions

15. More About Xlint

15.1 Resizing Windows
15.2 Window Interaction
15.3 Command-Line Options
15.4 Advanced Example

16. Resource Files

16.1 Overview
16.2 XLint and XLINT.DAT

Appendix A - Installation under UNIX

Appendix B - Installation under VMS

Appendix C - License Manager

Appendix D - Sample Output: Fortran 90

Appendix E - Sample Output: FORTRAN 77

Appendix F - Diagnostic Messages

Appendix G - Performance

Appendix H - Xlint Installation under UNIX

Appendix I - Xlint Installation under VMS

Chapter 1
Introduction

1.1 Overview

FORTRAN-lint is a programming tool that simplifies the  debugging  and
maintenance of FORTRAN 77 and Fortran 90 programs.

FORTRAN-lint includes a source code analyzer that can  detect  a  wide
range of potential problems, including:

     inappropriate arguments passed to functions

     inconsistencies in common block declarations

     non-portable code

     type usage conflicts across different subprograms/program units

     unused functions, subroutines, and variables

     variables which are referenced but not set

FORTRAN-lint can be used to:

     check source files before they are compiled

     isolate obscure problems

     identify problems before debugging is required

     map out unfamiliar programs

     enforce programming standards

The diagnostic  messages produced by FORTRAN-lint  are  more  detailed
than those produced by standard compilers, and cover a wider range  of
problems. FORTRAN-lint analyzes source files both individually and  as
a group, and can therefore identify problems that are beyond the scope
of a compiler.

Chapter 2
Getting Started

2.1 Analyzing Programs

To run FORTRAN-lint, use a command of the form:

    flint -options file1.f file2.f file3.f                  under UNIX
or
    flint /options file1.for file2.for file3.for            under VMS

where "options" may be one or more options,  and each of the specified
files is  a  FORTRAN  source file containing  any  number  of  FORTRAN
program units.  Options may be  intermixed with or appear  after  file
names.

If  FORTRAN-lint  is  invoked without any  options  or  parameters,  a
"help" screen will be displayed:

    flint

If source  files are specified, but no options are given, FORTRAN-lint
will perform  a  basic  analysis of the source files  and  output  the
results to the console.

For example,  to analyze a single source file, use a  command  of  the
form:

    flint demo.f                                            under UNIX
or
    flint demo.for                                          under VMS

The following commands will perform a more detailed analysis:

    flint -fgs demo.f                                       under UNIX
or
    flint /FYI /GLOBAL /STATISTICS demo.for                 under VMS

----------------------------------------------------------------------

2.2 Managing the Output

When FORTRAN-lint is used on a large program for the  first  time,  it
may report hundreds or thousands of inconsistencies.  FORTRAN-lint has
several features which simplify management of the output.

2.2.1 Redirection

The command-line  option   "-Sname"  (under  UNIX)  or   "/SPLIT=name"
(under VMS)   will  cause  FORTRAN-lint to redirect  output  from  the
console to the following files:

Under UNIX:

    Analysis output              -->  name.lnt
    Statistics (-s)              -->  name.stt
    Call tree  (-t)              -->  name.tre
    Cross-reference (-x)         -->  name.xrf

Under VMS:

    Analysis output              -->  name.lnt
    Statistics  ( /STATISTICS)   -->  name.stt
    Call tree   ( /TREE)         -->  name.tre
    Cross-reference  ( /XREF)    -->  name.xrf

For example, the following commands will analyze demo.f (or demo.for),
send analysis  output  to  demo.lnt, and  send  statistics  output  to
demo.stt:

    flint -fgs demo.f -Sdemo                                under UNIX
or
    flint /FYI /GLOBAL /STAT demo.for /SPLIT=demo           under VMS

2.2.2 Statistics Output

The command-line option  "-s" (under UNIX) or /STATISTICS (under  VMS)
enables statistics and related output.

If this  option  is  used, FLINT displays a screen after  analysis  is
completed  which   includes  I/O  statistics,  structural   statistics
(subroutine counts,  etc.)  and a list of  the  error  messages  which
occurred most frequently in the source code.

2.2.3 Summary Mode

The command-line  option  "-+" (under UNIX) or  /SUMMARY  (under  VMS)
combines three operations:

    (a)     This  option  displays a progress meter which  tracks  the
      progress of FORTRAN-lint in real time.

    (b)  It  redirects FORTRAN-lint output  (as explained  in  section
      2.2.1).

      By  default,  "-+" (or /SUMMARY) redirects the output  to  files
      named  flint.lnt, flint.tre, etc. "-S" (or /SPLIT) may  be  used
      to specify a different base name.

    (c)  It  displays  an  error-message  summary   (as  described  in
      section 2.2.2).

For example, the following commands will analyze demo.f (or demo.for),
display a  progress  meter, send analysis output  to  flint.lnt,   and
display an error-message summary after analysis is completed:

    flint -fg+ demo.f                                       under UNIX
or
    flint /FYI /GLOBAL /SUMMARY demo.for                    under VMS

----------------------------------------------------------------------

2.3 Call Trees and Cross Reference Tables

FORTRAN-lint will  optionally generate a diagram of program  structure
(i.e., a "call tree") and a symbol-table cross-reference.

For  example,  the  following  commands  will  analyze    demo.f   (or
demo.for),  output a  call tree  to the file  demo.tre,  and  output a
cross-reference to the file demo.xrf:

    flint -tx demo.f -Sdemo                                 under UNIX
or
    flint /TREE /XREF demo.for /SPLIT=demo                  under VMS

For  additional  information  on  call  trees,  see  chapter  7.   For
additional information on cross-reference tables, see chapter 8.

Chapter 3
Command Reference

3.1 Command-Line Options

3.1.1 Command Format

To run  FORTRAN-lint, use the command flint, followed by zero or  more
option switches and one or more file names:

    flint [options] [file1 [file2 ...]]
                                [file3.lbt ...] [file4.fdb ...]

"file1 file2 ..." are FORTRAN source files. ".lbt" files are  optional
call-interface library files (explained in chapter  9).  ".fdb"  files
are optional Xlint  database files (explained in chapter 13).

If no  options  or  file names are specified,  flint  will  display  a
"help" screen.

FORTRAN source  files  may use any valid FORTRAN  filename  extension.
".F" is  a  special case; under UNIX, if a source file  has  the  ".F"
extension, FORTRAN-lint  will run the 'C'  preprocessor  on  the  file
before analyzing it.

Option switches may be specified in any order, and may  be  intermixed
with filename arguments.

3.1.2 Option Format

Under UNIX,  options are specified by single-character  switches;  for
example, "-x".  Lower-case  options take  no  arguments,  and  may  be
combined into  a single switch. For example, "-stx" is  equivalent  to
"-s -t  -x".  Upper-case options require one or more arguments;  these
options cannot be combined.

Arguments are specified for UNIX switches as follows:

    -P argument             single -argument switches
or  -P arg1,arg2,arg3,...   multi  -argument switches

Under VMS,  options  are specified by  "word" switches  (for  example,
/XREF).   "Word"  switches  are  not  case-sensitive.  They   may   be
abbreviated, provided that the abbreviations are unique. For  example,
/XREF is an abbreviation for /XREFERENCE.

Arguments are specified for VMS switches as follows:

    /PORT=argument              single- argument switches
or  /PORT=(arg1,arg2,arg3,...)  multi-  argument switches

Note: Under VMS, switches should not include spaces.

Switch arguments  are  cumulative.   For  example,  under  UNIX,   the
following commands are equivalent:

    flint -O 123 -O 200,375foo.f
    flint -O 123,200,375 foo.f

Under VMS, these commands are equivalent:

    flint /SUPPRESS=123 /SUPPRESS=(200,375) foo.for
    flint /SUPPRESS=(123,200,375) foo.for

To disable  an  option under UNIX, add an extra  dash  to  the  option
switch.  For example, "-w" enables warning messages and "--w" disables
them.

To disable  an  option  under VMS, add the word  "NO"  to  the  option
switch. For  example,  /WARN  enables warning  messages  and   /NOWARN
disables them.

When an option is disabled, arguments accumulated up to that point are
discarded. If the option is re-enabled subsequently, it "starts over".

For example, under UNIX, the following commands are equivalent:

    flint -P ANSI,CRAY --P -P SGI foo.f
    flint -P SGI foo.f

Under VMS, these commands are equivalent:

    flint /PORT=(ANSI,CRAY) /NOPORT /PORT=SGI foo.for
    flint /PORT=SGI foo.for

Configuration files  may be used to set default  values  for  options.
The FORTRAN-lint  package  includes a  predefined  configuration  file
named flint.cfg; for additional information, see section 3.3.

3.1.3 List of Options

The FORTRAN-lint options are listed below:

-a,   /ANSI

    Description:   Reports non-ANSI constructs. If FORTRAN-lint is run
             in  FORTRAN 77 mode,  this switch has  the same effect as
             "-P ansi77" (or /PORT=ansi77).

                   If  FORTRAN-lint is run in Fortran  90  mode,  this
             switch   has   the  same  effect  as   "-P  ansi90"   (or
             /PORT=ansi90).

             Note:  To  set the  language mode,  use the -7, -9 and/or
             /LANG switches.

    UNIX syntax:   -a

    VMS  syntax:   /ANSI

-B,   /DATABASE=

    Description:   Creates a specified database (.fdb) file.  FORTRAN-
             lint  and  Xlint  use database files to  regenerate  call
             trees,  cross-reference tables, and diagnostic  messages.
             For additional information on database files, see chapter
             13.

             Note:   FORTRAN-lint  adds the ".fdb" filename  extension
             automatically.

    UNIX syntax:   -B file

    VMS  syntax:   /DATABASE=file

-d,   /DLINES

    Description:   Source  lines starting with "D" in column  one  (or
             "Y", for EPC code) are "debug" lines.

                   By  default, "debug" lines are treated  as  comment
             lines.  If  "-d" (or /DLINES) is specified,  FORTRAN-lint
             will process "debug" lines along with normal source code.

                   Note:   This  option is valid only  for  fixed-form
             code.

    UNIX syntax:   -d

    VMS  syntax:   /DLINES

-D

    Description:    (UNIX   only.)  Defines  symbols   for   the   'C'
             preprocessor.   Applies  only   if   source   files   are
             preprocessed (".F" filename extension or "-p" option).

             For additional information, see section 4.3.

    UNIX syntax:   -D symbol[=value],...

    VMS syntax:    N/A

-e,   /EXTEND

    Description:   By  default,  if the source format is  fixed  form,
             characters past column 72 are ignored. If this option  is
             specified,  the  source-line width  is  extended  to  132
             columns.

             For additional information, see section 4.1.

    UNIX syntax:   -e

    VMS  syntax:   /EXTEND

-E,   /FILES=

    Description:   Reads a specified file and adds its contents to the
             FORTRAN-lint command line.

                   The  file  may  contain  source-file  names  and/or
             command-line  option switches.  Entries may be  separated
             by commands, newlines, or spaces, and may be specified in
             any order.

                   Nested expansions are allowed.  I.e., the specified
            file may use the "-E" (or /FILES) option to process lower-
             level files.

                   Wildcard  are  not supported.  I.e., the  specified
             file cannot include entries of the form "*.for".

             This  option  cannot  be  suppressed.   I.e.,  "--E"  and
             /NOFILES are not supported.

             For additional information, see section 3.3.

    UNIX syntax:   -E  file,...

    VMS  syntax:   /FILES=(file,...)

/FORM=

    See  "-R".

-f,   /FYI

    Description:  Enables FYI (or "for your information") diagnostics.

             FYI  diagnostics are informational messages which may (or
             may not) indicate problems.

    UNIX syntax:   -f

    VMS  syntax:   /FYI

-g,   /GLOBAL

    Description: Global analysis. This option is strongly recommended.

             By  default,  subprograms are processed on an  individual
             basis, and call interface checking is not performed.  The
             "-g"  (or  /GLOBAL) option enables "global" analysis.  If
             this   option   is   used,   FORTRAN-lint    checks   for
             inconsistencies between subprograms; for example, invalid
             arguments  or  common-block problems.  This  option  also
             improves  usage  checking  and  enhances  cross-reference
             output.

    UNIX syntax:   -g

    VMS  syntax:   /GLOBAL

-i,   /INCLUDE

    Description:   Expands  INCLUDE  files in  source  listings.  This
             option applies only when source listings are enabled (see
             "-l" or /LISTING).

    UNIX syntax:   -i

    VMS  syntax:   /INCLUDE

-I,   /PATH=

    Description:   Adds  one  or more directories to the  include-file
             searchlist.  This switch affects both INCLUDE  files  and
             "#include" files.

             For additional information, see sections 4.2 and 4.3.

    UNIX syntax:   -I path,...

    VMS  syntax:   /PATH=([path],...)

    Example:  -I ../myftn,/usr/sam/headers                  under UNIX

              /PATH=([FTNCODE],[USR.HEADERS])               under VMS

/IMPLICIT

    See  "-m".

/LANG=

    See  "-7" and  "-9".

-l,   /LISTING

    Description:  Outputs a source listing with line numbers.

    UNIX syntax:   -l  (lower-case ell)

    VMS  syntax:   /LISTING

-L,   /LIBRARY=

    Description:  Creates or updates a library template file.

             This  option  adds interface information for the  current
             source  files  to  the  specified  library  template  (or
             ".lbt") file. ".lbt" files may be used to speed up  subse
             quent runs. For additional information, see chapter 9.

             Note: This option causes FORTRAN-lint to run in a special
             mode,  bypassing  normal analysis.  Consequently,  source
             files must be free of errors before this option is used.

    UNIX syntax:   -L file.lbt

    VMS  syntax:   /LIBRARY=file.lbt

    Example:  flint -L vmslib.lbt  vmslib.lsh               under UNIX

              flint /LIBRARY=mylib.lbt mylib.for            under VMS

/LPP=

    See  "-Y".

-m,   /IMPLICIT

    Description:  Reports the use of implicit data typing.

    UNIX syntax:   -m

    VMS  syntax:   /IMPLICIT

-M,   /MISC=   (F90 only)

    Description:  Miscellaneous options:

             ansi_maxloc     Modifies the rules used for HPF checking.
                       For additional information, see section 4.9.

             depend    If  this  sub-option is specified,  Fortran  90
                       source-  file order is irrelevant.  Note:  This
                       sub-option  adds an extra pass,  which  reduces
                       processing speed slightly.

             depend:filename
                       FORTRAN-lint   will  output  the   FORTRAN-lint
                       sorted file list and the file dependencies  via
                       USE  association  to  the specified  file.  The
                       filename   extension  ".dep"  is   added   auto
                       matically.

                       If the source files are in order, depend is not
                       required.

             help      Outputs  a "help" screen describing these  sub-
                       options.

             hpf       Enables  HPF  checking. For additional  informa
                       tion, see section 4.9.

             noexit    For  UNIX users who use shell scripts to  check
                       FORTRAN-lint  results.  This  sub-option  tells
                       FORTRAN-lint to return zero unless errors  were
                       detected.

             uselbt    Modifies the precedence rules used for  library
                       template    (.lbt)   files.   For    additional
                       information, see section 9.3.

    UNIX syntax:   -M option,...

    VMS  syntax:   /MISC=(option,...)

/NOI4

    See  "-2".

-O,   /SUPPRESS=

    Description:  Disables or enables individual diagnostic messages.

    UNIX syntax:  -O msg#,msg#,...   disables messages by number
                  -O +msg#,+msg#,... enables  messages by number

                  -O all   disables all numbered messages
                  -O +all  enables  all numbered messages

                  -O msg#,+msg#,...  disable/enable can be mixed

    VMS syntax:   /SUPPRESS=(msg#,...)    disables messages by number
                  /SUPPRESS=(+msg#,...)   enables  messages by number

                  /SUPPRESS=ALL  disables all numbered messages
                  /SUPPRESS=+ALL enables  all numbered messages

                                          disable/enable can be mixed
                  /SUPPRESS=(msg#,+msg#,...)

/OUTPUT=

    Description:  (VMS only.)  Redirects output to a specified file.

                   Note:  Under  UNIX,  use  standard-I/O  redirection
             (flint ... > file).

    UNIX syntax:   N/A

    VMS  syntax:   /OUTPUT=file

    See also: -S or /SPLIT

-p

    Description:  (UNIX only.)  Sends all source files through the 'C'
             preprocessor.

             Note:  FORTRAN-lint sends files with  the  ".F"  filename
             extension  through the 'C' preprocessor, whether  or  not
             the "-p" option is selected.

    UNIX syntax:   -p

    VMS syntax:    N/A

-P,   /PORT=

    Description:  Checks for portability issues related to one or more
             compilers or FORTRAN dialects.

             Supported environments include:

                  ANSI77  (FORTRAN 77)          HPUX
                  ANSI90  (Fortran 90)          LAHEY
                  CRAY                          SGI
                  DECUNIX                       SUN
                  DECVMS                        VAXULTRIX
                  EPC

             For additional information, see sections 4.5 through 4.7.

    UNIX syntax:   -P system,...

    VMS  syntax:   /PORT[ABILITY]=(system,...)

-q,   /QUIT

    Description:             This  option is related  to      FORTRAN-
             lint's  license  manager (see appendix  C).  By  default,
             FORTRAN-lint  waits  for  a  free  license,  if  none  is
             available.  If "-q" (or /QUIT) is specified, FORTRAN-lint
             terminates immediately, in this case.

    UNIX  syntax:  -q

    VMS  syntax:   /QUIT

-R,   /FORM=

    Description:   When Fortran 90 sources are processed, FORTRAN-lint
             normally  determines the source format  (fixed  or  free)
             based  on the filename extension. "-R" (or /FORM) may  be
             used  to  specify  the  source  format  explicitly.   For
             additional information, see section 4.1.

             Note:  This option does not apply to FORTRAN 77 code.

    UNIX syntax:   -R fixed       Specifies fixed form
                   -R free        Specifies free form

    VMS  syntax:   /FORM=fixed    Specifies fixed form
                   /FORM=free     Specifies free form

-s,   /STATISTICS

    Description:   Enables  statistics  and related  output.  If  this
             option is used, FLINT displays a screen after analysis is
             completed   which  includes  I/O  statistics,  structural
             statistics  (subroutine counts, etc.) and a list  of  the
             error  messages  which occurred most  frequently  in  the
             source code.

    UNIX syntax:   -s

    VMS  syntax:   /STATISTICS

    See also: -+  (or /SUMMARY)

-S,   /SPLIT=

    Description:  Sends FORTRAN-lint output to a group of text files.

             If this option is used, FORTRAN-lint stores its output as
             fol-lows:

             Analysis output               -->  name.lnt
             Statistics  ( /STATISTICS)    -->  name.stt
             Call tree   ( /TREE)          -->  name.tre
             Cross-reference  ( /XREF)     -->  name.xrf

             where  name  is  specified by "-S name" (under  UNIX)  or
             "/SPLIT=name" (under VMS).

    UNIX syntax:   -S name

    VMS  syntax:   /SPLIT=name

    See also: -+ (or /SUMMARY)

/SUMMARY

    See  "-+" at the end of this list.

/SYSTEM=

    See  "-V".

-t,   /TREE

    Description:   Generates a "call tree"; i.e., a structural diagram
            of the "call" structure used by the source code. For call-
             tree  format  options, see "-T" or /TREE. For  additional
             information on call trees, see chapter 7.

    UNIX syntax:   -t

    VMS  syntax:   /TREE

    See also: -T

-T,   /TREE=

    Description:   Sets  call-tree sub-options and  generates  a  call
             tree. (The "help" sub-option is a special case.)

             The following sub-options are supported:

             alphabetical    FORTRAN-lint normally displays  sub-trees
                       using  the order in which routines were called.
                       If   "alphabetical"  is  used,  sub-trees   are
                       displayed in alphabetical order. "alphabetical"
                       may be abbreviated to "alpha".

                       To  restore the default mode of  operation, use
                       "-T noalpha" (or /TREE=noalpha).

             condensed 
                       Merges multiple  calls to the same routine.  To
                       restore  the  default  mode  of  operation, use
                       "-T nocondensed" (or /TREE=nocondensed).

             graphics=xxx    Changes the graphics characters  used  to
                       print    the    call   tree.   For   additional
                       information, see section 7.3.5.

             head:symbol     Generates  a  call tree starting  at  the
                       specified symbol.

             help      Displays  a "help" screen describing the  call-
                       tree  options.  No processing is done, if  this
                       sub-option is selected.

             nolibrary
                       Suppresses calls to routines defined in librar-
                       ies (i.e., ".lbt" files). For additional infor-
                       mation, see section 7.4.3  and chapter 9.

             noundefined
                       Suppresses calls to undefined routines.

             squish    To  improve readability,  FORTRAN-lint normally
                       adds  extra white space to call trees. "squish"
                       removes the extra space.

                       To  restore the default mode of  operation, use
                       "-T nosquish" (or /TREE=nosquish).

             trim      This sub-option merges  redundant  sub-trees to
                       reduce the size of the output.

                       The  configuration file shipped  with  FORTRAN-
                       lint  enables trim, by default. To disable this
                       sub-option, use "-T notrim" (or /TREE=notrim).

                       "trim"  is  strongly  recommended  for  systems
                       which are low on disk space.

                       For  additional information on call trees,  see
                       chapter 7.

    UNIX syntax:   -T option,...

                  Note:  To set call-tree options without generating a
             call tree, use -T option,...  followed by  "--t".

    VMS  syntax:   /TREE=(option,...)

                  Note:  To set call-tree options without generating a
             call tree, use /TREE=(option,...)  followed by  "--t".

-u,   /USAGE

    Description:   Enables variable usage checking.  For example, this
             feature de-tects variables which are referenced, but  not
             set.

             The  configuration file shipped with FORTRAN-lint enables
             this  option,  by  default.  If  usage  checking  is  not
             required for a given project, "--u" (or /NOUSAGE) may  be
             used  to  disable  this option. Some operations  will  be
             slightly faster if usage checking is disabled.

    UNIX syntax:   -u

    VMS  syntax:   /USAGE

/UNIXHELP

    See "-?" at the end of this list.

-V,   /SYSTEM=

    Description:   FORTRAN-lint  normally  assumes  that  the  FORTRAN
             compiler  running  on the host system will  be  used.  To
             select a different environment, use this option.

               "-V"  (or /SYSTEM) tells FORTRAN-lint to assume that  a
             specific compiler (or FORTRAN dialect) will be used.

             This  allows FORTRAN-lint to resolve ambiguous extensions
             (constructs   that   look  similar,   but   are   handled
             differently in different environments).

             Supported environments include:

                  ANSI77  (FORTRAN 77)          HPUX
                  ANSI90  (Fortran 90)          LAHEY
                  CRAY                          SGI
                  DECUNIX                       SUN
                  DECVMS                        VAXULTRIX
                  EPC

             For additional information, see sections 4.5 through 4.7.

    UNIX syntax:   -V system

    VMS  syntax:   /SYSTEM=system

-w,   /WARNINGS

    Description:  Enables "warning" messages.

             The  configuration file shipped with FORTRAN-lint enables
             this option, by default. To disable warnings, use --w (or
             /NOWARNINGS).

    UNIX syntax:   -w

    VMS  syntax:   /WARNINGS

-W,   /WIDTH=

    Description:   Sets  output width in columns. This option  affects
             all  output,  including diagnostic  messages  and  cross-
             reference tables.

             Any value between 40 and 500 may be used. Under UNIX, the
             default width is 80 columns. Under VMS, the default width
             is  80 columns unless /OUTPUT is used; in this case,  the
             default width is 132 columns.

    UNIX syntax:   -W number

    VMS  syntax:   /WIDTH=number

-x,   /XREF

    Description:    Generates  a  cross-reference  table.  For  cross-
             reference   format  options,  see  "-X"  or  /XREF.   For
             additional  information  on cross-reference  tables,  see
             chapter 8.

    UNIX syntax:   -x

    VMS  syntax:   /XREF  or  /XREFERENCE

-X,   /XREF=

    Description:   Sets  cross-reference sub-options and  generates  a
             cross-reference table.

             The following sub-options are supported:

             freeform
                       Selects a compact  variable-width format.  This
                       is the default setting.

             tabular   Selects a fixed-width (132 column) format.

             linenumbers
                       Locations  by  line numbers rather than by sub-
                       program.

             noequiv   By default, the cross-reference entry
                       for a given variable includes usage information
                       for the associated equivalences, whether or not
                       the   variable   is   used  directly.   noequiv
                       suppresses equivalence usage information.

             nolegend  Suppresses the legend which describes
                       line num-ber usage codes.

             filters   FORTRAN-lint   supports  cross-reference
                       filters. Filters may be used to generate cross-
                       reference tables for items which meet  specific
                       constraints.  For  additional information,  see
                       sections 8.3 and 8.4.

                    For   additional  information  on  cross-reference
             tables, see chapter 8.

    UNIX syntax:   -X option,...

                    Note:   To  set  cross-reference  options  without
             generating   a   cross-reference,  use  "-X   option,..."
             followed by  "--x".

    VMS  syntax:   /XREF[ERENCE]=(option,...)

                    Note:   To  set  cross-reference  options  without
             generating  a  cross-reference,  use   /XREF=(option,...)
             followed by  "--x".

-Y,   /LPP=

    Description:   Sets lines per output page.  To disable pagination,
             use a page length of zero.

             The default value is zero for console output and 60 lines
             per page if  "-S", "-+", /OUTPUT, /SPLIT, and/or /SUMMARY
             are used to redirect output.

    UNIX syntax:   -Y number

    VMS  syntax:   /LPP=number

-2,   /NOI4

    Description:   On  most  systems, integers and logicals  are  four
             bytes long, by default.

             If   "-2"  (or  /NOI4)  is used, FORTRAN-lint  interprets
             INTEGER   and   LOGICAL  as  INTEGER*2   and   LOGICAL*2.
             Additionally, integer and logical constants  are  treated
             as  two-byte values unless they are too large to fit into
             the smaller size.

    UNIX syntax:   -2

    VMS  syntax:   /NOI4

-7,   /LANG=name
-9

    Description:   This  option  may  be used  to  specify  the  input
             language (FORTRAN 77 or Fortran 90).

    UNIX syntax:   -7         Selects FORTRAN 77
                   -9         Selects Fortran 90

    VMS  syntax:   /LANG=F77  Selects FORTRAN 77
                   /LANG=F90  Selects Fortran 90

-+,   /SUMMARY

    Description:   The  command-line  option   "-+"  (under  UNIX)  or
             /SUMMARY (under VMS) combines three operations:

             (a) This option  displays a  progress meter  which tracks
                 the progress of FORTRAN-lint in real time.

             (b) It  redirects  FORTRAN-lint output  (as explained  in
                 section 2.2.1).

                 By default,  "-+" (or /SUMMARY) redirects the  output
                 to files named flint.lnt, flint.tre,  etc.  "-S"  (or
                 /SPLIT)  may  be used to  specify  a  different  base
                 name.

             (c) It displays an error-message summary (as described in
                 section 2.2.2).

    UNIX syntax:   -+

    VMS  syntax:   /SUMMARY

-?,    /UNIXHELP

    Description:  (VMS only.)  Displays FORTRAN-lint's "letter" option
             switches.

             This  option is not supported under UNIX. To display  the
             "letter"  switches  under UNIX,  execute  flint  with  no
             parameters.

             For additional information, see section 3.1.2.

    UNIX syntax:   N/A

    VMS  syntax:   -?  or  /UNIXHELP

3.1.4 Using UNIX Switches Under VMS

FORTRAN-lint's "letter" option switches  (-letter) can  be  also  used
under VMS.

"Letter" switches can be used inside flint configuration files with no
special rules or restrictions. However, if "letter" switches are  used
on the VMS command line, three rules apply:

    (a) "letter" switches do not include white space
    (b) "letter" switches are limited to one argument per switch
    (c) upper-case switches must be double-quoted

For example, the following VMS flint commands are equivalent:

    flint /PORT=sgi   foo.for
    flint "-Psgi"     foo.for

To specify multiple arguments for a "letter" switch on the VMS command
line, use  multiple copies of the switch.  For example, the  following
commands are equivalent:

    flint /TREE=(condensed,nolibrary)   foo.for
    flint "-Tcondensed" "-Tnolibrary"   foo.for

As under  UNIX,  lower-case "letter" options may be  combined  into  a
single switch. For example, the following commands are equivalent:

    flint /IMPLICIT /XREF /NOI4   foo.for
    flint -mx2                    foo.for

Additional VMS examples:

1)  flint /IMPLICIT   foo.for
    flint -m          foo.for

2)  flint /SPLIT=result /WARNINGS /WIDTH=50   foo.for
    flint "-Sresult" -w "-W50"                foo.for

3)  flint /ANSI /FYI /GLOBAL /SUPPRESS=(201,202)   foo.for
    flint -afg "-O201" "-O202"                     foo.for

----------------------------------------------------------------------

3.2 Summary of Options

3.2.1 UNIX Option Summary

Source configuration options:

    -d                 Process "debug" lines
    -e                 Extend source width to 132 columns
    -I  path,...       Set search path for INCLUDE files
    -p                 Send source files through preprocessor (CPP)
    -R  form           Specify Fortran 90 source form
    -V  system         Specify FORTRAN dialect
    -2                 Two-byte integers and logicals
    -7                 Select FORTRAN 77
    -9                 Select Fortran 90

Diagnostic options:

    -a                 Report non-ANSI constructs
    -f                 Report FYI messages
    -g                 Enable global processing
    -m                 Report implicit typing
    -O  number,...     Suppress individual error messages
    -P  system,...     Enable portability checking
    -u                 Check data usage
    -w                 Enable warnings

Cross-reference options:

    -x                 Generate cross-reference table
    -X  option,...     Specify  cross-reference sub-options

Call tree options:

    -t                 Generate "call tree"
    -T  option,...     Specify  "call tree" options

Output format options:

    -I                 (Upper-case eye)  Expand INCLUDE files
    -l                 (Lower-case ell)  Generate source listing
    -W  number         Set output page width
    -Y  number         Set output page length

Other output control options:

    -+                 "Progress/summary" mode (implies -S)
    -B  file           Create database (.fdb) file
    -L  file           Create library  (.lbt) file
    -s                 Generate statistics
    -S  file           Split output and redirect it

Miscellaneous options:

    -D  definition,... Define preprocessor-level symbols
    -E  file           Expand configuration file
    -M option,...      Miscellaneous options
    -q                 Quit if no licenses are available

3.2.2 VMS Option Summary

Source configuration options:

    /DLINES            Process "debug" lines
    /EXTEND            Extend source width to 132 columns
    /FORM=form         Specify Fortran 90 source form
    /LANG=language     Specify language (F77 or F90)
    /NOI4              Two-byte integers and logicals
    /SYSTEM=system     Specify FORTRAN dialect
    /PATH=([path],...) Set search path for INCLUDE files

Diagnostic options:

    /ANSI              Report non-ANSI constructs
    /FYI               Report FYI messages
    /GLOBAL            Enable global processing
    /IMPLICIT          Report implicit typing
    /PORT=(system,...) Enable portability checking

    /SUPPRESS=(number,...)
                       Suppress individual error messages
    /USAGE             Check data usage
    /WARNINGS          Enable warnings

Cross-reference options:

    /XREF              Generate cross-reference table
    /XREF=(option,...) Specify  cross-reference sub-options

Call tree options:

    /TREE              Generate "call tree"
    /TREE=(option,...) Specify  "call tree" sub-options

Output format options:

    /INCLUDE           Expand INCLUDE files
    /LIST              Generate source listing
    /LPP=number        Set output page length
    /WIDTH=number      Set output width

Other output control options:

    /DATABASE=file     Create database (.fdb) file
    /LIBRARY=file      Create library  (.lbt) file
    /OUTPUT=file       Redirect output to a specified file
    /SPLIT=file        Split output and redirect it
    /STATISTICS        Generate statistics
    /SUMMARY           "Progress/summary" mode (implies /SPLIT)

Miscellaneous options:

    /FILES=file        Expand configuration file
    /MISC=(option,...) Miscellaneous options
    /QUIT              Quit if no licenses are free
    /UNIXHELP  or  -?  Display UNIX "letter" options

----------------------------------------------------------------------

3.3 Configuration Files

Command-line arguments may be specified indirectly, using text files.

If bar.txt is a text file containing option switches or filenames, the
following commands will add the contents of bar.txt  to  the  FORTRAN-
lint argument list:

    flint -E bar.txt foo.f                                  under UNIX
or
    flint /FILE=bar.txt foo.for                             under VMS

bar.txt may specify any number of switches or filenames. There are two
restrictions:

    (a) Arguments must be separated by white space or newlines
    (b) Under UNIX, wildcards (such as "*.for") are not supported

Files used this way are called configuration files.

FORTRAN-lint may be used for multiple purposes: quick  syntax  checks,
mapping out  unfamiliar  programs,  etc.  Configuration  files  are  a
convenient way to select different sets of options.

To set FORTRAN-lint options automatically, create a configuration file
named flint.cfg and add option switches to this file.

FORTRAN-lint searches for flint.cfg in the following directories:

    (a) Current working directory

    (b) Directories  specified  by the  environment  variable FLINTCFG
        (under UNIX) or logical FLINTCFG (under VMS)

    (c) FORTRAN-lint installation directory,  as specified by the env-
        ironment variable  FLINTHOME (under UNIX) or logical FLINTHOME
        (under VMS)

Note:  Command-line  option switches may be used to  override  options
set by flint.cfg.

Multiple  configuration  files  may  be  used;  e.g.,  for   different
projects. FLINTCFG should be set appropriately for  users  working  on
each project.

For additional information on FLINTCFG and FLINTHOME, see section 3.4.

FORTRAN-lint does not impose a fixed limit on configuration-file  line
length. However,  system  constraints  may  impose  a  limit  of  1024
characters per line for some environments.

This is a typical flint.cfg file:

-w                    ! Enable warnings
-u                    ! Enable usage checking
-O207                 ! Suppress Hollerith constant warning
-O261                 ! Suppress "initializer data type converted"
-Ttrim                ! Make TRIM the default call-tree format
--t                   ! Default setting: turn call tree off
                      ! Eliminate unreferenced parameters
-Xno_unreferenced_parameters
                      ! Show common variables only where they are used
-Xno_unused_common_variables
--x                   ! Default setting: turn cross-reference off

Note: VMS  configuration  files  may  use  "letter"  switches  without
special rules or restrictions. However, several restrictions apply  if
"letter" switches  are used on the VMS command line.   For  additional
information, see section 3.1.2.

For the  current  set of default options, see the  copy  of  flint.cfg
provided with FORTRAN-lint.

----------------------------------------------------------------------

3.4 Environment Variables / Logicals

FORTRAN-lint recognizes  the  following environment  variables  (under
UNIX) or logicals (under VMS):

Variable      Description
-----------   --------------------------------------------------------
FLINTCFG      Directory that contains alternate support files (see be-
              low)
FLINTHOME     FORTRAN-lint installation directory
FLINTHOST     Hostname of syetem running license-manager daemon
TMPDIR        (UNIX only) Directory used for temporary files
SYS$SCRATCH   (VMS  only) Directory used for temporary files

FLINTHOME specifies  the location of the main  FORTRAN-lint  directory
(i.e., the directory where FORTRAN-lint was installed). This  variable
is set during installation (see appendix A or appendix B).

FORTRAN-lint includes  a  license-manager  daemon  (see  appendix  C).
FLINTHOST specifies the system where the daemon resides. This variable
is also set during installation.

FORTRAN-lint uses the following run-time support files:

    flint.cfg     Configuration file (see section 3.4)
    flint.err     Error messages
    flint.hls     "Help" file
    unixlib.lbt   UNIX library definitions  (see chapter 9)
    vmslib.lbt    VMS  library definitions

By default,  FORTRAN-lint uses the copies stored in the main  FORTRAN-
lint directory (i.e., the FLINTHOME directory). However,  if  FLINTCFG
is defined,  FORTRAN-lint searches the FLINTCFG directory for  support
files before it loads the default copies.  Users may set this variable
to load customized versions of the support files.

Under UNIX,  FLINTCFG  specifies one or  more  directories  using  the
following format:

    directory-path
or  directory-path:...:directory-path

Note:  Directory paths must be separated by colons.

Under VMS,  FLINTCFG  specifies  one or  more  directories  using  the
following format:

    directory-path
or  directory-path,...,directory-path

Under VMS, directory paths must be separated by commas.

Users may define TMPDIR (under UNIX) or SYS$SCRATCH (under VMS) to set
or change the directory where FORTRAN-lint stores its temporary files.

Note: TMPDIR  is  ignored  on UNIX systems  which  don't  support  the
standard library routine "tempnam()".

Chapter 4

FORTRAN-lint Source Conventions

4.1 Source Format

FORTRAN-lint accepts one or more FORTRAN source files as  input.  Each
source file  may contain one or more FORTRAN subprograms  (or  program
units). A  subprogram/program unit may be a subroutine, a function,  a
block data module, or a main program. INCLUDE-file names should not be
specified explicitly on the command line or in configuration files.

FORTRAN-lint understands several different source formats. In  FORTRAN
77 mode  (-7  or /LANG=F77 option), FORTRAN-lint assumes ANSI-standard
fixed format, with a continuation indicator at column 6 and a  comment
field starting at column 73. To process FORTRAN 77 code  that  extends
past column  72,  add the option "-e" (under UNIX) or  /EXTEND  (under
VMS).

In Fortran  90 mode (-9 or /LANG=F90 option), sources may  use  either
free format  or  FORTRAN  77 fixed format. Variable-position  comments
(starting with  '!')  may  be used in either  fixed  or  free  format.
FORTRAN 77-style  comments (starting with a 'C' in column  1)  may  be
used only  in fixed format. Free-format lines may contain  up  to  132
characters.

TAB formatting  is supported for target environments  that  allow  it.
I.e., if the label field contains a TAB character, processing skips to
the first non-blank character. If that character is a non-zero  digit,
the source line is treated as a continuation line; otherwise, the line
is treated as a statement. TAB-formatted lines may be intermixed  with
normal fixed-format lines.

FORTRAN-lint normally  distinguishes  between  free-format  files  and
fixed-format files  based on filename extension.  By  default,  ".f90"
files are assumed to be free format and other files are assumed to  be
fixed or  TAB  format. To override the default setting, use  the  "-R"
option (under  UNIX) or the /FORM option (under VMS).  For  additional
information, see chapter 3.

The maximum number of continuation lines supported is 1,000 lines  per
statement, and   there  is a maximum of 32,000 significant  characters
per statement.

4.1.1 "Debug" Lines

Source lines  starting with "D" in column one (or "Y", for  EPC  code)
are "debug"  lines. By default, "debug" lines are treated  as  comment
lines. If  "-d" (or /DLINES) is specified, FORTRAN-lint  will  process
"debug" lines along with normal source code.

----------------------------------------------------------------------

4.2 Include Files

Standard INCLUDE statements are supported. FORTRAN-lint  searches  the
following directories for INCLUDE files:

    (a) The directory  which contains the source file that the current
        INCLUDE statement belongs to.

    (b) The user's  current directory  (at the time  when FORTRAN-lint
        was started).

    (c) (VMS  only.) The absolute path specified by the INCLUDE state-
        ment (taking logicals into account).

    (d) Directories specified by  "-I" (or /INCLUDE)  option switches,
        moving from left to right.

    (e) (UNIX only.)  The standard directory "/usr/include".

If an  INCLUDE  file can't be located, FORTRAN-lint  prints  an  error
message and attempts to continue.

INCLUDE files may be nested up to 10 levels deep.

Note: Under UNIX, FORTRAN programs may use both INCLUDE statements and
"#include" statements.   "#include" is similar  to  INCLUDE;  however,
"#include" statements  are  handled  by  the  'C'  preprocessor.   For
additional information, see the next section.

----------------------------------------------------------------------

4.3 'C' preprocessor (UNIX only)

Under UNIX,  FORTRAN-lint supports the 'C' preprocessor. I.e.,  source
files may  use  standard  'C'   "#define",  "#ifdef",  and  "#include"
statements.

Source files  with  ".F"  filename extensions  are  sent  through  the
preprocessor automatically. If the command-line option "-p"  is  used,
FORTRAN-lint  sends  all  source  files  through   the   preprocessor,
regardless of filename extension. Preprocessor output is then  checked
at the  FORTRAN  level.  Line  numbers used  for  error  messages  are
translated appropriately.

By  default,   FORTRAN-lint   assumes   that   the   preprocessor   is
/usr/lib/cpp. To use a different preprocessor, run flpatch  and  patch
the  cpp   parameter   in  the  flint  executable.   (For   additional
information, see appendix A.)

The  option  switch  "-D"  may  be  used  to  define  symbols  at  the
preprocessor level, and the option switch "-I" may be used to  specify
"#include" directories. For additional information, see chapter 3.

FORTRAN-lint passes  the  following  command-line  arguments  to   the
preprocessor:

    (a) "-D" and/or "-I" option switches, if any
    (b) FORTRAN source-file name
    (c) Output-file name

Note: Files  loaded  by  INCLUDE statements  are  loaded  directly  by
FORTRAN-lint; i.e., these files are not preprocessed.

----------------------------------------------------------------------

4.4 CDD and DBMS Processing (VMS Only)

4.4.1 CDD (Common Data Dictionary) Declarations

FORTRAN-lint supports standard DICTIONARY statements.

DICTIONARY is similar to INCLUDE in that it adds declarations  to  the
current routine. However, DICTIONARY differs from INCLUDE in  that  it
takes data structures from a CDD dictionary instead of a source  file.
FORTRAN-lint uses  the  FORTRAN compiler as a preprocessor  to  expand
DICTIONARY statements into normal code.

4.4.2 DBMS Support (FDML Statements)

FORTRAN-lint supports  FDML statements (for  example,  invoke,  ready,
use, commit, rollback, disconnect, connect, erase, get, modify, fetch,
find, free,  also, null, within, keep, reconnect, and  store).  invoke
statements are preprocessed by the FORTRAN compiler in the same manner
as  DICTIONARY  statements.  FORTRAN-lint  processes  all  other  FDML
statements directly.

Note: Usage checking is suppressed for variables that are  created  by
invoke statements.

4.4.3 CDD/DBMS Requirements

FORTRAN-lint uses the FORTRAN compiler to expand DICTIONARY and invoke
statements into  normal code. The FORTRAN compiler must  therefore  be
installed before these statements can be processed.

Additionally, the VMS CDD package must be installed before  DICTIONARY
statements can  be  processed,  and  the  VMS  DBMS  package  must  be
installed before invoke statements can be processed.

----------------------------------------------------------------------

4.5 FORTRAN 77 Extensions

FORTRAN-lint's FORTRAN 77 support is based on the 1978 ANSI FORTRAN 77
standard. FORTRAN-lint  also supports extensions  implemented  by  the
following compilers:

System                     Compiler                 Dialect code
-------------------------  -----------------------  ------------------
(ANSI standard)            FORTRAN, ANSI X3.9-1978  ANSI
Cray YMP UNICOS            CFT77 5.0                CRAY
HP9000 Series              HPUX FORTRAN/9000 8.05   HPUX
Silicon Graphics           IRIS-4D 3.3 FORTRAN 77   SGI
SunOS                      Sun FORTRAN 1.4          SUN
VAX/VMS                    DEC FORTRAN Version 6.0  DECVMS
Alpha/Digital UNIX (OSF1)  DEC FORTRAN 6.0          DECUNIX
VAX Ultrix                 VAX FORTRAN              VAXULTRIX

Extensions supported by FORTRAN-lint include, but are not limited  to,
the following:

     Data-type size specifiers (for example, INTEGER*4)
     Records, structures, and unions
     Cray-style and Apollo-style pointers
     Debugging lines with "D" or "Y" in the first column
     TAB formatting
     In-line comments (both "!" and ";" styles)
     Long symbol names with non-alphanumeric characters
     Numerous binary, octal, and hex constant formats
     Hollerith constants
     Namelist I/O
     Dozens of system-specific I/O statement specifiers
     Hundreds of intrinsic functions
     All I/O format strings, including embedded expressions
     Abbreviated and symbolic expression operators
     Recursion
     Array sections and array expressions

----------------------------------------------------------------------

4.6 Fortran 90 Extensions

FORTRAN-lint's Fortran 90 support is based on the 1992  ANSI  Fortran-
Extended (Fortran 90) standard. FORTRAN-lint also supports  extensions
implemented by the following compilers:

System                     Compiler                     Dialect code
-------------------------  -------------------------    --------------
(ANSI standard)            Fortran, ANSI X3.198-1992    ANSI90
DEC VAX/Alpha OpenVMS      DEC Fortran 90               DECVMS
Alpha/Digital UNIX (OSF1)  DEC Fortran 90               DECUNIX
Cray Y-MP UNICOS 7.0+      CF90 Release 1.0             CRAY
Silicon Graphics IRIX 6.1  MIPSpro Fortran 90           SGI
EPC                        EPC Fortran 90               EPC

In particular,  FORTRAN-lint supports High Performance Fortran  (HPF).
For additional information on HPF, see section 4.9.

Note: If  FORTRAN-lint  is used in Fortran 90  mode,  the  FORTRAN  77
extensions are supported, with the exception that debugging lines  are
not allowed in free format.

----------------------------------------------------------------------

4.7 Specifying FORTRAN Dialect

FORTRAN-lint normally assumes that the FORTRAN compiler running on the
host system will be used.

To select  a different compiler, use the "-V" option (under  UNIX)  or
/SYSTEM (under  VMS) and specify a dialect code from  section  4.5  or
4.6. (For option syntax, see chapter 3.)

To flag  code  that is not supported by a specific dialect,  use  "-P"
(under UNIX) or /PORT (under VMS), instead.

----------------------------------------------------------------------

4.8 Default Sizes

On most  systems,  integers  and logicals  are  four  bytes  long,  by
default. To change the default size, use the option "-2" (under  UNIX)
or /NOI4 (under VMS).

If either  of  these  options  are selected,  FORTRAN-lint  interprets
INTEGER and LOGICAL as INTEGER*2 and LOGICAL*2. Additionally,  integer
and logical constants are treated as two-byte values, unless they  are
too large into fit into the smaller size.

----------------------------------------------------------------------

4.9 High Performance Fortran (HPF)

FORTRAN-lint supports High Performance Fortran (HPF).

By default, HPF statements are treated as normal comments.  To  enable
HPF checking, use the option "-Mhpf" (under UNIX) or /MISC=hpf  (under
VMS).

To add  HPF processors and templates to a cross-reference, enable  HPF
checking and select linenumbers or tabular output format:

Under UNIX, use:    -Mhpf  -Xlinenumbers
or                  -Mhpf  -Xtabular

Under VMS, use:     /MISC=hpf  /XREF=linenumbers
or                  /MISC=hpf  /XREF=tabular

For additional information on the linenumbers and tabular formats, see
section 8.3.

For non-DEC  target  systems, FORTRAN-lint  normally  checks  argument
lists for MAXLOC() and MINLOC() using the following rules:

    MAXLOC (ARRAY, DIM, MASK)
    MINLOC (ARRAY, DIM, MASK)

    ARRAY  must be an integer or real array
    DIM    is optional; if present, must be integer scalar
    MASK   is optional; if present, must be of local type and
           conformable with ARRAY

To apply the ANSI X3.198-1992 rules for MAXLOC() and MINLOC(), use the
option  "-Mansi_maxloc" (under UNIX) or /MISC=ansi_maxloc (under VMS).
This option disallows the DIM argument.

Note that "ansi_maxloc" does not apply to DEC targets  (i.e.,  Digital
Fortran 90).

Chapter 5
Controlling Analysis

5.1 Setting the Scope

To enable  global (inter-module) checking, use the "-g" option  (under
UNIX) or /GLOBAL (under VMS). Global checking analyzes FORTRAN sources
as a  group;  this  enables  interface  checking  and  improves  usage
checking of variables passed as actual arguments.

If  "-g"  (or /GLOBAL) is not specified, subprograms are processed  on
an individual basis, and call interface checking is not performed.

----------------------------------------------------------------------

5.2 Message Classification

FORTRAN-lint  checks for  the following five  general classes of prob-
lems:

     syntax problems

     subprogram interface problems

     variable usage problems

     portability problems

     implicitly typed variables

Syntax problems are constructs that will not compile or  that  may  be
interpreted by  the  compiler in a different way than  the  programmer
intended.  This  includes  symbol names  that  have  embedded  blanks,
re-declared  or   re-dimensioned  variables,  and  poorly   structured
branches using GOTOs.

Interface  problems   are  problems  with  the   interaction   between
subprograms. This includes inconsistent argument lists in function  or
subroutine calls, inconsistent common block organization,  and  unused
or missing subroutines and functions.

Usage problems cover improper use of variables and arrays.   Variables
should be both set and referenced; any deviation from this is flagged.
Attempted redefinition  of  constants  in  subprogram  calls  is  also
flagged.

Portability problems  are constructs that  are  allowed  on  the  host
system but are not recognized or are interpreted differently on  other
systems.   This  includes  structures,  pointers,  data  type   length
specifiers, and other extensions.

Implicitly-typed variables can be flagged whether or not the "IMPLICIT
NONE" statement  is used.  If "IMPLICIT NONE" is used,  they  will  be
categorized as syntax errors.

FORTRAN-lint breaks  syntax problems, interface problems,  data  usage
problems, and portability problems down into three levels of severity:

     Error  messages are the most serious and indicate that  the  code
     will not compile or, probably, will not operate correctly.

     Warning  messages  flag  constructs  that  may  not  operate   as
     intended, that may cause intermittent problems, or that may  make
     no sense.

     FYI  (or "for your information") messages are used to flag  minor
     issues which may or may not be problems.

----------------------------------------------------------------------

5.3 Selecting Analysis Level

Categories of messages may be enabled or disabled using the  following
options:

     Syntax            Always enabled

     Interface         "-g"  (under UNIX) or /GLOBAL (under VMS)

     Usage             "-u" or /USAGE (This option is on, by default.)

     Portability       "-a" or /ANSI
                       -Psystem  or  /PORTABILITY=system  (see section
                       5.5)

     Implicit typing   "-m" or /IMPLICIT

Note: If  global interface checking (-g or /GLOBAL) is enabled,  usage
checking will detect a wider range of problems.

Severity level of messages in the above categories is controlled  with
the following options:

     Errors            Always enabled

     Warnings          "-w" or /WARNINGS  (This option  is on,  by de-
                       fault.)

     FYIs              "-f" or /FYI

To disable a category or level, add an extra dash (e.g., "--w")  under
UNIX or "NO" (e.g., /NOWARNINGS) under VMS.

Examples:

To perform  a  comprehensive analysis, use the options "-gamf"  (under
UNIX) or "/GLOBAL /ANSI /IMPLICIT /FYI" (under VMS).

To perform basic syntax checking, use "--uw" (under UNIX) or "/NOUSAGE
/NOWARNINGS" (under VMS).

----------------------------------------------------------------------

5.4 Suppressing Individual Messages

To suppress individual diagnostic messages, use the "-O" (omit) option
(under UNIX) or /SUPPRESS (under VMS).

"-O" and /SUPPRESS accept  message numbers as arguments.  Message num-
bers are  shown between the  category/severity  field  and the message
text.  Multiple instances  of the same message have  the same  number.
For additional information, see appendix E.

"-O" and /SUPPRESS also accept the word  "all"  as an argument  (e.g.,
"-Oall" or /SUPPRESS=all).  "all" suppresses  all  numbered  messages,
including syntax errors.

If message numbers (or the word "all") are preceded with a  plus  sign
("+"), the specified message or messages are "unsuppressed". E.g.,  if
"-O201" is used to suppress message #201, "-O+201" will re-enable  it.
Note that  an unsuppressed message will be shown only if its  analysis
category and level were selected.

Summary:

    -O arg
    /SUPPRESS=arg       Action
    -------------       -----------------------
    n                   Suppress message #n
    all                 Suppress all messages
    +n                  Unsuppress message #n
    +all                Unsuppress all messages

Example:

"-Oall,+279,+281" (under  UNIX) or "/SUPPRESS=(all,+279,+281)"  (under
VMS) will suppress all messages but #279 and #281. Since messages #279
and #281 are interface FYIs, the options "-gf" or  "/GLOBAL /FYI" must
also be selected in order for these messages to be produced.

----------------------------------------------------------------------

5.5 Portability Checking

To check  for  portability  problems (problems  that  may  occur  when
FORTRAN code  is  ported to different systems), use  the  "-P"  option
(under UNIX) or /PORT (under VMS).

"-P" and  /PORT take target-system names as arguments. Target  systems
are discussed in section 4.5 (FORTRAN 77 extensions) and  section  4.6
(Fortran 90  extensions).  System names include  ANSI,  ANSI90,  CRAY,
DECUNIX, DECVMS,  EPC,  HPUX, NCUBE, OS32, SGI,  SUN,  and  VAXULTRIX.
Multiple targets may be specified.

To flag  non-ANSI constructs, use "-a" (under UNIX)  or  /ANSI  (under
VMS). If  FORTRAN-lint is run in Fortran 90 mode, these  options  have
the same  effect as "-Pansi90" and /PORT=ANSI90. Otherwise, they  have
the same effect as "-Pansi" and /PORT=ANSI.

Example:

If FORTRAN code is being ported to both VAX/VMS and CRAY systems,  use
"-Pdecvms -Pcray" (under UNIX) or "/PORT=(DECVMS,CRAY)" (under VMS) to
check for portability problems related to either target system.

Chapter 6
Analysis Output

6.1 Overview

By default, FORTRAN-lint sends all text output to the console  (stdout
under UNIX  or  SYS$OUTPUT under VMS).  The  output  is  divided  into
sections, which are printed in the following order:

Section                 Controlled by


Current options

List of source files

Source listing          -l        -i
                        /LISTING  /INCLUDE

Analysis output         -g  -u  -m  -P  -a  -w  -f  -O
                        /GLOBAL /USAGE    /IMPLICIT /PORT
                        /ANSI   /WARNINGS /FYI      /SUPPRESS

Call tree               -t     -T
                        /TREE  /TREE=

Cross reference tables  -x     -X
                        /XREF  /XREF=

Statistics              -s
                        /STATISTICS

To redirect  output  under  UNIX, use the  standard  UNIX  redirection
operators or  FORTRAN-lint's   "-S" and   "-+"  options.  To  redirect
output under VMS, use the options  /OUTPUT,  /SPLIT, or /SUMMARY.

For additional information on  "-S" and /SPLIT,  see section  2.2.1 or
chapter 3.

For additional information on  "-+" and /SUMMARY, see section 2.2.3 or
chapter 3.

To modify  the  output page width or page length, use  "-W"  and  "-Y"
(under UNIX) or /WIDTH and /LPP (under VMS).

----------------------------------------------------------------------

6.2 Summary Mode

FORTRAN-lint provides an optional progress meter. The  progress  meter
is a  stationary counter (displayed on the console) which  tracks  the
progress of analysis from 0% to 100%.

To display  the  progress meter, use  "-+" (under UNIX)  or   /SUMMARY
(under VMS).

By default, these options divert normal flint output to a set of  text
files. Specifically, enabling the progress meter also sets the  option
"-Sflint" (under  UNIX) or /SPLIT= flint  (under VMS).  These  options
send analysis  output  to flint.lnt, statistics output  to  flint.stt,
etc. To  specify  a  different base name, add  an  explicit  "-S"  (or
/SPLIT) option to the command line.

Note: After  analysis is complete, FORTRAN-lint  erases  the  progress
meter and displays a summary of the messages produced.

For additional information, see sections 2.2.1 and 2.2.3.

----------------------------------------------------------------------

6.3 Analysis Output

6.3.1 Options and Filenames

The first line of the analysis output shows the FORTRAN-lint  revision
number and  the  current date and time.  The next few lines  show  the
selected options, along with where they were specified.

     Default  options are options that were specified in the flint.cfg
     configuration file in the installation directory.  These are  the
     system defaults.

     User  options  are  options that were specified  in  a  flint.cfg
     configuration  file  in the directory named  in  the  environment
     variable FLINTCFG.  These are a user's custom tailored defaults.

     Local  options  are options that were specified  in  a  flint.cfg
     configuration file in the local directory.  These are usually the
     defaults for a specific project.

     Expanded   options  are  options  that  were   specified   in   a
     configuration file expanded onto the command line with  the  "-E"
     or /FILES option.

     Command options are options that were placed on the command line.

The selected source file names are shown next, grouped by directory. A
source listing follows (if requested), along with diagnostic messages.

6.3.2 Source Listing

To produce  a  source listing, use the "-l" (dash ell)  option  (under
UNIX) or /LISTING (under VMS).

By default,  the  listing  does not expand include  files.  To  expand
include files,  use  the "-i" option (under UNIX) or  /INCLUDE  (under
VMS).

6.3.3 Diagnostic Messages

FORTRAN-lint generates a diagnostic message for each problem  detected
within a  subprogram/program unit. Each message  includes  the  source
line and  a  pointer  to the column where the problem  appears.   Also
shown are  the  name  of the source file, the subprogram/program  unit
name, the line number, the message category and severity, the  message
number, and the message text.

A typical message looks like this:

    >         CALL DIPSTAT( 4, CURITEM)
    >                       ^
    demo.f:PRINTIT
    line 43: INTERFACE ERROR #59- constant is changed by subprogram.

Messages are generally printed in the order they appear in the  source
file, and  are grouped by subprogram/program unit. Each message  group
starts with a header consisting of a row of "*" characters followed by
subprogram/program unit information.  The header looks like this:

    *************************************************************
    Subroutine PRINTIT         File demo.f               Line 39

Additional diagnostic messages may be printed after a  subprogram/pro-
gram unit is  completely processed or after  all subprograms  are pro-
cessed.  For example:

    IMPLICIT- symbols were implicitly typed:  A, AQDATA, DELTI

    USAGE ERROR- local variables referenced but never set: J, K

    SYNTAX FYI- unused labels: 150

----------------------------------------------------------------------

6.4 Statistics Output

To generate statistical reports, use the "-s" option (under  UNIX)  or
/STATISTICS (under  VMS). Statistical reports  include  program  size,
comment  density,  and  diagnostic  messages  summarized  by   number,
category, and severity.

Program size  statistics appear first. The number of source  files  is
shown, followed  by  the number of lines and bytes  of  code  for  the
source files, the include files, and the total of the two:

    Number of source files:  1

    Source files:    52 lines,  1314 bytes
                                (   5% comments, 95% code )
    Include files:   44 lines,  1052 bytes
                                (  14% comments, 86% code )
    Total parsed:    96 lines,  2366 bytes
                                (   9% comments, 91% code )

Counts on "Include files" reflect all appearances of the include files
and will be much higher than that of the  include files alone.  "Total
parsed" is calculated after all include files are expanded.

Byte counts do not include the newline characters.

Comment percentage  is  based on byte counts and  takes  both  comment
lines and  inline comments into account.  The comment  percentage  for
include files  and total parsed is calculated after all include  files
are expanded.  This multiplies the weight of an include  file  comment
by how many times it is included.

A breakdown of subprograms/program units follows:

    Total subprograms:  7
      Subroutines:  6
      Functions:    0
      Program:      1
      Block Data:   0
      Modules:      0

Shown next  is  a  breakdown of the messages  produced.  Messages  are
sorted by frequency of appearance. Displayed for each message are  its
category,   severity,   number,   frequency,   and    message    text.
Context-dependent fields in the message text are  shown  as  astericks
(*).

    Individual message summary
    ------------------------------------------------------------------
    INTRFC  ERR #57-      2x: too many arguments.
    INTRFC  WARN #63-     2x: expression is changed by subprogram.
    SYNTAX  WARN #47-     1x: branch into do loop via label *.
    INTRFC  ERR #56-      1x: not enough arguments.
    INTRFC  ERR #59-      1x: constant is changed by subprogram.
    INTRFC  ERR #95-      1x: this name is defined as a subroutine.

The number of messages is displayed last, shown both in total  and  by
category and severity. The code <supp>, meaning "suppressed", is shown
for message categories and severities that were not selected.

    Total messages:     18

              Errors   Warnings  FYIs
              ------   --------  ----
    Syntax:      0        1        0
    Interface:   8        4        0
    Data usage:  2        1        2

    Implicit typing:    <supp>

----------------------------------------------------------------------

6.5 Exit Status

FORTRAN-lint return status output is as follows:

On VMS systems:

     0x18000001 :  No errors/warnings/FYIs;
     0x18000003 :  FYIs produced;
     0x18000000 :  Warnings (and FYIs) produced;
     0x18000002 :  Errors (and warning/FYIs) produced;
     0x18000004 :  Fatal errors caused FORTRAN-lint to terminate
                   before completion.

On UNIX systems:

     0 :     No errors/warnings/FYIs;
     1 :     FYIs produced;
     2 :     Warnings (and FYIs) produced;
     3 :     Errors (and warning/FYIs) produced;
     4 :     Fatal errors caused FORTRAN-lint to terminate before
completion.

Note that  that  under UNIX, return status 0, 1, or 2  indicates  that
FORTRAN-lint did not detect any errors with the specified options.  If
"-Mnoexit" is  used, FORTRAN-lint will return 0 (only), unless  errors
are detected.

Chapter 7
Call Trees

7.1 Overview

"Call trees" are diagrams which outline the calling structure used  by
the FORTRAN input source files. To generate call trees, use  the  "-t"
option (under UNIX) or /TREE (under VMS).

A typical call tree (using the default format) looks like this:

    FORTRAN-lint    (call tree)
    This is a primary tree starting at the program 'PROCDAT'

    PROCDAT-+-GETUNIT
            |
            +-READNAME
            |
            +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT*
            |                         |
            |                         +-GETTING
            |
            +-PRINT--PRINTIT-+-DIPSTAT--*PRINT*
                             |
                             +-GETTING

For the source code used by this example, see appendix E.

----------------------------------------------------------------------

7.2 Tree Options

To modify  the call tree format, use the "-T" option (under  UNIX)  or
/TREE (under  VMS).  These switches take one or more   sub-options  as
arguments,  specified as follows:

    -Toption1,option2,option2, ...                          under UNIX
or
    /TREE=(option1,option2,option2, ...)                    under VMS

For a list of sub-options, see the next section.

7.2.1 Arguments

"-T" and /TREE accept the following sub-options:

{no}alphabetic     Calls are normally listed using the order in  which
              they   occur.   This   sub-option   sorts   call   trees
              alphabetically.  The condensed option  is   recommended,
              in this mode.

{no}condensed      Condenses multiple calls to the same routine. If  a
              routine  calls the same routine many times, these  calls
              are  merged  into  one  call.  (For  older  versions  of
              FORTRAN-lint, this is the default mode.)

disable       Disables call-tree output.  This sub-option has the same
              effect as "--t" (under UNIX) or /NOTREE (under VMS).

enable        Enables  call-tree output.  This sub-option has the same
              effect as "-t" (under UNIX) or /TREE (under VMS).

graphics=xx:xx:... Changes the tree  graphics  characters.  The values
              given are the hex codes for the following shapes:

                (1)      (2)      (3)      (4)      (5)

                          |                 |        |
                -----     |      --+--      +--      +--
                          |        |        |

              The  values are two-digit hex codes separated by colons.
              For  example,  if  the  IBM extended  character  set  is
              available, the following values may be used:

                   graphics=C4:B3:C2:C3:C0

nographics    Restores the default graphics characters (- | + + +).

head:symbol        Suppresses the full call tree and shows a call tree
              with  the  specified symbol as the top  node.   Multiple
              top nodes may be specified.

help          Outputs  a  help screen describing tree  sub-options and
              terminates FORTRAN-lint.

{no}library   Shows calls made to routines defined in library template
              (.lbt) files. For additional information, see chapter 9.

{no}squish         Compresses call trees vertically by removing excess
              line  graphics.  The resulting trees are less  readable,
              but require only half the space.

{no}trim      Trims the call  tree by  suppressing  repeated subtrees.
              This is the  default  mode of  operation.  notrim may be
              used to disable trimming.

              Note:  "notrim" may produce call trees which  require  a
              significant amount of disk space.

{no}undefined
              Shows calls made to routines that are  undefined  in the
              source code or libraries.

----------------------------------------------------------------------

7.3 Call Tree Format

The call  tree  displays  routines,  subroutine  calls,  and  function
references in a graphical format.  The starting routine  is  shown  at
the left top of the graph, and each level of routine calls is shown to
the right  of the calling routine.  Each routine is connected  to  its
called routines by lines drawn from dashes, vertical  bars,  and  plus
signs.  Within each routine, calls are shown in the order they  appear
in the source code.

Routines which are not the program routine and are not called  by  any
other routine are considered "detached".  They will not appear in  the
main tree, but will be shown as the head of their own detached trees.

    Symbol   Explanation

     ( )     Parentheses are used to flag undefined routines

     { }     Braces are  used to  mark  library routines  (from ".lbt"
             libraries)

     [ ]     Square brackets are used to mark Fortran 90 internal sub-
             programs

     @       Precedes calls to dummy routines

     *<name>*
             Marks  recursive chains  that are chopped after the first
             iteration

7.3.1 Trimmed Trees

The size  of call trees grows exponentially with program  size.   This
makes generating a complete call tree of a large program  impractical,
if not impossible.

To "trim"  a call tree, FORTRAN-lint removes duplicate subtrees.  This
brings the size of the tree down to a reasonable level. At each "trim"
point, FORTRAN-lint prints a subtree number which  indicates  where  a
master copy of the associated subtree can be found.

The  default  FORTRAN-lint  configuration  file  includes  the  option
"-Ttrim"; trees are therefore trimmed by default.

Example:

    PROCDAT-+-GETUNIT
            |
            +-READNAME
            |
            +-SETTYPE--PRINT (1)--PRINTIT-+-DIPSTAT--*PRINT*
            |                             |
            |                             +-GETUNIT
            |
            +-PRINT see 1

7.3.2 Condensing Multiple Calls

By default,  call  trees show all of the calls  made  inside  a  given
program.  If one routine calls another several times,  every  call  is
displayed. To  produce a call tree based on the  relationship  between
routines rather  than  the  exact calling  sequence,  use  the  option
"-Tcondensed" (under UNIX) or /TREE=CONDENSED (under  VMS).  The "con-
densed" option merges multiple calls from  one routine to another into
a single association.

Example:

    PROCDAT-+-GETUNIT
            |
            +-READNAME
            |
            +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT*
            |                         |
            |                         +-GETUNIT
            |
            +-PRINT--PRINTIT-+-DIPSTAT--*PRINT*
                             |
                             +-GETUNIT

7.3.3 Sorting Alphabetically

Calls are  normally  shown  in  order of  appearence.  To  sort  calls
alphabetically  (by   routine  name),  use  "-Talphabetical,condensed"
(under UNIX) or "/TREE=ALPHABETICAL,CONDENSED" (under VMS).

Example:

    PROCDAT-+-GETUNIT
            |
            +-PRINT--PRINTIT-+-DIPSTAT--*PRINT*
            |                |
            |                +-GETUNIT
            |
            +-READNAME
            |
            +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT*
                                      |
                                      +-GETTING

7.3.4 Squished Trees

Call trees  are  normally  double-spaced to  improve  readability.  To
produce single-spaced trees, use the option  "-Tsquish"  (under  UNIX)
or /TREE=SQUISH (under VMS).

Limitations of the ASCII character set make single-spaced trees harder
to  read.  If  an  extended  ASCII  character  set  with  line-drawing
characters is  available,  the  graphics  option  should  be  used  in
conjunction with  squish.  For  additional  information,  see  section
7.3.5.

Example:

    PROCDAT-+-GETUNIT
            +-READNAME
            +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT*
            |                         +-GETTING
            +-PRINT--PRINTIT-+-DIPSTAT--*PRINT*
                             +-GETTING

7.3.5 Graphic Character Set

By default, the call tree uses the ASCII characters "-", "|", and  "+"
to connect the routine names.  To specify alternate characters, use:

    -Tgraphics=xx:xx:xx:xx:xx                               under UNIX
or
    /TREE=(GRAPHICS=xx:xx:xx:xx:xx)                         under VMS

where the  xx entries are ASCII character codes expressed as two-digit
hexadecimal values.

The five entries are interpreted as follows:

    (a) 1st code:  horizontal connector
    (b) 2nd code:  vertical connector
    (c) 3rd code:  T intersection
    (d) 4th code:  "|-" intersection
    (e) 5th code:  L intersection

For example,  if  the  IBM extended character set  is  available,  use
c4:b3:c2:c3:c0.

The default values are 2d:7c:2b:2b:2b, for the characters -, |, +,  +,
and +. To restore the default values, use "-Tnographics" (under  UNIX)
or /TREE=NOGRAPHICS (under VMS).

----------------------------------------------------------------------

7.4 Call Tree Content

7.4.1 Top Node

Call trees can be generated with any routine as the top routine.  When
the top  routine  is  selected, the full tree and detached  trees  are
suppressed.

To generate a tree starting at the routine name, use the option switch
"-Thead:name" (under UNIX) or  /TREE=HEAD:name (under VMS).

To  display  multiple  trees,  specify  multiple  routine  names.  For
example:

    -Thead:PRINT,head:SETTYPE                               under UNIX
or
    /TREE=(HEAD:PRINT,HEAD:SETTYPE)                         under VMS

will show trees for both "PRINT" and "SETTYPE":

    FORTRAN-lint    (call tree)
    This is a primary tree starting at the program 'PRINT'

    PRINT--PRINTIT-+-DIPSTAT--*PRINT*
                   |
                   +-GETTING

    This is a primary tree starting at the program 'SETTYPE'

    SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT*
                            |
                            +-GETTING

To cancel a previously-specified "-Thead" (or /TREE=HEAD) switch,  add
"-Tnohead" (under  UNIX) or /TREE=NOHEAD (under VMS)  to  the  command
line. This will restore the full call tree.

7.4.2 Undefined Routines

Call trees  normally  include all calls, whether  or  not  the  called
routines are  defined in the current input files.   FORTRAN-lint  uses
parentheses to flag undefined routines.

To suppress calls to undefined routines, use "-Tnoundef" (under  UNIX)
or /TREE=  NOUNDEF (under VMS). If these options are used, call  trees
will be  restricted to calls between routines defined in  the  current
input files.

To restore  the  default mode of operation (e.g., if  "-Tnoundef"  was
set in  a  configuration  file),  use "-Tundefined"  (under  UNIX)  or
/TREE=UNDEFINED (under VMS).

7.4.3 Library Routines

If  "library"  (.lbt) files are specified on the  command  line,  call
trees will include calls to the associated library routines.  FORTRAN-
lint uses curly braces ({}) to flag library calls.

Calls to library routines will be displayed whether or not the noundef
sub-option is used (see section 7.4.2). However, calls between library
routines are not displayed, in either case.

To generate  call  trees which exclude library  calls,  use  "-Tnolib"
(under UNIX) or /TREE=NOLIB (under VMS).

To restore the default mode of operation, use "-Tlibrary" (under UNIX)
or /TREE= LIBRARY (under VMS).

For additional information on library files, see chapter 9.

----------------------------------------------------------------------

7.5 Recursion

FORTRAN-lint uses  a  pair of astericks to flag recursive  calls.  For
example: See *PRINT* in section 7.4.1.

----------------------------------------------------------------------

7.6 Dummy Routines

FORTRAN-lint uses "@" characters to flag indirect calls;  i.e.,  calls
to a  routine which are made indirectly through the argument  list  of
another routine.

----------------------------------------------------------------------

7.7 Entry Points

The ">" symbol in a call tree indicates that the call was made through
an entry point. For example:

             |
             +-ENTRPT>SUB1
             |

where ENTRPT is the entry point into subroutine or function SUB1.

----------------------------------------------------------------------

7.8 Fortran 90 Internal Subprograms

Square brackets  ([ ]) surrounding a routine name  indicate  that  the
routine is a Fortran 90 internal subprogram or a module subprogram:

    MAIN-+-M
         |
         +-M_INNER
         |
         +-OUTER--M
         |
         +-[MAIN_INNER]

Chapter 8
Cross Reference

8.1 Overview

To generate a symbol table cross-reference, use the option "-x" (under
UNIX) or /XREF (under VMS).

Cross-reference tables  can be generated from  source  files  or  from
database files (see chapter 10).

The option  switches "-X" and /XREF may be used to specify sub-options
that control the format and content of the cross-reference table.

The UNIX cross-reference format/content sub-options are:

    -Xfreeform          Free-form cross-reference
    -X{no}tabular       Selects tabular format (vs. freeform)
    -X{no}equiv         Selects equivalence usage information
    -X{no}line          Line resolution (vs. subprogram resolution)
    -X{no}legend        Selects legend for line resolution codes

The VMS cross-reference format/content sub-options are:

    /XREF=freeform      Free-form cross-reference
    /XREF={no}tabular   Tabular format (vs. freeform)
    /XREF={no}equiv     Selects equivalence usage information
    /XREF={no}line Line resolution (vs. subprogram resolution)
    /XREF={no}legend    Selects legend for line resolution codes

Two cross-reference formats are supported:  freeform and tabular.

freeform is the default format. This format uses variable-length lines
and shows  information using a compact layout. The default sub-options
for this  format  are  "-Xnoline" and "-Xnolegend"  (under  UNIX)   or
/XREF=noline and /XREF= nolegend (under VMS).

The tabular cross-reference format organizes fields into columns. This
format is  at  least 132 characters wide. The default sub-options  for
tabular cross-references are "-Xline" and  "-Xlegend" (under UNIX)  or
/XREF=line and  /XREF=legend (under VMS).

The line or noline sub-option sets the cross reference to either  line
resolution  or   subprogram/program  unit  resolution,   respectively.
Subprogram/program unit resolution shows usage of a  symbol  within  a
subprogram/program unit, while line resolution shows usage of a symbol
on each  line  in which that symbol appears. This must be  set  during
source analysis to have effect.

If the  "-g"  (or  /GLOBAL) option is used, the  cross-reference  will
include additional information. Specifically, dummy argument usage  is
shown for subroutine and function definitions. In addition, the  usage
of the  variables and arrays that are passed as actual  arguments  are
determined.

----------------------------------------------------------------------

8.2 Layout

Symbols are grouped into the following categories:

     programs
     block data subprograms/program units
     subroutines
     functions
     modules (F90 only)
     common blocks
     structures
     records
     variables and arrays
     parameters

Symbols are sorted alphabetically by name within each group.

If a  symbol appears in more than one context (e.g., as a variable  in
one subprogram /program unit and as a subroutine name in another), the
symbol is shown in both groups.

In the tabular format cross reference, the program, block data, module
(F90 only), subroutine, and function sections are combined, as are the
records and variable/array sections.

The information shown for each symbol will vary by category.

8.2.1 Program Routines

This symbol name is derived from the program name given on  a  program
statement. If an unnamed program routine exists, it is given the  name
"Program". Multiple  unnamed programs are named  "Program2,  Program3,
..., etc.".   The  filename  and the line  number  where  the  program
routine begins are shown along with the program name.

8.2.2 Block Data Routines

These are  the symbol names from block data statements.  Like  program
symbols, unnamed  block  data  subprograms/program  units  are   named
"Blockdata", "Blockdata2", etc.

The  filename   and   the   line   number   where   the   block   data
subprogram/program unit begins are shown along  with  the  block  data
name.

8.2.3 Subroutines and Functions

External procedures, internal procedures (F90 only), module procedures
(F90 only), intrinsic procedures, and  statement functions  are  shown
in this section  and are labeled correspondingly.

For functions, the data type is shown.  This is normally the data type
of the  function definition.  If the function is undefined,  the  data
type used by the first function call is used.

An internal  subprogram  (F90  only)  has  its  parent  routine  as  a
qualifier using a double colon (::); for example,  SUB::SUB_INNER.

If the  code  for the subroutine or function appeared in  the  sources
analyzed, the  filename  and  line number of  the  subroutine/function
statement are shown.  If the definition was in a FORTRAN-lint  library
(.lbt) file, the name of the library is shown.

Argument descriptions of external, internal, and  statement  functions
are also shown if the "-g" or /GLOBAL option was used during analysis.
The argument descriptions show the class, data type, and usage of each
argument. Argument class is one of the following:

    <blank>     variable
    array       variable or record array
    subprogram  function or subroutine
    return      alternate return
    ---         unused argument

Argument usage is indicated by the single-letter codes listed below:

    Code        Description
    ----        -----------------
     S          set
     R          referenced (used)
     X          undetermined

For external  and internal subroutines and functions, called  routines
are shown. If the table is in tabular format, the line number of  each
call is shown.

Finally, all  calls  to the function, subroutine  or  F90  module  are
listed. In the tabular cross reference, the locations of the calls are
shown by  subprogram/program unit, filename, and line  number  in  the
References columns.

8.2.4 Modules (F90 only)

These are the symbol names from module statements.

The filename  and  the line number where the module subprogram/program
unit begins are shown along with the module name.

Modules referenced  by  this module are shown.  If  the  table  is  in
tabular format, the line number of each module reference is  shown  in
the Calls column.

Finally, all references to the module via USE association are  listed.
In the  tabular cross reference, the locations of the calls are  shown
by  subprogram/program  unit,  filename,  and  line  number   in   the
References column.

8.2.5 Common Blocks

Common blocks are shown along with their size (in bytes) and a list of
their members.

The routines  that the common blocks appear in are shown,  categorized
into the following groups:

    model           the  definition  used  for  comparison  (shown  as
                    "same" if freeform)
    same            same declaration as the model
    names differ    member types and sizes match model but have
                    different names
    layout differs  member types or sizes do not match the model

8.2.6 Structures and Structure Components

The  cross-reference  lists  all  structures  used  by  the   program,
including their  size, format, and members.  Structures  of  the  same
name, size, and format are merged.

If the  linenumbers or tabular format is selected, the cross-reference
also includes  a section labelled "Structure components"  which  lists
occurrences of structure components. For additional information on the
linenumbers and tabular formats, see section 8.3.

8.2.7 Variables, Arrays, and Records

Variables, arrays,  and  records are  shown  in  this  section.   This
includes automatic  (local),  dummy, common  block  members,  and  F90
module entities.

Arrays are  distinguished by the dimension list.   Each  dimension  is
shown as  either an upper bound or a lower/upper bound pair  separated
by a  colon.  If  the  lower  or upper bounds  are  adjustable,  "adj"
appears. For open-ended dimensions, an asterisk ("*") appears  as  the
upper bound.

The Type  column shows the data type including a length specifier  for
symbols or the name of the associated structure for records.

The Kind column shows the kind parameter of the symbol, if specified.

The Attributes column shows the attributes of each symbol.  Attributes
include local,  pointer,  pointer based,  and  common  block  members.
Common block  members are shown with the name and byte offset  of  the
common block to which they belong.

The References column shows the cross reference information  for  each
symbol. The location resolution is either per subprogram/program  unit
or per  line,  depending  on  the setting of  the  "-Xlinenumbers"  or
/XREF=linenumbers   option   when   the    sources    are    analyzed.
Subprogram/program unit resolution will show  usage  within  each  sub
program/program unit and is described in words.  Line resolution  will
show usage  for  each line the symbol appears on,  and  its  usage  is
described in single-letter codes.

Symbol usage is described as one or more of the following:

    Line        Subprogram     Description
    resolution  resolution
    codes       codes
    ----------  ----------     ---------------------------------------

      ---       Unused         Symbol was not  referenced, set, or in-
                               determinate
      A         Actual arg     Symbol passed as an actual argument
      B         Array bound    Symbol was used as an  adjustable bound
                               for an array
      D         ---            Symbol appeared in a declaration  (type
                               decl, dim, common)
      E         Equivalenced   Appeared in an equivalence statement
      F         SF Dummy arg   Appeared as a  statement function dummy
                               argument
      G         Ref as Label   An  assigned goto  jumped  to label as-
                               signed to this symbol
      I         Indirect Init  A symbol  Equivalenced  to  this symbol
                               was initialized
      I         Initialized    Initialized in data statement,  or when
                               given data type
      L         Set to Label   Symbol was assigned a label
      M         Allocated      Symbol was allocated
      N         Nullified      Symbol was nullified
      O         Optl dummy arg Symbol  appeared as an  optional  dummy
                               argument
      P         Dummy arg      Symbol  appeared  in  a  subroutine  or
                               function statement
      R         Ref            Symbol was  referenced  (its  value was
                               used)
      S         Set            Symbol was assigned a value
      X         Indeterminate  May be ref or set, but exact usage can-
                               not be determined
      Z         Deallocated    Symbol was deallocated

Usage  information   (Ref/Set)  is  carried   through   all   variable
associations, including actual/dummy argument,  common  block  member,
and equivalence associations.

The default  is  to  suppress  unused common  blocks.  For  additional
information, see section 8.4.

8.2.8 Parameters

Parameters are  shown  along with their data  type  and  their  value.
Parameters from  different routines that have the same  name  and  the
same value will be merged.

The following usage codes apply to parameters:

    Line        Subprogram     Description
    resolution  resolution
    codes       codes
    ----------  ----------     ---------------------------------------

      D         ---            Symbol appeared in a  declaration (type
                               decl, parameter)
      R         Ref            Symbol  was  referenced  (its value was
                               used)
      S         Set            Symbol was assigned a value  (parameter
                               statement)

The default  is  to suppress unreferenced parameters.  For  additional
information, see section 8.4.

8.2.9 Equivalences

Entries for variables include equivalence information. For  non-common
block members,  equivalences are named variables in the  same  scoping
unit  or   the   parent   scoping  unit.  For  common-block   members,
equivalences belong to the same common block.

Note:  When  a variable is equivalenced to an array element,  FORTRAN-
lint recognizes  only the array name as an equivalence.  Consequently,
when two  variables that are not common block members are equivalenced
to different  elements of the same array, FORTRAN-lint will  show  the
two variables and the array as the equivalence of one another. In case
of two  different  scalar members of the same common  block  that  are
equivalenced to  different array elements of the same array,  FORTRAN-
lint will show the array as the equivalence of both scalar members.

8.2.10 High Performance Fortran (HPF)

If HPF  checking is enabled, and if the linenumbers or tabular  format
is selected,  the  cross-reference includes a section  which  displays
occurrences of HPF processors and templates.

For additional  information on HPF, see section  4.9.  For  additional
information on the linenumbers and tabular formats, see section 8.3.

----------------------------------------------------------------------

8.3 Format Selection

FORTRAN-lint allows users to select different formats  for  the  cross
reference table by using the "-X" option (under UNIX) or /XREF  (under
VMS). Available formats include:

    -Xfreeform          /XREF=freeform
    -X{no}tabular       /XREF={no}tabular
    -X{no}equiv         /XREF={no}equiv
    -X{no}linenumbers   /XREF={no}linenumbers
    -X{no}legend        /XREF={no}legend

A) freeform / tabular

    "-Xtabular"  (under UNIX) or /XREF=tabular  (under VMS)  selects a
    table style that uses fixed-width columns. The output  is  132  or
    more columns wide. The default line numbering mode for this format
    is "-Xlinenumbers" (under UNIX) or /XREF=linenumbers (under VMS).

    "-Xfreeform" (under UNIX) or /XREF=freeform (under VMS)  selects a
    more compact  style  with fields separated by single  spaces.  The
    default  line numbering mode  for  this  format  is  "-Xnolinenum"
    (under UNIX) or /XREF=nolinenum (under VMS).

B) equiv / noequiv

    By default,  the  cross-reference entry  for a given  variable in-
    cludes usage information for the associated equivalences,  whether
    or not  the variable is used  directly.  To  suppress  equivalence
    usage information,  use "-Xnoequiv" (under UNIX) or  /XREF=noequiv
    (under VMS).

C) linenumbers / nolinenum

    To  produce   cross-reference  tables  with  line   numbers,   use
    "-Xlinenumbers" (under UNIX) or /XREF=linenumbers (under VMS).

    To limit  cross-reference  tables to the  subprogram/program  unit
    level, use  "-Xnolinenum" (under UNIX) or  /XREF=nolinenum  (under
    VMS).

    Note: To  be effective, linenumbers or nolinenum must be specified
    after "-Xtabular", "-Xfreeform", /XREF=tabular, or  /XREF=freeform
    on the command line.

D) legend / nolegend

    If  linenumbers is  selected, FORTRAN-lint prints single-character
    usage codes along with line numbers.  Usage codes are described in
    a legend printed at the end of the cross-reference.

    To suppress  the legend,  use "-Xnolegend" (under UNIX) or  /XREF=
    nolegend (under VMS).

    To restore  the  legend (if it has been disabled), use  "-Xlegend"
    (under UNIX) or /XREF=legend (under VMS).

    Note: To be effective, legend or nolegend must be specified  after
    "-Xtabular", "-Xfreeform",  /XREF=tabular,  or  /XREF=freeform  on
    the  command line.

----------------------------------------------------------------------

8.4 Content Selection

"-X" and /XREF both accept content selection arguments.

Content selection arguments are sentence fragments composed of one  to
six words, separated by underlines or dashes.  Each sentence  fragment
describes a  criterion that can be used to select, add to,  or  filter
cross-reference output.

A complete  content  selection includes the  following  words  as  its
arguments:

under UNIX:    -X{conjunction}{_usage}{_scope}{_class}{_named_xxx}

under VMS:    /XREF={conjunction}{_usage}{_scope}{_class}{_named_xxx}

CONJUNCTIONS  USAGE (ADJECTIVE)   SCOPE (ADJECTIVE)    CLASS (NOUN)

only          used/unused         local (*)            routines
and              ref/unref           dummy/non...         programs
no               set/unset           statement/non...     subroutines
                 called/uncalled     intrinsic/non...     functions
                 indeterm/determ  global (*)              blockdata
              actual/notactual       common/non...        modules
              init/uninit            external/non...   extern
              decl/undecl         internal/non... (*)  blocks
              equiv/unequiv                            structures
                                                       variables
                                                          scalars
                                                          arrays
                                                          records
                                                          parameters

Note: The default conjunction is "only".

(*) dummy or nondummy,  common or noncommon,  internal or noninternal,
etc.

While any  of the words composing the criteria sentence are  optional,
the order  of  the words is significant. All words may be abbreviated,
as long as they remain unambiguous.  A few examples are:

Example                     Result
------------------------    ------------------------------------------
-Xno_unused_variables       Suppress unused variables
-Xand_par_named_+oo         Also show parameters with  names ending in
                            "oo"
-Xonly_ref_dum_var_nam_i    Show referenced dummy variables named "i"
/XREF=common_arrays         Show arrays in common blocks
/XREF=arr_named_a?b+c       Show arrays named
                            a{any-letter}b{zero-or-more-letters}c

(1) The conjunction, if specified, must be first.  This word specifies
    whether the criteria sentence is a selection, filter, or addition.
    The default mode of operation is "ONLY".

    Word  Type       Description
    ----  ---------  -------------------------------------------------
    ONLY  selection  suppress everything but the following (default)
    NO    filter     suppress the following
    AND   addition   add the following to what is already selected
                     (will not be subject to previous filter criteria)

(2) The usage adjective,  if specified,  must be next.  This word acts
    on symbols at the subprogram/program unit level.

    If a symbol is used in a particular subprogram/program unit in the
    fashion described by the usage adjective, the use of  that  symbol
    within the  subprogram/program unit is  included in the selection.
    If the  usage adjective is omitted,  FORTRAN-lint disregards usage
    when determining the selection.

    Word            Antonym          Description
    -------------   --------------   ---------------------------------
    used            unused           Referenced, set, called, or inde-
                                     terminate)
    referenced      unreferenced
    set             unset
    called          uncalled
    indeterminate   determinate
    actualarg       notactualarg     Variables passed to external rou-
                                     tines
    initialized     uninitialized
    declared        undeclared       Data type, dimensions, or common
    equivalenced    unequivalenced

    Filtering acts on references at a subprogram/program  unit  level,
    filtering out  the references to a symbol that  match  the  filter
    criteria. If  all  references to a symbol are  filtered  out,  the
    symbol itself is suppressed.

(3) The scope adjective, if specified, must be next.

    This is  used  in  a  similar fashion to the usage  adjective  but
    relates to  the  scope of the symbol.  If the scope  adjective  is
    omitted, scope is not used in determining the selection.

    Word            Antonym          Description
    -------------   --------------   ---------------------------------

    local           ---              Dummy, Statement,  Intrinsic,  or
                                     Automatic
    dummy           nondummy         Dummy argument
    statement       nonstatement     Statement function
    intrinsic       nonintrinsic     Intrinsic function
    global          ---              Common or External
    common          noncommon        Common block or common block mem-
                                     ber
    external        nonexternal      External routine

(4) The class noun,  if specified,  must be next.  This  specifies the
    class of the symbol.

    The class noun describes categories of symbols. If the class  noun
    is omitted,  the  selection  contains all  categories  of  symbols
    limited by the usage and scope adjectives.

    Class       Subclasses    Description
    ----------  -----------   ----------------------------------------
    routines                  Programs, subroutines, etc.
                programs
                subroutines   Includes dummy subroutines
                functions     Includes statement, dummy, and intrinsic
                              functions
                blockdata
                external      External routines  which  are  undefined
                              and unused
    blocks      ---           Common blocks
    structures  ---
    variables                 Includes scalars, arrays, and records
                scalars       Single-valued variables
                arrays
                records       Structured records
    parameters  ---           Defined in parameter statement

    (5) The symbol name is specified last.

    This is  composed of two words, the word "named" followed  by  the
    actual symbol name.  The following wildcards are allowed:

           *  or  +  matches zero or more characters
           ?  or  .  matches one character

    Wildcards may be combined.

Example:

    -Xnamed_ab+f.h                                          under UNIX
or
    /XREF=named_ab+f.h                                      under VMS

The default content of the cross reference table is everything  except
unused common variables and unreferenced parameters.

UNIX examples:

    -Xno_intrinsic          Suppress intrinsic functions

    -Xuncalled_routines     Only routines that have not been called

    -Xand_unused_parameters
                            Show unused parameters, too

    -Xno_unused_common_variables

                            Don't  show declarations of  common varia-
                            bles where they are unused (if a symbol is
                            never used, its name does not appear)

VMS examples:

    /XREF=routines          Only show routine names

    /XREF=no_common         Suppress  common blocks  and  common block
                            members

    /XREF=unset_functions   Show only undefined functions

    /XREF=unused_dummy_arrays

                            Show array dummy arguments that are unused

Multiple phrases may be given; these are checked in order from left to
right.  The  phrases may be either on the same option or  on  separate
options.

UNIX example:

    -Xset_variables  -Xno_unref_common_arrays  -Xand_init_common_var

This will  show set variables that are not unreferenced  array  common
block members and any common block members that are initialized.

VMS example:

    /XREF=routines,and_common_blocks

This will show routines and common blocks.

Remember, the default conjunction is "only". The following combination
will produce unexpected results:

    -Xused_variables  -Xequivalenced_variables              under UNIX
or
    /XREF=used_variables  /XREF=equivalenced_variables      under VMS

If the  intent  is  to  produce  a  cross-reference  table  with  only
variables that are used or equivalenced, the above command line option
will not  work.  The  second  argument  (equivalenced_variables)  will
override the  first  argument  (used_variables),  since  the   default
conjunction is  "only".  The cross-reference table  produced  by  this
option will  only  include  equivalenced variables.   To  perform  the
desired operation, use:

    -Xused_variables  -Xand_equivalenced_variables          under UNIX
or
    /XREF=used_variables  /XREF=and_equivalenced_variables

                                                            under VMS

Chapter 9
Library Support

9.1 Overview

FORTRAN-lint can be used to create library template (or ".lbt")  files
for use in subsequent analysis operations.

A library  template (or ".lbt") file is a binary file which  describes
the interface  structure  of  one  or  more  FORTRAN  subroutines   or
functions. ".lbt" files contain FORTRAN "stubs" which are  similar  in
concept to ANSI 'C' prototypes.

".lbt" files  may  be  used  to speed up interface  checking  where  a
project depends on a stable (unchanging) library or package. Adding  a
single ".lbt" file to the FORTRAN-lint command line is effectively the
same as adding all of the associated FORTRAN source files.

Two pre-defined ".lbt" files unixlib.lbt and vmslib.lbt  are  provided
with FORTRAN-lint. unixlib.lbt and vmslib.lbt describe  standard  UNIX
and VMS library routines, respectively. If system library routines are
used (and  if these routines are not defined in user-specified  ".lbt"
files), FORTRAN-lint searches unixlib.lbt or vmslib.lbt automatically.

----------------------------------------------------------------------

9.2 Creating Library Files

To create or update an ".lbt" file, use commands of the form:

    flint -L mylib.lbt file1.f file2.f ...                  under UNIX
or
    flint /LIBRARY=mylib.lbt file1.for file2.for ...        under VMS

These commands add all routines in the specified source files  to  the
file mylib.lbt.  If  mylib.lbt does not exist,  it  will  be  created.
Otherwise, the existing file will be updated.

The "-L"  and /LIBRARY options cause FORTRAN-lint to run in a  special
mode which  bypasses normal analysis. Consequently, source files  must
be debugged and error-free before ".lbt" files are created.

If a library routine is modified, repeat the original "-L" or /LIBRARY
operation to update the associated ".lbt" file. Note that FORTRAN-lint
will not update ".lbt" files automatically.

----------------------------------------------------------------------

9.3 Library Precedence

For analysis purposes,  FORTRAN-lint searches  for definitions as fol-
lows (highest precedence first):

    (1) Definitions found in FORTRAN source files
    (2) Definitions found in the intrinsic table for  the current tar-
        get system
    (3) Definitions found in user-specified ".lbt" files
    (4) Definitions found in unixlib.lbt or vmslib.lbt

By default,  the intrinsic table takes precedence over  user-specified
".lbt" files.  To  search  user-specified  ".lbt"  files  before   the
intrinsic  table,   use  the  option  "-Muselbt"   (under   UNIX)   or
/MISC=uselbt (under VMS).

If uselbt is specified, FORTRAN-lint uses the following search order:

    (1) Definitions found in FORTRAN source files
    (2) Definitions found in user-specified ".lbt" files
    (3) Definitions found in the intrinsic table for  the current tar-
        get system
    (4) Definitions found in unixlib.lbt or vmslib.lbt

Note that  the  default library templates unixlib.lbt  and  vmslib.lbt
have the lowest precedence, whether or not uselbt is specified.

----------------------------------------------------------------------

9.4 Library Shells

Users can  create  ".lbt" files for specific  libraries  or  packages.
FORTRAN-lint provides an option "-L" (under UNIX) or  /LIBRARY  (under
VMS) which  translates user-composed library shell (or  ".lsh")  files
into corresponding ".lbt" files.

Library shell  files  are  text files which  contain  FORTRAN  "stubs"
describing the  interface  structure of  a  library  or  package.  The
FORTRAN-lint package includes two sample ".lsh" files unixlib.lsh  and
vmslib.lsh, which may be used as starting points for new shell files.

unixlib.lsh is the source file for unixlib.lbt, and vmslib.lsh is  the
source file  for vmslib.lbt.  The ".lsh" files may be used  to  extend
the ".lbt" files. To rebuild the ".lbt" files, modify the ".lsh" files
as desired and use commands of the form:

    flint -L unixlib.lbt unixlib.lsh                        under UNIX
or
    flint /LIBRARY=vmslib.lbt vmslib.lsh                    under VMS

The required elements of a library shell file are:

    (1) definition of the return value
    (2) name of the function
    (3) dummy argument list

The data  types  of the dummy arguments and their  usage  need  to  be
defined within  the shell of the function. Switches on  the  arguments
have been  designed  to allow FORTRAN-lint to handle  the  shell  more
efficiently.

Function argument  switches  may only be  used  on  the  arguments  in
function  shells,  not  in  subroutine  shells.   Available   switches
include:

/v       Parameter passed by value.  [call foo(%val(3))]

/q       Suppress  error #251  (scalar passed to array) and  data type
         checking.  This switch  is used  to allow  binary data  to be
         passed in any form  without the data type being checked.  For
         example,  a quadword may be  passed in  any of  the following
         forms: LOG*1 FOO(8), INTEGER*2 FOO(4), or INTEGER*4 FOO(2).

/z       Suppress all interface checking with regard to this argument.
         The argument is of unspecified data type.

/o       This argument is optional.  [call foo(a,,b,,c,d)]

Optional argument switches:

/l       (Lower-case ell.)  The  rest of  the argument list  (starting
         with the  argument flagged by "/l")  is optional. This switch
         may be used to handle routines with  variable-length argument
         lists.

/s       This argument is set in the function.

/r       This argument is referenced in the function.

/i       This argument is indeterminate.

Each "shell"  is a simple FORTRAN subprogram/program unit  that  takes
the same  arguments as the associated library subprogram/program  unit
and references or sets these arguments in a similar fashion.

The examples  below show the structure of some of the FORTRAN  library
shells found in unixlib.lbt:

    INTEGER FUNCTION SIGNAL (SIGNUM/r, PROC, FLAG/r)
    INTEGER SIGNUM, FLAG
    EXTERNAL PROC
    CALL PROC
    END

    REAL FUNCTION R_COPYSIGN (X/r, Y/s)
    REAL X,Y
    END

The following  example  tells FORTRAN-lint that  only  the  first  two
arguments in  the  argument list are required; the rest  of  them  are
optional.  Note that arguments CLASS1, CLASS2, CLASS3, and CLASS4  all
need to specify the "/l" switch.

    INTEGER FUNCTION STUDENT (NAME/r, CREDITS/r, CLASS1/rl, CLASS2/rl,
                                      CLASS3/rl, CLASS4/rl)
    CHARACTER*40 NAME
    INTEGER CREDITS
    INTEGER CLASS1, CLASS2, CLASS3, CLASS4
    END

----------------------------------------------------------------------

9.5 Miscellaneous Library Issues

9.5.1 Interaction with Cross Reference and Call Trees

Cross-reference tables and call trees automatically include referenced
library routines.  Cross-reference tables print  library  names  along
with routine  names. Call trees use curly braces ({}) to flag  library
routines.

9.5.2 File Format

".lbt" files  are revision-locked. FORTRAN-lint will print  a  warning
message if incompatible ".lbt" files are used.

Chapter 10
Database Files

10.1 Overview

FORTRAN-lint can be used to create database (or ".fdb") files for  use
in subsequent analysis operations.

A database  (or ".fdb") file is a binary file which contains  symbolic
information obtained from one or more FORTRAN source files.

Files with  the  extension  ".fdb" are  database  files  generated  by
FORTRAN-lint during  source  code  analysis.  ".fdb"  database   files
contain symbolic information for the modules processed.

".fdb" files  may be used to re-generate cross-reference tables,  call
trees, diagnostic messages, etc., without re-analysis of the  original
source code.

----------------------------------------------------------------------

10.2 Creating Database Files

To create  database  files,  use  the  "-B"  option  (under  UNIX)  or
/DATABASE (under VMS) as follows:

    flint -Bdbfile foo1.f foo2.f foo3.f ...                 under UNIX
or
    flint /DATABASE=dbfile foo1.for foo2.for foo3.for ...
                                                            under VMS

dbfile specifies the base name which should be used for the  database.
The filename extension ".fdb" will be added automatically.

If the specified database file already exists, it will be overwritten.

To suppress console error messages during database creation,  add  the
option switch "-Oall" (under UNIX) or /SUPPRESS=ALL (under VMS) to the
FORTRAN-lint command line.

----------------------------------------------------------------------

10.3 Using Database Files

To extract  information from an existing database file, use  a  normal
flint command with the database file as an argument.  For example:

    flint -t dbfile.fdb                                     under UNIX
or
    flint /TREE dbfile.fdb                                  under VMS

The command  line  should  not specify any  other  database  files  or
FORTRAN source files.

All call tree options are available when database files are processed.
Most of  the  cross-reference  options  are  available;  line  is   an
exception. "-Xline" and /XREF=line are ignored; flint  uses  the  line
value set when the database file was generated.

Additionally, if  "unreferenced parameters" or  "unused  common  block
members" are  not  selected when the database  file  is  created,  the
associated messages  will  not  be  provided  by  subsequent  database
queries.

".fdb" files should be regenerated whenever the associated source code
is modified.

Chapter 11
Xlint Introduction

Xlint is  a  Motif-based programming tool. It is designed  to  provide
FORTRAN developers with an interactive graphical user interface  which
can be used to browse FORTRAN source files.

Xlint operates  on  the  database  (or  ".fdb")  files  generated   by
FORTRAN-lint. With four windows displaying information,  Xlint  allows
the developer  to  step  through  potential  errors  and  to  see  the
relationships between  source  code,  call  tree  and   symbol   table
information, all on one screen.

Symbol cross  reference information can be automatically  brought  up,
showing all  code  references to any symbol in the  analyzed  program.
Each occurrence of a symbol can quickly be found in the  source  code;
at the same time, the appropriate node is highlighted in the displayed
call tree.

Chapter 12
Learning About Xlint

This chapter  will  cover the basics that users need  to  know  before
running Xlint and will help them understand the usage and function  of
the many options available within this product.

12.1 Screen Layout

The Xlint screen is made up of four windows and a control panel.

The four windows from top to bottom are Source, Lint, Tree, and  Cross
Reference. They are used to display specific information  relating  to
the current database being analyzed.  When information in any  of  the
windows exceeds the size of the window, a scroll bar  will  appear  on
the bottom  and/or right hand side.  Each window can  be  enlarged  or
reduced at the expense or benefit of the other windows.

The Control Panel bar between the Source and Lint windows  contains  a
text input field and three buttons.

Popup menus are supported by all four windows and can be called up  by
a click  of the right mouse button, with the pointer anywhere  in  the
appropriate window.  Options in the popup menus  can  be  selected  by
simply holding  down the right button, dragging  the  pointer  to  the
desired option,  and then releasing the button.  When  the  button  is
released, the option will be set and the menu will disappear.

On-screen help is available. A help menu can be called up by  a  click
of the  left mouse button on the help option at the top of  the  Xlint
screen.

(For figure 12.1, see printed version of manual.)

----------------------------------------------------------------------

12.2 File Menu

The File menu is used to select the database or source file.

A submenu with five options can be brought up by a click of  the  left
mouse button.

Load Database
              Used  to  load a pre-existing database. A database  must
              beloaded  before symbol information can be displayed  in
              the windows.

View File     Used  to  load an arbitrary file into the Source window.
              It  will stay loaded until an action from another window
              calls up a different source file.

Save File     Used  to  save any edits made to the file in the  Source
              window. Editing must be enabled first.

Enable Editing
              Allows the file in the Source window to be  modified and
              saved.  Changes are only saved when the Save  File  menu
              item  is  selected. When the Source  window  is  in  the
              editing   mode,  the  Disable  Editing  option  replaces
              Enable  Editing  in  the  submenu   and  disallows   any
              editing in the Source window.

Quit          Exits Xlint.

----------------------------------------------------------------------

12.3 Search Menu

The Search menu allows text searches on the Source window,  using  the
currently-highlighted text as the search string.

Previous      Searches backwards for the selected text.

Next          Searches forwards for the selected text.

Go To Line    Uses  the selected text as the line number and  goes  to
              that  line. For example, if the highlighted text is  the
              number  "27", then if line 27 exists, the program cursor
              moves to the 27th line.

----------------------------------------------------------------------

12.4 Build Menu

The Build menu is used to create or update a database (.fdb) file.

The status  field  on the control bar shows the  status  of  the  most
recent rebuild.

Configure     Used  to  select  the name of the database,  the  source
              files, and options used during source processing.

Rebuild       Runs  FORTRAN-lint with the configured options and files
              to regenerate the database file.

Kill Rebuild Process

              Stops the source processing; available only during a re-
              build.

Use Rebuilt Database

              Loads the database that was last rebuilt by the  Rebuild
              menu selection.  This has the same effect as loading the
              database from within the File menu.

View Build Output

              Pops up a window that shows the output from FORTRAN-lint
              during the rebuild process.  The FORTRAN-lint output can
              be used to determine why a "build" operation failed.

----------------------------------------------------------------------

12.5 Source Window

The source code currently being analyzed is displayed in this window.

Action in  other  windows will cause files to load  automatically  and
jump to  the  appropriate  point in  the  source.   A  lookup  can  be
performed on  highlighted items that can affect  the  Tree  and  Cross
Reference windows.

The popup  menu can be used to select the source related  to  what  is
currently highlighted in the other windows. With these options,  users
can step  through the cross reference entries one by one or  repeat  a
text search with a click of the mouse.

Previous Xref
              Goes  to the text referred by the cross reference  entry
              one  before the current highlight in the Cross Reference
              window.

Current Xref
              Goes  to the text referred by the cross reference  entry
              currently highlighted in the Cross Reference window.

Next Xref     Goes  to the text referred by the cross reference  entry
              one  after  the current highlight in the Cross Reference
              window.

Previous Text
              Goes  to  the previous occurrence of the text  currently
              highlighted in the Source window.

Next Text     Goes  to  the  next  occurrence of  the  text  currently
              highlighted in the Source window.

Lint          Goes  to the text referred by the lint message currently
              highlighted in the Lint window.

              Note:  If  the Lint window is currently in the "summary"
              mode,  the  cursor  in the Source  window  will  not  be
              affected.

Tree          Goes   to   the   function   or   subroutine   currently
              highlighted in the Tree window.

----------------------------------------------------------------------

12.6 Lint Window

The  current   FORTRAN-lint   analysis   messages   pre-generated   by
FORTRAN-lint are displayed in this window.

When a  database  is initially loaded, a summary of  the  FORTRAN-lint
source analysis  is  shown.  Double-clicking an item  in  the  summary
calls up  the  actual  instances of that message.   Double-clicking  a
message instance  causes lookups in the other  windows  specified  for
action in Lint's popup menu.

Summary       Shows a summary of FORTRAN-lint analysis output.

              Example:

              IMPLCT #125 7x: symbols were implicitly typed as *: *

              where  7x  means  that  there are 7  instances  of  such
              message.

All Messages  Shows   all   the  actual  message  instances   of   the
              FORTRAN-lint  source  analysis.  Each  message  includes
              the  line  number,  the subroutine it  belongs  to,  the
              message number, and the message itself.

              Example:

              demo.f(33)[PRINT] #125: symbols were implicitly typed as
              I*4: IUNIT

Action        The  Action  popup menu determines which  of  the  other
              windows  are  influenced by actions taken  in  the  Lint
              window.

              If  a  message  is  double-clicked in the  Lint  window,
              depending  on the selections in the Action  popup  menu,
              one  or  more of the other windows is changed to reflect
              the  new  selection.  The Tree  window  will  change  to
              reflect the routine where the message was reported.  The
              Cross  Reference  window will change to  reflect  symbol
              information  associated with the  message.  By  default,
              both Cross Reference and Tree are selected.

----------------------------------------------------------------------

12.7 Tree Window

This window  contains  a  graphical representation  of  the  program's
"call" structure, centered around a given routine.

Each node of the call tree represents a routine.  The selected routine
is placed in the center.  The routines to the left and right  are  the
predecessors and descendants of the selected routine, respectively.

Clicking a  node  will highlight it and make it  selectable  from  the
popup menus  of  the  other  windows.   Double-clicking  a  node  will
recenter the  tree  around  that node. Double-clicking  a  node  while
holding the Shift key (<Shift>double-click) will cause lookups in  the
other windows specified for action in the Tree's popup menu.

The popup menu in the Tree window allows the tree root to be set  from
the current routine in the Source, Lint, or Cross Reference window.

Selected Routine

              Uses the  currently  highlighted routine  name  from the
              Source window or the text input field.

Routine Containing Lint

              Redisplays  the Tree window with a tree centered  around
              the routine containing the current lint message.

Routine Containing Xref

              Redisplays  the Tree window with a tree centered  around
              the  routine  containing  the  current  Cross  Reference
              entry.

Action        Selects  the  affected windows when a shift double-click
              is  done on a tree routine.  By default, the Source  and
              Lint  windows  will  reflect  the  change  on  the  Tree
              window.

----------------------------------------------------------------------

12.8 Cross Reference Window

The Cross Reference window contains a cross-reference for the selected
symbol.

Symbols may  be selected by name and may contain wildcard  characters.
The cross reference entries are filtered by the settings in  the  Xref
Filter selection box in the Control Panel (see next section).

The folllowing wildcard characters are accepted:

    *  zero or more characters
    ?  any character

Double-clicking a  cross reference entry calls up  the  source  and/or
call tree related to that entry, depending on the action settings.

Options available in the popup menu are as follows.

Lookup Selected Symbol

              Looks  up the symbol currently highlighted in the source
              window.

Lookup Tree Routine

              Allows  users  to  look up the cross reference  messages
              related  to  the  routine currently highlighted  in  the
              Tree window.

Lint References

              Shows  cross-reference  information  regarding  the lint
              message highlighted in the Lint window.

Action        Determines  the affected windows when a double-click  is
              done on a cross-reference entry.

----------------------------------------------------------------------

12.9 Control Panel

The control  panel bar between the Source and Lint  windows  has  four
labels which  will perform various functions.  A description  of  each
option follows:

Select        Allows  the  user to type in a symbol in the field  next
              to the Select option for lookup.

              To  perform  the lookup, the user can either hit  return
              at the end of the text or click on the Lookup button.

Lookup        Uses  the  highlighted text from the  Source  window  to
              affect  the  windows selected for action by  the  Source
              window's popup menu.

              If  no  text is highlighted, the text specified  in  the
              Select  field  to  the left will be used.   If  text  is
              entered  into this Select field and <Return> is pressed,
              the   entered  text  is  used  regardless  of  what   is
              highlighted in the Source window.

Xref Filter   Calls  up a selection box to select the types of symbols
              to  show  in the Cross Reference window. Any  number  of
              qualifiers may be selected.

Tree          Brings  up  a  selection box to  set  the  "parent"  and
              "child" depths of the call tree to be displayed  in  the
              Tree window, as well as condensing multiple calls.

              Parent  depth  is the number of levels shown  upward  in
              the   call  stack  in  relation  to  the  selected  tree
              routine.  Child  depth is similar,  but  in  a  downward
              direction. The toggle for Condense mode causes  multiple
              calls  from  one routine to another to be shown  as  one
              link,  rather  than  duplicated.  Library  includes  the
              library  routines  defined in  ".lbt"  files.  Undefined
              shows  all  routines which are called,  whether  or  not
              they are defined in the current input files.

----------------------------------------------------------------------

12.10 Mouse Functions

The functions of the mouse are consistent with standard Motif usage.

Left button   Used  to  select menu options and buttons; can  also  be
              used  to  highlight or mark text in the  Source  window.
              Highlighting   is  accomplished  by  pointing   to   the
              beginning  of  the  text the user wishes  to  mark  and,
              while holding the left button down, dragging to the  end
              of the text and then releasing the left button.

Middle button
              Used  to  paste  highlighted text at the current  cursor
              location or text prompt. Pasting or inserting cannot  be
              done into the Source window.

Right button
              Used  to  call up the popup menus and select the options
              in these menus.

Chapter 13
Database Files and Xlint

13.1 Overview

As explained  in  chapter 10, database (or ".fdb")  files  are  binary
files which  contain  symbolic information for  one  or  more  FORTRAN
source files.

Xlint uses  the  information  stored in ".fdb"  files  to  browse  the
associated source files and/or analysis output.

Database files  may be created from the command line  (using  FORTRAN-
lint), or  they  may be generated inside Xlint. For  the  command-line
procedure,  see section 10.2.  Section 13.3  covers  the  Xlint proce-
dure.

Note:  This  chapter  assumes that the environment  variable  (or  VMS
logical) XLINTPATH  is set properly. If Xlint  is  being  run  from  a
directory other  than  the directory which contains  project  sources,
XLINTPATH should point to the directory which contains the sources.

----------------------------------------------------------------------

13.2 Loading Database Files

Before Xlint can be used, a database (".fdb") file must be loaded.  To
load a database file inside Xlint, proceed as follows:

1) Select the File menu from the options at the top of the screen.

2) Select Load Database from the File menu.  This will bring up a dir-
   ectory and file selection screen.

3) Select the  appropriate directory.  To select  the  desired  ".fdb"
   file,  double-click the file or click the file to  highlight it and
   then click OK.

The "lint" summary for the specified ".fdb" file should appear in  the
Lint window.

Alternatively, a database file may be specified on the  Xlint  command
line. For additional information, see section 15.3.

----------------------------------------------------------------------

13.3 Rebuilding Database Files under Xlint

The Build  menu on top of the Source window can be used to rebuild  an
existing database (or to create a new one).  The "build" procedure  is
as follows:

1) Select Configure  on  the  Build  menu.  Enter  the  database  name
   (without the  ".fdb" extension) in the  Database field.  Enter  the
   associated source file names in the  Source Files field.   Set  the
   other options as desired.

   (See figure 13.1)

2) Select Rebuild on the Build menu.  The Status field in the  Control
   Panel may be used to monitor "build" status.

3) When the Status field shows  "Rebuilding completed",  the new data-
   base may  be loaded.  (To do this,  select  Use Rebuilt Database on
   the Build menu.)

Users may  also  see the FORTRAN-lint output by using the  View  Build
Output on the Build menu. If the "build" failed, View Build Output can
be used  to  determine  the cause.  (For additional  information,  see
section 12.4.)

(For figure 13.1, see printed version of manual.)

Chapter 14
Xlint: Getting Started

14.1 Configuration Setup

For installation instructions, see appendix H or I.

In particular, note that a "resource file" should be   copied  to  the
appropriate directory. (For additional information on resource  files,
see the installation instructions and chapter 16.)

Also note  that  three UNIX environment variables  (or  VMS  logicals)
should be set for each Xlint user:

    XLINTHOME      Path for the directory  which  contains  the  Xlint
                   support files.

    XLINTHOST      Network name (or node name) for  the system running
                   the Xlint license manager.

    XLINTPATH      Path for  the directory  which contains  the user's
                   FORTRAN source files.

----------------------------------------------------------------------

14.2 Running Xlint

Before Xlint can be used, the user must create a project database  (or
".fdb" file). For additional information, see chapters 10 and 13.

To run the browser, enter the command xlint:

    xlint

The Xlint menu will appear, along with four empty windows.

Next, use  Load Database on the File sub-menu to load the  appropriate
database. (For additional information, see section 13.2.)

After the ".fdb" file is loaded, source-analysis output will appear in
the Lint window.

To display all lint messages, scroll through the lint message summary.
To display  all  occurrences  of  a given  message,  double-click  the
message. The Lint window will be updated appropriately.

For detailed  information  on  a given  occurrence,  double-click  the
occurrence. Xlint will display related source code, call tree  output,
and cross-reference information.

For on-screen help, click the left mouse button on the Help  field  in
the upper right corner of the Xlint screen.

To load another database, select Load Database on the File menu.

To exit Xlint, select Quit on the File menu.

----------------------------------------------------------------------

14.3 Sample Sessions

The FORTRAN-lint  /  Xlint  package includes  sample  FORTRAN  77  and
Fortran 90 project files.

The sample FORTRAN 77 files include demo.for (an F77 source file)  and
demo.fdb (the  associated database file).  demo.for  may  be  used  to
rebuild demo.fdb; for additional information, see section 13.2.

Similarly, the  sample  Fortran 90 files include  demo90.for  (an  F90
source  file)   and  demo90.fdb  (the  associated    database   file).
demo90.for may be used to rebuild demo90.fdb.

Session 1:

1) Under the FORTRAN-lint / Xlint installation directory, run:

   xlint demo.fdb

   This will bring up the Xlint menu and analysis output for demo.fdb.

2) To find  all  symbols starting with "I", enter "I*" in  the  Select
   field on the Control Panel and press <Return>.

   This will  bring up  cross reference information for all  variables
   beginning with the letter "I".

3) To bring  up information related to a specific symbol, double-click
   the appropriate line in the  Cross Reference window.  For  example,
   to display  information related to  the variable  "INUIT",  double-
   click the following line:

   INUIT,I*4 variable,in demo.f(43)[PRINTIT] is Set,Actual arg

   The Source window should display demo.for with  line 43 (containing
   INUIT) highlighted.  The Tree window should display a tree centered
   around the PRINTIT routine.

   (See figure 14.3)

4) Double-click another cross reference entry.  For example:

   I, I*4 variable, in demo.f(6)[PROCDAT] is Ref

   Note the changes in the Source and Tree windows.

Session 2:

1) Run:

   xlint

   This will bring up the Xlint menu with four empty windows.

2) Click on  File in the upper left corner of the screen. Select  Load
   Database to bring up the Load Database dialog box.  Use the Direct-
   ories and Filter options to  go to the FORTRAN-lint / Xlint instal-
   lation directory.  Double-click  demo.fdb  to  select it or single-
   click to highlight demo.fdb and press OK.

   Xlint should display  analysis output for "demo.for"  in  the  Lint
   window.

3) To display  all  the  occurrences of  a  particular  lint  message,
   double-click the message with the left mouse button.

   For example, double-click the following message:

   IMPLCT #125 7x: symbols were implicitly typed as *: *

   to display all occurrences of IMPLCT #125.  Note that 7x means that
   there are 7 instances of this message.

4) After all instances are  displayed,  double-clicking one of the in-
   stances will display information related to the instance.

   For example, double-click the following instance:

   demo.f(33)[PRINT] #125: symbols were implicitly typed as I*4: IUNIT

   The Source window should display  source code with the highlight on
   IUNIT in line 33.  The Tree window should display  a call tree cen-
   tered around the PRINT routine. In the  Cross Reference window, the
   following line should be high-lighted:

   IUNIT, I*4 variable, in demo.f(33)[PRINT] is Dummy arg

5) Double-click a  lint instance  that is not  currently  highlighted.
   For example:

   demo.f(49)[DIPSTAT] #125: symbols were implicitly typed as R*4:
   PRINT ###

   The Source window now redisplays the source file with the highlight
   on "PRINT"  in  line 49.  The  Tree window shows  a  tree  centered
   around DIPSTAT.  The Cross Reference window shows the following in-
   formation:

   PRINT, subroutine, in demo.f(49)[DIPSTAT] is called

6) To see the lint summary again, use the right mouse button to select
   Summary in the Lint window.

(For figure 14.1, see printed version of manual.)

Chapter 15
More About Xlint

15.1 Resizing Windows

Any of the Source, Lint, Tree, or Cross Reference windows in the Xlint
screen can  be  enlarged or reduced at the expense or benefit  of  the
other windows.   To resize a window, press the left  or  middle  mouse
button on  the small box between two windows, and drag it to  the  new
boundary line users desire.  Then release the button.

When the  information in any of the windows exceeds the  size  of  the
window, a scroll bar will appear on the bottom and/or right hand  side
of the window.

----------------------------------------------------------------------

15.2 Window Interaction

Window interaction is controlled by the Action sub-menu in each of the
Lint, Tree, and Cross Reference windows.  The settings in these Action
menus determine how changes in that particular window will  affect the
other windows.  Depending on the action settings, all the  windows may
be updated to reflect information relative to the changed window.

To view  or  change the action settings for a particular window,  move
the mouse  cursor  to any location within that window  and  press  the
right mouse  button.   The  popup menu for that  window  will  now  be
displayed.  Move  the mouse to the Action option and press  the  right
button again. The action options will now be displayed.  To toggle  an
option on or off, simply point to that option box, and press the right
mouse button.

The default settings for window interaction are set so that an  action
in any  window  will  affect the others.  For  example,  if  the  user
double-clicks a cross reference entry, the corresponding  source  code
and the tree information will appear in the Source and Tree windows.

----------------------------------------------------------------------

15.3 Command-Line Options

Xlint supports the standard "X" command-line options (i.e., -bg,  -fg,
-display, etc...).  For additional information on these  options,  see
the system vendor's "X" documentation.

Additionally, a database (".fdb") file may be specified on the command
line. For example:

    xlint foo.fdb

To specify an alternate resource file (e.g., bar.dat), use  an  option
of the following form:

    xlint -rf bar.dat

This option  loads  both  the  default resource  file  and  the  user-
specified file. Options in the user-specified file take precedence.

----------------------------------------------------------------------

15.4 Advanced Example

The following session will use "demo.fdb" as the example.

Sample session 3:

1) In the FORTRAN-lint / Xlint installation directory, run:

   xlint demo.fdb

   This will  bring up  an Xlint screen with analysis output  for  the
   "demo" project in the Lint window.

2) Click the  left mouse button to bring up the File menu. Select  the
   View File  command.  Select  "demo.for"  (or "demo.f").  The Source
   window should display FORTRAN source code for the "demo" project.

3) Symbols can  be  located  throughout  the  loaded  source  file  by
   highlighting the  text of a  symbol in the Source window,  clicking
   the right  mouse button to bring up the popup menu,  and  selecting
   Next Text.  For instance, highlight "PRINT" in line 9 in the Source
   window.

   To search for the next "PRINT" in "demo.for", click the right mouse
   button anywhere  in the  Source window to call up the  popup  menu.
   Select Next Text.

   The next "PRINT" highlighted in the Source window is in the SETTYPE
   subroutine.

4) To see  all  occurrences of "PRINT", use the right mouse button  in
   the Cross Reference window to call up  the submenu.  Choose  Lookup
   Selected Symbol.

5) To make  a cross reference entry available as a selection  for  the
   Source and/or Tree windows,  highlight the entry using a  click  of
   the left mouse button.  For example:

   PRINT, subroutine, in demo.f(33)[PRINT] is defined

6) To see  the tree related to this highlighted cross reference entry,
   use the right mouse button to select the Routine Containing Xref in
   the Tree's popup menu.

   The Tree window  shows a  call tree centered around the  PRINT rou-
   tine.

7) To see  where in the  source code  the  highlighted  "PRINT" in the
   Cross Reference  window refers to,  use the right mouse  button  to
   select "Current Xref" in the Source window.

   The highlight in the Source window now moves to the symbol  "PRINT"
   in line 33.

   Note that  the combined result of  steps 5-7 can be done by  simply
   double-clicking the cross reference entry in step 5.

    (See figure 15.4)

8) <Shift> double-click the SETTYPE routine in the  Tree  window.  The
   Source window  moves the highlight to  "SETTYPE" in  line  27.  The
   Cross Reference  window shows all the  cross reference  information
   about SETTYPE.

Users can change the setting for any window at any time.  For example,
the depth  of  the  parent or child tree in the  Tree  window  can  be
changed by using the Tree Option in the Control Panel.  The tree  will
be redisplayed with the new depth.

(For figure 15.1, see printed version of manual.)

Chapter 16
Resource Files

16.1 Overview

A resource  file is an ASCII text file that contains the configuration
information needed for Xlint to run. Xlint resource files  conform  to
the standard X Window resource file conventions.

The default  resource file is named XLint (under  UNIX)  or  XLINT.DAT
(under VMS). It is strongly suggested that the original copy  of  this
resource file  not  be altered.  If users need to modify  the  default
configuration, they should create modified copies.

Users may load modified versions of the resource file in various ways;
for additional information, see section 16.2.

----------------------------------------------------------------------

16.2 XLint and XLINT.DAT

The Xlint  resource  file  is named XLint (under  UNIX)  or  XLINT.DAT
(under VMS).

A copy  of this file should be placed in the home directory  for  each
Xlint user.  By  default,  Xlint uses this  copy.  Users  may  specify
alternate  versions  on  the  Xlint  command  line;   for   additional
information, see section 15.3.

Alternatively, under  UNIX, users may set   the  standard  environment
variable XAPPLRESDIR or use the standard app-defaults directory.

Under VMS,  two logicals DECW$SYSTEM_DEFAULTS and DECW$USER_  DEFAULTS
are used. To install a copy of XLINT.DAT for system-wide use, place it
in the directory specified by DECW$SYSTEM_DEFAULTS. To install a  copy
of XLINT.DAT for use by an individual user, place it in the  directory
specified by DECW$USER_DEFAULTS for that user.

If Xlint finds copies of the resource file in two or more places,  all
of the  specified  options are used, but options  in  individual  user
resource files  take  precedence over options in system-wide  resource
files.

If a resource file is specified on the Xlint command line, options  in
the specified  file take precedence.  For additional information,  see
section 15.3.

                              Appendices


Appendix A
Installation Under UNIX

A.1 Pre-installation

Starting with  revision  2.81,  FORTRAN-lint  incorporates  a  license
manager that  requires a daemon to be loaded before the  product  will
run. The daemon is called iptlm for versions below 2.90 and iptlmd for
versions 2.90 and above.

The daemon  can  be  started by non-privileged users.   However,  root
privileges are  required if the product is to be installed  in  system
directories.

Note: The  FORTRAN-lint  "installation  directory"  mentioned  in  the
following sections  is  the directory that contains  the  FORTRAN-lint
support files (for example, flint.err and flint.cfg).

----------------------------------------------------------------------

A.2 Installation Procedure

1. Log in as system manager.

2. Create a temporary directory. Go to the new directory.

3. Insert the  tape (or other media) provided and enter a  command  of
   the form:

        tar xvf /dev/device_name

   where device_name is the  UNIX device name for the media used (1/4"
   cartridge tapes, 3 1/2" floppy diskettes, etc.).

4. Step 3 will load a number of files, including:

        demo.f          demo   source  files
        demo.inc        demo   include file
        demo90.f90      demo90 source  files
        demo90.inc      demo90 include file
        flint.1         man page
        flint.cfg       flint default configuration file
        flint.err       error message text
        flint.hls       flint help file
        unixlib.lsh     standard UNIX library description text
        unixlib.lbt     standard UNIX library file
        vmslib.lsh      standard VMS  library description text
        vmslib.lbt      standard VMS  library file

    The basic executables include:

        demo            demo   script
        demo90          demo90 script
        flint           FORTRAN-lint executable
        flpatch         executable patch program
        install_flint   installation script for FORTRAN-lint
        iptlma          license administration program
        iptlmd          license manager daemon
        iptlmr          license usage report generator

   Multiple versions of flint may be loaded.  For example,  flint_sun4
   is the  executable for  SUN 4 systems.  The  installation procedure
   will select the correct version and rename it appropriately.

   If the  Xlint option was purchased,  the following additional files
   will be loaded:

        demo.fdb        database generated from demo.f
        demo90.fdb      database generated from demo90.f90
        xlint           Xlint executable
        XLint           Xlint resource file

5. After the  tape  is  loaded,  run install_flint and  follow the in-
   structions on the screen.

6. Modify the  user configuration  for each  FORTRAN-lint user as fol-
   lows:

   (a) Set the environment variable FLINTHOST to the host name for the
       server where the license manager is  installed.  (To obtain the
       host name, execute the UNIX command hostname on the server.)

   (b) Set  the environment variable  FLINTHOME to a full path for the
       directory which contains the FORTRAN-lint support files (flint.
       err, etc.).

       For example,  if the  user is  using  csh,  use commands of the
       form:

       setenv FLINTHOST hostname
       setenv FLINTHOME installation_directory

       If the user is using sh, use commands of the form:

       FLINTHOST=hostname; export FLINTHOST
       FLINTHOME=installation_directory; export FLINTHOME

7. Add $FLINTHOME to the user's search list.

   For csh users, use a command of the form:

        set path=($path $FLINTHOME)

   For sh  users, use a command of the form:

        PATH=$FLINTHOME:$PATH

   To make the changes  permanent,  add the new commands to the appro-
   priate login scripts.  For example, for csh users, modify ".cshrc".

8. Optional:  The  FORTRAN-lint  package includes  a  utility  program
   named flpatch that can be used to patch the  FORTRAN-lint installa-
   tion directory and server host name directly into the flint execut-
   able.

   To patch the executable, use commands of the form:

        flpatch flint host <hostname>
        flpatch flint home <installation_directory>

   For additional information on FLPATCH, see section A.4.

9. Users are now ready to activate FORTRAN-lint.

----------------------------------------------------------------------

A.3 Activation Procedure

Every FORTRAN-lint  license must be assigned  a  unique  authorization
number (or "activation key")  by  Cleanscape  before the  package will
run.

1. To proceed, execute the following command:

        flint activate

   The software will provide  users with a  server code,  and  it will
   prompt them to call  Cleanscape for activation.  If users  have not
   already  received  an  activation key,  they will  need  to contact
   Cleanscape.  Cleanscape will then generate an  activation key based
   on the server code.

2. Once the activation key is acquired, execute the following command:

        flint activate

   again, and enter the activation code when prompted.

   Note:  A file  called  02.lic  or  07.lic  will be  created  in the
   FORTRAN-lint  installation directory.  This file stores information
   related to the activation key.

3. The activation  procedure  in step 2 also  creates  a  script  file
   called startup  under the installation directory.  This  file  will
   allow users to  load the daemon from the command line.  Users  will
   need to run startup every time they reboot their system or kill the
   license manager.

   After the key file has been  successfully  installed in the instal-
   lation directory, FORTRAN-lint will ask users if they want to put a
   command  to  start the  license daemon  in  the  system  boot  file
   (/etc/rc.local).

   If users answer "yes", the license manager daemon  will be  started
   automatically  whenever  the  system is  booted.  To  complete  the
   installation procedure,  in this case, simply  reboot  the  system.
   However, users must have sufficient privileges to do so.

   If users  answer "no", they will need to start the daemon  manually
   if they reboot the system or kill the daemon.

4. If users have elected not to have the boot file modified, they need
   to run:

        $FLINTHOME/startup

   at the next prompt to start the daemon.

   After being started,  the daemon requires a three minute period for
   initialization.

5. When three minutes are up, enter the command:

        flint

   FORTRAN-lint should display a "help" screen.

6. FORTRAN-lint is now ready for use.

   Note:  At this point, Xlint may be installed. For additional infor-
   mation, see appendix H.

----------------------------------------------------------------------

A.4 Patching FORTRAN-lint

Some of the default parameters in FORTRAN-lint can be modified  within
the FORTRAN-lint executable.  This is accomplished using the "flpatch"
program.  This program takes the following command-line arguments:

        1st:  name of the executable (required)
        2nd:  parameter to patch
        3rd:  desired value

If the  second or  third  arguments are  not given,  the user  will be
prompted for them.

The patchable parameters in FORTRAN-lint are:

    Name           Description              Default value
    ------------   ----------------------   --------------------------
    home           installation directory   /usr/local/flint
    host           license server host      ?
    preprocessor   path of C preprocessor   /usr/lib/cpp
    bootfile       system boot file         /etc/rc.local

(a) The home  parameter  sets  the default for  the directory  of  the
    FORTRAN-lint support files.

    home can be overridden by the environment variable FLINTHOME.

(b) The  host parameter is used by the  license manager  to locate the
    machine on which the license manager daemon is running. This helps
    improve performance since the  application does not have to search
    the entire network for the location of the daemon.  This parameter
    is set during the installation procedure and need not change,  ex-
    cept in the event of  changing the  hostname of  the current mach-
    ine.

    host can be overridden by the environment variable FLINTHOST.

    For the daemon hostname, there are two special values:

    (1) a ? causes a system-wide search for the daemon
    (2) a ! causes an error to be reported unless FLINTHOST is set

(c) The preprocessor parameter allows  FORTRAN-lint to pass the source
    code through a preprocessor, usually cpp, before analyzing it. The
    preprocessor must take the same arguments as cpp.

(d) The  bootfile parameter sets the name of the  boot file, which can
    optionally be modified during the activation procedure to automat-
    ically start the license daemon when rebooting the system.

Appendix B
Installation Under VMS

B.1 Pre-installation

Starting with  revision  2.82,  FORTRAN-lint  incorporates  a  license
manager that  requires  a detached process to  be  loaded  before  the
product will run. The daemon is called iptlm for versions below  2.90,
and iptlmd for versions 2.90 and above.

Installation can  be  done  by non-privileged  users.   However,  root
privileges are  required if the product is to be installed  in  system
directories.

Note: The  FORTRAN-lint  "installation  directory"  mentioned  in  the
following sections  is  the directory that contains  the  FORTRAN-lint
support files (for example, flint.err and flint.cfg).

----------------------------------------------------------------------

B.2 Installation Procedure

1. Log in as system manager.

2. Create an installation directory. Go to the new directory.

3. Load the tape (or other media) provided and execute commands of the
   following form:

        MOUNT /FOR      device_name
        BACKUP /LOG     device_name:FLINT []
        DISMOUNT        device_name

   where device_name is the VMS device name for the media used  (TK-50
   cartridge tape, 1600 bpi mag tape, etc.).

4. Step 3 will load a number of files, including:

        DEMO.FOR        demo source files
        DEMO.INC        demo include file
        DEMO90.F90      demo90 source files
        DEMO90.INC      demo90 include file
        FLINT.CFG       FLINT default configuration file
        FLINT.ERR       error message text
        FLINT.HLP       FLINT help file, use with VMS HELP
        FLINT.HLS       FLINT help file, command line options
        VMSLIB.LSH      standard VMS library description text
        VMSLIB.LBT      standard VMS library file
        UNIXLIB.LSH     standard UNIX library description text
        UNIXLIB.LBT     standard UNIX library file

   The basic executables include:

        DEMO.COM        demo script
        DEMO90.COM      demo90 script
        IPTLMA.EXE      license administration program
        IPTLMD.EXE      license manager detached process
        IPTLMR.EXE      license usage report generator
        FLINT.EXE       FORTRAN-lint executable
        FLPATCH.EXE     executable patch program

   If the Xlint option was purchased,  the following additional  files
   will be loaded:

        DEMO.FDB        database file for demo.for
        DEMO90.FDB      database file for demo90.f90
        XLINT.DAT       Xlint resource file
        XLINT.EXE       Xlint executable file

5. Modify the  user configuration  for each  FORTRAN-lint user as fol-
   lows:

   (a) If  the  FORTRAN-lint  license manager is installed on a DECNET
       server, set the logical FLINTHOST to the node name for the ser-
       ver.  Otherwise, set FLINTHOST to "NO_DECNET".

       Note:  To  obtain  the  node name,  execute  the command  "show
       logical SYS$NODE"  on the server.  Discard any  "colon" charac-
       ters.

       define FLINTHOST "node_name"

   (b) Set  the logical FLINTHOME to a full path for the  FORTRAN-lint
       installation directory.

       define FLINTHOME $disk:[installation_directory]

   (c) Define  the  symbol  FLINT  as a  foreign  command  to  execute
       FLINT.EXE (located in the installation directory):

       FLINT :== $FLINTHOME:FLINT.EXE

   (d) Define  the  symbol  FLPATCH as a  foreign command  to  execute
       FLPATCH.EXE (located in the installation directory):

       FLPATCH :== $FLINTHOME:FLPATCH.EXE

   To make the changes  permanent,  add the new commands to the appro-
   priate LOGIN.COM files.

   Example:

        DEFINE FLINTHOST "GUMBY"
        DEFINE FLINTHOME $disk3:[USR.PETER.FLINT]
        FLINT   :== $FLINTHOME:FLINT.EXE
        FLPATCH :== $FLINTHOME:FLPATCH.EXE

6. Optional: The FORTRAN-lint package includes a utility program named
   FLPATCH.EXE that can be used  to patch the host directory path  and
   server node name directly into the FLINT.EXE executable.

   To patch the executable, use commands of the form:

        FLPATCH  FLINT.EXE  HOME  $disk:[directory_path]
        FLPATCH  FLINT.EXE  HOST  "node_name"

   disk:[directory_path] should specify the  FORTRAN-lint installation
   directory.  node_name  should  be the  appropriate  node  name  (or
   "NO_DECNET"), as explained in step 5.

   For additional information on FLPATCH, see section B.4.

7. Users are now ready to activate FORTRAN-lint.

----------------------------------------------------------------------

B.3 Activation Procedure

Every FORTRAN-lint  license must be assigned  a  unique  authorization
number (or "activation key")  by  Cleanscape  before  the package will
run.

1. To proceed, execute the following command:

        flint /license=activate

   The software will provide users with a  server code,  and  it  will
   prompt them to call  Cleanscape  for activation.  If users have not
   already  received an  activation key,  they will  need  to  contact
   Cleanscape.  Cleanscape will then generate an  activation key based
   on the server code.

2. After the activation code is obtained, execute the command:

        flint /license=activate

   again, and enter the activation code when prompted.

   Note:  A file  called  02.lic  or  07.lic  will be  created  in the
   FORTRAN-lint  installation directory.  This file stores information
   related to the activation key.

3. The activation procedure in step 2 also creates a script file call-
   ed STARTUP.COM in the installation directory.  This file will allow
   users  to load  the  daemon  from  the command file.  To  start the
   license daemon, execute the following command:

        @FLINTHOME:startup

   Users will need to run @FLINTHOME:STARTUP if they reboot the system
   or kill  the detached process.  Alternatively,  add this command to
   the appropriate system startup script.

4. The  startup script in  step 3  requires a  three minute period for
   initialization.  When the three minutes are up, enter the command:

        flint

   FORTRAN-lint should display a "help" screen.

5. FORTRAN-lint is now ready for use.

   Note:  At this point, Xlint may be installed. For additional infor=
   mation, see appendix I.

----------------------------------------------------------------------

B.4 Patching FORTRAN-lint

Some of the default parameters in FORTRAN-lint can be modified  within
the FORTRAN-lint  executable. This is accomplished using  the  FLPATCH
program. This program takes three command-line arguments:

        1st:  name of the executable (required)
        2nd:  parameter to patch
        3rd:  desired value

If the  second  or  third arguments are not given, the  user  will  be
prompted for them.

The patchable parameters in FORTRAN-lint are:

    Name   Description                  Default value
    ----   ----------------------       ------------------------------
    home   installation directory       "!"
    host   license server host          "NO_DECNET"

To patch FORTRAN-lint, use a command of the following form:

        FLPATCH flint.exe home $disk2:[appl.FLINT]

(a) The home  parameter  sets the default for the  application support
    directory.

    home can be overridden by the system logical FLINTHOME.

    The default  value "!" for the home parameter indicates  that  the
    installation directory  is  not specified.  Unless  the  FLINTHOME
    logical is  specified, an error message will be  issued  reporting
    that the product is not yet installed.

(b) The host parameter is  used by the  license manager  to locate the
    machine on which the license manager detached process is running.

    If the  license manager is not installed on a DECNET server,  this
    parameter should be set to "NO_DECNET".

    The host  parameter  can  be overridden  by  setting  the  logical
    FLINTHOST.

    For the detached process hostname, there are two special values:

    1) a ? causes a system-wide search for the detached process.
    2) a ! causes an error to be reported unless FLINTHOST is set.

Appendix C
License Manager

Starting with  version  2.81,  FORTRAN-lint  incorporates  a   license
manager that  requires a daemon to be loaded before the  product  will
run.  This  daemon is called iptlm for versions below 2.90 and  iptlmd
for versions 2.90 and above.

C.1 License Manager Commands

C.1.1 User Commands

1) By default,  FORTRAN-lint will queue a job when there are  no  more
   licenses available. The "-q" option under UNIX or "/quit" under VMS
   when added  to the "flint" command line will  force the application
   to quit when there are no available licenses.

        flint -q [options] files                            under UNIX
   or
        flint /quit [options] files                         under VMS

2) FORTRAN-lint needs  to  identify the  node  on  which  the  license
   manager was loaded.  To accomplish this,  it uses the UNIX environ-
   ment variable (or VMS logical) FLINTHOST.

   To define FLINTHOST under UNIX, use commands of the form:

        setenv  FLINTHOST  hostname                      for csh users
   or
        FLINTHOST=hostname                               for sh  users
        export FLINTHOST

   hostname should be the  network name of the user's  license  server
   host.  (To  obtain the  host name under UNIX, execute  the  command
   hostname on the server.)

   To define FLINTHOST under VMS, use a command of the form:

        define FLINTHOST "nodename"

   If the  license  server  is installed  on a DECNET  host,  nodename
   should be the node name of the host.  Otherwise, nodename should be
   "NO_DECNET".

   (To obtain  the  node name under VMS,  execute  the  command  "show
   logical SYS$NODE" on the server.  Discard any "colon" characters.)

3) Another environment variable (or logical) FLINTHOME tells  FORTRAN-
   lint where  the  installation directory is located.  This  variable
   can be used to override the directory value patched into the execu-
   table during installation.

   To define FLINTHOME under UNIX, use commands of the form:

        setenv FLINTHOME directory                       for csh users
   or
        FLINTHOME=directory                              for sh  users
        export FLINTHOME

   directory should be a full path.

   To define FLINTHOME under VMS, use a command of the form:

        define FLINTHOME $disk:[installation_directory]

4) Under VMS, the qualifier /system may be added to the commands in 2)
   and 3) to place the definitions  of FLINTHOST and FLINTHOME in  the
   system logical table.  Note that users need to log in  with  SYSNAM
   privileges to add definitions to the system logical table.

C.1.2 Administrative Commands

Under UNIX       Under VMS                 Description
--------------   -----------------------   ---------------------------
flint activate   flint /license=activate   Enter an activation key
flint users      flint /license=users      Show licenses in use
flint servers    not supported             List active license daemons
flint report     flint /license=report     Cumulative usage report
flint daily      flint /license=daily      Daily      usage report
flint kill       flint /license=kill       Kill license daemon (*)

(*) Requires superuser privileges.

C.1.3 License Manager Options (at daemon startup only)

1) iptlmd -e  dir:dir:dir...    Key file directories  (required)

   Directories must be full pathnames separated by colons.

2) iptlmd -r file               Reserve file

   This file  allows  licenses to be  reserved for specific  users  or
   machines.

   The format of this file is:

        product:group:client1,...,clientN:K

   Each group,  with the client members,  has K  licenses for FORTRAN-
   lint.

   Under UNIX, the group name is unrelated to normal UNIX system group
   names.  It is only the name you wish to call this group of users.

   A client is either a  user name or a  host name  preceded by the at
   sign ("@").

   Example:

        flint:hackers:wendy,jeff,sara,fred:3
        flint:lab:@gumby:1

   Here Fred is a user name, and @gumby is a host name.

   Comment lines begin with "#".

3) iptlmd -l logfile            Log file (needed for usage reports;
                                recommended)

4) iptlmd -m size               Maximum log file size. This limits the
                                size of the log  file. When this  size
                                is reached,  the log file is copied to
                                file.old and is  cleared.  The size is
                                given as a floating number followed by
                                either "m" for megabytes  or  "k"  for
                                kilobytes.

                                Examples:   -m 100k
                                            -m 0.5m

5) iptlmd -v #                  Log file verbosity.  The default value
                                is 3.  Lower numbers produce less out-
                                put and  higher numbers  produce  more
                                output.

6) iptlmd -f                    Run in foreground. The license manager
                                normally "backgrounds" itself  and ex-
                                its.  This  option  keeps  it  in  the
                                foreground.

Appendix D
Sample Output: Fortran 90

For sample Fortran 90-related output, see printed version of manual.

Appendix E
Sample Output: FORTRAN 77

For sample FORTRAN 77-related output, see printed version of manual.

Appendix F
Diagnostic Messages

F.1 Format

FORTRAN-lint's diagnostic messages are defined in a  text  file  named
flint.err.  This file contains one message per line in  the  following
format:

        ### XX Text

where   ###   is a three-digit message number
        XX    is a two-letter  diagnostic code
        Text  is the message text

Example:

        157 SE no matching "(".

If the  message number  is less than  three digits long,  it is right-
justified in a three-column field.

The first letter of the  diagnostic code specifies a basic error cate-
gory as follows:

        Letter    Type of problem
        ------    -------------------------
          S       Syntax
          U       Data usage
          I       Call interface
          P       Portability
          M       Implicit typing
          O       Overflow (limit exceeded)

The second letter of the diagnostic code specifies a severity level as
follows:

        Letter    Type of problem
        ------    -------------------------
          E       Error
          W       Warning
          F       Hint (FYI)

Lines that start with an "I" are not diagnostic messages.  These lines
contain information used during portability checking.

Appendix G
Performance

G.1 Disk Space

G.1.1 Program Size

FORTRAN-lint requires approximately 2 MB of disk space for the package
itself.  Additional space is required during analysis (see below).

G.1.2 Temporary Files

FORTRAN-lint generates temporary files during processing.  These files
are automatically deleted upon program termination, including aborts.

Under UNIX, the library function tempnam() is used to obtain names for
the temporary files.  On most systems, the environment variable TMPDIR
may be used to control the directory used by  tempnam();  if TMPDIR is
not set, tempnam() normally uses /usr/tmp or /tmp.  For additional in-
formation, see the UNIX "man" page for tempnam().

Under VMS,  temporary files are placed in the directory  specified  by
SYS$SCRATCH.

Generally speaking,  temporary files will require  2 MB of  disk space
(or above)  for  every  10,000 lines of source  code.  Cross-reference
tables and call trees will increase the amount of disk space required.

Appendix H
Xlint Installation Under UNIX

H.1 Pre-installation

The Xlint installation procedure assumes that FORTRAN-lint has already
been installed and activated. If FORTRAN-lint has not been  installed,
see the instructions in appendix A.

Note: The  FORTRAN-lint / Xlint "installation directory" mentioned  in
the following sections is the directory that contains the FORTRAN-lint
/ Xlint support files (for example, flint.err and flint.cfg).

----------------------------------------------------------------------

H.2 Installation Procedure

1. Log in as system manager.

2. Go to the FORTRAN-lint / Xlint installation directory.  The follow-
   ing Xlint support files should already be present:

        xlint       # Xlint executable
        XLint       # Xlint resource file
        demo.fdb    # demo database generated from demo.f

3. Modify the user configuration for each Xlint user as follows:

   (a) Set the environment variable  XLINTHOST to the host name of the
       system where the  Xlint license manager  will be  running.  (To
       obtain the host name,  execute the UNIX command hostname on the
       server.)

   (b) Set the environment variable  XLINTPATH to a  full path for the
       directory which contains the user's own FORTRAN source files.

   (c) Set the environment variable  XLINTHOME to a  full path for the
       Xlint installation directory.

       For example,  if  the user  is using csh,  use commands  of the
       form:

           setenv XLINTHOST nodename
           setenv XLINTPATH source_path
           setenv XLINTHOME installation_directory

       If the user is using sh, use commands of the form:

           XLINTHOST=nodename; export XLINTHOST
           XLINTPATH=source_path; export XLINTPATH
           XLINTHOME=installation_directory; export XLINTHOME

   Note:  There should no white space on  either side of the  "equals"
   sign.

   For other shells, substitute the appropriate commands.

4. Add $XLINTHOME to the user's search path.  This step can be omitted
   if  $FLINTHOME points  to the  same  directory  as  $XLINTHOME  and
   $FLINTHOME has been already been added to the search path.

   For csh users, use the command:

        set path=($path $XLINTHOME)

   For sh users, use the command:

        PATH=$XLINTHOME:$PATH

   To make the changes permanent, add the new command to the appropri-
   ate login scripts.  For example, for csh users, modify ".cshrc".

5. Optional:  The  Xlint package  includes a utility  program  flpatch
   that can be used to patch the Xlint installation directory and ser-
   ver name directly into the xlint executable.

   To patch the executable, use commands of the form:

        flpatch xlint home <directory>
        flpatch xlint host <hostname>

   Replace  directory  with  the  Xlint  installation  directory,  and
   hostname  with the host name for the system that  will  be  running
   the Xlint license manager.

   Note:   The  install_flint shell script runs flpatch automatically.
   flpatch therefore should be needed only if one of  these parameters
   changes.

6. Copy  the Xlint resource file (XLint) to the  appropriate directory
   or directories.

   A copy of this file should be placed in the home directory for each
   Xlint user.  By default,  Xlint uses  this copy.  Users may specify
   alternate versions on the Xlint command line; for additional infor-
   mation, see section 15.3.

   Alternatively,  users  may set the  standard  environment  variable
   XAPPLRESDIR or use the standard  app-defaults directory.  For addi-
   tional information, see the operating system vendor's "X" document-
   ation.

7. Users are now ready to activate Xlint.

----------------------------------------------------------------------

H.3 Activation Procedure

Every Xlint  license  must be assigned a unique  authorization  number
(activation key) before the package will run.

1. To proceed, execute the following command:

        xlint activate

   The  software will provide users with a server code,  and  it  will
   prompt them to call Cleanscape for activation.  Cleanscape will use
   the server code to  generate a unique  authorization number for the
   software.

2. After an activation key is obtained, execute the command:

        xlint activate

   again, and enter the activation key when prompted.

3. If the license manager process iptlmd has not already been started,
   users will need to execute the command:

        startup

   from the  installation  directory.  Note that a single  iptlmd pro-
   cess will allow both FORTRAN-lint and Xlint to run.

   Users  will need to run startup every time they  reboot the  system
   or  kill the  license manager. To avoid this step,  add the startup
   command to the appropriate system boot script.

4. The license manager daemon requires a three minute period after be-
   ing started  for  initialization.  When the  three minutes are  up,
   execute the command:

        xlint

   Xlint is now ready for use.

Note:  For license manager options, see appendix C.

Appendix I
Xlint Installation Under VMS

I.1 Pre-installation

The Xlint installation procedure assumes that FORTRAN-lint has already
been installed and activated. If FORTRAN-lint has not been  installed,
see the instructions in appendix B.

Note: The  FORTRAN-lint / Xlint "installation directory" mentioned  in
the following sections is the directory that contains the FORTRAN-lint
/ Xlint support files (for example, flint.err and flint.cfg).

----------------------------------------------------------------------

I.2 Installation Procedure

1. Log in as system manager.

2. Go to the FORTRAN-lint / Xlint installation directory.  The follow-
   ing Xlint support files should already be present:

        XLINT.EXE     ! Xlint executable file
        XLINT.DAT     ! Xlint resource file
        DEMO.FDB      ! demo database file for demo.for

3. Modify the user configuration for each Xlint user as follows:

   (a) If the Xlint  license manager is installed on a  DECNET server,
       set the logical  XLINTHOST  to the  node name  for  the server.
       Otherwise, set XLINTHOST to "NO_DECNET".

       Note:  To obtain the node name, execute the command "show logi-
       cal SYS$NODE" on the server.  Discard any "colon" characters.

   (b) Set  the logical  XLINTPATH  to  a  full path for the directory
       which contains the user's own FORTRAN source files.

   (c) Set  the logical  XLINTHOME  to  a  full  path  for  the  Xlint
       installation directory.

   (d) Set  the  logical XLINT to a full  pathname  for the executable
       file XLINT.EXE in the installation directory.

   Add the new commands to the appropriate login.com files.

   Example:

        define XLINTHOST "nodename"
        define XLINTPATH [source_path]
        define XLINTHOME [installation_directory]
        XLINT :== $XLINTHOME:XLINT.EXE

4. Optional: The FORTRAN-lint package includes a utility program named
   FLPATCH.EXE that can be used  to patch  the Xlint installation dir-
   ectory and  server node name  directly  into  the  Xlint executable
   file.

   To patch Xlint, use commands of the form:

        FLPATCH XLINT.EXE HOME disk:[directory_path]
        FLPATCH XLINT.EXE HOST nodename

   disk:[directory_path] should specify the Xlint installation direct-
   ory. nodename should be the appropriate node name (or "NO_DECNET"),
   as explained in step 3.

5. Copy the resource file (XLINT.DAT) to the appropriate  directory or
   directories.

   Two logicals are used:

   DECW$SYSTEM_DEFAULT  -- System directory (same for all users)
   DECW$USER_ DEFAULTS  -- Per-user directory

   To install a copy of XLINT.DAT for system-wide use, place it in the
   directory  specified by DECW$SYSTEM_DEFAULTS.  To install a copy of
   XLINT.DAT for use by an individual user,  place it in the directory
   specified by DECW$USER_DEFAULTS for that user.

   Note that users may an alternate resource file on the Xlint command
   line; for additional information, see section 15.3.

6. Users are now ready to activate Xlint.

----------------------------------------------------------------------

I.3 Activation Procedure

Every Xlint  license  must be assigned a unique  authorization  number
(activation key) before the package will run.

1. To proceed, execute the following command:

        FLINT /LICENSE=ACTIVATE

   The   software will provide users  with a server code,  and it will
   prompt them to call Cleanscape for activation.  Cleanscape will use
   the server code to  generate a unique  authorization number for the
   software.

2. After an activation key is obtained, execute the command:

        FLINT /LICENSE=ACTIVATE

   again, and enter the activation code when prompted.

3. If the license manager (iptlmd) hasn't already been started,  users
   will need to execute the command:

        @FLINTHOME:STARTUP.COM

   This  will  start  the  license daemon.  Note that a  single iptlmd
   process will allow both FORTRAN-lint and Xlint to run.

   Users  will  need to run  @FLINTHOME:STARTUP again if  they  reboot
   the system or kill the detached process.  Alternatively, simply add
   the STARTUP command to the appropriate system startup script.

4. The  detached process requires a  three minute period  after  being
   started for initialization.  When the three minutes are up, execute
   the command:

        XLINT

   Xlint is now ready for use.

Note:  For license manager options, see appendix C.
