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.
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:
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:
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.
The option names in the following list are in alphabetical order.
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.
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.
- 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.
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.
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.
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.
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.
See also: -sixchar, -usage.
See also: -portability, -truncation.
The -extern flag is now superseded by the Level 1 usage checking of subprograms. For the sake of compatibility with earlier versions of ftnchek, the -extern flag is retained, so that -noextern is equivalent to a 0 or 2 in the hundreds place of the -usage setting. However, to avoid anomalous behavior, you should not use both -extern and -usage on the command line. Probably the -extern switch will be retired eventually.
See also: -library.
This setting provides detailed control over the warnings about supported extensions to the Fortran 77 Standard. The list consists of keywords separated by commas or colons. There are three special keywords: all to turn on all the warnings about nonstandard extensions, none to turn them all off, and help to print the list of all the keywords with a brief explanation of each. If list is omitted, -f77 is equivalent to -f77=all, and -nof77 is equivalent to -f77=none. The warning keywords with their meanings are as follows. (Further details about the extensions themselves are given below in the section on Extensions.)
- accept-type:
- ACCEPT and TYPE I/O statements.
- backslash:
- Unix backslash escape in strings. This warning will be given only if the -source setting value 4 (UNIX backslash) is specified to cause the escape interpretation of backslash..
- byte:
- BYTE data type declaration.
- common-subprog-name:
- Common block and subprogram having the same name.
- continuation:
- More than 19 successive continuation lines.
- cpp:
- Unix C preprocessor directives in the source code.
- d-comment:
- Debugging comments starting with D in the source code.
- dec-tab:
- DEC Fortran style tab-formatted source code. This warning will be given only if the -source setting value 1 is specified to cause interpretation of tabs in this style.
- do-enddo:
- DO loop extensions: terminal statement label omitted, END DO, and WHILE.
- double-complex:
- Double precision complex datatype.
- format-dollarsign:
- Dollar sign control code in FORMAT statements.
- format-edit-descr:
- Nonstandard edit descriptors in FORMAT statements.
- function-noparen:
- Function definition without parentheses.
- implicit-none:
- IMPLICIT NONE statement.
- include:
- INCLUDE statement.
- inline-comment:
- Inline comments starting with an exclamation point.
- internal-list-io:
- List-directed I/O to or from an internal file.
- intrinsic:
- Nonstandard intrinsic functions.
- long-line:
- Statements with meaningful code past 72 columns. This warning is given only if the -columns setting has been used to increase the statement field width.
- long-name:
- Identifiers over 6 characters long.
- mixed-common:
- Mixed character and noncharacter data in COMMON block.
- mixed-expr:
- Nonstandard type combinations in expressions, for example DOUBLE PRECISION with COMPLEX, assigning hollerith to integer, logical operations on integers.
- name-dollarsign:
- Dollar sign used as a character in identifiers.
- name-underscore:
- Underscore used as a character in identifiers.
- namelist:
- NAMELIST statement.
- param-intrinsic:
- Intrinsic function or exponentiation by a real used to define the value of a PARAMETER definition.
- param-noparen:
- PARAMETER statement without parentheses.
- pointer:
- ``Cray pointer'' syntax.
- quotemark:
- Strings delimited by quote marks rather than apostrophes.
- typeless-constant:
- Typeless constants, for example Z'19AF.
- type-size:
- Type declarations specifying a size, for example REAL*8.
- variable-format:
- Variable repeat specification or field size in FORMAT. These are of the form < expr >.
- vms-io:
- The following VMS Fortran keywords used in I/O statements:
NAME (in OPEN; it is standard only in INQUIRE) BLOCKSIZE EXTENDSIZE READONLY BUFFERCOUNT INITIALSIZE RECORDSIZE CARRIAGECONTROL MAXREC RECORDTYPE DEFAULTFILE NOSPANBLOCK SHARED DISP ORGANIZATION TYPE DISPOSE
See also: -portability, -pretty, -wordsize.
The help listing also prints the version number and patch level of ftnchek and a copyright notice.
Note: the ``default'' values printed in square brackets in the help listing are, strictly speaking, not the built-in defaults but the current values after any environment options and any command-line options preceding the -help option have been processed.
See also: -version, -f77=help, -portability=help, -pretty=help, -truncation=help.
CDABS CDSQRT DREAL ZLOG
CDCOS DCMPLX IMAG ZSIN
CDEXP DCONJG ZABS ZSQRT
CDLOG DIMAG ZEXP ZCOS
CDSIN
Set 1 includes set 0 as well as the following commonly available
intrinsics (all except EXIT and LOC are defined in
MIL-STD 1753):
BTEST IBCLR IEOR ISHFTC
EXIT IBITS IOR LOC
IAND IBSET ISHFT NOT
Set 2 includes set 1, plus these common Unix intrinsic functions:
ABORT GMTIME LTIME SRAND
AND IARGC OR SYSTEM
GETARG IRAND RAND TIME
GETENV LSHIFT RSHIFT XOR
Set 3 includes set 1, plus these common VMS functions:
DATE IDATE SECNDS TIME
ERRSNS RAN SIZEOF
The tens digit of this setting controls the syntax of the RAND
intrinsic function. Specify 0 to require invocation with no argument,
1 to require one argument, and 2 to allow either form. The hundreds
digits controls the syntax of the IARGC function in the same
way.
Note that this setting does not control whether non-standard warnings are issued about these functions. It controls whether the functions are assumed to be intrinsic or not, which determines how their usage is checked. When functions in any of these sets are included, their invocations will be checked according to the rules for the intrinsic functions; otherwise they will be checked as normal (user-written) external functions. The non-standard warnings are controlled by the -f77=intrinsic option.
Default setting = turn-on = 222 for the Unix version, 223 for the VMS version, and 221 for all other versions of ftnchek. Turn-off = 0.
This switch also controls which subprogram calls and COMMON block declarations are checked. If a file is read with the -library flag in effect, the subprogram calls and COMMON declarations contained in a routine in that file will be checked only if that routine is in the main program's call tree. On the other hand, if the -library switch is turned off, then ftnchek checks the calls of every routine by every other routine, regardless of whether those routines could ever actually be invoked at run time, and likewise all COMMON block declarations are compared for agreement.
The difference between this switch and the -usage level 2 setting for subprograms is that the latter suppresses only the warning about routines being declared but not used. The -library switch goes further and excludes unused routines processed while it is in effect from all cross-checking of arguments and COMMON block declarations as well.
(If there is no main program anywhere in the set of files that ftnchek has read, so that there is no call tree, then ftnchek will look for any non-library routines that are not called by any other routine, and use these as substitutes for the main program in constructing the call tree and deciding what to check. If no such top-level non-library routines are found, then all inter-module calls and all COMMON declarations will be checked.)
See also: -arguments, -calltree, -common, -extern, -usage.
See also: -symtab, -quiet.
If input comes from standard input, instead of a named file, then declarations are written to standard output.
Variables are declared in alphabetical order within each declaration class and type, with integer variables first, because of their later possible use in array dimensions.
PARAMETER statements are an exception to the alphabetical order rule, because the Fortran 77 Standard requires that the expressions defining parameter values refer only to constants and already-defined parameter names. This forces the original source file order of such statements to be preserved in the declaration files.
Explicit declaration of all variables is considered good modern programming practice. By using compiler options to reject undeclared variables, misspelled variable names (or names extending past column 72) can be caught at compile time. Explicit declarations also greatly facilitate changing floating-point precision with filters such as dtoq(1L), dtos(1L), fd2s(1L), fs2d(1L), qtod(1L), and stod(1L). These programs are capable of changing types of explicit floating-point type declarations, intrinsic functions, and constants, but because they do not carry out rigorous lexical and grammatical analysis of the Fortran source code, they cannot provide modified type declarations for undeclared variables. Default setting = 0, turn-on = 1.
The setting values are given by the sum of selected option values from the following list:
- 0:
- Do not write a declaration file.
- 1:
- Write a declaration file.
- 2:
- Normally, all variables are included in the declaration file. With this option, include only undeclared variables. This setting is useful if you want to check for undeclared variables, since Fortran source files with all variables properly declared will not result in a .dcl file. With this option, common blocks and namelist lists will not be included in the declaration file, since by their nature they cannot be undeclared.
- 4:
- The declarations are normally prettyprinted to line up neatly in common columns, as in the declaration files output by the Extended PFORT Verifier, pfort(1L). This option value selects instead compact output, without column alignment.
- 8:
- Causes continuation lines to be used where permissible. The default is to begin a new declaration on each line. This option is appropriate to use with the option for compact output.
- 16:
- Output Fortran keywords in lowercase, instead of the default uppercase.
- 32:
- Output variables and constants in lowercase, instead of the default uppercase. Character string constants are not affected by this option.
- 64:
- Omit declarations of internal integer variables produced by the SFTRAN3 preprocessor, xsf3(1L), as part of the translation of structured Fortran statements to ordinary Fortran. These variables have six-character names of the form NPRddd, NXdddd, N2dddd, and N3dddd, where d is a decimal digit. Because they are invisible in the SFTRAN3 source code, and will change if the SFTRAN3 code is modified, such variables should not be explicitly declared. Instead, they should just assume the default Fortran INTEGER data type based on their initial letter, N.
- 128:
- Use an asterisk as the comment character; the default is otherwise 'C'.
- 256:
- Use 'c' instead of 'C' or '*' as the comment character.
- 512:
- Suppress dimensioning of arrays in the generated declarations. This option is for use with code lacking type declarations, to allow the declaration files to be inserted without change into the code. Since the code will have dimension statements already, dimensioning the array variables in the type statements of the declaration file is redundant. This option should be used only in conjunction with option 2 = undeclared-only because otherwise any arrays that were dimensioned in a type statement will lose their dimensioning.
If any non-zero value is specified, then declaration output is selected, even if the value 1 was not included in the sum.
The declaration files contain distinctive comments that mark the start and end of declarations for each program unit, to facilitate using text editor macros for merging the declarations back into the source code.
The ftnchek distribution includes a program, dcl2inc, which processes declaration files to produce files containing declarations of all COMMON blocks, in a form suitable for use as INCLUDE files. See the dcl2inc man page for the details of its use.
- (a)
- provides an extra message to the effect that a 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).
- (b)
- modifies the form of the error messages and warnings. If the flag is turned off by -nonovice, these messages are printed in a style more resembling UNIX lint.
Default = yes.
This setting provides detailed control over the warnings about possible portability problems. The list consists of keywords separated by commas or colons. There are three special keywords: all to turn on all the warnings about nonportable usages, none to turn them all off, and help to print the list of all the keywords with a brief explanation of each. If list is omitted, -portability is equivalent to -portability=all, and -noportability is equivalent to -portability=none. The warning keywords with their meanings are as follows:
- backslash:
- Backslash character in strings. Since some compilers treat the backslash as an escape character, its presence can cause problems even though it is used in a standard-conforming way.
- common-alignment:
- COMMON block variables not in descending order of storage size. Some compilers require this ordering because of storage alignment requirements.
- hollerith:
- Hollerith constants (other than within FORMAT specifications). The Hollerith data type is a feature of Fortran IV that has been deleted in the Fortran 77 standard. It is superseded by the character data type. Storing Hollerith data in variables of a numeric or logical data type is nonportable due to differing word sizes.
- long-string:
- String constants, variables, or expressions over 255 chars long.
- mixed-equivalence:
- Variables of different data types equivalenced.
- mixed-size:
- Variables declared with default precision used with variables given explicit precision, in expressions, assignments, or as arguments. For example, if a variable declared as REAL*8 is treated as equivalent to DOUBLE PRECISION.
- real-do:
- Non-integer DO loop index and bounds. These can cause a program's results to depend on the hardware characteristics of the particular computer used.
- tab:
- Tabs in source code. Tabs are interpreted differently by different compilers. This warning will be given only once, at the end of the file.
See also: -f77, -hollerith, -pretty, -wordsize.
This setting provides detailed control over the warnings about appearance. The list consists of keywords separated by commas or colons. Since all warnings are on by default, include a keyword prefixed by no- to turn off a particular warning. There are three special keywords: all to turn on all the warnings about misleading appearances, none to turn them all off, and help to print the list of all the keywords with a brief explanation of each. If list is omitted, -pretty is equivalent to -pretty=all, and -nopretty is equivalent to -pretty=none. The warning keywords with their meanings are as follows:
- embedded-space:
- Space embedded in variable names.
- continuation:
- Continuation mark following a comment line.
- long-line:
- Lines (except comments) over 72 columns in width (beyond 72 is normally ignored by compiler).
- missing-space:
- Lack of space between variable and a preceding keyword.
- multiple-common:
- COMMON block declared in multiple statements. No warning is given if the statements are consecutive except for comment lines.
- multiple-namelist:
- NAMELIST declared in multiple statements. No warning is given if the statements are consecutive except for comment lines.
- parentheses:
- Parentheses around a variable by itself. As a subprogram argument, this makes the argument an expression, not modifiable by the subprogram.
See also: -f77, -portability.
A project file contains a summary of information from the source file, for use in checking agreement among FUNCTION, SUBROUTINE, and COMMON 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.
Naturally, when the -project flag is set, ftnchek will not read project files as input.
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.
A more detailed discussion is given in the section on Using Project Files.
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.
The reference list omits routines called by unused library modules. Thus it contains the same information as for the call-tree format, namely the hierarchy of subprogram calls, but printed in a different way. This prints out a breadth-first traversal of the call tree whereas -calltree prints out a depth-first traversal. Only one format is printed. If both -calltree and -reference flags are given, the former will take precedence.
See also: -calltree, -crossref, -library, -sort, -symtab, -vcg.
In this listing, the term ``chunk size'' is the size of the blocks of memory allocated to store the item in question, in units of the size of one item, not necessarily in bytes. When the initially allocated space is filled up, more memory is allocated in chunks of this size. The following is an explanation of the items printed:
- Source lines processed:
- Total number of lines of code, with separate totals for statement lines and comment lines. Comment lines include lines with 'C' or '*' in column 1 as well as blank lines and lines containing only an inline comment. Statement lines are all other lines, including lines that have an inline comment following some code. Continuation lines are counted as separate lines. Lines in include files are counted each time the file is included.
- Total executable statements:
- Number of statements in the program, other than specification, data, statement-function, FORMAT, ENTRY, and END statements.
- Total number of modules:
- A module is any external subprogram, including the main program, subroutines, functions, and block data units. This count is of modules defined within the source, not modules referenced. Statement functions are not included. A subprogram with multiple entry points is only counted once.
- Max identifier name chars:
- Number of characters used for storing identifier names. An identifier is a variable, subprogram, or common block name. Local names are those of local variables in a subprogram, whereas global names refer to subprogram and common block names, as well as dummy argument names and common variable names. Actual argument text (up to 15 characters for each argument) is also included here. The space used for local names is recovered at the end of each module, whereas the global space grows until the whole program is analyzed. Unfortunately, this figure may include some common block names and arguments stored more than once, although a heuristic is used that will avoid duplicates in many cases.
- Max token text chars:
- A token is the smallest syntactic unit of the FORTRAN language above the level of individual characters. For instance a token can be a variable name, a numerical constant, a quoted text string, or a punctuation character. Token text is stored while a module is being processed. For technical reasons, single-character tokens are not included in this total. Items that are not represented in the symbol table may be duplicated. The space for token text is recovered at the end of each module, so this figure represents the maximum for any one module.
- Max local symbols:
- This is the largest number of entries in the local symbol table for any module. Local symbol table entries include all variables and parameters, common block names, statement functions, external subprograms and intrinsic functions referenced by the module. Literal constants are not stored in the local symbol table.
- Max global symbols:
- This is the number of entries in the global symbol table at the end of processing. Global symbol table entries include external subprogram and common block names. Intrinsic functions and statement functions are not included.
- Max number of tokenlists:
- A token list is a sequence of tokens representing the actual or dummy argument list of a subprogram, or the list of variables in a common block or namelist. Therefore this number represents the largest sum of COMMON, CALL, NAMELIST and ENTRY statements and function invocations for any one module. The space is recovered at the end of each module.
- Max token list/tree space:
- This is the largest number of tokens in all the token lists and token trees of any one module. A token tree is formed when analyzing an expression: each operand is a leaf of the tree, and the operators are the nodes. Therefore this number is a measure of the maximum complexity of an individual module. For instance a module with many long arithmetic expressions will have a high number. Note that unlike token text described above, the number of tokens is independent of the length of the variable names or literal constants in the expressions.
- Number of subprogram invocations:
- This is the sum over all modules of the number of CALL statements and function invocations (except intrinsic functions and statement functions).
- Number of common block decls:
- This is the sum over all modules of the number of common block declarations. That is, each declaration of a block in a different module is counted separately. (The standard allows multiple declarations of a block within the same module; these are counted as only one declaration since they are equivalent to a single long declaration.)
- Number of array dim & param ptrs:
- This is the sum over all modules of the number of array dimension and parameter definition text strings saved for use by the -makedcls option. The length of the text strings is not counted. Each dimension of a multidimensional array is counted separately.
These numbers are obviously not the same when project files are used in place of the original source code. Even the numbers for global entities may be different, since some redundant information is eliminated in project files.
Use the -f77=long-names if you want to list all variables longer than six characters, not just those pairs that are the same in the first six.
See also: -f77, -portability.
See also: -calltree, -crossref, -reference, -symtab, -vcg.
- 1:
- Accept DEC-style tab-formatted source. A line beginning with an initial tab will be treated as a new statement line unless the character after the tab is a nonzero digit, in which case it is treated as a continuation line. The next column after the tab or continuation mark is taken as column 7. A warning will be given in the case where the line is a continuation, if -f77=dec-tab is in effect.
- 2:
- Accept VMS-style INCLUDE statements. These follow the normal syntax, but with the following additional features: (1) the file extension, if not given, defaults to the same as a normal source file extension; and (2) the option /LIST or /NOLIST can be appended to the include-file name, to control listing of its contents.
- 4:
- Handle UNIX-style backslash escapes in character strings. The escape sequence following the backslash will be evaluated according to the ANSI standard for strings in C: up to three digits signify an octal value, an x signifies the start of a hexadecimal constant, any of the letters a b f n r t signify special control codes, and any other character (including newline) signifies the character itself. When this source code option is in effect, a warning will be given if the -f77=backslash setting is specified.
The default behavior is to treat the backslash like any other normal character, but a warning about portability will be generated if the -portability flag is set. Because of the fact that some compilers treat the backslash in a nonstandard way, it is possible for standard-conforming programs to be non-portable if they use the backslash character in strings.
Since ftnchek does not do much with the interpreted string, it is seldom necessary to use this option. It is needed in order to avoid spurious warnings only if (a) the program being checked uses backslash to embed an apostrophe or quote mark in a string instead of using the standard mechanism of doubling the delimiter; (b) the backslash is used to escape the end-of-line in order to continue a string across multiple source lines; or (c) a PARAMETER definition uses an intrinsic string function such as LEN with such a string as argument, and that value is later used to define array dimensions, etc.
Default setting = 0, turn-on = 7.
See also: -calltree, -crossref, -list, -reference, -sort, -vcg.
This setting provides detailed control over the warnings about possible truncation errors. The list consists of keywords separated by commas or colons. Since all warnings are on by default, include a keyword prefixed by no- to turn off a particular warning. There are three special keywords: all to turn on all the warnings about truncation, none to turn them all off, and help to print the list of all the keywords with a brief explanation of each. If list is omitted, -truncation is equivalent to -truncation=all, and -notruncation is equivalent to -truncation=none. The warning keywords with their meanings are as follows:
- demotion:
- automatic conversion of a higher precision quantity to one of lower precision. This warning includes conversion of real quantities to integer, double precision to single precision real, and assignment of a longer character string to a shorter one. Also, if explicit sizes are used in type declarations, a warning is given if a longer-sized quantity is assigned to one of shorter size, e.g. if an INTEGER*4 variable is assigned to an INTEGER*2.
- int-div-exponent:
- use of the result of integer division as an exponent. This suggests that a real quotient is intended. An example would be writing X**(1/3) to evaluate the cube root of X. The correct expression is X**(1./3.).
- int-div-real:
- Conversion of an expression involving an integer division to real. This suggests that a real quotient is intended.
- int-div-zero:
- division in an integer constant expression that yields a result of zero.
- int-neg-power:
- exponentiation of an integer by a negative integer (which yields zero unless the base integer is 1 in magnitude). This suggests that a real base is intended.
- promotion:
- automatic conversion of a lower precision quantity to one of higher precision. The loss of accuracy for real variables in this process is comparable to the corresponding demotion. No warning is given for promotion of integer quantities to real since this is ordinarily exact.
- real-do-index:
- use of a non-integer DO index in a loop with integer bounds. An integer DO index with real bounds is always warned about regardless of this setting.
- real-subscript:
- use of a non-integer array subscript.
- significant-figures:
- overspecifying a single precision constant. This may indicate that a double precision constant was intended.
The warnings about promotion and demotion also apply to complex constants, considering the precision to be that of the real or imaginary part. Warnings about promotions and demotions are given only when the conversion is done automatically, e.g. in expressions of mixed precision or in an assignment statement. If intrinsic functions such as INT are used to perform the conversion, no warning is given.
See also: -portability, -wordsize.
This setting is composed of three digits. The first digit (hundreds place) controls warnings about subprograms (functions and subroutines), the second digit (tens place) warnings about common blocks and common variables,, and the third digit (ones place) warnings about local variables. Each digit controls warnings according to the following scale:
- 0:
- no warnings.
- 1:
- warn about undefined items: subprograms that are used but never defined, common block variables that are used but never set, or local variables that are (or may be) used before they are set.
- 2:
- warn about unused items: subprograms that are defined but never used (unless taken in library mode), common blocks and common variables that are unused, or local variables that are declared or set but never used.
- 3:
- give both types of warnings.
Default = turn-on = 333.
Sometimes ftnchek makes a mistake in the warnings about local variable usage. 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.
When checking for used-before-set errors involving COMMON variables, ftnchek does not do a thorough enough analysis of the calling sequence to know which routines are called before others. So warnings about this type of error will only be given for cases in which a variable is used in some routine but not set in any other routine. Checking of individual COMMON variables is done only if the -common setting is 3 (variable by variable agreement).
The Level 1 value for subprogram usage checking controls warnings about routines that are invoked by the program but 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. Set this digit to 0 or 2 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.
See also: -common, -declare, -extern, -library, -volatile.
The VCG description as created is more complex than it need be. VCG allows graphs and nested subgraphs: each subroutine is created as a subgraph nested inside its calling routines. This allows you to interactively display subgraphs or summarise them.
The -vcg option for ftnchek was written by Dr. Philip Rubini (p.rubini@cranfield.ac.uk).
xvcg is a graph visualisation tool which runs under the X windows system. It is freely available from ftp.cs.uni-sb.de. It was written by G. Sander of the University of Saarland, Germany.
See also: -help.
Many Fortran programmers assume that variables, whether local or in COMMON, are static, i.e. that once assigned a value, they retain that value permanently until assigned a different value by the program. However, in fact the Fortran 77 Standard does not require this to be the case. Local variables may become undefined between activations of a module in which they are declared. Similarly, COMMON blocks may become undefined if no module in which they are declared is active. (The technical term for entities with this behavior is ``automatic'', but ftnchek uses the word ``volatile'' since it is clearer to the nonspecialist.) Only COMMON blocks declared in a SAVE statement, or declared in the main program or in a block data subprogram remain defined as long as the program is running. Variables and COMMON blocks that can become undefined at some point are called volatile.
If the -volatile flag is turned on, ftnchek will warn you if it finds a volatile COMMON block. If, at the same time, the -usage setting is 1 or 3 (check used before set), ftnchek will try to check whether such a block can lose its defined status between activations of the modules where it is declared. ftnchek does not do a very good job of this: the rule used is to see whether the block is declared in two separated subtrees of the call tree. For instance, this would be the case if two modules, both called from the main program, shared a volatile COMMON block. A block can also become undefined between two successive calls of the same subprogram, but ftnchek is not smart enough to tell whether a subprogram can be called more than once, so this case is not checked for.
The -volatile flag does not affect the way ftnchek checks the usage of local variables.
See also: -common, -usage.
The word size value does not matter for checking standard-conforming programs that do not declare explicit precisions for non-character variables or store Hollerith data in variables. This setting also does not affect the default size of character variables, which is always 1 byte. Hollerith constants also are assumed to occupy 1 byte per character.
The word size is used to determine whether truncation occurs in assignment statements, and to catch precision mismatches in subprogram argument lists and common block lists. The exact warnings that are issued will depend on the status of other flags. Under both the -portability=mixed-size and the -nowordsize flag, any mixing of explicit with default precision objects (character expressions not included) is warned about. This applies to arithmetic expressions containing both types of objects, and to subprogram arguments and COMMON variables. Under control of the -truncation=demotion and promotion options, a warning is given for assignment of an expression to a shorter variable of the same type, or for promotion of a lower precision value to higher precision in an arithmetic expression or an assignment statement.
Giving a word size of 0, or equivalently, using -nowordsize means that no default value will be assumed. This is equivalent to specifying -portability=mixed-size. Use it to find cases of mixing default and explicit precision, for example to flag places where REAL*8 is treated as equivalent to DOUBLE PRECISION.
See also: -portability, -truncation.
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.
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)
C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO
C DATE: MAY 8, 1989
C Variables:
C SCORE -> an array of test scores
C SUM -> sum of the test scores
C COUNT -> counter of scores read in
C I -> loop counter
REAL FUNCTION COMPAV(SCORE,COUNT)
INTEGER SUM,COUNT,J,SCORE(5)
DO 30 I = 1,COUNT
SUM = SUM + SCORE(I)
30 CONTINUE
COMPAV = SUM/COUNT
END
PROGRAM AVENUM
C
C MAIN PROGRAM
C
C AUTHOR: LOIS BIGBIE
C DATE: MAY 15, 1990
C
C Variables:
C MAXNOS -> maximum number of input values
C NUMS -> an array of numbers
C COUNT -> exact number of input values
C AVG -> average returned by COMPAV
C I -> loop counter
C
PARAMETER(MAXNOS=5)
INTEGER I, COUNT
REAL NUMS(MAXNOS), AVG
COUNT = 0
DO 80 I = 1,MAXNOS
READ (5,*,END=100) NUMS(I)
COUNT = COUNT + 1
80 CONTINUE
100 AVG = COMPAV(NUMS, COUNT)
END
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
FTNCHEK Version 2.9 April 1996
File average.f:
1 C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO
2 C DATE: MAY 8, 1989
3
4 C Variables:
5 C SCORE -> an array of test scores
6 C SUM -> sum of the test scores
7 C COUNT -> counter of scores read in
8 C I -> loop counter
9
10 REAL FUNCTION COMPAV(SCORE,COUNT)
11 INTEGER SUM,COUNT,J,SCORE(5)
12
13 DO 30 I = 1,COUNT
14 SUM = SUM + SCORE(I)
15 30 CONTINUE
16 COMPAV = SUM/COUNT
^
Warning near line 16 col 20: integer quotient expr converted to real
17 END
18
Module COMPAV: func: real
Variables:
Name Type Dims Name Type Dims Name Type Dims Name Type Dims
COMPAV real COUNT intg I intg* J intg
SCORE intg 1 SUM intg
* Variable not declared. Type has been implicitly defined.
Warning: Variables declared but never referenced:
J
Warning: Variables may be used before set:
SUM
19
20 PROGRAM AVENUM
21 C
22 C MAIN PROGRAM
23 C
24 C AUTHOR: LOIS BIGBIE
25 C DATE: MAY 15, 1990
26 C
27 C Variables:
28 C MAXNOS -> maximum number of input values
29 C NUMS -> an array of numbers
30 C COUNT -> exact number of input values
31 C AVG -> average returned by COMPAV
32 C I -> loop counter
33 C
34
35 PARAMETER(MAXNOS=5)
36 INTEGER I, COUNT
37 REAL NUMS(MAXNOS), AVG
38 COUNT = 0
39 DO 80 I = 1,MAXNOS
40 READ (5,*,END=100) NUMS(I)
41 COUNT = COUNT + 1
42 80 CONTINUE
43 100 AVG = COMPAV(NUMS, COUNT)
44 END
Module AVENUM: prog
External subprograms referenced:
COMPAV: real*
Variables:
Name Type Dims Name Type Dims Name Type Dims Name Type Dims
AVG real COUNT intg I intg MAXNOS intg*
NUMS real 1
* Variable not declared. Type has been implicitly defined.
Warning: Variables set but never used:
AVG
0 syntax errors detected in file average.f
6 warnings issued in file average.f
Subprogram COMPAV: argument data type mismatch
at position 1:
Dummy arg SCORE is type intg in module COMPAV line 10 file average.f
Actual arg NUMS is type real in module AVENUM line 43 file average.f
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:
Here is the corrected program, and its output when run:
C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO
C DATE: MAY 8, 1989
C
C Variables:
C SCORE -> an array of test scores
C SUM -> sum of the test scores
C COUNT -> counter of scores read in
C I -> loop counter
C
REAL FUNCTION COMPAV(SCORE,COUNT)
INTEGER SUM,COUNT,I,SCORE(5)
C
SUM = 0
DO 30 I = 1,COUNT
SUM = SUM + SCORE(I)
30 CONTINUE
COMPAV = FLOAT(SUM)/FLOAT(COUNT)
END
C
C
PROGRAM AVENUM
C
C MAIN PROGRAM
C
C AUTHOR: LOIS BIGBIE
C DATE: MAY 15, 1990
C
C Variables:
C MAXNOS -> maximum number of input values
C NUMS -> an array of numbers
C COUNT -> exact number of input values
C AVG -> average returned by COMPAV
C I -> loop counter
C
C
INTEGER MAXNOS
PARAMETER(MAXNOS=5)
INTEGER I, NUMS(MAXNOS), COUNT
REAL AVG,COMPAV
COUNT = 0
DO 80 I = 1,MAXNOS
READ (5,*,END=100) NUMS(I)
COUNT = COUNT + 1
80 CONTINUE
100 AVG = COMPAV(NUMS, COUNT)
WRITE(6,*) 'AVERAGE =',AVG
END
$ run average
70
90
85
<EOF>
AVERAGE = 81.66666
$
With ftnchek's help, our program is a success!
``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 /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.
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.).
--------------------------------------------------------
| | implicit
| parameter |---------------------
| | other specification
format |---------------|---------------------
and | | statement-function
entry | data |---------------------
| | executable
--------------------------------------------------------
Table 1
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.
These warnings are not affected by the -arguments setting.
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.
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.
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.
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
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.
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.
Prognosis: To be fixed in a future version of ftnchek.
Prognosis: unlikely to be fixed.
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. \" The above brace is the end of the .if !\nb at section "OPTIONS"
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 ..in -5