MAN page from Rawhide ftnchek-4beta_r132-61.138.x86_64.rpm

FTNCHEK 4.0

Section: Misc. Reference Manual Pages (1L)
Updated: July 2012
Index

NAME

ftnchek - Fortran program checker

SYNOPSIS

ftnchek[-[no]arguments[=list]][-[no]array[=list]]
     [-[no]brief][-[no]calltree[=list]][-[no]check]
     [-columns[=num]][-[no]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][-[no]intrinsic[=list]][-[no]library]
     [-[no]list][-[no]makedcls[=list]][-[no]mkhtml[=list]]
     [-module=str][-[no]novice][-output=str]
     [-pointersize[=num]][-[no]portability[=list]]
     [-[no]pretty[=list]][-[no]project[=list]]
     [-[no]pure][-[no]quiet][-[no]resources]
     [-[no]sixchar][-[no]sort][-[no]source[=list]]
     [-[no]style[=list]][-[no]symtab][-[no]truncation[=list]]
     [-[no]type[=list]][-[no]usage[=list]][-[no]version]
     [-wordsize[=num]][-wrap[=num]][files ...]

DESCRIPTION

ftnchek (short for Fortran checker)is designed to detect certain errors in aFortran program that a compiler usually does not.ftnchek is not primarilyintended to detect syntax errors. Its purpose is to assist the user in findingsemantic errors. Semantic errors are legal in the Fortran language but arewasteful or may cause incorrect operation. For example, variables which arenever used may indicate some omission in the program; uninitialized variablescontain garbage which may cause incorrect results to be calculated; andvariables which are not declared may not have the intended type.ftnchek isintended to assist users in the debugging of their Fortran program. It is notintended to catch all syntax errors. This is the function of the compiler.Prior to using ftnchek,the user should verify that the program compilescorrectly.

The language accepted by ftnchek is Fortran 95 (with someexceptions noted in the section on limitations and extensions).

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

INVOKING FTNCHEK

ftnchek isinvoked through a command of the form:

$ ftnchek [-option -option ...] filename [filename ...]

The brackets indicate something which is optional. The bracketsthemselves are not actually typed. Here options are command-lineswitches or settings, which control the operation of the program and theamount of information that will be printed out. If no option isspecified, the default action is to print error messages, warnings,and informational messages, but not the program listing or symbol tables.

Each option begins with the '-' character.(On VAX/VMS or MS-DOS systems you may use either '/' or '-'.)For the sake of conformity with a common convention, options canalso begin with '--'.The options are described at greater length in the next section.

ftnchek options fall into two categories: switches, which are eithertrue or false, and settings, which have a numeric or string value. Thename of a switch is prefixed by 'no' or 'no-' to turn it off:e.g. -nopurewould turn off the warnings about impure functions. The 'no' prefixcan also be used with numeric settings, having the effect of turningoff the corresponding warnings.Settings that control lists of warnings have a special syntax discussedbelow.Only the first 3characters of an option name (not countingthe '-')need be provided.A colon may be used in place of an equals sign for numeric or string settingassignments; however, we show only the equals sign form below.

The switches and settings which ftnchek currently recognizes arelisted below. For each option, the default is the value used if theoption is not explicitly specified, while the turn-on is the valueused if the option is given without assigning it a value.

-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 appliedcalltree option, a file named CallTree.html, will be produceddepicting the tree in HTML format.
-check: Perform checking. Default = yes.
-columns=num: Set maximum line length to num columns. (Beyondthis is ignored.) Turn-on = max = 10000. 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/orCOMMON block use. Default = none.
-declare: Print a list of all identifiers whose datatype is notexplicitly declared. Default = no.
-division: Warn wherever division is done (except division by aconstant). Default = no.
-errors=num: Set the maximum number of error messages per cascade. Default =turn-on = 3.
-extern: Warn if external subprograms which are invokedare never defined. Default = yes.
-f77=list: Control specific warnings about supported extensions to the Fortran 77Standard. Default = none, turn-on = all.
-f90=list: Control specific warnings about supported extensions to the Fortran 90Standard.Default = none, turn-on = all.
-f95=list: Control specific warnings about standard Fortran 77features 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 thesystem-wide directory.Cumulative. Default = turn-on = none.
-intrinsic=list: Control treatment of nonstandard intrinsic functions. Default =all except vms for Unix version, all except unixfor VMS version, all except unix and vms for otherversions. Turn-on = all.
-library: Begin library mode: do not warn about subprogramsin 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 forthe 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 theroot HTML file CallTree.html.Default = none, turn-on = documents.
-module=path: Define a directory into which to write module files, and alsoto search for module files referenced in USE statements.Default = directory of source file, turn-on = none.
-novice: Give output suitable for novice users. Default = yes.Advanced users will want to turn this off to give output suitable forparsing by IDEs and context-aware editors like emacs.
-output=filename: Send output to the given file.Default and turn-on sends output to the screen. (Default filenameextension 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 appearanceof 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.
-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 Fortrantab-formatted lines, VMS-style INCLUDE statement,UNIX-style backslash escape sequences,and implicit typing of parameters. Default = none (fixed or free forminferred from file extension), turn-on = all.
-style=list: Produce extra-picky warnings about obsolescent or old-fashionedprogramming 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.
-type=list: Check for issues related to user-defined types.Default = turn-on = all.
-usage=list: Control warnings about unused or uninitialized variables, commonblocks, etc. Default = turn-on = all.
-version: Print version number. Default = no.
-wordsize=num: Set the default word size for numericquantities to num bytes. Default = turn-on = 4 bytes.
-wrap=num: Set output column at which to wrap long error messages andwarnings to the next line. If set to 0, turn off wrapping. Default =turn-on = 79.

When more than one option is used, they should be separated by a blankspace, except on systems such as VMS where options begin with slash ( / ).No blank spaces may be placed around the equals sign ( = ) in a setting.ftnchek "?"will produce a command summary listing all options and settings.

For settings that take a list of keywords, namely-arguments,-array,-calltree,-common,-crossref,-f77,-f90,-f95,-intrinsic,-makedcls,-mkhtml,-portability,-pretty,-project,-source,-style,-truncation,-type,and-usage,the list consists of keywordsseparated by commas or colons.If the list of keywords is omitted, theeffect is to set the option to its turn-on value (same as ``all'' in mostcases).Also, if thelist is omitted, the setting name can be prefixed with no orno- toturn off all the options it controls. For example, -f77 turnson all warnings about nonstandard constructions, while-nof77 turns them all off. Three special keywords are:

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.

For example, -f77=help gives a list of all the keywordscontrolled by the -f77 option, -f77=all turns them allon, and -f77=all turns them all off.These three special keywords must be given in full. For all otherkeywords, only as many letters of the keyword as are necessary toidentify it unambiguously need be given, or a wildcard patternmay be used. Including a keyword in thelist turns the corresponding option on.For example, -f77=intrinsic wouldturn on only the warnings about use of nonstandard intrinsic functions.Prefixing a keyword by no- turns its option off.For example,-pretty=no-long-line turns off warnings about linesexceeding 72 columns in length while leaving all other warnings aboutmisleading appearance in effect.If a setting has default none, you can turn on all optionsexcept one or two by using all first.For example,-f77=all,no-intrinsic enables warnings about all nonstandardextensions except intrinsic functions.If a setting has default all, you can turn off all warningsexcept one or two by using none first.For example,-truncation=none,demotion would turn off all precision relatedwarnings except about demotions.Wildcard patterns contain an asterisk to stand for any string ofcharacters. If a wildcard pattern is used, all the warnings thatmatch it are affected. If no- is prefixed to the pattern, allthe matching warnings are turned off, otherwise they are all turnedon. The minimum unambiguous length rule does not apply to wildcardmatching. For example, use -usage=no-*var* to turn offall warnings relating to variable usage (both local and common).(Unix users may need toquote any options containing wildcards in order to prevent the shellfrom attempting to expand them.)Wildcards are recognized only in lists of warning keywords, not in thetop-level options themselves.

When ftnchek starts up, it looks for environment variablesand also for a preferences file.Any options defined in the environment or in the preferences file areused as defaults in place of the built-in defaults. They areover-ridden by any command line options.See the section on changing the defaults for details about theenvironment options and the preferences file.

When giving a name of an input file, the extension is optional. If noextension is given, ftnchek will first look for a project filewith extension .prj, and will use that if it exists. If not, thenftnchek will look for a Fortran source filewith the extension .for for VMS systems, .f for UNIX systems.The default source format for files with extension .for or .fis fixed format. If the input file is in free format, use extension.f90 or any other suffix (or specify -source=free on thecommand line).More than one file name can be given to ftnchek,and it will process theprogram units in all files as if they were in a single file.

Wildcards are allowed in the specification of filenames on the commandline for the VMS and MS-DOS versions,as also of course under UNIX and any other system that performswildcard expansion in the command processor.

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

OPTIONS

This section provides a more detailed discussion of ftnchekcommand-line options. Options and filenames may be interspersed on acommand line. Most options are positional: each option remains ineffect from the point it isencountered until it is overridden by a later change. Thus forexample, the listing may be suppressed for some files and not forothers. Exceptions are: the -intrinsic, -pointersize,and -wordsize settings, which cannot bechanged once processing of input files has started;the-arguments,-array,-calltree,-common,-crossref,-extern,-resources,and-sortoptions, where the action depends only on the value ofthe 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 aboutmismatches between actual and dummy subprogram arguments, and alsoabout mismatches between expected and actual subprogram type. (An actualargument is an argument passed to the subprogram by the caller; adummy 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 byno- to turn off a particular warning.There are three special keywords: all to turn on all thewarnings about arguments, none to turn them alloff, and help to print the list of all the keywords with a briefexplanation 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 adifferent type than it actually is. Also warns if a function iscalled as a subroutine, or vice-versa.
number:: warn about invoking a subprogram with a different number of argumentsthan the subprogram expects.

For compatibility with previous versions of ftnchek, a numericform of this setting is also accepted: the list is replaced by anumber from 0 to 3. A value of 0 turns all the warnings off,1 turns on only number, 2 turns on allexcept number, and 3 turns all the warnings on.

This setting does not apply to checking invocationsof intrinsic functions or statement functions, which canonly be turned off by the -nocheck option.

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

-array=list

Controls the degree of strictness in checkingagreement between actual and dummy subprogram arguments that are arrays.The warnings controlled by this setting are for constructions that mightlegitimately be used by a knowledgeable programmer, but that oftenindicate 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 byno- to turn off a particular warning.There are three special keywords: all to turn on all thewarnings about array arguments, none to turn them alloff, and help to print the list of all the keywords with a briefexplanation 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 argumentis a whole array.
size:: warn if both arguments are arrays, but they differ in numberof elements.

For compatibility with previous versions of ftnchek, a numericform of this setting is also accepted: the list is replaced by anumber from 0 to 3. A value of 0 turns all the warnings off,1 turns on only dimensions, 2 turns on onlysize, and 3 turns all the warnings on.

Note:A warning is always given regardless of this setting if the actualargument is an array while the dummy argument is a scalar variable, orif the actual argument is a scalar variable or expression while thedummy argument is an array. These cases are seldom intentional.(To turn off even these warnings, use -arguments=no-arrayness.)No warning is ever given if the actual argument is an arrayelement while the dummy argument is a scalar variable.Variable-dimensioned arrays and arrays dimensioned with 1 or asterisk match anynumber of array elements.There is no check of whether multi-dimensional arrays agree in thesize of each dimension separately.

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

-brief

: Selects a shorter format for some warning messages. At present, theonly warnings controlled by this flag are those that are printed atthe end of processing each subprogram. These include warnings aboutvariables that are set but not used or used before set, variable namesthat do not conform to the Fortran 77 standard, etc. (These warningsmay be suppressed entirely depending on other flags, such as the-usage or -f77 flags.) In the default format eachvariable is listed on a separate line, along with the line numberwhere the variable is declared, set or used, according to the natureof the warning. The briefer format simply lists all variables towhich the warning applies, with up to 4 variables per line.
See also: -quiet.

-calltree=list

Causes ftnchek to print out the call structure ofthe complete program.NOTE: at this time, this option is not workingcorrectly for programs containing or using module subprograms.

The list consists of keywords separated by commas or colons.There are two special keywords: none to turn off all theoptions, andhelp to print the list of all the keywords with a briefexplanation of each. (The keyword all turns on all theoptions, but should not normally be used since only one format shouldbe 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 appliedcalltree option, a file named CallTree.html, will also be produceddepicting the tree in HTML format. This file is useful as a startingpoint for browsing the HTML files describing each component of theprogram.

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.
vcg:: produce the call graph in VCG format.

Only one of the formats tree, reference, or vcg maybe specified.

The following keywords control options affecting the output:

prune:: prune repeated subtrees (applicable only with tree). Thisthe default.
sort:: sort children of each routine into alphabetical order. This is the default.

For tree format, the call graph is printed outstarting from the main program, which is listed on the first line atthe left margin. Then on the following lines, each routine called bythe main program is listed, indented a few spaces, followed by thesubtree starting at that routine.

In the default mode,if a routine is called by more than one other routine,its call subtree is printed only the first time it is encountered.Later calls give only the routine name and the notice ``(see above)''.To have the subtree printed for each occurrence of the routine,use option no-prune.

Note that the call tree will be incomplete if any of the input filesare project files containing more than one program unitthat were created in -library mode. See thediscussion of project files below.

Technical points: Each list of routines called by a given routine isprinted in alphabetical order unless the no-sort option is given.If multiple main programs are found, the call tree of each is printedseparately.If no main program is found, a report to that effect is printed out,and the call trees of any top-level non-library routines are printed.See the discussionof the -library flag.

For reference format a who-calls-who table is printed.This table lists each subprogram followed by a list of theroutines it calls.

The reference list omits routinescalled by unused library program units. Thus it contains the sameinformation as for the call-tree format, namely the hierarchy ofsubprogram calls, but printed in a different way. This prints outa breadth-first traversal of the call tree whereas -calltree=tree printsout a depth-first traversal.

For vcg format the call tree is producedin the form of a VCG graph description. Thisdescription is written to a separate file, with the same stem as thefile containing the main program, and suffix.vcg.This file is able to be given directly toxvcg(1L)to visualize the call graph.(If input is from the standard input, then the graph description issent to standard output.)

The VCG description as created is more complex than it need be. VCG allowsgraphs and nested subgraphs: each subroutine is created as asubgraph nested inside its calling routines. This allows you tointeractively display subgraphs or summarise them.

The-calltree=vcgoption forftnchekwas written by Dr. Philip Rubini of Cranfield University, UK.

xvcg(1L) 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. Sanderof the University of Saarland, Germany.

For compatibility with previous versions of ftnchek, a numericform of this setting is also accepted: the list is replaced by anumber from 0 to 15. This number is formed from 1 fortree format, 2 for reference format, or 3 for vcgformat, plus 4 for no-prune, and 8 for no-sort.

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

-check

This switch is provided so that errors and warning messages can beturned off when ftnchek is used for purposes other than findingbugs, such as making declarations or printing the call tree. It ispositional, so after turning all checks off, selected checks can beturned back on. The effect of -nocheck is to put all switches,numeric settings, and settings controlling lists of warningsto their turn-off values, as if they had all beenspecified with the -no prefix.NOTE: in ftnchek version 4, many new warnings were introduced,and some may not have been put under the control of this switch. Weare working on this.

Switches and settings that specifyoptions and modes of operation, rather than controlling warnings, areunaffected.These are-calltree,-columns, -crossref,-include, -intrinsic,-library, -list,-makedcls,-module,-novice,-output,-pointersize, -project,-quiet,-resources,-sort, -source, -symtab,-version,-wordsize,and-wrap.Default = yes.

Parse errors (syntax errors due to unrecognized or malformedstatements) are not suppressed by this switch, since the results maybe incorrect if ftnchek has not parsed the program correctly.

There are some miscellaneous errors and warning messages that are notcontrolled by any other switch, and so can be turned off only by thisswitch. Note that using -check following -nocheck onlyhas the effect of turning these special warnings back on, and does notrestore all the checks it turned off. These warnings include:

o: Program unit contains no executable statements.
o: In free source form, missing space where space is required(e.g. between a keyword and an identifier) or spacepresent where none is allowed (e.g. within an identifier).
o: Zero or negative length specification in a data type declaration of theform 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 anINTRINSIC statement.
o: Intrinsic function passed as a subprogram argument is not declaredin 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'sname.
o: Unknown keyword used in an I/O statement.
o: Illegal label reference (e.g. GOTO refers to a non-executablestatement; I/O statement refers to a non-format statement).

CHANGING THE DEFAULTS

ftnchek includes two mechanisms for changing thedefault values of all options:by defining environment variablesor by creating a preferences file.When ftnchek starts up,it looks in its environment for any variables whose names are composed byprefixing the stringFTNCHEK_onto the uppercased version of the optionname. If such avariable is found, its value is used to specify the default for thecorresponding switch or setting. In the case of settings (for example,the -common strictness setting)the value of the environment variable is read as thedefault setting value. In the case of switches, the default switch willbe taken as true or yes unless the environment variable has the value0 or NO.

Note that the environment variable name must be constructed with thefull-length option name, which must be in uppercase. For example, tomakeftnchek print a source listing by default, set the environmentvariableFTNCHEK_LISTto 1 or YES or anything other than 0 or NO.The namesFTNCHEK_LIS(not the full option name) orftnchek_list(lower case) would not be recognized.

Here are some examples of how to set environment variables on varioussystems. For simplicity, all the examples set the default -listswitch to YES.
1. UNIX, Bourne shell: $ FTNCHEK_LIST=YES
$ export FTNCHEK_LIST

2. UNIX, C shell: % setenv FTNCHEK_LIST YES

3. VAX/VMS: $ DEFINE FTNCHEK_LIST YES

4. MSDOS: $ SET FTNCHEK_LIST=YES

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

Each option or setting in the preferences file must be on a separateline. They are given in the same form as on the command line, exceptwithout the initialdash.The preferences file can contain blank lines and comments. Commentsare introduced at any point in a line by a space character (blank ortab) or the '#' character, and are terminated by the end of the line.

Command-line options override the defaults set in the environmentor in the preferences file, in the same way as theyoverride the built-in defaults.

USING PROJECT FILES

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

NOTE: project files were designed for Fortran 77 code and do not workcorrectly for program units containing or using modules. There are noplans to upgrade them to do so. Modules provide all the benefits ofproject files and more besides, so if you are writing new Fortran codethat uses modules you should not need project files. (You can stillmake and use project files for any source files that do not define oruse modules themselves. For instance, if your own code uses modulesbut calls external procedures in a library written in Fortran77, you can make a project file of the latter and include it alongwith your own source for input to ftnchek.)

One can divide the checksftnchek does into two categories, local and global. Localchecking is restricted to within a single routine,and catches things like uninitialized variables, unintended lossof precision in arithmetic expressions, etc. This sort of checkingcan be done on each subprogram independently. Furthermore,local checking of a subprogram does not need to be repeated when some othersubprogram is changed. Global checking catches things like calling asubroutine with the wrong argument types, or disagreeing in commonblock declarations. It requires looking at the whole set of subprogramsinteracting with each other.

The purpose of project files is to allow the local checking and globalchecking steps to be separated. Assuming that each subprogram is inits own source file, you can run ftnchek once on each one to do localchecking while suppressing global checking.Then ftnchek can be run once on all the projectfiles together to do the global checking. The sample makefile belowshows how to automate this task. The ``.f.prj'' target updates aproject file for a particular file any time the source file changes.The information needed for global checking is savedin the project file.The ``check'' target does the combined global checking.Typically ``make check'' would repeat the ``ftnchek-project'' step only on changed sourcefiles, then do the global check. This is obviously a big advantagefor large programs, when many subprograms seldom if ever change.

It is best when using project files to place each subprogramin a separate source file. If each source file may contain more than onesubprogram, it complicates the definition of ``local'' and ``global''checking because there is some inter-program unit checking that is containedwithin a file. ftnchek tries to do the right thing in thiscase, but there are some complications (described below) due to thetrade-off between avoiding re-doing cross-checks and preservinginformation about the program's structure.

Ordinarily, to do the least amount of re-checking, project files should becreated with the -libraryflag in effect and trimming turned on. In this mode,the information saved in the project file consists of all subprogramdeclarations, all subprogram invocations not resolved by declarations in thesame file, and one instance of each COMMONblock declaration. This is the minimum amount of information neededto check agreement between files.

If the source file contains more than one routine, there are somepossible problems that can arise from creating the project file inlibrary mode, because the callinghierarchy among routines defined within the file is lost. Also,if the routines in the file make use of COMMONblocks that are shared with routines in other files, there will not beenough information saved for the correct checking of set and usedstatus of COMMON blocks and COMMON variables according to the-usage setting. Therefore ifyou plan to use project files when -usagechecking is turned on (which is the default situation), and ifmultiple routines in oneproject file share COMMON blocks with routines in other files,the project filesshould be created with the -library flag turned off.In this mode, ftnchek saves, besidesthe information listed above, one invocation of each subprogram byany other subprogram in the same file, and all COMMON blockdeclarations. This means that the project file will be larger thannecessary, and that when it is read in, ftnchek may repeat someinter-program unit checks that it already did when the project file wascreated. If each project file contains only oneprogram unit, there is no loss of information in creating the projectfiles in library mode.

Because of the possible loss of information entailed by creating a project filewith the -library flag in effect, whenever that project file is readin later, it will be treated as a library file regardless of thecurrent setting of the -library flag. On the other hand, a projectfile created with library mode turned off can be read in later in eithermode.

The foregoing discussion assumes that the trimming options of the-project setting are turned on when the project file iscreated. This is the normal situation. The no-trim options ofthe -project setting are provided in case one wants to use theproject files for purposes other than checking the program withftnchek. For instance, one could write a Perl script to analyzethe project files for information about how the different subprogramsare called. You should not use the no-trim options to dealwith the issues of information loss discussed above, since they causemore information than necessary to be stored. This makes the projectfiles bigger and causes ftnchek to do more work later when it readsthem to check your complete program. Ordinarily, you should use the-library option to control how much information to store forlater use by ftnchek in checking your program.

Here is an example of how to use the UNIX make utility toautomatically create a new project file each time the correspondingsource 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 whichlists all the names of object files to be linked together to form thecomplete executable program.(In this makefile, the indented lines should each begin with atab, not blanks.)If any source file contains multiple routines that sharecommon blocks among themselves, then the no-com-\* optionshould 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 ofdifferent source files in different directories, it can becumbersome to specify all the different project files needed to checkthe program properly. To deal with such cases, ftnchek allowsproject files to be concatenated into a single large file. Thissingle file can then be given to ftnchek to provide theinformation for checking the use of any or all of the routines definedin the combined project files. When using such a ``library''project file, you may want ftnchek's error reports to documentprecisely 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 rathershould include the path to the file. The solution is to createeach of the individual project files by giving the complete path tothe source file. Then this complete path will appear in the errorreports. For example, suppose that all of the library subprogramsource files are in subdirectories of a directory named/util/lib. Then the individual project filescould first be created by a command such as

find /util/lib -name '*.f' -exec ftnchek -project '{}' ';'

(Possibly other options would be provided to ftnchek asdiscussed above. Also, this step could be handled instead by arevised makefile rule that would provide the completesource file path instead of just the local name when invokingftnchek.) Next, concatenate all of these project files manually.

find /util/lib -name '*.prj' -exec cat '{}' ';' > ourlib.prj

Then a program source file can be checked by using the command

ftnchek prog.f ... -lib ourlib.prj

and an error message related to any library routine will includethe full path to the routine's source file.

At present, there is no archive utility like ar to manage thecontents of a concatenated project file like the one in theillustration above. If changes are made to one of the libraryroutines, the only way to update the combined project file is toconcatenate all the individual project files once again. Such autility would be quite easy to write. Someone should do so andcontribute it to the ftnchek effort.

AN EXAMPLE

The following simple Fortran program illustrates the messages given byftnchek.The program is intended to accept an array of test scoresand then compute the average for the series.

C       AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLOC       DATE:    MAY 8, 1989C       Variables:C               SCORE -> an array of test scoresC               SUM ->   sum of the test scoresC               COUNT -> counter of scores read inC               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 AVENUMCC                       MAIN PROGRAMCC       AUTHOR:   LOIS BIGBIEC       DATE:     MAY 15, 1990CC       Variables:C               MAXNOS -> maximum number of input valuesC               NUMS    -> an array of numbersC               COUNT   -> exact number of input valuesC               AVG     -> average returned by COMPAVC               I       -> loop counterC            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 + 180          CONTINUE100         AVG = COMPAV(NUMS, COUNT)        END

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

$ run average709085<EOF>$

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

$ ftnchek -list -symtab averageFTNCHEK Version 4.beta July 2012File 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         ENDProg unit COMPAV: func: realVariables:       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 prog unit COMPAV: Variables declared but never used or set:    J declared at line 11Warning in prog unit COMPAV: Variables may be used before set:    SUM used at line 14    SUM set at line 14Statement 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         ENDProg unit AVENUM: progExternal 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 prog unit AVENUM: Variables set but never used:    AVG set at line 43I/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.fWarning: Subprogram COMPAV argument data type mismatch at position 1:    Dummy arg SCORE in prog unit COMPAV line 10 file average.f is type intg    Actual arg NUMS in prog unit AVENUM line 43 file average.f is type real

According to ftnchek,the program contains variables which may beused before they are assigned an initial value, and variables whichare not needed. ftnchek also warns the user that an integerquotient has been converted to a real. This may assist the user incatching an unintended roundoff error. Since the -symtab flagwas given, ftnchek prints out a table containing identifiers fromthe local program unit and their corresponding datatype and number ofdimensions. Finally, ftnchek warns that the functionCOMPAV is not usedwith the proper type of arguments.

With ftnchek'shelp, we can debug the program. We can see that therewere the following errors:

1.: SUM and COUNTshould 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 INTEGERinstead of REAL.

We also see that I, not J, should have been declaredINTEGER in function COMPAV. Also, MAXNOS was notdeclared as INTEGER, nor COMPAV as REAL, inprogram AVENUM. These are not errors, but they may indicatecarelessness. As it happened, the default type of these variablescoincided with the intended type.

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

C       AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLOC       DATE:    MAY 8, 1989CC       Variables:C               SCORE -> an array of test scoresC               SUM ->   sum of the test scoresC               COUNT -> counter of scores read inC               I ->     loop counterC       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)        ENDCC        PROGRAM AVENUMCC                       MAIN PROGRAMCC       AUTHOR:   LOIS BIGBIEC       DATE:     MAY 15, 1990CC       Variables:C               MAXNOS -> maximum number of input valuesC               NUMS    -> an array of numbersC               COUNT   -> exact number of input valuesC               AVG     -> average returned by COMPAVC               I       -> loop counterCC            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 + 180          CONTINUE100         AVG = COMPAV(NUMS, COUNT)            WRITE(6,*) 'AVERAGE =',AVG        END$ run average709085<EOF>AVERAGE =   81.66666$

With ftnchek'shelp, our program is a success!

INTERPRETING THE OUTPUT

The messages given byftnchek include not onlysyntax errors but also warnings and informational messagesabout things that are legal Fortran but that may indicate errors orcarelessness.Most of these messages can be turned off bycommand-line options. Which option controls each messagedepends onthe nature of the condition being warned about. See thedescriptions 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 natureof the condition and its severity.

NOTE: this section does not attempt to list all of ftnchek'swarnings and error messages. There are far too many to documenteach. Hopefully the examples given here will provide enough guidancefor you to interpret all of the messages you may see.

``Error'' means a syntax error. The simplestkind of syntax errors are typographical errors, for example unbalancedparentheses or misspelling of a keyword. This type of error is caughtby the parser and appears with the description ``parse error'' or``syntax error'' (depending on the version of the parser generator and whetherit is GNU bison or UNIX yacc).This type of error message cannot besuppressed. Be aware that this type of error often meansthat ftnchek has not properly interpreted the statement where theerror occurs, so that its subsequent checking operations will becompromised. You should eliminate all syntax errors before proceeding tointerpret the other messages ftnchek gives.

``Warning: Nonstandard syntax'' indicates an extension to Fortran thatftnchek supports but that is not according to the Fortran 77 orFortran 90 Standard.The extensions that ftnchek acceptsare described in the section on Extensions below.These are typically features supported by many compilers even thoughthey are not standard.One example is the TYPE output statement.If a program uses these extensions, warnings will begiven according to specifications under the -f77 and-f90 settings.The default behavior is to give no warnings.

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

Truncation warnings cover situations in which accuracy may be lostunintentionally, for example when a double precision value is assignedto 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 beaccepted by some compilers even though it is not contraryto the Fortran Standard, or that may cause the program to performdifferently on different platforms.For example, equivalencing realand integer variables is usually a non-portable practice.The use of extensions to the standard language is, of course, anothersource of non-portability, but this is handled as a separate case. Tocheck a program for true portability, both the -portability andthe -f90 flags should be used. They are both turned off bydefault. The -wordsize setting is provided to check only thosenonportable usages that depend on a particular machine wordsize.

``Possibly misleading appearance'' is used for legal constructions that may notmean what they appear to mean at first glance. For example,in fixed-form Fortran sourceblank spaces are not significant, so extraneous space within variable namesor the lack of space between a keyword and a variable can convey the wrongimpression to the reader.These messages can be suppressed by turning off the -prettyflag, which is on by default.

Other messages that are given after all the files are processed,and having to do with agreement between program units, do not use the word``warning'' but generally fall into that category.Examples include type mismatches between corresponding variables indifferent COMMONblock declarations, or between dummy and actual arguments of asubprogram.These warnings are controlled by the -common and-arguments settings respectively. By default both are set formaximum strictness of checking.

Another group of warnings about conditions that are often harmlessrefer to cases where the array properties of a variablepassed as a subprogram argument differ between the two routines.For instance, an array element might be passed to a subroutine thatexpects a whole array. This is a commonly-used technique forprocessing 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 ofstrictness to be used in checking this kind of agreement betweenactual and dummy array arguments. By defaultthe strictness is maximum.

``Oops'' indicates a technicalproblem, meaning either a bug in ftnchek or that its resources havebeen exceeded.

The syntax error messages and warnings includethe filename along with the line number and columnnumber. ftnchek has two different options for theappearance of these error messages. If -novice is in effect,which is the default,the messages are in a style approximatingnormal English. (In default style, the filename isnot printed in messages within the body of the program if -list is ineffect.) The other style of error messages is selected by the-nonovice option. In thisstyle, the appearance of the messages is similar to that of theUNIX lint program.

ftnchek is still blind to some kinds of errors.The most important one is detailed checking of FORMAT statementsagainst their I/O lists. But there are many others that any compilerwill catch. Our efforts have always been concentrated on producingwarnings about errors that compilers typically do not warn about.See the section on Limitations for a more detailed discussion.

If ftnchek gives you a syntax error message when the compiler doesnot, it may be because your program contains an extension tostandard Fortran which is accepted by the compiler but not byftnchek. (See the section on Extensions.)On a VAX/VMS system, you can use the compiler option /STANDARDto cause the compiler to accept only standard Fortran.On most UNIX or UNIX-like systems, this can be accomplished bysetting the flag -ansi. The gfortran(1) compiler fromthe GNU project accepts a flag -std=f95 to enforce compliancewith Fortran 95.

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

Common block NAME: data type mismatch at position n

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

     COMMON /COM1/ A,Band     COMMON /COM1/ A(2)

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

Common block NAME has long data type following short data type

Some compilers require alignment of multi-byte items so that each itembegins at an address that is a multiple of the item size. Thus if ashort (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 Fortran 77 standard requires that if any variable in a COMMONblock is of type CHARACTER, then all other variables in thesame COMMON block must also be of type CHARACTER.In Fortran 90 this requirement is relaxed, so long as correspondingstorage locations have the same type.Controlled by -f77=f90 option.

Common block NAME: varying length

For -common setting level 2, this message means thata COMMON block is declared to have different numbers of words in twodifferent subprograms. A word is the amount of storage occupied byone integer or real variable.For -common setting level 3, it means that the two declarationshave different numbers of variables, where an array of any size isconsidered one variable.This is notnecessarily an error, but it may indicate that a variable is missingfrom 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 differin number of words in declarations in different program units.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 ofone of the special words that begin andend 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 prog unit NAME

A character variable cannot be declared with a size that is anasterisk in parentheses unless it is a dummy argument, a parameter, orthe name of the function defined in the program unit.

Error: cannot be declared in SAVE statement in prog unit NAME

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

Error: No path to this statement

ftnchek will detect statements which are ignored or by-passed becausethere is no foreseeable route to the statement. For example, anunnumbered statement (a statement without a statement label), occurringimmediately after a GOTOstatement, cannot possibly be executed.

Error: Parse error

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

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

Error: Syntax error

This is the same as ``Error: Parse error'' (see above). It is generatedif your version of ftnchek was built using the UNIX yaccparser 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 notdiffer in the first 6 characters. This is for portability: they may notbe 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 beincorrect on some computers. Issued when a numeric variable declaredwith explicit precision (e.g. REAL*8 X) is passed to aspecific 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 255characters in length.Controlled by -portability=long-string.

Nonportable usage: File contains tabs

ftnchek expands tabs to be equivalent to spaces up to the next columnwhich is a multiple of 8. Some compilers treat tabs differently, andalso it is possible that files sent by electronic mail will have the tabsconverted to blanks in some way. Therefore files containing tabs may notbe compiled correctly after being transferred. ftnchek does not givethis 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 arenon-integer.Use of non-integer quantities in a DO statement may causeunexpected errors, or different results on different machines, due toroundoff effects.Controlled by -portability=real-do.

Possibly it is an array which was not declared

This message is appended to warnings related toa function invocation or to an argument typemismatch, for which the possibility exists that what appears to be afunction is actually meant to be an array. If the programmer forgot todimension an array, references to the array will be interpreted asfunction invocations. This message will be suppressed if the name inquestion 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 itsstandard value of 72, and some nonblank characters have been foundpast column 72. In this case,ftnchek is not processing the characters past column 72, and isnotifying the user that the statement may not have the meaning that itappears to have. These characters might be intended by the programmer to besignificant, 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 asa continuation of the original declaration of the block.This warning is only given if the two declarations are separated byone 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 acontinuation of a statement is interspersed with comments, making it easyto overlook.Controlled by -pretty=continuation.

Possibly misleading appearance: Extraneous parentheses

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

Subprogram NAME: argument data type mismatch at position n

The subprogram'sn-th actual argument (in the CALL or theusage of a function) differs in datatype or precision from the n-th dummyargument (in the SUBROUTINE or FUNCTIONdeclaration). For instance, if the user defines asubprogram by

     SUBROUTINE SUBA(X)     REAL X

and elsewhere invokes SUBA by

     CALL SUBA(2)

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

     CALL SUBA(2.0)

When checking an argument which is a subprogram, ftnchek must beable to determine whether it is a function or a subroutine. The rulesused by ftnchek to do this are as follows: If the subprogram,besides being passed as an actual argument, is also invoked directlyelsewhere in the same program unit, then its type is determined by thatusage. If not, then if the name of the subprogram does not appear inan explicit type declaration, it is assumed to be a subroutine; if itis explicitly typed it is taken as a function. Therefore, subroutinespassed as actual arguments need only be declared by an EXTERNALstatement in the calling program unit, whereas functions must also beexplicitly 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, butthe subprogram dummy argument differs from the corresponding actualargument 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 actualargument, or a Hollerith dummy argument is larger than thecorresponding actual argument. Controlled by -arguments setting.

Subprogram NAME: argument usage mismatch

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

Dummy arg is modified, Actual arg is const or exprA dummy argument is an argument as named in a SUBROUTINE orFUNCTION statement and used within the subprogram. An actualargument is an argument as passed to a subroutine or function by thecaller. ftnchek is saying that a dummy argument is modified bythe subprogram, implying that its value is changed in the calling program unit.The corresponding actual argument should not be a constant orexpression, but rather a variable or array element which can belegitimately assigned to.Controlled by the -usage=arg-const-modified option.

Dummy arg used before set, Actual arg not setHere a dummy argument may be used in the subprogrambefore having a value assigned to it by the subprogram. Thecorresponding actual argument should have a value assigned to it by thecaller prior to invoking the subprogram.Controlled by the -usage=var-uninitialized option.

This warning is not affected by the -arguments setting.

Subprogram NAME invoked inconsistently

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

     INTEGER FUNCTION COUNT(A)

and invokes COUNT in another subprogram as

     N = COUNT(A)

without declaring its datatype, it will default to real type, based onthe first letter of its name. The calling subprogram should have includedthe declaration

     INTEGER COUNT

Given for -arguments setting 2 or 3.

Subprogram NAME: varying length argument lists:

An inconsistency has been found between the number of dummy arguments(parameters) a subprogram has and the number of actual arguments given itin an invocation.ftnchek keeps track of all invocations of subprograms(CALLstatements and expressions using functions) and compares them withthe definitions of the subprograms elsewhere in the source code. TheFortran 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 program unit,ftnchek will flag with an asteriskall identifiers that are not explicitly typedand will show the datatype that was assigned through implicit typing.This provides support for users who wish to declare all variables asis 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 allundeclared variables.

Variables declared but never referenced

Detects any identifiers that were declared in your program but werenever used, either to be assigned a value or to have their valueaccessed. 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 avalue, but the variable is not otherwise used in the program. Usuallythis 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 valueprior to its initialization. Such usage may lead to an incorrect valuebeing 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 todetermine its status with certainty. ftnchek assumes a variablemay be used before set if the first usage of the variable occurs priorin 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, butthe DO index is not. It may indicate a failure to declare theindex 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, inwhich the fractional part is dropped. If such an integer expressioninvolving division is later converted to a real datatype, it may be thata 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, inwhich the fractional part is dropped. If such an integer expressionis used as an exponent, it is quite likely that a real type division wasintended.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 thevalue to the name of the function. This message indicates that thefunction was not assigned a value before the point where aRETURN statement was found. Therefore it is possible that thefunction 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 variableswhose size is an asterisk in parentheses, except in an assignmentstatement. 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 fixed-form Fortran ignores all text in those columns, but some compilersdo not. Thus the program may be treated differently by differentcompilers.

Warning: Nonstandard syntax : Statement out of order.

ftnchek will detect statements that are out of thesequence specified for ANSI standard Fortran 77. Table 1 illustrates theallowed sequence of statements in the Fortran language. Statements which areout of order are nonetheless interpreted byftnchek,to prevent ``cascades'' of error messages.The sequence counter is also rolled back to preventrepetition 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 divisionby a constant). Use it tohelp 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 realexpression on the right, but an integer variable on the left. Thefractional part of the real value will be lost. If you explicitlyconvert the real expression to integer using the INT orNINT intrinsic function, no warning will be printed. A similarmessage is printed if a double precision expression is assigned to asingle precision variable, etc.Controlled by -truncation=demotion option.

Warning: subscript is not integer

Since array subscripts are normally integer quantities, the use of anon-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 anINTRINSIC statement is unknown to ftnchek. Probably it isa nonstandard intrinsic function, and so the program will not beportable. The function will be treated by ftnchek as auser-defined function. This warning is not suppressed by anyoption, since it affects ftnchek's analysis ofthe program. However, if the intrinsic function is in one of thesupported sets of nonstandard intrinsics, you can use the-intrinsic setting to cause ftnchek to recognize it.

LIMITATIONS AND EXTENSIONS

ftnchek now accepts ANSI standard Fortran 95 programs with a few exceptions and some common non-standard extensions. It stillaccepts Fortran 77 conforming code, even if it contains featuresdeleted in Fortran 95. The behavior of ftnchek on Fortran 77source code is unchanged from the previous version, 3.3.1, apart fromsome minor wording changes on messages.

Limitations:

INTERFACE statements, generic functions, overloaded operators, anduser-defined operators are not yet supported. ftnchek parsesthese elements but does not interpret them, so many bogus errormessages can be expected for programs that use them. Supporting theselanguage elements is a high priority and should be completed shortly.

Optional arguments in user-defined functions are not supported. Theywill generate warnings about inconsistency between function call anddefinition.This defect is expected to be fixed very soon.Optional arguments are supported for intrinsic functions.

When tracking array-valued expressions, the detailed shape of arraysis not recorded, only the overall length. When ftnchek cannotdetermine whether the size of an array or array section does not matchanother array-valued object in an expression or assignment, it assumesit is OK and does not issue a warning. Thus some shape mismatches maybe missed. Storing array shapes is a high priority for a futureversion of ftnchek.

Related to this, array-valued constants are not stored. Thus if anarray constructor is used as the SHAPE argument in RESHAPE,ftnchek will not be able to determine the shape of the result.We plan to have ftnchek store array-valued parameters whosevalues are compile-time integer constants.

When parameters are defined for use in declaring array sizes orcharacter lengths, or as kind parameters, ftnchek will try toevaluate them to allow better checking.However, it is not able to evaluate all intrinsic functions. It doesnot evaluate those that yield real or complex values.The intrinsic functions that are evaluated are:

ABS	ICHAR	KIND	MIN	SELECTED_INT_KIND
DIM	IDIM	LEN	MIN0	SELECTED_REAL_KIND
IABS	INDEX	MAX	MOD	SIGN
IACHAR	ISIGN	MAX0	MODULO	SIZE

The functions of integer arguments are evaluated only if the argumentsare integer constant expressions. (These may involve integerconstants, parameters, and evaluated intrinsic functions.) Thefunction LEN is evaluated if its argument is an expressioninvolving only character constants and variables whose length is notadjustable. The functions ICHAR, IACHAR, and INDEX are evaluatedonly if the arguments are character constants. The function KIND isevaluated for any argument. The function SIZE is evaluated for anyarray argument whose size is fixed. ftnchek gives awarning if it needs the value of some intrinsic function that is notevaluated.

COMMON blocks and NAMELISTs in modules do not get exported. Thisdefect should be fixed soon.

The dummy arguments in statement functions are treated like ordinaryvariables of the program. That is, their scope is the entire subprogram, notjust the statement function definition.

The checking of FORMAT statements is lax, tolerating missing separators(comma, etc.) between format descriptors in places where the Standardrequires them, and allowing .d fields on descriptors that shouldnot have them. It does warn under -f77=format-edit-descrabout nonstandard descriptor types (likeO), and supported extensions.

If a user-supplied subprogram has the same name as one of thenonstandard intrinsic functions recognized by ftnchek, it mustbe declared in an EXTERNAL statement in any routine that invokesit. Otherwise it will be subject to the checking normally given tothe intrinsic function. Since the nonstandard intrinsics are notstandard, this EXTERNAL statement is not required by the Fortran77 Standard. Using the -intrinsic=none setting, recognition of mostnonstandard intrinsics (excepting only those needed to support thedouble complex data type) can be turned off. See the lists ofsupported nonstandard intrinsic functions under the discussion of the-intrinsic setting above.

Extensions:

All of these extensions will generatewarnings if the relevant -f77 or -f90option is set.

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

Strings may contain UNIX-style backslash escape sequences. They willbe interpreted as such if the -source=unix-backslash setting is given.Otherwise the backslash character will be treated as a normalprinting character.

Hollerith constants are permitted, in accordance with the Fortran 77Standard, appendix C. According to the standard, they can appear onlyin DATA statements and as arguments in subroutine calls.ftnchek also accepts them as function arguments and in assignmentstatements.They should not be used in expressions, or confusedwith datatype CHARACTER.

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

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

Variable names may contain underscores and dollar signs (or othernon-alphabetic characters as specified by the-identifier-chars option). These characters areare treated the same as alphabetic letters. The default typefor 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 77 permits only alphanumeric characters in variable names.Fortran 90 permits underscores as well.

The UNIX version tolerates the presence of preprocessor directives,namely lines beginning with the pound sign(#).These are treated as comments, except for#linedirectives, which are interpreted, and are used to set the line numberand source file name for warnings and error messages. Note that#includedirectives are not processed by ftnchek. Programs that use them forincluding source files should be passed through the preprocessorbefore being input to ftnchek.As noted below, ftnchek does processINCLUDE statements, which have a different syntax.An optional program, ftnpp(1L) (available separately)provides preprocessing that properly handlesINCLUDE files.

The ACCEPT and TYPE statements (for terminal I/O) arepermitted. ACCEPT uses the same syntax as PRINT. However, becauseTYPE is now used as a keyword for derived-type declarations, a TYPEoutput statement may only be of a restricted form that preventsambiguity:
TYPE format-id [ , io-list ]
Here the format-id may only be an asterisk, a statement label(number), or a character literal constant (i.e. a format string withinquotes).

The so-called ``Cray pointer'' syntax is tolerated. It is not the same as theFortran 90 POINTER statement.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 inpractice they are accessed indirectly via the pointers.

Statements may have any number of continuation lines. The Fortran 77and 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.

FORMAT statements can contain a dollar sign to indicate suppression ofcarriage-return.An integer expression enclosed in angle brackets can be used anywhere in aFORMAT statement wherethe Fortran Standard allows an integer constant (except for the length of aHollerith 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.

Data types INTEGER, REAL, COMPLEX, andLOGICAL are allowed to have an optional nonstandard precision specification intype declarations. For instance, REAL*8 means an 8-bytefloating point data type. The REAL*8 datatype is notnecessarily considered equivalent to DOUBLE PRECISION,depending on the -wordsize setting.The Fortran 77 Standard allowsa length specification of this form only for CHARACTER data. The Fortran 90Standard introduced kind parameters, which should be used to controlthe precision and range of numeric variables.

ftnchek supports the DOUBLE COMPLEX typespecification for a complex quantity whose real and imaginary partsare double precision. Mixed-mode arithmetic involvingsingle-precision complex with double-precision real data,prohibited under the Standard, yields a double complex result.In Fortran 90, complex quantities may be given a kind parameterthat applies to each of their parts. By using a kind that correspondsto double precision, the effect of DOUBLE COMPLEX can be achieved in astandard conforming way.

Combined type declarations and data-statement-like initializers areaccepted. These have the form of a standard Fortran 77 typedeclaration, followed by a slash-delimited list of constants like thatused in a DATA statement. An example of the syntax is
INTEGER N / 100 /
This form of initializing declaration was notadopted in Fortran 90. Such declarations should be written usingthe standard form:
INTEGER :: N = 100

Many commonly found nonstandard intrinsic functions are provided. Seethe discussion of -intrinsic for a list of supported intrinsicfunctions and how tocontrol which ones are recognized.

Argument checking is not tight for those intrinsicsthat take arrays or mixed argument types.

The Fortran 90 standard defines the INCLUDE statement, which causesinclusion of the text of the given file. The syntax is
INCLUDE 'filename'
If the -source=vms-include option is given, ftnchek followsVMS conventions with respect to this statement: it assumes a defaultextension of .for if no filename extension is given, andallows the qualifier /[NO]LIST following the filename, tocontrol the listing of the included file. There is no support forincluding VMS text modules.

ftnchek accepts PARAMETER statements which lackparentheses. These will be warned about if the-f77=param-noparen flag is given.

ftnchek accepts PARAMETER definitions that involveintrinsic functionsand exponentiation by a non-integer exponent. Both of these cases areprohibited by the Fortran 77Standard, and will be warned about if the -f77=param-intrinsicflag is given. Fortran 90 allowsintrinsic functions in PARAMETER definitions, under specific conditions.

NEW FEATURES

This section will document future improvements to ftnchek afterthe initial release of version 4.0. Relative to the previous version,namely 3.3.1, the improvements can be summarized as follows:

1.: Fortran 95 is now largely supported. Previously only some Fortran 90syntax was supported. See the section on Limitations for what remainsto be implemented to fully support Fortran 95.

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 messagewhere no error exists, but also if ftnchek fails to issue a warning whenit ought to. Note, however, that ftnchek does not try to catch allsyntax errors (see section on Limitations). Our development efforts focuson warning about things a compiler does not flag. So please onlyreport incorrect operation on code that passes the compiler withouterror, except for things that cause ftnchek to crash.We especially want to know if ftnchek crashes for any reason. It isnot supposed to crash, even on programs with syntax errors.

It is not considered a bug for a variable to bereported as used before set, if the reason is that the usage of thevariable occurs prior in the text to where the variable is set. Forinstance, this could occur when a GOTO causes execution to loop backwardto some previously skipped statements. ftnchek does not analyze theprogram flow, but assumes that statements occurring earlier in the textare executed before the following ones.

Suggestionsare welcomed for additional features which you would find useful. Tellus if any of ftnchek'smessages are incomprehensible. Comments on thereadability and accuracy of this document are also welcome.

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

If you find a bug in ftnchek,first consult the list of known bugsbelow to see if it has already been reported. Also check the sectionentitled ``Limitations and Extensions'' above for restrictionsthat could be causing the problem. If you do not find the problemdocumented 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 orsettings defined in startup file. (Capturing the output of ftnchek-help is useful for this.)
3.: A brief description of the bug.
4.: If possible, a small sample program showing the bug.

The report should be sent to Dr. Robert Moniot (see contact informationin section entitled ``Installation and Support'').

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

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

The following is a list of known bugs.

1.

Bug: Used-before-set message is suppressed for any variable whichis used as the loop index in an implied-do loop, even if it was infact 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 loopwhere J is set. Normally this would causeftnchek 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: To be fixed in a future version of ftnchek.

2.

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

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

3.

Bug: VAX version does not expand wildcards in filenames on thecommand 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 interveningspace are not supported by the GNU shell_mung routine that is usedto expand wildcards.

: Prognosis: unlikely to be fixed.

4.

Bug: checking for nonstandard format edit descriptors is done only inFORMAT statements, not in character strings used as formats.

: Prognosis: may be fixed someday.

ACKNOWLEDGEMENTS

ftnchekwas designed by Dr. Robert Moniot, professor at FordhamUniversity. During the academic year of1988-1989, Michael Myers and Lucia Spagnuolo developed the program toperform the variable usage checks. During the following year it wasaugmented by Lois Bigbie to check subprogram arguments andCOMMON block declarations.Brian Downing assisted with the implementation of the INCLUDEstatement.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 codeto implement the -makedcls feature and wrote the dcl2inc script.The -mkhtml feature was contributed by Mark McVeigh ofFramatome ANP, Inc.The -calltree=reference feature was contributed by Gerome Emmanuel,Ecole des mines, U. Nancy (slightly modified).The -calltree=vcg optionwas contributed by Dr. Philip Rubini of Cranfield University, UK.The support for Cray pointer syntax was provided by John Dannenhoffer ofUnited Technologies Research Center.John C. Bollinger of Indiana University added the parser syntax forthe SELECT CASE construct.Robert Landrito added the parser syntax for F90 pointer-related features.Gaurav Gautam of HCL Technologies, Noida India, contributed code forsupport of F90 pointers and allocatable arrays.

A special acknowledgement is due to the U.S. Department of DefenseHigh Performance Computing Modernization Program, which funded ayear-long graduate assistantship to upgrade ftnchek to support Fortran 95.The upgrade might never have happened without this support.Karma Shrestha performed the implementation of most of the new syntax.

As of Version 2.5, the name was changed from forchek to ftnchek,to avoid confusion with asimilar program named forcheck,developed earlier at Leiden University.

We would like to thankJohn 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,andNelson 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,andBob Wells of Oxford Universitywere extremely helpful as alpha testers.We also thank Jack Dongarra for puttingftnchek into the netliblibrary of publicly available software,and Mark Brown of the University of Edinburgh for acting asthe ftnchek package maintainer for Debian.Thanks also to SourceForgehttp://www.sourceforge.netfor hosting the ftnchek source code repository.

INSTALLATION AND SUPPORT

The ftnchek program is free software.Version 3.3.1 is included as a standard package in many Linuxdistributions, including Fedora and Debian. It is hoped that whenVersion 4 becomes stable, these distributions will update it.The source code can be obtainedby anonymous ftp from many software servers, includingftp://netlib.org/fortran .Note that on Netlib the distribution is named ftnchek.tar.gzwhereas on most other servers the file name includes the versionnumber, e.g. ftnchek-3.3.0.tar.gz.If the file extension is .Z, uncompress with the Unixuncompress(1)utility. If the file extension is .gz, uncompress with theGNUgunzip(1L)program. Then usetar(1)to unpack the files into a subdirectory.

Installation requires a C compiler for your computer.See the INSTALL file provided with the distribution forinstructions on installing ftnchek on your system.Executable binary for particular systems such as IBM PC orMacintosh, as available, can be obtained by anonymous ftp fromftp://ftp.dsm.fordham.edu/pub/ftnchek .Assistance in preparing such executable binary forms is welcome.

The nroff version of this document is namedftnchek.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 producethe other forms of the documentation. The cleaned-up man pagedocument, created during installation of ftnchek, is namedftnchek.1.The distribution also includes a plain ASCII version namedftnchek.doc,a PostScript version namedftnchek.ps,an HTML version in directoryhtml,and a VMS HELP version namedftnchek.hlp.

Information about the latest version and the status of the project can beobtainedby visiting ftnchek's home page,http://www.dsm.fordham.edu/~ftnchek .For further information and to report bugs, you may contactDr. Robert Moniot, whose contact informationcan be found by a Web search for his name and Fordham University.(E-mail address is not provided here because it attracts unsolicitedcommercial e-mail, but it is easily constructed by combining his lastname with the name of the university and the edu domain.)

This document was created byman2html,using the manual pages.