
1 FTNCHEK
       ftnchek - Fortran program checker

2 Introduction
      ftnchek  (short  for Fortran checker) is designed to detect cer-
 tain errors in a Fortran program that a compiler  usually  does  not.
 ftnchek  is not primarily intended to detect syntax errors.  Its pur-
 pose is to assist the user  in  finding  semantic  errors.   Semantic
 errors  are  legal  in  the  Fortran language but are wasteful or may
 cause incorrect operation.  For example, variables  which  are  never
 used  may  indicate some omission in the program; uninitialized vari-
 ables contain garbage which may cause incorrect results to be  calcu-
 lated; and variables which are not declared may not have the intended
 type.  ftnchek is intended to assist users in the debugging of  their
 Fortran  program.   It  is  not  intended to catch all syntax errors.
 This is the function of the compiler.  Prior to  using  ftnchek,  the
 user should verify that the program compiles correctly.

 For more detailed information, consult the printed documentation.

2 Invoking_Ftnchek
       ftnchek is invoked through a command of the form:

        $ ftnchek [/option /option ...] filename [filename ...]
      The brackets indicate something which is optional.  The brackets
 themselves are not actually typed.   Here  options  are  command-line
 switches  or settings, which control the operation of the program and
 the amount of information that will be printed out.  If no option  is
 specified,  the  default action is to print error messages, warnings,
 and informational messages, but not the  program  listing  or  symbol
 tables.

      Each option begins with the '/' character.  (ftnchek also allows
 the '-' character to be used.)
      ftnchek options fall into two categories:  switches,  which  are
 either  true  or  false, and settings, which have a numeric or string
 value.  The name of a switch is prefixed by 'no' to turn it off: e.g.
 /nopure  would turn off the warnings about impure functions. The 'no'
 prefix can also be used with numeric settings, having the  effect  of
 turning  off the corresponding warnings.  Only the first 3 characters
 of an option name (not counting the '/') need be provided.   A  colon
 may  be used in place of an equals sign for option value assignments;
 however, we show only the equals sign form below.
      When more than one option is used, they should be separated by a
 blank  space,  except on systems such as VMS where options begin with
 slash ( / ).  No blank spaces may be placed around the equals sign  (
 =  ) in a setting.  ftnchek "?"  will produce a command summary list-
 ing all options and settings.

2 Files
      When giving a name of an input file, the extension is  optional.
 If  no extension is given, ftnchek will first look for a project file
 with extension .prj, and will use that if it exists.   If  not,  then
 ftnchek  will look for a Fortran source file with the extension .for.
 More than one file name can be given to ftnchek, and it will  process
 the modules in all files as if they were in a single file.

      Wildcards  are  allowed in the specification of filenames on the
 command line.
      If no filename is given, ftnchek will read input from the  stan-
 dard input.


2 Options
      ftnchek  options  fall  into two categories: switches, which are
 either true or false, and settings, which have a  numeric  or  string
 value.   The  name  of a switch or numeric setting can be preceded by
 'no' to turn it off: e.g. /nousage would turn off the warnings  about
 variable  usage.   Only the first 3 characters of an option name (not
 counting the '/') need be provided.   Most  options  are  positional:
 each  option remains in effect from the point it is encountered until
 it is overridden by a later change.


3 /arguments=num
       Controls warnings about mismatches  between  actual  and  dummy
 subprogram  arguments.   (An actual argument is an argument passed to
 the subprogram by  the  caller;  a  dummy  argument  is  an  argument
 received by the subprogram.)

     The meanings of the setting values are as follows:
    0: turn off all such warnings.
    1: warn only about different number of arguments.
    2: warn only about mismatch of data type of arguments and of func-
        tion itself.
    3: all warnings.

     Default = 3.

     This setting is provided mainly to  suppress  warnings  when  you
 wish  to use ftnchek for some other purpose than checking for errors,
 for example when you only want to print the call tree.  It  does  not
 apply  to  checking  invocations  of intrinsic functions or statement
 functions.

     See also: /array, /library, /usage.


3 /array=num
       Controls the degree of strictness in checking agreement between
 actual  and dummy subprogram arguments that are arrays.  The warnings
 controlled by this setting are for constructions that  might  legiti-
 mately be used by a knowledgeable programmer, but that often indicate
 programming errors.

     The meanings of the setting values are as follows:
    0: only warn about cases that are  seldom  intentional  (see  note
        below).
    1:  warn if the arguments differ in their number of dimensions, or
        if the actual argument is an array  element  while  the  dummy
        argument is a whole array.
    2: warn if both arguments are arrays, but they differ in number of
        elements.
    3: give both types of warnings.

     Default = 3.

     Note: A warning is always given regardless of this setting if the
 actual  argument  is  an  array  while the dummy argument is a scalar
 variable, or if the actual argument is a scalar variable  or  expres-
 sion  while the dummy argument is an array.  No warning is ever given
 if the actual argument is an array element while the  dummy  argument
 is  a scalar variable.  Variable-dimensioned arrays and arrays dimen-
 sioned with 1 or asterisk match any number of array elements.   There
 is  no check of whether multi-dimensional arrays agree in the size of
 each dimension separately.

     See also: /arguments, /library, /usage.


3 /backslash
       Handle UNIX-style backslash escapes in character strings.   The
 escape  sequence  following the backslash will be evaluated according
 to the ANSI standard for strings in C: up to three digits signify  an
 octal  value, an x signifies the start of a hexadecimal constant, any
 of the letters a b f n r t signify special  control  codes,  and  any
 other  character  (including newline) signifies the character itself.
 When this option is in effect, a non-standard warning will  be  given
 if the /f77 flag is set.  Default = no.

     If this option is turned off (the default), the backslash will be
 treated like any other normal character, but a warning  about  porta-
 bility will be generated if the /portability flag is set.  Because of
 the fact that some compilers treat the  backslash  in  a  nonstandard
 way,  it  is  possible  for  standard-conforming  programs to be non-
 portable if they use the backslash character in strings.

     Since ftnchek does not do much with the interpreted string, it is
 seldom  necessary to use this option.  It is needed in order to avoid
 spurious warnings only if (a) the program being  checked  uses  back-
 slash  to  embed  an  apostrophe or quote mark in a string instead of
 using the standard mechanism of doubling the delimiter; (b) the back-
 slash is used to escape the end-of-line in order to continue a string
 across multiple source lines; or (c) a PARAMETER definition  uses  an
 intrinsic string function such as LEN with such a string as argument,
 and that value is later used to define array dimensions, etc.


3 /calltree
       Causes ftnchek to print out the call structure of the  complete
 program in the form of a tree.  The tree is printed out starting from
 the main program, which is listed on the first line at the left  mar-
 gin.   Then  on  the following lines, each routine called by the main
 program is listed, indented a few spaces,  followed  by  the  subtree
 starting at that routine.  Default = no.

     If  a  routine is called by more than one other routine, its call
 subtree is printed only the first  time  it  is  encountered.   Later
 calls give only the routine name and the notice ``(see above)''.

     Note  that  the  call tree will be incomplete if any of the input
 files are project files containing more than  one  module  that  were
 created in /library mode.  See the discussion of project files below.

     Technical points: Each list of routines called by a given routine
 is  printed  in  alphabetical  order.   If multiple main programs are
 found, the call tree of each is printed separately.  If no main  pro-
 gram  is  found, a report to that effect is printed out, and the call
 trees of any top-level non-library routines are printed.   This  flag
 only  controls  the printing of the call tree: ftnchek constructs the
 call tree in any case because it is used to determine  which  library
 modules  will  be  cross-checked.  See the discussion of the /library
 flag.

     See also: /crossref, /library, /reference, /sort, /symtab.


3 /columns=num
       Set maximum statement length to num columns.  (Beyond  this  is
 ignored.)   This  setting  is  provided to allow checking of programs
 which may violate the Fortran standard limit of 72  columns  for  the
 length  of  a  statement.   According to the standard, all characters
 past column 72 are ignored.  If this setting is used  when  the  /f77
 option  is  in effect, a warning will be given for any lines in which
 characters past column 72 are processed.  Max is 132.  Default =  72.


3 /common=num
        This  setting  varies  the  strictness  of  checking of COMMON
 blocks.

     The different levels are:
    0: no checking.
    1: in each declaration of a given COMMON block, corresponding mem-
        ory locations (words or bytes) must agree in data type.
    2:  also  warn if different declarations of the same block are not
        equal in total length.
    3: corresponding variables in each declaration  of  a  block  must
        agree  in  data  type  and  (if  arrays) in size and number of
        dimensions.

     Default = 3.

     The Fortran 77 Standard requires each named common block, but not
 blank  common,  to  be the same length in all modules of the program.
 Level 3 provides an extra degree of checking to  support  a  frequent
 programming practice.

     See also: /library, /usage, /volatile.


3 /crossref
        Specifies that a cross-reference table be printed.  This table
 lists each subprogram followed by a list of the  routines  that  call
 it.  Also prints a table listing each COMMON block followed by a list
 of the routines that access it.  Default = no.

     The cross-reference listing omits library modules that are not in
 the  call  tree  of the main program.  The list is alphabetized.  The
 routines listed as using a COMMON block are those in which some vari-
 ables  in  the  block  are  accessed,  not simply those routines that
 declare the block.  (To find out what routines declare a COMMON block
 but do not use it, see the /usage flag.)

     See also: /calltree, /reference, /sort, /symtab.


3 /declare
        If  this  flag  is  set, all identifiers whose datatype is not
 declared in each module will be listed.   This  flag  is  useful  for
 helping  to  find  misspelled  variable names, etc.  The same listing
 will be given if the module  contains  an  IMPLICIT  NONE  statement.
 Default = no.

     See also: /sixchar, /usage.


3 /division
        This  switch is provided to help users spot potential division
 by zero problems.  If this switch is selected, every division  except
 by  a  constant  will  be  flagged.   (It is assumed that the user is
 intelligent enough not to divide by a  constant  which  is  equal  to
 zero!)  Default = no.

     See also: /portability, /truncation.


3 /extern
       Causes ftnchek to report whether any subprograms invoked by the
 program are never defined, or are multiply defined.   Ordinarily,  if
 ftnchek  is  being  run  on a complete program, each subprogram other
 than the intrinsic functions should be defined  once  and  only  once
 somewhere.   Turn  off this switch if you just want to check a subset
 of files which form part of a larger complete program,  or  to  check
 all  at  once a number of unrelated files which might each contain an
 unnamed main program.  Subprogram arguments will still be checked for
 correctness.  Default = yes.

     See also: /library.


3 /f77
        Use  this  flag to catch language extensions which violate the
 Fortran 77 Standard.  Such extensions may cause your program  not  to
 be  portable.   Examples  include  the use of underscores in variable
 names; variable names longer than  six  characters;  statement  lines
 longer  than 72 characters; and nonstandard statements such as the DO
 ... ENDDO structure.  ftnchek does not report on the use of lowercase
 letters.  Default = no.

     See also: /portability, /pretty, /wordsize.


3 /help
        Prints  a  list  of  all the command-line options with a short
 description of each along with its default value.   This  command  is
 identical  in  function  to the ``?''  argument, and is provided as a
 convenience for those systems in which the question mark has  special
 meaning to the command interpreter.  Default = no.

     The  help  listing also prints the version number and patch level
 of ftnchek and a copyright notice.

     Note: the ``default'' values printed in square  brackets  in  the
 help  listing  are,  strictly speaking, not the built-in defaults but
 the current values after any environment options and any command-line
 options preceding the /help option have been processed.


3 /hollerith
        Hollerith  constants (other than within FORMAT specifications)
 are a source of possible portability problems, so when the /portabil-
 ity  flag is set, warnings about them will be produced.  If your pro-
 gram uses many Hollerith constants, these warnings can obscure  other
 more  serious  warnings.   So you can set this flag to ``no'' to sup-
 press the warnings about Holleriths.  This flag has no effect  unless
 the  /portability  flag  (which  is  off  by  default)  is turned on.
 Default = yes.

     See also: /portability.


3 /include=path
       Specifies a directory to be searched  for  files  specified  by
 INCLUDE  statements.  Unlike other command-line options, this setting
 is cumulative; that is, if it is given more than once on the  command
 line, all the directories so specified are placed on a list that will
 be searched in the same order as they are given.  The order in  which
 ftnchek searches for a file to be included is: the current directory;
 the directory specified by environment  variable  FTNCHEK_INCLUDE  if
 any; the directories specified by any /include options; the directory
 specified by environment variable INCLUDE; and finally in a  standard
 systemwide directory (/usr/include for UNIX, SYS$LIBRARY for VMS, and
 \include for MSDOS).


3 /library
       This switch is used when a number of subprograms are  contained
 in  a  file,  but  not  all  of  them  are  used  by the application.
 Normally, ftnchek warns you if any subprograms are defined but  never
 used.  This switch will suppress these warnings.  Default = no.

     This switch also controls which subprogram calls and COMMON block
 declarations are checked.  If a file is read with the  /library  flag
 in  effect, the subprogram calls and COMMON declarations contained in
 a routine in that file will be checked only if that routine is in the
 main  program's call tree.  On the other hand, if the /library switch
 is turned off, then ftnchek checks the  calls  of  every  routine  by
 every  other routine, regardless of whether those routines could ever
 actually be invoked at run time, and likewise all COMMON block decla-
 rations are compared for agreement.

     (If  there  is  no main program anywhere in the set of files that
 ftnchek has read, so that there is no call tree,  then  ftnchek  will
 look  for  any  non-library routines that are not called by any other
 routine, and use these as substitutes for the main  program  in  con-
 structing  the call tree and deciding what to check.  If no such top-
 level non-library routines are found, then all inter-module calls and
 all COMMON declarations will be checked.)

     See also: /arguments, /calltree, /common, /extern.


3 /list
        Specifies  that  a  listing  of  the  Fortran program is to be
 printed out with line numbers.  If  ftnchek  detects  an  error,  the
 error  message follows the program line with a caret ( ^ ) specifying
 the location of the error.   If  no  source  listing  was  requested,
 ftnchek will still print out any line containing an error, to aid the
 user in determining where the error occurred.  Default = no.

     See also: /symtab, /verbose.


3 /makedcls=num
       Prepare a neatly-formatted file of declarations  of  variables,
 common  blocks,  and  namelist  lists,  for possible merging into the
 source code.  The declarations are stored in a file of the same  name
 as  the  source  code, but with the extension changed to .dcl.  If no
 declarations are written to the file, it is deleted to reduce clutter
 from empty files.

     If input comes from standard input, instead of a named file, then
 declarations are written to standard output.

     Variables are declared in alphabetical order within each declara-
 tion  class  and type, with integer variables first, because of their
 later possible use in array dimensions.

     PARAMETER statements are an exception to the  alphabetical  order
 rule,  because  the Fortran 77 Standard requires that the expressions
 defining parameter values refer only to constants and already-defined
 parameter  names.  This forces the original source file order of such
 statements to be preserved in the declaration files.

     Explicit declaration of all variables is considered  good  modern
 programming practice.  By using compiler options to reject undeclared
 variables, misspelled variable names (or names extending past  column
 72)  can  be  caught  at  compile  time.   Explicit declarations also
 greatly facilitate changing  floating-point  precision  with  filters
 such   as  dtoq(1L),  dtos(1L),  fd2s(1L),  fs2d(1L),  qtod(1L),  and
 stod(1L).  These programs are capable of changing types  of  explicit
 floating-point type declarations, intrinsic functions, and constants,
 but because they do not carry out rigorous  lexical  and  grammatical
 analysis  of  the  Fortran  source code, they cannot provide modified
 type declarations for undeclared variables.

     The setting values are given by the sum of selected option values
 from the following list:
    0: Do not write a declaration file.
    1: Write a declaration file.
    2:  Normally,  all variables are included in the declaration file.
        With this option, include  only  undeclared  variables.   This
        setting  is  useful  if you want to check for undeclared vari-
        ables, since Fortran source files with all variables  properly
        declared  will  not  result in a .dcl file.  With this option,
        common blocks and namelist lists will not be included  in  the
        declaration  file,  since by their nature they cannot be unde-
        clared.
    4: The declarations are normally prettyprinted to line  up  neatly
        in  common  columns, as in the declaration files output by the
        Extended PFORT Verifier, pfort(1L).  This option value selects
        instead compact output, without column alignment.
    8:  Causes  continuation  lines to be used where permissible.  The
        default is to begin a new  declaration  on  each  line.   This
        option  is appropriate to use with the option for compact out-
        put.
    16: Output Fortran keywords in lowercase, instead of  the  default
        uppercase.
    32:  Output  variables  and constants in lowercase, instead of the
        default  uppercase.    Character  string  constants  are   not
        affected by this option.
    64:  Omit  declarations  of internal integer variables produced by
        the SFTRAN3 preprocessor, xsf3(1L), as part of the translation
        of  structured  Fortran statements to ordinary Fortran.  These
        variables have six-character names of the form NPRddd, NXdddd,
        N2dddd,  and N3dddd, where d is a decimal digit.  Because they
        are invisible in the SFTRAN3 source code, and will  change  if
        the  SFTRAN3  code  is  modified, such variables should not be
        explicitly declared.  Instead, they  should  just  assume  the
        default  Fortran INTEGER data type based on their initial let-
        ter, N.
    128: Use an asterisk as the comment character; the default is oth-
        erwise 'C'.
    256: Use 'c' instead of 'C' or '*' as the comment character.

     If  any  non-zero  value is specified, then declaration output is
 selected, even if the value 1 was not included in the sum.

     The declaration files contain distinctive comments that mark  the
 start  and  end  of declarations for each program unit, to facilitate
 using text editor macros for merging the declarations back  into  the
 source code.


3 /novice
       This flag is intended to provide more helpful output for begin-
 ners.  It has two effects:
    (a) provides an extra message to the effect that a  function  that
        is  used  but not defined anywhere might be an array which the
        user forgot to declare in a  DIMENSION  statement  (since  the
        syntax of an array reference is the same as that of a function
        reference).
    (b) modifies the form of the error messages and warnings.  If  the
        flag is turned off by /nonovice, these messages are printed in
        a style more resembling UNIX lint.

     Default = yes.

     In versions of ftnchek prior to 2.6, this option  could  take  on
 various  numerical values, as a way of controlling various classes of
 warnings.  These warnings are now controlled  individually  by  their
 own flags.  Novice level 1 is now handled by the /array flag; level 2
 has been eliminated; level 3 is equivalent now to setting /novice  to
 yes; level 4 is handled by the /pure flag.


3 /output=filename
        This  setting  is provided for convenience on systems which do
 not allow easy redirection of output from programs.  When  this  set-
 ting  is  given, the output which normally appears on the screen will
 be sent instead to the named file.  Note, however,  that  operational
 errors of ftnchek itself (e.g. out of space or cannot open file) will
 still be sent to the screen.   The  extension  for  the  filename  is
 optional,  and  if  no extension is given, the extension .lis will be
 used.


3 /portability
       ftnchek will  give  warnings  for  a  variety  of  non-portable
 usages.   Examples  include  the  use  of  tabs except in comments or
 inside strings, the use of Hollerith constants, and the equivalencing
 of  variables  of different data types.  This option does not produce
 warnings for supported extensions to the Fortran 77  Standard,  which
 may  also  cause  portability problems.  To catch those, use the /f77
 option.  Default = no.

     See also: /backslash, /f77, /hollerith, /pretty, /wordsize.


3 /pretty
       Controls certain messages related  to  the  appearance  of  the
 source  code.  These warn about things that might be deceptive to the
 reader.  Default = yes.

     The warnings controlled by this flag include such things as  com-
 ments  that are interspersed among the continuation lines of a state-
 ment, lack of space between a keyword and a following variable  name,
 and statement lines containing characters past column 72.

     See also: /f77, /portability.


3 /project
        ftnchek  will create a project file from each source file that
 is input while this flag is in effect.   The  project  file  will  be
 given  the  same name as the input file, but with the extension .f or
 .for replaced by .prj.  (If input is from standard input, the project
 file is named ftnchek.prj.)  Default = no.

     A  project file contains a summary of information from the source
 file, for use in checking agreement among FUNCTION,  SUBROUTINE,  and
 COMMON  usages in other files.  It allows incremental checking, which
 saves time whenever you have a large set of files  containing  shared
 subroutines,  most  of which seldom change.  You can run ftnchek once
 on each file with the /project flag set, creating the project  files.
 Usually  you  would also set the /library and /noextern flags at this
 time, to suppress messages relating to consistency with other  files.
 Only error messages pertaining to each file by itself will be printed
 at this time.  Thereafter, run ftnchek without these flags on all the
 project  files  together,  to  check  consistency among the different
 files.  All messages internal to the individual  files  will  now  be
 omitted.  Only when a file is altered will a new project file need to
 be made for it.

     Naturally, when the /project flag is set, ftnchek will  not  read
 project files as input.

     Project files contain only information needed for checking agree-
 ment between files.  This means that a project file is of no  use  if
 all modules of the complete program are contained in a single file.

     A  more detailed discussion is given in the section on Using Pro-
 ject Files.


3 /pure
       Assume functions are ``pure'', i.e., they will  not  have  side
 effects  by modifying their arguments or variables in a COMMON block.
 When this flag is in effect, ftnchek will base its  determination  of
 set  and  used  status of the actual arguments on the assumption that
 arguments passed to a function are not altered.  It will also issue a
 warning  if a function is found to modify any of its arguments or any
 COMMON variables.  Default = yes.

     When this flag is turned off, actual arguments  passed  to  func-
 tions will be handled the same way as actual arguments passed to sub-
 routines.  This means that ftnchek will assume that arguments may  be
 modified  by  the functions.  No warnings will be given if a function
 is found to have side effects.  Because stricter checking is possible
 if  functions  are  assumed to be pure, you should turn this flag off
 only if your program actually uses functions with side effects.


3 /reference
       Specifies that a who-calls-who table be  printed.   This  table
 lists  each  subprogram  followed by a list of the routines it calls.
 Default = no.

     The reference list omits routines called by unused  library  mod-
 ules.   Thus  it  contains  the same information as for the /calltree
 flag, namely the hierarchy of subprogram calls, but printed in a dif-
 ferent format.  This prints out a breadth-first traversal of the call
 tree whereas /calltree prints out a depth-first traversal.   If  both
 /calltree  and /reference flags are given, only the reference form of
 the table will be produced.

     See also: /calltree, /crossref, /library, /sort, /symtab.


3 /resource
       Prints the amount of resources used by  ftnchek  in  processing
 the  program.   This  listing may be useful in analyzing the size and
 complexity of a program.  It can also help in choosing  larger  sizes
 for ftnchek's internal tables if they are too small to analyze a par-
 ticular program.  Default = no.

     In this listing, the term ``chunk  size''  is  the  size  of  the
 blocks of memory allocated to store the item in question, in units of
 the size of one item, not necessarily in bytes.  When  the  initially
 allocated  space  is filled up, more memory is allocated in chunks of
 this size.  The following is an explanation of the items printed:
    Source lines processed: Total number of lines of code, with  sepa-
        rate  totals  for  statement lines and comment lines.  Comment
        lines include lines with 'C' or '*' in column  1  as  well  as
        blank  lines  and  lines  containing  only  an inline comment.
        Statement lines are all other lines, including lines that have
        an inline comment following some code.  Continuation lines are
        counted as separate lines.  Lines in include files are counted
        each time the file is included.
    Total  executable statements: Number of statements in the program,
        other than specification,  data,  statement-function,  FORMAT,
        ENTRY, and END statements.
    Total  number  of  modules:  A  module is any external subprogram,
        including the main program, subroutines, functions, and  block
        data  units.   This  count  is  of  modules defined within the
        source, not modules referenced.  Statement functions  are  not
        included.   A  subprogram  with  multiple entry points is only
        counted once.
    Max identifier name chars: Number of characters used  for  storing
        identifier names.  An identifier is a variable, subprogram, or
        common block name.  Local names are those of  local  variables
        in  a subprogram, whereas global names refer to subprogram and
        common block names, as well as dummy argument names and common
        variable names.  Actual argument text (up to 15 characters for
        each argument) is also included  here.   The  space  used  for
        local  names  is  recovered at the end of each module, whereas
        the global space grows until the whole  program  is  analyzed.
        Unfortunately, this figure may include some common block names
        and arguments stored more than once, although a  heuristic  is
        used that will avoid duplicates in many cases.
    Max  token  text  chars: A token is the smallest syntactic unit of
        the FORTRAN language above the level of individual characters.
        For  instance a token can be a variable name, a numerical con-
        stant, a quoted  text  string,  or  a  punctuation  character.
        Token  text  is stored while a module is being processed.  For
        technical reasons, single-character tokens are not included in
        this  total.   Items  that  are  not represented in the symbol
        table may be duplicated.  The space for token text  is  recov-
        ered  at the end of each module, so this figure represents the
        maximum for any one module.
    Max local symbols: This is the largest number of  entries  in  the
        local symbol table for any module.  Local symbol table entries
        include all variables  and  parameters,  common  block  names,
        statement  functions, external subprograms and intrinsic func-
        tions referenced by the module.   Literal  constants  are  not
        stored in the local symbol table.
    Max  global  symbols:  This is the number of entries in the global
        symbol table at the end of processing.   Global  symbol  table
        entries  include  external  subprogram and common block names.
        Intrinsic functions and statement functions are not  included.
    Max  number  of  tokenlists:  A token list is a sequence of tokens
        representing the actual or dummy argument list  of  a  subpro-
        gram,  or the list of variables in a common block or namelist.
        Therefore this number represents the largest  sum  of  COMMON,
        CALL,  NAMELIST  and ENTRY statements and function invocations
        for any one module.  The space is recovered at the end of each
        module.
    Max token list/tree space: This is the largest number of tokens in
        all the token lists and token trees  of  any  one  module.   A
        token  tree  is  formed  when  analyzing  an  expression: each
        operand is a leaf of the  tree,  and  the  operators  are  the
        nodes.  Therefore this number is a measure of the maximum com-
        plexity of an individual module.  For instance a  module  with
        many  long  arithmetic  expressions  will  have a high number.
        Note that unlike token text described  above,  the  number  of
        tokens  is  independent of the length of the variable names or
        literal constants in the expressions.
    Number of subprogram invocations: This is the sum over all modules
        of  the  number  of  CALL  statements and function invocations
        (except intrinsic functions and statement functions).
    Number of common block decls: This is the sum over all modules  of
        the number of common block declarations.  That is, each decla-
        ration of a block in a different module is counted separately.
        (The  standard  allows multiple declarations of a block within
        the same module; these are counted  as  only  one  declaration
        since they are equivalent to a single long declaration.)
    Number of array dim & param ptrs: This is the sum over all modules
        of the number of array dimension and parameter definition text
        strings  saved for use by the /makedcls option.  The length of
        the text strings is not counted.  Each dimension of a multidi-
        mensional array is counted separately.

     These  numbers  are obviously not the same when project files are
 used in place of the original source  code.   Even  the  numbers  for
 global entities may be different, since some redundant information is
 eliminated in project files.


3 /sixchar
       One of the goals of the ftnchek program is  to  help  users  to
 write  portable  Fortran programs.  One potential source of nonporta-
 bility is the use of variable names that are longer than six  charac-
 ters.   Some compilers just ignore the extra characters.  This behav-
 ior could potentially lead to two different variables  being  consid-
 ered  as  the  same.   For  instance, variables named AVERAGECOST and
 AVERAGEPRICE are the same in the first six characters.  If  you  wish
 to catch such possible conflicts, use this flag.  Default = no.

     Use  the  /f77 flag if you want to list all variables longer than
 six characters, not just those pairs that are the same in  the  first
 six.

     See also: /f77, /portability.


3 /sort
       Specifies that a sorted list of all modules used in the program
 be printed.  This list is in ``prerequisite'' order, i.e. each module
 is  printed  only  after all the modules from which it is called have
 been printed.  This is also called a ``topological sort'' of the call
 tree.  Each module is listed only once.  Routines that are not in the
 call tree of the main program are omitted.  If there are  any  cycles
 in the call graph (illegal in standard Fortran) they will be detected
 and diagnosed.  Default = no.

     See also: /calltree, /crossref, /reference, /symtab.


3 /symtab
       A symbol table will be printed out for each module, listing all
 identifiers  mentioned  in  the module.  This table gives the name of
 each variable, its datatype, and the number of dimensions for arrays.
 An  asterisk  (*)  indicates  that  the  variable has been implicitly
 typed, rather than being named in an explicit type declaration state-
 ment.   The  table  also lists all subprograms invoked by the module,
 all COMMON blocks declared, etc.  Default = no.

     See also: /calltree, /crossref, /list, /reference, /sort.


3 /tab
       Accept DEC-style tab-formatted source.  A line  beginning  with
 an  initial  tab  will  be treated as a new statement line unless the
 character after the tab is a nonzero  digit,  in  which  case  it  is
 treated  as  a  continuation  line.  The next column after the tab or
 continuation mark is taken as column 7.  A warning will be  given  in
 the  case  where  the  line  is a continuation, if /f77 is in effect.
 Default = no.


3 /truncation
       Warn about possible truncation (or roundoff) errors.   Most  of
 these  are  related to integer arithmetic.  The warnings enabled when
 this flag is in effect are:
    (a) use of the result of integer  division  where  a  real  result
        seems  intended  (namely as an exponent, or if the quotient is
        later converted to real);
    (b) division in an  integer  constant  expression  that  yields  a
        result of zero;
    (c)  exponentiation  of  an  integer  by a negative integer (which
        yields zero unless the base integer is 1 in magnitude);
    (d) use of a non-integer array subscript or DO index;
    (e) conversion of any real type to integer,  or  conversion  of  a
        complex value to real or integer;
    (f) conversion of a double precision value to single precision, or
        vice-versa (promotion).  This applies both to real  types  and
        to complex types.

     Default = yes.

     Note:  warnings  about truncating type conversions are given only
 when the conversion is done automatically,  e.g.   by  an  assignment
 statement.   If  intrinsic  functions such as INT are used to perform
 the conversion, no warning is given.  Promotions of real  types  from
 single to double precision are included here because such conversions
 imply a possible loss of accuracy that is similar to the  correspond-
 ing demotions.

     See also: /portability, /wordsize.


3 /usage=num
        Warn  about  unused  or  possible  uninitialized variables and
 unused common blocks.

     The meanings of the setting values are as follows:
    0: no warnings.
    1: warn if variables are (or may be) used before they are set.
    2: warn if variables are declared or set but never used.
    3: give both types of warnings.

     Default = 3.

     Sometimes ftnchek makes a mistake about these warnings.   Usually
 it  errs on the side of giving a warning where no problem exists, but
 in rare cases it may fail to warn where the problem does exist.   See
 the section on Bugs for examples.  If variables are equivalenced, the
 rule used by ftnchek is that a reference to any variable implies  the
 same  reference  to all variables it is equivalenced to.  For arrays,
 the rule is that a reference to any array element  is  treated  as  a
 reference to all elements of the array.

     This  setting  controls warnings not only for local variables but
 also for variables in COMMON blocks.  Level 2 also controls whether a
 warning  is given when an entire COMMON block is unused.  When check-
 ing for used-before-set errors involving  COMMON  variables,  ftnchek
 does  not  do  a  thorough enough analysis of the calling sequence to
 know which routines are called before others.  So warnings about this
 type  of  error  will  only be given for cases in which a variable is
 used in some routine but not set in any other routine.   Checking  of
 individual  COMMON variables is done only if the /common setting is 3
 (variable by variable agreement).

     See also: /common, /declare, /volatile.


3 /verbose
       This option is on by  default.   Turning  it  off  reduces  the
 amount of output relating to normal operation, so that error messages
 are more apparent.  This option is provided for  the  convenience  of
 users  who are checking large suites of files.  The eliminated output
 includes the names of project files, and the message  reporting  that
 no  syntax errors were found.  (Some of this output is turned back on
 by the /list and /symtab options.)  Default = yes.


3 /volatile
       Assume that COMMON blocks are volatile.  Default = no.

     Many Fortran programmers assume that variables, whether local  or
 in  COMMON,  are static, i.e. that once assigned a value, they retain
 that value permanently until assigned a different value by  the  pro-
 gram.  However, in fact the Fortran 77 Standard does not require this
 to be the case.  Local variables may become undefined between activa-
 tions  of  a  module  in  which they are declared.  Similarly, COMMON
 blocks may become undefined if no module in which they  are  declared
 is  active.   (The technical term for this behavior is ``automatic'',
 but ftnchek uses the word ``volatile'' since it  is  clearer  to  the
 nonspecialist.)   Only COMMON blocks declared in a SAVE statement, or
 declared in the main program or in a  block  data  subprogram  remain
 defined  as  long  as  the  program is running.  Variables and COMMON
 blocks that can become undefined at some point are called volatile.

     If the /volatile flag is turned on, ftnchek will warn you  if  it
 finds a volatile COMMON block.  If, at the same time, the /usage set-
 ting is 1 or 3 (check used before set), ftnchek  will  try  to  check
 whether  such a block can lose its defined status between activations
 of the modules where it is declared.  ftnchek does not do a very good
 job of this: the rule used is to see whether the block is declared in
 two separated subtrees of the call tree.  For instance, this would be
 the  case if two modules, both called from the main program, shared a
 volatile COMMON block.  A block can also become undefined between two
 successive  calls  of  the  same subprogram, but ftnchek is not smart
 enough to tell whether a subprogram can be called more than once,  so
 this case is not checked for.

     The  /volatile  flag  does  not affect the way ftnchek checks the
 usage of local variables.

     See also: /common, /usage.


3 /wordsize=num
       Specifies the default word size to be num bytes.  This  is  the
 size  of  logical and single-precision numeric variables that are not
 given explicit precisions.  Double-precision  and  complex  variables
 will  be  twice  this value, and double complex variables four times.
 Explicit precisions for non-character variables are an  extension  to
 the  Fortran  77 Standard, and are given by type declarations such as
 REAL*8 X.  Default = 4 bytes.

     If you want to change the built-in default value of this setting,
 compile  ftnchek  with the macro name BpW (Bytes per Word) set to the
 desired default value.  This is not critical:  the  word  size  value
 does not matter for checking standard-conforming programs that do not
 declare explicit precisions for non-character variables or store Hol-
 lerith  data  in  variables.   This  setting also does not affect the
 default size of character variables, which is always  1  byte.   Hol-
 lerith constants also are assumed to occupy 1 byte per character.

     The  word  size is used to determine whether truncation occurs in
 assignment statements, and to catch precision mismatches  in  subpro-
 gram  argument lists and common block lists.  The exact warnings that
 are issued will depend on the status of other flags.  Under both  the
 /portability  or  /nowordsize  flags,  any  mixing  of  explicit with
 default precision objects (character  expressions  not  included)  is
 warned about.  This applies to arithmetic expressions containing both
 types of objects, and to subprogram arguments and  COMMON  variables.
 Under  the  /truncation flag, a warning is given for assignment of an
 expression to a shorter variable of the same type, or  for  promotion
 of  a  lower  precision  value  to  higher precision in an arithmetic
 expression or an assignment statement.

     Giving a word size of 0, or equivalently, using /nowordsize means
 that  no  default value will be assumed.  Use this instead of /porta-
 bility if you want to check only for  those  aspects  of  portability
 related to mixing default and explicit precision, for example to flag
 places where REAL*8 is treated as equivalent to DOUBLE PRECISION.

     See also: /portability, /truncation.


3 /wrap=col
       Controls the wrapping of error messages.  Long  error  messages
 that would run past the specified column will be broken up into sepa-
 rate lines between the words of the message for  better  readability.
 If  turned  off  with  /nowrap,  each  separate error message will be
 printed on one line, leaving it up to the display to wrap the message
 or truncate it.  Default = 79.


2 Changing_the_defaults
       ftnchek includes a mechanism for changing the default values of
 all options by defining environment variables.  When  ftnchek  starts
 up,  it  looks  in  its environment for any variables whose names are
 composed by prefixing the string FTNCHEK_ onto the uppercased version
 of  the  option name.  If such a variable is found, its value is used
 to specify the default for the corresponding switch or  setting.   In
 the  case  of  settings (for example, the /common strictness setting)
 the value of the environment variable is read as the default  setting
 value.   In the case of switches, the default switch will be taken as
 true or yes unless the environment variable has the value  0  or  NO.
 Of course, command-line options will override these defaults the same
 way as they override the built-in defaults.
      Note that the environment variable name must be constructed with
 the  full-length  option name, which must be in uppercase.  For exam-
 ple, to make ftnchek print a source listing by default, set the envi-
 ronment variable FTNCHEK_LIST to 1 or YES or anything other than 0 or
 NO.  The names FTNCHEK_LIS (not the full option name) or ftnchek_list
 (lower case) would not be recognized.

 The  way to set the environment variables on the VAX/VMS system is by
 using the DEFINE command.  For example,  to  set  the  default  /list
 switch to YES, give the command

          $ DEFINE FTNCHEK_LIST 1


2 Project_files
        This  section contains detailed information on how to use pro-
 ject files most effectively, and how to avoid some pitfalls.
      Ordinarily, project files should be created  with  the  /library
 flag  in  effect.  In this mode, the information saved in the project
 file consists of all subprogram declarations, all subprogram  invoca-
 tions not resolved by declarations in the same file, and one instance
 of each COMMON block declaration.  This  is  the  minimum  amount  of
 information needed to check agreement between files.
      If  the file contains more than one routine, there are some pos-
 sible problems that can arise  from  creating  the  project  file  in
 library  mode,  because  the calling hierarchy among routines defined
 within the file is lost.  Also, if the routines in the file make  use
 of  COMMON blocks that are shared with routines in other files, there
 will not be enough information saved for the correct checking of  set
 and  used  status  of COMMON blocks and COMMON variables according to
 the /usage setting.  Therefore if you plan to use project files  when
 the  /usage  setting is nonzero (which is the default situation), and
 if multiple routines in one project file  share  COMMON  blocks  with
 routines in other files, the project files should be created with the
 /library flag turned off.  In this mode, ftnchek saves,  besides  the
 information  listed  above,  one invocation of each subprogram by any
 other subprogram in the same file, and all COMMON block declarations.
 This  means  that the project file will be larger than necessary, and
 that when it is read in, ftnchek may repeat some inter-module  checks
 that  it already did when the project file was created.  If each pro-
 ject file contains only one module, there is no loss  of  information
 in creating the project files in library mode.
      Because of the possible loss of information entailed by creating
 a project file with the /library flag in effect, whenever  that  pro-
 ject  file  is  read  in  later, it will be treated as a library file
 regardless of the current setting of the /library flag.  On the other
 hand, a project file created with library mode turned off can be read
 in later in either mode.














































