1 21 FTNCHEK 3 ftnchek - Fortran 77 program checker 4 52 Introduction 6 ftnchek (short for Fortran checker) is designed to detect cer- 7 tain errors in a Fortran program that a compiler usually does not. 8 ftnchek is not primarily intended to detect syntax errors. Its pur- 9 pose is to assist the user in finding semantic errors. Semantic er- 10 rors are legal in the Fortran language but are wasteful or may cause 11 incorrect operation. For example, variables which are never used may 12 indicate some omission in the program; uninitialized variables con- 13 tain garbage which may cause incorrect results to be calculated; and 14 variables which are not declared may not have the intended type. ft- 15 nchek is intended to assist users in the debugging of their Fortran 16 program. It is not intended to catch all syntax errors. This is the 17 function of the compiler. Prior to using ftnchek, the user should 18 verify that the program compiles correctly. 19 20 For more detailed information, consult the printed documentation. 21 222 Invoking_Ftnchek 23 ftnchek is invoked through a command of the form: 24 25 $ ftnchek [/option /option ...] filename [filename ...] 26 The brackets indicate something which is optional. The brackets 27 themselves are not actually typed. Here options are command-line 28 switches or settings, which control the operation of the program and 29 the amount of information that will be printed out. If no option is 30 specified, the default action is to print error messages, warnings, 31 and informational messages, but not the program listing or symbol ta- 32 bles. 33 34 Each option begins with the '/' character. (ftnchek also allows 35 the '-' character to be used.) 36 ftnchek options fall into two categories: switches, which are 37 either true or false, and settings, which have a numeric or string 38 value. The name of a switch is prefixed by 'no' or 'no-' to turn it 39 off: e.g. /nopure would turn off the warnings about impure functions. 40 The 'no' prefix can also be used with numeric settings, having the 41 effect of turning off the corresponding warnings. Settings that con- 42 trol lists of warnings have a special syntax discussed below. Only 43 the first 3 characters of an option name (not counting the '/') need 44 be provided. A colon may be used in place of an equals sign for nu- 45 meric or string setting assignments; however, we show only the equals 46 sign form below. 47 48 When more than one option is used, they should be separated by a 49 blank space. No blank spaces may be placed around the equals sign ( 50 = ) in a setting. ftnchek "?" will produce a command summary list- 51 ing all options and settings. 52 For settings that take a list of keywords, namely /arguments, 53 /array, /calltree, /common, /crossref, /f77, /f90, /f95, /intrinsic, 54 /makedcls, /mkhtml, /portability, /pretty, /project, /source, /style, 55 /truncation, and /usage, the list consists of keywords separated by 56 commas or colons. If the list of keywords is omitted, the effect is 57 to set the option to its turn-on value (same as ''all'' in most cas- 58 es). Also, if the list is omitted, the setting name can be prefixed 59 with no or no- to turn off all the options it controls. For example, 60 /f77 turns on all warnings about nonstandard constructions, while 61 /nof77 turns them all off. Three special keywords are: 62 help Print out all the option keywords controlled by the setting, 63 with a brief explanation of their meanings. This keyword can- 64 not be given in a list with other keywords. 65 all Set all options. This turns on all options controlled by the 66 setting. 67 none Clear all options. This turns off all options controlled by 68 the setting. 69 These three special keywords must be given in full. For all 70 other keywords, only as many letters of the keyword as are necessary 71 to identify it unambiguously need be given, or a wildcard pattern may 72 be used. Including a keyword in the list turns the corresponding op- 73 tion on. For example, /f77=intrinsic would turn on only the warnings 74 about use of nonstandard intrinsic functions. Prefixing a keyword by 75 no- turns its option off. For example, /pretty=no-long-line turns 76 off warnings about lines exceeding 72 columns in length while leaving 77 all other warnings about misleading appearance in effect. If a set- 78 ting has default none, you can turn on all options except one or two 79 by using all first. For example, /f77=all,no-include enables warn- 80 ings about all nonstandard extensions except INCLUDE statements. If 81 a setting has default all, you can turn off all warnings except one 82 or two by using none first. For example, /truncation=none,demotion 83 would turn off all precision related warnings except about demotions. 84 Wildcard patterns contain an asterisk to stand for any string of 85 characters. If a wildcard pattern is used, all the warnings that 86 match it are affected. If no- is prefixed to the pattern, all the 87 matching warnings are turned off, otherwise they are all turned on. 88 The minimum unambiguous length rule does not apply to wildcard match- 89 ing. For example, use /usage=no-*var* to turn off all warnings re- 90 lating to variable usage (both local and common). (Unix users may 91 need to quote any options containing wildcards in order to prevent 92 the shell from attempting to expand them.) Wildcards are recognized 93 only in lists of warning keywords, not in the top-level options them- 94 selves. 95 When ftnchek starts up, it looks for environment variables and 96 also for a preferences file. Any options defined in the environment 97 or in the preferences file are used as defaults in place of the 98 built-in defaults. They are over-ridden by any command line options. 99 See the section on changing the defaults for details about the envi- 100 ronment options and the preferences file. 101 1022 Files 103 When giving a name of an input file, the extension is optional. 104 If no extension is given, ftnchek will first look for a project file 105 with extension .prj, and will use that if it exists. If not, then 106 ftnchek will look for a Fortran source file with the extension .for. 107 More than one file name can be given to ftnchek, and it will process 108 the modules in all files as if they were in a single file. 109 110 Wildcards are allowed in the specification of filenames on the 111 command line. 112 If no filename is given, ftnchek will read input from the stan- 113 dard input. 114 115 1162 Options 117 ftnchek options fall into two categories: switches, which are 118 either true or false, and settings, which have a numeric or string 119 value. The name of a switch or numeric setting can be preceded by 120 'no' to turn it off: e.g. /nocommon would turn off the warnings about 121 common block inconsistencies. Only the first 3 characters of an op- 122 tion name (not counting the '/') need be provided. Most options are 123 positional: each option remains in effect from the point it is en- 124 countered until it is overridden by a later change. 125 126 1273 /arguments=list 128 Controls warnings about mismatches between actual and dummy 129 subprogram arguments, and also about mismatches between expected and 130 actual subprogram type. (An actual argument is an argument passed to 131 the subprogram by the caller; a dummy argument is an argument re- 132 ceived by the subprogram.) By default, all warnings are turned on. 133 The list consists of keywords separated by commas or colons. 134 Since all these warnings are on by default, include a keyword pre- 135 fixed by no- to turn off a particular warning. There are three spe- 136 cial keywords: all to turn on all the warnings about arguments, none 137 to turn them all off, and help to print the list of all the keywords 138 with a brief explanation of each. If list is omitted, /arguments is 139 equivalent to /arguments=all, and /noarguments is equivalent to /ar- 140 guments=none. The warning keywords with their meanings are as fol- 141 lows: 142 arrayness: warn about inconsistent use of arguments that are ar- 143 rays. These warnings can be further controlled by the /array 144 option. 145 type: warn about dummy arguments of a different data type from the 146 actual arguments. 147 function-type: warn if the invocation assumes the function's re- 148 turn value is a different type than it actually is. Also 149 warns if a function is called as a subroutine, or vice-versa. 150 number: warn about invoking a subprogram with a different number 151 of arguments than the subprogram expects. 152 For compatibility with previous versions of ftnchek, a numeric 153 form of this setting is also accepted: the list is replaced by a num- 154 ber from 0 to 3. A value of 0 turns all the warnings off, 1 turns on 155 only number, 2 turns on all except number, and 3 turns all the warn- 156 ings on. 157 This setting does not apply to checking invocations of intrinsic 158 functions or statement functions, which can only be turned off by the 159 /nocheck option. 160 See also: /array, /library, /usage. 161 162 1633 /array=list 164 Controls the degree of strictness in checking agreement between 165 actual and dummy subprogram arguments that are arrays. The warnings 166 controlled by this setting are for constructions that might legiti- 167 mately be used by a knowledgeable programmer, but that often indicate 168 programming errors. By default, all warnings are turned on. 169 The list consists of keywords separated by commas or colons. 170 Since all these warnings are on by default, include a keyword pre- 171 fixed by no- to turn off a particular warning. There are three spe- 172 cial keywords: all to turn on all the warnings about array arguments, 173 none to turn them all off, and help to print the list of all the key- 174 words with a brief explanation of each. If list is omitted, /array 175 is equivalent to /array=all, and /noarray is equivalent to /ar- 176 ray=none. The warning keywords with their meanings are as follows: 177 dimensions: warn if the arguments differ in their number of dimen- 178 sions, or if the actual argument is an array element while the 179 dummy argument is a whole array. 180 size: warn if both arguments are arrays, but they differ in number 181 of elements. 182 For compatibility with previous versions of ftnchek, a numeric 183 form of this setting is also accepted: the list is replaced by a num- 184 ber from 0 to 3. A value of 0 turns all the warnings off, 1 turns on 185 only dimensions, 2 turns on only size, and 3 turns all the warnings 186 on. 187 Note: A warning is always given regardless of this setting if 188 the actual argument is an array while the dummy argument is a scalar 189 variable, or if the actual argument is a scalar variable or expres- 190 sion while the dummy argument is an array. These cases are seldom 191 intentional. (To turn off even these warnings, use /arguments=no-ar- 192 rayness.) No warning is ever given if the actual argument is an ar- 193 ray element while the dummy argument is a scalar variable. Variable- 194 dimensioned arrays and arrays dimensioned with 1 or asterisk match 195 any number of array elements. There is no check of whether multi-di- 196 mensional arrays agree in the size of each dimension separately. 197 See also: /arguments, /library, /usage. 198 199 2003 /brief 201 Selects a shorter format for some warning messages. At 202 present, the only warnings controlled by this flag are those that are 203 printed at the end of processing each subprogram. These include 204 warnings about variables that are set but not used or used before 205 set, variable names that do not conform to the Fortran 77 standard, 206 etc. (These warnings may be suppressed entirely depending on other 207 flags, such as the /usage or /f77 flags.) In the default format each 208 variable is listed on a separate line, along with the line number 209 where the variable is declared, set or used, according to the nature 210 of the warning. The briefer format simply lists all variables to 211 which the warning applies, with up to 4 variables per line. 212 See also: /quiet. 213 214 2153 /calltree=list 216 Causes ftnchek to print out the call structure of the complete 217 program. 218 The list consists of keywords separated by commas or colons. 219 There are two special keywords: none to turn off all the options, and 220 help to print the list of all the keywords with a brief explanation 221 of each. (The keyword all turns on all the options, but should not 222 normally be used since only one format should be specified.) If list 223 is omitted, /calltree is equivalent to /calltree=tree, and /nocall- 224 tree is equivalent to /calltree=none. By default no call graph is 225 printed. 226 If the /mkhtml option is invoked and tree is the applied call- 227 tree option, a file named CallTree.html, will also be produced de- 228 picting the tree in HTML format. This file is useful as a starting 229 point for browsing the HTML files describing each component of the 230 program. 231 The keywords which control which format is used are as follows: 232 tree: produce the call graph in tree format. 233 reference: produce the call graph in who-calls-who format (same as 234 /reference switch). 235 vcg: produce the call graph in VCG format (same as /vcg switch). 236 Only one of the formats tree, reference, or vcg may be speci- 237 fied. 238 The following keywords control options affecting the output: 239 prune: prune repeated subtrees (applicable only with tree). This 240 the default. 241 sort: sort children of each routine into alphabetical order. This 242 is the default. 243 See the discussion of the /reference and /vcg flags for details 244 about these formats. 245 For tree format, The call graph is printed out starting from the 246 main program, which is listed on the first line at the left margin. 247 Then on the following lines, each routine called by the main program 248 is listed, indented a few spaces, followed by the subtree starting at 249 that routine. 250 In the default mode, if a routine is called by more than one 251 other routine, its call subtree is printed only the first time it is 252 encountered Later calls give only the routine name and the notice 253 ''(see above)''. To have the subtree printed for each occurrence of 254 the routine, use option no-prune. 255 Note that the call tree will be incomplete if any of the input 256 files are project files containing more than one module that were 257 created in /library mode. See the discussion of project files below. 258 Technical points: Each list of routines called by a given rou- 259 tine is printed in alphabetical order unless the no-sort option is 260 given. If multiple main programs are found, the call tree of each is 261 printed separately. If no main program is found, a report to that 262 effect is printed out, and the call trees of any top-level non-li- 263 brary routines are printed. This flag only controls the printing of 264 the call tree: ftnchek constructs the call tree in any case because 265 it is used to determine which library modules will be cross-checked. 266 See the discussion of the /library flag. 267 For compatibility with previous versions of ftnchek, a numeric 268 form of this setting is also accepted: the list is replaced by a num- 269 ber from 0 to 15. This number is formed from 1 for tree format, 2 270 for reference format, or 3 for vcg format, plus 4 for no-prune, and 8 271 for no-sort. 272 See also: /crossref, /library, /reference, /sort, /symtab, /vcg. 273 274 2753 /check 276 This switch is provided so that errors and warning messages can 277 be turned off when ftnchek is used for purposes other than finding 278 bugs, such as making declarations or printing the call tree. It is 279 positional, so after turning all checks off, selected checks can be 280 turned back on. The effect of /nocheck is to put all switches, nu- 281 meric settings, and settings controlling lists of warnings to their 282 turn-off values, as if they had all been specified with the /no pre- 283 fix. Switches and settings that specify options and modes of opera- 284 tion, rather than controlling warnings, are unaffected. These are 285 /columns, /crossref, /include, /intrinsic, /library, /list, /maked- 286 cls, /novice, /output, /pointersize, /project, /quiet, /reference, 287 /resources, /sort, /source, /symtab, /vcg, /version, /wordsize, and 288 /wrap. Default = yes. 289 Parse errors (syntax errors due to unrecognized or malformed 290 statements) are not suppressed by this switch, since the results may 291 be incorrect if ftnchek has not parsed the program correctly. 292 There are some miscellaneous errors and warning messages that 293 are not controlled by any other switch, and so can be turned off only 294 by this switch. Note that using /check following /nocheck only has 295 the effect of turning these special warnings back on, and does not 296 restore all the checks it turned off. These warnings are: 297 o Module contains no executable statements. 298 o In free source form, missing space where space is required (e.g. 299 between a keyword and an identifier) or space present where 300 none is allowed (e.g. within an identifier). 301 o Zero or negative length specification in a data type declaration 302 of the form type*len. 303 o Invalid operand(s) in an expression. 304 o Array assigned to scalar. 305 o Type mismatch between DO index and bounds. 306 o Undefined common block declared in SAVE statement. 307 o Intrinsic function explicitly declared with an incompatible 308 type. 309 o Unknown intrinsic function explicitly declared in an INTRINSIC 310 statement. 311 o Intrinsic function passed as a subprogram argument is not de- 312 clared in an INTRINSIC statement. 313 o Intrinsic function or statement function invoked incorrectly. 314 o Function does not set return value prior to RETURN statement. 315 o Parameter constant value not evaluated (this is ftnchek's fault, 316 and it is just informing you of the fact). 317 o Entry point of a subprogram is later used as a different subpro- 318 gram's name. 319 o Unknown keyword used in an I/O statement. 320 o Illegal label reference (e.g. GOTO refers to a non-executable 321 statement; I/O statement refers to a non-format statement). 322 See also: /errors. 323 324 325 3263 /columns=num 327 Set maximum statement length to num columns. (Beyond this is 328 ignored.) This setting is provided to allow checking of programs 329 which may violate the Fortran standard limit of 72 columns for the 330 length of a statement. According to the standard, all characters 331 past column 72 are ignored. If this setting is used when the 332 /f77=long-line option is in effect, a warning will be given for any 333 lines in which characters past column 72 are processed. Turn-on = 334 max = 132. Default = 72. 335 This setting does not suppress warnings about the presence of 336 characters beyond column 72. To process code with meaningful program 337 text beyond column 72, use this setting and be sure the /f77 338 long-line option is off. To process code with sequence numbers in 339 columns 73 to 80, leave the the columns setting at the default value 340 and use the /pretty=no-long-line flag. 341 See also: /f77, /pretty. 342 343 3443 /common=list 345 This setting controls the strictness of checking of COMMON 346 blocks. By default, all warnings except volatile are turned on. 347 The list consists of keywords separated by commas or colons. 348 Since most of these warnings are on by default, include a keyword 349 prefixed by no- to turn off a particular warning. There are three 350 special keywords: all to turn on all the warnings, none to turn them 351 all off, and help to print the list of all the keywords with a brief 352 explanation of each. If list is omitted, /common is equivalent to 353 /common=dimensions,exact,length,type, and /nocommon is equivalent to 354 /common=none. The warning keywords with their meanings are as fol- 355 lows: 356 dimensions: corresponding arrays in each declaration of a block 357 must agree in size and number of dimensions. This option only 358 has an effect when used together with exact. 359 exact: the comparison of two blocks is done variable-by-variable 360 rather than simply requiring agreement between corresponding 361 storage locations. Use this if all declarations of a given 362 COMMON block are supposed to be identical, which is a good 363 programming practice. 364 length: warn if different declarations of the same block are not 365 equal in total length. The Fortran 77 Standard requires each 366 named common block, but not blank common, to be the same 367 length in all modules of the program. 368 type: in each declaration of a given COMMON block, corresponding 369 memory locations (words or bytes) must agree in data type. If 370 used together with exact, this will require that corresponding 371 variables agree in data type. 372 volatile: Assume that COMMON blocks are volatile. 373 Many Fortran programmers assume that variables, whether local or 374 in COMMON, are static, i.e. that once assigned a value, they retain 375 that value permanently until assigned a different value by the pro- 376 gram. However, in fact the Fortran 77 Standard does not require this 377 to be the case. Local variables may become undefined between activa- 378 tions of a module in which they are declared. Similarly, COMMON 379 blocks may become undefined if no module in which they are declared 380 is active. (The technical term for entities with this behavior is 381 ''automatic'', but ftnchek uses the word ''volatile'' since it is 382 clearer to the nonspecialist.) Only COMMON blocks declared in a SAVE 383 statement, or declared in the main program or in a block data subpro- 384 gram remain defined as long as the program is running. Variables and 385 COMMON blocks that can become undefined at some point are called 386 volatile. 387 If the /common=volatile flag is turned on, ftnchek will warn you 388 if it finds a volatile COMMON block. If, at the same time, the /us- 389 age=com-block-volatile option is turned on (which is the default), 390 ftnchek will try to check whether such a block can lose its defined 391 status between activations of the modules where it is declared. ft- 392 nchek does not do a very good job of this: the rule used is to see 393 whether the block is declared in two separated subtrees of the call 394 tree. For instance, this would be the case if two modules, both 395 called from the main program, shared a volatile COMMON block. A 396 block can also become undefined between two successive calls of the 397 same subprogram, but ftnchek is not smart enough to tell whether a 398 subprogram can be called more than once, so this case is not checked 399 for. 400 The /common=volatile flag does not affect the way ftnchek checks 401 the usage of local variables. 402 For compatibility with previous versions of ftnchek, a numeric 403 form of this setting is also accepted: the list is replaced by a num- 404 ber from 0 to 3. A value of 0 turns all the warnings off, 1 or 405 greater turns on type, 2 or greater turns on length, and 3 turns on 406 dimensions and exact also. The numeric form cannot turn on the 407 volatile option. 408 See also: /library, /usage. 409 410 4113 /crossref=list 412 Prints cross-reference tables. Default = none. 413 The list consists of keywords separated by commas or colons. 414 The keywords with their meanings are as follows: 415 calls: table lists each subprogram followed by a list of routines 416 that call it. This listing omits library modules that are not 417 in the call tree of the main program. The list is alphabet- 418 ized. 419 common: table lists each COMMON block followed by a list of the 420 routines that access it. These listed routines are those in 421 which some variables in the COMMON block are accessed, not 422 simply those routines that declare the block. (To find out 423 what routines declare a COMMON block but do not use it, see 424 the /usage flag.) 425 labels: table lists each label followed by a list of all refer- 426 ences to it. A label reference is denoted by the line number 427 and statement type of the referring statement. The label 428 list is in sequential order. The references are listed in the 429 order they are encountered in the program. 430 See also: /calltree, /reference, /sort, /symtab, /vcg. 431 432 4333 /declare 434 If this flag is set, all identifiers whose datatype is not de- 435 clared in each module will be listed. This flag is useful for help- 436 ing to find misspelled variable names, etc. The same listing will be 437 given if the module contains an IMPLICIT NONE statement. Default = 438 no. 439 See also: /sixchar, /usage. 440 441 4423 /division 443 This switch is provided to help users spot potential division 444 by zero problems. If this switch is selected, every division except 445 by a constant will be flagged. (It is assumed that the user is in- 446 telligent enough not to divide by a constant which is equal to zero!) 447 Default = no. 448 See also: /portability, /truncation. 449 450 4513 /errors=num 452 Set the maximum number of error messages in a ''cascade''. 453 During checking of agreement of subprogram arguments, common block 454 declarations, and so forth, sometimes a single case will generate a 455 long string of warnings. Often this simply indicates some other 456 cause than a genuine item-by-item mismatch, such as for example a 457 varible missing from one list. So in such cases ftnchek stops print- 458 ing the warnings after the cascade limit is reached, and the trailer 459 ''etc...'' is printed to indicate that there were more errors not 460 printed. If you think that these warnings are likely to be genuine, 461 use this setting to see more of them. Turn-on = default = 3, max = 462 999. A value of 0 means no limit. 463 This setting does not set an overall limit on the number of er- 464 ror messages printed, only the number printed in any one cascade. 465 Most types of warnings and error messages are not subject to the cas- 466 cade effect and so are not affected by this setting. To turn off 467 warnings generally, use the individual warning control options or the 468 /nocheck option. 469 See also: /check. 470 471 4723 /extern 473 Causes ftnchek to report whether any subprograms invoked by the 474 program are never defined. Ordinarily, if ftnchek is being run on a 475 complete program, each subprogram other than the intrinsic functions 476 should be defined somewhere. Turn off this switch if you just want 477 to check a subset of files which form part of a larger complete pro- 478 gram. Subprogram arguments will still be checked for correctness. 479 Default = yes. 480 The /extern flag is now superseded by the /usage=ext-undefined 481 option. For the sake of convenience, the /extern flag is retained, 482 so that /noextern is equivalent to /usage=no-ext-undefined option. 483 The /extern switch may be retired eventually. 484 See also: /library. 485 486 4873 /f77=list 488 Use this setting to catch language extensions which violate the 489 Fortran 77 Standard. Such extensions may cause your program not to 490 be portable. Examples include the use of underscores in variable 491 names; variable names longer than six characters; statement lines 492 longer than 72 characters; and nonstandard statements such as the DO 493 ... ENDDO structure. ftnchek does not report on the use of lowercase 494 letters. By default, all warnings are turned off. 495 This setting provides detailed control over the warnings about 496 supported extensions to the Fortran 77 Standard. The list consists 497 of keywords separated by commas or colons. There are three special 498 keywords: all to turn on all the warnings about nonstandard exten- 499 sions, none to turn them all off, and help to print the list of all 500 the keywords with a brief explanation of each. If list is omitted, 501 /f77 is equivalent to /f77=all, and /nof77 is equivalent to 502 /f77=none. The warning keywords with their meanings are as follows: 503 accept-type: ACCEPT and TYPE I/O statements. 504 array-bounds: Expressions defining array bounds that contain array 505 elements or function references. 506 assignment-stmt: Assignment statements involving arrays. In For- 507 tran 90, an array can be assigned to another array of compati- 508 ble shape, or a scalar can be assigned to an array. Neither 509 of these assignments is permitted in Fortran 77. 510 511 A related warning occurs when an array is assigned to a scalar. 512 Since this is illegal also in Fortran 90, it is always warned about 513 regardless of the /f77 setting (unless all checking is turned off 514 with the /nocheck flag). 515 attribute-based-decl: Type declarations in the new Fortran 90 at- 516 tribute-based style. This style of declaration is distin- 517 guished by the use of a double colon (::) between the list of 518 attributes and the list of declared variables. This option 519 also controls warnings for use of Fortran 90 length or kind 520 specifiers in type declarations. (Although these specifiers 521 can be used in non-attribute-based declarations, they are con- 522 trolled by this option to avoid proliferation of /f77 op- 523 tions.) 524 automatic-array: Local (not dummy) arrays which have variable 525 size. These would correspond to arrays whose storage would 526 have to be dynamically allocated at run time. 527 backslash: Unix backslash escape in strings. This warning will be 528 given only if the /source=unix-backslash setting is specified 529 to cause the escape interpretation of backslash.. 530 byte: BYTE data type declaration. 531 case-construct: The SELECT CASE construct. 532 character: Extensions to the Fortran 77 standard regarding charac- 533 ter data. At present, this only controls warnings about char- 534 acter variables declared with zero or negative length. In 535 Fortran 77, all character variables must be of positive 536 length. In Fortran 90, they can be zero length, and declara- 537 tions that specify negative lengths are permitted, turning in- 538 to zero for the declared length. Note: because negative 539 length specifiers may indicate a programming error, the warn- 540 ing about them is given even if this option is turned off, and 541 is suppressed only by the /nocheck flag. 542 common-subprog-name: Common block and subprogram having the same 543 name. 544 construct-name: Use of a construct-name to label a control state- 545 ment. 546 continuation: More than 19 successive continuation lines. 547 cpp: Unix C preprocessor directives in the source code. 548 cray-pointer: ''Cray pointer'' syntax. 549 cycle-exit: The CYCLE and EXIT statements. 550 d-comment: Debugging comments starting with D in the source code. 551 dec-tab: DEC Fortran style tab-formatted source code. This warn- 552 ing will be given only if the /source=dec-tab setting is spec- 553 ified to cause interpretation of tabs in this style. 554 do-enddo: DO loop extensions: terminal statement label omitted, 555 END DO, and WHILE. 556 double-complex: Double precision complex datatype. 557 format-dollarsign: Dollar sign control code in FORMAT statements. 558 format-edit-descr: Nonstandard edit descriptors in FORMAT state- 559 ments. 560 function-noparen: Function definition without parentheses. 561 implicit-none: IMPLICIT NONE statement. 562 include: INCLUDE statement. 563 inline-comment: Inline comments starting with an exclamation 564 point. 565 internal-list-io: List-directed I/O to or from an internal file. 566 intrinsic: Nonstandard intrinsic functions. 567 io-keywords Nonstandard keywords used in I/O statements. These 568 fall into three groups. The first group includes keywords 569 that are accepted in Fortran 90: 570 ACTION PAD READWRITE 571 ADVANCE POSITION SIZE 572 DELIM READ WRITE 573 EOR 574 The second group comprises the following VMS Fortran keywords: 575 BLOCKSIZE EXTENDSIZE READONLY 576 BUFFERCOUNT INITIALSIZE RECORDSIZE 577 CARRIAGECONTROL MAXREC RECORDTYPE 578 DEFAULTFILE NAME (in OPEN) SHARED 579 DISP NOSPANBLOCK TYPE 580 DISPOSE ORGANIZATION 581 (The keyword NAME is standard only in the INQUIRE statement.) 582 The third group consists of the following IBM/MVS keyword: 583 NUM 584 This flag also controls a warning about use of ACCESS='AP- 585 PEND', which is accepted by some compilers. The value of 'AP- 586 PEND' is not valid for any I/O specifier in standard Fortran 587 77, and in Fortran 90 'APPEND' should be used as a value of 588 the POSITION specifier, not ACCESS. 589 long-line: Statements with meaningful code past 72 columns. This 590 warning is given only if the /columns setting has been used to 591 increase the statement field width. 592 long-name: Identifiers over 6 characters long. 593 mixed-common: Mixed character and noncharacter data in COMMON 594 block. 595 mixed-expr: Nonstandard type combinations in expressions, for ex- 596 ample DOUBLE PRECISION with COMPLEX, assigning hollerith to 597 integer, logical operations on integers. 598 name-dollarsign: Dollar sign used as a character in identifiers. 599 name-underscore: Underscore used as a character in identifiers. 600 namelist: NAMELIST statement. 601 param-implicit-type: Implicit typing of a parameter by the data 602 type of the value assigned. This warning can only occur if 603 implicit parameter typing has been turned on by the 604 /source=param-implicit-type option, or if the PARAMETER state- 605 ment is of the nonstandard form without parentheses. If this 606 option is turned on, then any instances where implicit parame- 607 ter typing occurs will be warned about. If you want to be 608 warned only in those instances where the implicit data type 609 differs from the default type, use /portability=param-implic- 610 it-type instead. According to the Fortran 77 standard, the 611 data type of a parameter is given by the same rules as for a 612 variable, and if necessary a type conversion is done when the 613 value is assigned. 614 param-intrinsic: Intrinsic function or exponentiation by a real 615 used to define the value of a PARAMETER definition. 616 param-noparen: PARAMETER statement without parentheses. The user 617 should be aware that the semantics of this form of the state- 618 ment differs from that of the standard form: in this form, the 619 parameter takes its data type from the value assigned, rather 620 than having its default data type based on the first letter of 621 the parameter name. (This form of the PARAMETER statement was 622 introduced by DEC before the Fortran 77 standard was defined, 623 and should be avoided.) 624 pointer: Fortran 90 standard pointer-related syntax, including 625 POINTER, TARGET and ALLOCATABLE type declarations, ALLOCATE, 626 DEALLOCATE, and NULLIFY statements, and pointer assignment us- 627 ing =>. 628 quad-constant: Quad precision real constants, e.g. of the form 629 1.23Q4. 630 quotemark: Strings delimited by quote marks rather than apostro- 631 phes. 632 relops: Relational (comparison) operators composed of punctuation, 633 namely: < <= == /= > >=. 634 semicolon: Semicolon used as statement separator. 635 statement-order: Statements out of the sequence mandated by the 636 Standard. The allowed sequence is illustrated in Table 1 in 637 the section on Interpreting the Output. 638 typeless-constant: Typeless constants, for example Z'19AF'. 639 type-size: Type declarations specifying a size, for example RE- 640 AL*8. 641 variable-format: Variable repeat specification or field size in 642 FORMAT. These are of the form < expr >. 643 vms-io: Obsolete. Now has the same meaning as the io-keywords 644 keyword. 645 See also: /f90, /f95, /portability, /pretty, /style, /wordsize. 646 647 6483 /f90=list 649 This setting provides detailed control over the warnings about 650 supported extensions to the Fortran 77 Standard that were not adopted 651 as part of the Fortran 90 Standard. Note that ftnchek does not sup- 652 port the full Fortran 90 language. However, it does support some 653 common extensions to Fortran 77 that were prevalent before Fortran 90 654 was defined. Some of these extensions became part of the Fortran 90 655 Standard, but others did not. The /f90 setting warns only about the 656 latter. That is, this flag covers things that are neither legal For- 657 tran 77 nor legal Fortran 90. Therefore, the warnings controlled by 658 this flag are basically a subset of the warnings controlled by /f77. 659 There are a few cases, described below, where the circumstances in 660 which the warning is given are slightly different for the two flags. 661 The list consists of keywords separated by commas or colons. 662 There are three special keywords: all to turn on all the warnings 663 about nonstandard extensions, none to turn them all off, and help to 664 print the list of all the keywords with a brief explanation of each. 665 If list is omitted, /f90 is equivalent to /f90=all, and /nof90 is 666 equivalent to /f90=none. 667 The following keywords have identical meanings for /f90 as for 668 /f77. The reader is referred to the explanations under /f77. 669 accept-type double-complex param-noparen 670 backslash format-dollarsign cray-pointer 671 byte format-edit-descr quad-constant 672 cpp function-noparen type-size 673 d-comment name-dollarsign variable-format 674 dec-tab param-implicit-type vms-io 675 The keywords which differ somewhat from the corresponding /f77 676 keywords are as follows. 677 continuation: The limit on the number of continuation lines for a 678 statement in fixed source form is the same, namely 19, in For- 679 tran 90 as in Fortran 77. For free source form the limit is 680 39 continuation lines, and a line containing a continuation 681 mark cannot be otherwise empty or contain only a comment. 682 intrinsic: This is the same as for /f77 except for the intrinsic 683 functions defined in MIL-STD 1753, which are all included in 684 Fortran 90, and so are not warned about. (See /intrinsic for 685 a list.) 686 io-keywords: This is the same as for /f77 except that no warnings 687 are given for the I/O keywords that are standard in Fortran 688 90. 689 long-line: Although the Fortran 90 Standard allows lines longer 690 than 72 characters in free source form, this restriction still 691 applies to fixed source form. In free source form the line 692 length limit is 132 characters, and unlike fixed form, ftnchek 693 does not allow this limit to be increased. 694 mixed-expr: This is the same as for /f77 except for expressions 695 mixing extended precision real with complex data types, which 696 are permitted in Fortran 90. 697 statement-order: This is similar to the corresponding /f77 warn- 698 ing, but applies the somewhat looser restrictions on statement 699 order of the Fortran 90 Standard. In particular, Fortran 90 700 allows DATA statements and statement-function definitions to 701 be intermixed with specification statements. 702 typeless-constant: In Fortran 90, binary, octal, and hexadecimal 703 constants of the form B'ddd', O'ddd', and Z'ddd', respective- 704 ly, are permitted. Here 'ddd' represents a string of digits. 705 ftnchek recognizes these forms, as well as a variant of the 706 form X'ddd' for a hexadecimal constant, and other variants in 707 which the base indicator B, O, Z, or X follows the digit 708 string. These variants were not adopted in Fortran 90, so on- 709 ly they are warned about when this flag is turned on. 710 See also: /f77, /f95, /portability, /pretty, /style, /wordsize. 711 712 7133 /f95=list 714 This setting provides detailed control over warnings about 715 standard Fortran 77 features that were deleted from the Fortran 95 716 Standard. Unlike the /f77 and /f90 settings, these warnings apply to 717 syntax which is legal Fortran 77. However, since these features have 718 been deleted from the Standard, it is possible that programs contain- 719 ing them will be unacceptable to some newer compilers. 720 The list consists of keywords separated by commas or colons. 721 There are three special keywords: all to turn on all the warnings 722 about nonstandard extensions, none to turn them all off, and help to 723 print the list of all the keywords with a brief explanation of each. 724 If list is omitted, /f95 is equivalent to /f95=all, and /nof95 is 725 equivalent to /f95=none. The warning keywords with their meanings 726 are as follows. 727 real-do: A DO variable of any real numeric type. 728 pause: The PAUSE statement. 729 assign: The ASSIGN statement, assigned GOTO, or assigned format. 730 h-edit: The H edit descriptor in a format. 731 There is one other Fortran 77 syntax feature that was deleted in 732 Fortran 95, namely branching to an ENDIF from outside the IF block. 733 However, ftnchek is unable to analyze program flow, and so it does 734 not provide a warning for this. 735 See also: /f77, /f90, /portability, /pretty, /style, /wordsize. 736 737 7383 /help 739 Prints a list of all the command-line options with a short de- 740 scription of each along with its default value. This command is 741 identical in function to the ''?'' argument, and is provided as a 742 convenience for those systems in which the question mark has special 743 meaning to the command interpreter. Default = no. 744 The help listing also prints the version number and patch level 745 of ftnchek and a copyright notice. 746 Note: the ''default'' values printed in square brackets in the 747 help listing are, strictly speaking, not the built-in defaults but 748 the current values after any environment options and any command-line 749 options preceding the /help option have been processed. 750 See also: /novice, /version, and help option of all settings 751 that take a list of keywords. 752 753 7543 /identifier-chars=list 755 Define non-alphanumeric characters that may be used in identi- 756 fiers. By default, ftnchek only accepts the dollar sign and under- 757 score as non-alphanumeric characters in identifier names. The char- 758 acters in the list replace whatever set of accepted non-alphanumeric 759 characters was previously in effect. Thus, if dollar sign or under- 760 score are not included in the list, they lose their status as accept- 761 able characters. 762 This option is provided to enable ftnchek to handle source files 763 containing non-standard identifer names that may be needed, for exam- 764 ple, to access certain operating system services. See the section on 765 Limitations and Extensions for the treatment of identifiers contain- 766 ing these characters in implicit typing. 767 Using /noidentifer-chars turns off acceptance of non-alphanumer- 768 ic characters entirely. 769 See also: /source. 770 771 7723 /include=path 773 Specifies a directory to be searched for files specified by IN- 774 CLUDE statements. Unlike other command-line options, this setting is 775 cumulative; that is, if it is given more than once on the command 776 line, all the directories so specified are placed on a list that will 777 be searched in the same order as they are given. The order in which 778 ftnchek searches for a file to be included is: the current directory; 779 the directory specified by environment variable FTNCHEK_INCLUDE if 780 any; the directories specified by any /include options; the directory 781 specified by environment variable INCLUDE; and finally in a standard 782 system-wide directory (/usr/include for UNIX, SYS$LIBRARY for VMS, 783 and \include for MSDOS). 784 See also: /f77, /source. 785 786 7873 /intrinsic=list 788 Controls whether ftnchek recognizes certain nonstandard intrin- 789 sic functions as intrinsic. The list consists of keywords separated 790 by commas or colons. Some of the keywords control whether to recog- 791 nize certain groups of functions, and other keywords control the ex- 792 pected syntax for invoking some nonstandard intrinsics. Include a 793 keyword to turn on recognition of the corresponding set of intrinsics 794 or to allow the corresponding syntax. Include a keyword prefixed by 795 no- to turn off that recognition. 796 There are three special keywords: all turns on recognition of 797 all the nonstandard intrinsics (listed below) and accepts either syn- 798 tax for those that have variations. Use none to turn off recognition 799 of all nonstandard intrinsics except those noted below. Use help to 800 print the list of all the keywords with a brief explanation of each. 801 If list is omitted, /intrinsic is equivalent to /intrinsic=all, and 802 /nointrinsic is equivalent to /intrinsic=none. 803 The nonstandard intrinsic functions needed to support the non- 804 standard extended precision data types (double complex and quad pre- 805 cision) are always recognized. The intrinsics for the double complex 806 data type are: 807 CDABS CDSQRT DREAL ZLOG 808 CDCOS DCMPLX IMAG ZSIN 809 CDEXP DCONJG ZABS ZSQRT 810 CDLOG DIMAG ZEXP ZCOS 811 CDSIN 812 813 The intrinsics for the quad precision and quad complex types are: 814 CQABS QARCOS QEXT QNINT 815 CQCOS QARSIN QEXTD QPROD 816 CQEXP QATAN QFLOAT QREAL 817 CQLOG QATAN2 QIMAG QSIGN 818 CQSIN QCMPLX QINT QSIN 819 CQSQRT QCONJG QLOG QSINH 820 DBLEQ QCOS QLOG10 QSQRT 821 IQINT QCOSH QMAX1 QTAN 822 IQNINT QDIM QMIN1 QTANH 823 QABS QEXP QMOD SNGLQ 824 825 The keywords controlling recognition of other nonstandard intrinsic 826 functions are as follows: 827 extra: recognize the following commonly available nonstandard in- 828 trinsics (all except EXIT and LOC are defined in MIL-STD 829 1753): 830 BTEST IBCLR IEOR ISHFTC 831 EXIT IBITS IOR LOC 832 IAND IBSET ISHFT NOT 833 834 unix: recognize these common Unix-specific intrinsic functions: 835 ABORT GMTIME LTIME SRAND 836 AND IARGC OR SYSTEM 837 GETARG IRAND RAND TIME 838 GETENV LSHIFT RSHIFT XOR 839 840 vms: recognize these common VMS-specific intrinsic functions: 841 DATE IDATE SECNDS TIME 842 ERRSNS RAN SIZEOF 843 844 iargc-no-argument: specify that IARGC may be invoked with no argu- 845 ments. 846 iargc-one-argument: specify that IARGC may be invoked with one ar- 847 gument. 848 rand-no-argument: specify that RAND and IRAND may be invoked with 849 no arguments. 850 rand-one-argument: specify that RAND and IRAND may be invoked with 851 one argument. 852 The no-argument and one-argument keywords work as follows: turn- 853 ing the option on causes ftnchek to accept the corresponding syntax 854 for invocation of the function, without excluding the possibility of 855 the alternative syntax. Turning the option off causes the corre- 856 sponding syntax not to be accepted. If both options are turned on at 857 once (the default), then either syntax is accepted. Turning both op- 858 tions off at once would not be meaningful. These options have no ef- 859 fect if recognition of Unix intrinsics has been turned off. 860 Note that this setting does not control whether non-standard 861 warnings are issued about these functions. It controls whether the 862 functions are assumed to be intrinsic or not, which determines how 863 their usage is checked. When functions in any of these sets are in- 864 cluded, their invocations will be checked according to the rules for 865 the intrinsic functions; otherwise they will be checked as normal 866 (user-written) external functions. The non-standard warnings are 867 controlled by the /f77=intrinsic option. 868 The default value of this setting is equivalent to 869 870 /intrinsic=all,no-unix. 871 Note: In versions of ftnchek prior to 2.10, the /intrinsic flag 872 took a numeric argument instead of a list of options. For the sake 873 of users who may have written scripts invoking ftnchek in this way, 874 the numeric form is still accepted. The numeric form of the setting 875 consists of three digits. The ones digit selects the set of intrin- 876 sic functions to be supported. The digit 0 selects only Fortran 77 877 standard intrinsics plus those needed to support the nonstandard ex- 878 tended precision data types. The digit 1 is equivalent to extra, 2 879 is equivalent to extra,unix, and 3 is equivalent to extra,vms. The 880 tens digit of this setting controls the syntax of the RAND intrinsic 881 function, and the hundreds digit controls the syntax of the IARGC 882 function. For these digits, specify 0 to require invocation with no 883 argument, 1 to require one argument, and 2 to allow either form. 884 See also: /f77. 885 886 8873 /library 888 This switch is used when a number of subprograms are contained 889 in a file, but not all of them are used by the application. Normal- 890 ly, ftnchek warns you if any subprograms are defined but never used. 891 This switch will suppress these warnings. Default = no. 892 This switch also controls which subprogram calls and COMMON 893 block declarations are checked. If a file is read with the /library 894 flag in effect, the subprogram calls and COMMON declarations con- 895 tained in a routine in that file will be checked only if that routine 896 is in the main program's call tree. On the other hand, if the /li- 897 brary switch is turned off, then ftnchek checks the calls of every 898 routine by every other routine, regardless of whether those routines 899 could ever actually be invoked at run time, and likewise all COMMON 900 block declarations are compared for agreement. 901 The difference between this switch and the /usage=no-ext-unused 902 option for subprograms is that the latter suppresses only the warning 903 about routines being declared but not used. The /library switch goes 904 further and excludes unused routines processed while it is in effect 905 from all cross-checking of arguments and COMMON block declarations as 906 well. 907 (If there is no main program anywhere in the set of files that 908 ftnchek has read, so that there is no call tree, then ftnchek will 909 look for any non-library routines that are not called by any other 910 routine, and use these as substitutes for the main program in con- 911 structing the call tree and deciding what to check. If no such top- 912 level non-library routines are found, then all inter-module calls and 913 all COMMON declarations will be checked.) 914 See also: /arguments, /calltree, /common, /extern, /usage. 915 916 9173 /list 918 Specifies that a listing of the Fortran program is to be print- 919 ed out with line numbers. If ftnchek detects an error, the error 920 message follows the program line with a caret ( ^ ) specifying the 921 location of the error. If no source listing was requested, ftnchek 922 will still print out any line containing an error, to aid the user in 923 determining where the error occurred. Default = no. 924 See also: /output, \fB-symtab, fB-quiet. 925 926 9273 /makedcls=list 928 Prepare a neatly-formatted file of declarations of variables, 929 common blocks, and namelist lists, for possible merging into the 930 source code. The declarations are stored in a file of the same name 931 as the source code, but with the extension changed to If no declara- 932 tions are written to the file, it is deleted to reduce clutter from 933 empty files. 934 If input comes from standard input, instead of a named file, 935 then declarations are written to standard output. 936 Variables are declared in alphabetical order within each decla- 937 ration class and type, with integer variables first, because of their 938 later possible use in array dimensions. 939 PARAMETER statements are an exception to the alphabetical order 940 rule, because the Fortran 77 Standard requires that the expressions 941 defining parameter values refer only to constants and already-defined 942 parameter names. This forces the original source file order of such 943 statements to be preserved in the declaration files. 944 Explicit declaration of variables is considered good modern pro- 945 gramming practice. By using compiler options to reject undeclared 946 variables, misspelled variable names (or names extending past column 947 72) can be caught at compile time. Explicit declarations also great- 948 ly facilitate changing floating-point precision with filters such as 949 and These programs are capable of changing types of explicit float- 950 ing-point type declarations, intrinsic functions, and constants, but 951 because they do not carry out rigorous lexical and grammatical analy- 952 sis of the Fortran source code, they cannot provide modified type 953 declarations for undeclared variables. Default setting = 0, turn-on 954 = 1. 955 Various options for the form of the declarations file are con- 956 trolled by the list, which consists of keywords separated by commas 957 or colons. There are three special keywords: all to turn on all the 958 options, none to turn them all off, and help to print the list of all 959 the keywords with a brief explanation of each. If list is omitted, 960 /makedcls is equivalent to /makedcls=declarations (i.e. produce the 961 declarations file using the default options), and /nomakedcls is 962 equivalent to /makedcls=none. 963 For compatibility with previous versions of ftnchek, a numeric 964 form of this setting is also accepted: the list is replaced by a 965 number which is the sum of the numbers in parentheses beside the key- 966 words in the following list. The warning keywords with their mean- 967 ings are as follows: 968 declarations (1): Write a declaration file. (This is implied by 969 any of the other options, and can be omitted if any other op- 970 tions are given.) 971 undeclared-only (2): By default, all variables are included in the 972 declaration file. With this option, include only variables. 973 This setting is useful if you want to check for undeclared 974 variables, since Fortran source files with all variables prop- 975 erly declared will not result in a file. With this option, 976 common blocks and namelist lists will not be included in the 977 declaration file, since by their nature they cannot be unde- 978 clared. 979 compact (4): The declarations are normally prettyprinted to line 980 up neatly in common columns, as in the declaration files out- 981 put by the Extended PFORT Verifier, This option value selects 982 instead compact output, without column alignment. 983 use-continuation-lines (8): Causes continuation lines to be used 984 where permissible. The default is to begin a new declaration 985 on each line. This option is appropriate to use together with 986 compact. 987 keywords-lowercase (16): Output Fortran keywords in lowercase, in- 988 stead of the default uppercase. 989 vars-and-consts-lowercase (32): Output variables and constants in 990 lowercase, instead of the default uppercase. Character 991 string constants are not affected by this option. 992 exclude-sftran3 (64): Omit declarations of internal integer vari- 993 ables produced by the SFTRAN3 preprocessor, as part of the 994 translation of structured Fortran statements to ordinary For- 995 tran. These variables have six-character names of the form 996 and where is a decimal digit. Because they are invisible in 997 the SFTRAN3 source code, and will change if the SFTRAN3 code 998 is modified, such variables should not be explicitly declared. 999 Instead, they should just assume the default Fortran INTEGER 1000 data type based on their initial letter, 1001 asterisk-comment (128): Use an asterisk as the comment character; 1002 the default is otherwise 'C'. 1003 comment-char-lowercase (256): Use 'c' instead of 'C' or '*' as the 1004 comment character. 1005 suppress-array-dimensions (512): Suppress dimensioning of arrays 1006 in the generated declarations. This option is for use with 1007 code lacking type declarations, to allow the declaration files 1008 to be inserted without change into the code. Since the code 1009 will have dimension statements already, dimensioning the array 1010 variables in the type statements of the declaration file is 1011 redundant. This option should be used only in conjunction 1012 with option 2 = undeclared-only because otherwise any arrays 1013 that were dimensioned in a type statement will lose their di- 1014 mensioning. 1015 free-form (1024): Produce declarations in free source form. This 1016 mode is automatically used if the input source is free form. 1017 Use this option to produce declarations in free form even if 1018 the input is in fixed form. Free form declarations are in- 1019 dented only 2 columns instead of 6, use the exclamation mark 1020 as the comment character, and indicate continuation lines by 1021 an ampersand at the end of the line to be continued. 1022 The declaration files contain distinctive comments that mark the 1023 start and end of declarations for each program unit, to facilitate 1024 using text editor macros for merging the declarations back into the 1025 source code. 1026 The ftnchek distribution includes a program, dcl2inc, which pro- 1027 cesses declaration files to produce files containing declarations of 1028 all COMMON blocks, in a form suitable for use as INCLUDE files. See 1029 the man page for the details of its use. 1030 See also: /mkhtml. 1031 1032 10333 /mkhtml=list 1034 Produce HTML documentation from source. Creates individual HTML 1035 files from ftnchek analysis and code comments. All comments immedi- 1036 ately preceding and following the function or subroutine definition 1037 are captured to the HTML file. No reformatting of source comments is 1038 performed other than stripping of FORTRAN comment characters. In ad- 1039 dition, the HTML file lists the local variables declared, common 1040 block variables used, functions and subroutines called, I/O unit us- 1041 age, and other information about each subprogram. Usually you will 1042 also want to specify /call=tree to create the root HTML file Call- 1043 Tree.html. (Perhaps this file should be named index.html.) 1044 Various options for the form of the HTML files are controlled by 1045 the list, which consists of keywords separated by commas or colons. 1046 There are three special keywords: all to turn on all the options, 1047 none to turn them all off, and help to print the list of all the key- 1048 words with a brief explanation of each. If list is omitted, /mkhtml 1049 is equivalent to /mkhtml=documents (i.e. produce the HTML document 1050 files using the default options), and /nomkhtmls is equivalent to 1051 /mkhtml=none. 1052 For the sake of simplicity, the options for /mkhtml are the same 1053 as those for /makedcls except for those that are inapplicable. Like- 1054 wise, a numeric form of this setting can be used, formed as the sum 1055 of the numbers in parentheses in the list below. The warning key- 1056 words with their meanings are as follows: 1057 documents (1): Create the HTML documents. (This is implied by any 1058 of the other options, and can be omitted if any other options 1059 are given.) 1060 compact (4): The declarations are normally prettyprinted to line 1061 up neatly in common columns. This option value selects in- 1062 stead compact output, without column alignment. 1063 use-continuation-lines (8): Causes continuation lines to be used 1064 instead of beginning a new declaration on each line. This op- 1065 tion is appropriate to use together with compact. 1066 keywords-lowercase (16): Output Fortran keywords in lowercase, in- 1067 stead of the default uppercase. 1068 vars-and-consts-lowercase (32): Output variables and constants in 1069 lowercase, instead of the default uppercase. Character 1070 string constants are not affected by this option. 1071 exclude-sftran3 (64): Omit declarations of internal integer vari- 1072 ables produced by the SFTRAN3 preprocessor, (See /makedcls for 1073 discussion.) 1074 suppress-array-dimensions (512): Suppress dimensioning of arrays 1075 in the generated declarations. This is normally undesirable, 1076 but is available if for some reason you do not want the array 1077 dimensions to appear in the HTML. 1078 free-form (1024): Produce variable declarations in free source 1079 form. This mode is automatically used if the input source is 1080 free form. This mainly affects the form of continuation lines 1081 if they are used. 1082 See also: /calltree, /makedcls. 1083 1084 10853 /novice 1086 This flag is intended to provide more helpful output for begin- 1087 ners. It has two effects: 1088 (a) provides an extra message to the effect that a function that 1089 is used but not defined anywhere might be an array which the 1090 user forgot to declare in a DIMENSION statement (since the 1091 syntax of an array reference is the same as that of a function 1092 reference). 1093 (b) modifies the form of the error messages and warnings. If the 1094 flag is turned off by /nonovice, these messages are printed in 1095 a style more resembling UNIX lint. 1096 Default = yes. 1097 1098 10993 /output=filename 1100 This setting is provided for convenience on systems which do 1101 not allow easy redirection of output from programs. When this set- 1102 ting is given, the output which normally appears on the screen will 1103 be sent instead to the named file. Note, however, that operational 1104 errors of ftnchek itself (e.g. out of space or cannot open file) will 1105 still be sent to the screen. The extension for the filename is op- 1106 tional, and if no extension is given, the extension .lis will be 1107 used. 1108 1109 11103 /pointersize=num 1111 Specifies the size of a ''Cray pointer'' variable to be num 1112 bytes. Default = turn-on = 4 bytes. 1113 The pointer size is used to inform precision mismatch warnings 1114 involving pointer variables, for example when a pointer is assigned a 1115 value from an allocation routine, or passed as a subprogram parame- 1116 ter. 1117 See also: /f77, /portability, /truncation, /wordsize. 1118 1119 11203 /portability=list 1121 ftnchek will give warnings for a variety of non-portable us- 1122 ages. Examples include the use of tabs except in comments or inside 1123 strings, the use of Hollerith constants, and the equivalencing of 1124 variables of different data types. This option does not produce 1125 warnings for supported extensions to the Fortran 77 Standard, which 1126 may also cause portability problems. To catch those, use the /f77 1127 setting. By default, all warnings are turned off. 1128 This setting provides detailed control over the warnings about 1129 possible portability problems. The list consists of keywords sepa- 1130 rated by commas or colons. There are three special keywords: all to 1131 turn on all the warnings about nonportable usages, none to turn them 1132 all off, and help to print the list of all the keywords with a brief 1133 explanation of each. If list is omitted, /portability is equivalent 1134 to /portability=all, and /noportability is equivalent to /portabili- 1135 ty=none. The warning keywords with their meanings are as follows: 1136 backslash: Backslash character in strings. Since some compilers 1137 treat the backslash as an escape character, its presence can 1138 cause problems even though it is used in a standard-conforming 1139 way. 1140 common-alignment: COMMON block variables not in descending order 1141 of storage size. Some compilers require this ordering because 1142 of storage alignment requirements. 1143 hollerith: Hollerith constants (other than within FORMAT specifi- 1144 cations). The Hollerith data type is a feature of Fortran IV 1145 that has been deleted in the Fortran 77 standard. It is su- 1146 perseded by the character data type. Storing Hollerith data 1147 in variables of a numeric or logical data type is nonportable 1148 due to differing word sizes. 1149 long-string: String constants, variables, or expressions over 255 1150 chars long. 1151 mixed-equivalence: Variables of different data types equivalenced. 1152 mixed-size: Variables declared with default precision used with 1153 variables given explicit precision, in expressions, assign- 1154 ments, or as arguments. For example, if a variable declared 1155 as REAL*8 is treated as equivalent to DOUBLE PRECISION. 1156 real-do: Non-integer DO loop index and bounds. These can cause a 1157 program's results to depend on the hardware characteristics of 1158 the particular computer used. 1159 param-implicit-type: Implicit typing of a parameter by the data 1160 type of the value assigned, if it differs from the default 1161 type. This warning can only occur if implicit parameter typ- 1162 ing has been turned on by the /source=param-implicit-type op- 1163 tion, or if the PARAMETER statement is of the nonstandard form 1164 without parentheses. If this option is turned on, then any 1165 instances where implicit parameter typing occurs and where the 1166 implicit type is different from the default type based on the 1167 first letter of the parameter name, will be warned about. Im- 1168 plicit parameter typing can change the semantics of statements 1169 where the parameter is used, causing portability problems. 1170 tab: Tabs in source code. Tabs are interpreted differently by 1171 different compilers. This warning will be given only once, at 1172 the end of the file. 1173 See also: /f77, /f90, /f95, /pretty, /style, /wordsize. 1174 1175 11763 /pretty=list 1177 Controls certain messages related to the appearance of the 1178 source code. These warn about things that might make a program less 1179 readable or be deceptive to the reader. By default, all warnings are 1180 turned on. 1181 This setting provides detailed control over the warnings about 1182 appearance. The list consists of keywords separated by commas or 1183 colons. Since all warnings are on by default, include a keyword pre- 1184 fixed by no- to turn off a particular warning. There are three spe- 1185 cial keywords: all to turn on all the warnings about misleading ap- 1186 pearances, none to turn them all off, and help to print the list of 1187 all the keywords with a brief explanation of each. If list is omit- 1188 ted, /pretty is equivalent to /pretty=all, and /nopretty is equiva- 1189 lent to /pretty=none. The warning keywords with their meanings are 1190 as follows: 1191 alternate-return: A RETURN statement has a constant specifying an 1192 alternate return point that is not between 0 and the number of 1193 dummy arguments that are labels. This is legal, and has the 1194 same effect as a RETURN with no alternate return expression, 1195 but suggests that the programmer intended to use an alternate 1196 return label that is not provided. 1197 embedded-space: Space embedded in variable names or in multi-char- 1198 acter operators such as **. 1199 continuation: Continuation mark following a comment line. 1200 long-line: Lines (except comments) over 72 columns in width (be- 1201 yond 72 is normally ignored by compiler). 1202 missing-space: Lack of space between variable and a preceding key- 1203 word. 1204 multiple-common: COMMON block declared in multiple statements. No 1205 warning is given if the statements are consecutive except for 1206 comment lines. 1207 multiple-namelist: NAMELIST declared in multiple statements. No 1208 warning is given if the statements are consecutive except for 1209 comment lines. 1210 parentheses: Parentheses around a variable by itself. As a sub- 1211 program argument, this makes the argument an expression, not 1212 modifiable by the subprogram. 1213 Note that in free source form, extra space and missing space are 1214 forbidden by the Fortran 90 Standard, and are not mere style viola- 1215 tions. In this case the warnings are replaced by syntax error mes- 1216 sages, and can be turned off only by using /nocheck. 1217 See also: /f77, /portability, /style. 1218 1219 12203 /project=list 1221 ftnchek will create a project file from each source file that 1222 is input while this option is turned on. The project file will be 1223 given the same name as the input file, but with the extension .f or 1224 .for replaced by .prj. (If input is from standard input, the project 1225 file is named Default = none. 1226 The list consists of keywords separated by commas or colons. 1227 There are three special keywords: all to turn on all the options, 1228 none to turn them all off, and help to print the list of all the key- 1229 words with a brief explanation of each. If list is omitted, /project 1230 is equivalent to /project=all, and /noproject is equivalent to 1231 /project=none. The keywords with their meanings are as follows: 1232 create: Produce a project file. The default is not to produce a 1233 project file. If this option is not turned on, the other op- 1234 tions have no effect. 1235 trim-calls: Trim the amount of information stored in the project 1236 file about subprogram declarations and calls. This is the de- 1237 fault. Turn this option off only in rare situations. (See 1238 discussion below.) The amount of trimming varies depending on 1239 the /library flag. More information is trimmed if that flag 1240 is turned on. 1241 trim-common: Trim the number of common block declarations stored 1242 in the project file. This is the default. Turn this option 1243 off only in rare situations. (See discussion below.) This 1244 option has no effect if the /library flag is turned off: when 1245 not in library mode, no trimming of common block declarations 1246 is done regardless of this option. 1247 A project file contains a summary of information from the source 1248 file, for use in checking agreement among FUNCTION, SUBROUTINE, and 1249 COMMON usages in other files. It allows incremental checking, which 1250 saves time whenever you have a large set of files containing shared 1251 subroutines, most of which seldom change. You can run ftnchek once 1252 on each file with the /project flag set, creating the project files. 1253 Usually you would also set the /library and /noextern flags at this 1254 time, to suppress messages relating to consistency with other files. 1255 Only error messages pertaining to each file by itself will be printed 1256 at this time. Thereafter, run ftnchek without these flags on all the 1257 project files together, to check consistency among the different 1258 files. All messages internal to the individual files will now be 1259 omitted. Only when a file is altered will a new project file need to 1260 be made for it. 1261 Naturally, when the /project option is turned on, ftnchek will 1262 not read project files as input. 1263 Ordinarily, the trim options should be left on when you intend 1264 to create project files for future input to ftnchek. Since trimming 1265 is on by default, this means that simply giving the command /project 1266 with no option list is the recommended mode. The trim options are 1267 provided only as a convenience for those who want to make use of 1268 project files for purposes other than checking the program with ft- 1269 nchek. To use project files for their intended purpose, the trim op- 1270 tions should not be turned off. 1271 Project files contain only information needed for checking 1272 agreement between files. This means that a project file is of no use 1273 if all modules of the complete program are contained in a single 1274 file. 1275 A more detailed discussion is given in the section on Using 1276 Project Files. 1277 1278 12793 /pure 1280 Assume functions are ''pure'', i.e., they will not have side 1281 effects by modifying their arguments or variables in a COMMON block. 1282 When this flag is in effect, ftnchek will base its determination of 1283 set and used status of the actual arguments on the assumption that 1284 arguments passed to a function are not altered. It will also issue a 1285 warning if a function is found to modify any of its arguments or any 1286 COMMON variables. Default = yes. 1287 When this flag is turned off, actual arguments passed to func- 1288 tions will be handled the same way as actual arguments passed to sub- 1289 routines. This means that ftnchek will assume that arguments may be 1290 modified by the functions. No warnings will be given if a function 1291 is found to have side effects. Because stricter checking is possible 1292 if functions are assumed to be pure, you should turn this flag off 1293 only if your program actually uses functions with side effects. 1294 1295 12963 /quiet 1297 This option reduces the amount of output relating to normal op- 1298 eration, so that error messages are more apparent. This option is 1299 provided for the convenience of users who are checking large suites 1300 of files. The eliminated output includes the names of project files, 1301 and the message reporting that no syntax errors were found. It also 1302 eliminates some blank lines that are ordinarily included for clarity. 1303 (Some of this output is turned back on by the /list and /symtab op- 1304 tions.) Default = no. 1305 Note: the way to remember the difference between the /quiet and 1306 /brief is that /quiet doesn't suppress any warning-related informa- 1307 tion, whereas /brief does. 1308 See also: /brief. 1309 1310 13113 /reference 1312 Specifies that a who-calls-who table be printed. This table 1313 lists each subprogram followed by a list of the routines it calls. 1314 This switch is equivalent to /calltree=reference. Default = no. 1315 The reference list omits routines called by unused library mod- 1316 ules. Thus it contains the same information as for the call-tree 1317 format, namely the hierarchy of subprogram calls, but printed in a 1318 different way. This prints out a breadth-first traversal of the call 1319 tree whereas /calltree=tree prints out a depth-first traversal. 1320 See also: /calltree, /crossref, /library, /sort, /symtab, /vcg. 1321 1322 13233 /resources 1324 Prints the amount of resources used by ftnchek in processing 1325 the program. This listing may be useful in analyzing the size and 1326 complexity of a program. It can also help in choosing larger sizes 1327 for ftnchek's internal tables if they are too small to analyze a par- 1328 ticular program. Default = no. 1329 In this listing, the term ''chunk size'' is the size of the 1330 blocks of memory allocated to store the item in question, in units of 1331 the size of one item, not necessarily in bytes. When the initially 1332 allocated space is filled up, more memory is allocated in chunks of 1333 this size. The following is an explanation of the items printed: 1334 Total number of lines of code, with separate totals for statement 1335 lines and comment lines. Comment lines include lines with 'C' 1336 or '*' in column 1 as well as blank lines and lines containing 1337 only an inline comment. Statement lines are all other lines, 1338 including lines that have an inline comment following some 1339 code. Continuation lines are counted as separate lines. 1340 Lines in include files are counted each time the file is in- 1341 cluded. 1342 Number of statements in the program, other than specification, da- 1343 ta, statement-function, FORMAT, ENTRY, and END statements. 1344 A module is any external subprogram, including the main program, 1345 subroutines, functions, and block data units. This count is 1346 of modules defined within the source, not modules referenced. 1347 Statement functions are not included. A subprogram with mul- 1348 tiple entry points is only counted once. 1349 Number of labels attached to statements (often called statement 1350 numbers). The total label count for the entire program is 1351 given, as well as the maximum number in any single subprogram. 1352 Number of characters used for storing identifier names. An iden- 1353 tifier is a variable, subprogram, or common block name. Local 1354 names are those of local variables in a subprogram, whereas 1355 global names refer to subprogram and common block names, as 1356 well as dummy argument names and common variable names. Actu- 1357 al argument text (up to 15 characters for each argument) is 1358 also included here. The space used for local names is not re- 1359 covered at the end of each module, so this number, like global 1360 space, grows until the whole program is analyzed. Unfortu- 1361 nately, this figure may include some text stored more than 1362 once, although a heuristic is used that will avoid duplicates 1363 in many cases. 1364 A token is the smallest syntactic unit of the FORTRAN language 1365 above the level of individual characters. For instance a token 1366 can be a variable name, a numerical constant, a quoted text 1367 string, or a punctuation character. Token text is stored 1368 while a module is being processed. For technical reasons, 1369 single-character tokens are not included in this total. Items 1370 that are not represented in the symbol table may be duplicat- 1371 ed. The space for token text is recovered at the end of each 1372 module, so this figure represents the maximum for any one mod- 1373 ule. 1374 This is the largest number of entries in the local symbol table 1375 for any module. Local symbol table entries include all vari- 1376 ables and parameters, common block names, statement functions, 1377 external subprograms and intrinsic functions referenced by the 1378 module. Literal constants are not stored in the local symbol 1379 table. 1380 This is the number of entries in the global symbol table at the 1381 end of processing. Global symbol table entries include exter- 1382 nal subprogram and common block names. Intrinsic functions 1383 and statement functions are not included. 1384 A token list is a sequence of tokens representing the actual or 1385 dummy argument list of a subprogram, or the list of variables 1386 in a common block or namelist. Therefore this number repre- 1387 sents the largest sum of COMMON, CALL, NAMELIST and ENTRY 1388 statements and function invocations for any one module. The 1389 space is recovered at the end of each module. 1390 This is the largest number of tokens in all the token lists and 1391 token trees of any one module. A token tree is formed when 1392 analyzing an expression: each operand is a leaf of the tree, 1393 and the operators are the nodes. Therefore this number is a 1394 measure of the maximum complexity of an individual module. 1395 For instance a module with many long arithmetic expressions 1396 will have a high number. Note that unlike token text de- 1397 scribed above, the number of tokens is independent of the 1398 length of the variable names or literal constants in the ex- 1399 pressions. 1400 This is the sum over all modules of the number of CALL statements 1401 and function invocations (except intrinsic functions and 1402 statement functions). 1403 This is the sum over all modules of the number of common block 1404 declarations. That is, each declaration of a block in a dif- 1405 ferent module is counted separately. (The standard allows 1406 multiple declarations of a block within the same module; these 1407 are counted as only one declaration since they are equivalent 1408 to a single long declaration.) 1409 This is the sum over all modules of the number of array dimension 1410 and parameter definition text strings saved for use by the 1411 /makedcls option. The length of the text strings is not 1412 counted. Each dimension of a multidimensional array is count- 1413 ed separately. 1414 These numbers are obviously not the same when project files are 1415 used in place of the original source code. Even the numbers for 1416 global entities may be different, since some redundant information is 1417 eliminated in project files. 1418 1419 14203 /sixchar 1421 One of the goals of the ftnchek program is to help users to 1422 write portable Fortran programs. One potential source of nonporta- 1423 bility is the use of variable names that are longer than six charac- 1424 ters. Some compilers just ignore the extra characters. This behav- 1425 ior could potentially lead to two different variables being consid- 1426 ered as the same. For instance, variables named AVERAGECOST and AV- 1427 ERAGEPRICE are the same in the first six characters. If you wish to 1428 catch such possible conflicts, use this flag. Default = no. 1429 Use the /f77=long-names if you want to list all variables longer 1430 than six characters, not just those pairs that are the same in the 1431 first six. 1432 See also: /f77, /portability. 1433 1434 14353 /sort 1436 Specifies that a sorted list of all modules used in the program 1437 be printed. This list is in ''prerequisite'' order, i.e. each module 1438 is printed only after all the modules from which it is called have 1439 been printed. This is also called a ''topological sort'' of the call 1440 tree. Each module is listed only once. Routines that are not in the 1441 call tree of the main program are omitted. If there are any cycles 1442 in the call graph (illegal in standard Fortran) they will be detected 1443 and diagnosed. Default = no. 1444 See also: /calltree, /crossref, /reference, /symtab, /vcg. 1445 1446 14473 /source=list 1448 This setting controls certain options about the form of the 1449 Fortran source code. The list consists of keywords separated by com- 1450 mas or colons. There are three special keywords: all to turn on all 1451 the options, none to turn them all off, and help to print the list of 1452 all the keywords with a brief explanation of each. If list is omit- 1453 ted, /source is equivalent to /source=all, and /nosource is equiva- 1454 lent to /source=none. 1455 For compatibility with previous versions of ftnchek, a numeric 1456 form of this setting is also accepted: the list is replaced by a 1457 number which is the sum of the numbers in parentheses beside the key- 1458 words in the following list. (The fixed and free options do not have 1459 numeric values.) The warning keywords with their meanings are as 1460 follows: 1461 fixed: Interpret the source as fixed form (with supported exten- 1462 sions such as exclamation mark for comments). Statements must 1463 be in columns 7 to 72 (unless the /cols setting has been used 1464 to change this), and blanks are not significant outside char- 1465 acter context (but warned about under the /pretty option). 1466 This is the default mode unless the source file extension is 1467 .f90 or .F90. this option cannot be given together with 1468 /source=free. 1469 free: Interpret the source as free form. Statements may be any- 1470 where in columns 1 to 132, comments can only begin with an ex- 1471 clamation mark, and blanks are required in some places such as 1472 between identifiers and keywords. This is the default mode if 1473 the source file extension is .f90 or .F90. This option cannot 1474 be given together with /source=fixed or /source=dec-tab 1475 dec-tab (1): Accept DEC-style tab-formatted source. A line begin- 1476 ning with an initial tab will be treated as a new statement 1477 line unless the character after the tab is a nonzero digit, in 1478 which case it is treated as a continuation line. The next 1479 column after the tab or continuation mark is taken as column 1480 7. A warning will be given in the case where the line is a 1481 continuation, if /f77=dec-tab is in effect. 1482 vms-include (2): Accept VMS-style INCLUDE statements. These fol- 1483 low the normal syntax, but with the following additional fea- 1484 tures: (1) the file extension, if not given, defaults to the 1485 same as a normal source file extension; and (2) the option 1486 /LIST or /NOLIST can be appended to the include-file name, to 1487 control listing of its contents. 1488 unix-backslash (4): Handle UNIX-style backslash escapes in charac- 1489 ter strings. The escape sequence following the backslash will 1490 be evaluated according to the ANSI standard for strings in C: 1491 up to three digits signify an octal value, an x signifies the 1492 start of a hexadecimal constant, any of the letters a b f n r 1493 t signify special control codes, and any other character (in- 1494 cluding newline) signifies the character itself. When this 1495 source code option is in effect, a warning will be given if 1496 the /f77=backslash setting is specified. 1497 1498 The default behavior is to treat the backslash like any other 1499 normal character, but a warning about portability will be generated 1500 if the /portability flag is set. Because of the fact that some com- 1501 pilers treat the backslash in a nonstandard way, it is possible for 1502 standard-conforming programs to be non-portable if they use the back- 1503 slash character in strings. 1504 1505 Since ftnchek does not do much with the interpreted string, it is 1506 seldom necessary to use this option. It is needed in order to avoid 1507 spurious warnings only if (a) the program being checked uses back- 1508 slash to embed an apostrophe or quote mark in a string instead of us- 1509 ing the standard mechanism of doubling the delimiter; (b) the back- 1510 slash is used to escape the end-of-line in order to continue a string 1511 across multiple source lines; or (c) a PARAMETER definition uses an 1512 intrinsic string function such as LEN with such a string as argument, 1513 and that value is later used to define array dimensions, etc. 1514 param-implicit-type (8): Implicit typing of a parameter by the da- 1515 ta type of the value assigned. Some non-standard compilers 1516 may allow the data type of the value to override the Fortran 1517 77 default type of a parameter that is based on the first let- 1518 ter of the parameter name. This option only applies to PARAM- 1519 ETER statements of the standard form which has parentheses. A 1520 parameter that has been explicitly declared in a type state- 1521 ment prior to the PARAMETER statement is not affected by this 1522 option. A warning will be given under the /f77=param-implic- 1523 it-type or /portability=param-implicit-type option. 1524 1525 Note that this implicit typing is treated as equivalent to an ex- 1526 plicit type declaration for the parameter. Therefore, if you use 1527 /makedcls=undeclared-only to generate declarations only of undeclared 1528 variables, these parameters will not be included. 1529 dec-param-standard-type (16): Follow the Fortran 77 rule for data 1530 typing of DEC Fortran style parameters. These are declared 1531 using a nonstandard form of the PARAMETER statement which 1532 lacks parentheses. According to DEC Fortran, parameters de- 1533 fined by this form of the statement have their data type given 1534 by the data type of the value assigned. Use this option to 1535 tell ftnchek not to follow this rule but instead to use the 1536 same rule as for standard PARAMETER statements. This option 1537 does not apply to PARAMETER statements of the standard form. 1538 By default, all these source code options are turned off, except 1539 for the vms-include option, which is on by default in the VMS ver- 1540 sion.. 1541 See also: /f77, /include, /portability. 1542 1543 15443 /style=list 1545 Provides extra-picky warnings about obsolescent or old-fash- 1546 ioned programming constructions. This option is helpful for efforts 1547 to follow a modern programming style. (Most of the things complained 1548 about under this option are forbidden in the F subset language.) By 1549 default, all warnings are turned off. 1550 The list consists of keywords separated by commas or colons. 1551 There are three special keywords: all to turn on all the options, 1552 none to turn them all off, and help to print the list of all the key- 1553 words with a brief explanation of each. If list is omitted, /style 1554 is equivalent to /style=all, and /nostyle is equivalent to 1555 /style=none. The warning keywords with their meanings are as fol- 1556 lows: 1557 block-if: Complain about arithmetic IF statement. Accept block IF 1558 or logical IF (which controls a single statement). 1559 construct-name: Complain about unnamed block constructs: IF, DO, 1560 and SELECT CASE. Note that if a construct name is present on 1561 the opening statement of a construct, then it is required to 1562 be present on all other component statements (ELSE, END IF, 1563 etc.) of the construct. In that case a missing construct name 1564 on those statements generates a syntax error regardless of 1565 this option. The purpose of this option is to warn if the 1566 construct completely lacks the optional name. 1567 distinct-do: Complain if two DO loops share a common terminator 1568 statement. 1569 do-construct: Complain if terminator of a DO loop is anything oth- 1570 er than an END DO or CONTINUE statement. This is the require- 1571 ment in order for the loop to meet the Fortran 90 definition 1572 of a do-construct. 1573 do-enddo: Complain if terminator of a DO loop is anything other 1574 than an END DO statement. (This option overrides the do-con- 1575 struct option, being even stricter.) 1576 end-name: Complain about the absence of the subprogram name on 1577 structured END statements. 1578 format-stmt: Complain about the presence of FORMAT statements. 1579 Only the FORMAT statements themselves are flagged, not the 1580 references to them in I/O lists. 1581 goto: Complain about the presence of unconditional, computed or 1582 assigned GOTO statements. Also complain about alternate re- 1583 turns (but not about labels as subprogram arguments). 1584 labeled-stmt: Complain about the presence of labels (numbers) on 1585 statements other than FORMAT statements. (Since FORMAT state- 1586 ments are arguably convenient and not readily abused, com- 1587 plaints about them are controlled by the separate format-stmt 1588 keyword.) 1589 program-stmt: Complain about the absence of a PROGRAM statement at 1590 the head of the main program. 1591 structured-end: Complain about the use of a plain END statement to 1592 end a subprogram, rather than a structured END statement (END 1593 PROGRAM, END SUBROUTINE, END FUNCTION, or END BLOCK DATA). 1594 See also: /f77, /f90, /f95, /pretty, /portability. 1595 1596 15973 /symtab 1598 A symbol table will be printed out for each module, listing all 1599 identifiers mentioned in the module. This table gives the name of 1600 each variable, its datatype, and the number of dimensions for arrays. 1601 An asterisk (*) indicates that the variable has been implicitly 1602 typed, rather than being named in an explicit type declaration state- 1603 ment. The table also lists all subprograms invoked by the module, 1604 all COMMON blocks declared, etc. Default = no. 1605 Also, for each module, a label table will be printed. The table 1606 lists each label defined in the module; the line on which said state- 1607 ment label is defined; and the statement type (executable, format, or 1608 specification). The labels are listed in sequential order. 1609 Also printed is a table describing the I/O units used by the 1610 module, together with information about how they are used: what oper- 1611 ations are performed, whether the access is sequential or direct, and 1612 whether the I/O is formatted or unformatted. 1613 See also: /calltree, /crossref, /list, /reference, /sort, /vcg. 1614 1615 16163 /truncation=list 1617 Warn about possible truncation (or roundoff) errors. Most of 1618 these are related to integer arithmetic. By default, all warnings 1619 are turned on. 1620 This setting provides detailed control over the warnings about 1621 possible truncation errors. The list consists of keywords separated 1622 by commas or colons. Since all warnings are on by default, include a 1623 keyword prefixed by no- to turn off a particular warning. There are 1624 three special keywords: all to turn on all the warnings about trunca- 1625 tion, none to turn them all off, and help to print the list of all 1626 the keywords with a brief explanation of each. If list is omitted, 1627 /truncation is equivalent to /truncation=all, and /notruncation is 1628 equivalent to /truncation=none. The warning keywords with their 1629 meanings are as follows: 1630 int-div-exponent: use of the result of integer division as an ex- 1631 ponent. This suggests that a real quotient is intended. An 1632 example would be writing X**(1/3) to evaluate the cube root of 1633 X. The correct expression is X**(1./3.). 1634 int-div-real: Conversion of an expression involving an integer di- 1635 vision to real. This suggests that a real quotient is intend- 1636 ed. 1637 int-div-zero: division in an integer constant expression that 1638 yields a result of zero. 1639 int-neg-power: exponentiation of an integer by a negative integer 1640 (which yields zero unless the base integer is 1 in magnitude). 1641 This suggests that a real base is intended. 1642 promotion: automatic conversion of a lower precision quantity to 1643 one of higher precision. The loss of accuracy for real vari- 1644 ables in this process is comparable to the corresponding demo- 1645 tion. No warning is given for promotion of integer quantities 1646 to real since this is ordinarily exact. 1647 real-do-index: use of a non-integer DO index in a loop with inte- 1648 ger bounds. An integer DO index with real bounds is always 1649 warned about regardless of this setting. 1650 real-subscript: use of a non-integer array subscript. 1651 significant-figures: overspecifying a single precision constant. 1652 This may indicate that a double precision constant was intend- 1653 ed. 1654 size-demotion: automatic conversion of a higher precision quantity 1655 to one of lower precision of the same type. This warning only 1656 occurs when an explicit size is used in declaring the type of 1657 one or both operands in an assignment. For example, a warning 1658 wil be issued where a REAL*8 variable is assigned to a REAL 1659 variable, if the default wordsize of 4 is in effect. A warn- 1660 ing is also issued if a long integer is assigned to a shorter 1661 one, for example, if an INTEGER expression is assigned to an 1662 INTEGER*2 variable. There is one exception to this last case, 1663 namely if the right hand side of the assignment is a small 1664 literal constant (less than 128). type-demotion: automatic 1665 conversion of a higher precision quantity to one of lower pre- 1666 cision of different type. This warning includes conversion of 1667 real quantities to integer, double precision to single preci- 1668 sion real, and assignment of a longer character string to a 1669 shorter one. 1670 The warnings about promotion and demotion also apply to complex 1671 constants, considering the precision to be that of the real or imagi- 1672 nary part. Warnings about promotions and demotions are given only 1673 when the conversion is done automatically, e.g. in expressions of 1674 mixed precision or in an assignment statement. If intrinsic func- 1675 tions such as INT are used to perform the conversion, no warning is 1676 given. 1677 See also: /portability, /wordsize. 1678 1679 16803 /usage=list 1681 Warn about unused or possible uninitialized variables, unused 1682 common blocks, undefined or unused statement labels, and unused or 1683 undefined subprograms. By default, all warnings are turned on. 1684 This setting provides detailed control over the warnings about 1685 possible usage errors. The list consists of keywords separated by 1686 commas or colons. Since all warnings are on by default, include a 1687 keyword prefixed by no- to turn off a particular warning. There are 1688 three special keywords: all to turn on all the warnings about usage, 1689 none to turn them all off, and help to print the list of all the key- 1690 words with a brief explanation of each. If list is omitted, /usage 1691 is equivalent to /usage=all, and /nousage is equivalent to /us- 1692 age=none. These warnings cover four main categories of objects: sub- 1693 program dummy arguments, common blocks and variables, subprograms and 1694 functions, and local variables. Warnings include undefined items, 1695 multiply defined items, unused items, etc. The warning keywords with 1696 their meanings are as follows: 1697 arg-alias: a scalar dummy argument is actually the same as another 1698 and is (or may be) modified. The Fortran 77 standard (section 1699 15.9.3.6) prohibits modifying an argument that is aliased to 1700 another. 1701 arg-array-alias: a dummy argument which is an array or array ele- 1702 ment is in the same array as another and is modified. This 1703 flag is similar to arg-alias but provides separate control 1704 over array arguments. It is harder to tell if aliasing is oc- 1705 curring in the case of arrays, so if ftnchek gives too many 1706 false warnings, this flag allows the array-related ones to be 1707 turned off without suppressing the warnings for scalars. 1708 arg-common-alias: a scalar dummy argument is the same as a common 1709 variable in the subprogram, and either is modified. This is 1710 also prohibited by the Fortran 77 standard. If common check- 1711 ing is not exact (see the /common setting), it is harder to 1712 tell if aliasing is occurring, so the warning is given if the 1713 variable is anywhere in a common block that is declared by the 1714 subprogram. 1715 arg-common-array-alias: a dummy argument which is an array or ar- 1716 ray element is in the same array as a common variable, and ei- 1717 ther is modified. If common checking is not exact, the vari- 1718 able can be anywhere in a common block that is declared by the 1719 subprogram. 1720 arg-const-modified: a subprogram modifies an argument which is a 1721 constant or an expression. Such an action could cause anoma- 1722 lous behavior of the program. 1723 arg-unused: a dummy argument is declared but never used. This is 1724 similar to the var-unused keyword described below, but applies 1725 only to arguments. 1726 com-block-unused: a common block is declared but none of the vari- 1727 ables in it are used by any subprogram. This warning is sup- 1728 pressed if the common strictness setting is 0. 1729 com-block-volatile: a common block may lose the definition of its 1730 contents if common blocks are volatile. This option only has 1731 an effect if the /common=volatile flag is in effect. See the 1732 discussion of the /common setting above. 1733 com-var-set-unused: a common variable is assigned a value, but its 1734 value is not used by any subprogram. This warning is sup- 1735 pressed if the common strictness setting is 0. 1736 com-var-uninitialized: a common variable's value is used in some 1737 subprogram, but is not set anywhere. Unfortunately, ftnchek 1738 does not do a thorough enough analysis of the calling sequence 1739 to know which routines are called before others. So warnings 1740 about this type of error will only be given for cases in which 1741 a variable is used in some routine but not set in any other 1742 routine. Checking of individual COMMON variables is done on- 1743 ly if the /common setting is 3 (variable by variable agree- 1744 ment). This warning is suppressed if the common strictness 1745 setting is 0. 1746 com-var-unused: a common variable is declared but not used by any 1747 subprogram. This warning is suppressed if the common strict- 1748 ness setting is 0. 1749 do-index-modified: a variable that is the index of a DO loop is 1750 modified by some statement within the range of the loop. The 1751 Standard permits an active DO variable to be modified only by 1752 the incrementation mechanism of the DO statement. 1753 ext-multiply-defined: an external (a subroutine or function) is 1754 defined more than once. Definition of an external means pro- 1755 viding the body of its source code. 1756 ext-declared-only: a name is declared in an EXTERNAL statement in 1757 some module, but is not defined or used anywhere. 1758 ext-undefined: an external is used (invoked) but not defined any- 1759 where. This option is equivalent to the /external flag. If 1760 the subprogram is invoked more than once, those invocations 1761 will still be checked for consistency. 1762 ext-unused: an external is defined (its subprogram body is 1763 present) but it is not used. A subprogram is considered un- 1764 used even if it is invoked by some other subprogram, if it 1765 cannot be called from any thread of execution starting with 1766 the main program. The agreement of the subprogram's arguments 1767 with its invocations is still checked even if this warning is 1768 turned off. If there is no main program, then this warning is 1769 issued only if the subprogram is not invoked anywhere. This 1770 warning is suppressed in library mode, but library mode has 1771 the additional effect of suppressing argument checking for un- 1772 used routines. 1773 label-undefined: a statement refers to a label that has not been 1774 defined. 1775 label-unused: a statement label is defined, but never referred to. 1776 var-set-unused: a local variable is assigned a value, but that 1777 value is not used. 1778 var-uninitialized: a local variable's value may be used before it 1779 is assigned. Sometimes ftnchek makes a mistake in the warn- 1780 ings about local variable usage. Usually it errs on the side 1781 of giving a warning where no problem exists, but in rare cases 1782 it may fail to warn where the problem does exist. See the 1783 section on Bugs for examples. If variables are equivalenced, 1784 the rule used by ftnchek is that a reference to any variable 1785 implies the same reference to all variables it is equivalenced 1786 to. For arrays, the rule is that a reference to any array el- 1787 ement is treated as a reference to all elements of the array. 1788 var-unused: a local variable is declared (for instance, in a type 1789 declaration) but is not used in the module. Does not apply to 1790 dummy arguments: warnings about them are controlled by the 1791 keyword arg-unused described above. 1792 Note: In versions of ftnchek prior to 2.10, the /usage flag took 1793 a numeric argument instead of a list of options. For the sake of 1794 users who may have written scripts invoking ftnchek in this way, the 1795 numeric form is still accepted. The numeric setting is composed of 1796 three digits. The first digit (hundreds place) controls warnings 1797 about subprograms (functions and subroutines), the second digit (tens 1798 place) warnings about common blocks and common variables,, and the 1799 third digit (ones place) warnings about local variables. Each digit 1800 controls warnings according to the convention that a 1 means warn 1801 about undefined items and variables that are used before set, a 2 1802 means warn about items that are unused, and a 3 means warn about both 1803 types. These numbers are now converted to the appropriate values for 1804 the above-listed keywords, except for com-block-volatile, which is 1805 not affected by the numeric argument. 1806 See also: /common, /declare, /extern, /library. 1807 1808 18093 /vcg 1810 Produce the call graph in the form of a VCG graph description. 1811 This description is written to a separate file, with the same stem as 1812 the file containing the main program, and suffix This file is able to 1813 be given directly to to visualize the call graph. (If input is from 1814 the standard input, then the graph description is sent to standard 1815 output.) This switch is equivalent to /calltree=vcg. Default = no. 1816 The VCG description as created is more complex than it need be. 1817 VCG allows graphs and nested subgraphs: each subroutine is created as 1818 a subgraph nested inside its calling routines. This allows you to 1819 interactively display subgraphs or summarise them. 1820 The option for was written by Dr. Philip Rubini of Cranfield 1821 University, UK. 1822 xvcg is a graph visualisation tool which runs under the X win- 1823 dows system. It is freely available from ftp.cs.uni-sb.de. It was 1824 written by G. Sander of the University of Saarland, Germany. 1825 See also: /calltree, /crossref, /reference, /sort. 1826 1827 18283 /version 1829 This option causes ftnchek to print a line giving the version 1830 number, release date, and patch level of the program. If no files 1831 are given, it then exits. If files are given, the effect of this op- 1832 tion is to include the patch level (normally omitted) in the version 1833 information printed at the start of processing. Default = no. 1834 See also: /help. 1835 1836 18373 /volatile 1838 Assume that COMMON blocks are volatile. Default = no. 1839 This flag is superseded by /common=volatile, and should no 1840 longer be used. It may be eliminated in a future release of ftnchek. 1841 See also: /common, /usage. 1842 1843 18443 /wordsize=num 1845 Specifies the default word size to be num bytes. This is the 1846 size of logical and single-precision numeric variables that are not 1847 given explicit precisions. (Explicit precisions for non-character 1848 variables are an extension to the Fortran 77 Standard, and are given 1849 by type declarations such as REAL*8 X.) Double-precision and complex 1850 variables will be twice this value, and double complex variables four 1851 times. Quad-precision constants and intrinsic function results will 1852 be four times this value. Note that variables declared as REAL*16 1853 will be regarded as quad precision only if the word size is 4 bytes. 1854 Default = turn-on = 4 bytes. 1855 The word size value does not matter for checking standard-con- 1856 forming programs that do not declare explicit precisions for non- 1857 character variables or store Hollerith data in variables. This set- 1858 ting also does not affect the default size of character variables, 1859 which is always 1 byte. Hollerith constants also are assumed to oc- 1860 cupy 1 byte per character. 1861 The word size is used to determine whether truncation occurs in 1862 assignment statements, and to catch precision mismatches in subpro- 1863 gram argument lists and common block lists. The exact warnings that 1864 are issued will depend on the status of other flags. Under both the 1865 /portability=mixed-size and the /nowordsize flag, any mixing of ex- 1866 plicit with default precision objects (character expressions not in- 1867 cluded) is warned about. This applies to arithmetic expressions con- 1868 taining both types of objects, and to subprogram arguments and COMMON 1869 variables. Under control of the /truncation=demotion and promotion 1870 options, a warning is given for assignment of an expression to a 1871 shorter variable of the same type, or for promotion of a lower preci- 1872 sion value to higher precision in an arithmetic expression or an as- 1873 signment statement. 1874 Giving a word size of 0, or equivalently, using /nowordsize 1875 means that no default value will be assumed. This is equivalent to 1876 specifying /portability=mixed-size. Use it to find cases of mixing 1877 default and explicit precision, for example to flag places where RE- 1878 AL*8 is treated as equivalent to DOUBLE PRECISION. 1879 See also: /pointersize, /portability, /truncation. 1880 1881 18823 /wrap=col 1883 Controls the wrapping of error messages. Long error messages 1884 that would run past the specified column will be broken up into sepa- 1885 rate lines between the words of the message for better readability. 1886 If turned off with /nowrap, each separate error message will be 1887 printed on one line, leaving it up to the display to wrap the message 1888 or truncate it. Default = turn-on = 79. 1889 1890 18912 Changing_the_defaults 1892 ftnchek includes two mechanisms for changing the default values 1893 of all options: by defining environment variables or by creating a 1894 preferences file. When ftnchek starts up, it looks in its environ- 1895 ment for any variables whose names are composed by prefixing the 1896 string FTNCHEK_ onto the uppercased version of the option name. If 1897 such a variable is found, its value is used to specify the default 1898 for the corresponding switch or setting. In the case of settings 1899 (for example, the /common strictness setting) the value of the envi- 1900 ronment variable is read as the default setting value. In the case 1901 of switches, the default switch will be taken as true or yes unless 1902 the environment variable has the value 0 or NO. 1903 Note that the environment variable name must be constructed with 1904 the full-length option name, which must be in uppercase. For exam- 1905 ple, to make ftnchek print a source listing by default, set the envi- 1906 ronment variable FTNCHEK_LIST to 1 or YES or anything other than 0 or 1907 NO. The names FTNCHEK_LIS (not the full option name) or ftnchek_list 1908 (lower case) would not be recognized. 1909 1910 The way to set the environment variables on the VMS system is by us- 1911 ing the DEFINE command. For example, to set the default /list switch 1912 to YES, give the command 1913 1914 $ DEFINE FTNCHEK_LIST 1 1915 After processing any environment variables, ftnchek looks for a 1916 preferences file containing options and settings. It will search in 1917 the following order, using only the first file found: (1) .ftnchekrc 1918 in the current directory, (2) ftnchek.ini in the current directory, 1919 (3) .ftnchekrc in the user's home directory, (4) ftnchek.ini in the 1920 home directory. If such a file is found, the options defined in it 1921 are used as defaults in place of the built-in defaults and overriding 1922 any defaults set in the environment.. 1923 Each option or setting in the preferences file must be on a sep- 1924 arate line. They are given in the same form as on the command line, 1925 except without the initial slash. The preferences file can contain 1926 blank lines and comments. Comments are introduced at any point in a 1927 line by a space character (blank or tab) or the '#' character, and 1928 are terminated by the end of the line. 1929 Command-line options override the defaults set in the environ- 1930 ment or in the preferences file, in the same way as they override 1931 the built-in defaults. 1932 1933 19342 Project_files 1935 This section contains detailed information on how to use 1936 project files most effectively, and how to avoid some pitfalls. 1937 One can divide the checks ftnchek does into two categories, lo- 1938 cal and global. Local checking is restricted to within a single rou- 1939 tine, and catches things like uninitialized variables, unintended 1940 loss of precision in arithmetic expressions, etc. This sort of 1941 checking can be done on each subprogram independently. Furthermore, 1942 local checking of a subprogram does not need to be repeated when some 1943 other subprogram is changed. Global checking catches things like 1944 calling a subroutine with the wrong argument types, or disagreeing in 1945 common block declarations. It requires looking at the whole set of 1946 subprograms interacting with each other. 1947 The purpose of project files is to allow the local checking and 1948 global checking steps to be separated. Assuming that each subprogram 1949 is in its own source file, you can run ftnchek once on each one to do 1950 local checking while suppressing global checking. Then ftnchek can 1951 be run once on all the project files together to do the global check- 1952 ing. The sample makefile below shows how to automate this task. The 1953 ''.f.prj'' target updates a project file for a particular file any 1954 time the source file changes. The information needed for global 1955 checking is saved in the project file. The ''check'' target does the 1956 combined global checking. Typically ''make check'' would repeat the 1957 ''ftnchek /project'' step only on changed source files, then do the 1958 global check. This is obviously a big advantage for large programs, 1959 when many subprograms seldom if ever change. 1960 It is best when using project files to place each subprogram in 1961 a separate source file. If each source file may contain more than 1962 one subprogram, it complicates the definition of ''local'' and 1963 ''global'' checking because there is some inter-module checking that 1964 is contained within a file. ftnchek tries to do the right thing in 1965 this case, but there are some complications (described below) due to 1966 the trade-off between avoiding re-doing cross-checks and preserving 1967 information about the program's structure. 1968 Ordinarily, to do the least amount of re-checking, project files 1969 should be created with the /library flag in effect and trimming 1970 turned on. In this mode, the information saved in the project file 1971 consists of all subprogram declarations, all subprogram invocations 1972 not resolved by declarations in the same file, and one instance of 1973 each COMMON block declaration. This is the minimum amount of infor- 1974 mation needed to check agreement between files. 1975 If the source file contains more than one routine, there are 1976 some possible problems that can arise from creating the project file 1977 in library mode, because the calling hierarchy among routines defined 1978 within the file is lost. Also, if the routines in the file make use 1979 of COMMON blocks that are shared with routines in other files, there 1980 will not be enough information saved for the correct checking of set 1981 and used status of COMMON blocks and COMMON variables according to 1982 the /usage setting. Therefore if you plan to use project files when 1983 /usage checking is turned on (which is the default situation), and if 1984 multiple routines in one project file share COMMON blocks with rou- 1985 tines in other files, the project files should be created with the 1986 /library flag turned off. In this mode, ftnchek saves, besides the 1987 information listed above, one invocation of each subprogram by any 1988 other subprogram in the same file, and all COMMON block declarations. 1989 This means that the project file will be larger than necessary, and 1990 that when it is read in, ftnchek may repeat some inter-module checks 1991 that it already did when the project file was created. If each 1992 project file contains only one module, there is no loss of informa- 1993 tion in creating the project files in library mode. 1994 Because of the possible loss of information entailed by creating 1995 a project file with the /library flag in effect, whenever that 1996 project file is read in later, it will be treated as a library file 1997 regardless of the current setting of the /library flag. On the other 1998 hand, a project file created with library mode turned off can be read 1999 in later in either mode. 2000 The foregoing discussion assumes that the trimming options of 2001 the /project setting are turned on when the project file is created. 2002 This is the normal situation. The no-trim options of the /project 2003 setting are provided in case one wants to use the project files for 2004 purposes other than checking the program with ftnchek. For instance, 2005 one could write a Perl script to analyze the project files for infor- 2006 mation about how the different subprograms are called. You should 2007 not use the no-trim options to deal with the issues of information 2008 loss discussed above, since they cause more information than neces- 2009 sary to be stored. This makes the project files bigger and causes 2010 ftnchek to do more work later when it reads them to check your com- 2011 plete program. Ordinarily, you should use the /library option to 2012 control how much information to store for later use by ftnchek in 2013 checking your program. 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047