FTNCHEK 2.9

Section: Misc. Reference Manual Pages (1L)
Updated: 4 Apr 1996
Index Return to Main Contents

NAME

ftnchek - Fortran 77 program checker

SYNOPSIS

ftnchek [ -arguments[=num] ] [ -array[=num] ]
      [ -calltree[=num] ] [ -[no]check ] [ -columns[=num] ]
      [ -common[=num] ] [ -[no]crossref ] [ -[no]declare ]
      [ -[no]division ] [ -[no]extern ] [ -[no]f77[=str] ]
      [ -[no]help ] [ -include=str ] [ -intrinsic[=num] ]
      [ -[no]library ] [ -[no]list ] [ -makedcls[=num] ]
      [ -[no]novice ] [ -output=str ]
      [ -[no]portability[=str] ] [ -[no]pretty[=str] ]
      [ -[no]project ] [ -[no]pure ] [ -[no]quiet ]
      [ -[no]reference ] [ -[no]resources ]
      [ -[no]sixchar ] [ -[no]sort ] [ -source[=num] ]
      [ -[no]symtab ] [ -[no]truncation[=str] ]
      [ -usage[=num] ] [ -[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 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.

This document first summarizes how to invoke ftnchek. That section should be read before beginning to use ftnchek. Later sections describe ftnchek's options in more detail, give an example of its use, and explain how to interpret the output. The final sections mention the limitations and known bugs in ftnchek.

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. (On VAX/VMS or MS-DOS systems you may use either '/' or '-'.) 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' 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 characters 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 setting assignments; however, we show only the equals sign form below.

The switches and settings which ftnchek currently recognizes are:

-arguments=num: Set level of strictness in checking subprogram arguments. Min is 0 (no checking). Max is 3 (most checking). Default = turn-on = 3.
-array=num: Set level of strictness in checking array arguments of subprograms. Min is 0 (least strict). Max is 3 (most strict). Default = turn-on = 3.
-calltree=num: Produce subprogram call hierarchy in one of 3 formats. Default = 0, no tree. Turn-on = 1, call-tree format. Other values are 2, who-calls-who and 3, VCG.
-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=num: Set level of strictness in checking COMMON blocks. Min is 0 (no checking). Max is 3 (must be identical). Default = turn-on = 3.
-crossref: Print cross-reference list of subprogram calls and COMMON block use. Default = no.
-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.
-extern: Warn if external subprograms which are invoked are never defined. Default = yes.
-f77=list: Control specific warnings about supported extensions to the Fortran 77 Standard. Default = none.
-help: Print command summary. Default = no.
-include=path: Define a directory to search for INCLUDE files. Cumulative.
-intrinsic=num: Control treatment of nonstandard intrinsic functions. Three digits. Max = 223. Default = turn-on = 222 for Unix version, 223 for VMS version, 221 for others.
-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=num: Prepare a file of declarations. Min is 0 (no declaration file). Max is 1023. Default = 0, turn-on = 1.
-novice: Give output suitable for novice users. Default = yes.
-output=filename: Send output to the given file. Default is to send output to the screen. (Default filename extension is .lis).
-portability=list: Warn about non-portable usages. Default = none.
-pretty=list: Give warnings for possibly misleading appearance of source code. Default = all.
-project: 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=num: Select source formatting options. Sum of 1 for DEC Fortran tab-formatted lines, 2 for VMS-style INCLUDE statement, and 4 for UNIX-style backslash escape sequences. Default = 0. Turn-on = max = 7.
-symtab: Print symbol table for each subprogram. Default = no.
-truncation=list: Check for possible loss of accuracy by truncation. Default = all.
-usage=num: Control warnings about unused variables, etc. Three digits: 1st digit = subprograms, 2nd digit = common, 3rd digit = local variables. For each digit: min is 0 (no checking). Max is 3 (most checking). Default = turn-on = 333.
-vcg: Produce VCG format of call graph.
-version: Print version number. Default = no.
-volatile: Assume COMMON blocks lose definition between activations. Default = no.
-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 warnings 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 warnings, namely -f77, -pretty, -portability, and -truncation, the list consists of keywords separated by commas or colons. The list can be omitted, having the effect of turning on all the corresponding warnings. Also, if the list is omitted, the setting name can be prefixed with no to turn off all the warnings 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 warning 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 warnings. This turns on all warnings controlled by the setting.
none: Clear all warnings. This turns off all warnings controlled by the setting.

These special keywords must be given in full. For all other warning keywords, only as many letters of the keyword as are necessary to identify it unambiguously need be given. Including a keyword in the list turns its warnings on. For example, -f77=intrinsic would turn on only the warnings about use of nonstandard intrinsic functions. Prefixing a keyword by no- turns its warnings 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 warnings 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.

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 processor.

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

OPTIONS

This section provides a more detailed discussion of ftnchek command-line options. Options and filenames may be interspersed on a command line. Most options are positional: each option remains in effect from the point it is encountered until it is overridden by a later change. Thus for example, the listing may be suppressed for some files and not for others. Exceptions are: the -wordsize setting, which cannot be changed once processing of input files has started; the -arguments, -array, -calltree, -common, -crossref, -extern, -reference, -resource, -sort, -vcg, and -volatile options, where the action depends only on the value of the option after the processing of input files is finished; and the -include setting, which is cumulative.

The option names in the following list are in alphabetical order.

-arguments=num

Controls warnings about mismatches between actual and dummy subprogram arguments. (An actual argument is an argument passed to the subprogram by the caller; a dummy argument is an argument received by the subprogram.)

The meanings of the setting values are as follows:

0:: turn off all such warnings.
1:: warn only about different number of arguments.
2:: warn only about mismatch of data type of arguments and of function itself.
3:: all warnings.

Default = turn-on = 3.

This setting does not apply to checking invocations of intrinsic functions or statement functions.

See also: -array, -library, -usage.

-array=num

Controls the degree of strictness in checking agreement between actual and dummy subprogram arguments that are arrays. The warnings controlled by this setting 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 warn about cases that are seldom intentional (see note below).
1:: warn 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:: warn if both arguments are arrays, but they differ in number of elements.
3:: give both types of warnings.

Default = turn-on = 3.

Note: 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. No warning is ever given if the actual argument is an array element while the dummy argument is a scalar variable. Variable-dimensioned arrays and arrays dimensioned with 1 or asterisk match any number of array elements. There is no check of whether multi-dimensional arrays agree in the size of each dimension separately.

See also: -arguments, -library, -usage.

-calltree=num

Causes ftnchek to print out the call structure of the complete program. The value of num is the sum of numbers selected from the following list:

0:: do not produce any call graph.
1:: produce the call graph in tree format.
2:: produce the call graph in who-calls-who format (same as -reference switch).
3:: produce the call graph in VCG format (same as -vcg switch).
4:: do not prune repeated subtrees (applicable only for format 1).
8:: do not sort children into alphabetical order.

Only one of the formats 1, 2, or 3 may be included in the sum. If no format is specified but one of the other options is given so that the number is nonzero, call-tree format will be used.

Default = turn-on = 1. See the discussion of the -reference and -vcg flags for details about these formats.

For tree format, 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.

In the default mode, 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)''. To have the subtree printed for each occurrence of the routine, include 4 (don't-prune) in num.

Note that the call tree will be incomplete if any of the input files are project files containing more than one module 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 multiple main programs are found, the call tree of each is printed separately. If no main program is found, a report to that effect is printed out, and the call trees of any top-level non-library routines are printed. This flag only controls the printing of the call tree: ftnchek constructs the call tree in any case because it is used to determine which library modules will be cross-checked. See the discussion of the -library flag.

See also: -crossref, -library, -reference, -sort, -symtab, -vcg.

-check

This switch is provided so that errors and warning messages can be turned off when ftnchek is used for purposes other than finding bugs, such as making declarations or printing the call tree. It is positional, so after turning all checks off, selected checks can be turned back on. The effect of -nocheck is to put all switches, numeric settings, and settings controlling lists of warnings to their turn-off values, as if they had all been specified with the -no prefix. The only exceptions are -quiet, -source, -wrap and -wordsize, which are unaffected by this switch. Default = yes.

Parse errors (syntax errors due to unrecognized or malformed statements) are not suppressed by this switch, since the results may be incorrect if ftnchek has not parsed the program correctly. Note that -check as an option has no effect: this flag can only turn checking off, not turn it back on again.

-columns=num

Set maximum statement length to num 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=long-line option is in effect, a warning will be given for any lines in which characters past column 72 are processed. Turn-on = max = 132. Default = 72.

This setting does not suppress warnings about the presence of characters beyond column 72. To process code with meaningful program text beyond column 72, use this setting and be sure the -f77 long-line option is off. To process code with sequence numbers in columns 73 to 80, leave the the columns setting at the default value and use the -pretty=no-long-line flag.

-common=num

This setting varies the strictness of checking of COMMON blocks.

The different levels are:

0:: no checking.
1:: in each declaration of a given COMMON block, corresponding memory locations (words or bytes) 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.

Default = turn-on = 3.

The Fortran 77 Standard requires each named common block, but not blank common, to be the same length in all modules of the program. Level 3 provides an extra degree of checking to support a frequent programming practice.

See also: -library, -usage, -volatile.

-crossref

Specifies that a cross-reference table be printed. This table lists each subprogram followed by a list of the routines that call it. Also prints a table listing each COMMON block followed by a list of the routines that access it. Default = no.

The cross-reference listing omits library modules that are not in the call tree of the main program. The list is alphabetized. The routines listed as using a COMMON block are those in which some variables in the block are accessed, not simply those routines that declare the block. (To find out what routines declare a COMMON block but do not use it, see the -usage flag.)

See also: -calltree, -reference, -sort, -symtab, -vcg.

-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.

CHANGING THE DEFAULTS

ftnchek includes two mechanisms for changing the default values of all options: by defining environment variables or by creating a preferences file. 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 -common strictness setting) 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.

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.

Here are some examples of how to set environment variables on various systems. For simplicity, all the examples set the default -list switch to YES.

>1. UNIX, Bourne shell: >$ FTNCHEK_LIST=YES
> >$ export FTNCHEK_LIST

>2. UNIX, C shell: >% setenv FTNCHEK_LIST YES

>3. VAX/VMS: >$ DEFINE FTNCHEK_LIST YES

>4. MSDOS: >$ SET FTNCHEK_LIST=YES

After processing any environment variables, ftnchek looks for a preferences file containing options and settings. It will search in the following order, using only the first file found: (1) .ftnchekrc in the current directory, (2) ftnchek.ini in the current directory, (3) .ftnchekrc in the user's home directory, (4) ftnchek.ini in the home directory. If such a file is found, the options defined in it are used as defaults in place of the built-in defaults and overriding any defaults set in the environment..

Each option or setting in the preferences file must be on a separate line. They are given in the same form as on the command line, except without the initial dash. The preferences file can contain blank lines and comments. Comments are introduced at any point in a line by a space character (blank or tab) or the '#' character, and are terminated by the end of the line.

Command-line options override the defaults set in the environment or in the preferences file, in the same way as they override the built-in defaults.

USING PROJECT FILES

This section contains detailed information on how to use project files most effectively, and how to avoid some pitfalls.

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.

If the file contains more than one routine, there are some possible problems that can arise from creating the project file in library mode, because the calling hierarchy among routines defined within the file is lost. Also, if the routines in the file make use of COMMON blocks that are shared with routines in other files, there will not be enough information saved for the correct checking of set and used status of COMMON blocks and COMMON variables according to the -usage setting. Therefore if you plan to use project files when the -usage setting is nonzero (which is the default situation), and if multiple routines in one project file share COMMON blocks with routines in other files, the project files should be created 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. If each project file contains only one module, there is no loss of information in creating the project files in library mode.

Because of the possible 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.

Here is an example of how to use the UNIX make utility to automatically create a new project file each time the corresponding source file is altered, and to check the set of files for consistency. The example assumes that a macro OBJS has been defined which lists all the names of object files to be linked together to form the complete executable program.


    # tell make what a project file suffix is
    .SUFFIXES: .prj

    # tell make how to create a .prj file from a .f file
    .f.prj:
            ftnchek -project -noextern -library $<

    # set up macro PRJS containing project filenames
    PRJS= $(OBJS:.o=.prj)

    # "make check" will check everything that has been changed.
    check: $(PRJS)
            ftnchek $(PRJS)

AN EXAMPLE

The following simple Fortran program illustrates the messages given by ftnchek. The program is intended to accept an array of test scores and then compute the average for the series.


man2html: unable to open or read file
../average.f

The compiler gives no error messages when this program is compiled. Yet here is what happens when it is run:


$ run average
70
90
85
<EOF>
$

What happened? Why didn't the program do anything? The following is the output from ftnchek when it is used to debug the above program:



$ ftnchek -list -symtab average
man2html: unable to open or read file
../average.out

According to ftnchek, the program contains variables which may be used before they are assigned an initial value, and variables which are not needed. ftnchek also warns the user that an integer quotient has been converted to a real. This may assist the user in catching an unintended roundoff error. Since the -symtab flag was given, ftnchek prints out a table containing identifiers from the local module and their corresponding datatype and number of dimensions. Finally, ftnchek warns that the function COMPAV is not used with the proper type of arguments.

With ftnchek's help, we can debug the program. We can see that there were the following errors:

1.: SUM and COUNT should have been converted to real before doing the division.
2.: SUM should have been initialized to 0 before entering the loop.
3.: AVG was never printed out after being calculated.
4.: NUMS should have been declared INTEGER instead of REAL.

We also see that I, not J, should have been declared INTEGER in function COMPAV. Also, MAXNOS was not declared as INTEGER, nor COMPAV as REAL, in program AVENUM. These are not errors, but they may indicate carelessness. As it happened, the default type of these variables coincided with the intended type.

Here is the corrected program, and its output when run:


man2html: unable to open or read file
../correct.f

$ run average
70
90
85
<EOF>
AVERAGE =   81.66666
$

With ftnchek's help, our program is a success!

INTERPRETING THE OUTPUT

The messages given by ftnchek include not only syntax errors but also warnings and informational messages about things that are legal Fortran but that may indicate errors or carelessness. Most of these messages can be turned off by command-line options. Which option controls each message depends on the nature of the condition being warned about. See the descriptions of the command-line flags in the previous sections, and of individual messages below. Each message is prefixed with a word or phrase indicating the nature of the condition and its severity.

``Error'' means a syntax error. The simplest kind of syntax errors are typographical errors, for example unbalanced parentheses or misspelling of a keyword. This type of error is caught by the parser and appears with the description ``parse error'' or ``syntax error'' (depending on whether the parser was built using GNU bison or UNIX yacc respectively). This type of error message cannot be suppressed. Be aware that this type of error often means that ftnchek has not properly interpreted the statement where the error occurs, so that its subsequent checking operations will be compromised. You should eliminate all syntax errors before proceeding to interpret the other messages ftnchek gives.

``Warning: Nonstandard syntax'' indicates an extension to Fortran that ftnchek supports but that is not according to the Fortran 77 Standard. The extensions that ftnchek accepts are described in the section on Extensions below. One example is the DO ... ENDDO construction. If a program uses these extensions, warnings will be given according to specifications under the -f77 setting. The default behavior is to give no warnings.

``Warning'' in other cases means a condition that is suspicious but that may or may not be a programming error. Frequently these conditions are legal under the standard. Some are illegal but do not fall under the heading of syntax errors. Usage errors are one example. These refer to the possibility that a variable may be used before it has been assigned a value (generally an error), or that a variable is declared but never used (harmless but may indicate carelessness). The amount of checking for usage errors is controlled by the -usage flag, which is set for the maximum amount of checking by default.

Truncation warnings cover situations in which accuracy may be lost unintentionally, for example when a double precision value is assigned to a real variable. These warnings are controlled by the -truncation setting, which is on by default.

``Nonportable usage'' warns about some feature that may not be accepted by some compilers even though it is not contrary to the Fortran 77 Standard, or that may cause the program to perform differently on different platforms. For example, equivalencing real and integer variables is usually a non-portable practice. The use of extensions to the standard language is, of course, another source of non-portability, but this is handled as a separate case. To check a program for true portability, both the -portability and the -f77 flags should be used. They are both turned off by default. The -wordsize setting is provided to check only those nonportable usages that depend on a particular machine wordsize.

``Possibly misleading appearance'' is used for legal constructions that may not mean what they appear to mean at first glance. For example, Fortran is insensitive to blank space, so extraneous space within variable names or the lack of space between a keyword and a variable can convey the wrong impression to the reader. These messages can be suppressed by turning off the -pretty flag, which is on by default.

Other messages that are given after all the files are processed, and having to do with agreement between modules, do not use the word ``warning'' but generally fall into that category. Examples include type mismatches between corresponding variables in different COMMON block declarations, or between dummy and actual arguments of a subprogram. These warnings are controlled by the -common and -arguments settings respectively. By default both are set for maximum strictness of checking.

Another group of warnings about conditions that are often harmless refer to cases where the array properties of a variable passed as a subprogram argument differ between the two routines. For instance, an array element might be passed to a subroutine that expects a whole array. This is a commonly-used technique for processing single rows or columns of two-dimensional arrays. However, it could also indicate a programming error. The -array setting allows the user to adjust the degree of strictness to be used in checking this kind of agreement between actual and dummy array arguments. By default the strictness is maximum.

``Oops'' indicates a technical problem, meaning either a bug in ftnchek or that its resources have been exceeded.

The syntax error messages and warnings include the filename along with the line number and column number. ftnchek has two different options for the appearance of these error messages. If -novice is in effect, which is the default, the messages are in a style approximating normal English. (In default style, the filename is not printed in messages within the body of the program if -list is in effect.) The other style of error messages is selected by the -nonovice option. In this style, the appearance of the messages is similar to that of the UNIX lint program.

ftnchek is still blind to some kinds of syntax errors. The two most important ones are detailed checking of FORMAT statements, and almost anything to do with control of execution flow by means of IF, DO, and GOTO statements: namely correct nesting of control structures, matching of opening statements such as IF ... THEN with closing statements such as ENDIF, and the proper use of statement labels (numbers). Most compilers will catch these errors. See the section on Limitations for a more detailed discussion.

If ftnchek gives you a syntax error message when the compiler does not, it may be because your program contains an extension to standard Fortran which is accepted by the compiler but not by ftnchek. (See the section on Extensions.) On a VAX/VMS system, you can use the compiler option /STANDARD to cause the compiler to accept only standard Fortran. On most UNIX or UNIX-like systems, this can be accomplished by setting the flag -ansi.

Many of the messages given by ftnchek are self-explanatory. Those that need some additional explanation are listed below in alphabetical order.

Common block NAME: data type mismatch at position n

The n-th variable in the COMMON block differs in data type in two different declarations of the COMMON block. By default (-common strictness level 3), ftnchek is very picky about COMMON blocks: the variables listed in them must match exactly by data type and array dimensions. That is, the legal pair of declarations in different modules:

     COMMON /COM1/ A,B
and
     COMMON /COM1/ A(2)

will cause ftnchek to give warnings at strictness level 3. These two declarations are legal in Fortran since they both declare two real variables. At strictness level 1 or 2, no warning would be given in this example, but the warning would be given if there were a data type mismatch, for instance, if B were declared INTEGER. Controlled by -common setting.

Common block NAME has long data type following short data type

Some compilers require alignment of multi-byte items so that each item begins at an address that is a multiple of the item size. Thus if a short (e.g. single-precision real) item is followed by a long (e.g. double precision real) item, the latter may not be aligned correctly. Controlled by -portability=common-alignment option.

Common block NAME has mixed character and non-character variables

The ANSI standard requires that if any variable in a COMMON block is of type CHARACTER, then all other variables in the same COMMON block must also be of type CHARACTER. Controlled by -f77=mixed-common option.

Common block NAME: varying length

For -common setting level 2, this message means that a COMMON block is declared to have different numbers of words in two different subprograms. A word is the amount of storage occupied by one integer or real variable. For -common setting level 3, it means that the two declarations have different numbers of variables, where an array of any size is considered one variable. This is not necessarily an error, but it may indicate that a variable is missing from one of the lists. Note that according to the Fortran 77 Standard, it is an error for named COMMON blocks (but not blank COMMON) to differ in number of words in declarations in different modules. Given for -common setting 2 or 3.

Error: Badly formed logical/relational operator or constant

Error: Badly formed real constant

The syntax analyzer has found the start of one of the special words that begin and end with a period (e.g. .EQ.), or the start of a numeric constant, but did not succeed in finding a complete item of that kind.

Error: cannot be adjustable size in module NAME

A character variable cannot be declared with a size that is an asterisk in parentheses unless it is a dummy argument, a parameter, or the name of the function defined in the module.

Error: cannot be declared in SAVE statement in module NAME

Only local variables and common blocks can be declared in a SAVE statement.

Error: No path to this statement

ftnchek will detect statements which are ignored or by-passed because there is no foreseeable route to the statement. For example, an unnumbered statement (a statement without a statement label), occurring immediately after a GOTO statement, cannot possibly be executed.

Error: Parse error

This means that the parser, which analyzes the Fortran program into expressions, statements, etc., has been unable to find a valid interpretation for some portion of a statement in the program. If your compiler does not report a syntax error at the same place, the most common explanations are: (1) use of an extension to ANSI standard Fortran that is not recognized by ftnchek, or (2) the statement requires more lookahead than ftnchek uses (see section on Bugs).

NOTE: This message means that the affected statement is not interpreted. Therefore, it is possible that ftnchek's subsequent processing will be in error, if it depends on any matters affected by this statement (type declarations, etc.).

Error: Syntax error

This is the same as ``Error: Parse error'' (see above). It is generated if your version of ftnchek was built using the UNIX yacc parser generator rather than GNU bison.

Identifiers which are not unique in first six chars

Warns that two identifiers which are longer than 6 characters do not differ in the first 6 characters. This is for portability: they may not be considered distinct by some compilers. Controlled by -sixchar option.

Nonportable usage: argument precision may not be correct for intrinsic function

The precision of an argument passed to an intrinsic function may be incorrect on some computers. Issued when a numeric variable declared with explicit precision (e.g. REAL*8 X) is passed to a specific intrinsic function (e.g. DSQRT(X)). Controlled by -portability=mixed-size and -wordsize.

Nonportable usage: character constant/variable length exceeds 255

Some compilers do not support character strings more than 255 characters in length. Controlled by -portability=long-string.

Nonportable usage: File contains tabs

ftnchek expands tabs to be equivalent to spaces up to the next column which is a multiple of 8. Some compilers treat tabs differently, and also it is possible that files sent by electronic mail will have the tabs converted to blanks in some way. Therefore files containing tabs may not be compiled correctly after being transferred. ftnchek does not give this message if tabs only occur within comments or character constants. Controlled by -portability=tab.

Nonportable usage: non-integer DO loop bounds

This warning is only given when the DO index and bounds are non-integer. Use of non-integer quantities in a DO statement may cause unexpected errors, or different results on different machines, due to roundoff effects. Controlled by -portability=real-do.

Possibly it is an array which was not declared

This message is appended to warnings related to a function invocation or to an argument type mismatch, for which the possibility exists that what appears to be a function is actually meant to be an array. If the programmer forgot to dimension an array, references to the array will be interpreted as function invocations. This message will be suppressed if the name in question appears in an EXTERNAL or INTRINSIC statement. Controlled by the -novice option.

Possibly misleading appearance: characters past 72 columns

The program is being processed with the statement field width at its standard value of 72, and some nonblank characters have been found past column 72. In this case, ftnchek is not processing the characters past column 72, and is notifying the user that the statement may not have the meaning that it appears to have. These characters might be intended by the programmer to be significant, but they will be ignored by the compiler. Controlled by -pretty=long-line.

Possibly misleading appearance: Common block declared in more than one statement

Such multiple declarations are legal and have the same effect as a continuation of the original declaration of the block. This warning is only given if the two declarations are separated by one or more intervening statements. Controlled by -pretty=multiple-common.

Possibly misleading appearance: Continuation follows comment or blank line

ftnchek issues this warning message to alert the user that a continuation of a statement is interspersed with comments, making it easy to overlook. Controlled by -pretty=continuation.

Possibly misleading appearance: Extraneous parentheses

Warns about parentheses surrounding a variable by itself in an expression. When a parenthesized variable is passed as an argument to a subprogram, it is treated as an expression, not as a variable whose value can be modified by the called routine. Controlled by -pretty=parentheses.

Subprogram NAME: argument data type mismatch at position n

The subprogram's n-th actual argument (in the CALL or the usage of a function) differs in datatype or precision from the n-th dummy argument (in the SUBROUTINE or FUNCTION declaration). For instance, if the user defines a subprogram by

     SUBROUTINE SUBA(X)
     REAL X
and elsewhere invokes SUBA by
     CALL SUBA(2)

ftnchek will detect the error. The reason here is that the number 2 is integer, not real. The user should have written

     CALL SUBA(2.0)

When checking an argument which is a subprogram, ftnchek must be able to determine whether it is a function or a subroutine. The rules used by ftnchek to do this are as follows: If the subprogram, besides being passed as an actual argument, is also invoked directly elsewhere in the same module, then its type is determined by that usage. If not, then if the name of the subprogram does not appear in an explicit type declaration, it is assumed to be a subroutine; if it is explicitly typed it is taken as a function. Therefore, subroutines passed as actual arguments need only be declared by an EXTERNAL statement in the calling module, whereas functions must also be explicitly typed in order to avoid generating this error message. Controlled by -arguments setting.

Subprogram NAME: argument arrayness mismatch at position n

Similar to the preceding situation, but the subprogram dummy argument differs from the corresponding actual argument in its number of dimensions or number of elements. Controlled by -array together with -arguments settings.

Subprogram NAME: argument mismatch at position n

A character dummy argument is larger than the corresponding actual argument, or a Hollerith dummy argument is larger than the corresponding actual argument. Controlled by -arguments setting.

Subprogram NAME: argument usage mismatch

ftnchek detects a possible conflict between the way a subprogram uses an argument and the way in which the argument is supplied to the subprogram. The conflict can be one of two types, as outlined below.

Dummy arg is modified, Actual arg is const or expr A dummy argument is an argument as named in a SUBROUTINE or FUNCTION statement and used within the subprogram. An actual argument is an argument as passed to a subroutine or function by the caller. ftnchek is saying that a dummy argument is modified by the subprogram, implying that its value is changed in the calling module. The corresponding actual argument should not be a constant or expression, but rather a variable or array element which can be legitimately assigned to. Given for -usage setting (one's digit) 1 or 3.

Dummy arg used before set, Actual arg not set Here a dummy argument may be used in the subprogram before having a value assigned to it by the subprogram. The corresponding actual argument should have a value assigned to it by the caller prior to invoking the subprogram. Given for -usage setting (one's digit) 1 or 3.

These warnings are not affected by the -arguments setting.

Subprogram NAME invoked inconsistently

Here the mismatch is between the datatype of the subprogram itself as used and as defined. For instance, if the user declares

     INTEGER FUNCTION COUNT(A)
and invokes COUNT in another module as
     N = COUNT(A)

without declaring its datatype, it will default to real type, based on the first letter of its name. The calling module should have included the declaration

     INTEGER COUNT

Given for -arguments setting 2 or 3.

Subprogram NAME: varying length argument lists:

An inconsistency has been found between the number of dummy arguments (parameters) a subprogram has and the number of actual arguments given it in an invocation. ftnchek keeps track of all invocations of subprograms (CALL statements and expressions using functions) and compares them with the definitions of the subprograms elsewhere in the source code. The Fortran compiler normally does not catch this type of error. Given for -arguments setting 1 or 3.

Variable not declared. Type has been implicitly defined

When printing the symbol table for a module, ftnchek will flag with an asterisk all identifiers that are not explicitly typed and will show the datatype that was assigned through implicit typing. This provides support for users who wish to declare all variables as is required in Pascal or some other languages. This message appears only when the -symtab option is in effect. Alternatively, use the -declare flag if you want to get a list of all undeclared variables.

Variables declared but never referenced

Detects any identifiers that were declared in your program but were never used, either to be assigned a value or to have their value accessed. Variables in COMMON are excluded. Given for -usage setting (one's digit) 2 or 3.

Variables set but never used

ftnchek will notify the user when a variable has been assigned a value, but the variable is not otherwise used in the program. Usually this results from an oversight. Given for -usage setting (one's digit) 2 or 3.

Variables used before set

This message indicates that an identifier is used to compute a value prior to its initialization. Such usage may lead to an incorrect value being computed, since its initial value is not controlled. Given for -usage setting (one's digit) 1 or 3.

Variables may be used before set

Similar to used before set except that ftnchek is not able to determine its status with certainty. ftnchek assumes a variable may be used before set if the first usage of the variable occurs prior in the program text to its assignment. Given for -usage setting (one's digit) 1 or 3.

Warning: DO index is not integer

This warning is only given when the DO bounds are integer, but the DO index is not. It may indicate a failure to declare the index to be an integer. Controlled by -truncation=real-do option.

Warning: integer quotient expr converted to real

The quotient of two integers results in an integer type result, in which the fractional part is dropped. If such an integer expression involving division is later converted to a real datatype, it may be that a real type division had been intended. Controlled by -truncation=int-div-real option.

Warning: Integer quotient expr used in exponent

The quotient of two integers results in an integer type result, in which the fractional part is dropped. If such an integer expression is used as an exponent, it is quite likely that a real type division was intended. Controlled by -truncation=int-div-exponent option.

Warning: NAME not set when RETURN encountered

The way that functions in Fortran return a value is by assigning the value to the name of the function. This message indicates that the function was not assigned a value before the point where a RETURN statement was found. Therefore it is possible that the function could return an undefined value.

Warning: Nonstandard syntax: adjustable size cannot be concatenated here

The Fortran 77 Standard forbids concatenating character variables whose size is an asterisk in parentheses, except in an assignment statement. Controlled by -f77=mixed-expr.

Warning: Nonstandard syntax : significant characters past 72 columns

This warning is given under the -f77=long-line setting if the -columns setting has been used to increase the statement field width, and a statement has meaningful program text beyond column 72. Standard Fortran ignores all text in those columns, but some compilers do not. Thus the program may be treated differently by different compilers.

Warning: Nonstandard syntax : Statement out of order.

ftnchek will detect statements that are out of the sequence specified for ANSI standard Fortran 77. Table 1 illustrates the allowed sequence of statements in the Fortran language. Statements which are out of order are nonetheless interpreted by ftnchek, to prevent ``cascades'' of error messages. The sequence counter is also rolled back to prevent repetition of the error message for a block of similar statements. Controlled by the -f77=statement-order option.




--------------------------------------------------------
                  |               | implicit
                  |  parameter    |---------------------
                  |               | other specification
        format    |---------------|---------------------
         and      |               | statement-function
        entry     |  data         |---------------------
                  |               | executable
--------------------------------------------------------

                      Table 1

Warning: Possible division by zero

This message is printed out wherever division is done (except division by a constant). Use it to help locate a runtime division by zero problem. Controlled by -division option.

Warning: real truncated to intg

ftnchek has detected an assignment statement which has a real expression on the right, but an integer variable on the left. The fractional part of the real value will be lost. If you explicitly convert the real expression to integer using the INT or NINT intrinsic function, no warning will be printed. A similar message is printed if a double precision expression is assigned to a single precision variable, etc. Controlled by -truncation=demotion option.

Warning: subscript is not integer

Since array subscripts are normally integer quantities, the use of a non-integer expression here may signal an error. Controlled by -truncation=real-subscript option.

Warning: Unknown intrinsic function

This message warns the user that a name declared in an INTRINSIC statement is unknown to ftnchek. Probably it is a nonstandard intrinsic function, and so the program will not be portable. The function will be treated by ftnchek as a user-defined function. This warning is not suppressed by any option, since it affects ftnchek's analysis of the program. However, if the intrinsic function is in one of the supported sets of nonstandard intrinsics, you can use the -intrinsic setting to cause ftnchek to recognize it.

LIMITATIONS AND EXTENSIONS

ftnchek accepts ANSI standard Fortran-77 programs with some minor limitations and numerous common extensions.

Limitations:

ftnchek uses only one line of lookahead when analyzing a program into its basic syntactic elements. If a particular statement is difficult to identify, it may be handled improperly if the ambiguity is not resolved on a single line. This limitation applies to complex constants except in DATA statements, and to situations in which a variable name might be confused with a keyword. For example, if the variable name WRITE is used for an array, then a very long statement assigning a value to some element of this array could be mistaken as a WRITE statement if the equals sign is not on the same line as the word WRITE.

The dummy arguments in statement functions are treated like ordinary variables of the program. That is, their scope is the entire module, not just the statement function definition.

The checking of FORMAT statements is lax, tolerating missing separators (comma, etc.) between format descriptors in places where the Standard requires them, and allowing .d fields on descriptors that should not have them. It does warn under -f77=format-edit-descr about nonstandard descriptor types (like O), and supported extensions.

The only checking related to control of execution flow is a warning about statements that cannot be reached because they do not have a label and they follow an unconditional transfer. There is no checking for correct nesting of DO loops or matching of opening statements such as IF ... THEN with closing statements such as ENDIF, nor the proper definition and use of statement labels. Fortunately, most compilers will catch these errors.

If a user-supplied subprogram has the same name as one of the nonstandard intrinsic functions recognized by ftnchek, it must be declared in an EXTERNAL statement in any routine that invokes it. Otherwise it will be subject to the checking normally given to the intrinsic function. Since the nonstandard intrinsics are not standard, this EXTERNAL statement is not required by the Fortran 77 Standard. Using the -intrinsic=0 setting, recognition of most nonstandard intrinsics (excepting only those needed to support the double complex data type) can be turned off. See the lists of supported nonstandard intrinsic functions under the discussion of the -intrinsic setting above.

Extensions:

All of these extensions (except lower-case characters) will generate warnings if the relevant -f77 option is set. Some of the extensions listed below are part of the Fortran-90 Standard. These are indicated by the notation (F90).

Tabs are permitted, and translated into equivalent blanks which correspond to tab stops every 8 columns. The standard does not recognize tabs. Note that some compilers allow tabs, but treat them differently. The treatment defined for DEC FORTRAN can be achieved using -source setting value 1.

Strings may be delimited by either quote marks or apostrophes. A sequence of two delimiter characters is interpreted as a single embedded delimiter character. (F90)

Strings may contain UNIX-style backslash escape sequences. They will be interpreted as such if the -source value 4 (backslash) is given. Otherwise the backslash character will be treated as a normal printing character.

Lower case characters are permitted, and are converted internally to uppercase except in character strings. The standard specifies upper case only, except in comments and strings. (F90)

Hollerith constants are permitted, in accordance with the Fortran 77 Standard, appendix C. They should not be used in expressions, or confused with datatype CHARACTER.

The letter 'D' (upper or lower case) in column 1 is treated as the beginning of a comment. There is no option to treat such lines as statements instead of comments.

Statements may be longer than 72 columns provided that the setting -column was used to increase the limit. According to the standard, all text from columns 73 through 80 is ignored, and no line may be longer than 80 columns.

Variable names may be longer than six characters. The standard specifies six as the maximum. ftnchek permits names up to 31 characters long (F90).

Variable names may contain underscores and dollar signs, which are treated the same as alphabetic letters. The default type for variables beginning with these characters is REAL. In IMPLICIT type statements specifying a range of characters, the dollar sign follows Z and is followed by underscore. Fortran 90 permits underscores in variable names.

The UNIX version tolerates the presence of preprocessor directives, namely lines beginning with the pound sign (#). These are treated as comments, except for #line directives, which are interpreted, and are used to set the line number and source file name for warnings and error messages. Note that #include directives are not processed by ftnchek. Programs that use them for including source files should be passed through the preprocessor before being input to ftnchek. As noted below, ftnchek does process INCLUDE statements, which have a different syntax.

The DO ... ENDDO control structure is permitted. The syntax which is recognized is according to either of the following two forms: DO [label [,]] var = expr , expr [, expr]

...
END DO or DO [label [,]] WHILE ( expr )

...
END DO where square brackets indicate optional elements. This is a subset of the Fortran 90 do-loop syntax.

The ACCEPT and TYPE statements (for terminal I/O) are permitted, with the same syntax as PRINT.

The so-called ``Cray pointer'' syntax is tolerated. It is not the same as the Fortran 90 POINTER statement. There is no real checking of the statement other than basic syntax. The form of this statement is POINTER (pointer, pointee) [,(pointer, pointee)] The pointer variables are assigned a data type of INTEGER *4. Usage checking of the pointee variables is suppressed, since in practice they are accessed indirectly via the pointers.

Statements may have any number of continuation lines. The standard allows a maximum of 19.

Inline comments, beginning with an exclamation mark, are permitted. (F90)

NAMELIST I/O is supported. The syntax is the same as in Fortran 90.

FORMAT statements can contain a dollar sign to indicate suppression of carriage-return. An integer expression enclosed in angle brackets can be used anywhere in a FORMAT statement where the Fortran 77 Standard allows an integer constant (except for the length of a Hollerith constant), to provide a run-time value for a repeat specification or field width.

Nonstandard keywords are allowed in I/O statements, corresponding to those in VMS Fortran.

The IMPLICIT NONE statement is supported. The meaning of this statement is that all variables must have their data types explicitly declared. Rather than flag the occurrences of such variables with syntax error messages, ftnchek waits till the end of the module, and then prints out a list of all undeclared variables, as it does for the -declare option. (F90)

Data types INTEGER, REAL, COMPLEX, and LOGICAL are allowed to have an optional precision specification in type declarations. For instance, REAL*8 means an 8-byte floating point data type. The REAL*8 datatype is not necessarily considered equivalent to DOUBLE PRECISION, depending on the -wordsize setting. The Fortran 77 Standard allows a length specification only for CHARACTER data.

ftnchek supports the DOUBLE COMPLEX type specification for a complex quantity whose real and imaginary parts are double precision. Mixed-mode arithmetic involving single-precision complex with double-precision real data, prohibited under the Standard, yields a double complex result.

Many commonly found nonstandard intrinsic functions are provided. See the discussion of -intrinsic for a list of functions and how to control which ones are recognized..

Argument checking is not tight for those nonstandard intrinsics that take arrays or mixed argument types.

ftnchek permits the INCLUDE statement, which causes inclusion of the text of the given file. The syntax is INCLUDE 'filename'

This is compatible with Fortran 90. If the -source setting value 2 is given, ftnchek follows VMS conventions with respect to this statement: it assumes a default extension of .for if no filename extension is given, and allows the qualifier /[NO]LIST following the filename, to control the listing of the included file. There is no support for including VMS text modules.

In diagnostic output relating to items contained in include files, the location of the error is specified by both its location in the include file and the location in the parent file where the file was included.

ftnchek accepts PARAMETER definitions that involve intrinsic functions and exponentiation by a non-integer exponent. Both of these cases are prohibited by the Fortran 77 Standard, and will be warned about if the -f77=param-intrinsic flag is given. If an intrinsic function value is a compile-time integer constant, ftnchek will evaluate it. This allows better checking if the parameter is used in declaring array sizes. Fortran 90 allows intrinsic functions in PARAMETER definitions.

The intrinsic functions that are evaluated are:

    ABS       IABS      DIM       IDIM      MAX
    MAX0      MIN       MIN0      MOD       SIGN
    ISIGN     LEN       ICHAR     INDEX

The functions of integer arguments are evaluated only if the arguments are integer constant expressions. (These may involve integer constants, parameters, and evaluated intrinsic functions.) The function LEN is evaluated if its argument is an expression involving only character constants and variables whose length is not adjustable. The functions ICHAR and INDEX are evaluated only if the arguments are character constants. ftnchek gives a warning if it needs the value of some intrinsic function that is not evaluated.

NEW FEATURES

Here are the changes from Version 2.8 to Version 2.9:

1.: The -usage flag is now a 3-digit number, for separate control of checking of subprograms, common variables, and local variables.
2.: New command-line options: -nocheck, -intrinsic, -source, -version . Changed -f77, -portability, -pretty and -truncation from switches to string settings that allow detailed control of warnings. Eliminated -backslash, -hollerith and -tab switches which are now handled by -source and -portability settings. Changed name of -noverbose option to -quiet.
3.: Ftnchek now reads a startup file named .ftnchekrc or ftnchek.ini located in the current directory or in the home directory.
4.: Added a new -makedcls value: 512=no-array-dimensions.
5.: Command-line numeric settings can omit the number, giving them default turn-on values.
6.: The -calltree option now takes various numeric settings to specify options for the form of the output.
7.: The non-parenthesis PARAMETER statement variant, and the Cray POINTER statement are now part of the distribution, i.e. no longer as patches accompanying the source.
8.: Two new warnings: common block and subprogram having the same name, controlled by the -f77 flag; and statement function defined but not used, controlled by the -usage setting.
9.: The support for VCG output has been improved so that ftnchek now sends output to a file that is suitable for direct input to xvcg. The script fcl2vcg is now obsolete. Support for VCG is now standard.
10.: Various minor bugs were fixed, and some improvements were made to help in maintaining and distributing the program: the source code has been augmented with function prototypes, and a configure script is used to handle variations among systems automatically.
11.: Support for VMS I/O keywords is now standard. Previously it was only enabled in VMS version.
12.: Recognition of nonstandard intrinsic functions is now controlled by command-line option -intrinsic. Previously the choice was set when building ftnchek.
13.: Support for quad precision constants (such as 1.23Q4) and intrinsic functions was added.

Here are the changes from Version 2.7 to Version 2.8:

1.: Improvements in handling command-line settings: add support for colon as assignment operator, and extend setting switch support to include a default value to replace out-of-range values, instead of just choosing the nearer endpoint of the valid range.
2.: New options: -makedcls=num to generate variable declarations; -backslash to handle UNIX-style backslash escapes in character strings; -resource to print out internal resource usage; -tab to accept DEC-style tab-formatted source.
3.: New extensions to syntax: Accept quote marks as an alternative to apostrophes for delimiting strings. Accept 'D' as equivalent to 'C' in column 1 for comments. A patch is supplied to allow ``Cray pointer'' syntax to be tolerated. (This patch does not include checking proper use of pointers.)
4.: Provide variable names and not just position numbers in warnings about mismatches in common block declarations and subprogram argument lists.
5.: Add installation validation suite to check for correct functioning after a new installation, or a new compilation with a different compiler or compiler options. The validation suite also serves to record input cases that exhibited bugs in older versions of the program, providing regression testing to ensure that changes do not introduce new bugs, or restore old ones. This test suite uncovered compiler optimizer errors on at least one system, errors which did not appear in older versions of ftnchek.
6.: Improve memory management to avoid running out of space.
7.: Update the UNIX Makefile with new targets following the Free Software Foundation standards, and create the CHECKLIST file to record systems for which this version of ftnchek has been successfully built and has passed the validation suite tests.
8.: Add the man2ps script, and a target in the UNIX Makefile to use it for converting the manual pages file to PostScript.
9.: Correct several small typographical irregularities in these manual pages. troff preserves all input spaces, so great care is needed in preparing troff input to avoid introducing spurious space into the typeset output.

Grateful acknowledgement is given to Nelson H. F. Beebe of the University of Utah for providing most of these improvements, and especially for writing most of the new code to produce variable declarations, which represents a very substantial effort.

BUGS

ftnchek still has much room for improvement. Your feedback is appreciated. We want to know about any bugs you notice. Bugs include not only cases in which ftnchek issues an error message where no error exists, but also if ftnchek fails to issue a warning when it ought to. Note, however, that ftnchek is not intended to catch all syntax errors (see section on Limitations). Also, it is not considered a bug for a variable to be reported as used before set, if the reason is that the usage of the variable occurs prior in the text to where the variable is set. For instance, this could occur when a GOTO causes execution to loop backward to some previously skipped statements. ftnchek does not analyze the program flow, but assumes that statements occurring earlier in the text are executed before the following ones.

We especially want to know if ftnchek crashes for any reason. It is not supposed to crash, even on programs with syntax errors. Suggestions are welcomed for additional features which you would find useful. Tell us if any of ftnchek's messages are incomprehensible. Comments on the readability and accuracy of this document are also welcome.

You may also suggest support for additional extensions to the Fortran language. These will be included only if it is felt that the extensions are sufficiently widely accepted by compilers.

If you find a bug in ftnchek, first consult the list of known bugs below to see if it has already been reported. Also check the section entitled ``Limitations and Extensions'' above for restrictions that could be causing the problem. If you do not find the problem documented in either place, then send a report including

1.: The operating system and CPU type on which ftnchek is running.
2.: The version of ftnchek and values of any environment options or settings defined in startup file. (Capturing the output of ftnchek -help is useful for this.)
3.: A brief description of the bug.
4.: If possible, a small sample program showing the bug.

The report should be sent to the following address: moniot@mary.fordham.edu

Highest priority will be given to bugs which cause ftnchek to crash.

Certain problems that arise when checking large programs can be fixed by increasing the sizes of the data areas in ftnchek. (These problems are generally signaled by error messages beginning with ``Oops''.) The simplest way to increase the table sizes is by recompiling ftnchek with the LARGE_MACHINE macro name defined. Consult the makefile and README file for the method of doing this.

The following is a list of known bugs.

1.

Bug: Used-before-set message is suppressed for any variable which is used as the loop index in an implied-do loop, even if it was in fact used before being set in some earlier statement. For example, consider J in the statement

      WRITE(5,*) (A(J), J=1,10)

Here ftnchek parses the I/O expression, A(J), where J is used, before it parses the implied loop where J is set. Normally this would cause ftnchek to report a spurious used-before-set warning for J. Since this report is usually in error and occurs fairly commonly, ftnchek suppresses the warning for J altogether.

Prognosis: A future version of ftnchek is planned which will handle implied-do loops correctly.

2.

Bug: Variables used (not as arguments) in statement-function subprograms do not have their usage status updated when the statement function is invoked.

Prognosis: To be fixed in a future version of ftnchek.

3.

Bug: VAX version does not expand wildcards in filenames on the command line if they are followed without space by an option, e.g. ftnchek *.f/calltree would not expand the *.f. This is because VMS-style options without intervening space are not supported by the GNU shell_mung routine that is used to expand wildcards.

Prognosis: unlikely to be fixed.

ACKNOWLEDGEMENTS

ftnchek is a public-domain program. It was designed by Dr. Robert Moniot, professor at Fordham University. During the academic year of 1988-1989, Michael Myers and Lucia Spagnuolo developed the program to perform the variable usage checks. During the following year it was augmented by Lois Bigbie to check subprogram arguments and COMMON block declarations. Brian Downing assisted with the implementation of the INCLUDE statement. John Quinn wrote the common block usage checks. Nelson H. F. Beebe of the University of Utah added most of the new code to implement the -makedcls feature. The -reference feature was contributed by Gerome Emmanuel, Ecole des mines, U. Nancy (slightly modified). The support for Cray pointer syntax was provided by John Dannenhoffer of United Technologies Research Center. Additional features will be added as time permits. With Version 2.5, the name was changed from forchek to ftnchek, to avoid confusion with a similar program named forcheck, developed earlier at Leiden University.

We would like to thank John Amor of the University of British Columbia, Reg Clemens of the Air Force Phillips Lab in Albuquerque, Markus Draxler of the University of Stuttgart, Victor Eijkhout of the University of Tennessee at Knoxville, Greg Flint of Purdue University, Daniel P. Giesy of NASA Langley Research Center, Fritz Keinert of Iowa State University, Judah Milgram of the University of Maryland College Park, Hugh Nicholas of the Pittsburgh Supercomputing Center, Dan Severance of Yale University, Phil Sterne of Lawrence Livermore National Laboratory, Larry Weissman of the University of Washington, Warren J. Wiscombe of NASA Goddard, and especially Nelson H. F. Beebe of the University of Utah, for pointing out bugs and suggesting some improvements. We also thank Jack Dongarra for putting ftnchek into the netlib library of publicly available software.

INSTALLATION AND SUPPORT

The ftnchek program can be obtained by anonymous ftp from many software servers, including host netlib.org (128.169.92.17) where it is located in directory /fortran. You should download it in binary mode. 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.dsm.fordham.edu (150.108.64.2), located in directory /pub/ftnchek2.9. Assistance in preparing such executable binary forms is welcome.

The nroff version of this document is named ftnchek.man. On UNIX systems, this file can be used as the man page, but actually it is a multi-purpose source file which is used to produce the other forms of the documentation. The cleaned-up man page document, created during installation of ftnchek, is named ftnchek.1. You can print it using the command

      nroff -man ftnchek.1 | lpr.

The distribution also includes a plain ASCII version named ftnchek.doc, a PostScript version named ftnchek.ps, and a VMS HELP version named ftnchek.hlp.

Information about the latest version and the status of the project can be obtained by the Internet command ``finger ftnchek@mary.fordham.edu''. For further information and to report bugs, you may contact Dr. Robert Moniot at the following network address:

moniot@mary.fordham.edu

This document was created by man2html, using the manual pages.
Time: 00:00:45 GMT, February 16, 2023

FTNCHEK 2.9

NAME

SYNOPSIS

DESCRIPTION

INVOKING FTNCHEK

OPTIONS

CHANGING THE DEFAULTS

USING PROJECT FILES

AN EXAMPLE

INTERPRETING THE OUTPUT

LIMITATIONS AND EXTENSIONS

NEW FEATURES

BUGS

ACKNOWLEDGEMENTS

INSTALLATION AND SUPPORT

SEE ALSO

Index