FTNCHEK 3.3(1L)                                                FTNCHEK 3.3(1L)



NAME
        ftnchek - Fortran 77 program checker


SYNOPSIS
       ftnchek [ -arguments[=list] ] [ -array[=list] ]
            [ -[no]brief ] [ -calltree[=list] ] [ -[no]check ]
            [ -columns[=num] ] [ -common[=list] ]
            [ -[no]crossref[=list] ] [ -[no]declare ]
            [ -[no]division ] [ -errors[=num] ] [ -[no]extern ]
            [ -[no]f77[=list] ] [ -[no]f90[=list] ]
            [ -[no]f95[=list] ] [ -[no]help ]
            [ -[no]identifier-chars[=list] ] [ -include=str ]
            [ -intrinsic[=list] ] [ -[no]library ] [ -[no]list ]
            [ -makedcls[=list] ] [ -mkhtml[=list] ]
            [ -[no]novice ] [ -output=str ]
            [ -pointersize[=num] ] [ -[no]portability[=list] ]
            [ -[no]pretty[=list] ] [ -project[=list] ]
            [ -[no]pure ] [ -[no]quiet ] [ -[no]reference ]
            [ -[no]resources ] [ -[no]sixchar ] [ -[no]sort ]
            [ -source[=list] ] [ -style[=list] ] [ -[no]symtab ]
            [ -[no]truncation[=list] ] [ -usage[=list] ]
            [ -[no]vcg ] [ -[no]version ] [ -[no]volatile ]
            [ -wordsize[=num] ] [ -wrap[=num] ] [ files ...  ]


DESCRIPTION


       ftnchek  (short  for  Fortran  checker)  is  designed to detect certain
       errors in a Fortran program that a compiler usually does not.   ftnchek
       is  not  primarily intended to detect syntax errors.  Its purpose is to
       assist the user in finding semantic errors.  Semantic errors are  legal
       in  the Fortran language but are wasteful or may cause incorrect opera-
       tion.  For example, variables which are never used  may  indicate  some
       omission  in the program; uninitialized variables contain garbage which
       may cause incorrect results to be calculated; 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 com-
       piler.  Prior to using ftnchek, the user should verify that the program
       compiles correctly.


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 them-
       selves 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 informa-
       tional messages, but not the program listing or symbol tables.


       Each option begins with the '-' character.  (On VAX/VMS or MS-DOS  sys-
       tems  you  may use either '/' or '-'.)  For the sake of conformity with
       an increasingly common convention, options can also  begin  with  '--'.
       The options are described at greater length in the next section.

       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' or '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.  Settings that control lists of
       warnings have a special syntax discussed below.  Only the first 3 char-
       acters of an option name (not counting the '-') need  be  provided.   A
       colon may be used in place of an equals sign for numeric or string set-
       ting assignments; however, we show only the equals sign form below.


       The switches and settings which ftnchek currently recognizes are listed
       below.  For each option, the default is the value used if the option is
       not explicitly specified, while the turn-on is the value  used  if  the
       option is given without assigning it a value.

       -arguments=list
              Control  warnings about subprogram type and argument mismatches.
              Default = turn-on = all.

       -array=list
              Control warnings in checking  array  arguments  of  subprograms.
              Default = turn-on = all.

       -brief Use shorter format for some error messages.  Default = no.

       -calltree=list
              Produce  subprogram  call  hierarchy  in  one of 3 formats: text
              call-tree, who-calls-who and VCG.  Default  =  none,  turn-on  =
              tree,prune,sort.

              If  the  -mkhtml option is invoked and tree is the applied call-
              tree option,  a  file  named  CallTree.html,  will  be  produced
              depicting the tree in HTML format.

       -check Perform checking.  Default = yes.

       -columns=num
              Set  maximum  line  length  to  num  columns.  (Beyond  this  is
              ignored.)  Turn-on = max = 132.  Default = 72.

       -common=list
              Set degree of strictness in checking COMMON blocks.   Default  =
              turn-on = all.

       -crossref=list
              Print  cross-reference  list  of  subprogram calls, label usage,
              and/or COMMON block use.  Default = none.

       -declare
              Print a list of all identifiers whose datatype is not explicitly
              declared.  Default = no.

       -division
              Warn  wherever division is done (except division by a constant).
              Default = no.

       -errors=num
              Set the maximum number of error messages per cascade.  Default =
              turn-on = 3.

       -extern
              Warn  if  external  subprograms  which  are  invoked  are  never
              defined.  Default = yes.

       -f77=list
              Control specific warnings about supported extensions to the For-
              tran 77 Standard.  Default  = none, turn-on = all.

       -f90=list
              Control specific warnings about supported extensions to the For-
              tran 77 Standard that were not adopted as part of the Fortran 90
              Standard.  Default  = none, turn-on = all.

       -f95=list
              Control  specific  warnings  about  standard Fortran 77 features
              that were deleted from the  Fortran  95  Standard.   Default   =
              none, turn-on = all.

       -help  Print command summary.  Default = no.

       -identifier-chars=list
              Define  non-alphanumeric  characters that may be used in identi-
              fiers.  Default = turn-on = dollar sign and underscore.

       -include=path
              Define a directory to search for INCLUDE files before  searching
              in  the system-wide directory.  Cumulative.  Default = turn-on =
              none.

       -intrinsic=list
              Control treatment of nonstandard intrinsic functions.  Default =
              all  except  vms  for Unix version, all except unix for VMS ver-
              sion, all except unix and vms for  other  versions.   Turn-on  =
              all.

       -library
              Begin  library  mode: do not warn about subprograms in file that
              are defined but never used.  Default = no.

       -list  Print source listing of program.  Default = no.

       -makedcls=list
              Prepare a file of declarations.  The list specifies options  for
              the  format  of  this  file.  Default = none, turn-on = declara-
              tions.

       -mkhtml=list
              Create individual HTML document files from ftnchek analysis  and
              code comments.  Usually you will also want to specify -call=tree
              to create the root HTML file  CallTree.html.   Default  =  none,
              turn-on = documents.

       -novice
              Give output suitable for novice users.  Default = yes.

       -output=filename
              Send output to the given file.  Default and turn-on sends output
              to the screen. (Default filename extension is .lis).

       -pointersize=num
              Set the size of ''Cray pointer'' variables to num bytes.  Min  =
              1, max = 16.  Default = turn-on = 4

       -portability=list
              Warn  about non-portable usages.  Default = none, turn-on = all.

       -pretty=list
              Give warnings for possibly misleading appearance of source code.
              Default = turn-on = all.

       -project=list
              Create project file (see explanation below).  Default = no.

       -pure  Assume functions are pure, i.e. have no side effects.  Default =
              yes.

       -quiet Produce less verbose output.  Default = no.

       -reference
              Print  table  of  subprograms  referenced  by  each  subprogram.
              Default = no.

       -resources
              Print  amount  of  resources  used  in  analyzing  the  program.
              Default = no.

       -sixchar
              List any variable names which  clash  at  6  characters  length.
              Default = no.

       -sort  Print list of subprograms sorted in prerequisite order.  Default
              = no.

       -source=list
              Select source formatting options: fixed or free form,  DEC  For-
              tran  tab-formatted  lines,  VMS-style  INCLUDE statement, UNIX-
              style backslash escape sequences, and implicit typing of parame-
              ters.  Default = none, turn-on = all.

       -style=list
              Produce  extra-picky warnings about obsolescent or old-fashioned
              programming constructions.  Default = none, turn-on = all.

       -symtab
              Print symbol table and label table for each subprogram.  Default
              = no.

       -truncation=list
              Check  for  possible  loss of accuracy by truncation.  Default =
              turn-on = all.

       -usage=list
              Control warnings about unused or uninitialized variables, common
              blocks, etc.  Default = turn-on = all.

       -vcg   Produce VCG format of call graph.

       -version
              Print version number.  Default = no.

       -volatile
              Assume   COMMON  blocks  lose  definition  between  activations.
              Default = no. (Obsolete.  Use -common=volatile instead.)

       -wordsize=num
              Set the default word size for numeric quantities to  num  bytes.
              Default = turn-on = 4 bytes.

       -wrap=num
              Set output column at which to wrap long error messages and warn-
              ings to the next line.  If set to 0, turn off wrapping.  Default
              = turn-on = 79.


       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  listing  all
       options and settings.

       For  settings  that take a list of keywords, namely -arguments, -array,
       -calltree, -common, -crossref, -f77, -f90, -f95, -intrinsic, -makedcls,
       -mkhtml, -portability, -pretty, -project, -source, -style, -truncation,
       and -usage, the list  consists  of  keywords  separated  by  commas  or
       colons.   If  the list of keywords is omitted, the effect is to set the
       option to its turn-on value (same as ''all'' in most cases).  Also,  if
       the list is omitted, the setting name can be prefixed with no or no- to
       turn off all the options it controls.  For example, -f77 turns  on  all
       warnings  about  nonstandard constructions, while -nof77 turns them all
       off.    Three special keywords are:

       help   Print out all the option keywords  controlled  by  the  setting,
              with a brief explanation of their meanings.  This keyword cannot
              be given in a list with other keywords.

       all    Set all options. This turns on all  options  controlled  by  the
              setting.

       none   Clear all options.  This turns off all options controlled by the
              setting.

       These three special keywords must be given in full.  For all other key-
       words, only as many letters of the keyword as are necessary to identify
       it unambiguously need be given, or a  wildcard  pattern  may  be  used.
       Including a keyword in the list turns the corresponding option on.  For
       example, -f77=intrinsic would turn on only the warnings  about  use  of
       nonstandard  intrinsic functions.  Prefixing a keyword by no- turns its
       option off.  For example, -pretty=no-long-line turns off warnings about
       lines  exceeding  72 columns in length while leaving all other warnings
       about misleading appearance in effect.  If a setting has default  none,
       you  can turn on all options except one or two by using all first.  For
       example, -f77=all,no-include enables  warnings  about  all  nonstandard
       extensions  except  INCLUDE  statements.  If a setting has default all,
       you can turn off all warnings except one or two by  using  none  first.
       For  example,  -truncation=none,demotion  would  turn off all precision
       related warnings except about demotions.  Wildcard patterns contain  an
       asterisk  to stand for any string of characters.  If a wildcard pattern
       is used, all the warnings that match it are affected.  If no-  is  pre-
       fixed  to the pattern, all the matching warnings are turned off, other-
       wise they are all turned on.  The minimum unambiguous length rule  does
       not  apply to wildcard matching.    For example, use -usage=no-*var* to
       turn off all warnings relating to variable usage (both local  and  com-
       mon).   (Unix  users may need to quote any options containing wildcards
       in order to prevent the shell from attempting to expand  them.)   Wild-
       cards are recognized only in lists of warning keywords, not in the top-
       level options themselves.

       When ftnchek starts up, it looks for environment variables and also for
       a  preferences  file.  Any options defined in the environment or in the
       preferences file  are  used  as  defaults  in  place  of  the  built-in
       defaults.   They  are over-ridden by any command line options.  See the
       section on changing the defaults  for  details  about  the  environment
       options and the preferences file.


       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  for  VMS
       systems,  .f for UNIX systems.  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 for the VMS and MS-DOS versions, as also of course under UNIX  and
       any  other  system that performs wildcard expansion in the command pro-
       cessor.

       If no filename is given, ftnchek will  read  input  from  the  standard
       input.

NEW FEATURES
       Here are the changes from Version 3.2 to Version 3.3:

       1.  Front-end  has  been rewritten for unlimited lookahead, eliminating
           the longstanding bug that caused incorrect interpretation of state-
           ments whose ambiguity was not resolved in the first line.

       2.  The -mkhtml option is now available in the MS-DOS version.

       3.  Added  support  for  Fortran  90  pointer related syntax: ALLOCATE,
           DEALLOCATE, and NULLIFY statements; the  ALLOCATABLE,  POINTER  and
           TARGET attributes in type declarations; the pointer assigment oper-
           ator => and  intrinsic  functions  ALLOCATED  and  ASSOCIATED;  and
           deferred-shape  array  declarations.   At  present these new syntax
           features are accepted but not properly checked.  This  feature  was
           added by Robert Landrito.

       4.  The  -f77 and -f90 pointer option controlling warnings about ''Cray
           pointers'' has been  renamed  to  cray-pointer.   The  -f77=pointer
           option now instead controls warnings for code containing Fortran 90
           pointer-related syntax.

       5.  Re-implemented -mkhtml processing so  it  is  now  much  faster  on
           source files containing many routines.

       6.  Changed the arrangement of the test directory so there is no longer
           any need to modify the distribution in order to run the test  suite
           (check.bat) under MS-DOS.

       7.  Fixed  bug in reading numeric settings on command line when setting
           name abbreviated to 3 characters.

       8.  Fixed bug causing spurious  warning  for  a  GOTO  referring  to  a
           labeled END statement when the statement before END was a FORMAT.

       9.  New flag -f77=character to control warnings about extensions to the
           Fortran 77 character data type.  Accompanying this new flag is sup-
           port  for Fortran 90 rules for character variable declarations that
           evaluate to zero or negative length,  allowing  them  and  treating
           negative length values as zero.

       10. Fixed  minor  bug in printing of comments and blank lines following
           last END statement in -list mode.

INSTALLATION AND SUPPORT
       The ftnchek program is free software.  It can be obtained by  anonymous
       ftp  from  many  software servers, including ftp://netlib.org/fortran .
       Note that on Netlib the distribution is named ftnchek.tar.gz whereas on
       most  other  servers  the  file  name includes the version number, e.g.
       ftnchek-3.3.0.tar.gz.  If the file extension is .Z, uncompress with the
       Unix  uncompress(1)  utility.  If the file extension is .gz, uncompress
       with the GNU gunzip(1L) program.  Then use tar(1) to unpack  the  files
       into a subdirectory.

       Installation  requires a C compiler for your computer.  See the INSTALL
       file provided with the  distribution  for  instructions  on  installing
       ftnchek  on your system.  Executable binary for particular systems such
       as IBM PC or Macintosh, as available, can be obtained by anonymous  ftp
       from  ftp://ftp.dsm.fordham.edu/pub/ftnchek  .  Assistance in preparing
       such executable binary forms is welcome.

       Information about the latest version and the status of the project  can
       be  obtained  by  visiting  ftnchek's  home  page, http://www.dsm.ford-
       ham.edu/~ftnchek .  For further information and to report bugs, you may
       contact  Dr. Robert Moniot, whose contact information can be found by a
       Web search for his name and Fordham University.  (E-mail address is not
       provided here because it attracts unsolicited commercial e-mail, but it
       is easily constructed by combining his last name with the name  of  the
       university and the edu domain.)



                                 November 2004                 FTNCHEK 3.3(1L)
