home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / fchk294b.zip / ftnchek-2.9.4 / blurb.txt < prev    next >
Text File  |  1996-10-02  |  15KB  |  463 lines
  1.  
  2.  
  3.  
  4. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  5.  
  6.  
  7. NAME
  8.         ftnchek - Fortran 77 program checker
  9.  
  10.  
  11. SYNOPSIS
  12.        ftnchek [ -arguments[=num] ] [ -array[=num] ]
  13.             [ -calltree[=num] ] [ -[no]check ] [ -columns[=num] ]
  14.             [ -common[=num] ] [ -[no]crossref ] [ -[no]declare ]
  15.             [ -[no]division ] [ -[no]extern ] [ -[no]f77[=str] ]
  16.             [ -[no]help ] [ -include=str ] [ -intrinsic[=num] ]
  17.             [ -[no]library ] [ -[no]list ] [ -makedcls[=num] ]
  18.             [ -[no]novice ] [ -output=str ]
  19.             [ -[no]portability[=str] ] [ -[no]pretty[=str] ]
  20.             [ -[no]project ] [ -[no]pure ] [ -[no]quiet ]
  21.             [ -[no]reference ] [ -[no]resources ]
  22.             [ -[no]sixchar ] [ -[no]sort ] [ -source[=num] ]
  23.             [ -[no]symtab ] [ -[no]truncation[=str] ]
  24.             [ -usage[=num] ] [ -[no]vcg ] [ -[no]version ]
  25.             [ -[no]volatile ] [ -wordsize[=num] ] [ -wrap[=num] ]
  26.             [ files ...  ]
  27.  
  28.  
  29. DESCRIPTION
  30.  
  31.  
  32.        ftnchek  (short for Fortran checker) is designed to detect
  33.        certain errors in a Fortran program that a  compiler  usu-
  34.        ally  does  not.   ftnchek  is  not  primarily intended to
  35.        detect syntax errors.  Its purpose is to assist  the  user
  36.        in  finding semantic errors.  Semantic errors are legal in
  37.        the Fortran language but are wasteful or may cause  incor-
  38.        rect  operation.   For  example, variables which are never
  39.        used may indicate some omission in the program; uninitial-
  40.        ized  variables  contain garbage which may cause incorrect
  41.        results to be calculated;  and  variables  which  are  not
  42.        declared  may  not  have  the  intended  type.  ftnchek is
  43.        intended to assist users in the debugging of their Fortran
  44.        program.   It  is not intended to catch all syntax errors.
  45.        This is the function of  the  compiler.   Prior  to  using
  46.        ftnchek,  the user should verify that the program compiles
  47.        correctly.
  48.  
  49.  
  50. INVOKING FTNCHEK
  51.         ftnchek is invoked through a command of the form:
  52.  
  53.         $ ftnchek [-option -option ...] filename [filename ...]
  54.  
  55.        The brackets indicate something which  is  optional.   The
  56.        brackets  themselves are not actually typed.  Here options
  57.        are command-line switches or settings, which  control  the
  58.        operation  of  the  program  and the amount of information
  59.        that will be printed out.  If no option is specified,  the
  60.        default  action  is to print error messages, warnings, and
  61.  
  62.  
  63.  
  64.                             4 Apr 1996                          1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  71.  
  72.  
  73.        informational messages, but not  the  program  listing  or
  74.        symbol tables.
  75.  
  76.  
  77.        Each option begins with the '-' character.  (On VAX/VMS or
  78.        MS-DOS systems you  may  use  either  '/'  or  '-'.)   The
  79.        options  are  described at greater length in the next sec-
  80.        tion.
  81.  
  82.        ftnchek options fall into two categories: switches,  which
  83.        are  either  true  or  false,  and  settings, which have a
  84.        numeric or string value.  The name of a switch is prefixed
  85.        by  'no'  to  turn it off: e.g. -nopure would turn off the
  86.        warnings about impure functions. The 'no' prefix can  also
  87.        be  used with numeric settings, having the effect of turn-
  88.        ing off the corresponding warnings.  Settings that control
  89.        lists  of  warnings have a special syntax discussed below.
  90.        Only the first 3 characters of an option name (not  count-
  91.        ing  the  '-')  need  be provided.  A colon may be used in
  92.        place of an equals sign  for  numeric  or  string  setting
  93.        assignments;  however,  we  show only the equals sign form
  94.        below.
  95.  
  96.  
  97.        The switches and settings which ftnchek  currently  recog-
  98.        nizes are:
  99.  
  100.        -arguments=num
  101.               Set  level  of  strictness  in  checking subprogram
  102.               arguments.  Min is 0 (no checking).  Max is 3 (most
  103.               checking).  Default = turn-on = 3.
  104.  
  105.        -array=num
  106.               Set level of strictness in checking array arguments
  107.               of subprograms.  Min is 0 (least strict).  Max is 3
  108.               (most strict).  Default = turn-on = 3.
  109.  
  110.        -calltree=num
  111.               Produce  subprogram call hierarchy in one of 3 for-
  112.               mats.  Default = 0, no tree.  Turn-on  =  1,  call-
  113.               tree format.  Other values are 2, who-calls-who and
  114.               3, VCG.
  115.  
  116.        -check Perform checking.  Default = yes.
  117.  
  118.        -columns=num
  119.               Set maximum line length  to  num  columns.  (Beyond
  120.               this  is ignored.)  Turn-on = max = 132.  Default =
  121.               72.
  122.  
  123.        -common=num
  124.               Set level of strictness in checking COMMON  blocks.
  125.               Min  is 0 (no checking).  Max is 3 (must be identi-
  126.               cal).  Default = turn-on = 3.
  127.  
  128.  
  129.  
  130.                             4 Apr 1996                          2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  137.  
  138.  
  139.        -crossref
  140.               Print cross-reference list of subprogram calls  and
  141.               COMMON block use.  Default = no.
  142.  
  143.        -declare
  144.               Print  a  list of all identifiers whose datatype is
  145.               not explicitly declared.  Default = no.
  146.  
  147.        -division
  148.               Warn wherever division is done (except division  by
  149.               a constant).  Default = no.
  150.  
  151.        -extern
  152.               Warn  if external subprograms which are invoked are
  153.               never defined.  Default = yes.
  154.  
  155.        -f77=list
  156.               Control specific warnings  about  supported  exten-
  157.               sions to the Fortran 77 Standard.  Default  = none.
  158.  
  159.        -help  Print command summary.  Default = no.
  160.  
  161.        -include=path
  162.               Define a directory to  search  for  INCLUDE  files.
  163.               Cumulative.
  164.  
  165.        -intrinsic=num
  166.               Control  treatment  of  nonstandard intrinsic func-
  167.               tions.  Three digits.  Max = 223.  Default =  turn-
  168.               on = 222 for Unix version, 223 for VMS version, 221
  169.               for others.
  170.  
  171.        -library
  172.               Begin library mode: do not warn  about  subprograms
  173.               in file that are defined but never used.  Default =
  174.               no.
  175.  
  176.        -list  Print source listing of program.  Default = no.
  177.  
  178.        -makedcls=num
  179.               Prepare a file of declarations.  Min is 0 (no  dec-
  180.               laration file).  Max is 1023.  Default = 0, turn-on
  181.               = 1.
  182.  
  183.        -novice
  184.               Give output suitable for novice users.   Default  =
  185.               yes.
  186.  
  187.        -output=filename
  188.               Send  output to the given file.  Default is to send
  189.               output to the screen. (Default  filename  extension
  190.               is .lis).
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                             4 Apr 1996                          3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  203.  
  204.  
  205.        -portability=list
  206.               Warn about non-portable usages.  Default = none.
  207.  
  208.        -pretty=list
  209.               Give warnings for possibly misleading appearance of
  210.               source code.    Default = all.
  211.  
  212.        -project
  213.               Create  project  file  (see   explanation   below).
  214.               Default = no.
  215.  
  216.        -pure  Assume  functions  are  pure,  i.e.  have  no  side
  217.               effects.  Default = yes.
  218.  
  219.        -quiet Produce less verbose output.  Default = no.
  220.  
  221.        -reference
  222.               Print table of subprograms referenced by each  sub-
  223.               program.  Default = no.
  224.  
  225.        -resources
  226.               Print  amount  of  resources  used in analyzing the
  227.               program.  Default = no.
  228.  
  229.        -sixchar
  230.               List any variable names which clash at 6 characters
  231.               length.  Default = no.
  232.  
  233.        -sort  Print  list  of  subprograms sorted in prerequisite
  234.               order.  Default = no.
  235.  
  236.        -source=num
  237.               Select source formatting options.  Sum of 1 for DEC
  238.               Fortran   tab-formatted   lines,  2  for  VMS-style
  239.               INCLUDE statement, and 4 for  UNIX-style  backslash
  240.               escape sequences.  Default = 0.  Turn-on = max = 7.
  241.  
  242.        -symtab
  243.               Print symbol table for each subprogram.  Default  =
  244.               no.
  245.  
  246.        -truncation=list
  247.               Check  for possible loss of accuracy by truncation.
  248.               Default = all.
  249.  
  250.        -usage=num
  251.               Control  warnings  about  unused  variables,   etc.
  252.               Three  digits: 1st digit = subprograms, 2nd digit =
  253.               common, 3rd digit  =  local  variables.   For  each
  254.               digit:  min  is  0  (no  checking).  Max is 3 (most
  255.               checking).  Default = turn-on = 333.
  256.  
  257.        -vcg   Produce VCG format of call graph.
  258.  
  259.  
  260.  
  261.  
  262.                             4 Apr 1996                          4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  269.  
  270.  
  271.        -version
  272.               Print version number.  Default = no.
  273.  
  274.        -volatile
  275.               Assume COMMON blocks lose definition between  acti-
  276.               vations.  Default = no.
  277.  
  278.        -wordsize=num
  279.               Set the default word size for numeric quantities to
  280.               num bytes.  Default = turn-on = 4 bytes.
  281.  
  282.        -wrap=num
  283.               Set output column at which to wrap long error  mes-
  284.               sages  and warnings to the next line.  If set to 0,
  285.               turn off wrapping.  Default = turn-on = 79.
  286.  
  287.  
  288.        When more than one option is used, they  should  be  sepa-
  289.        rated  by  a  blank  space,  except on systems such as VMS
  290.        where options begin with slash ( / ).  No blank spaces may
  291.        be  placed  around  the  equals  sign  ( = ) in a setting.
  292.        ftnchek "?"  will produce a command  summary  listing  all
  293.        options and settings.
  294.  
  295.        For  settings  that  take a list of warnings, namely -f77,
  296.        -pretty, -portability, and -truncation, the list  consists
  297.        of  keywords  separated by commas or colons.  The list can
  298.        be omitted, having the effect of turning on all the corre-
  299.        sponding warnings.  Also, if the list is omitted, the set-
  300.        ting name can be prefixed with no  to  turn  off  all  the
  301.        warnings  it  controls.   For  example,  -f77 turns on all
  302.        warnings about  nonstandard  constructions,  while  -nof77
  303.        turns them all off.    Three special keywords are:
  304.  
  305.        help   Print  out  all  the  warning  option keywords con-
  306.               trolled by the setting, with a brief explanation of
  307.               their  meanings.  This keyword cannot be given in a
  308.               list with other keywords.
  309.  
  310.        all    Set all warnings. This turns on all  warnings  con-
  311.               trolled by the setting.
  312.  
  313.        none   Clear  all  warnings.   This turns off all warnings
  314.               controlled by the setting.
  315.  
  316.        These special keywords must be given  in  full.   For  all
  317.        other  warning  keywords, only as many letters of the key-
  318.        word as are necessary to identify it unambiguously need be
  319.        given.  Including a keyword in the list turns its warnings
  320.        on.  For example, -f77=intrinsic would turn  on  only  the
  321.        warnings  about  use  of  nonstandard intrinsic functions.
  322.        Prefixing a keyword by no- turns its  warnings  off.   For
  323.        example,  -pretty=no-long-line  turns  off  warnings about
  324.        lines exceeding 72 columns in  length  while  leaving  all
  325.  
  326.  
  327.  
  328.                             4 Apr 1996                          5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  335.  
  336.  
  337.        other  warnings about misleading appearance in effect.  If
  338.        a setting has default none, you can turn on  all  warnings
  339.        except  one  or  two  by  using  all  first.  For example,
  340.        -f77=all,no-include enables warnings about all nonstandard
  341.        extensions  except  INCLUDE  statements.  If a setting has
  342.        default all, you can turn off all warnings except  one  or
  343.        two   by   using   none   first.   For  example,  -trunca-
  344.        tion=none,demotion would turn off  all  precision  related
  345.        warnings except about demotions.
  346.  
  347.        When ftnchek starts up, it looks for environment variables
  348.        and also for a preferences file.  Any options  defined  in
  349.        the  environment  or  in  the preferences file are used as
  350.        defaults in place of  the  built-in  defaults.   They  are
  351.        over-ridden  by any command line options.  See the section
  352.        on changing the defaults for details about the environment
  353.        options and the preferences file.
  354.  
  355.  
  356.        When  giving  a  name  of  an input file, the extension is
  357.        optional.  If no extension is given,  ftnchek  will  first
  358.        look  for a project file with extension .prj, and will use
  359.        that if it exists.  If not, then ftnchek will look  for  a
  360.        Fortran  source  file with the extension .for for VMS sys-
  361.        tems, .f for UNIX systems.  More than one file name can be
  362.        given  to  ftnchek, and it will process the modules in all
  363.        files as if they were in a single file.
  364.  
  365.  
  366.        Wildcards are allowed in the specification of filenames on
  367.        the  command line for the VMS and MS-DOS versions, as also
  368.        of course under UNIX and any other  system  that  performs
  369.        wildcard expansion in the command processor.
  370.  
  371.        If  no filename is given, ftnchek will read input from the
  372.        standard input.
  373.  
  374.  
  375. INSTALLATION AND SUPPORT
  376.        The ftnchek program can be obtained by anonymous ftp  from
  377.        many   software   servers,   including   host   netlib.org
  378.        (128.169.92.17) where it is located in directory /fortran.
  379.        You should download it in binary mode.  If the file exten-
  380.        sion is .Z, uncompress with the Unix  uncompress(1)  util-
  381.        ity.   If  the  file extension is .gz, uncompress with the
  382.        GNU gunzip(1L) program.  Then use  tar(1)  to  unpack  the
  383.        files into a subdirectory.
  384.  
  385.        Installation requires a C compiler for your computer.  See
  386.        the  INSTALL  file  provided  with  the  distribution  for
  387.        instructions  on  installing ftnchek on your system.  Exe-
  388.        cutable binary for particular systems such as  IBM  PC  or
  389.        Macintosh,  as available, can be obtained by anonymous ftp
  390.        from  ftp.dsm.fordham.edu   (150.108.64.2),   located   in
  391.  
  392.  
  393.  
  394.                             4 Apr 1996                          6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. FTNCHEK 2.9(1L)                                   FTNCHEK 2.9(1L)
  401.  
  402.  
  403.        directory  /pub/ftnchek2.9.   Assistance in preparing such
  404.        executable binary forms is welcome.
  405.  
  406.        Information about the latest version and the status of the
  407.        project  can  be obtained by the Internet command ``finger
  408.        ftnchek@mary.fordham.edu''.  For further  information  and
  409.        to  report  bugs, you may contact Dr. Robert Moniot at the
  410.        following network address:
  411.  
  412.                   moniot@mary.fordham.edu
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                             4 Apr 1996                          7
  461.  
  462.  
  463.