FTNCHEK 3.3(1) | General Commands Manual | FTNCHEK 3.3(1) |
NAME¶
ftnchek - Fortran 77 program checkerSYNOPSIS¶
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 ... ]DESCRIPTION¶
ftnchek (short for Fortran checker) is designed to detect certain errors in a Fortran program that a compiler usually does not. ftnchek is not primarily intended to detect syntax errors. Its purpose is to assist the user in finding semantic errors. Semantic errors are legal in the Fortran language but are wasteful or may cause incorrect operation. For example, variables which are never used may indicate some omission in the program; uninitialized variables contain garbage which may cause incorrect results to be calculated; and variables which are not declared may not have the intended type. ftnchek is intended to assist users in the debugging of their Fortran program. It is not intended to catch all syntax errors. This is the function of the compiler. Prior to using ftnchek, the user should verify that the program compiles correctly. This document first summarizes how to invoke ftnchek. That section should be read before beginning to use ftnchek. Later sections describe ftnchek's options in more detail, give an example of its use, and explain how to interpret the output. The final sections mention the limitations and known bugs in ftnchek.INVOKING FTNCHEK¶
ftnchek is invoked through a command of the form:- -arguments=list
- Control warnings about subprogram type and argument mismatches. Default = turn-on = all.
- -array=list
- Control warnings in checking array arguments of subprograms. Default = turn-on = all.
- -brief
- Use shorter format for some error messages. Default = no.
- -calltree=list
- Produce subprogram call hierarchy in one of 3 formats: text call-tree, who-calls-who and VCG. Default = none, turn-on = tree,prune,sort. 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.
- -check
- Perform checking. Default = yes.
- -columns=num
- Set maximum line length to num columns. (Beyond this is ignored.) Turn-on = max = 132. Default = 72.
- -common=list
- Set degree of strictness in checking COMMON blocks. Default = turn-on = all.
- -crossref=list
- Print cross-reference list of subprogram calls, label usage, and/or COMMON block use. Default = none.
- -declare
- Print a list of all identifiers whose datatype is not explicitly declared. Default = no.
- -division
- Warn wherever division is done (except division by a constant). Default = no.
- -errors=num
- Set the maximum number of error messages per cascade. Default = turn-on = 3.
- -extern
- Warn if external subprograms which are invoked are never defined. Default = yes.
- -f77=list
- Control specific warnings about supported extensions to the Fortran 77 Standard. Default = none, turn-on = all.
- -f90=list
- Control specific warnings about supported extensions to the Fortran 77 Standard that were not adopted as part of the Fortran 90 Standard. Default = none, turn-on = all.
- -f95=list
- Control specific warnings about standard Fortran 77 features that were deleted from the Fortran 95 Standard. Default = none, turn-on = all.
- -help
- Print command summary. Default = no.
- -identifier-chars=list
- Define non-alphanumeric characters that may be used in identifiers. Default = turn-on = dollar sign and underscore.
- -include=path
- Define a directory to search for INCLUDE files before searching in the system-wide directory. Cumulative. Default = turn-on = none.
- -intrinsic=list
- Control treatment of nonstandard intrinsic functions. Default = all except vms for Unix version, all except unix for VMS version, all except unix and vms for other versions. Turn-on = all.
- -library
- Begin library mode: do not warn about subprograms in file that are defined but never used. Default = no.
- -list
- Print source listing of program. Default = no.
- -makedcls=list
- Prepare a file of declarations. The list specifies options for the format of this file. Default = none, turn-on = declarations.
- -mkhtml=list
- Create individual HTML document files from ftnchek analysis and code comments. Usually you will also want to specify -call=tree to create the root HTML file CallTree.html. Default = none, turn-on = documents.
- -novice
- Give output suitable for novice users. Default = yes.
- -output=filename
- Send output to the given file. Default and turn-on sends output to the screen. (Default filename extension is .lis).
- -pointersize=num
- Set the size of ``Cray pointer'' variables to num bytes. Min = 1, max = 16. Default = turn-on = 4
- -portability=list
- Warn about non-portable usages. Default = none, turn-on = all.
- -pretty=list
- Give warnings for possibly misleading appearance of source code. Default = turn-on = all.
- -project=list
- Create project file (see explanation below). Default = no.
- -pure
- Assume functions are pure, i.e. have no side effects. Default = yes.
- -quiet
- Produce less verbose output. Default = no.
- -reference
- Print table of subprograms referenced by each subprogram. Default = no.
- -resources
- Print amount of resources used in analyzing the program. Default = no.
- -sixchar
- List any variable names which clash at 6 characters length. Default = no.
- -sort
- Print list of subprograms sorted in prerequisite order. Default = no.
- -source=list
- Select source formatting options: fixed or free form, DEC Fortran tab-formatted lines, VMS-style INCLUDE statement, UNIX-style backslash escape sequences, and implicit typing of parameters. Default = none, turn-on = all.
- -style=list
- Produce extra-picky warnings about obsolescent or old-fashioned programming constructions. Default = none, turn-on = all.
- -symtab
- Print symbol table and label table for each subprogram. Default = no.
- -truncation=list
- Check for possible loss of accuracy by truncation. Default = turn-on = all.
- -usage=list
- Control warnings about unused or uninitialized variables, common blocks, etc. Default = turn-on = all.
- -vcg
- Produce VCG format of call graph.
- -version
- Print version number. Default = no.
- -volatile
- Assume COMMON blocks lose definition between activations. Default = no. (Obsolete. Use -common=volatile instead.)
- -wordsize=num
- Set the default word size for numeric quantities to num bytes. Default = turn-on = 4 bytes.
- -wrap=num
- Set output column at which to wrap long error messages and warnings to the next line. If set to 0, turn off wrapping. Default = turn-on = 79.
- help
- Print out all the option keywords controlled by the setting, with a brief explanation of their meanings. This keyword cannot be given in a list with other keywords.
- all
- Set all options. This turns on all options controlled by the setting.
- none
- Clear all options. This turns off all options controlled by the setting.
OPTIONS¶
This section provides a more detailed discussion of ftnchek command-line options. Options and filenames may be interspersed on a command line. Most options are positional: each option remains in effect from the point it is encountered until it is overridden by a later change. Thus for example, the listing may be suppressed for some files and not for others. Exceptions are: the -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.- -arguments=list
Controls warnings about mismatches between actual and
dummy subprogram arguments, and also about mismatches between expected and
actual subprogram type. (An actual argument is an argument passed to the
subprogram by the caller; a dummy argument is an argument received by the
subprogram.) By default, all warnings are turned on.
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:
- arrayness:
- warn about inconsistent use of arguments that are arrays. These warnings can be further controlled by the -array option.
- type:
- warn about dummy arguments of a different data type from the actual arguments.
- function-type:
- warn if the invocation assumes the function's return value is a different type than it actually is. Also warns if a function is called as a subroutine, or vice-versa.
- number:
- warn about invoking a subprogram with a different number of arguments than the subprogram expects.
- -array=list
Controls the degree of strictness in checking agreement
between actual and dummy subprogram arguments that are arrays. The warnings
controlled by this setting are for constructions that might legitimately be
used by a knowledgeable programmer, but that often indicate programming
errors. By default, all warnings are turned on.
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:
- dimensions:
- 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.
- size:
- warn if both arguments are arrays, but they differ in number of elements.
- -brief
Selects a shorter format for some warning messages. At
present, the only warnings controlled by this flag are those that are printed
at the end of processing each subprogram. These include warnings about
variables that are set but not used or used before set, variable names that do
not conform to the Fortran 77 standard, etc. (These warnings may be suppressed
entirely depending on other flags, such as the -usage or -f77
flags.) In the default format each variable is listed on a separate line,
along with the line number where the variable is declared, set or used,
according to the nature of the warning. The briefer format simply lists all
variables to which the warning applies, with up to 4 variables per line.
See also: -quiet.
- -calltree=list
Causes ftnchek to print out the call structure of
the complete program.
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:
- tree:
- produce the call graph in tree format.
- reference:
- produce the call graph in who-calls-who format (same as -reference switch).
- vcg:
- produce the call graph in VCG format (same as -vcg switch).
- prune:
- prune repeated subtrees (applicable only with tree). This the default.
- sort:
- sort children of each routine into alphabetical order. This is the default.
- -check
This switch is provided so that errors and warning
messages can be turned off when ftnchek is used for purposes other than
finding bugs, such as making declarations or printing the call tree. It is
positional, so after turning all checks off, selected checks can be turned
back on. The effect of -nocheck is to put all switches, numeric
settings, and settings controlling lists of warnings to their turn-off values,
as if they had all been specified with the -no prefix. Switches and settings
that specify options and modes of operation, rather than controlling warnings,
are unaffected. These are -columns, -crossref, -include,
-intrinsic, -library, -list, -makedcls,
-novice, -output, -pointersize, -project,
-quiet, -reference, -resources, -sort,
-source, -symtab, -vcg, -version,
-wordsize, and -wrap. Default = yes.
Parse errors (syntax errors due to unrecognized or malformed statements) are not
suppressed by this switch, since the results may be incorrect if
ftnchek has not parsed the program correctly.
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:
- o
- Module contains no executable statements.
- o
- In free source form, missing space where space is required (e.g. between a keyword and an identifier) or space present where none is allowed (e.g. within an identifier).
- o
- Zero or negative length specification in a data type declaration of the form type*len.
- o
- Invalid operand(s) in an expression.
- o
- Array assigned to scalar.
- o
- Type mismatch between DO index and bounds.
- o
- Undefined common block declared in SAVE statement.
- o
- Intrinsic function explicitly declared with an incompatible type.
- o
- Unknown intrinsic function explicitly declared in an INTRINSIC statement.
- o
- Intrinsic function passed as a subprogram argument is not declared in an INTRINSIC statement.
- o
- Intrinsic function or statement function invoked incorrectly.
- o
- Function does not set return value prior to RETURN statement.
- o
- Parameter constant value not evaluated (this is ftnchek's fault, and it is just informing you of the fact).
- o
- Entry point of a subprogram is later used as a different subprogram's name.
- o
- Unknown keyword used in an I/O statement.
- o
- Illegal label reference (e.g. GOTO refers to a non-executable statement; I/O statement refers to a non-format statement).
- -columns=num
Set maximum statement length to num columns.
(Beyond this is ignored.) This setting is provided to allow checking of
programs which may violate the Fortran standard limit of 72 columns for the
length of a statement. According to the standard, all characters past column
72 are ignored. If this setting is used when the -f77=long-line option
is in effect, a warning will be given for any lines in which characters past
column 72 are processed. Turn-on = max = 132. Default = 72.
This setting does not suppress warnings about the presence of characters beyond
column 72. To process code with meaningful program text beyond column 72, use
this setting and be sure the -f77 long-line option is off. To
process code with sequence numbers in columns 73 to 80, leave the the columns
setting at the default value and use the -pretty=no-long-line flag.
See also: -f77, -pretty.
- -common=list
This setting controls the strictness of checking of
COMMON blocks. By default, all warnings except volatile are turned on.
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:
- dimensions:
- corresponding arrays in each declaration of a block must agree in size and number of dimensions. This option only has an effect when used together with exact.
- exact:
- the comparison of two blocks is done variable-by-variable rather than simply requiring agreement between corresponding storage locations. Use this if all declarations of a given COMMON block are supposed to be identical, which is a good programming practice.
- length:
- warn if different declarations of the same block are not equal in total length. The Fortran 77 Standard requires each named common block, but not blank common, to be the same length in all modules of the program.
- type:
- in each declaration of a given COMMON block, corresponding memory locations (words or bytes) must agree in data type. If used together with exact, this will require that corresponding variables agree in data type.
- volatile:
- Assume that COMMON blocks are volatile.
- -crossref=list
Prints cross-reference tables. Default = none.
The list consists of keywords separated by commas or colons. The keywords
with their meanings are as follows:
- calls:
- table lists each subprogram followed by a list of routines that call it. This listing omits library modules that are not in the call tree of the main program. The list is alphabetized.
- common:
- table lists each COMMON block followed by a list of the routines that access it. These listed routines are those in which some variables in the COMMON 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.)
- labels:
- table lists each label followed by a list of all references to it. A label reference is denoted by the line number and statement type of the referring statement. The label list is in sequential order. The references are listed in the order they are encountered in the program.
- -declare
If this flag is set, all identifiers whose datatype is
not declared in each module will be listed. This flag is useful for helping to
find misspelled variable names, etc. The same listing will be given if the
module contains an IMPLICIT NONE statement. Default = no.
See also: -sixchar, -usage.
- -division
This switch is provided to help users spot potential
division by zero problems. If this switch is selected, every division except
by a constant will be flagged. (It is assumed that the user is intelligent
enough not to divide by a constant which is equal to zero!) Default = no.
See also: -portability, -truncation.
- -errors=num
Set the maximum number of error messages in a
``cascade''. During checking of agreement of subprogram arguments, common
block declarations, and so forth, sometimes a single case will generate a long
string of warnings. Often this simply indicates some other cause than a
genuine item-by-item mismatch, such as for example a varible missing from one
list. So in such cases ftnchek stops printing the warnings after the
cascade limit is reached, and the trailer ``etc...'' is printed to indicate
that there were more errors not printed. If you think that these warnings are
likely to be genuine, use this setting to see more of them. Turn-on = default
= 3, max = 999. A value of 0 means no limit.
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.
- -extern
Causes ftnchek to report whether any subprograms
invoked by the program are never defined. Ordinarily, if ftnchek is
being run on a complete program, each subprogram other than the intrinsic
functions should be defined somewhere. Turn off this switch if you just want
to check a subset of files which form part of a larger complete program.
Subprogram arguments will still be checked for correctness. Default = yes.
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.
- -f77=list
Use this setting to catch language extensions which
violate the Fortran 77 Standard. Such extensions may cause your program not to
be portable. Examples include the use of underscores in variable names;
variable names longer than six characters; statement lines longer than 72
characters; and nonstandard statements such as the DO ... ENDDO structure.
ftnchek does not report on the use of lowercase letters. By default,
all warnings are turned off.
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:
- accept-type:
- ACCEPT and TYPE I/O statements.
- array-bounds:
- Expressions defining array bounds that contain array elements or function references.
- assignment-stmt:
- Assignment statements involving arrays. In Fortran 90, an array can be assigned to another array of compatible shape, or a scalar can be assigned to an array. Neither of these assignments is permitted in Fortran 77.
- A related warning occurs when an array is assigned to a scalar. Since this is illegal also in Fortran 90, it is always warned about regardless of the -f77 setting (unless all checking is turned off with the -nocheck flag).
- attribute-based-decl:
- Type declarations in the new Fortran 90 attribute-based style. This style of declaration is distinguished by the use of a double colon (::) between the list of attributes and the list of declared variables. This option also controls warnings for use of Fortran 90 length or kind specifiers in type declarations. (Although these specifiers can be used in non-attribute-based declarations, they are controlled by this option to avoid proliferation of -f77 options.)
- automatic-array:
- Local (not dummy) arrays which have variable size. These would correspond to arrays whose storage would have to be dynamically allocated at run time.
- backslash:
- Unix backslash escape in strings. This warning will be given only if the -source=unix-backslash setting is specified to cause the escape interpretation of backslash..
- byte:
- BYTE data type declaration.
- case-construct:
- The SELECT CASE construct.
- character:
- Extensions to the Fortran 77 standard regarding character data. At present, this only controls warnings about character variables declared with zero or negative length. In Fortran 77, all character variables must be of positive length. In Fortran 90, they can be zero length, and declarations that specify negative lengths are permitted, turning into zero for the declared length. Note: because negative length specifiers may indicate a programming error, the warning about them is given even if this option is turned off, and is suppressed only by the -nocheck flag.
- common-subprog-name:
- Common block and subprogram having the same name.
- construct-name:
- Use of a construct-name to label a control statement.
- continuation:
- More than 19 successive continuation lines.
- cpp:
- Unix C preprocessor directives in the source code.
- cray-pointer:
- ``Cray pointer'' syntax.
- cycle-exit:
- The CYCLE and EXIT statements.
- 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=dec-tab setting 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.
- io-keywords
- Nonstandard keywords used in I/O statements. These fall into three groups.
The first group includes keywords that are accepted in Fortran 90:
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
- 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-implicit-type:
- Implicit typing of a parameter by the data type of the value assigned. This warning can only occur if implicit parameter typing has been turned on by the -source=param-implicit-type option, or if the PARAMETER statement is of the nonstandard form without parentheses. If this option is turned on, then any instances where implicit parameter typing occurs will be warned about. If you want to be warned only in those instances where the implicit data type differs from the default type, use -portability=param-implicit-type instead. According to the Fortran 77 standard, the data type of a parameter is given by the same rules as for a variable, and if necessary a type conversion is done when the value is assigned.
- param-intrinsic:
- Intrinsic function or exponentiation by a real used to define the value of a PARAMETER definition.
- param-noparen:
- PARAMETER statement without parentheses. The user should be aware that the semantics of this form of the statement differs from that of the standard form: in this form, the parameter takes its data type from the value assigned, rather than having its default data type based on the first letter of the parameter name. (This form of the PARAMETER statement was introduced by DEC before the Fortran 77 standard was defined, and should be avoided.)
- pointer:
- Fortran 90 standard pointer-related syntax, including POINTER, TARGET and ALLOCATABLE type declarations, ALLOCATE, DEALLOCATE, and NULLIFY statements, and pointer assignment using =>.
- quad-constant:
- Quad precision real constants, e.g. of the form 1.23Q4.
- quotemark:
- Strings delimited by quote marks rather than apostrophes.
- relops:
- Relational (comparison) operators composed of punctuation, namely: < <= == /= > >=.
- semicolon:
- Semicolon used as statement separator.
- statement-order:
- Statements out of the sequence mandated by the Standard. The allowed sequence is illustrated in Table 1 in the section on Interpreting the Output.
- 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:
- Obsolete. Now has the same meaning as the io-keywords keyword.
- -f90=list
This setting provides detailed control over the warnings
about supported extensions to the Fortran 77 Standard that were not adopted as
part of the Fortran 90 Standard. Note that ftnchek does not support the
full Fortran 90 language. However, it does support some common extensions to
Fortran 77 that were prevalent before Fortran 90 was defined. Some of these
extensions became part of the Fortran 90 Standard, but others did not. The
-f90 setting warns only about the latter. That is, this flag covers
things that are neither legal Fortran 77 nor legal Fortran 90. Therefore, the
warnings controlled by this flag are basically a subset of the warnings
controlled by -f77. There are a few cases, described below, where the
circumstances in which the warning is given are slightly different for the two
flags.
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.
The keywords which differ somewhat from the corresponding -f77 keywords
are as follows.
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 |
- continuation:
- The limit on the number of continuation lines for a statement in fixed source form is the same, namely 19, in Fortran 90 as in Fortran 77. For free source form the limit is 39 continuation lines, and a line containing a continuation mark cannot be otherwise empty or contain only a comment.
- intrinsic:
- This is the same as for -f77 except for the intrinsic functions defined in MIL-STD 1753, which are all included in Fortran 90, and so are not warned about. (See -intrinsic for a list.)
- io-keywords:
- This is the same as for -f77 except that no warnings are given for the I/O keywords that are standard in Fortran 90.
- long-line:
- Although the Fortran 90 Standard allows lines longer than 72 characters in free source form, this restriction still applies to fixed source form. In free source form the line length limit is 132 characters, and unlike fixed form, ftnchek does not allow this limit to be increased.
- mixed-expr:
- This is the same as for -f77 except for expressions mixing extended precision real with complex data types, which are permitted in Fortran 90.
- statement-order:
- This is similar to the corresponding -f77 warning, but applies the somewhat looser restrictions on statement order of the Fortran 90 Standard. In particular, Fortran 90 allows DATA statements and statement-function definitions to be intermixed with specification statements.
- typeless-constant:
- In Fortran 90, binary, octal, and hexadecimal constants of the form B'ddd', O'ddd', and Z'ddd', respectively, are permitted. Here 'ddd' represents a string of digits. ftnchek recognizes these forms, as well as a variant of the form X'ddd' for a hexadecimal constant, and other variants in which the base indicator B, O, Z, or X follows the digit string. These variants were not adopted in Fortran 90, so only they are warned about when this flag is turned on.
- -f95=list
This setting provides detailed control over warnings
about standard Fortran 77 features that were deleted from the Fortran 95
Standard. Unlike the -f77 and -f90 settings, these warnings
apply to syntax which is legal Fortran 77. However, since these features have
been deleted from the Standard, it is possible that programs containing them
will be unacceptable to some newer compilers.
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.
- real-do:
- A DO variable of any real numeric type.
- pause:
- The PAUSE statement.
- assign:
- The ASSIGN statement, assigned GOTO, or assigned format.
- h-edit:
- The H edit descriptor in a format.
- -help
Prints a list of all the command-line options with a
short description of each along with its default value. This command is
identical in function to the ``?'' argument, and is provided as a
convenience for those systems in which the question mark has special meaning
to the command interpreter. Default = no.
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.
- -identifier-chars=list
Define non-alphanumeric characters that may be used in
identifiers. By default, ftnchek only accepts the dollar sign and
underscore as non-alphanumeric characters in identifier names. The characters
in the list replace whatever set of accepted non-alphanumeric
characters was previously in effect. Thus, if dollar sign or underscore are
not included in the list, they lose their status as acceptable characters.
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.
- -include=path
Specifies a directory to be searched for files specified
by INCLUDE statements. Unlike other command-line options, this setting is
cumulative; that is, if it is given more than once on the command line, all
the directories so specified are placed on a list that will be searched in the
same order as they are given. The order in which ftnchek searches for a
file to be included is: the current directory; the directory specified by
environment variable FTNCHEK_INCLUDE if any; the directories specified by any
-include options; the directory specified by environment variable
INCLUDE; and finally in a standard system-wide directory (/usr/include for
UNIX, SYS$LIBRARY for VMS, and \include for MSDOS).
See also: -f77, -source.
- -intrinsic=list
Controls whether ftnchek recognizes certain
nonstandard intrinsic functions as intrinsic. The list consists of
keywords separated by commas or colons. Some of the keywords control whether
to recognize certain groups of functions, and other keywords control the
expected syntax for invoking some nonstandard intrinsics. Include a keyword to
turn on recognition of the corresponding set of intrinsics or to allow the
corresponding syntax. Include a keyword prefixed by no- to turn off
that recognition.
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:
The intrinsics for the quad precision and quad complex types are:
The keywords controlling recognition of other nonstandard intrinsic functions
are as follows:
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 |
- extra:
- recognize the following commonly available nonstandard intrinsics (all
except EXIT and LOC are defined in MIL-STD 1753):
BTEST IBCLR IEOR ISHFTC EXIT IBITS IOR LOC IAND IBSET ISHFT NOT
- unix:
- recognize these common Unix-specific intrinsic functions:
ABORT GMTIME LTIME SRAND AND IARGC OR SYSTEM GETARG IRAND RAND TIME GETENV LSHIFT RSHIFT XOR
- vms:
- recognize these common VMS-specific intrinsic functions:
DATE IDATE SECNDS TIME ERRSNS RAN SIZEOF
- iargc-no-argument:
- specify that IARGC may be invoked with no arguments.
- iargc-one-argument:
- specify that IARGC may be invoked with one argument.
- rand-no-argument:
- specify that RAND and IRAND may be invoked with no arguments.
- rand-one-argument:
- specify that RAND and IRAND may be invoked with one argument.
- -library
This switch is used when a number of subprograms are
contained in a file, but not all of them are used by the application.
Normally, ftnchek warns you if any subprograms are defined but never
used. This switch will suppress these warnings. Default = no.
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.
- -list
Specifies that a listing of the Fortran program is to be
printed out with line numbers. If ftnchek detects an error, the error
message follows the program line with a caret ( ^ ) specifying the location of
the error. If no source listing was requested, ftnchek will still print
out any line containing an error, to aid the user in determining where the
error occurred. Default = no.
See also: -output, \fB-symtab, fB-quiet.
- -makedcls=list
Prepare a neatly-formatted file of declarations of
variables, common blocks, and namelist lists, for possible merging into the
source code. The declarations are stored in a file of the same name as the
source code, but with the extension changed to .dcl. If no declarations
are written to the file, it is deleted to reduce clutter from empty files.
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:
- declarations (1):
- Write a declaration file. (This is implied by any of the other options, and can be omitted if any other options are given.)
- undeclared-only (2):
- By default, 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.
- compact (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.
- use-continuation-lines (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 together with compact.
- keywords-lowercase (16):
- Output Fortran keywords in lowercase, instead of the default uppercase.
- vars-and-consts-lowercase (32):
- Output variables and constants in lowercase, instead of the default uppercase. Character string constants are not affected by this option.
- exclude-sftran3 (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.
- asterisk-comment (128):
- Use an asterisk as the comment character; the default is otherwise 'C'.
- comment-char-lowercase (256):
- Use 'c' instead of 'C' or '*' as the comment character.
- suppress-array-dimensions (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.
- free-form (1024):
- Produce declarations in free source form. This mode is automatically used if the input source is free form. Use this option to produce declarations in free form even if the input is in fixed form. Free form declarations are indented only 2 columns instead of 6, use the exclamation mark as the comment character, and indicate continuation lines by an ampersand at the end of the line to be continued.
- -mkhtml=list
Produce HTML documentation from source. Creates
individual HTML files from ftnchek analysis and code comments. All comments
immediately preceding and following the function or subroutine definition are
captured to the HTML file. No reformatting of source comments is performed
other than stripping of FORTRAN comment characters. In addition, the HTML file
lists the local variables declared, common block variables used, functions and
subroutines called, I/O unit usage, and other information about each
subprogram. Usually you will also want to specify -call=tree to create
the root HTML file CallTree.html. (Perhaps this file should be named
index.html.)
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:
- documents (1):
- Create the HTML documents. (This is implied by any of the other options, and can be omitted if any other options are given.)
- compact (4):
- The declarations are normally prettyprinted to line up neatly in common columns. This option value selects instead compact output, without column alignment.
- use-continuation-lines (8):
- Causes continuation lines to be used instead of beginning a new declaration on each line. This option is appropriate to use together with compact.
- keywords-lowercase (16):
- Output Fortran keywords in lowercase, instead of the default uppercase.
- vars-and-consts-lowercase (32):
- Output variables and constants in lowercase, instead of the default uppercase. Character string constants are not affected by this option.
- exclude-sftran3 (64):
- Omit declarations of internal integer variables produced by the SFTRAN3 preprocessor, xsf3(1L). (See -makedcls for discussion.)
- suppress-array-dimensions (512):
- Suppress dimensioning of arrays in the generated declarations. This is normally undesirable, but is available if for some reason you do not want the array dimensions to appear in the HTML.
- free-form (1024):
- Produce variable declarations in free source form. This mode is automatically used if the input source is free form. This mainly affects the form of continuation lines if they are used.
- -novice
This flag is intended to provide more helpful output for
beginners. It has two effects:
- (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.
- -output=filename
- This setting is provided for convenience on systems which do not allow easy redirection of output from programs. When this setting is given, the output which normally appears on the screen will be sent instead to the named file. Note, however, that operational errors of ftnchek itself (e.g. out of space or cannot open file) will still be sent to the screen. The extension for the filename is optional, and if no extension is given, the extension .lis will be used.
- -pointersize=num
Specifies the size of a ``Cray pointer'' variable to be
num bytes. Default = turn-on = 4 bytes.
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.
- -portability=list
ftnchek will give warnings for a variety of
non-portable usages. Examples include the use of tabs except in comments or
inside strings, the use of Hollerith constants, and the equivalencing of
variables of different data types. This option does not produce warnings for
supported extensions to the Fortran 77 Standard, which may also cause
portability problems. To catch those, use the -f77 setting. By default,
all warnings are turned off.
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.
- param-implicit-type:
- Implicit typing of a parameter by the data type of the value assigned, if it differs from the default type. This warning can only occur if implicit parameter typing has been turned on by the -source=param-implicit-type option, or if the PARAMETER statement is of the nonstandard form without parentheses. If this option is turned on, then any instances where implicit parameter typing occurs and where the implicit type is different from the default type based on the first letter of the parameter name, will be warned about. Implicit parameter typing can change the semantics of statements where the parameter is used, causing portability problems.
- 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.
- -pretty=list
Controls certain messages related to the appearance of
the source code. These warn about things that might make a program less
readable or be deceptive to the reader. By default, all warnings are turned
on.
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:
- alternate-return:
- A RETURN statement has a constant specifying an alternate return point that is not between 0 and the number of dummy arguments that are labels. This is legal, and has the same effect as a RETURN with no alternate return expression, but suggests that the programmer intended to use an alternate return label that is not provided.
- embedded-space:
- Space embedded in variable names or in multi-character operators such as **.
- 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.
- -project=list
ftnchek will create a project file from each
source file that is input while this option is turned on. The project file
will be given the same name as the input file, but with the extension
.f or .for replaced by .prj. (If input is from standard
input, the project file is named ftnchek.prj.) Default = none.
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:
- create:
- Produce a project file. The default is not to produce a project file. If this option is not turned on, the other options have no effect.
- trim-calls:
- Trim the amount of information stored in the project file about subprogram declarations and calls. This is the default. Turn this option off only in rare situations. (See discussion below.) The amount of trimming varies depending on the -library flag. More information is trimmed if that flag is turned on.
- trim-common:
- Trim the number of common block declarations stored in the project file. This is the default. Turn this option off only in rare situations. (See discussion below.) This option has no effect if the -library flag is turned off: when not in library mode, no trimming of common block declarations is done regardless of this option.
- -pure
Assume functions are ``pure'', i.e., they will not have
side effects by modifying their arguments or variables in a COMMON block. When
this flag is in effect, ftnchek will base its determination of set and
used status of the actual arguments on the assumption that arguments passed to
a function are not altered. It will also issue a warning if a function is
found to modify any of its arguments or any COMMON variables. Default = yes.
When this flag is turned off, actual arguments passed to functions will be
handled the same way as actual arguments passed to subroutines. This means
that ftnchek will assume that arguments may be modified by the
functions. No warnings will be given if a function is found to have side
effects. Because stricter checking is possible if functions are assumed to be
pure, you should turn this flag off only if your program actually uses
functions with side effects.
- -quiet
This option reduces the amount of output relating to
normal operation, so that error messages are more apparent. This option is
provided for the convenience of users who are checking large suites of files.
The eliminated output includes the names of project files, and the message
reporting that no syntax errors were found. It also eliminates some blank
lines that are ordinarily included for clarity. (Some of this output is turned
back on by the -list and -symtab options.) Default = no.
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.
- -reference
Specifies that a who-calls-who table be printed. This
table lists each subprogram followed by a list of the routines it calls. This
switch is equivalent to -calltree=reference. Default = no.
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.
- -resources
Prints the amount of resources used by ftnchek in
processing the program. This listing may be useful in analyzing the size and
complexity of a program. It can also help in choosing larger sizes for
ftnchek's internal tables if they are too small to analyze a particular
program. Default = no.
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.
- Total statement labels defined
- Number of labels attached to statements (often called statement numbers). The total label count for the entire program is given, as well as the maximum number in any single subprogram.
- 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 not recovered at the end of each module, so this number, like global space, grows until the whole program is analyzed. Unfortunately, this figure may include some text 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.
- -sixchar
One of the goals of the ftnchek program is to help
users to write portable Fortran programs. One potential source of
nonportability is the use of variable names that are longer than six
characters. Some compilers just ignore the extra characters. This behavior
could potentially lead to two different variables being considered as the
same. For instance, variables named AVERAGECOST and AVERAGEPRICE are the same
in the first six characters. If you wish to catch such possible conflicts, use
this flag. Default = no.
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.
- -sort
Specifies that a sorted list of all modules used in the
program be printed. This list is in ``prerequisite'' order, i.e. each module
is printed only after all the modules from which it is called have been
printed. This is also called a ``topological sort'' of the call tree. Each
module is listed only once. Routines that are not in the call tree of the main
program are omitted. If there are any cycles in the call graph (illegal in
standard Fortran) they will be detected and diagnosed. Default = no.
See also: -calltree, -crossref, -reference, -symtab,
-vcg.
- -source=list
This setting controls certain options about the form of
the Fortran source code. 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, -source is equivalent to -source=all, and
-nosource is equivalent to -source=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 fixed and free options do not have numeric values.)
The warning keywords with their meanings are as follows:
- fixed:
- Interpret the source as fixed form (with supported extensions such as exclamation mark for comments). Statements must be in columns 7 to 72 (unless the -cols setting has been used to change this), and blanks are not significant outside character context (but warned about under the -pretty option). This is the default mode unless the source file extension is .f90 or .F90. this option cannot be given together with -source=free.
- free:
- Interpret the source as free form. Statements may be anywhere in columns 1 to 132, comments can only begin with an exclamation mark, and blanks are required in some places such as between identifiers and keywords. This is the default mode if the source file extension is .f90 or .F90. This option cannot be given together with -source=fixed or -source=dec-tab
- dec-tab (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.
- vms-include (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.
- unix-backslash (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.
- param-implicit-type (8):
- Implicit typing of a parameter by the data type of the value assigned. Some non-standard compilers may allow the data type of the value to override the Fortran 77 default type of a parameter that is based on the first letter of the parameter name. This option only applies to PARAMETER statements of the standard form which has parentheses. A parameter that has been explicitly declared in a type statement prior to the PARAMETER statement is not affected by this option. A warning will be given under the -f77=param-implicit-type or -portability=param-implicit-type option.
- Note that this implicit typing is treated as equivalent to an explicit type declaration for the parameter. Therefore, if you use -makedcls=undeclared-only to generate declarations only of undeclared variables, these parameters will not be included.
- dec-param-standard-type (16):
- Follow the Fortran 77 rule for data typing of DEC Fortran style parameters. These are declared using a nonstandard form of the PARAMETER statement which lacks parentheses. According to DEC Fortran, parameters defined by this form of the statement have their data type given by the data type of the value assigned. Use this option to tell ftnchek not to follow this rule but instead to use the same rule as for standard PARAMETER statements. This option does not apply to PARAMETER statements of the standard form.
- -style=list
Provides extra-picky warnings about obsolescent or
old-fashioned programming constructions. This option is helpful for efforts to
follow a modern programming style. (Most of the things complained about under
this option are forbidden in the F subset language.) By default, all
warnings are turned off.
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:
- block-if:
- Complain about arithmetic IF statement. Accept block IF or logical IF (which controls a single statement).
- construct-name:
- Complain about unnamed block constructs: IF, DO, and SELECT CASE. Note that if a construct name is present on the opening statement of a construct, then it is required to be present on all other component statements (ELSE, END IF, etc.) of the construct. In that case a missing construct name on those statements generates a syntax error regardless of this option. The purpose of this option is to warn if the construct completely lacks the optional name.
- distinct-do:
- Complain if two DO loops share a common terminator statement.
- do-construct:
- Complain if terminator of a DO loop is anything other than an END DO or CONTINUE statement. This is the requirement in order for the loop to meet the Fortran 90 definition of a do-construct.
- do-enddo:
- Complain if terminator of a DO loop is anything other than an END DO statement. (This option overrides the do-construct option, being even stricter.)
- end-name:
- Complain about the absence of the subprogram name on structured END statements.
- format-stmt:
- Complain about the presence of FORMAT statements. Only the FORMAT statements themselves are flagged, not the references to them in I/O lists.
- goto:
- Complain about the presence of unconditional, computed or assigned GOTO statements. Also complain about alternate returns (but not about labels as subprogram arguments).
- labeled-stmt:
- Complain about the presence of labels (numbers) on statements other than FORMAT statements. (Since FORMAT statements are arguably convenient and not readily abused, complaints about them are controlled by the separate format-stmt keyword.)
- program-stmt:
- Complain about the absence of a PROGRAM statement at the head of the main program.
- structured-end:
- Complain about the use of a plain END statement to end a subprogram, rather than a structured END statement (END PROGRAM, END SUBROUTINE, END FUNCTION, or END BLOCK DATA).
- -symtab
A symbol table will be printed out for each module,
listing all identifiers mentioned in the module. This table gives the name of
each variable, its datatype, and the number of dimensions for arrays. An
asterisk (*) indicates that the variable has been implicitly typed, rather
than being named in an explicit type declaration statement. The table also
lists all subprograms invoked by the module, all COMMON blocks declared, etc.
Default = no.
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.
- -truncation=list
Warn about possible truncation (or roundoff) errors. Most
of these are related to integer arithmetic. By default, all warnings are
turned on.
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:
- 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.
- size-demotion:
- automatic conversion of a higher precision quantity to one of lower precision of the same type. This warning only occurs when an explicit size is used in declaring the type of one or both operands in an assignment. For example, a warning wil be issued where a REAL*8 variable is assigned to a REAL variable, if the default wordsize of 4 is in effect. A warning is also issued if a long integer is assigned to a shorter one, for example, if an INTEGER expression is assigned to an INTEGER*2 variable. There is one exception to this last case, namely if the right hand side of the assignment is a small literal constant (less than 128). type-demotion: automatic conversion of a higher precision quantity to one of lower precision of different type. 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.
- -usage=list
Warn about unused or possible uninitialized variables,
unused common blocks, undefined or unused statement labels, and unused or
undefined subprograms. By default, all warnings are turned on.
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:
- arg-alias:
- a scalar dummy argument is actually the same as another and is (or may be) modified. The Fortran 77 standard (section 15.9.3.6) prohibits modifying an argument that is aliased to another.
- arg-array-alias:
- a dummy argument which is an array or array element is in the same array as another and is modified. This flag is similar to arg-alias but provides separate control over array arguments. It is harder to tell if aliasing is occurring in the case of arrays, so if ftnchek gives too many false warnings, this flag allows the array-related ones to be turned off without suppressing the warnings for scalars.
- arg-common-alias:
- a scalar dummy argument is the same as a common variable in the subprogram, and either is modified. This is also prohibited by the Fortran 77 standard. If common checking is not exact (see the -common setting), it is harder to tell if aliasing is occurring, so the warning is given if the variable is anywhere in a common block that is declared by the subprogram.
- arg-common-array-alias:
- a dummy argument which is an array or array element is in the same array as a common variable, and either is modified. If common checking is not exact, the variable can be anywhere in a common block that is declared by the subprogram.
- arg-const-modified:
- a subprogram modifies an argument which is a constant or an expression. Such an action could cause anomalous behavior of the program.
- arg-unused:
- a dummy argument is declared but never used. This is similar to the var-unused keyword described below, but applies only to arguments.
- com-block-unused:
- a common block is declared but none of the variables in it are used by any subprogram. This warning is suppressed if the common strictness setting is 0.
- com-block-volatile:
- a common block may lose the definition of its contents if common blocks are volatile. This option only has an effect if the -common=volatile flag is in effect. See the discussion of the -common setting above.
- com-var-set-unused:
- a common variable is assigned a value, but its value is not used by any subprogram. This warning is suppressed if the common strictness setting is 0.
- com-var-uninitialized:
- a common variable's value is used in some subprogram, but is not set anywhere. Unfortunately, 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). This warning is suppressed if the common strictness setting is 0.
- com-var-unused:
- a common variable is declared but not used by any subprogram. This warning is suppressed if the common strictness setting is 0.
- do-index-modified:
- a variable that is the index of a DO loop is modified by some statement within the range of the loop. The Standard permits an active DO variable to be modified only by the incrementation mechanism of the DO statement.
- ext-multiply-defined:
- an external (a subroutine or function) is defined more than once. Definition of an external means providing the body of its source code.
- ext-declared-only:
- a name is declared in an EXTERNAL statement in some module, but is not defined or used anywhere.
- ext-undefined:
- an external is used (invoked) but not defined anywhere. This option is equivalent to the -external flag. If the subprogram is invoked more than once, those invocations will still be checked for consistency.
- ext-unused:
- an external is defined (its subprogram body is present) but it is not used. A subprogram is considered unused even if it is invoked by some other subprogram, if it cannot be called from any thread of execution starting with the main program. The agreement of the subprogram's arguments with its invocations is still checked even if this warning is turned off. If there is no main program, then this warning is issued only if the subprogram is not invoked anywhere. This warning is suppressed in library mode, but library mode has the additional effect of suppressing argument checking for unused routines.
- label-undefined:
- a statement refers to a label that has not been defined.
- label-unused:
- a statement label is defined, but never referred to.
- var-set-unused:
- a local variable is assigned a value, but that value is not used.
- var-uninitialized:
- a local variable's value may be used before it is assigned. 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.
- var-unused:
- a local variable is declared (for instance, in a type declaration) but is not used in the module. Does not apply to dummy arguments: warnings about them are controlled by the keyword arg-unused described above.
- -vcg
Produce the call graph in the form of a VCG graph
description. This description is written to a separate file, with the same
stem as the file containing the main program, and suffix .vcg. This
file is able to be given directly to xvcg(1L) to visualize the call
graph. (If input is from the standard input, then the graph description is
sent to standard output.) This switch is equivalent to -calltree=vcg.
Default = no.
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.
- -version
This option causes ftnchek to print a line giving
the version number, release date, and patch level of the program. If no files
are given, it then exits. If files are given, the effect of this option is to
include the patch level (normally omitted) in the version information printed
at the start of processing. Default = no.
See also: -help.
- -volatile
Assume that COMMON blocks are volatile. Default = no.
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.
- -wordsize=num
Specifies the default word size to be num bytes.
This is the size of logical and single-precision numeric variables that are
not given explicit precisions. (Explicit precisions for non-character
variables are an extension to the Fortran 77 Standard, and are given by type
declarations such as REAL*8 X.) Double-precision and complex variables will be
twice this value, and double complex variables four times. Quad-precision
constants and intrinsic function results will be four times this value. Note
that variables declared as REAL*16 will be regarded as quad precision only if
the word size is 4 bytes. Default = turn-on = 4 bytes.
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.
- -wrap=col
- Controls the wrapping of error messages. Long error messages that would run past the specified column will be broken up into separate lines between the words of the message for better readability. If turned off with -nowrap, each separate error message will be printed on one line, leaving it up to the display to wrap the message or truncate it. Default = turn-on = 79.
CHANGING THE DEFAULTS¶
ftnchek includes two mechanisms for changing the default values of all options: by defining environment variables or by creating a preferences file. When ftnchek starts up, it looks in its environment for any variables whose names are composed by prefixing the string FTNCHEK_ onto the uppercased version of the option name. If such a variable is found, its value is used to specify the default for the corresponding switch or setting. In the case of settings (for example, the -common strictness setting) the value of the environment variable is read as the default setting value. In the case of switches, the default switch will be taken as true or yes unless the environment variable has the value 0 or NO. Note that the environment variable name must be constructed with the full-length option name, which must be in uppercase. For example, to make ftnchek print a source listing by default, set the environment variable FTNCHEK_LIST to 1 or YES or anything other than 0 or NO. The names FTNCHEK_LIS (not the full option name) or ftnchek_list (lower case) would not be recognized. Here are some examples of how to set environment variables on various systems. For simplicity, all the examples set the default -list switch to YES. >1. UNIX, Bourne shell: >$ FTNCHEK_LIST=YESUSING PROJECT FILES¶
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.
AN EXAMPLE¶
The following simple Fortran program illustrates the messages given by ftnchek. The program is intended to accept an array of test scores and then compute the average for the series.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) ENDThe 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 realAccording to ftnchek, the program contains variables which may be used before they are assigned an initial value, and variables which are not needed. ftnchek also warns the user that an integer quotient has been converted to a real. This may assist the user in catching an unintended roundoff error. Since the -symtab flag was given, ftnchek prints out a table containing identifiers from the local module and their corresponding datatype and number of dimensions. Finally, ftnchek warns that the function COMPAV is not used with the proper type of arguments. With ftnchek's help, we can debug the program. We can see that there were the following errors:
- 1.
- SUM and COUNT should have been converted to real before doing the division.
- 2.
- SUM should have been initialized to 0 before entering the loop.
- 3.
- AVG was never printed out after being calculated.
- 4.
- NUMS should have been declared INTEGER instead of REAL.
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!
INTERPRETING THE OUTPUT¶
The messages given by ftnchek include not only syntax errors but also warnings and informational messages about things that are legal Fortran but that may indicate errors or carelessness. Most of these messages can be turned off by command-line options. Which option controls each message depends on the nature of the condition being warned about. See the descriptions of the command-line flags in the previous sections, and of individual messages below. Each message is prefixed with a word or phrase indicating the nature of the condition and its severity. ``Error'' means a syntax error. The simplest kind of syntax errors are typographical errors, for example unbalanced parentheses or misspelling of a keyword. This type of error is caught by the parser and appears with the description ``parse error'' or ``syntax error'' (depending on 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 block NAME: data type mismatch at position n
- The n-th variable in the COMMON block differs in data type in two
different declarations of the COMMON block. By default ( -common
strictness level 3), ftnchek is very picky about COMMON blocks: the
variables listed in them must match exactly by data type and array
dimensions. That is, the legal pair of declarations in different modules:
COMMON /COM1/ A,B and COMMON /COM1/ A(2)
- Common block NAME has long data type following short data type
- Some compilers require alignment of multi-byte items so that each item begins at an address that is a multiple of the item size. Thus if a short (e.g. single-precision real) item is followed by a long (e.g. double precision real) item, the latter may not be aligned correctly. Controlled by -portability=common-alignment option.
- Common block NAME has mixed character and non-character variables
- The ANSI standard requires that if any variable in a COMMON block is of type CHARACTER, then all other variables in the same COMMON block must also be of type CHARACTER. Controlled by -f77=mixed-common option.
- Common block NAME: varying length
- For -common setting level 2, this message means that a COMMON block is declared to have different numbers of words in two different subprograms. A word is the amount of storage occupied by one integer or real variable. For -common setting level 3, it means that the two declarations have different numbers of variables, where an array of any size is considered one variable. This is not necessarily an error, but it may indicate that a variable is missing from one of the lists. Note that according to the Fortran 77 Standard, it is an error for named COMMON blocks (but not blank COMMON) to differ in number of words in declarations in different modules. Given for -common setting 2 or 3.
- Error: Badly formed logical/relational operator or constant
- Error: Badly formed real constant
- The syntax analyzer has found the start of one of the special words that begin and end with a period (e.g. .EQ.), or the start of a numeric constant, but did not succeed in finding a complete item of that kind.
- Error: cannot be adjustable size in module NAME
- A character variable cannot be declared with a size that is an asterisk in parentheses unless it is a dummy argument, a parameter, or the name of the function defined in the module.
- Error: cannot be declared in SAVE statement in module NAME
- Only local variables and common blocks can be declared in a SAVE statement.
- Error: No path to this statement
- ftnchek will detect statements which are ignored or by-passed because there is no foreseeable route to the statement. For example, an unnumbered statement (a statement without a statement label), occurring immediately after a GOTO statement, cannot possibly be executed.
- Error: Parse error
- This means that the parser, which analyzes the Fortran program into expressions, statements, etc., has been unable to find a valid interpretation for some portion of a statement in the program. If your compiler does not report a syntax error at the same place, the most common explanations are: (1) use of an extension to ANSI standard Fortran that is not recognized by ftnchek, or (2) the statement requires more lookahead than ftnchek uses (see section on Bugs).
- NOTE: This message means that the affected statement is not interpreted. Therefore, it is possible that ftnchek's subsequent processing will be in error, if it depends on any matters affected by this statement (type declarations, etc.).
- Error: Syntax error
- This is the same as ``Error: Parse error'' (see above). It is generated if your version of ftnchek was built using the UNIX yacc parser generator rather than GNU bison.
- Identifiers which are not unique in first six chars
- Warns that two identifiers which are longer than 6 characters do not differ in the first 6 characters. This is for portability: they may not be considered distinct by some compilers. Controlled by -sixchar option.
- Nonportable usage: argument precision may not be correct for intrinsic function
- The precision of an argument passed to an intrinsic function may be incorrect on some computers. Issued when a numeric variable declared with explicit precision (e.g. REAL*8 X) is passed to a specific intrinsic function (e.g. DSQRT(X)). Controlled by -portability=mixed-size and -wordsize.
- Nonportable usage: character constant/variable length exceeds 255
- Some compilers do not support character strings more than 255 characters in length. Controlled by -portability=long-string.
- Nonportable usage: File contains tabs
- ftnchek expands tabs to be equivalent to spaces up to the next column which is a multiple of 8. Some compilers treat tabs differently, and also it is possible that files sent by electronic mail will have the tabs converted to blanks in some way. Therefore files containing tabs may not be compiled correctly after being transferred. ftnchek does not give this message if tabs only occur within comments or character constants. Controlled by -portability=tab.
- Nonportable usage: non-integer DO loop bounds
- This warning is only given when the DO index and bounds are non-integer. Use of non-integer quantities in a DO statement may cause unexpected errors, or different results on different machines, due to roundoff effects. Controlled by -portability=real-do.
- Possibly it is an array which was not declared
- This message is appended to warnings related to a function invocation or to an argument type mismatch, for which the possibility exists that what appears to be a function is actually meant to be an array. If the programmer forgot to dimension an array, references to the array will be interpreted as function invocations. This message will be suppressed if the name in question appears in an EXTERNAL or INTRINSIC statement. Controlled by the -novice option.
- Possibly misleading appearance: characters past 72 columns
- The program is being processed with the statement field width at its standard value of 72, and some nonblank characters have been found past column 72. In this case, ftnchek is not processing the characters past column 72, and is notifying the user that the statement may not have the meaning that it appears to have. These characters might be intended by the programmer to be significant, but they will be ignored by the compiler. Controlled by -pretty=long-line.
- Possibly misleading appearance: Common block declared in more than one statement
- Such multiple declarations are legal and have the same effect as a continuation of the original declaration of the block. This warning is only given if the two declarations are separated by one or more intervening statements. Controlled by -pretty=multiple-common.
- Possibly misleading appearance: Continuation follows comment or blank line
- ftnchek issues this warning message to alert the user that a continuation of a statement is interspersed with comments, making it easy to overlook. Controlled by -pretty=continuation.
- Possibly misleading appearance: Extraneous parentheses
- Warns about parentheses surrounding a variable by itself in an expression. When a parenthesized variable is passed as an argument to a subprogram, it is treated as an expression, not as a variable whose value can be modified by the called routine. Controlled by -pretty=parentheses.
- Subprogram NAME: argument data type mismatch at position n
- The subprogram's n-th actual argument (in the CALL or the usage of
a function) differs in datatype or precision from the n-th dummy
argument (in the SUBROUTINE or FUNCTION declaration). For instance, if the
user defines a subprogram by
SUBROUTINE SUBA(X) REAL X
and elsewhere invokes SUBA byCALL SUBA(2)
CALL SUBA(2.0)
- When checking an argument which is a subprogram, ftnchek must be able to determine whether it is a function or a subroutine. The rules used by ftnchek to do this are as follows: If the subprogram, besides being passed as an actual argument, is also invoked directly elsewhere in the same module, then its type is determined by that usage. If not, then if the name of the subprogram does not appear in an explicit type declaration, it is assumed to be a subroutine; if it is explicitly typed it is taken as a function. Therefore, subroutines passed as actual arguments need only be declared by an EXTERNAL statement in the calling module, whereas functions must also be explicitly typed in order to avoid generating this error message. Controlled by -arguments setting.
- Subprogram NAME: argument arrayness mismatch at position n
- Similar to the preceding situation, but the subprogram dummy argument differs from the corresponding actual argument in its number of dimensions or number of elements. Controlled by -array together with -arguments settings.
- Subprogram NAME: argument mismatch at position n
- A character dummy argument is larger than the corresponding actual argument, or a Hollerith dummy argument is larger than the corresponding actual argument. Controlled by -arguments setting.
- Subprogram NAME: argument usage mismatch
- ftnchek detects a possible conflict between the way a subprogram uses an argument and the way in which the argument is supplied to the subprogram. The conflict can be one of two types, as outlined below.
- This warning is not affected by the -arguments setting.
- Subprogram NAME invoked inconsistently
- Here the mismatch is between the datatype of the subprogram itself as used
and as defined. For instance, if the user declares
INTEGER FUNCTION COUNT(A)
and invokes COUNT in another module asN = COUNT(A)
INTEGER COUNT
- Given for -arguments setting 2 or 3.
- Subprogram NAME: varying length argument lists:
- An inconsistency has been found between the number of dummy arguments (parameters) a subprogram has and the number of actual arguments given it in an invocation. ftnchek keeps track of all invocations of subprograms (CALL statements and expressions using functions) and compares them with the definitions of the subprograms elsewhere in the source code. The Fortran compiler normally does not catch this type of error. Given for -arguments setting 1 or 3.
- Variable not declared. Type has been implicitly defined
- When printing the symbol table for a module, ftnchek will flag with an asterisk all identifiers that are not explicitly typed and will show the datatype that was assigned through implicit typing. This provides support for users who wish to declare all variables as is required in Pascal or some other languages. This message appears only when the -symtab option is in effect. Alternatively, use the -declare flag if you want to get a list of all undeclared variables.
- Variables declared but never referenced
- Detects any identifiers that were declared in your program but were never used, either to be assigned a value or to have their value accessed. Variables in COMMON are excluded. Controlled by the -usage=var-unused option.
- Variables set but never used
- ftnchek will notify the user when a variable has been assigned a value, but the variable is not otherwise used in the program. Usually this results from an oversight. Controlled by the -usage=var-set-unused option.
- Variables used before set
- This message indicates that an identifier is used to compute a value prior to its initialization. Such usage may lead to an incorrect value being computed, since its initial value is not controlled. Controlled by the -usage=var-uninitialized option.
- Variables may be used before set
- Similar to used before set except that ftnchek is not able to determine its status with certainty. ftnchek assumes a variable may be used before set if the first usage of the variable occurs prior in the program text to its assignment. Controlled by the -usage=var-uninitialized option.
- Warning: DO index is not integer
- This warning is only given when the DO bounds are integer, but the DO index is not. It may indicate a failure to declare the index to be an integer. Controlled by -truncation=real-do option.
- Warning: integer quotient expr ... converted to real
- The quotient of two integers results in an integer type result, in which the fractional part is dropped. If such an integer expression involving division is later converted to a real datatype, it may be that a real type division had been intended. Controlled by -truncation=int-div-real option.
- Warning: Integer quotient expr ... used in exponent
- The quotient of two integers results in an integer type result, in which the fractional part is dropped. If such an integer expression is used as an exponent, it is quite likely that a real type division was intended. Controlled by -truncation=int-div-exponent option.
- Warning: NAME not set when RETURN encountered
- The way that functions in Fortran return a value is by assigning the value to the name of the function. This message indicates that the function was not assigned a value before the point where a RETURN statement was found. Therefore it is possible that the function could return an undefined value.
- Warning: Nonstandard syntax: adjustable size cannot be concatenated here
- The Fortran 77 Standard (sec. 6.2.2) forbids concatenating character variables whose size is an asterisk in parentheses, except in an assignment statement. Controlled by -f77=mixed-expr.
- Warning: Nonstandard syntax : significant characters past 72 columns
- This warning is given under the -f77=long-line setting if the -columns setting has been used to increase the statement field width, and a statement has meaningful program text beyond column 72. Standard Fortran ignores all text in those columns, but some compilers do not. Thus the program may be treated differently by different compilers.
- Warning: Nonstandard syntax : Statement out of order.
- ftnchek will detect statements that are out of the sequence specified for ANSI standard Fortran 77. Table 1 illustrates the allowed sequence of statements in the Fortran language. Statements which are out of order are nonetheless interpreted by ftnchek, to prevent ``cascades'' of error messages. The sequence counter is also rolled back to prevent repetition of the error message for a block of similar statements. Controlled by the -f77=statement-order option.
-
-------------------------------------------------------- | | implicit | parameter |--------------------- | | other specification format |---------------|--------------------- and | | statement-function entry | data |--------------------- | | executable -------------------------------------------------------- Table 1
- Warning: Possible division by zero
- This message is printed out wherever division is done (except division by a constant). Use it to help locate a runtime division by zero problem. Controlled by -division option.
- Warning: real truncated to intg
- ftnchek has detected an assignment statement which has a real expression on the right, but an integer variable on the left. The fractional part of the real value will be lost. If you explicitly convert the real expression to integer using the INT or NINT intrinsic function, no warning will be printed. A similar message is printed if a double precision expression is assigned to a single precision variable, etc. Controlled by -truncation=demotion option.
- Warning: subscript is not integer
- Since array subscripts are normally integer quantities, the use of a non-integer expression here may signal an error. Controlled by -truncation=real-subscript option.
- Warning: Unknown intrinsic function
- This message warns the user that a name declared in an INTRINSIC statement is unknown to ftnchek. Probably it is a nonstandard intrinsic function, and so the program will not be portable. The function will be treated by ftnchek as a user-defined function. This warning is not suppressed by any option, since it affects ftnchek's analysis of the program. However, if the intrinsic function is in one of the supported sets of nonstandard intrinsics, you can use the -intrinsic setting to cause ftnchek to recognize it.
LIMITATIONS AND EXTENSIONS¶
ftnchek accepts ANSI standard Fortran-77 programs with some minor limitations and numerous common extensions.- Limitations:
The dummy arguments in statement functions are treated
like ordinary variables of the program. That is, their scope is the entire
subprogram, 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.
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.
- Extensions:
All of these extensions (except lower-case characters)
will generate warnings if the relevant -f77 option is set. Some of the
extensions listed below are part of the Fortran-90 Standard. These are
indicated by the notation (F90).
Tabs are permitted, and translated into equivalent blanks which correspond to
tab stops every 8 columns. The standard does not recognize tabs. Note that
some compilers allow tabs, but treat them differently. The treatment defined
for DEC FORTRAN can be achieved using 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:
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.
POINTER ( pointer, pointee) [,( pointer, pointee)]
INTEGER N / 100 /
INCLUDE ' filename'
ABS | IABS | DIM | IDIM | MAX |
MAX0 | MIN | MIN0 | MOD | SIGN |
ISIGN | LEN | ICHAR | INDEX |
NEW FEATURES¶
Here are the changes from Version 3.2 to Version 3.3:- 1.
- Front-end has been rewritten for unlimited lookahead, eliminating the longstanding bug that caused incorrect interpretation of statements whose ambiguity was not resolved in the first line.
- 2.
- The -mkhtml option is now available in the MS-DOS version.
- 3.
- Added support for Fortran 90 pointer related syntax: ALLOCATE, DEALLOCATE, and NULLIFY statements; the ALLOCATABLE, POINTER and TARGET attributes in type declarations; the pointer assigment operator => and intrinsic functions ALLOCATED and ASSOCIATED; and deferred-shape array declarations. At present these new syntax features are accepted but not properly checked. This feature was added by Robert Landrito.
- 4.
- The -f77 and -f90 pointer option controlling warnings about ``Cray pointers'' has been renamed to cray-pointer. The -f77=pointer option now instead controls warnings for code containing Fortran 90 pointer-related syntax.
- 5.
- Re-implemented -mkhtml processing so it is now much faster on source files containing many routines.
- 6.
- Changed the arrangement of the test directory so there is no longer any need to modify the distribution in order to run the test suite ( check.bat) under MS-DOS.
- 7.
- Fixed bug in reading numeric settings on command line when setting name abbreviated to 3 characters.
- 8.
- Fixed bug causing spurious warning for a GOTO referring to a labeled END statement when the statement before END was a FORMAT.
- 9.
- New flag -f77=character to control warnings about extensions to the Fortran 77 character data type. Accompanying this new flag is support for Fortran 90 rules for character variable declarations that evaluate to zero or negative length, allowing them and treating negative length values as zero.
- 10.
- Fixed minor bug in printing of comments and blank lines following last END statement in -list mode.
BUGS¶
ftnchek still has much room for improvement. Your feedback is appreciated. We want to know about any bugs you notice. Bugs include not only cases in which ftnchek issues an error message where no error exists, but also if ftnchek fails to issue a warning when it ought to. Note, however, that ftnchek is not intended to catch all syntax errors (see section on Limitations). Also, it is not considered a bug for a variable to be reported as used before set, if the reason is that the usage of the variable occurs prior in the text to where the variable is set. For instance, this could occur when a GOTO causes execution to loop backward to some previously skipped statements. ftnchek does not analyze the program flow, but assumes that statements occurring earlier in the text are executed before the following ones. We especially want to know if ftnchek crashes for any reason. It is not supposed to crash, even on programs with syntax errors. Suggestions are welcomed for additional features which you would find useful. Tell us if any of ftnchek's messages are incomprehensible. Comments on the readability and accuracy of this document are also welcome. You may also suggest support for additional extensions to the Fortran language. These will be included only if it is felt that the extensions are sufficiently widely accepted by compilers. If you find a bug in ftnchek, first consult the list of known bugs below to see if it has already been reported. Also check the section entitled ``Limitations and Extensions'' above for restrictions that could be causing the problem. If you do not find the problem documented in either place, then send a report including- 1.
- The operating system and CPU type on which ftnchek is running.
- 2.
- The version of ftnchek and values of any environment options or settings defined in startup file. (Capturing the output of ftnchek -help is useful for this.)
- 3.
- A brief description of the bug.
- 4.
- If possible, a small sample program showing the bug.
- 1.
- Bug: Used-before-set message is suppressed for any variable which is used as the loop index in an implied-do loop, even if it was in fact used before being set in some earlier statement. For example, consider J in the statement
WRITE(5,*) (A(J), J=1,10)Here ftnchek parses the I/O expression, A(J), where J is used, before it parses the implied loop where J is set. Normally this would cause ftnchek to report a spurious used-before-set warning for J. Since this report is usually in error and occurs fairly commonly, ftnchek suppresses the warning for J altogether. Prognosis: A future version of ftnchek is planned which will handle implied-do loops correctly.
- 2.
- Bug: Variables used (not as arguments) in statement-function subprograms do not have their usage status updated when the statement function is invoked.
Prognosis: To be fixed in a future version of ftnchek.
- 3.
- Bug: VAX version does not expand wildcards in filenames on the command line if they are followed without space by an option, e.g. ftnchek *.f/calltree would not expand the *.f. This is because VMS-style options without intervening space are not supported by the GNU shell_mung routine that is used to expand wildcards.
Prognosis: unlikely to be fixed.
- 4.
- Bug: checking for nonstandard format edit descriptors is done only in FORMAT statements, not in character strings used as formats.
Prognosis: may be fixed someday.
ACKNOWLEDGEMENTS¶
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.INSTALLATION AND SUPPORT¶
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.)SEE ALSO¶
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 |