Category : Miscellaneous Language Source Code
Archive   : FTNCHECK.ZIP
Filename : FTNCHEK.HLP

 
Output of file : FTNCHEK.HLP contained in archive : FTNCHECK.ZIP



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



  3 Responses to “Category : Miscellaneous Language Source Code
Archive   : FTNCHECK.ZIP
Filename : FTNCHEK.HLP

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/