FTNCHEK 3.3(1) | General Commands Manual | FTNCHEK 3.3(1) |
ftnchek - Fortran 77 program checker
ftnchek [ -arguments[=list] ] [ -array[=list] ] [ -[no]brief ] [ -calltree[=list] ] [ -[no]check ] [ -columns[=num] ] [ -common[=list] ] [ -[no]crossref[=list] ] [ -[no]declare ] [ -[no]division ] [ -errors[=num] ] [ -[no]extern ] [ -[no]f77[=list] ] [ -[no]f90[=list] ] [ -[no]f95[=list] ] [ -[no]help ] [ -[no]identifier-chars[=list] ] [ -include=str ] [ -intrinsic[=list] ] [ -[no]library ] [ -[no]list ] [ -makedcls[=list] ] [ -mkhtml[=list] ] [ -[no]novice ] [ -output=str ] [ -pointersize[=num] ] [ -[no]portability[=list] ] [ -[no]pretty[=list] ] [ -project[=list] ] [ -[no]pure ] [ -[no]quiet ] [ -[no]reference ] [ -[no]resources ] [ -[no]sixchar ] [ -[no]sort ] [ -source[=list] ] [ -style[=list] ] [ -[no]symtab ] [ -[no]truncation[=list] ] [ -usage[=list] ] [ -[no]vcg ] [ -[no]version ] [ -[no]volatile ] [ -wordsize[=num] ] [ -wrap[=num] ] [ files ... ]
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.
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 '-'.) For the sake of conformity with an increasingly common convention, options can also begin with '--'. 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' or '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 listed below. For each option, the default is the value used if the option is not explicitly specified, while the turn-on is the value used if the option is given without assigning it a value.
If the -mkhtml option is invoked and tree is the applied calltree option, a file named CallTree.html, will be produced depicting the tree in HTML format.
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 keywords, namely -arguments, -array, -calltree, -common, -crossref, -f77, -f90, -f95, -intrinsic, -makedcls, -mkhtml, -portability, -pretty, -project, -source, -style, -truncation, and -usage, the list consists of keywords separated by commas or colons. If the list of keywords is omitted, the effect is to set the option to its turn-on value (same as ``all'' in most cases). Also, if the list is omitted, the setting name can be prefixed with no or no- to turn off all the options it controls. For example, -f77 turns on all warnings about nonstandard constructions, while -nof77 turns them all off. Three special keywords are:
These three special keywords must be given in full. For all other keywords, only as many letters of the keyword as are necessary to identify it unambiguously need be given, or a wildcard pattern may be used. Including a keyword in the list turns the corresponding option on. For example, -f77=intrinsic would turn on only the warnings about use of nonstandard intrinsic functions. Prefixing a keyword by no- turns its option 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 options 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. Wildcard patterns contain an asterisk to stand for any string of characters. If a wildcard pattern is used, all the warnings that match it are affected. If no- is prefixed to the pattern, all the matching warnings are turned off, otherwise they are all turned on. The minimum unambiguous length rule does not apply to wildcard matching. For example, use -usage=no-*var* to turn off all warnings relating to variable usage (both local and common). (Unix users may need to quote any options containing wildcards in order to prevent the shell from attempting to expand them.) Wildcards are recognized only in lists of warning keywords, not in the top-level options themselves.
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.
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 -intrinsic, -pointersize, and -wordsize settings, which cannot be changed once processing of input files has started; the -arguments, -array, -calltree, -common, -crossref, -extern, -reference, -resources, -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.
The list consists of keywords separated by commas or colons. Since all these 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 arguments, 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, -arguments is equivalent to -arguments=all, and -noarguments is equivalent to -arguments=none. The warning keywords with their meanings are as follows:
For compatibility with previous versions of ftnchek, a numeric form of this setting is also accepted: the list is replaced by a number from 0 to 3. A value of 0 turns all the warnings off, 1 turns on only number, 2 turns on all except number, and 3 turns all the warnings on.
This setting does not apply to checking invocations of intrinsic functions or statement functions, which can only be turned off by the -nocheck option.
See also: -array, -library, -usage.
The list consists of keywords separated by commas or colons. Since all these 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 array arguments, 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, -array is equivalent to -array=all, and -noarray is equivalent to -array=none. The warning keywords with their meanings are as follows:
For compatibility with previous versions of ftnchek, a numeric form of this setting is also accepted: the list is replaced by a number from 0 to 3. A value of 0 turns all the warnings off, 1 turns on only dimensions, 2 turns on only size, and 3 turns all the warnings on.
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. These cases are seldom intentional. (To turn off even these warnings, use -arguments=no-arrayness.) 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.
See also: -quiet.
The list consists of keywords separated by commas or colons. There are two special keywords: none to turn off all the options, and help to print the list of all the keywords with a brief explanation of each. (The keyword all turns on all the options, but should not normally be used since only one format should be specified.) If list is omitted, -calltree is equivalent to -calltree=tree, and -nocalltree is equivalent to -calltree=none. By default no call graph is printed.
If the -mkhtml option is invoked and tree is the applied calltree option, a file named CallTree.html, will also be produced depicting the tree in HTML format. This file is useful as a starting point for browsing the HTML files describing each component of the program.
The keywords which control which format is used are as follows:
Only one of the formats tree, reference, or vcg may be specified.
The following keywords control options affecting the output:
See the discussion of the -reference and -vcg flags for details about these formats.
For tree format, The call graph 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, use option no-prune.
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 unless the no-sort option is given. 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.
For compatibility with previous versions of ftnchek, a numeric form of this setting is also accepted: the list is replaced by a number from 0 to 15. This number is formed from 1 for tree format, 2 for reference format, or 3 for vcg format, plus 4 for no-prune, and 8 for no-sort.
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.
There are some miscellaneous errors and warning messages that are not controlled by any other switch, and so can be turned off only by this switch. Note that using -check following -nocheck only has the effect of turning these special warnings back on, and does not restore all the checks it turned off. These warnings are:
See also: -errors.
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.
See also: -f77, -pretty.
The list consists of keywords separated by commas or colons. Since most of these 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, 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, -common is equivalent to -common=dimensions,exact,length,type, and -nocommon is equivalent to -common=none. The warning keywords with their meanings are as follows:
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 -common=volatile flag is turned on, ftnchek will warn you if it finds a volatile COMMON block. If, at the same time, the -usage=com-block-volatile option is turned on (which is the default), 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 -common=volatile flag does not affect the way ftnchek checks the usage of local variables.
For compatibility with previous versions of ftnchek, a numeric form of this setting is also accepted: the list is replaced by a number from 0 to 3. A value of 0 turns all the warnings off, 1 or greater turns on type, 2 or greater turns on length, and 3 turns on dimensions and exact also. The numeric form cannot turn on the volatile option.
See also: -library, -usage.
The list consists of keywords separated by commas or colons. The keywords with their meanings are as follows:
See also: -calltree, -reference, -sort, -symtab, -vcg.
See also: -sixchar, -usage.
See also: -portability, -truncation.
This setting does not set an overall limit on the number of error messages printed, only the number printed in any one cascade. Most types of warnings and error messages are not subject to the cascade effect and so are not affected by this setting. To turn off warnings generally, use the individual warning control options or the -nocheck option.
See also: -check.
The -extern flag is now superseded by the -usage=ext-undefined option. For the sake of convenience, the -extern flag is retained, so that -noextern is equivalent to -usage=no-ext-undefined option. The -extern switch may be retired eventually.
See also: -library.
This setting provides detailed control over the warnings about supported extensions to the Fortran 77 Standard. (Further details about the extensions themselves are given below in the section on Extensions.) 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:
ACTION | PAD | READWRITE |
ADVANCE | POSITION | SIZE |
DELIM | READ | WRITE |
EOR |
BLOCKSIZE | EXTENDSIZE | READONLY |
BUFFERCOUNT | INITIALSIZE | RECORDSIZE |
CARRIAGECONTROL | MAXREC | RECORDTYPE |
DEFAULTFILE | NAME (in OPEN) | SHARED |
DISP | NOSPANBLOCK | TYPE |
DISPOSE | ORGANIZATION |
NUM |
See also: -f90, -f95, -portability, -pretty, -style, -wordsize.
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, -f90 is equivalent to -f90=all, and -nof90 is equivalent to -f90=none.
The following keywords have identical meanings for -f90 as for -f77. The reader is referred to the explanations under -f77.
accept-type | double-complex | param-noparen |
backslash | format-dollarsign | cray-pointer |
byte | format-edit-descr | quad-constant |
cpp | function-noparen | type-size |
d-comment | name-dollarsign | variable-format |
dec-tab | param-implicit-type | vms-io |
The keywords which differ somewhat from the corresponding -f77 keywords are as follows.
See also: -f77, -f95, -portability, -pretty, -style, -wordsize.
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, -f95 is equivalent to -f95=all, and -nof95 is equivalent to -f95=none. The warning keywords with their meanings are as follows.
There is one other Fortran 77 syntax feature that was deleted in Fortran 95, namely branching to an ENDIF from outside the IF block. However, ftnchek is unable to analyze program flow, and so it does not provide a warning for this.
See also: -f77, -f90, -portability, -pretty, -style, -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: -novice, -version, and help option of all settings that take a list of keywords.
This option is provided to enable ftnchek to handle source files containing non-standard identifer names that may be needed, for example, to access certain operating system services. See the section on Limitations and Extensions for the treatment of identifiers containing these characters in implicit typing.
Using -noidentifer-chars turns off acceptance of non-alphanumeric characters entirely.
See also: -source.
See also: -f77, -source.
There are three special keywords: all turns on recognition of all the nonstandard intrinsics (listed below) and accepts either syntax for those that have variations. Use none to turn off recognition of all nonstandard intrinsics except those noted below. Use help to print the list of all the keywords with a brief explanation of each. If list is omitted, -intrinsic is equivalent to -intrinsic=all, and -nointrinsic is equivalent to -intrinsic=none.
The nonstandard intrinsic functions needed to support the nonstandard extended precision data types (double complex and quad precision) are always recognized. The intrinsics for the double complex data type are:
CDABS | CDSQRT | DREAL | ZLOG |
CDCOS | DCMPLX | IMAG | ZSIN |
CDEXP | DCONJG | ZABS | ZSQRT |
CDLOG | DIMAG | ZEXP | ZCOS |
CDSIN |
CQABS | QARCOS | QEXT | QNINT |
CQCOS | QARSIN | QEXTD | QPROD |
CQEXP | QATAN | QFLOAT | QREAL |
CQLOG | QATAN2 | QIMAG | QSIGN |
CQSIN | QCMPLX | QINT | QSIN |
CQSQRT | QCONJG | QLOG | QSINH |
DBLEQ | QCOS | QLOG10 | QSQRT |
IQINT | QCOSH | QMAX1 | QTAN |
IQNINT | QDIM | QMIN1 | QTANH |
QABS | QEXP | QMOD | SNGLQ |
BTEST | IBCLR | IEOR | ISHFTC |
EXIT | IBITS | IOR | LOC |
IAND | IBSET | ISHFT | NOT |
ABORT | GMTIME | LTIME | SRAND |
AND | IARGC | OR | SYSTEM |
GETARG | IRAND | RAND | TIME |
GETENV | LSHIFT | RSHIFT | XOR |
DATE | IDATE | SECNDS | TIME |
ERRSNS | RAN | SIZEOF |
The no-argument and one-argument keywords work as follows: turning the option on causes ftnchek to accept the corresponding syntax for invocation of the function, without excluding the possibility of the alternative syntax. Turning the option off causes the corresponding syntax not to be accepted. If both options are turned on at once (the default), then either syntax is accepted. Turning both options off at once would not be meaningful. These options have no effect if recognition of Unix intrinsics has been turned off.
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.
The default value of this setting is equivalent to -intrinsic=all followed by -intrinsic=no-vms for the Unix version, -intrinsic=no-unix for the VMS version, and -intrinsic=no-unix,no-vms for other versions.
Note: In versions of ftnchek prior to 2.10, the -intrinsic flag took a numeric argument instead of a list of options. For the sake of users who may have written scripts invoking ftnchek in this way, the numeric form is still accepted. The numeric form of the setting consists of three digits. The ones digit selects the set of intrinsic functions to be supported. The digit 0 selects only Fortran 77 standard intrinsics plus those needed to support the nonstandard extended precision data types. The digit 1 is equivalent to extra, 2 is equivalent to extra,unix, and 3 is equivalent to extra,vms. The tens digit of this setting controls the syntax of the RAND intrinsic function, and the hundreds digit controls the syntax of the IARGC function. For these digits, specify 0 to require invocation with no argument, 1 to require one argument, and 2 to allow either form.
See also: -f77.
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=no-ext-unused option 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: -output, \fB-symtab, fB-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.
Various options for the form of the declarations file are controlled by the list, which consists of keywords separated by commas or colons. There are three special keywords: all to turn on all the options, 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, -makedcls is equivalent to -makedcls=declarations (i.e. produce the declarations file using the default options), and -nomakedcls is equivalent to -makedcls=none.
For compatibility with previous versions of ftnchek, a numeric form of this setting is also accepted: the list is replaced by a number which is the sum of the numbers in parentheses beside the keywords in the following list. The warning keywords with their meanings are as follows:
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(1L) man page for the details of its use.
See also: -mkhtml.
Various options for the form of the HTML files are controlled by the list, which consists of keywords separated by commas or colons. There are three special keywords: all to turn on all the options, 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, -mkhtml is equivalent to -mkhtml=documents (i.e. produce the HTML document files using the default options), and -nomkhtmls is equivalent to -mkhtml=none.
For the sake of simplicity, the options for -mkhtml are the same as those for -makedcls except for those that are inapplicable. Likewise, a numeric form of this setting can be used, formed as the sum of the numbers in parentheses in the list below. The warning keywords with their meanings are as follows:
See also: -calltree, -makedcls.
Default = yes.
The pointer size is used to inform precision mismatch warnings involving pointer variables, for example when a pointer is assigned a value from an allocation routine, or passed as a subprogram parameter.
See also: -f77, -portability, -truncation, -wordsize.
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:
See also: -f77, -f90, -f95, -pretty, -style, -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:
Note that in free source form, extra space and missing space are forbidden by the Fortran 90 Standard, and are not mere style violations. In this case the warnings are replaced by syntax error messages, and can be turned off only by using -nocheck.
See also: -f77, -portability, -style.
The list consists of keywords separated by commas or colons. There are three special keywords: all to turn on all the options, 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, -project is equivalent to -project=all, and -noproject is equivalent to -project=none. The keywords with their meanings are as follows:
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 option is turned on, ftnchek will not read project files as input.
Ordinarily, the trim options should be left on when you intend to create project files for future input to ftnchek. Since trimming is on by default, this means that simply giving the command -project with no option list is the recommended mode. The trim options are provided only as a convenience for those who want to make use of project files for purposes other than checking the program with ftnchek. To use project files for their intended purpose, the trim options should not be turned off.
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.
Note: the way to remember the difference between the -quiet and -brief is that -quiet doesn't suppress any warning-related information, whereas -brief does.
See also: -brief.
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=tree prints out a depth-first traversal.
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:
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.
For compatibility with previous versions of ftnchek, a numeric form of this setting is also accepted: the list is replaced by a number which is the sum of the numbers in parentheses beside the keywords in the following list. (The fixed and free options do not have numeric values.) The warning keywords with their meanings are as follows:
By default, all these source code options are turned off, except for the vms-include option, which is on by default in the VMS version..
See also: -f77, -include, -portability.
The list consists of keywords separated by commas or colons. There are three special keywords: all to turn on all the options, 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, -style is equivalent to -style=all, and -nostyle is equivalent to -style=none. The warning keywords with their meanings are as follows:
See also: -f77, -f90, -f95, -pretty, -portability.
Also, for each module, a label table will be printed. The table lists each label defined in the module; the line on which said statement label is defined; and the statement type (executable, format, or specification). The labels are listed in sequential order.
Also printed is a table describing the I/O units used by the module, together with information about how they are used: what operations are performed, whether the access is sequential or direct, and whether the I/O is formatted or unformatted.
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:
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 provides detailed control over the warnings about possible usage 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 usage, 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, -usage is equivalent to -usage=all, and -nousage is equivalent to -usage=none. These warnings cover four main categories of objects: subprogram dummy arguments, common blocks and variables, subprograms and functions, and local variables. Warnings include undefined items, multiply defined items, unused items, etc. The warning keywords with their meanings are as follows:
Note: In versions of ftnchek prior to 2.10, the -usage flag took a numeric argument instead of a list of options. For the sake of users who may have written scripts invoking ftnchek in this way, the numeric form is still accepted. The numeric 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 convention that a 1 means warn about undefined items and variables that are used before set, a 2 means warn about items that are unused, and a 3 means warn about both types. These numbers are now converted to the appropriate values for the above-listed keywords, except for com-block-volatile, which is not affected by the numeric argument.
See also: -common, -declare, -extern, -library.
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 of Cranfield University, 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: -calltree, -crossref, -reference, -sort.
See also: -help.
This flag is superseded by -common=volatile, and should no longer be used. It may be eliminated in a future release of ftnchek.
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: -pointersize, -portability, -truncation.
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.
This section contains detailed information on how to use project files most effectively, and how to avoid some pitfalls.
One can divide the checks ftnchek does into two categories, local and global. Local checking is restricted to within a single routine, and catches things like uninitialized variables, unintended loss of precision in arithmetic expressions, etc. This sort of checking can be done on each subprogram independently. Furthermore, local checking of a subprogram does not need to be repeated when some other subprogram is changed. Global checking catches things like calling a subroutine with the wrong argument types, or disagreeing in common block declarations. It requires looking at the whole set of subprograms interacting with each other.
The purpose of project files is to allow the local checking and global checking steps to be separated. Assuming that each subprogram is in its own source file, you can run ftnchek once on each one to do local checking while suppressing global checking. Then ftnchek can be run once on all the project files together to do the global checking. The sample makefile below shows how to automate this task. The ``.f.prj'' target updates a project file for a particular file any time the source file changes. The information needed for global checking is saved in the project file. The ``check'' target does the combined global checking. Typically ``make check'' would repeat the ``ftnchek -project'' step only on changed source files, then do the global check. This is obviously a big advantage for large programs, when many subprograms seldom if ever change.
It is best when using project files to place each subprogram in a separate source file. If each source file may contain more than one subprogram, it complicates the definition of ``local'' and ``global'' checking because there is some inter-module checking that is contained within a file. ftnchek tries to do the right thing in this case, but there are some complications (described below) due to the trade-off between avoiding re-doing cross-checks and preserving information about the program's structure.
Ordinarily, to do the least amount of re-checking, project files should be created with the -library flag in effect and trimming turned on. 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 source 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 -usage checking is turned on (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.
The foregoing discussion assumes that the trimming options of the -project setting are turned on when the project file is created. This is the normal situation. The no-trim options of the -project setting are provided in case one wants to use the project files for purposes other than checking the program with ftnchek. For instance, one could write a Perl script to analyze the project files for information about how the different subprograms are called. You should not use the no-trim options to deal with the issues of information loss discussed above, since they cause more information than necessary to be stored. This makes the project files bigger and causes ftnchek to do more work later when it reads them to check your complete program. Ordinarily, you should use the -library option to control how much information to store for later use by ftnchek in checking your program.
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. Add these lines to your makefile. 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. (In this makefile, the indented lines should each begin with a tab, not blanks.) If any source file contains multiple routines that share common blocks among themselves, then the no-com-\* option should be removed from NOGLOBAL, and/or drop the -library flag.
# tell make what a project file suffix is .SUFFIXES: .prj # these options suppress global checks. NOGLOBAL=-usage=no-ext-undefined,no-com-\* # tell make how to create a .prj file from a .f file .f.prj: ftnchek -project $(NOGLOBAL) -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)
When a program uses many routines defined in a large number of different source files in different directories, it can be cumbersome to specify all the different project files needed to check the program properly. To deal with such cases, ftnchek allows project files to be concatenated into a single large file. This single file can then be given to ftnchek to provide the information for checking the use of any or all of the routines defined in the combined project files. When using such a ``library'' project file, you may want ftnchek's error reports to document precisely the name of the file where the specific function is defined. If the various source files are in several directories, an error report that gives only the file name may be ambiguous, and rather should include the path to the file. The solution is to create each of the individual project files by giving the complete path to the source file. Then this complete path will appear in the error reports. For example, suppose that all of the library subprogram source files are in subdirectories of a directory named /util/lib. Then the individual project files could first be created by a command such as
find /util/lib -name '*.f' -exec ftnchek -project '{}' ';'(Possibly other options would be provided to ftnchek as discussed above. Also, this step could be handled instead by a revised makefile rule that would provide the complete source file path instead of just the local name when invoking ftnchek.) Next, concatenate all of these project files manually.
find /util/lib -name '*.prj' -exec cat '{}' ';' > ourlib.prjThen a program source file can be checked by using the command
ftnchek prog.f ... -lib ourlib.prjand an error message related to any library routine will include the full path to the routine's source file.
At present, there is no archive utility like ar to manage the contents of a concatenated project file like the one in the illustration above. If changes are made to one of the library routines, the only way to update the combined project file is to concatenate all the individual project files once again. Such a utility would be quite easy to write. Someone should do so and contribute it to the ftnchek effort.
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.
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 3.3 November 2004 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 SUM/COUNT converted to real 17 END 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 in module COMPAV: Variables declared but never referenced: J declared at line 11 Warning in module COMPAV: Variables may be used before set: SUM used at line 14 SUM set at line 14 Statement labels defined: Label Line StmtType <30> 15 exec 18 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 in module AVENUM: Variables set but never used: AVG set at line 43 I/O Operations: Unit ID Unit No. Access Form Operation Line 5 SEQ FMTD READ 40 Statement labels defined: Label Line StmtType Label Line StmtType <80> 42 exec <100> 43 exec 0 syntax errors detected in file average.f 6 warnings issued in file average.f Warning: Subprogram COMPAV argument data type mismatch at position 1: Dummy arg SCORE in module COMPAV line 10 file average.f is type intg Actual arg NUMS in module AVENUM line 43 file average.f is type real
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:
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:
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!
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 the version of the parser generator and whether it is GNU bison or UNIX yacc). 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 specifies 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)
SUBROUTINE SUBA(X) REAL Xand elsewhere invokes SUBA by
CALL SUBA(2)
CALL SUBA(2.0)
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. Controlled by the -usage=var-uninitialized option.
INTEGER FUNCTION COUNT(A)and invokes COUNT in another module as
N = COUNT(A)
INTEGER COUNT
-------------------------------------------------------- | | implicit | parameter |--------------------- | | other specification format |---------------|--------------------- and | | statement-function entry | data |--------------------- | | executable -------------------------------------------------------- Table 1
ftnchek accepts ANSI standard Fortran-77 programs with some minor limitations and numerous common extensions.
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.
There are some syntactic extensions and Fortran 90 elements that ftnchek accepts but does very little checking. For instance, pointer usage (whether the nonstandard Cray syntax or the Fortran 90 syntax) is not checked other than for set and used status. It is hoped that some day more thorough checking will be implemented, but for now the user should regard the acceptance of these syntactic features simply as a convenience to enable checking of other aspects of code that contains them. See the section Extensions for specifics about what features are accepted but not fully checked.
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=none 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 the -source=dec-tab setting.
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=unix-backslash setting is given. Otherwise the backslash character will be treated as a normal printing character.
Source code can be in either Fortran 90 free format or traditional fixed format. (F90)
A semicolon is allowed as a statement separator. (F90)
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 -columns 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 (or other non-alphabetic characters as specified by the -identifier-chars option). These characters are 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. (Any other user-defined characters are treated the same as the dollar sign.) 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. An optional program, ftnpp(1L) (available separately) provides preprocessing that properly handles INCLUDE files.
The Fortran 90 DO ... ENDDO control structure is permitted. The CYCLE and EXIT statements are accepted. All of these may have an optional do-construct name, but construct names are not checked for consistency. (F90)
The Fortran 90 SELECT CASE construct is accepted. (F90)
Construct names are also accepted on IF, THEN, ELSE, ENDIF and SELECT CASE statements. (F90)
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.
The following Fortran 90 pointer related syntaxes are accepted: ALLOCATABLE, POINTER, and TARGET statements and the same attributes in type declarations; ALLOCATE, DEALLOCATE, and NULLIFY executable statements; pointer assignment using => operator; and the intrinsic functions ALLOCATED and ASSOCIATED. Little semantic checking of pointer variables and operations is done beyond basic set and used status. For instance, there is no checking for such errors as dangling pointers, or use of unallocated arrays.
Statements may have any number of continuation lines. The Fortran 77 and Fortran 90 standards allow a maximum of 19 in fixed source form. The Fortran 90 standard allows a maximum of 39 in free source form.
Relational (comparison) operators composed of punctuation, namely: < <= == /= > >= are allowed. (F90)
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.
Combined type declarations and data-statement-like initializers
are accepted. These have the form of a standard Fortran 77 type declaration,
followed by a slash-delimited list of constants like that used in a DATA
statement. An example of the syntax is
INTEGER N / 100 /
This bastard form of initializing declaration was not adopted in Fortran 90.
Such declarations should be written using the standard form described below,
which is accepted by ftnchek.
There is limited support for Fortran 90 attribute-based type declarations. This style of declaration is distinguished by the use of a double colon (::) between the list of attributes and the list of declared variables. The features supported may be adequate for novice programmers, but are not yet sufficient for professional-quality Fortran 90 programs. I hope to add support for more features in future releases. I invite volunteers to assist in this task. See the ToDo file in the source code distribution for details. The attributes currently accepted, besides all the usual data types, are DIMENSION, EXTERNAL, INTRINSIC, PARAMETER, and SAVE. The new form of declaration also allows assignment of values to the variables declared. At present, the (LEN=value) form of specifying character lengths is also accepted. Kind specifications, using (KIND=value) are parsed but are not processed: all kinds are treated as default kind. Also, there is little checking of these declarations beyond basic syntax.
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=vms-include option
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 statements which lack parentheses. These will be warned about if the -f77=param-noparen flag is given.
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 |
Here are the changes from Version 3.2 to Version 3.3:
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
The report should be sent to Dr. Robert Moniot (see contact information in section entitled ``Installation and Support'').
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.
Prognosis: may be fixed someday.
ftnchek 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. Heba Elsayed wrote the label table printout and label usage checks. Nelson H. F. Beebe of the University of Utah added most of the new code to implement the -makedcls feature and wrote the dcl2inc script. The -mkhtml feature was contributed by Mark McVeigh of Framatome ANP, Inc. The -reference feature was contributed by Gerome Emmanuel, Ecole des mines, U. Nancy (slightly modified). The -vcg option was contributed by Dr. Philip Rubini of Cranfield University, UK. The support for Cray pointer syntax was provided by John Dannenhoffer of United Technologies Research Center. John C. Bollinger of Indiana University added the parser syntax for the SELECT CASE construct. Robert Landrito added the parser syntax for F90 pointer-related features. Additional features will be added as time permits. As of 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 Nelson H. F. Beebe of the University of Utah, for pointing out bugs and suggesting some improvements. Stefan A. Deutscher, Gunnar Duus, Clive Page of the University of Leicester, Stephan Wefing of Heidelberg University, and Bob Wells of Oxford University were extremely helpful as alpha testers. We also thank Jack Dongarra for putting ftnchek into the netlib library of publicly available software.
The ftnchek program is free software. It can be obtained by anonymous ftp from many software servers, including ftp://netlib.org/fortran . Note that on Netlib the distribution is named ftnchek.tar.gz whereas on most other servers the file name includes the version number, e.g. ftnchek-3.3.0.tar.gz. 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://ftp.dsm.fordham.edu/pub/ftnchek . 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. The distribution also includes a plain ASCII version named ftnchek.doc, a PostScript version named ftnchek.ps, an HTML version in directory html, and a VMS HELP version named ftnchek.hlp.
Information about the latest version and the status of the project can be obtained by visiting ftnchek's home page, http://www.dsm.fordham.edu/~ftnchek . For further information and to report bugs, you may contact Dr. Robert Moniot, whose contact information can be found by a Web search for his name and Fordham University. (E-mail address is not provided here because it attracts unsolicited commercial e-mail, but it is easily constructed by combining his last name with the name of the university and the edu domain.)
dcl2inc(1L), dtoq(1L), dtos(1L), f77(1), fd2s(1L), fs2d(1L), ftnpp(1L), pfort(1L), qtod(1L), sf3(1L), stod(1L). xsf3(1L), xvcg(1L).
November 2004 |