OS/2 Shareware BBS: 10 Tools/10-Tools.zip/FTNCHK32.ZIP/ftnchek.hlp

Text File | 1993-02-16 | 24KB | 434 lines

1 FTNCHEK
 Fortran program checker.
2 Introduction


      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  operation.   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  compiler.  Prior to using
 Ftnchek, the user should verify that the program compiles correctly.

      For more detailed information, consult the 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.)
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'
 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.

      If no filename is  given,  Ftnchek  will  read  input  from  the
 standard 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.
3 /array=n
 Controls  warnings  about  mismatches  between   actual   and   dummy
 subprogram  array  arguments.   (An  actual  argument  is an argument
 passed to the subprogram by  the  caller;  a  dummy  argument  is  an
 argument  received  by  the  subprogram.)  Default = 3.  The warnings
 which can be turned off are for constructions that might legitimately
 be  used  by  a  knowledgeable  programmer,  but  that often indicate
 programming errors.

      The meanings of the setting values are as follows:

         0:  only the warnings noted below.

         1:  give warnings 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:  give warnings if  the  arguments  are  both  arrays,  but
            differ in size.

         3:  give both types of warnings.

      Note:  no warning is ever given if the  actual  argument  is  an
 array  element  while  the dummy argument is a scalar variable, and 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  expression  while
 the  dummy  argument  is an array.  Variable-dimensioned arrays match
 any array size.
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
 margin.  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 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 no main program is
 found, a report to that effect is printed out, and no  call  tree  is
 printed.   If multiple main programs are found, the call tree of each
 is printed separately.

      Now that  Ftnchek  recognizes  the  call  tree  structure  of  a
 program,  its  checking  behavior  is  somewhat altered from previous
 versions, which checked the calls of every  routine  by  every  other
 routine,  regardless of whether those routines could ever actually be
 invoked at run time.  Now, if a file is read with the  /library  flag
 in  effect,  the calls made by a routine in that file will be checked
 only if the calling routine is  in  the  main  program's  call  tree.
 Likewise,  COMMON declarations in a library file will only be checked
 if the routine is in the call tree.  If the /library flag is not set,
 Ftnchek   will   check   all   inter-module   calls  and  all  common
 declarations, as it did formerly.   (If  there  is  no  main  program
 anywhere  in the set of files that Ftnchek has read, so that there is
 no call tree, then library routines  will  be  checked  if  they  are
 called by any routine in the complete set of files.)
3 /columns=n
 Set maximum statement length to n 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 overlength lines that are
 processed.  Max is 132.  Default = 72.
3 /common=n
 This setting varies the strictness  of  checking  of  COMMON  blocks.
 Default = 3.

      The different levels are:

         0:  no checking.

         1:   in  each  declaration   of   a   given   COMMON   block,
            corresponding memory locations 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.
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.
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.
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.
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.
3 /help
 This command is identical in function to the  "?"  argument,  and  is
 provided  simply  as  a  convenience  for  those systems in which the
 question  mark  has  special  meaning  to  the  command  interpreter.
 Default = no.
3 /hollerith
 Hollerith constants (other than within format specifications)  are  a
 source  of  possible  portability  problems, so when the /portability
 flag is set, warnings about them will be produced.  If  your  program
 uses  many hollerith constants, these warnings can obscure other more
 serious warnings.  So you can set this flag to "no" to  suppress  the
 warnings  about  holleriths.   This  flag  has  no  effect  when  the
 /portability flag is turned off.  Default = yes.
3 /include=n
 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 the standard systemwide directory SYS$LIBRARY.
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.
3 /linebreak
 Normally, when scanning a statement which is continued onto the  next
 line,  Ftnchek  treats the end of the line as a space.  This behavior
 is the same as for Pascal and C, and also corresponds to  how  humans
 normally  would  read  and write programs.  However, occasionally one
 would like to use Ftnchek to check a program in which identifiers and
 keywords  are  split  across  lines,  for instance programs which are
 produced using a preprocessor.  Choosing the option /nolinebreak will
 cause Ftnchek to skip over the end of line and also any leading space
 on the continuation line (from the continuation mark up to the  first
 nonspace character).  Default = yes, i.e.  treat linebreaks as space.
 Default = no.

      Note  that  in  nolinebreak  mode,  if  token  pairs   requiring
 intervening  space  (for  instance, GOTO 100) are separated only by a
 linebreak, they will be rejoined.

      Also, tokens requiring more than one character of lookahead  for
 the  resolution  of  ambiguities  must not be split across lines.  In
 particular, a complex constant may not be split across a line.
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.
3 /novice
 This flag is  intended  to  provide  additional  helpful  output  for
 beginners.   At  this  time,  the only extra message it provides is a
 comment that any 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).  Default = yes.

      In earlier versions  of  Ftnchek,  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 /impure flag.
3 /output=n
 This setting is provided for convenience  on  systems  which  do  not
 allow easy redirection of output from programs.  When this setting 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.
 These  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
 violations  of  the  Fortran  77  standard,  which  may  also   cause
 portability  problems.  To catch those, use the /f77 option.  Default
 = no.
3 /pretty
 Controls certain messages related to the  appearance  of  the  source
 code.   These warn about things that might in some cases be deceptive
 to the reader.  At present, the only warning that  is  controlled  by
 this  flag  refers  to  comments  that  are  interspersed  among  the
 continuation lines of a statement.  Default = yes.
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 block 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.

      Project files  contain  only  information  needed  for  checking
 agreement 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.

      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
 invocations  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.  Of
 course, this means that the calling hierarchy among routines  defined
 within  the  file  is lost.  Normally the loss of this information is
 unimportant.  If you wish to retain this information for some reason,
 you  can  create  the project file 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.

      Because of the  loss  of  information  entailed  by  creating  a
 project  file with the /library flag in effect, whenever that project
 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.

      Naturally, when the /project flag is set, Ftnchek will not  read
 project files as input.
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
 functions  will be handled the same way as actual arguments passed to
 subroutines.  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 /sixchar
 One of the goals of the Ftnchek program is to  help  users  to  write
 portable Fortran programs.  One potential source of nonportability is
 the use of variable names that are longer than six characters.   Some
 compilers  just  ignore  the  extra  characters.  This behavior could
 potentially lead to two different variables being considered  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.
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
 statement.   The  table  also  lists  all  subprograms invoked by the
 module, all COMMON blocks declared, etc.  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:  conversion of a complex or  double  precision
 value  to  single  precision; conversion of any real type to integer;
 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); division in an integer constant  expression  that
 yields  a  result of zero; exponentiation of an integer by a negative
 integer  (which  yields  zero  unless  the  base  integer  is  1   in
 magnitude);  and use of a non-integer array subscript, DO index or DO
 loop bounds.  Default=yes.

      Note:  warnings about truncating type conversions are given only
 when  the  conversion  is  done automatically, i.e.  by an assignment
 statement.  If intrinsic functions such as INT are  used  to  perform
 the conversion, no warning is given.
3 /usage=n
 Warn about unused or possible uninitialized variables.  Default=3.

      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.

      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.
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.
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 novice level) 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
 example, to make Ftnchek print a source listing by default,  set  the
 environment  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