home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Power-Programmierung
/
CD1.mdf
/
fortran
/
tools
/
forcheck
/
forchek.hlp
< prev
next >
Wrap
Text File
|
1991-10-28
|
16KB
|
293 lines
1 FORCHEK
Fortran program checker.
2 Introduction
Forchek (short for Fortran checker) is designed to detect
certain errors in a Fortran program that a compiler usually does not.
Forchek 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. Forchek 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
Forchek, the user should verify that the program compiles correctly.
For more detailed information, consult the documentation.
2 Invoking_Forchek
Forchek is invoked through a command of the form:
$ forchek [/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. (Forchek 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, Forchek will first look for a project file
with extension '.prj' and will use that if it exists. If not, then
Forchek 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 Forchek, and it will process the modules in all files as
if they were in a single file.
If no filename is given, Forchek will read input from the
standard input.
2 Options
Forchek 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 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 /columns=n
Set maximum line 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 line.
According to the standard, all characters past column 72 are ignored.
This setting does not affect the reporting of overlength lines under
the /f77 option. Max is 132. Default = 72.
3 /common=n
This setting varies the strictness of checking of common blocks.
Level 3 is the strictest: it requires that in each declaration of a
given common block, corresponding variables agree in data type and
(if arrays) size and number of dimensions. Levels 1 and 2 require
only that corresponding memory locations agree in data type. The
difference between Levels 1 and 2 is that Level 2 warns if the blocks
are not equal in total length, while Level 1 does not. Level 0
suppresses all checking. Default = 3.
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 Forchek to report whether any subprograms invoked by the
program are never defined, or are multiply defined. Ordinarily, if
Forchek 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. Forchek does not report on the use of lowercase
letters. Default=no.
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,
Forchek 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, Forchek 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 Forchek 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 Forchek 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.
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 Forchek 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, Forchek will still
print out any line containing an error, to aid the user in
determining where the error occurred. Default = no.
3 /novice=n
This setting controls certain messages about conditions which are
likely to be errors for novice programmers, but which are often
intentional by more sophisticated programmers. Some of these
warnings deal with cases in which Forchek suspects that what appears
to be a function is intended to be an array, which the user forgot to
declare in a DIMENSION statement. Since a function invocation and an
array reference are identical in syntax, undeclared arrays are
interpreted by the Fortran compiler and by Forchek as functions.
Novice users are often confused by the messages which result.
Forchek attempts to remedy this confusion. Default level = 1.
The novice levels are given below. The warning corresponding to
each number will be suppressed if the novice level is set to greater
than that value.
1. Warn if arrays passed as arguments to a subprogram do not
match the corresponding dummy arguments in both number of
dimensions and size. Exception: if the declared size of
the dummy array is 1 or if it is dimensioned with a dummy
variable, only the number of dimensions will be checked.
2. Warn the user if any argument of a subprogram appears to
be a function. This warning is suppressed if the dummy
argument is declared in an EXTERNAL statement. Novice
programmers seldom pass functions as arguments of a
subprogram, so it is more likely that such an argument was
intended to be an array, but was not dimensioned.
3. If a function was invoked but never defined, advise the
user that it may be an array which was not dimensioned.
This warning is suppressed if the function is declared in
an EXTERNAL or INTRINSIC statement in any module of the
program. This warning is completely suppressed by the
/noextern option.
4. Warn if a function has side effects: i.e. if it
modifies any of its arguments, or modifies a variable in
common. Ideally, a function has no side effects, and acts
only by computing a value based on its arguments, whereas
a subroutine normally acts through side effects. Advanced
programmers sometimes wish to combine the features of a
subroutine and a function in a single module.
3 /output=filename
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
Forchek 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
Forchek 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 /project
Forchek 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 forchek.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 Forchek
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 Forchek 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.
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. Thus project files contain only information 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.
Naturally, when the /project flag is set, Forchek will not read
project files as input.
3 /sixchar
One of the goals of the Forchek 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 /usage
This switch is on by default. It causes Forchek to list all
variables which may be used before they are initialized, or which are
given a value but never subsequently used, or which are declared but
never used. Sometimes Forchek makes a mistake about this. Usually
it errs on the side of giving a warning where no problem exists, but
in rare cases it will fail to warn where the problem does exist. See
the section on bugs for examples. If variables are equivalenced, the
rule used by Forchek is that a reference to any variable implies the
same reference to all variables it is equivalenced to. Default =
yes.
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
Forchek includes a mechanism for changing the default values of
all options by defining environment variables. When Forchek starts
up, it looks in its environment for any variables whose names are
composed by prefixing the string "FORCHEK_" onto the uppercased
version of the option name (the quote marks are not part of the
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" (again, the quotes
are not part of the value). 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 Forchek print a source listing by default, set the
environment variable "FORCHEK_LIST" to "1" or "YES" or anything other
than "0" or "NO". The names "FORCHEK_LIS" (not the full option name)
or "forchek_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 FORCHEK_LIST 1