OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / fchek284.zip / ftnchek.doc < prev next >

Wrap

Text File | 1995-06-02 | 142KB | 3,631 lines

FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) NAME ftnchek - Fortran program checker SYNOPSIS ftnchek [ -arguments=num ] [ -array=num ] [ -[no]backslash ] [ -[no]calltree ] [ -columns=num ] [ -common=num ] [ -[no]crossref ] [ -[no]declare ] [ -[no]division ] [ -[no]extern ] [ -[no]f77 ] [ -[no]help ] [ -[no]hollerith ] [ -include=str ] [ -[no]library ] [ -[no]list ] [ -makedcls=num ] [ -[no]novice ] [ -output=str ] [ -[no]portability ] [ -[no]pretty ] [ -[no]project ] [ -[no]pure ] [ -[no]reference ] [ -[no]resource ] [ -[no]sixchar ] [ -[no]sort ] [ -[no]symtab ] [ -[no]tab ] [ -[no]truncation ] [ -usage=num ] [ -[no]verbose ] [ -[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 usu- ally 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 incor- rect operation. For example, variables which are never used may indicate some omission in the program; uninitial- ized variables contain garbage which may cause incorrect results to be calculated; and variables which are not declared may not have the intended type. ftnchek is intended to assist users in the debugging of their Fortran program. It is not intended to catch all syntax errors. This is the function of the compiler. Prior to using ftnchek, the user should verify that the program compiles correctly. This document first summarizes how to invoke ftnchek. That section should be read before beginning to use ftnchek. Later sections describe ftnchek's options in more detail, give an example of its use, and explain how to interpret the output. The final sections mention the limitations and known bugs in ftnchek. INVOKING FTNCHEK ftnchek is invoked through a command of the form: $ ftnchek [-option -option ...] filename [filename ...] 2 June 1995 1 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) The brackets indicate something which is optional. The brackets themselves are not actually typed. Here options are command-line switches or settings, which control the operation of the program and the amount of information that will be printed out. If no option is specified, the default action is to print error messages, warnings, and informational messages, but not the program listing or symbol tables. Each option begins with the '-' character. (On VAX/VMS or MS-DOS systems you may use either '/' or '-'.) The options are described at greater length in the next sec- tion. ftnchek options fall into two categories: switches, which are either true or false, and settings, which have a numeric or string value. The name of a switch is prefixed by 'no' to turn it off: e.g. -nopure would turn off the warnings about impure functions. The 'no' prefix can also be used with numeric settings, having the effect of turn- ing off the corresponding warnings. Only the first 3 characters of an option name (not counting the '-') need be provided. A colon may be used in place of an equals sign for option value assignments; however, we show only the equals sign form below. The switches and settings which ftnchek currently recog- nizes are: -arguments=num Set level of strictness in checking subprogram arguments. Min is 0 (no checking). Max is 3 (most checking). Default = 3. -array=num Set level of strictness in checking array arguments of subprograms. Min is 0 (least strict). Max is 3 (most strict). Default = 3. -backslash Handle UNIX-style backslash escapes in character strings. Default = no. -calltree Print tree of subprogram call hierarchy. Default = no. -columns=num Set maximum line length to num columns. (Beyond this is ignored.) Max is 132. Default = 72. 2 June 1995 2 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -common=num Set level of strictness in checking COMMON blocks. Min is 0 (no checking). Max is 3 (must be identi- cal). Default = 3. -crossref Print cross-reference list of subprogram calls and COMMON block use. Default = no. -declare Print a list of all identifiers whose datatype is not explicitly declared. Default = no. -division Warn wherever division is done (except division by a constant). Default = no. -extern Warn if external subprograms which are invoked are never defined. Default = yes. -f77 Warn about extensions to the Fortran 77 Standard. Default = no. -help Print command summary. Default = no. -hollerith Warn about Hollerith constants if -portability option is in effect. Default = yes. -include=path Define a directory to search for INCLUDE files. Cumulative. -library Begin library mode: do not warn about subprograms in file that are defined but never used. Default = no. -list Print source listing of program. Default = no. -makedcls=num Prepare a file of declarations. Min is 0 (no dec- laration file). Max is 511. Default = 1 if this option is specified with an out-of-range numeric value. -novice Give output suitable for novice users. Default = yes. -output=filename Send output to the given file. Default is to send output to the screen. (Default filename extension 2 June 1995 3 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) is .lis). -portability Warn about non-portable usages. Default = no. -pretty Give warnings for possibly misleading appearance of source code. Default = yes. -project Create project file (see explanation below). Default = no. -pure Assume functions are pure, i.e. have no side effects. Default = yes. -reference Print table of subprograms referenced by each sub- program. Default = no. -resource 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. -symtab Print symbol table for each subprogram. Default = no. -tab Accept DEC-style tab-formatted source. Default = no. -truncation Check for possible loss of accuracy by truncation. Default = yes. -usage=num Control warnings about unused variables, etc. Min is 0 (no checking). Max is 3 (most checking). Default = 3. -verbose Produce full amount of output. Default = yes. -volatile Assume COMMON blocks lose definition between acti- vations. Default = no. 2 June 1995 4 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -wordsize=num Set the default word size for numeric quantities to num bytes. Default = 4 bytes. -wrap=num Set output column at which to wrap long error mes- sages and warnings to the next line. If set to 0, turn off wrapping. Default = 79. When more than one option is used, they should be sepa- rated by a blank space, except on systems such as VMS where options begin with slash ( / ). No blank spaces may be placed around the equals sign ( = ) in a setting. ftnchek "?" will produce a command summary listing all options and settings. When giving a name of an input file, the extension is optional. If no extension is given, ftnchek will first look for a project file with extension .prj, and will use that if it exists. If not, then ftnchek will look for a Fortran source file with the extension .for for VMS sys- tems, .f for UNIX systems. More than one file name can be given to ftnchek, and it will process the modules in all files as if they were in a single file. Wildcards are allowed in the specification of filenames on the command line for the VMS and MS-DOS versions, as also of course under UNIX and any other system that performs wildcard expansion in the command processor. If no filename is given, ftnchek will read input from the standard input. OPTIONS This section provides a more detailed discussion of ftnchek command-line options. Options and filenames may be interspersed on a command line. Most options are posi- tional: each option remains in effect from the point it is encountered until it is overridden by a later change. Thus for example, the listing may be suppressed for some files and not for others. Exceptions are: the -wordsize setting, which cannot be changed once processing of input files has started; the -arguments, -array, -calltree, -common, -crossref, -extern, -reference, -resource, -sort, 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 2 June 1995 5 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) order. -arguments=num Controls warnings about mismatches between actual and dummy subprogram arguments. (An actual argu- ment is an argument passed to the subprogram by the caller; a dummy argument is an argument received by the subprogram.) The meanings of the setting values are as follows: 0: turn off all such warnings. 1: warn only about different number of arguments. 2: warn only about mismatch of data type of argu- ments and of function itself. 3: all warnings. Default = 3. This setting is provided mainly to suppress warn- ings when you wish to use ftnchek for some other purpose than checking for errors, for example when you only want to print the call tree. It does not apply to checking invocations of intrinsic func- tions or statement functions. See also: -array, -library, -usage. -array=num Controls the degree of strictness in checking agreement between actual and dummy subprogram argu- ments that are arrays. The warnings controlled by this setting are for constructions that might legitimately be used by a knowledgeable programmer, but that often indicate programming errors. The meanings of the setting values are as follows: 0: only warn about cases that are seldom inten- tional (see note below). 1: warn if the arguments differ in their number of dimensions, or if the actual argument is an array element while the dummy argument is a whole array. 2: warn if both arguments are arrays, but they 2 June 1995 6 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) differ in number of elements. 3: give both types of warnings. Default = 3. Note: A warning is always given regardless of this setting if the actual argument is an array while the dummy argument is a scalar variable, or if the actual argument is a scalar variable or expression while the dummy argument is an array. No warning is ever given if the actual argument is an array element while the dummy argument is a scalar vari- able. Variable-dimensioned arrays and arrays dimensioned with 1 or asterisk match any number of array elements. There is no check of whether multi-dimensional arrays agree in the size of each dimension separately. See also: -arguments, -library, -usage. -backslash Handle UNIX-style backslash escapes in character strings. The escape sequence following the back- slash will be evaluated according to the ANSI stan- dard for strings in C: up to three digits signify an octal value, an x signifies the start of a hex- adecimal constant, any of the letters a b f n r t signify special control codes, and any other char- acter (including newline) signifies the character itself. When this option is in effect, a non- standard warning will be given if the -f77 flag is set. Default = no. If this option is turned off (the default), the backslash will be treated 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 back- slash 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 2 June 1995 7 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) PARAMETER definition uses an intrinsic string func- tion such as LEN with such a string as argument, and that value is later used to define array dimen- sions, etc. -calltree Causes ftnchek to print out the call structure of the complete program in the form of a tree. The tree is printed out starting from the main program, which is listed on the first line at the left mar- gin. Then on the following lines, each routine called by the main program is listed, indented a few spaces, followed by the subtree starting at that routine. Default = no. If a routine is called by more than one other rou- tine, its call subtree is printed only the first time it is encountered. Later calls give only the routine name and the notice ``(see above)''. Note that the call tree will be incomplete if any of the input files are project files containing more than one module that were created in -library mode. See the discussion of project files below. Technical points: Each list of routines called by a given routine is printed in alphabetical order. If multiple main programs are found, the call tree of each is printed separately. If no main program is found, a report to that effect is printed out, and the call trees of any top-level non-library rou- tines are printed. This flag only controls the printing of the call tree: ftnchek constructs the call tree in any case because it is used to deter- mine which library modules will be cross-checked. See the discussion of the -library flag. See also: -crossref, -library, -reference, -sort, -symtab. -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 option is in effect, a warning will be given for any lines in which characters past column 72 are processed. Max is 2 June 1995 8 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 132. Default = 72. -common=num This setting varies the strictness of checking of COMMON blocks. The different levels are: 0: no checking. 1: in each declaration of a given COMMON block, corresponding memory locations (words or bytes) must agree in data type. 2: also warn if different declarations of the same block are not equal in total length. 3: corresponding variables in each declaration of a block must agree in data type and (if arrays) in size and number of dimensions. Default = 3. The Fortran 77 Standard requires each named common block, but not blank common, to be the same length in all modules of the program. Level 3 provides an extra degree of checking to support a frequent pro- gramming practice. See also: -library, -usage, -volatile. -crossref Specifies that a cross-reference table be printed. This table lists each subprogram followed by a list of the routines that call it. Also prints a table listing each COMMON block followed by a list of the routines that access it. Default = no. The cross-reference listing omits library modules that are not in the call tree of the main program. The list is alphabetized. The routines listed as using a COMMON block are those in which some vari- ables in the block are accessed, not simply those routines that declare the block. (To find out what routines declare a COMMON block but do not use it, see the -usage flag.) See also: -calltree, -reference, -sort, -symtab. 2 June 1995 9 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -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 poten- tial 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 intel- ligent enough not to divide by a constant which is equal to zero!) Default = no. See also: -portability, -truncation. -extern Causes ftnchek to report whether any subprograms invoked by the program are never defined, or are multiply defined. Ordinarily, if ftnchek is being run on a complete program, each subprogram other than the intrinsic functions should be defined once and only once somewhere. Turn off this switch if you just want to check a subset of files which form part of a larger complete program, or to check all at once a number of unrelated files which might each contain an unnamed main program. Subprogram arguments will still be checked for correctness. Default = yes. See also: -library. -f77 Use this flag to catch language extensions which violate the Fortran 77 Standard. Such extensions may cause your program not to be portable. Exam- ples include the use of underscores in variable names; variable names longer than six characters; statement lines longer than 72 characters; and non- standard statements such as the DO ... ENDDO struc- ture. ftnchek does not report on the use of lower- case letters. Default = no. See also: -portability, -pretty, -wordsize. 2 June 1995 10 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -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 conve- nience 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 speak- ing, not the built-in defaults but the current val- ues after any environment options and any command- line options preceding the -help option have been processed. -hollerith Hollerith constants (other than within FORMAT specifications) are a source of possible portabil- ity problems, so when the -portability flag is set, warnings about them will be produced. If your pro- gram uses many Hollerith constants, these warnings can obscure other more serious warnings. So you can set this flag to ``no'' to suppress the warn- ings about Holleriths. This flag has no effect unless the -portability flag (which is off by default) is turned on. Default = yes. See also: -portability. -include=path Specifies a directory to be searched for files specified by INCLUDE statements. Unlike other com- mand-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 systemwide directory (/usr/include for UNIX, SYS$LIBRARY for VMS, and \include for MSDOS). 2 June 1995 11 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -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. (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. -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: -symtab, -verbose. -makedcls=num Prepare a neatly-formatted file of declarations of variables, common blocks, and namelist lists, for possible merging into the source code. The decla- rations are stored in a file of the same name as the source code, but with the extension changed to 2 June 1995 12 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) .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 stan- dard output. Variables are declared in alphabetical order within each declaration class and type, with integer vari- ables first, because of their later possible use in array dimensions. PARAMETER statements are an exception to the alpha- betical 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 com- piler options to reject undeclared variables, mis- spelled 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 chang- ing types of explicit floating-point type declara- tions, 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. The setting values are given by the sum of selected option values from the following list: 0: Do not write a declaration file. 1: Write a declaration file. 2: Normally, all variables are included in the declaration file. With this option, include only undeclared variables. This setting is useful if you want to check for undeclared variables, since Fortran source files with all variables properly declared will not result in a .dcl file. With this option, common blocks and namelist lists will not be included in the declaration file, since by their nature they cannot be undeclared. 2 June 1995 13 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 col- umn alignment. 8: Causes continuation lines to be used where permissible. The default is to begin a new declaration on each line. This option is appropriate to use with the option for com- pact output. 16: Output Fortran keywords in lowercase, instead of the default uppercase. 32: Output variables and constants in lowercase, instead of the default uppercase. Character string constants are not affected by this option. 64: Omit declarations of internal integer vari- ables produced by the SFTRAN3 preprocessor, xsf3(1L), as part of the translation of structured Fortran statements to ordinary Fortran. These variables have six-character names of the form NPRddd, NXdddd, N2dddd, and N3dddd, where d is a decimal digit. Because they are invisible in the SFTRAN3 source code, and will change if the SFTRAN3 code is modified, such variables should not be explicitly declared. Instead, they should just assume the default Fortran INTEGER data type based on their initial letter, N. 128: Use an asterisk as the comment character; the default is otherwise 'C'. 256: Use 'c' instead of 'C' or '*' as the comment character. If any non-zero value is specified, then declara- tion output is selected, even if the value 1 was not included in the sum. The declaration files contain distinctive comments that mark the start and end of declarations for each program unit, to facilitate using text editor macros for merging the declarations back into the source code. 2 June 1995 14 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -novice This flag is intended to provide more helpful out- put 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. Default = yes. In versions of ftnchek prior to 2.6, this option could take on various numerical values, as a way of controlling various classes of warnings. These warnings are now controlled individually by their own flags. Novice level 1 is now handled by the -array flag; level 2 has been eliminated; level 3 is equivalent now to setting -novice to yes; level 4 is handled by the -pure flag. -output=filename This setting is provided for convenience on sys- tems 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 exten- sion .lis will be used. -portability 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 vari- ables 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 option. Default = no. 2 June 1995 15 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) See also: -backslash, -f77, -hollerith, -pretty, -wordsize. -pretty Controls certain messages related to the appear- ance of the source code. These warn about things that might be deceptive to the reader. Default = yes. The warnings controlled by this flag include such things as comments that are interspersed among the continuation lines of a statement, lack of space between a keyword and a following variable name, and statement lines containing characters past col- umn 72. See also: -f77, -portability. -project ftnchek will create a project file from each source file that is input while this flag is in effect. 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 stan- dard input, the project file is named ftnchek.prj.) Default = no. A project file contains a summary of information from the source file, for use in checking agreement among FUNCTION, SUBROUTINE, and COMMON usages in other files. It allows incremental checking, which saves time whenever you have a large set of files containing shared subroutines, most of which seldom change. You can run ftnchek once on each file with the -project flag set, creating the project files. Usually you would also set the -library and -noex- tern flags at this time, to suppress messages relating to consistency with other files. Only error messages pertaining to each file by itself will be printed at this time. Thereafter, run ftnchek without these flags on all the project files together, to check consistency among the dif- ferent files. All messages internal to the indi- vidual files will now be omitted. Only when a file is altered will a new project file need to be made for it. Naturally, when the -project flag is set, ftnchek will not read project files as input. 2 June 1995 16 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) Project files contain only information needed for checking agreement between files. This means that a project file is of no use if all modules of the complete program are contained in a single file. A more detailed discussion is given in the section on Using Project Files. -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 mod- ified 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. -reference Specifies that a who-calls-who table be printed. This table lists each subprogram followed by a list of the routines it calls. Default = no. The reference list omits routines called by unused library modules. Thus it contains the same infor- mation as for the -calltree flag, namely the hier- archy of subprogram calls, but printed in a differ- ent format. This prints out a breadth-first traversal of the call tree whereas -calltree prints out a depth-first traversal. If both -calltree and -reference flags are given, only the reference form of the table will be produced. See also: -calltree, -crossref, -library, -sort, -symtab. 2 June 1995 17 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -resource 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 allo- cated space is filled up, more memory is allocated in chunks of this size. The following is an expla- nation 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 con- taining 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, FOR- MAT, 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 refer- enced. Statement functions are not included. A subprogram with multiple entry points is only counted once. Max identifier name chars: Number of characters used for storing identi- fier names. An identifier is a variable, sub- program, 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 argu- ment text (up to 15 characters for each argu- ment) is also included here. The space used for local names is recovered at the end of each module, whereas the global space grows until 2 June 1995 18 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) the whole program is analyzed. Unfortunately, this figure may include some common block names and arguments stored more than once, although a heuristic is used that will avoid duplicates in many cases. Max token text chars: A token is the smallest syntactic unit of the FORTRAN language above the level of individual characters. For instance a token can be a vari- able 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 recov- ered 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 sym- bol table entries include all variables and parameters, common block names, statement func- tions, external subprograms and intrinsic func- tions referenced by the module. Literal con- stants 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 subpro- gram and common block names. Intrinsic func- tions and statement functions are not included. Max number of tokenlists: A token list is a sequence of tokens represent- ing the actual or dummy argument list of a sub- program, or the list of variables in a common block or namelist. Therefore this number rep- resents 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 2 June 1995 19 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 func- tions). 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 mul- tiple declarations of a block within the same module; these are counted as only one declara- tion since they are equivalent to a single long declaration.) Number of array dim & param ptrs: This is the sum over all modules of the number of array dimension and parameter definition text strings saved for use by the -makedcls option. The length of the text strings is not counted. Each dimension of a multidimensional array is counted separately. These numbers are obviously not the same when pro- ject files are used in place of the original source code. Even the numbers for global entities may be different, since some redundant information is eliminated in project files. -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 differ- ent variables being considered as the same. For instance, variables named AVERAGECOST and AVER- AGEPRICE are the same in the first six characters. If you wish to catch such possible conflicts, use this flag. Default = no. Use the -f77 flag if you want to list all variables 2 June 1995 20 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 ``pre- requisite'' 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 For- tran) they will be detected and diagnosed. Default = no. See also: -calltree, -crossref, -reference, -symtab. -symtab A symbol table will be printed out for each mod- ule, listing all identifiers mentioned in the mod- ule. This table gives the name of each variable, its datatype, and the number of dimensions for arrays. An asterisk (*) indicates that the vari- able 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. See also: -calltree, -crossref, -list, -reference, -sort. -tab 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 is in effect. Default = no. 2 June 1995 21 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -truncation Warn about possible truncation (or roundoff) errors. Most of these are related to integer arithmetic. The warnings enabled when this flag is in effect are: (a) use of the result of integer division where a real result seems intended (namely as an expo- nent, or if the quotient is later converted to real); (b) division in an integer constant expression that yields a result of zero; (c) exponentiation of an integer by a negative integer (which yields zero unless the base integer is 1 in magnitude); (d) use of a non-integer array subscript or DO index; (e) conversion of any real type to integer, or con- version of a complex value to real or integer; (f) conversion of a double precision value to sin- gle precision, or vice-versa (promotion). This applies both to real types and to complex types. Default = yes. Note: warnings about truncating type conversions are given only when the conversion is done automat- ically, e.g. by an assignment statement. If intrinsic functions such as INT are used to perform the conversion, no warning is given. Promotions of real types from single to double precision are included here because such conversions imply a pos- sible loss of accuracy that is similar to the cor- responding demotions. See also: -portability, -wordsize. -usage=num Warn about unused or possible uninitialized vari- ables and unused common blocks. The meanings of the setting values are as follows: 0: no warnings. 1: warn if variables are (or may be) used before 2 June 1995 22 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) they are set. 2: warn if variables are declared or set but never used. 3: give both types of warnings. Default = 3. Sometimes ftnchek makes a mistake about these warn- ings. 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 refer- ence 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. This setting controls warnings not only for local variables but also for variables in COMMON blocks. Level 2 also controls whether a warning is given when an entire COMMON block is unused. When check- ing for used-before-set errors involving COMMON variables, ftnchek does not do a thorough enough analysis of the calling sequence to know which rou- tines 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 set- ting is 3 (variable by variable agreement). See also: -common, -declare, -volatile. -verbose This option is on by default. Turning it off reduces the amount of output relating to normal operation, so that error messages are more appar- ent. 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. (Some of this output is turned back on by the -list and -symtab options.) Default = yes. 2 June 1995 23 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) -volatile Assume that COMMON blocks are volatile. Default = no. Many Fortran programmers assume that variables, whether local or in COMMON, are static, i.e. that once assigned a value, they retain that value per- manently until assigned a different value by the program. However, in fact the Fortran 77 Standard does not require this to be the case. Local vari- ables may become undefined between activations of a module in which they are declared. Similarly, COM- MON blocks may become undefined if no module in which they are declared is active. (The technical term for this behavior is ``automatic'', but ftnchek uses the word ``volatile'' since it is clearer to the nonspecialist.) Only COMMON blocks declared in a SAVE statement, or declared in the main program or in a block data subprogram remain defined as long as the program is running. Vari- ables and COMMON blocks that can become undefined at some point are called volatile. If the -volatile flag is turned on, ftnchek will warn you if it finds a volatile COMMON block. If, at the same time, the -usage setting is 1 or 3 (check used before set), ftnchek will try to check whether such a block can lose its defined status between activations of the modules where it is declared. ftnchek does not do a very good job of this: the rule used is to see whether the block is declared in two separated subtrees of the call tree. For instance, this would be the case if two modules, both called from the main program, shared a volatile COMMON block. A block can also become undefined between two successive calls of the same subprogram, but ftnchek is not smart enough to tell whether a subprogram can be called more than once, so this case is not checked for. The -volatile flag does not affect the way ftnchek checks the usage of local variables. See also: -common, -usage. -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 pre- cisions. Double-precision and complex variables will be twice this value, and double complex vari- ables four times. Explicit precisions for non- 2 June 1995 24 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) character variables are an extension to the Fortran 77 Standard, and are given by type declarations such as REAL*8 X. Default = 4 bytes. If you want to change the built-in default value of this setting, compile ftnchek with the macro name BpW (Bytes per Word) set to the desired default value. This is not critical: 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 trunca- tion 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 or -nowordsize flags, any mixing of explicit with default preci- sion 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 the -truncation flag, a warning is given for assignment of an expression to a shorter variable of the same type, or for promotion of a lower pre- cision 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. Use this instead of -portability if you want to check only for those aspects of portability related to mixing default and explicit precision, for example to flag places where REAL*8 is treated as equivalent to DOUBLE PRECISION. See also: -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 read- ability. 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 trun- cate it. Default = 79. 2 June 1995 25 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) CHANGING THE DEFAULTS ftnchek includes a mechanism for changing the default values of all options by defining environment variables. 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 set- ting. 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. Of course, command-line options will override these defaults the same way as they override the built-in defaults. Note that the environment variable name must be con- structed with the full-length option name, which must be in uppercase. For example, to make ftnchek print a source listing by default, set the environment variable FTNCHEK_LIST to 1 or YES or anything other than 0 or NO. The names FTNCHEK_LIS (not the full option name) or ftnchek_list (lower case) would not be recognized. Here are some examples of how to set environment variables on various systems. For simplicity, all the examples set the default -list switch to YES. 1. UNIX, Bourne shell: $ FTNCHEK_LIST=YES; export FTNCHEK_LIST 2. UNIX, C shell: % setenv FTNCHEK_LIST YES 3. VAX/VMS: $ DEFINE FTNCHEK_LIST YES 4. MSDOS: $ SET FTNCHEK_LIST=YES USING PROJECT FILES This section contains detailed information on how to use project files most effectively, and how to avoid some pit- falls. Ordinarily, project files should be created with the -library flag in effect. In this mode, the information saved in the project file consists of all subprogram dec- larations, all subprogram invocations not resolved by dec- larations in the same file, and one instance of each COM- MON block declaration. This is the minimum amount of information needed to check agreement between files. If the file contains more than one routine, there are some 2 June 1995 26 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) possible problems that can arise from creating the project file in library mode, because the calling hierarchy among routines defined within the file is lost. Also, if the routines in the file make use of COMMON blocks that are shared with routines in other files, there will not be enough information saved for the correct checking of set and used status of COMMON blocks and COMMON variables according to the -usage setting. Therefore if you plan to use project files when the -usage setting is nonzero (which is the default situation), and if multiple routines in one project file share COMMON blocks with routines in other files, the project files should be created with the -library flag turned off. In this mode, ftnchek saves, besides the information listed above, one invocation of each subprogram by any other subprogram in the same file, and all COMMON block declarations. This means that the project file will be larger than necessary, and that when it is read in, ftnchek may repeat some inter-module checks that it already did when the project file was created. If each project file contains only one module, there is no loss of information in creating the project files in library mode. Because of the possible loss of information entailed by creating a project file with the -library flag in effect, whenever that project file is read in later, it will be treated as a library file regardless of the current set- ting of the -library flag. On the other hand, a project file created with library mode turned off can be read in later in either mode. Here is an example of how to use the UNIX make utility to automatically create a new project file each time the cor- responding source file is altered, and to check the set of files for consistency. The example assumes that a macro OBJS has been defined which lists all the names of object files to be linked together to form the complete exe- cutable program. # tell make what a project file suffix is .SUFFIXES: .prj # tell make how to create a .prj file from a .f file .f.prj: ftnchek -project -noextern -library $< # set up macro PRJS containing project filenames PRJS= $(OBJS:.o=.prj) # "make check" will check everything that has been changed. check: $(PRJS) ftnchek $(PRJS) 2 June 1995 27 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) AN EXAMPLE The following simple Fortran program illustrates the mes- sages given by ftnchek. The program is intended to accept an array of test scores and then compute the average for the series. C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO C DATE: MAY 8, 1989 C Variables: C SCORE -> an array of test scores C SUM -> sum of the test scores C COUNT -> counter of scores read in C I -> loop counter REAL FUNCTION COMPAV(SCORE,COUNT) INTEGER SUM,COUNT,J,SCORE(5) DO 30 I = 1,COUNT SUM = SUM + SCORE(I) 30 CONTINUE COMPAV = SUM/COUNT END PROGRAM AVENUM C C MAIN PROGRAM C C AUTHOR: LOIS BIGBIE C DATE: MAY 15, 1990 C C Variables: C MAXNOS -> maximum number of input values C NUMS -> an array of numbers C COUNT -> exact number of input values C AVG -> average returned by COMPAV C I -> loop counter C PARAMETER(MAXNOS=5) INTEGER I, COUNT REAL NUMS(MAXNOS), AVG COUNT = 0 DO 80 I = 1,MAXNOS READ (5,*,END=100) NUMS(I) COUNT = COUNT + 1 80 CONTINUE 100 AVG = COMPAV(NUMS, COUNT) END 2 June 1995 28 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) The compiler gives no error messages when this program is compiled. Yet here is what happens when it is run: $ run average 70 90 85 <EOF> $ What happened? Why didn't the program do anything? The following is the output from ftnchek when it is used to debug the above program: $ ftnchek -list -symtab average FTNCHEK Version 2.8 May 1995 File average.f: 1 C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO 2 C DATE: MAY 8, 1989 3 4 C Variables: 5 C SCORE -> an array of test scores 6 C SUM -> sum of the test scores 7 C COUNT -> counter of scores read in 8 C I -> loop counter 9 10 REAL FUNCTION COMPAV(SCORE,COUNT) 11 INTEGER SUM,COUNT,J,SCORE(5) 12 13 DO 30 I = 1,COUNT 14 SUM = SUM + SCORE(I) 15 30 CONTINUE 16 COMPAV = SUM/COUNT ^ Warning near line 16 col 20: integer quotient expr converted to real 17 END 18 Module COMPAV: func: real Variables: Name Type Dims Name Type Dims Name Type Dims Name Type Dims COMPAV real COUNT intg I intg* J intg SCORE intg 1 SUM intg 2 June 1995 29 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) * Variable not declared. Type has been implicitly defined. Warning: Variables declared but never referenced: J Warning: Variables may be used before set: SUM 19 20 PROGRAM AVENUM 21 C 22 C MAIN PROGRAM 23 C 24 C AUTHOR: LOIS BIGBIE 25 C DATE: MAY 15, 1990 26 C 27 C Variables: 28 C MAXNOS -> maximum number of input values 29 C NUMS -> an array of numbers 30 C COUNT -> exact number of input values 31 C AVG -> average returned by COMPAV 32 C I -> loop counter 33 C 34 35 PARAMETER(MAXNOS=5) 36 INTEGER I, COUNT 37 REAL NUMS(MAXNOS), AVG 38 COUNT = 0 39 DO 80 I = 1,MAXNOS 40 READ (5,*,END=100) NUMS(I) 41 COUNT = COUNT + 1 42 80 CONTINUE 43 100 AVG = COMPAV(NUMS, COUNT) 44 END Module AVENUM: prog External subprograms referenced: COMPAV: real* Variables: Name Type Dims Name Type Dims Name Type Dims Name Type Dims AVG real COUNT intg I intg MAXNOS intg* NUMS real 1 * Variable not declared. Type has been implicitly defined. Warning: Variables set but never used: AVG 2 June 1995 30 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 0 syntax errors detected in file average.f 6 warnings issued in file average.f Subprogram COMPAV: argument data type mismatch at position 1: Dummy arg SCORE is type intg in module COMPAV line 10 file average.f Actual arg NUMS is type real in module AVENUM line 43 file average.f According to ftnchek, the program contains variables which may be used before they are assigned an initial value, and variables which are not needed. ftnchek also warns the user that an integer quotient has been converted to a real. This may assist the user in catching an unintended roundoff error. Since the -symtab flag was given, ftnchek prints out a table containing identifiers from the local module and their corresponding datatype and number of dimensions. Finally, ftnchek warns that the function COM- PAV is not used with the proper type of arguments. With ftnchek's help, we can debug the program. We can see that there were the following errors: 1. SUM and COUNT should have been converted to real before doing the division. 2. SUM should have been initialized to 0 before entering the loop. 3. AVG was never printed out after being calculated. 4. NUMS should have been declared INTEGER instead of REAL. We also see that I, not J, should have been declared INTE- GER in function COMPAV. Also, MAXNOS was not declared as INTEGER, nor COMPAV as REAL, in program AVENUM. These are not errors, but they may indicate carelessness. As it happened, the default type of these variables coincided with the intended type. Here is the corrected program, and its output when run: C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO C DATE: MAY 8, 1989 C C Variables: C SCORE -> an array of test scores C SUM -> sum of the test scores C COUNT -> counter of scores read in C I -> loop counter C REAL FUNCTION COMPAV(SCORE,COUNT) 2 June 1995 31 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 2 June 1995 32 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) or carelessness. Most of these messages can be turned off by command-line options. Which option controls each mes- sage 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 syn- tax errors are typographical errors, for example unbal- anced parentheses or misspelling of a keyword. This type of error is caught by the parser and appears with the description ``parse error'' or ``syntax error'' (depending on whether the parser was built using GNU bison or UNIX yacc respectively). This type of error message cannot be suppressed. Be aware that this type of error often means that ftnchek has not properly interpreted the statement where the error occurs, so that its subsequent checking operations will be compromised. You should eliminate all syntax errors before proceeding to interpret the other messages ftnchek gives. ``Warning: Nonstandard syntax'' indicates an extension to Fortran that ftnchek supports but that is not according to the Fortran 77 Standard. The extensions that ftnchek accepts are described in the section on Extensions below. One example is the DO ... ENDDO construction. If a pro- gram uses these extensions, warnings will be given only if the -f77 flag is set. The default is to give no warnings. ``Warning'' in other cases means a condition that is sus- picious 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 syn- tax errors. Usage errors are one example. These refer to the possibility that a variable may be used before it has been assigned a value (generally an error), or that a variable is declared but never used (harmless but may indicate carelessness). The amount of checking for usage errors is controlled by the -usage flag, which is set for the maximum amount of checking by default. Truncation warnings cover situations in which accuracy may be lost unintentionally, for example when a double preci- sion value is assigned to a real variable. These warnings are controlled by the -truncation flag, 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 2 June 1995 33 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 -porta- bility 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 con- structions 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 pro- cessed, 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 declara- tions, or between dummy and actual arguments of a subpro- gram. 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 format of the error messages has been modified from previous versions for more clarity. The syntax error mes- sages and warnings now have the filename included along with the line number and column number. ftnchek now has two different options for the appearance of these error messages. If -novice is in effect, which is the default, the messages are very similar in style to those of the previous version. (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 2 June 1995 34 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) lint program. ftnchek is still blind to some kinds of syntax errors. The two most important ones are detailed checking of FOR- MAT 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 state- ments 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 discus- sion. If ftnchek gives you a syntax error message when the com- piler 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 Exten- sions.) 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. Also, con- sult the README file included in the ftnchek distribution for information on how to control which extensions ftnchek accepts. 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 COM- MON block. By default (-common strictness level 3), ftnchek is very picky about COMMON blocks: the variables listed in them must match exactly by data type and array dimensions. That is, the legal pair of declarations in different modules: COMMON /COM1/ A,B and COMMON /COM1/ A(2) will cause ftnchek to give warnings at strictness level 3. These two declarations are legal in For- tran since they both declare two real variables. At strictness level 1 or 2, no warning would be given in this example, but the warning would be given if there were a data type mismatch, for instance, if B were declared INTEGER. Controlled by -common setting. 2 June 1995 35 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 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 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 inte- ger 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 dif- fer in number of words in declarations in different modules. Given for -common setting 2 or 3. Error: Badly formed logical/relational operator or con- stant 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. 2 June 1995 36 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 state- ment (a statement without a statement label), occurring immediately after a GOTO statement, can- not possibly be executed. Error: Parse error This means that the parser, which analyzes the For- tran 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 sec- tion on Bugs). NOTE: This message means that the affected state- ment 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: 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 state- ments in the Fortran language. Statements which are out of order are nonetheless interpreted by ftnchek, to prevent ``cascades'' of error messages. -------------------------------------------------------- | | implicit | parameter |--------------------- | | other specification format |---------------|--------------------- and | | statement-function entry | data |--------------------- | | executable -------------------------------------------------------- Table 1 2 June 1995 37 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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)). Con- trolled by -portability 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. 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. 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 quanti- ties in a DO statement may cause unexpected errors, or different results on different machines, due to roundoff effects. Controlled by -portability. 2 June 1995 38 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 mis- match, 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 sup- pressed 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 charac- ters 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. (A similar warning is alternatively given under the -f77 flag if the -columns setting is used to increase the statement field width.) Controlled by -pretty. 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 dec- laration of the block. This warning is only given if the two declarations are separated by one or more intervening statements. Controlled by -pretty. 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 inter- spersed with comments, making it easy to overlook. Controlled by -pretty. 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. 2 June 1995 39 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 SUB- ROUTINE or FUNCTION declaration). For instance, if the user defines a subprogram by SUBROUTINE SUBA(X) REAL X and elsewhere invokes SUBA by CALL SUBA(2) ftnchek will detect the error. The reason here is that the number 2 is integer, not real. The user should have said 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 subpro- gram, besides being passed as an actual argument, is also invoked directly elsewhere in the same mod- ule, 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, sub- routines 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 mes- sage. Controlled by -arguments. Subprogram NAME: argument arrayness mismatch at position n Similar to the preceding situation, but the subpro- gram dummy argument differs from the corresponding actual argument in its number of dimensions or num- ber of elements. Controlled by -array together with -arguments. Subprogram NAME: argument mismatch at position n A character dummy argument is larger than the cor- responding actual argument, or a Hollerith dummy 2 June 1995 40 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) argument is larger than the corresponding actual argument. Controlled by -arguments. Subprogram NAME: argument usage mismatch ftnchek detects a possible conflict between the way a subprogram uses an argument and the way in which the argument is supplied to the subprogram. The conflict can be one of two types, as outlined below. Dummy arg is modified, Actual arg is const or expr A dummy argument is an argument as named in a SUB- ROUTINE or FUNCTION statement and used within the subprogram. An actual argument is an argument as passed to a subroutine or function by the caller. ftnchek is saying that a dummy argument is modified by the subprogram, implying that its value is changed in the calling module. The corresponding actual argument should not be a constant or expres- sion, but rather a variable or array element which can be legitimately assigned to. Given for -usage setting 1 or 3. Dummy arg used before set, Actual arg not set Here a dummy argument may be used in the subprogram before having a value assigned to it by the subpro- gram. The corresponding actual argument should have a value assigned to it by the caller prior to invoking the subprogram. Given for -usage setting 1 or 3. These warnings are not affected by the -arguments setting. Subprogram NAME invoked inconsistently Here the mismatch is between the datatype of the subprogram itself as used and as defined. For instance, if the user declares INTEGER FUNCTION COUNT(A) and invokes COUNT in another module as N = COUNT(A) without declaring its datatype, it will default to real type, based on the first letter of its name. The calling module should have included the 2 June 1995 41 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) declaration INTEGER COUNT Given for -arguments setting 2 or 3. Subprogram NAME: varying length argument lists: An inconsistency has been found between the number of dummy arguments (parameters) a subprogram has and the number of actual arguments given it in an invocation. ftnchek keeps track of all invocations of subprograms (CALL statements and expressions using functions) and compares them with the defini- tions of the subprograms elsewhere in the source code. The Fortran compiler normally does not catch this type of error. Given for -arguments setting 1 or 3. Variable not declared. Type has been implicitly defined When printing the symbol table for a module, ftnchek will flag with an asterisk all identifiers that are not explicitly typed and will show the datatype that was assigned through implicit typing. This provides support for users who wish to declare all variables as is required in Pascal or some other languages. This message appears only when the -symtab option is in effect. Alternatively, use the -declare flag if you want to get a list of all undeclared variables. Variables declared but never referenced Detects any identifiers that were declared in your program but were never used, either to be assigned a value or to have their value accessed. Variables in COMMON are excluded. Given for -usage setting 2 or 3. Variables set but never used ftnchek will notify the user when a variable has been assigned a value, but the variable is not oth- erwise used in the program. Usually this results from an oversight. Given for -usage setting 2 or 3. Variables used before set This message indicates that an identifier is used to compute a value prior to its initialization. Such usage may lead to an incorrect value being 2 June 1995 42 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) computed, since its initial value is not con- trolled. Given for -usage setting 1 or 3. Variables may be used before set Similar to used before set except that ftnchek is not able to determine its status with certainty. ftnchek assumes a variable may be used before set if the first usage of the variable occurs prior in the program text to its assignment. Given for -usage setting 1 or 3. Warning: DO index is not integer This warning is only given when the DO bounds are integer, but the DO index is not. It may indicate a failure to declare the index to be an integer. Controlled by -truncation 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 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 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 concate- nated here The Fortran 77 Standard forbids concatenating char- acter variables whose size is an asterisk in paren- theses, except in an assignment statement. Con- trolled by -f77. 2 June 1995 43 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) Warning: Nonstandard syntax: characters past 72 columns A statement has been read which has nonblank char- acters past column 72, with the statement field extended beyond the standard value of 72 columns by the -col setting. Standard Fortran ignores all text in those columns, but some compilers do not. Thus the program may be treated differently by dif- ferent compilers. Controlled by -f77 option and -columns setting. 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 preci- sion variable, etc. Controlled by -truncation option. Warning: subscript is not integer Since array subscripts are normally integer quanti- ties, the use of a non-integer expression here may signal an error. Controlled by -truncation 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 func- tion will be treated by ftnchek as a user-defined function. This warning is not controlled by any option, since it affects ftnchek's analysis of the program. LIMITATIONS AND EXTENSIONS ftnchek accepts ANSI standard Fortran-77 programs with some minor limitations and numerous common extensions. Limitations: 2 June 1995 44 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) ftnchek uses only one line of lookahead when ana- lyzing a program into its basic syntactic elements. If a particular statement is difficult to identify, it may be handled improperly if the ambiguity is not resolved on a single line. This limitation applies to complex constants except in DATA state- ments, and to situations in which a variable name might be confused with a keyword. For example, if the variable name WRITE is used for an array, then a very long statement assigning a value to some element of this array could be mistaken as a WRITE statement if the equals sign is not on the same line as the word WRITE. The dummy arguments in statement functions are treated like ordinary variables of the program. That is, their scope is the entire module, not just the statement function definition. The checking of FORMAT statements is lax, tolerat- ing 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 about nonstandard descriptor types (like O), and supported extensions. The only checking related to control of execution flow is a warning about statements that cannot be reached because they do not have a label and they follow an unconditional transfer. There is no checking for correct nesting of DO loops or match- ing of opening statements such as IF ... THEN with closing statements such as ENDIF, nor the proper definition and use of statement labels. Fortu- nately, most compilers will catch these errors. If a user-supplied subprogram has the same name as one of the nonstandard intrinsic functions, 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 func- tion. Since the nonstandard intrinsics are not standard, this EXTERNAL statement is not required by the Fortran 77 Standard. See the lists of sup- ported nonstandard intrinsic functions under Exten- sions below. Extensions: All of these extensions (except lower-case charac- ters) will generate warnings if the -f77 flag is set. Some of the extensions listed below are part of the Fortran-90 Standard. These are indicated by the notation (F90). 2 June 1995 45 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 -tab option. Strings may be delimited by either quote marks or apostrophes. A sequence of two delimiter charac- ters 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 -backslash flag is set. Otherwise the backslash character will be treated as a normal printing character. Lower case characters are permitted, and are con- verted internally to uppercase except in character strings. The standard specifies upper case only, except in comments and strings. (F90) Hollerith constants are permitted, in accordance with the Fortran 77 Standard, appendix C. They should not be used in expressions, or confused with datatype CHARACTER. The letter 'D' (upper or lower case) in column 1 is treated as the beginning of a comment. There is no option to treat such lines as statements instead of comments. Statements may be longer than 72 columns provided that the setting -column was used to increase the limit. According to the standard, all text from columns 73 through 80 is ignored, and no line may be longer than 80 columns. Variable names may be longer than six characters. The standard specifies six as the maximum. ftnchek permits names up to 31 characters long (F90). Variable names may contain underscores and dollar signs, which are treated the same as alphabetic letters. The default type for variables beginning with these characters is REAL. In IMPLICIT type statements specifying a range of characters, the dollar sign follows Z and is followed by under- score. Fortran 90 permits underscores in variable names. The UNIX version tolerates the presence of prepro- cessor directives, namely lines beginning with the 2 June 1995 46 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 dif- ferent syntax. The DO ... ENDDO control structure is permitted. The syntax which is recognized is according to either of the following two forms: DO [label [,]] var = expr , expr [, expr] ... END DO or DO [label [,]] WHILE ( expr ) ... END DO where square brackets indicate optional elements. This is a subset of the Fortran 90 do-loop syntax. The ACCEPT and TYPE statements (for terminal I/O) are permitted, with the same syntax as PRINT. Statements may have any number of continuation lines. The standard allows a maximum of 19. Inline comments, beginning with an exclamation mark, are permitted. (F90) NAMELIST I/O is supported. The syntax is the same as in Fortran 90. FORMAT statements can contain a dollar sign to indicate suppression of carriage-return. An inte- ger expression enclosed in angle brackets can be used anywhere in a FORMAT statement where the For- tran 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. 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) 2 June 1995 47 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 specifica- tion for a complex quantity whose real and imagi- nary parts are double precision. Mixed-mode arith- metic involving single-precision complex with dou- ble-precision real data, prohibited under the Stan- dard, yields a double complex result. The double complex counterparts of all the standard intrinsic functions for complex data are included: DCMPLX DCONJG DIMAG DREAL IMAG CDABS CDSQRT CDEXP CDLOG CDSIN CDCOS ZABS ZSQRT ZEXP ZLOG ZSIN ZCOS The following other commonly found nonstandard intrinsic functions are provided. All except EXIT and LOC are defined in MIL-STD 1753. BTEST IAND IOR IBSET IBCLR IBITS IEOR ISHFT ISHFTC NOT EXIT LOC For the UNIX version of ftnchek, the following com- mon UNIX intrinsic functions are provided: ABORT AND GETARG GETENV GMTIME IARGC LSHIFT LTIME OR IRAND RAND RSHIFT SRAND SYSTEM TIME XOR Note: there are two common calling sequences for RAND and IRAND: with zero arguments or with 1 argu- ment. By default, ftnchek accepts either form. If you wish to enforce strict adherence to one form or the other, you should compile ftnchek with one of the two macros RAND_NO_ARG or RAND_ONE_ARG set. For the VAX/VMS version of ftnchek, the following common VMS intrinsic functions are provided: DATE ERRSNS IDATE RAN SECNDS SIZEOF TIME 2 June 1995 48 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) Argument checking is not tight for those nonstan- dard intrinsics that take arrays or mixed argument types. ftnchek permits the INCLUDE statement, which causes inclusion of the text of the given file. The syn- tax is INCLUDE 'filename' This is compatible with Fortran 90. When compiled for VMS, ftnchek will assume a default extension of .for if no filename extension is given. Also for compatibility with VMS, the VMS version allows the qualifier /[NO]LIST following the filename, to con- trol 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 speci- fied by both its location in the include file and the location in the parent file where the file was included. ftnchek accepts PARAMETER definitions that involve intrinsic functions and exponentiation by a non- integer exponent. Both of these cases are prohib- ited by the Fortran 77 Standard, and will be warned about if the -f77 flag is set. If an intrinsic function is a compile-time integer constant, ftnchek will evaluate it. This allows better checking if the parameter is used in declaring array sizes. Fortran 90 allows intrinsic functions in PARAMETER definitions. The intrinsic functions that are evaluated are: ABS IABS DIM IDIM MAX MAX0 MIN MIN0 MOD SIGN ISIGN LEN ICHAR INDEX The functions of integer arguments are evaluated only if the arguments are integer constant expres- sions. (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. 2 June 1995 49 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) NEW FEATURES Here are the changes from Version 2.7 to Version 2.8: 1. Improvements in handling command-line settings: add support for colon as assignment operator, and extend setting switch support to include a default value to replace out-of-range values, instead of just choosing the nearer endpoint of the valid range. 2. New options: -makedcls=num to generate variable decla- rations; -backslash to handle UNIX-style backslash escapes in character strings; -resource to print out internal resource usage; -tab to accept DEC-style tab- formatted source. 3. New extensions to syntax: Accept quote marks as an alternative to apostrophes for delimiting strings. Accept 'D' as equivalent to 'C' in column 1 for com- ments. A patch is supplied to allow ``Cray pointer'' syntax to be tolerated. (This patch does not include checking proper use of pointers.) 4. Provide variable names and not just position numbers in warnings about mismatches in common block declara- tions and subprogram argument lists. 5. Add installation validation suite to check for correct functioning after a new installation, or a new compi- lation with a different compiler or compiler options. The validation suite also serves to record input cases that exhibited bugs in older versions of the program, providing regression testing to ensure that changes do not introduce new bugs, or restore old ones. This test suite uncovered compiler optimizer errors on at least one system, errors which did not appear in older versions of ftnchek. 6. Improve memory management to avoid running out of space. 7. Update the UNIX Makefile with new targets following the Free Software Foundation standards, and create the CHECKLIST file to record systems for which this ver- sion of ftnchek has been successfully built and has passed the validation suite tests. 8. Add the man2ps script, and a target in the UNIX Make- file to use it for converting the manual pages file to PostScript. 9. Correct several small typographical irregularities in these manual pages. troff preserves all input spaces, so great care is needed in preparing troff input to avoid introducing spurious space into the typeset 2 June 1995 50 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) output. Grateful acknowledgement is given to Nelson H. F. Beebe of the University of Utah for providing most of these improvements, and especially for writing most of the new code to produce variable declarations, which represents a very substantial effort. Here are the changes from Version 2.6 to Version 2.7: 1. Fixed bugs: to allow statement functions with no argu- ments; to catch extra comma in subprogram argument lists; argument of LEN does not need to have a defined value. 2. Insensitive to blanks as per the Standard. 3. Changed behavior of options: -f77 controls warnings about statement out of order and COMMON block with mixed character and non-character data; -help option now lists patch level and copyright; -novice controls appearance of warning messages. 4. Added handling of explicit precision and double com- plex data type. REAL*8 is no longer synonymous with DOUBLE PRECISION, depending on the machine wordsize. Checking length agreement for character data also done properly now. 5. Checking usage status of COMMON blocks and COMMON variables. 6. Improved format of messages. 7. Support for common nonstandard intrinsic functions. 8. New options: -arguments, -crossref, -reference, -sort, -volatile, -wordsize, and -wrap. 9. Behavior when no top-level non-library modules found, changed from no cross-checking to complete cross- checking. 10. Added expansion of wildcards for filenames on the com- mand line to the VMS and MS-DOS versions. 11. Parser is generated by bison. Formerly yacc was used. 12. Made changes to allow the IBM PC version handle larger files. BUGS ftnchek still has much room for improvement. Your feed- back is appreciated. We want to know about any bugs you 2 June 1995 51 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) 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 con- sidered 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 execu- tion to loop backward to some previously skipped state- ments. 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 rea- son. 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 wel- come. 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 Exten- sions'' 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. 3. A brief description of the bug. 4. If possible, a small sample program showing the bug. The report should be sent to either of the following addresses: MONIOT@FORDMULC.BITNET moniot@mary.fordham.edu Highest priority will be given to bugs which cause ftnchek to crash. Bugs involving incorrect warnings or error 2 June 1995 52 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) messages may take longer to fix. Certain problems that arise when checking large programs can be fixed by increasing the sizes of the data areas in ftnchek. (These problems are generally signaled by error messages beginning with ``Oops''.) The simplest way to increase the table sizes is by recompiling ftnchek with the LARGE_MACHINE macro name defined. Consult the make- file and README file for the method of doing this. The following is a list of known bugs. 1. Bug: Used-before-set message is suppressed for any variable which is used as the loop index in an implied-do loop, even if it was in fact used before being set in some earlier statement. For example, consider J in the statement WRITE(5,*) (A(J), J=1,10) Here ftnchek parses the I/O expression, A(J), where J is used, before it parses the implied loop where J is set. Normally this would cause ftnchek to report a spurious used-before-set warning for J. Since this report is usually in error and occurs fairly commonly, ftnchek suppresses the warning for J altogether. Prognosis: A future version of ftnchek is planned which will handle implied-do loops correctly. 2. Bug: Variables used (not as arguments) in statement- function subprograms do not have their usage status updated when the statement function is invoked. Prognosis: To be fixed in a future version of ftnchek. 3. Bug: VAX version does not expand wildcards in file- names on the command line if they are followed without space by an option, e.g. ftnchek *.f/calltree would not expand the *.f. This is because VMS-style options without intervening space are not supported by the GNU shell_mung routine that is used to expand wildcards. Prognosis: unlikely to be fixed. ACKNOWLEDGEMENTS ftnchek is a public-domain program. It was designed by Dr. Robert Moniot, professor at Fordham University. Dur- ing the academic year of 1988-1989, Michael Myers and Lucia Spagnuolo developed the program to perform the 2 June 1995 53 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) variable usage checks. During the following year it was augmented by Lois Bigbie to check subprogram arguments and COMMON block declarations. Brian Downing assisted with the implementation of the INCLUDE statement. John Quinn wrote the common block usage checks. Nelson H. F. Beebe of the University of Utah added most of the new code to implement the -makedcls feature. The -reference feature was contributed by Gerome Emmanuel, Ecole des mines, U. Nancy (slightly modified). The patch for Cray pointer syntax was provided by John Dannenhoffer of United Tech- nologies Research Center. Additional features will be added as time permits. With Version 2.5, the name was changed from forchek to ftnchek, to avoid confusion with a similar program named forcheck, developed earlier at Lei- den University. We would like to thank John Amor of the University of British Columbia, Reg Clemens of the Air Force Phillips Lab in Albuquerque, Markus Draxler of the University of Stuttgart, Victor Eijkhout of the University of Tennessee at Knoxville, Greg Flint of Purdue University, Daniel P. Giesy of NASA Langley Research Center, Fritz Keinert of Iowa State University, Judah Milgram of the University of Maryland College Park, Hugh Nicholas of the Pittsburgh Supercomputing Center, Dan Severance of Yale University, Phil Sterne of Lawrence Livermore National Laboratory, Larry Weissman of the University of Washington, Warren J. Wiscombe of NASA Goddard, and especially Nelson H. F. Beebe of the University of Utah, for pointing out bugs and suggesting some improvements. We also thank Jack Dongarra for putting ftnchek into the netlib library of publicly available software. INSTALLATION AND SUPPORT The ftnchek program can be obtained by anonymous ftp from many software servers, including host netlib.org (128.169.92.17) where it is located in directory /fortran. Installation requires a C compiler for your computer. See the README file provided with the distribution for instructions on installing ftnchek on your system. Exe- cutable binary in ZIP format for IBM PC computers under MS-DOS is available by anonymous ftp from oak.oakland.edu (141.210.10.117) where it is located in directory /Sim- Tel/msdos/fortran, filename ftnchk28.zip. Executable binary in binhexed stuffit format for Macintosh computers is available from sumex-aim.stanford.edu (36.44.0.6), in directory info-mac/Development, filename ftnchek-28.hqx. The nroff version of this document is named ftnchek.man. On UNIX systems, it can be used as the man page or you can print it using the command nroff -man ftnchek.man | lpr. 2 June 1995 54 FTNCHEK 2.8.3(1L) FTNCHEK 2.8.3(1L) The distribution also includes a plain ASCII version named ftnchek.doc, a PostScript version named ftnchek.ps, and a VMS HELP version named ftnchek.hlp. Information about the latest version and the status of the project can be obtained by the Internet command ``finger ftnchek@mary.fordham.edu''. For further information and to report bugs, you may contact Dr. Robert Moniot at either of the following network addresses: MONIOT@FORDMULC.BITNET moniot@mary.fordham.edu SEE ALSO dcl2inc(1L), dtoq(1L), dtos(1L), f77(1), fd2s(1L), fs2d(1L), pfort(1L), qtod(1L), sf3(1L), stod(1L). xsf3(1L). 2 June 1995 55