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.hlp < prev next >

Wrap

Text File | 1995-06-02 | 48KB | 991 lines

1 FTNCHEK ftnchek - Fortran program checker 2 Introduction ftnchek (short for Fortran checker) is designed to detect cer- tain errors in a Fortran program that a compiler usually does not. ftnchek is not primarily intended to detect syntax errors. Its pur- pose is to assist the user in finding semantic errors. Semantic errors are legal in the Fortran language but are wasteful or may cause incorrect operation. For example, variables which are never used may indicate some omission in the program; uninitialized vari- ables contain garbage which may cause incorrect results to be calcu- lated; 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. For more detailed information, consult the printed documentation. 2 Invoking_Ftnchek ftnchek is invoked through a command of the form: $ ftnchek [/option /option ...] filename [filename ...] The brackets indicate something which is optional. The brackets themselves are not actually typed. Here options are command-line switches or settings, which control the operation of the program and the amount of information that will be printed out. If no option is specified, the default action is to print error messages, warnings, and informational messages, but not the program listing or symbol tables. Each option begins with the '/' character. (ftnchek also allows the '-' character to be used.) ftnchek options fall into two categories: switches, which are either true or false, and settings, which have a numeric or string value. The name of a switch is prefixed by 'no' to turn it off: e.g. /nopure would turn off the warnings about impure functions. The 'no' prefix can also be used with numeric settings, having the effect of turning off the corresponding warnings. 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. When more than one option is used, they should be separated by a blank space, except on systems such as VMS where options begin with slash ( / ). No blank spaces may be placed around the equals sign ( = ) in a setting. ftnchek "?" will produce a command summary list- ing all options and settings. 2 Files 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. 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. If no filename is given, ftnchek will read input from the stan- dard input. 2 Options 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 or numeric setting can be preceded by 'no' to turn it off: e.g. /nousage would turn off the warnings about variable usage. Only the first 3 characters of an option name (not counting the '/') need be provided. Most options are positional: each option remains in effect from the point it is encountered until it is overridden by a later change. 3 /arguments=num Controls warnings about mismatches between actual and dummy subprogram arguments. (An actual argument 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 arguments and of func- tion itself. 3: all warnings. Default = 3. This setting is provided mainly to suppress warnings 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 functions or statement functions. See also: /array, /library, /usage. 3 /array=num Controls the degree of strictness in checking agreement between actual and dummy subprogram arguments that are arrays. The warnings controlled by this setting are for constructions that might legiti- mately 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 intentional (see note below). 1: warn if the arguments differ in their number of dimensions, or if the actual argument is an array element while the dummy argument is a whole array. 2: warn if both arguments are arrays, but they differ in number of elements. 3: give both types of warnings. Default = 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 expres- sion while the dummy argument is an array. No warning is ever given if the actual argument is an array element while the dummy argument is a scalar variable. Variable-dimensioned arrays and arrays dimen- sioned 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. 3 /backslash Handle UNIX-style backslash escapes in character strings. The escape sequence following the backslash will be evaluated according to the ANSI standard for strings in C: up to three digits signify an octal value, an x signifies the start of a hexadecimal constant, any of the letters a b f n r t signify special control codes, and any other character (including newline) signifies the character itself. When this 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 porta- bility 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 back- slash is used to escape the end-of-line in order to continue a string across multiple source lines; or (c) a PARAMETER definition uses an intrinsic string function such as LEN with such a string as argument, and that value is later used to define array dimensions, etc. 3 /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 routine, its call subtree is printed only the first time it is encountered. Later calls give only the routine name and the notice ``(see above)''. 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 pro- gram is found, a report to that effect is printed out, and the call trees of any top-level non-library routines are printed. This flag only controls the printing of the call tree: ftnchek constructs the call tree in any case because it is used to determine which library modules will be cross-checked. See the discussion of the /library flag. See also: /crossref, /library, /reference, /sort, /symtab. 3 /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 132. Default = 72. 3 /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 mem- ory 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 programming practice. See also: /library, /usage, /volatile. 3 /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. 3 /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. 3 /division This switch is provided to help users spot potential division by zero problems. If this switch is selected, every division except by a constant will be flagged. (It is assumed that the user is intelligent enough not to divide by a constant which is equal to zero!) Default = no. See also: /portability, /truncation. 3 /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. 3 /f77 Use this flag to catch language extensions which violate the Fortran 77 Standard. Such extensions may cause your program not to be portable. Examples include the use of underscores in variable names; variable names longer than six characters; statement lines longer than 72 characters; and nonstandard statements such as the DO ... ENDDO structure. ftnchek does not report on the use of lowercase letters. Default = no. See also: /portability, /pretty, /wordsize. 3 /help Prints a list of all the command-line options with a short description of each along with its default value. This command is identical in function to the ``?'' argument, and is provided as a convenience for those systems in which the question mark has special meaning to the command interpreter. Default = no. The help listing also prints the version number and patch level of ftnchek and a copyright notice. Note: the ``default'' values printed in square brackets in the help listing are, strictly speaking, not the built-in defaults but the current values after any environment options and any command-line options preceding the /help option have been processed. 3 /hollerith Hollerith constants (other than within FORMAT specifications) are a source of possible portability problems, so when the /portabil- ity 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 sup- press the warnings about Holleriths. This flag has no effect unless the /portability flag (which is off by default) is turned on. Default = yes. See also: /portability. 3 /include=path Specifies a directory to be searched for files specified by INCLUDE statements. Unlike other command-line options, this setting is cumulative; that is, if it is given more than once on the command line, all the directories so specified are placed on a list that will be searched in the same order as they are given. The order in which ftnchek searches for a file to be included is: the current directory; the directory specified by environment variable FTNCHEK_INCLUDE if any; the directories specified by any /include options; the directory specified by environment variable INCLUDE; and finally in a standard systemwide directory (/usr/include for UNIX, SYS$LIBRARY for VMS, and \include for MSDOS). 3 /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 decla- rations 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 con- structing 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. 3 /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. 3 /makedcls=num Prepare a neatly-formatted file of declarations of variables, common blocks, and namelist lists, for possible merging into the source code. The declarations are stored in a file of the same name as the source code, but with the extension changed to .dcl. If no declarations are written to the file, it is deleted to reduce clutter from empty files. If input comes from standard input, instead of a named file, then declarations are written to standard output. Variables are declared in alphabetical order within each declara- tion class and type, with integer variables first, because of their later possible use in array dimensions. PARAMETER statements are an exception to the alphabetical order rule, because the Fortran 77 Standard requires that the expressions defining parameter values refer only to constants and already-defined parameter names. This forces the original source file order of such statements to be preserved in the declaration files. Explicit declaration of all variables is considered good modern programming practice. By using compiler options to reject undeclared variables, misspelled variable names (or names extending past column 72) can be caught at compile time. Explicit declarations also greatly facilitate changing floating-point precision with filters such as dtoq(1L), dtos(1L), fd2s(1L), fs2d(1L), qtod(1L), and stod(1L). These programs are capable of changing types of explicit floating-point type declarations, intrinsic functions, and constants, but because they do not carry out rigorous lexical and grammatical analysis of the Fortran source code, they cannot provide modified type declarations for undeclared variables. 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 vari- ables, 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 unde- clared. 4: The declarations are normally prettyprinted to line up neatly in common columns, as in the declaration files output by the Extended PFORT Verifier, pfort(1L). This option value selects instead compact output, without column alignment. 8: Causes continuation lines to be used where permissible. The default is to begin a new declaration on each line. This option is appropriate to use with the option for compact out- put. 16: Output Fortran keywords in lowercase, instead of the default uppercase. 32: Output variables and constants in lowercase, instead of the default uppercase. Character string constants are not affected by this option. 64: Omit declarations of internal integer variables produced by the SFTRAN3 preprocessor, xsf3(1L), as part of the translation of structured Fortran statements to ordinary Fortran. These variables have six-character names of the form NPRddd, NXdddd, N2dddd, and N3dddd, where d is a decimal digit. Because they are invisible in the SFTRAN3 source code, and will change if the SFTRAN3 code is modified, such variables should not be explicitly declared. Instead, they should just assume the default Fortran INTEGER data type based on their initial let- ter, N. 128: Use an asterisk as the comment character; the default is oth- erwise 'C'. 256: Use 'c' instead of 'C' or '*' as the comment character. If any non-zero value is specified, then declaration output is selected, even if the value 1 was not included in the sum. The declaration files contain distinctive comments that mark the start and end of declarations for each program unit, to facilitate using text editor macros for merging the declarations back into the source code. 3 /novice This flag is intended to provide more helpful output for begin- ners. 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. 3 /output=filename This setting is provided for convenience on systems which do not allow easy redirection of output from programs. When this set- ting is given, the output which normally appears on the screen will be sent instead to the named file. Note, however, that operational errors of ftnchek itself (e.g. out of space or cannot open file) will still be sent to the screen. The extension for the filename is optional, and if no extension is given, the extension .lis will be used. 3 /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 variables of different data types. This option does not produce warnings for supported extensions to the Fortran 77 Standard, which may also cause portability problems. To catch those, use the /f77 option. Default = no. See also: /backslash, /f77, /hollerith, /pretty, /wordsize. 3 /pretty Controls certain messages related to the appearance 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 com- ments that are interspersed among the continuation lines of a state- ment, lack of space between a keyword and a following variable name, and statement lines containing characters past column 72. See also: /f77, /portability. 3 /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 standard 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 /noextern flags at this time, to suppress messages relating to consistency with other files. Only error messages pertaining to each file by itself will be printed at this time. Thereafter, run ftnchek without these flags on all the project files together, to check consistency among the different files. All messages internal to the individual files will now be omitted. Only when a file is altered will a new project file need to be made for it. Naturally, when the /project flag is set, ftnchek will not read project files as input. Project files contain only information needed for checking agree- ment 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 Pro- ject Files. 3 /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 func- tions will be handled the same way as actual arguments passed to sub- routines. This means that ftnchek will assume that arguments may be modified by the functions. No warnings will be given if a function is found to have side effects. Because stricter checking is possible if functions are assumed to be pure, you should turn this flag off only if your program actually uses functions with side effects. 3 /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 mod- ules. Thus it contains the same information as for the /calltree flag, namely the hierarchy of subprogram calls, but printed in a dif- ferent 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. 3 /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 par- ticular program. Default = no. In this listing, the term ``chunk size'' is the size of the blocks of memory allocated to store the item in question, in units of the size of one item, not necessarily in bytes. When the initially allocated space is filled up, more memory is allocated in chunks of this size. The following is an explanation of the items printed: Source lines processed: Total number of lines of code, with sepa- rate totals for statement lines and comment lines. Comment lines include lines with 'C' or '*' in column 1 as well as blank lines and lines containing only an inline comment. Statement lines are all other lines, including lines that have an inline comment following some code. Continuation lines are counted as separate lines. Lines in include files are counted each time the file is included. Total executable statements: Number of statements in the program, other than specification, data, statement-function, FORMAT, ENTRY, and END statements. Total number of modules: A module is any external subprogram, including the main program, subroutines, functions, and block data units. This count is of modules defined within the source, not modules referenced. Statement functions are not included. A subprogram with multiple entry points is only counted once. Max identifier name chars: Number of characters used for storing identifier names. An identifier is a variable, subprogram, or common block name. Local names are those of local variables in a subprogram, whereas global names refer to subprogram and common block names, as well as dummy argument names and common variable names. Actual argument text (up to 15 characters for each argument) is also included here. The space used for local names is recovered at the end of each module, whereas the global space grows until the whole program is analyzed. Unfortunately, this figure may include some common block names and arguments stored more than once, although a heuristic is used that will avoid duplicates in many cases. Max token text chars: A token is the smallest syntactic unit of the FORTRAN language above the level of individual characters. For instance a token can be a variable name, a numerical con- stant, 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 symbol table entries include all variables and parameters, common block names, statement functions, external subprograms and intrinsic func- tions referenced by the module. Literal constants are not stored in the local symbol table. Max global symbols: This is the number of entries in the global symbol table at the end of processing. Global symbol table entries include external subprogram and common block names. Intrinsic functions and statement functions are not included. Max number of tokenlists: A token list is a sequence of tokens representing the actual or dummy argument list of a subpro- gram, or the list of variables in a common block or namelist. Therefore this number represents the largest sum of COMMON, CALL, NAMELIST and ENTRY statements and function invocations for any one module. The space is recovered at the end of each module. Max token list/tree space: This is the largest number of tokens in all the token lists and token trees of any one module. A token tree is formed when analyzing an expression: each operand is a leaf of the tree, and the operators are the nodes. Therefore this number is a measure of the maximum com- plexity of an individual module. For instance a module with many long arithmetic expressions will have a high number. Note that unlike token text described above, the number of tokens is independent of the length of the variable names or literal constants in the expressions. Number of subprogram invocations: This is the sum over all modules of the number of CALL statements and function invocations (except intrinsic functions and statement functions). Number of common block decls: This is the sum over all modules of the number of common block declarations. That is, each decla- ration of a block in a different module is counted separately. (The standard allows multiple declarations of a block within the same module; these are counted as only one declaration since they are equivalent to a single long declaration.) Number of array dim & param ptrs: This is the sum over all modules of the number of array dimension and parameter definition text strings saved for use by the /makedcls option. The length of the text strings is not counted. Each dimension of a multidi- mensional array is counted separately. These numbers are obviously not the same when project files are used in place of the original source code. Even the numbers for global entities may be different, since some redundant information is eliminated in project files. 3 /sixchar One of the goals of the ftnchek program is to help users to write portable Fortran programs. One potential source of nonporta- bility is the use of variable names that are longer than six charac- ters. Some compilers just ignore the extra characters. This behav- ior could potentially lead to two different variables being consid- ered as the same. For instance, variables named AVERAGECOST and AVERAGEPRICE are the same in the first six characters. If you wish to catch such possible conflicts, use this flag. Default = no. Use the /f77 flag if you want to list all variables longer than six characters, not just those pairs that are the same in the first six. See also: /f77, /portability. 3 /sort Specifies that a sorted list of all modules used in the program be printed. This list is in ``prerequisite'' order, i.e. each module is printed only after all the modules from which it is called have been printed. This is also called a ``topological sort'' of the call tree. Each module is listed only once. Routines that are not in the call tree of the main program are omitted. If there are any cycles in the call graph (illegal in standard Fortran) they will be detected and diagnosed. Default = no. See also: /calltree, /crossref, /reference, /symtab. 3 /symtab A symbol table will be printed out for each module, listing all identifiers mentioned in the module. This table gives the name of each variable, its datatype, and the number of dimensions for arrays. An asterisk (*) indicates that the variable has been implicitly typed, rather than being named in an explicit type declaration state- ment. The table also lists all subprograms invoked by the module, all COMMON blocks declared, etc. Default = no. See also: /calltree, /crossref, /list, /reference, /sort. 3 /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. 3 /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 exponent, 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 conversion of a complex value to real or integer; (f) conversion of a double precision value to single 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 automatically, 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 possible loss of accuracy that is similar to the correspond- ing demotions. See also: /portability, /wordsize. 3 /usage=num Warn about unused or possible uninitialized variables 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 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 warnings. Usually it errs on the side of giving a warning where no problem exists, but in rare cases it may fail to warn where the problem does exist. See the section on Bugs for examples. If variables are equivalenced, the rule used by ftnchek is that a reference to any variable implies the same reference to all variables it is equivalenced to. For arrays, the rule is that a reference to any array element is treated as a reference to all elements of the array. 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 routines are called before others. So warnings about this type of error will only be given for cases in which a variable is used in some routine but not set in any other routine. Checking of individual COMMON variables is done only if the /common setting is 3 (variable by variable agreement). See also: /common, /declare, /volatile. 3 /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 apparent. This option is provided for the convenience of users who are checking large suites of files. The eliminated output includes the names of project files, and the message reporting that no syntax errors were found. (Some of this output is turned back on by the /list and /symtab options.) Default = yes. 3 /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 permanently until assigned a different value by the pro- gram. However, in fact the Fortran 77 Standard does not require this to be the case. Local variables may become undefined between activa- tions of a module in which they are declared. Similarly, COMMON blocks may become undefined if no module in which they are declared is active. (The technical term for this behavior is ``automatic'', but ftnchek uses the word ``volatile'' since it is clearer to the nonspecialist.) Only COMMON blocks declared in a SAVE statement, or declared in the main program or in a block data subprogram remain defined as long as the program is running. Variables and COMMON blocks that can become undefined at some point are called volatile. If the /volatile flag is turned on, ftnchek will warn you if it finds a volatile COMMON block. If, at the same time, the /usage set- ting 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. 3 /wordsize=num Specifies the default word size to be num bytes. This is the size of logical and single-precision numeric variables that are not given explicit precisions. Double-precision and complex variables will be twice this value, and double complex variables four times. Explicit precisions for non-character variables are an extension to the Fortran 77 Standard, and are given by type declarations such as REAL*8 X. 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 Hol- lerith data in variables. This setting also does not affect the default size of character variables, which is always 1 byte. Hol- lerith constants also are assumed to occupy 1 byte per character. The word size is used to determine whether truncation occurs in assignment statements, and to catch precision mismatches in subpro- gram 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 precision objects (character expressions not included) is warned about. This applies to arithmetic expressions containing both types of objects, and to subprogram arguments and COMMON variables. Under 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 precision value to higher precision in an arithmetic expression or an assignment statement. Giving a word size of 0, or equivalently, using /nowordsize means that no default value will be assumed. Use this instead of /porta- bility 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. 3 /wrap=col Controls the wrapping of error messages. Long error messages that would run past the specified column will be broken up into sepa- rate lines between the words of the message for better readability. If turned off with /nowrap, each separate error message will be printed on one line, leaving it up to the display to wrap the message or truncate it. Default = 79. 2 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 setting. In the case of settings (for example, the /common strictness setting) the value of the environment variable is read as the default setting value. In the case of switches, the default switch will be taken as true or yes unless the environment variable has the value 0 or NO. 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 constructed with the full-length option name, which must be in uppercase. For exam- ple, to make ftnchek print a source listing by default, set the envi- ronment 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. The way to set the environment variables on the VAX/VMS system is by using the DEFINE command. For example, to set the default /list switch to YES, give the command $ DEFINE FTNCHEK_LIST 1 2 Project_files This section contains detailed information on how to use pro- ject files most effectively, and how to avoid some pitfalls. Ordinarily, project files should be created with the /library flag in effect. In this mode, the information saved in the project file consists of all subprogram declarations, all subprogram invoca- tions not resolved by declarations in the same file, and one instance of each COMMON block declaration. This is the minimum amount of information needed to check agreement between files. If the file contains more than one routine, there are some pos- sible 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 pro- ject 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 pro- ject file is read in later, it will be treated as a library file regardless of the current setting of the /library flag. On the other hand, a project file created with library mode turned off can be read in later in either mode.