1FTNCHEK 3.3(1L) FTNCHEK 3.3(1L) 2 3 4 5NAME 6 ftnchek - Fortran 77 program checker 7 8 9SYNOPSIS 10 ftnchek [ -arguments[=list] ] [ -array[=list] ] 11 [ -[no]brief ] [ -calltree[=list] ] [ -[no]check ] 12 [ -columns[=num] ] [ -common[=list] ] 13 [ -[no]crossref[=list] ] [ -[no]declare ] 14 [ -[no]division ] [ -errors[=num] ] [ -[no]extern ] 15 [ -[no]f77[=list] ] [ -[no]f90[=list] ] 16 [ -[no]f95[=list] ] [ -[no]help ] 17 [ -[no]identifier-chars[=list] ] [ -include=str ] 18 [ -intrinsic[=list] ] [ -[no]library ] [ -[no]list ] 19 [ -makedcls[=list] ] [ -mkhtml[=list] ] 20 [ -[no]novice ] [ -output=str ] 21 [ -pointersize[=num] ] [ -[no]portability[=list] ] 22 [ -[no]pretty[=list] ] [ -project[=list] ] 23 [ -[no]pure ] [ -[no]quiet ] [ -[no]reference ] 24 [ -[no]resources ] [ -[no]sixchar ] [ -[no]sort ] 25 [ -source[=list] ] [ -style[=list] ] [ -[no]symtab ] 26 [ -[no]truncation[=list] ] [ -usage[=list] ] 27 [ -[no]vcg ] [ -[no]version ] [ -[no]volatile ] 28 [ -wordsize[=num] ] [ -wrap[=num] ] [ files ... ] 29 30 31DESCRIPTION 32 33 34 ftnchek (short for Fortran checker) is designed to detect certain 35 errors in a Fortran program that a compiler usually does not. ftnchek 36 is not primarily intended to detect syntax errors. Its purpose is to 37 assist the user in finding semantic errors. Semantic errors are legal 38 in the Fortran language but are wasteful or may cause incorrect opera- 39 tion. For example, variables which are never used may indicate some 40 omission in the program; uninitialized variables contain garbage which 41 may cause incorrect results to be calculated; and variables which are 42 not declared may not have the intended type. ftnchek is intended to 43 assist users in the debugging of their Fortran program. It is not 44 intended to catch all syntax errors. This is the function of the com- 45 piler. Prior to using ftnchek, the user should verify that the program 46 compiles correctly. 47 48 49 50 This document first summarizes how to invoke ftnchek. That section 51 should be read before beginning to use ftnchek. Later sections 52 describe ftnchek's options in more detail, give an example of its use, 53 and explain how to interpret the output. The final sections mention 54 the limitations and known bugs in ftnchek. 55 56INVOKING FTNCHEK 57 ftnchek is invoked through a command of the form: 58 59 $ ftnchek [-option -option ...] filename [filename ...] 60 61 The brackets indicate something which is optional. The brackets them- 62 selves are not actually typed. Here options are command-line switches 63 or settings, which control the operation of the program and the amount 64 of information that will be printed out. If no option is specified, 65 the default action is to print error messages, warnings, and informa- 66 tional messages, but not the program listing or symbol tables. 67 68 69 Each option begins with the '-' character. (On VAX/VMS or MS-DOS sys- 70 tems you may use either '/' or '-'.) For the sake of conformity with 71 an increasingly common convention, options can also begin with '--'. 72 The options are described at greater length in the next section. 73 74 ftnchek options fall into two categories: switches, which are either 75 true or false, and settings, which have a numeric or string value. The 76 name of a switch is prefixed by 'no' or 'no-' to turn it off: e.g. 77 -nopure would turn off the warnings about impure functions. The 'no' 78 prefix can also be used with numeric settings, having the effect of 79 turning off the corresponding warnings. Settings that control lists of 80 warnings have a special syntax discussed below. Only the first 3 char- 81 acters of an option name (not counting the '-') need be provided. A 82 colon may be used in place of an equals sign for numeric or string set- 83 ting assignments; however, we show only the equals sign form below. 84 85 86 The switches and settings which ftnchek currently recognizes are listed 87 below. For each option, the default is the value used if the option is 88 not explicitly specified, while the turn-on is the value used if the 89 option is given without assigning it a value. 90 91 -arguments=list 92 Control warnings about subprogram type and argument mismatches. 93 Default = turn-on = all. 94 95 -array=list 96 Control warnings in checking array arguments of subprograms. 97 Default = turn-on = all. 98 99 -brief Use shorter format for some error messages. Default = no. 100 101 -calltree=list 102 Produce subprogram call hierarchy in one of 3 formats: text 103 call-tree, who-calls-who and VCG. Default = none, turn-on = 104 tree,prune,sort. 105 106 If the -mkhtml option is invoked and tree is the applied call- 107 tree option, a file named CallTree.html, will be produced 108 depicting the tree in HTML format. 109 110 -check Perform checking. Default = yes. 111 112 -columns=num 113 Set maximum line length to num columns. (Beyond this is 114 ignored.) Turn-on = max = 132. Default = 72. 115 116 -common=list 117 Set degree of strictness in checking COMMON blocks. Default = 118 turn-on = all. 119 120 -crossref=list 121 Print cross-reference list of subprogram calls, label usage, 122 and/or COMMON block use. Default = none. 123 124 -declare 125 Print a list of all identifiers whose datatype is not explicitly 126 declared. Default = no. 127 128 -division 129 Warn wherever division is done (except division by a constant). 130 Default = no. 131 132 -errors=num 133 Set the maximum number of error messages per cascade. Default = 134 turn-on = 3. 135 136 -extern 137 Warn if external subprograms which are invoked are never 138 defined. Default = yes. 139 140 -f77=list 141 Control specific warnings about supported extensions to the For- 142 tran 77 Standard. Default = none, turn-on = all. 143 144 -f90=list 145 Control specific warnings about supported extensions to the For- 146 tran 77 Standard that were not adopted as part of the Fortran 90 147 Standard. Default = none, turn-on = all. 148 149 -f95=list 150 Control specific warnings about standard Fortran 77 features 151 that were deleted from the Fortran 95 Standard. Default = 152 none, turn-on = all. 153 154 -help Print command summary. Default = no. 155 156 -identifier-chars=list 157 Define non-alphanumeric characters that may be used in identi- 158 fiers. Default = turn-on = dollar sign and underscore. 159 160 -include=path 161 Define a directory to search for INCLUDE files before searching 162 in the system-wide directory. Cumulative. Default = turn-on = 163 none. 164 165 -intrinsic=list 166 Control treatment of nonstandard intrinsic functions. Default = 167 all except vms for Unix version, all except unix for VMS ver- 168 sion, all except unix and vms for other versions. Turn-on = 169 all. 170 171 -library 172 Begin library mode: do not warn about subprograms in file that 173 are defined but never used. Default = no. 174 175 -list Print source listing of program. Default = no. 176 177 -makedcls=list 178 Prepare a file of declarations. The list specifies options for 179 the format of this file. Default = none, turn-on = declara- 180 tions. 181 182 -mkhtml=list 183 Create individual HTML document files from ftnchek analysis and 184 code comments. Usually you will also want to specify -call=tree 185 to create the root HTML file CallTree.html. Default = none, 186 turn-on = documents. 187 188 -novice 189 Give output suitable for novice users. Default = yes. 190 191 -output=filename 192 Send output to the given file. Default and turn-on sends output 193 to the screen. (Default filename extension is .lis). 194 195 -pointersize=num 196 Set the size of ''Cray pointer'' variables to num bytes. Min = 197 1, max = 16. Default = turn-on = 4 198 199 -portability=list 200 Warn about non-portable usages. Default = none, turn-on = all. 201 202 -pretty=list 203 Give warnings for possibly misleading appearance of source code. 204 Default = turn-on = all. 205 206 -project=list 207 Create project file (see explanation below). Default = no. 208 209 -pure Assume functions are pure, i.e. have no side effects. Default = 210 yes. 211 212 -quiet Produce less verbose output. Default = no. 213 214 -reference 215 Print table of subprograms referenced by each subprogram. 216 Default = no. 217 218 -resources 219 Print amount of resources used in analyzing the program. 220 Default = no. 221 222 -sixchar 223 List any variable names which clash at 6 characters length. 224 Default = no. 225 226 -sort Print list of subprograms sorted in prerequisite order. Default 227 = no. 228 229 -source=list 230 Select source formatting options: fixed or free form, DEC For- 231 tran tab-formatted lines, VMS-style INCLUDE statement, UNIX- 232 style backslash escape sequences, and implicit typing of parame- 233 ters. Default = none, turn-on = all. 234 235 -style=list 236 Produce extra-picky warnings about obsolescent or old-fashioned 237 programming constructions. Default = none, turn-on = all. 238 239 -symtab 240 Print symbol table and label table for each subprogram. Default 241 = no. 242 243 -truncation=list 244 Check for possible loss of accuracy by truncation. Default = 245 turn-on = all. 246 247 -usage=list 248 Control warnings about unused or uninitialized variables, common 249 blocks, etc. Default = turn-on = all. 250 251 -vcg Produce VCG format of call graph. 252 253 -version 254 Print version number. Default = no. 255 256 -volatile 257 Assume COMMON blocks lose definition between activations. 258 Default = no. (Obsolete. Use -common=volatile instead.) 259 260 -wordsize=num 261 Set the default word size for numeric quantities to num bytes. 262 Default = turn-on = 4 bytes. 263 264 -wrap=num 265 Set output column at which to wrap long error messages and warn- 266 ings to the next line. If set to 0, turn off wrapping. Default 267 = turn-on = 79. 268 269 270 When more than one option is used, they should be separated by a blank 271 space, except on systems such as VMS where options begin with slash ( / 272 ). No blank spaces may be placed around the equals sign ( = ) in a 273 setting. ftnchek "?" will produce a command summary listing all 274 options and settings. 275 276 For settings that take a list of keywords, namely -arguments, -array, 277 -calltree, -common, -crossref, -f77, -f90, -f95, -intrinsic, -makedcls, 278 -mkhtml, -portability, -pretty, -project, -source, -style, -truncation, 279 and -usage, the list consists of keywords separated by commas or 280 colons. If the list of keywords is omitted, the effect is to set the 281 option to its turn-on value (same as ''all'' in most cases). Also, if 282 the list is omitted, the setting name can be prefixed with no or no- to 283 turn off all the options it controls. For example, -f77 turns on all 284 warnings about nonstandard constructions, while -nof77 turns them all 285 off. Three special keywords are: 286 287 help Print out all the option keywords controlled by the setting, 288 with a brief explanation of their meanings. This keyword cannot 289 be given in a list with other keywords. 290 291 all Set all options. This turns on all options controlled by the 292 setting. 293 294 none Clear all options. This turns off all options controlled by the 295 setting. 296 297 These three special keywords must be given in full. For all other key- 298 words, only as many letters of the keyword as are necessary to identify 299 it unambiguously need be given, or a wildcard pattern may be used. 300 Including a keyword in the list turns the corresponding option on. For 301 example, -f77=intrinsic would turn on only the warnings about use of 302 nonstandard intrinsic functions. Prefixing a keyword by no- turns its 303 option off. For example, -pretty=no-long-line turns off warnings about 304 lines exceeding 72 columns in length while leaving all other warnings 305 about misleading appearance in effect. If a setting has default none, 306 you can turn on all options except one or two by using all first. For 307 example, -f77=all,no-include enables warnings about all nonstandard 308 extensions except INCLUDE statements. If a setting has default all, 309 you can turn off all warnings except one or two by using none first. 310 For example, -truncation=none,demotion would turn off all precision 311 related warnings except about demotions. Wildcard patterns contain an 312 asterisk to stand for any string of characters. If a wildcard pattern 313 is used, all the warnings that match it are affected. If no- is pre- 314 fixed to the pattern, all the matching warnings are turned off, other- 315 wise they are all turned on. The minimum unambiguous length rule does 316 not apply to wildcard matching. For example, use -usage=no-*var* to 317 turn off all warnings relating to variable usage (both local and com- 318 mon). (Unix users may need to quote any options containing wildcards 319 in order to prevent the shell from attempting to expand them.) Wild- 320 cards are recognized only in lists of warning keywords, not in the top- 321 level options themselves. 322 323 When ftnchek starts up, it looks for environment variables and also for 324 a preferences file. Any options defined in the environment or in the 325 preferences file are used as defaults in place of the built-in 326 defaults. They are over-ridden by any command line options. See the 327 section on changing the defaults for details about the environment 328 options and the preferences file. 329 330 331 When giving a name of an input file, the extension is optional. If no 332 extension is given, ftnchek will first look for a project file with 333 extension .prj, and will use that if it exists. If not, then ftnchek 334 will look for a Fortran source file with the extension .for for VMS 335 systems, .f for UNIX systems. More than one file name can be given to 336 ftnchek, and it will process the modules in all files as if they were 337 in a single file. 338 339 340 Wildcards are allowed in the specification of filenames on the command 341 line for the VMS and MS-DOS versions, as also of course under UNIX and 342 any other system that performs wildcard expansion in the command pro- 343 cessor. 344 345 If no filename is given, ftnchek will read input from the standard 346 input. 347 348 349 350OPTIONS 351 This section provides a more detailed discussion of ftnchek command- 352 line options. Options and filenames may be interspersed on a command 353 line. Most options are positional: each option remains in effect from 354 the point it is encountered until it is overridden by a later change. 355 Thus for example, the listing may be suppressed for some files and not 356 for others. Exceptions are: the -intrinsic, -pointersize, and -word- 357 size settings, which cannot be changed once processing of input files 358 has started; the -arguments, -array, -calltree, -common, -crossref, 359 -extern, -reference, -resources, -sort, -vcg, and -volatile options, 360 where the action depends only on the value of the option after the pro- 361 cessing of input files is finished; and the -include setting, which is 362 cumulative. 363 364 The option names in the following list are in alphabetical order. 365 366 367 368 -arguments=list 369 Controls warnings about mismatches between actual and dummy 370 subprogram arguments, and also about mismatches between expected 371 and actual subprogram type. (An actual argument is an argument 372 passed to the subprogram by the caller; a dummy argument is an 373 argument received by the subprogram.) By default, all warnings 374 are turned on. 375 376 The list consists of keywords separated by commas or colons. 377 Since all these warnings are on by default, include a keyword 378 prefixed by no- to turn off a particular warning. There are 379 three special keywords: all to turn on all the warnings about 380 arguments, none to turn them all off, and help to print the list 381 of all the keywords with a brief explanation of each. If list 382 is omitted, -arguments is equivalent to -arguments=all, and 383 -noarguments is equivalent to -arguments=none. The warning key- 384 words with their meanings are as follows: 385 386 arrayness: 387 warn about inconsistent use of arguments that are arrays. 388 These warnings can be further controlled by the -array 389 option. 390 391 type: 392 warn about dummy arguments of a different data type from the 393 actual arguments. 394 395 function-type: 396 warn if the invocation assumes the function's return value 397 is a different type than it actually is. Also warns if a 398 function is called as a subroutine, or vice-versa. 399 400 number: 401 warn about invoking a subprogram with a different number of 402 arguments than the subprogram expects. 403 404 For compatibility with previous versions of ftnchek, a numeric 405 form of this setting is also accepted: the list is replaced by a 406 number from 0 to 3. A value of 0 turns all the warnings off, 1 407 turns on only number, 2 turns on all except number, and 3 turns 408 all the warnings on. 409 410 This setting does not apply to checking invocations of intrinsic 411 functions or statement functions, which can only be turned off 412 by the -nocheck option. 413 414 See also: -array, -library, -usage. 415 416 417 418 -array=list 419 Controls the degree of strictness in checking agreement between 420 actual and dummy subprogram arguments that are arrays. The 421 warnings controlled by this setting are for constructions that 422 might legitimately be used by a knowledgeable programmer, but 423 that often indicate programming errors. By default, all warn- 424 ings are turned on. 425 426 The list consists of keywords separated by commas or colons. 427 Since all these warnings are on by default, include a keyword 428 prefixed by no- to turn off a particular warning. There are 429 three special keywords: all to turn on all the warnings about 430 array arguments, none to turn them all off, and help to print 431 the list of all the keywords with a brief explanation of each. 432 If list is omitted, -array is equivalent to -array=all, and 433 -noarray is equivalent to -array=none. The warning keywords 434 with their meanings are as follows: 435 436 dimensions: 437 warn if the arguments differ in their number of dimensions, 438 or if the actual argument is an array element while the 439 dummy argument is a whole array. 440 441 size: 442 warn if both arguments are arrays, but they differ in number 443 of elements. 444 445 For compatibility with previous versions of ftnchek, a numeric 446 form of this setting is also accepted: the list is replaced by a 447 number from 0 to 3. A value of 0 turns all the warnings off, 1 448 turns on only dimensions, 2 turns on only size, and 3 turns all 449 the warnings on. 450 451 Note: A warning is always given regardless of this setting if 452 the actual argument is an array while the dummy argument is a 453 scalar variable, or if the actual argument is a scalar variable 454 or expression while the dummy argument is an array. These cases 455 are seldom intentional. (To turn off even these warnings, use 456 -arguments=no-arrayness.) No warning is ever given if the 457 actual argument is an array element while the dummy argument is 458 a scalar variable. Variable-dimensioned arrays and arrays 459 dimensioned with 1 or asterisk match any number of array ele- 460 ments. There is no check of whether multi-dimensional arrays 461 agree in the size of each dimension separately. 462 463 See also: -arguments, -library, -usage. 464 465 466 467 -brief 468 Selects a shorter format for some warning messages. At 469 present, the only warnings controlled by this flag are those 470 that are printed at the end of processing each subprogram. 471 These include warnings about variables that are set but not used 472 or used before set, variable names that do not conform to the 473 Fortran 77 standard, etc. (These warnings may be suppressed 474 entirely depending on other flags, such as the -usage or -f77 475 flags.) In the default format each variable is listed on a sep- 476 arate line, along with the line number where the variable is 477 declared, set or used, according to the nature of the warning. 478 The briefer format simply lists all variables to which the warn- 479 ing applies, with up to 4 variables per line. 480 481 See also: -quiet. 482 483 484 485 -calltree=list 486 Causes ftnchek to print out the call structure of the complete 487 program. 488 489 The list consists of keywords separated by commas or colons. 490 There are two special keywords: none to turn off all the 491 options, and help to print the list of all the keywords with a 492 brief explanation of each. (The keyword all turns on all the 493 options, but should not normally be used since only one format 494 should be specified.) If list is omitted, -calltree is equiva- 495 lent to -calltree=tree, and -nocalltree is equivalent to -call- 496 tree=none. By default no call graph is printed. 497 498 If the -mkhtml option is invoked and tree is the applied call- 499 tree option, a file named CallTree.html, will also be produced 500 depicting the tree in HTML format. This file is useful as a 501 starting point for browsing the HTML files describing each com- 502 ponent of the program. 503 504 The keywords which control which format is used are as follows: 505 506 tree: 507 produce the call graph in tree format. 508 509 reference: 510 produce the call graph in who-calls-who format (same as 511 -reference switch). 512 513 vcg: 514 produce the call graph in VCG format (same as -vcg switch). 515 516 Only one of the formats tree, reference, or vcg may be speci- 517 fied. 518 519 The following keywords control options affecting the output: 520 521 prune: 522 prune repeated subtrees (applicable only with tree). This 523 the default. 524 525 sort: 526 sort children of each routine into alphabetical order. This 527 is the default. 528 529 See the discussion of the -reference and -vcg flags for details 530 about these formats. 531 532 For tree format, The call graph is printed out starting from the 533 main program, which is listed on the first line at the left mar- 534 gin. Then on the following lines, each routine called by the 535 main program is listed, indented a few spaces, followed by the 536 subtree starting at that routine. 537 538 In the default mode, if a routine is called by more than one 539 other routine, its call subtree is printed only the first time 540 it is encountered Later calls give only the routine name and the 541 notice ''(see above)''. To have the subtree printed for each 542 occurrence of the routine, use option no-prune. 543 544 Note that the call tree will be incomplete if any of the input 545 files are project files containing more than one module that 546 were created in -library mode. See the discussion of project 547 files below. 548 549 Technical points: Each list of routines called by a given rou- 550 tine is printed in alphabetical order unless the no-sort option 551 is given. If multiple main programs are found, the call tree of 552 each is printed separately. If no main program is found, a 553 report to that effect is printed out, and the call trees of any 554 top-level non-library routines are printed. This flag only 555 controls the printing of the call tree: ftnchek constructs the 556 call tree in any case because it is used to determine which 557 library modules will be cross-checked. See the discussion of 558 the -library flag. 559 560 For compatibility with previous versions of ftnchek, a numeric 561 form of this setting is also accepted: the list is replaced by a 562 number from 0 to 15. This number is formed from 1 for tree for- 563 mat, 2 for reference format, or 3 for vcg format, plus 4 for 564 no-prune, and 8 for no-sort. 565 566 See also: -crossref, -library, -reference, -sort, -symtab, -vcg. 567 568 569 570 -check 571 This switch is provided so that errors and warning messages can 572 be turned off when ftnchek is used for purposes other than find- 573 ing bugs, such as making declarations or printing the call tree. 574 It is positional, so after turning all checks off, selected 575 checks can be turned back on. The effect of -nocheck is to put 576 all switches, numeric settings, and settings controlling lists 577 of warnings to their turn-off values, as if they had all been 578 specified with the -no prefix. Switches and settings that spec- 579 ify options and modes of operation, rather than controlling 580 warnings, are unaffected. These are -columns, -crossref, 581 -include, -intrinsic, -library, -list, -makedcls, -novice, -out- 582 put, -pointersize, -project, -quiet, -reference, -resources, 583 -sort, -source, -symtab, -vcg, -version, -wordsize, and -wrap. 584 Default = yes. 585 586 Parse errors (syntax errors due to unrecognized or malformed 587 statements) are not suppressed by this switch, since the results 588 may be incorrect if ftnchek has not parsed the program cor- 589 rectly. 590 591 There are some miscellaneous errors and warning messages that 592 are not controlled by any other switch, and so can be turned off 593 only by this switch. Note that using -check following -nocheck 594 only has the effect of turning these special warnings back on, 595 and does not restore all the checks it turned off. These warn- 596 ings are: 597 598 o Module contains no executable statements. 599 600 o In free source form, missing space where space is required 601 (e.g. between a keyword and an identifier) or space present 602 where none is allowed (e.g. within an identifier). 603 604 o Zero or negative length specification in a data type decla- 605 ration of the form type*len. 606 607 o Invalid operand(s) in an expression. 608 609 o Array assigned to scalar. 610 611 o Type mismatch between DO index and bounds. 612 613 o Undefined common block declared in SAVE statement. 614 615 o Intrinsic function explicitly declared with an incompatible 616 type. 617 618 o Unknown intrinsic function explicitly declared in an INTRIN- 619 SIC statement. 620 621 o Intrinsic function passed as a subprogram argument is not 622 declared in an INTRINSIC statement. 623 624 o Intrinsic function or statement function invoked incor- 625 rectly. 626 627 o Function does not set return value prior to RETURN state- 628 ment. 629 630 o Parameter constant value not evaluated (this is ftnchek's 631 fault, and it is just informing you of the fact). 632 633 o Entry point of a subprogram is later used as a different 634 subprogram's name. 635 636 o Unknown keyword used in an I/O statement. 637 638 o Illegal label reference (e.g. GOTO refers to a non-exe- 639 cutable statement; I/O statement refers to a non-format 640 statement). 641 642 See also: -errors. 643 644 645 646 647 -columns=num 648 Set maximum statement length to num columns. (Beyond this is 649 ignored.) This setting is provided to allow checking of pro- 650 grams which may violate the Fortran standard limit of 72 columns 651 for the length of a statement. According to the standard, all 652 characters past column 72 are ignored. If this setting is used 653 when the -f77=long-line option is in effect, a warning will be 654 given for any lines in which characters past column 72 are pro- 655 cessed. Turn-on = max = 132. Default = 72. 656 657 This setting does not suppress warnings about the presence of 658 characters beyond column 72. To process code with meaningful 659 program text beyond column 72, use this setting and be sure the 660 -f77 long-line option is off. To process code with sequence 661 numbers in columns 73 to 80, leave the the columns setting at 662 the default value and use the -pretty=no-long-line flag. 663 664 See also: -f77, -pretty. 665 666 667 668 -common=list 669 This setting controls the strictness of checking of COMMON 670 blocks. By default, all warnings except volatile are turned on. 671 672 The list consists of keywords separated by commas or colons. 673 Since most of these warnings are on by default, include a key- 674 word prefixed by no- to turn off a particular warning. There 675 are three special keywords: all to turn on all the warnings, 676 none to turn them all off, and help to print the list of all the 677 keywords with a brief explanation of each. If list is omitted, 678 -common is equivalent to -common=dimensions,exact,length,type, 679 and -nocommon is equivalent to -common=none. The warning key- 680 words with their meanings are as follows: 681 682 dimensions: 683 corresponding arrays in each declaration of a block must 684 agree in size and number of dimensions. This option only 685 has an effect when used together with exact. 686 687 exact: 688 the comparison of two blocks is done variable-by-variable 689 rather than simply requiring agreement between corresponding 690 storage locations. Use this if all declarations of a given 691 COMMON block are supposed to be identical, which is a good 692 programming practice. 693 694 length: 695 warn if different declarations of the same block are not 696 equal in total length. The Fortran 77 Standard requires 697 each named common block, but not blank common, to be the 698 same length in all modules of the program. 699 700 type: 701 in each declaration of a given COMMON block, corresponding 702 memory locations (words or bytes) must agree in data type. 703 If used together with exact, this will require that corre- 704 sponding variables agree in data type. 705 706 volatile: 707 Assume that COMMON blocks are volatile. 708 709 Many Fortran programmers assume that variables, whether local or 710 in COMMON, are static, i.e. that once assigned a value, they 711 retain that value permanently until assigned a different value 712 by the program. However, in fact the Fortran 77 Standard does 713 not require this to be the case. Local variables may become 714 undefined between activations of a module in which they are 715 declared. Similarly, COMMON blocks may become undefined if no 716 module in which they are declared is active. (The technical 717 term for entities with this behavior is ''automatic'', but 718 ftnchek uses the word ''volatile'' since it is clearer to the 719 nonspecialist.) Only COMMON blocks declared in a SAVE state- 720 ment, or declared in the main program or in a block data subpro- 721 gram remain defined as long as the program is running. Vari- 722 ables and COMMON blocks that can become undefined at some point 723 are called volatile. 724 725 If the -common=volatile flag is turned on, ftnchek will warn you 726 if it finds a volatile COMMON block. If, at the same time, the 727 -usage=com-block-volatile option is turned on (which is the 728 default), ftnchek will try to check whether such a block can 729 lose its defined status between activations of the modules where 730 it is declared. ftnchek does not do a very good job of this: 731 the rule used is to see whether the block is declared in two 732 separated subtrees of the call tree. For instance, this would 733 be the case if two modules, both called from the main program, 734 shared a volatile COMMON block. A block can also become unde- 735 fined between two successive calls of the same subprogram, but 736 ftnchek is not smart enough to tell whether a subprogram can be 737 called more than once, so this case is not checked for. 738 739 The -common=volatile flag does not affect the way ftnchek checks 740 the usage of local variables. 741 742 For compatibility with previous versions of ftnchek, a numeric 743 form of this setting is also accepted: the list is replaced by a 744 number from 0 to 3. A value of 0 turns all the warnings off, 1 745 or greater turns on type, 2 or greater turns on length, and 3 746 turns on dimensions and exact also. The numeric form cannot 747 turn on the volatile option. 748 749 See also: -library, -usage. 750 751 752 753 -crossref=list 754 Prints cross-reference tables. Default = none. 755 756 The list consists of keywords separated by commas or colons. 757 The keywords with their meanings are as follows: 758 759 calls: 760 table lists each subprogram followed by a list of routines 761 that call it. This listing omits library modules that are 762 not in the call tree of the main program. The list is 763 alphabetized. 764 765 common: 766 table lists each COMMON block followed by a list of the 767 routines that access it. These listed routines are those 768 in which some variables in the COMMON block are accessed, 769 not simply those routines that declare the block. (To 770 find out what routines declare a COMMON block but do not 771 use it, see the -usage flag.) 772 773 labels: 774 table lists each label followed by a list of all refer- 775 ences to it. A label reference is denoted by the line 776 number and statement type of the referring statement. 777 The label list is in sequential order. The references are 778 listed in the order they are encountered in the program. 779 780 See also: -calltree, -reference, -sort, -symtab, -vcg. 781 782 783 784 -declare 785 If this flag is set, all identifiers whose datatype is not 786 declared in each module will be listed. This flag is useful for 787 helping to find misspelled variable names, etc. The same list- 788 ing will be given if the module contains an IMPLICIT NONE state- 789 ment. Default = no. 790 791 See also: -sixchar, -usage. 792 793 794 795 -division 796 This switch is provided to help users spot potential division 797 by zero problems. If this switch is selected, every division 798 except by a constant will be flagged. (It is assumed that the 799 user is intelligent enough not to divide by a constant which is 800 equal to zero!) Default = no. 801 802 See also: -portability, -truncation. 803 804 805 806 -errors=num 807 Set the maximum number of error messages in a ''cascade''. 808 During checking of agreement of subprogram arguments, common 809 block declarations, and so forth, sometimes a single case will 810 generate a long string of warnings. Often this simply indicates 811 some other cause than a genuine item-by-item mismatch, such as 812 for example a varible missing from one list. So in such cases 813 ftnchek stops printing the warnings after the cascade limit is 814 reached, and the trailer ''etc...'' is printed to indicate that 815 there were more errors not printed. If you think that these 816 warnings are likely to be genuine, use this setting to see more 817 of them. Turn-on = default = 3, max = 999. A value of 0 means 818 no limit. 819 820 This setting does not set an overall limit on the number of 821 error messages printed, only the number printed in any one cas- 822 cade. Most types of warnings and error messages are not subject 823 to the cascade effect and so are not affected by this setting. 824 To turn off warnings generally, use the individual warning con- 825 trol options or the -nocheck option. 826 827 See also: -check. 828 829 830 831 -extern 832 Causes ftnchek to report whether any subprograms invoked by the 833 program are never defined. Ordinarily, if ftnchek is being run 834 on a complete program, each subprogram other than the intrinsic 835 functions should be defined somewhere. Turn off this switch if 836 you just want to check a subset of files which form part of a 837 larger complete program. Subprogram arguments will still be 838 checked for correctness. Default = yes. 839 840 The -extern flag is now superseded by the -usage=ext-undefined 841 option. For the sake of convenience, the -extern flag is 842 retained, so that -noextern is equivalent to -usage=no-ext-unde- 843 fined option. The -extern switch may be retired eventually. 844 845 See also: -library. 846 847 848 849 -f77=list 850 Use this setting to catch language extensions which violate the 851 Fortran 77 Standard. Such extensions may cause your program not 852 to be portable. Examples include the use of underscores in 853 variable names; variable names longer than six characters; 854 statement lines longer than 72 characters; and nonstandard 855 statements such as the DO ... ENDDO structure. ftnchek does not 856 report on the use of lowercase letters. By default, all warn- 857 ings are turned off. 858 859 This setting provides detailed control over the warnings about 860 supported extensions to the Fortran 77 Standard. 861 862 (Further details about the extensions themselves are given below 863 in the section on Extensions.) The list consists of keywords 864 separated by commas or colons. There are three special key- 865 words: all to turn on all the warnings about nonstandard exten- 866 sions, none to turn them all off, and help to print the list of 867 all the keywords with a brief explanation of each. If list is 868 omitted, -f77 is equivalent to -f77=all, and -nof77 is equiva- 869 lent to -f77=none. The warning keywords with their meanings are 870 as follows: 871 872 accept-type: 873 ACCEPT and TYPE I/O statements. 874 875 array-bounds: 876 Expressions defining array bounds that contain array ele- 877 ments or function references. 878 879 assignment-stmt: 880 Assignment statements involving arrays. In Fortran 90, an 881 array can be assigned to another array of compatible 882 shape, or a scalar can be assigned to an array. Neither 883 of these assignments is permitted in Fortran 77. 884 885 A related warning occurs when an array is assigned to a 886 scalar. Since this is illegal also in Fortran 90, it is 887 always warned about regardless of the -f77 setting (unless 888 all checking is turned off with the -nocheck flag). 889 890 attribute-based-decl: 891 Type declarations in the new Fortran 90 attribute-based 892 style. This style of declaration is distinguished by the 893 use of a double colon (::) between the list of attributes 894 and the list of declared variables. This option also con- 895 trols warnings for use of Fortran 90 length or kind speci- 896 fiers in type declarations. (Although these specifiers 897 can be used in non-attribute-based declarations, they are 898 controlled by this option to avoid proliferation of -f77 899 options.) 900 901 automatic-array: 902 Local (not dummy) arrays which have variable size. These 903 would correspond to arrays whose storage would have to be 904 dynamically allocated at run time. 905 906 backslash: 907 Unix backslash escape in strings. This warning will be 908 given only if the -source=unix-backslash setting is speci- 909 fied to cause the escape interpretation of backslash.. 910 911 byte: BYTE data type declaration. 912 913 case-construct: 914 The SELECT CASE construct. 915 916 character: 917 Extensions to the Fortran 77 standard regarding character 918 data. At present, this only controls warnings about char- 919 acter variables declared with zero or negative length. In 920 Fortran 77, all character variables must be of positive 921 length. In Fortran 90, they can be zero length, and dec- 922 larations that specify negative lengths are permitted, 923 turning into zero for the declared length. Note: because 924 negative length specifiers may indicate a programming 925 error, the warning about them is given even if this option 926 is turned off, and is suppressed only by the -nocheck 927 flag. 928 929 common-subprog-name: 930 Common block and subprogram having the same name. 931 932 construct-name: 933 Use of a construct-name to label a control statement. 934 935 continuation: 936 More than 19 successive continuation lines. 937 938 cpp: Unix C preprocessor directives in the source code. 939 940 cray-pointer: 941 ''Cray pointer'' syntax. 942 943 cycle-exit: 944 The CYCLE and EXIT statements. 945 946 d-comment: 947 Debugging comments starting with D in the source code. 948 949 dec-tab: 950 DEC Fortran style tab-formatted source code. This warning 951 will be given only if the -source=dec-tab setting is spec- 952 ified to cause interpretation of tabs in this style. 953 954 do-enddo: 955 DO loop extensions: terminal statement label omitted, END 956 DO, and WHILE. 957 958 double-complex: 959 Double precision complex datatype. 960 961 format-dollarsign: 962 Dollar sign control code in FORMAT statements. 963 964 format-edit-descr: 965 Nonstandard edit descriptors in FORMAT statements. 966 967 function-noparen: 968 Function definition without parentheses. 969 970 implicit-none: 971 IMPLICIT NONE statement. 972 973 include: 974 INCLUDE statement. 975 976 inline-comment: 977 Inline comments starting with an exclamation point. 978 979 internal-list-io: 980 List-directed I/O to or from an internal file. 981 982 intrinsic: 983 Nonstandard intrinsic functions. 984 985 io-keywords 986 Nonstandard keywords used in I/O statements. These fall 987 into three groups. The first group includes keywords that 988 are accepted in Fortran 90: 989 990 ACTION PAD READWRITE 991 ADVANCE POSITION SIZE 992 DELIM READ WRITE 993 EOR 994 The second group comprises the following VMS Fortran key- 995 words: 996 997 BLOCKSIZE EXTENDSIZE READONLY 998 BUFFERCOUNT INITIALSIZE RECORDSIZE 999 CARRIAGECONTROL MAXREC RECORDTYPE 1000 DEFAULTFILE NAME (in OPEN) SHARED 1001 DISP NOSPANBLOCK TYPE 1002 DISPOSE ORGANIZATION 1003 (The keyword NAME is standard only in the INQUIRE state- 1004 ment.) The third group consists of the following IBM/MVS 1005 keyword: 1006 1007 NUM 1008 This flag also controls a warning about use of 1009 ACCESS='APPEND', which is accepted by some compilers. The 1010 value of 'APPEND' is not valid for any I/O specifier in 1011 standard Fortran 77, and in Fortran 90 'APPEND' should be 1012 used as a value of the POSITION specifier, not ACCESS. 1013 1014 long-line: 1015 Statements with meaningful code past 72 columns. This 1016 warning is given only if the -columns setting has been 1017 used to increase the statement field width. 1018 1019 long-name: 1020 Identifiers over 6 characters long. 1021 1022 mixed-common: 1023 Mixed character and noncharacter data in COMMON block. 1024 1025 mixed-expr: 1026 Nonstandard type combinations in expressions, for example 1027 DOUBLE PRECISION with COMPLEX, assigning hollerith to 1028 integer, logical operations on integers. 1029 1030 name-dollarsign: 1031 Dollar sign used as a character in identifiers. 1032 1033 name-underscore: 1034 Underscore used as a character in identifiers. 1035 1036 namelist: 1037 NAMELIST statement. 1038 1039 param-implicit-type: 1040 Implicit typing of a parameter by the data type of the 1041 value assigned. This warning can only occur if implicit 1042 parameter typing has been turned on by the 1043 -source=param-implicit-type option, or if the PARAMETER 1044 statement is of the nonstandard form without parentheses. 1045 If this option is turned on, then any instances where 1046 implicit parameter typing occurs will be warned about. If 1047 you want to be warned only in those instances where the 1048 implicit data type differs from the default type, use 1049 -portability=param-implicit-type instead. According to 1050 the Fortran 77 standard, the data type of a parameter is 1051 given by the same rules as for a variable, and if neces- 1052 sary a type conversion is done when the value is assigned. 1053 1054 param-intrinsic: 1055 Intrinsic function or exponentiation by a real used to 1056 define the value of a PARAMETER definition. 1057 1058 param-noparen: 1059 PARAMETER statement without parentheses. The user should 1060 be aware that the semantics of this form of the statement 1061 differs from that of the standard form: in this form, the 1062 parameter takes its data type from the value assigned, 1063 rather than having its default data type based on the 1064 first letter of the parameter name. (This form of the 1065 PARAMETER statement was introduced by DEC before the For- 1066 tran 77 standard was defined, and should be avoided.) 1067 1068 pointer: 1069 Fortran 90 standard pointer-related syntax, including 1070 POINTER, TARGET and ALLOCATABLE type declarations, ALLO- 1071 CATE, DEALLOCATE, and NULLIFY statements, and pointer 1072 assignment using =>. 1073 1074 quad-constant: 1075 Quad precision real constants, e.g. of the form 1.23Q4. 1076 1077 quotemark: 1078 Strings delimited by quote marks rather than apostrophes. 1079 1080 relops: 1081 Relational (comparison) operators composed of punctuation, 1082 namely: < <= == /= > >=. 1083 1084 semicolon: 1085 Semicolon used as statement separator. 1086 1087 statement-order: 1088 Statements out of the sequence mandated by the Standard. 1089 The allowed sequence is illustrated in Table 1 in the sec- 1090 tion on Interpreting the Output. 1091 1092 typeless-constant: 1093 Typeless constants, for example Z'19AF'. 1094 1095 type-size: 1096 Type declarations specifying a size, for example REAL*8. 1097 1098 variable-format: 1099 Variable repeat specification or field size in FORMAT. 1100 These are of the form < expr >. 1101 1102 vms-io: 1103 Obsolete. Now has the same meaning as the io-keywords 1104 keyword. 1105 1106 See also: -f90, -f95, -portability, -pretty, -style, -wordsize. 1107 1108 1109 1110 -f90=list 1111 This setting provides detailed control over the warnings about 1112 supported extensions to the Fortran 77 Standard that were not 1113 adopted as part of the Fortran 90 Standard. Note that ftnchek 1114 does not support the full Fortran 90 language. However, it does 1115 support some common extensions to Fortran 77 that were prevalent 1116 before Fortran 90 was defined. Some of these extensions became 1117 part of the Fortran 90 Standard, but others did not. The -f90 1118 setting warns only about the latter. That is, this flag covers 1119 things that are neither legal Fortran 77 nor legal Fortran 90. 1120 Therefore, the warnings controlled by this flag are basically a 1121 subset of the warnings controlled by -f77. There are a few 1122 cases, described below, where the circumstances in which the 1123 warning is given are slightly different for the two flags. 1124 1125 The list consists of keywords separated by commas or colons. 1126 There are three special keywords: all to turn on all the warn- 1127 ings about nonstandard extensions, none to turn them all off, 1128 and help to print the list of all the keywords with a brief 1129 explanation of each. If list is omitted, -f90 is equivalent to 1130 -f90=all, and -nof90 is equivalent to -f90=none. 1131 1132 The following keywords have identical meanings for -f90 as for 1133 -f77. The reader is referred to the explanations under -f77. 1134 1135 accept-type double-complex param-noparen 1136 backslash format-dollarsign cray-pointer 1137 byte format-edit-descr quad-constant 1138 cpp function-noparen type-size 1139 d-comment name-dollarsign variable-format 1140 dec-tab param-implicit-type vms-io 1141 1142 The keywords which differ somewhat from the corresponding -f77 1143 keywords are as follows. 1144 1145 continuation: 1146 The limit on the number of continuation lines for a state- 1147 ment in fixed source form is the same, namely 19, in For- 1148 tran 90 as in Fortran 77. For free source form the limit 1149 is 39 continuation lines, and a line containing a continu- 1150 ation mark cannot be otherwise empty or contain only a 1151 comment. 1152 1153 intrinsic: 1154 This is the same as for -f77 except for the intrinsic 1155 functions defined in MIL-STD 1753, which are all included 1156 in Fortran 90, and so are not warned about. (See -intrin- 1157 sic for a list.) 1158 1159 io-keywords: 1160 This is the same as for -f77 except that no warnings are 1161 given for the I/O keywords that are standard in Fortran 1162 90. 1163 1164 long-line: 1165 Although the Fortran 90 Standard allows lines longer than 1166 72 characters in free source form, this restriction still 1167 applies to fixed source form. In free source form the 1168 line length limit is 132 characters, and unlike fixed 1169 form, ftnchek does not allow this limit to be increased. 1170 1171 mixed-expr: 1172 This is the same as for -f77 except for expressions mixing 1173 extended precision real with complex data types, which are 1174 permitted in Fortran 90. 1175 1176 statement-order: 1177 This is similar to the corresponding -f77 warning, but 1178 applies the somewhat looser restrictions on statement 1179 order of the Fortran 90 Standard. In particular, Fortran 1180 90 allows DATA statements and statement-function defini- 1181 tions to be intermixed with specification statements. 1182 1183 typeless-constant: 1184 In Fortran 90, binary, octal, and hexadecimal constants of 1185 the form B'ddd', O'ddd', and Z'ddd', respectively, are 1186 permitted. Here 'ddd' represents a string of digits. 1187 ftnchek recognizes these forms, as well as a variant of 1188 the form X'ddd' for a hexadecimal constant, and other 1189 variants in which the base indicator B, O, Z, or X follows 1190 the digit string. These variants were not adopted in For- 1191 tran 90, so only they are warned about when this flag is 1192 turned on. 1193 1194 See also: -f77, -f95, -portability, -pretty, -style, -wordsize. 1195 1196 1197 1198 -f95=list 1199 This setting provides detailed control over warnings about 1200 standard Fortran 77 features that were deleted from the Fortran 1201 95 Standard. Unlike the -f77 and -f90 settings, these warnings 1202 apply to syntax which is legal Fortran 77. However, since these 1203 features have been deleted from the Standard, it is possible 1204 that programs containing them will be unacceptable to some newer 1205 compilers. 1206 1207 The list consists of keywords separated by commas or colons. 1208 There are three special keywords: all to turn on all the warn- 1209 ings about nonstandard extensions, none to turn them all off, 1210 and help to print the list of all the keywords with a brief 1211 explanation of each. If list is omitted, -f95 is equivalent to 1212 -f95=all, and -nof95 is equivalent to -f95=none. The warning 1213 keywords with their meanings are as follows. 1214 1215 real-do: 1216 A DO variable of any real numeric type. 1217 1218 pause: 1219 The PAUSE statement. 1220 1221 assign: 1222 The ASSIGN statement, assigned GOTO, or assigned format. 1223 1224 h-edit: 1225 The H edit descriptor in a format. 1226 1227 There is one other Fortran 77 syntax feature that was deleted in 1228 Fortran 95, namely branching to an ENDIF from outside the IF 1229 block. However, ftnchek is unable to analyze program flow, and 1230 so it does not provide a warning for this. 1231 1232 See also: -f77, -f90, -portability, -pretty, -style, -wordsize. 1233 1234 1235 1236 -help 1237 Prints a list of all the command-line options with a short 1238 description of each along with its default value. This command 1239 is identical in function to the ''?'' argument, and is provided 1240 as a convenience for those systems in which the question mark 1241 has special meaning to the command interpreter. Default = no. 1242 1243 The help listing also prints the version number and patch level 1244 of ftnchek and a copyright notice. 1245 1246 Note: the ''default'' values printed in square brackets in the 1247 help listing are, strictly speaking, not the built-in defaults 1248 but the current values after any environment options and any 1249 command-line options preceding the -help option have been pro- 1250 cessed. 1251 1252 See also: -novice, -version, and help option of all settings 1253 that take a list of keywords. 1254 1255 1256 1257 -identifier-chars=list 1258 Define non-alphanumeric characters that may be used in identi- 1259 fiers. By default, ftnchek only accepts the dollar sign and 1260 underscore as non-alphanumeric characters in identifier names. 1261 The characters in the list replace whatever set of accepted non- 1262 alphanumeric characters was previously in effect. Thus, if dol- 1263 lar sign or underscore are not included in the list, they lose 1264 their status as acceptable characters. 1265 1266 This option is provided to enable ftnchek to handle source files 1267 containing non-standard identifer names that may be needed, for 1268 example, to access certain operating system services. See the 1269 section on Limitations and Extensions for the treatment of 1270 identifiers containing these characters in implicit typing. 1271 1272 Using -noidentifer-chars turns off acceptance of non-alphanu- 1273 meric characters entirely. 1274 1275 See also: -source. 1276 1277 1278 1279 -include=path 1280 Specifies a directory to be searched for files specified by 1281 INCLUDE statements. Unlike other command-line options, this 1282 setting is cumulative; that is, if it is given more than once on 1283 the command line, all the directories so specified are placed on 1284 a list that will be searched in the same order as they are 1285 given. The order in which ftnchek searches for a file to be 1286 included is: the current directory; the directory specified by 1287 environment variable FTNCHEK_INCLUDE if any; the directories 1288 specified by any -include options; the directory specified by 1289 environment variable INCLUDE; and finally in a standard system- 1290 wide directory (/usr/include for UNIX, SYS$LIBRARY for VMS, and 1291 \include for MSDOS). 1292 1293 See also: -f77, -source. 1294 1295 1296 1297 -intrinsic=list 1298 Controls whether ftnchek recognizes certain nonstandard intrin- 1299 sic functions as intrinsic. The list consists of keywords sepa- 1300 rated by commas or colons. Some of the keywords control whether 1301 to recognize certain groups of functions, and other keywords 1302 control the expected syntax for invoking some nonstandard 1303 intrinsics. Include a keyword to turn on recognition of the 1304 corresponding set of intrinsics or to allow the corresponding 1305 syntax. Include a keyword prefixed by no- to turn off that 1306 recognition. 1307 1308 There are three special keywords: all turns on recognition of 1309 all the nonstandard intrinsics (listed below) and accepts either 1310 syntax for those that have variations. Use none to turn off 1311 recognition of all nonstandard intrinsics except those noted 1312 below. Use help to print the list of all the keywords with a 1313 brief explanation of each. If list is omitted, -intrinsic is 1314 equivalent to -intrinsic=all, and -nointrinsic is equivalent to 1315 -intrinsic=none. 1316 1317 The nonstandard intrinsic functions needed to support the non- 1318 standard extended precision data types (double complex and quad 1319 precision) are always recognized. The intrinsics for the double 1320 complex data type are: 1321 1322 CDABS CDSQRT DREAL ZLOG 1323 CDCOS DCMPLX IMAG ZSIN 1324 CDEXP DCONJG ZABS ZSQRT 1325 CDLOG DIMAG ZEXP ZCOS 1326 CDSIN 1327 1328 The intrinsics for the quad precision and quad complex types 1329 are: 1330 1331 CQABS QARCOS QEXT QNINT 1332 CQCOS QARSIN QEXTD QPROD 1333 CQEXP QATAN QFLOAT QREAL 1334 CQLOG QATAN2 QIMAG QSIGN 1335 CQSIN QCMPLX QINT QSIN 1336 CQSQRT QCONJG QLOG QSINH 1337 DBLEQ QCOS QLOG10 QSQRT 1338 IQINT QCOSH QMAX1 QTAN 1339 IQNINT QDIM QMIN1 QTANH 1340 QABS QEXP QMOD SNGLQ 1341 1342 The keywords controlling recognition of other nonstandard 1343 intrinsic functions are as follows: 1344 1345 extra: 1346 recognize the following commonly available nonstandard 1347 intrinsics (all except EXIT and LOC are defined in MIL-STD 1348 1753): 1349 1350 BTEST IBCLR IEOR ISHFTC 1351 EXIT IBITS IOR LOC 1352 IAND IBSET ISHFT NOT 1353 1354 1355 unix: recognize these common Unix-specific intrinsic functions: 1356 1357 ABORT GMTIME LTIME SRAND 1358 AND IARGC OR SYSTEM 1359 GETARG IRAND RAND TIME 1360 GETENV LSHIFT RSHIFT XOR 1361 1362 1363 vms: recognize these common VMS-specific intrinsic functions: 1364 1365 DATE IDATE SECNDS TIME 1366 ERRSNS RAN SIZEOF 1367 1368 1369 iargc-no-argument: 1370 specify that IARGC may be invoked with no arguments. 1371 1372 iargc-one-argument: 1373 specify that IARGC may be invoked with one argument. 1374 1375 rand-no-argument: 1376 specify that RAND and IRAND may be invoked with no argu- 1377 ments. 1378 1379 rand-one-argument: 1380 specify that RAND and IRAND may be invoked with one argu- 1381 ment. 1382 1383 The no-argument and one-argument keywords work as follows: turn- 1384 ing the option on causes ftnchek to accept the corresponding 1385 syntax for invocation of the function, without excluding the 1386 possibility of the alternative syntax. Turning the option off 1387 causes the corresponding syntax not to be accepted. If both 1388 options are turned on at once (the default), then either syntax 1389 is accepted. Turning both options off at once would not be 1390 meaningful. These options have no effect if recognition of Unix 1391 intrinsics has been turned off. 1392 1393 Note that this setting does not control whether non-standard 1394 warnings are issued about these functions. It controls whether 1395 the functions are assumed to be intrinsic or not, which deter- 1396 mines how their usage is checked. When functions in any of 1397 these sets are included, their invocations will be checked 1398 according to the rules for the intrinsic functions; otherwise 1399 they will be checked as normal (user-written) external func- 1400 tions. The non-standard warnings are controlled by the 1401 -f77=intrinsic option. 1402 1403 The default value of this setting is equivalent to 1404 1405 -intrinsic=all followed by -intrinsic=no-vms for the Unix ver- 1406 sion, -intrinsic=no-unix for the VMS version, and -intrin- 1407 sic=no-unix,no-vms for other versions. 1408 1409 Note: In versions of ftnchek prior to 2.10, the -intrinsic flag 1410 took a numeric argument instead of a list of options. For the 1411 sake of users who may have written scripts invoking ftnchek in 1412 this way, the numeric form is still accepted. The numeric form 1413 of the setting consists of three digits. The ones digit selects 1414 the set of intrinsic functions to be supported. The digit 0 1415 selects only Fortran 77 standard intrinsics plus those needed to 1416 support the nonstandard extended precision data types. The 1417 digit 1 is equivalent to extra, 2 is equivalent to extra,unix, 1418 and 3 is equivalent to extra,vms. The tens digit of this set- 1419 ting controls the syntax of the RAND intrinsic function, and the 1420 hundreds digit controls the syntax of the IARGC function. For 1421 these digits, specify 0 to require invocation with no argument, 1422 1 to require one argument, and 2 to allow either form. 1423 1424 See also: -f77. 1425 1426 1427 1428 -library 1429 This switch is used when a number of subprograms are contained 1430 in a file, but not all of them are used by the application. 1431 Normally, ftnchek warns you if any subprograms are defined but 1432 never used. This switch will suppress these warnings. Default 1433 = no. 1434 1435 This switch also controls which subprogram calls and COMMON 1436 block declarations are checked. If a file is read with the 1437 -library flag in effect, the subprogram calls and COMMON decla- 1438 rations contained in a routine in that file will be checked only 1439 if that routine is in the main program's call tree. On the 1440 other hand, if the -library switch is turned off, then ftnchek 1441 checks the calls of every routine by every other routine, 1442 regardless of whether those routines could ever actually be 1443 invoked at run time, and likewise all COMMON block declarations 1444 are compared for agreement. 1445 1446 The difference between this switch and the -usage=no-ext-unused 1447 option for subprograms is that the latter suppresses only the 1448 warning about routines being declared but not used. The 1449 -library switch goes further and excludes unused routines pro- 1450 cessed while it is in effect from all cross-checking of argu- 1451 ments and COMMON block declarations as well. 1452 1453 (If there is no main program anywhere in the set of files that 1454 ftnchek has read, so that there is no call tree, then ftnchek 1455 will look for any non-library routines that are not called by 1456 any other routine, and use these as substitutes for the main 1457 program in constructing the call tree and deciding what to 1458 check. If no such top-level non-library routines are found, 1459 then all inter-module calls and all COMMON declarations will be 1460 checked.) 1461 1462 See also: -arguments, -calltree, -common, -extern, -usage. 1463 1464 1465 1466 -list 1467 Specifies that a listing of the Fortran program is to be 1468 printed out with line numbers. If ftnchek detects an error, the 1469 error message follows the program line with a caret ( ^ ) speci- 1470 fying the location of the error. If no source listing was 1471 requested, ftnchek will still print out any line containing an 1472 error, to aid the user in determining where the error occurred. 1473 Default = no. 1474 1475 See also: -output, \fB-symtab, fB-quiet. 1476 1477 1478 1479 -makedcls=list 1480 Prepare a neatly-formatted file of declarations of variables, 1481 common blocks, and namelist lists, for possible merging into the 1482 source code. The declarations are stored in a file of the same 1483 name as the source code, but with the extension changed to .dcl. 1484 If no declarations are written to the file, it is deleted to 1485 reduce clutter from empty files. 1486 1487 If input comes from standard input, instead of a named file, 1488 then declarations are written to standard output. 1489 1490 Variables are declared in alphabetical order within each decla- 1491 ration class and type, with integer variables first, because of 1492 their later possible use in array dimensions. 1493 1494 PARAMETER statements are an exception to the alphabetical order 1495 rule, because the Fortran 77 Standard requires that the expres- 1496 sions defining parameter values refer only to constants and 1497 already-defined parameter names. This forces the original 1498 source file order of such statements to be preserved in the dec- 1499 laration files. 1500 1501 Explicit declaration of all variables is considered good modern 1502 programming practice. By using compiler options to reject unde- 1503 clared variables, misspelled variable names (or names extending 1504 past column 72) can be caught at compile time. Explicit decla- 1505 rations also greatly facilitate changing floating-point preci- 1506 sion with filters such as dtoq(1L), dtos(1L), fd2s(1L), 1507 fs2d(1L), qtod(1L), and stod(1L). These programs are capable of 1508 changing types of explicit floating-point type declarations, 1509 intrinsic functions, and constants, but because they do not 1510 carry out rigorous lexical and grammatical analysis of the For- 1511 tran source code, they cannot provide modified type declarations 1512 for undeclared variables. Default setting = 0, turn-on = 1. 1513 1514 Various options for the form of the declarations file are con- 1515 trolled by the list, which consists of keywords separated by 1516 commas or colons. There are three special keywords: all to turn 1517 on all the options, none to turn them all off, and help to print 1518 the list of all the keywords with a brief explanation of each. 1519 If list is omitted, -makedcls is equivalent to -makedcls=decla- 1520 rations (i.e. produce the declarations file using the default 1521 options), and -nomakedcls is equivalent to -makedcls=none. 1522 1523 For compatibility with previous versions of ftnchek, a numeric 1524 form of this setting is also accepted: the list is replaced by 1525 a number which is the sum of the numbers in parentheses beside 1526 the keywords in the following list. The warning keywords with 1527 their meanings are as follows: 1528 1529 declarations (1): 1530 Write a declaration file. (This is implied by any of the 1531 other options, and can be omitted if any other options are 1532 given.) 1533 1534 undeclared-only (2): 1535 By default, all variables are included in the declaration 1536 file. With this option, include only undeclared vari- 1537 ables. This setting is useful if you want to check for 1538 undeclared variables, since Fortran source files with all 1539 variables properly declared will not result in a .dcl 1540 file. With this option, common blocks and namelist lists 1541 will not be included in the declaration file, since by 1542 their nature they cannot be undeclared. 1543 1544 compact (4): 1545 The declarations are normally prettyprinted to line up 1546 neatly in common columns, as in the declaration files out- 1547 put by the Extended PFORT Verifier, pfort(1L). This 1548 option value selects instead compact output, without col- 1549 umn alignment. 1550 1551 use-continuation-lines (8): 1552 Causes continuation lines to be used where permissible. 1553 The default is to begin a new declaration on each line. 1554 This option is appropriate to use together with compact. 1555 1556 keywords-lowercase (16): 1557 Output Fortran keywords in lowercase, instead of the 1558 default uppercase. 1559 1560 vars-and-consts-lowercase (32): 1561 Output variables and constants in lowercase, instead of 1562 the default uppercase. Character string constants are 1563 not affected by this option. 1564 1565 exclude-sftran3 (64): 1566 Omit declarations of internal integer variables produced 1567 by the SFTRAN3 preprocessor, xsf3(1L), as part of the 1568 translation of structured Fortran statements to ordinary 1569 Fortran. These variables have six-character names of the 1570 form NPRddd, NXdddd, N2dddd, and N3dddd, where d is a dec- 1571 imal digit. Because they are invisible in the SFTRAN3 1572 source code, and will change if the SFTRAN3 code is modi- 1573 fied, such variables should not be explicitly declared. 1574 Instead, they should just assume the default Fortran INTE- 1575 GER data type based on their initial letter, N. 1576 1577 asterisk-comment (128): 1578 Use an asterisk as the comment character; the default is 1579 otherwise 'C'. 1580 1581 comment-char-lowercase (256): 1582 Use 'c' instead of 'C' or '*' as the comment character. 1583 1584 suppress-array-dimensions (512): 1585 Suppress dimensioning of arrays in the generated declara- 1586 tions. This option is for use with code lacking type dec- 1587 larations, to allow the declaration files to be inserted 1588 without change into the code. Since the code will have 1589 dimension statements already, dimensioning the array vari- 1590 ables in the type statements of the declaration file is 1591 redundant. This option should be used only in conjunction 1592 with option 2 = undeclared-only because otherwise any 1593 arrays that were dimensioned in a type statement will lose 1594 their dimensioning. 1595 1596 free-form (1024): 1597 Produce declarations in free source form. This mode is 1598 automatically used if the input source is free form. Use 1599 this option to produce declarations in free form even if 1600 the input is in fixed form. Free form declarations are 1601 indented only 2 columns instead of 6, use the exclamation 1602 mark as the comment character, and indicate continuation 1603 lines by an ampersand at the end of the line to be contin- 1604 ued. 1605 1606 The declaration files contain distinctive comments that mark the 1607 start and end of declarations for each program unit, to facili- 1608 tate using text editor macros for merging the declarations back 1609 into the source code. 1610 1611 The ftnchek distribution includes a program, dcl2inc, which pro- 1612 cesses declaration files to produce files containing declara- 1613 tions of all COMMON blocks, in a form suitable for use as 1614 INCLUDE files. See the dcl2inc(1L) man page for the details of 1615 its use. 1616 1617 See also: -mkhtml. 1618 1619 1620 1621 -mkhtml=list 1622 Produce HTML documentation from source. Creates individual HTML 1623 files from ftnchek analysis and code comments. All comments 1624 immediately preceding and following the function or subroutine 1625 definition are captured to the HTML file. No reformatting of 1626 source comments is performed other than stripping of FORTRAN 1627 comment characters. In addition, the HTML file lists the local 1628 variables declared, common block variables used, functions and 1629 subroutines called, I/O unit usage, and other information about 1630 each subprogram. Usually you will also want to specify 1631 -call=tree to create the root HTML file CallTree.html. (Perhaps 1632 this file should be named index.html.) 1633 1634 Various options for the form of the HTML files are controlled by 1635 the list, which consists of keywords separated by commas or 1636 colons. There are three special keywords: all to turn on all 1637 the options, none to turn them all off, and help to print the 1638 list of all the keywords with a brief explanation of each. If 1639 list is omitted, -mkhtml is equivalent to -mkhtml=documents 1640 (i.e. produce the HTML document files using the default 1641 options), and -nomkhtmls is equivalent to -mkhtml=none. 1642 1643 For the sake of simplicity, the options for -mkhtml are the same 1644 as those for -makedcls except for those that are inapplicable. 1645 Likewise, a numeric form of this setting can be used, formed as 1646 the sum of the numbers in parentheses in the list below. The 1647 warning keywords with their meanings are as follows: 1648 1649 documents (1): 1650 Create the HTML documents. (This is implied by any of the 1651 other options, and can be omitted if any other options are 1652 given.) 1653 1654 compact (4): 1655 The declarations are normally prettyprinted to line up 1656 neatly in common columns. This option value selects 1657 instead compact output, without column alignment. 1658 1659 use-continuation-lines (8): 1660 Causes continuation lines to be used instead of beginning 1661 a new declaration on each line. This option is appropri- 1662 ate to use together with compact. 1663 1664 keywords-lowercase (16): 1665 Output Fortran keywords in lowercase, instead of the 1666 default uppercase. 1667 1668 vars-and-consts-lowercase (32): 1669 Output variables and constants in lowercase, instead of 1670 the default uppercase. Character string constants are 1671 not affected by this option. 1672 1673 exclude-sftran3 (64): 1674 Omit declarations of internal integer variables produced 1675 by the SFTRAN3 preprocessor, xsf3(1L). (See -makedcls for 1676 discussion.) 1677 1678 suppress-array-dimensions (512): 1679 Suppress dimensioning of arrays in the generated declara- 1680 tions. This is normally undesirable, but is available if 1681 for some reason you do not want the array dimensions to 1682 appear in the HTML. 1683 1684 free-form (1024): 1685 Produce variable declarations in free source form. This 1686 mode is automatically used if the input source is free 1687 form. This mainly affects the form of continuation lines 1688 if they are used. 1689 1690 See also: -calltree, -makedcls. 1691 1692 1693 1694 -novice 1695 This flag is intended to provide more helpful output for begin- 1696 ners. It has two effects: 1697 1698 (a) provides an extra message to the effect that a function that 1699 is used but not defined anywhere might be an array which the 1700 user forgot to declare in a DIMENSION statement (since the 1701 syntax of an array reference is the same as that of a func- 1702 tion reference). 1703 1704 (b) modifies the form of the error messages and warnings. If 1705 the flag is turned off by -nonovice, these messages are 1706 printed in a style more resembling UNIX lint. 1707 1708 Default = yes. 1709 1710 1711 1712 -output=filename 1713 This setting is provided for convenience on systems which do 1714 not allow easy redirection of output from programs. When this 1715 setting is given, the output which normally appears on the 1716 screen will be sent instead to the named file. Note, however, 1717 that operational errors of ftnchek itself (e.g. out of space or 1718 cannot open file) will still be sent to the screen. The exten- 1719 sion for the filename is optional, and if no extension is given, 1720 the extension .lis will be used. 1721 1722 1723 1724 -pointersize=num 1725 Specifies the size of a ''Cray pointer'' variable to be num 1726 bytes. Default = turn-on = 4 bytes. 1727 1728 The pointer size is used to inform precision mismatch warnings 1729 involving pointer variables, for example when a pointer is 1730 assigned a value from an allocation routine, or passed as a sub- 1731 program parameter. 1732 1733 See also: -f77, -portability, -truncation, -wordsize. 1734 1735 1736 1737 -portability=list 1738 ftnchek will give warnings for a variety of non-portable 1739 usages. Examples include the use of tabs except in comments or 1740 inside strings, the use of Hollerith constants, and the equiva- 1741 lencing of variables of different data types. This option does 1742 not produce warnings for supported extensions to the Fortran 77 1743 Standard, which may also cause portability problems. To catch 1744 those, use the -f77 setting. By default, all warnings are 1745 turned off. 1746 1747 This setting provides detailed control over the warnings about 1748 possible portability problems. The list consists of keywords 1749 separated by commas or colons. There are three special key- 1750 words: all to turn on all the warnings about nonportable usages, 1751 none to turn them all off, and help to print the list of all the 1752 keywords with a brief explanation of each. If list is omitted, 1753 -portability is equivalent to -portability=all, and -noportabil- 1754 ity is equivalent to -portability=none. The warning keywords 1755 with their meanings are as follows: 1756 1757 backslash: 1758 Backslash character in strings. Since some compilers 1759 treat the backslash as an escape character, its presence 1760 can cause problems even though it is used in a standard- 1761 conforming way. 1762 1763 common-alignment: 1764 COMMON block variables not in descending order of storage 1765 size. Some compilers require this ordering because of 1766 storage alignment requirements. 1767 1768 hollerith: 1769 Hollerith constants (other than within FORMAT specifica- 1770 tions). The Hollerith data type is a feature of Fortran 1771 IV that has been deleted in the Fortran 77 standard. It 1772 is superseded by the character data type. Storing Hol- 1773 lerith data in variables of a numeric or logical data type 1774 is nonportable due to differing word sizes. 1775 1776 long-string: 1777 String constants, variables, or expressions over 255 chars 1778 long. 1779 1780 mixed-equivalence: 1781 Variables of different data types equivalenced. 1782 1783 mixed-size: 1784 Variables declared with default precision used with vari- 1785 ables given explicit precision, in expressions, assign- 1786 ments, or as arguments. For example, if a variable 1787 declared as REAL*8 is treated as equivalent to DOUBLE PRE- 1788 CISION. 1789 1790 real-do: 1791 Non-integer DO loop index and bounds. These can cause a 1792 program's results to depend on the hardware characteris- 1793 tics of the particular computer used. 1794 1795 param-implicit-type: 1796 Implicit typing of a parameter by the data type of the 1797 value assigned, if it differs from the default type. This 1798 warning can only occur if implicit parameter typing has 1799 been turned on by the -source=param-implicit-type option, 1800 or if the PARAMETER statement is of the nonstandard form 1801 without parentheses. If this option is turned on, then 1802 any instances where implicit parameter typing occurs and 1803 where the implicit type is different from the default type 1804 based on the first letter of the parameter name, will be 1805 warned about. Implicit parameter typing can change the 1806 semantics of statements where the parameter is used, caus- 1807 ing portability problems. 1808 1809 tab: Tabs in source code. Tabs are interpreted differently by 1810 different compilers. This warning will be given only 1811 once, at the end of the file. 1812 1813 See also: -f77, -f90, -f95, -pretty, -style, -wordsize. 1814 1815 1816 1817 -pretty=list 1818 Controls certain messages related to the appearance of the 1819 source code. These warn about things that might make a program 1820 less readable or be deceptive to the reader. By default, all 1821 warnings are turned on. 1822 1823 This setting provides detailed control over the warnings about 1824 appearance. The list consists of keywords separated by commas 1825 or colons. Since all warnings are on by default, include a key- 1826 word prefixed by no- to turn off a particular warning. There 1827 are three special keywords: all to turn on all the warnings 1828 about misleading appearances, none to turn them all off, and 1829 help to print the list of all the keywords with a brief explana- 1830 tion of each. If list is omitted, -pretty is equivalent to 1831 -pretty=all, and -nopretty is equivalent to -pretty=none. The 1832 warning keywords with their meanings are as follows: 1833 1834 alternate-return: 1835 A RETURN statement has a constant specifying an alternate 1836 return point that is not between 0 and the number of dummy 1837 arguments that are labels. This is legal, and has the 1838 same effect as a RETURN with no alternate return expres- 1839 sion, but suggests that the programmer intended to use an 1840 alternate return label that is not provided. 1841 1842 embedded-space: 1843 Space embedded in variable names or in multi-character 1844 operators such as **. 1845 1846 continuation: 1847 Continuation mark following a comment line. 1848 1849 long-line: 1850 Lines (except comments) over 72 columns in width (beyond 1851 72 is normally ignored by compiler). 1852 1853 missing-space: 1854 Lack of space between variable and a preceding keyword. 1855 1856 multiple-common: 1857 COMMON block declared in multiple statements. No warning 1858 is given if the statements are consecutive except for com- 1859 ment lines. 1860 1861 multiple-namelist: 1862 NAMELIST declared in multiple statements. No warning is 1863 given if the statements are consecutive except for comment 1864 lines. 1865 1866 parentheses: 1867 Parentheses around a variable by itself. As a subprogram 1868 argument, this makes the argument an expression, not modi- 1869 fiable by the subprogram. 1870 1871 Note that in free source form, extra space and missing space are 1872 forbidden by the Fortran 90 Standard, and are not mere style 1873 violations. In this case the warnings are replaced by syntax 1874 error messages, and can be turned off only by using -nocheck. 1875 1876 See also: -f77, -portability, -style. 1877 1878 1879 1880 -project=list 1881 ftnchek will create a project file from each source file that 1882 is input while this option is turned on. The project file will 1883 be given the same name as the input file, but with the extension 1884 .f or .for replaced by .prj. (If input is from standard input, 1885 the project file is named ftnchek.prj.) Default = none. 1886 1887 The list consists of keywords separated by commas or colons. 1888 There are three special keywords: all to turn on all the 1889 options, none to turn them all off, and help to print the list 1890 of all the keywords with a brief explanation of each. If list 1891 is omitted, -project is equivalent to -project=all, and -nopro- 1892 ject is equivalent to -project=none. The keywords with their 1893 meanings are as follows: 1894 1895 create: 1896 Produce a project file. The default is not to produce a 1897 project file. If this option is not turned on, the other 1898 options have no effect. 1899 1900 trim-calls: 1901 Trim the amount of information stored in the project file 1902 about subprogram declarations and calls. This is the 1903 default. Turn this option off only in rare situations. 1904 (See discussion below.) The amount of trimming varies 1905 depending on the -library flag. More information is 1906 trimmed if that flag is turned on. 1907 1908 trim-common: 1909 Trim the number of common block declarations stored in the 1910 project file. This is the default. Turn this option off 1911 only in rare situations. (See discussion below.) This 1912 option has no effect if the -library flag is turned off: 1913 when not in library mode, no trimming of common block dec- 1914 larations is done regardless of this option. 1915 1916 A project file contains a summary of information from the source 1917 file, for use in checking agreement among FUNCTION, SUBROUTINE, 1918 and COMMON usages in other files. It allows incremental check- 1919 ing, which saves time whenever you have a large set of files 1920 containing shared subroutines, most of which seldom change. You 1921 can run ftnchek once on each file with the -project flag set, 1922 creating the project files. Usually you would also set the 1923 -library and -noextern flags at this time, to suppress messages 1924 relating to consistency with other files. Only error messages 1925 pertaining to each file by itself will be printed at this time. 1926 Thereafter, run ftnchek without these flags on all the project 1927 files together, to check consistency among the different files. 1928 All messages internal to the individual files will now be omit- 1929 ted. Only when a file is altered will a new project file need 1930 to be made for it. 1931 1932 Naturally, when the -project option is turned on, ftnchek will 1933 not read project files as input. 1934 1935 Ordinarily, the trim options should be left on when you intend 1936 to create project files for future input to ftnchek. Since 1937 trimming is on by default, this means that simply giving the 1938 command -project with no option list is the recommended mode. 1939 The trim options are provided only as a convenience for those 1940 who want to make use of project files for purposes other than 1941 checking the program with ftnchek. To use project files for 1942 their intended purpose, the trim options should not be turned 1943 off. 1944 1945 Project files contain only information needed for checking 1946 agreement between files. This means that a project file is of 1947 no use if all modules of the complete program are contained in a 1948 single file. 1949 1950 A more detailed discussion is given in the section on Using 1951 Project Files. 1952 1953 1954 1955 -pure 1956 Assume functions are ''pure'', i.e., they will not have side 1957 effects by modifying their arguments or variables in a COMMON 1958 block. When this flag is in effect, ftnchek will base its 1959 determination of set and used status of the actual arguments on 1960 the assumption that arguments passed to a function are not 1961 altered. It will also issue a warning if a function is found to 1962 modify any of its arguments or any COMMON variables. Default = 1963 yes. 1964 1965 When this flag is turned off, actual arguments passed to func- 1966 tions will be handled the same way as actual arguments passed to 1967 subroutines. This means that ftnchek will assume that arguments 1968 may be modified by the functions. No warnings will be given if 1969 a function is found to have side effects. Because stricter 1970 checking is possible if functions are assumed to be pure, you 1971 should turn this flag off only if your program actually uses 1972 functions with side effects. 1973 1974 1975 1976 -quiet 1977 This option reduces the amount of output relating to normal 1978 operation, so that error messages are more apparent. This 1979 option is provided for the convenience of users who are checking 1980 large suites of files. The eliminated output includes the names 1981 of project files, and the message reporting that no syntax 1982 errors were found. It also eliminates some blank lines that are 1983 ordinarily included for clarity. (Some of this output is turned 1984 back on by the -list and -symtab options.) Default = no. 1985 1986 Note: the way to remember the difference between the -quiet and 1987 -brief is that -quiet doesn't suppress any warning-related 1988 information, whereas -brief does. 1989 1990 See also: -brief. 1991 1992 1993 1994 -reference 1995 Specifies that a who-calls-who table be printed. This table 1996 lists each subprogram followed by a list of the routines it 1997 calls. This switch is equivalent to -calltree=reference. 1998 Default = no. 1999 2000 The reference list omits routines called by unused library mod- 2001 ules. Thus it contains the same information as for the call- 2002 tree format, namely the hierarchy of subprogram calls, but 2003 printed in a different way. This prints out a breadth-first 2004 traversal of the call tree whereas -calltree=tree prints out a 2005 depth-first traversal. 2006 2007 See also: -calltree, -crossref, -library, -sort, -symtab, -vcg. 2008 2009 2010 2011 -resources 2012 Prints the amount of resources used by ftnchek in processing 2013 the program. This listing may be useful in analyzing the size 2014 and complexity of a program. It can also help in choosing 2015 larger sizes for ftnchek's internal tables if they are too small 2016 to analyze a particular program. Default = no. 2017 2018 In this listing, the term ''chunk size'' is the size of the 2019 blocks of memory allocated to store the item in question, in 2020 units of the size of one item, not necessarily in bytes. When 2021 the initially allocated space is filled up, more memory is allo- 2022 cated in chunks of this size. The following is an explanation 2023 of the items printed: 2024 2025 Source lines processed: 2026 Total number of lines of code, with separate totals for 2027 statement lines and comment lines. Comment lines include 2028 lines with 'C' or '*' in column 1 as well as blank lines and 2029 lines containing only an inline comment. Statement lines 2030 are all other lines, including lines that have an inline 2031 comment following some code. Continuation lines are counted 2032 as separate lines. Lines in include files are counted each 2033 time the file is included. 2034 2035 Total executable statements: 2036 Number of statements in the program, other than specifica- 2037 tion, data, statement-function, FORMAT, ENTRY, and END 2038 statements. 2039 2040 Total number of modules: 2041 A module is any external subprogram, including the main pro- 2042 gram, subroutines, functions, and block data units. This 2043 count is of modules defined within the source, not modules 2044 referenced. Statement functions are not included. A sub- 2045 program with multiple entry points is only counted once. 2046 2047 Total statement labels defined 2048 Number of labels attached to statements (often called state- 2049 ment numbers). The total label count for the entire program 2050 is given, as well as the maximum number in any single sub- 2051 program. 2052 2053 Max identifier name chars: 2054 Number of characters used for storing identifier names. An 2055 identifier is a variable, subprogram, or common block name. 2056 Local names are those of local variables in a subprogram, 2057 whereas global names refer to subprogram and common block 2058 names, as well as dummy argument names and common variable 2059 names. Actual argument text (up to 15 characters for each 2060 argument) is also included here. The space used for local 2061 names is not recovered at the end of each module, so this 2062 number, like global space, grows until the whole program is 2063 analyzed. Unfortunately, this figure may include some text 2064 stored more than once, although a heuristic is used that 2065 will avoid duplicates in many cases. 2066 2067 Max token text chars: 2068 A token is the smallest syntactic unit of the FORTRAN lan- 2069 guage above the level of individual characters. For instance 2070 a token can be a variable name, a numerical constant, a 2071 quoted text string, or a punctuation character. Token text 2072 is stored while a module is being processed. For technical 2073 reasons, single-character tokens are not included in this 2074 total. Items that are not represented in the symbol table 2075 may be duplicated. The space for token text is recovered at 2076 the end of each module, so this figure represents the maxi- 2077 mum for any one module. 2078 2079 Max local symbols: 2080 This is the largest number of entries in the local symbol 2081 table for any module. Local symbol table entries include 2082 all variables and parameters, common block names, statement 2083 functions, external subprograms and intrinsic functions 2084 referenced by the module. Literal constants are not stored 2085 in the local symbol table. 2086 2087 Max global symbols: 2088 This is the number of entries in the global symbol table at 2089 the end of processing. Global symbol table entries include 2090 external subprogram and common block names. Intrinsic func- 2091 tions and statement functions are not included. 2092 2093 Max number of tokenlists: 2094 A token list is a sequence of tokens representing the actual 2095 or dummy argument list of a subprogram, or the list of vari- 2096 ables in a common block or namelist. Therefore this number 2097 represents the largest sum of COMMON, CALL, NAMELIST and 2098 ENTRY statements and function invocations for any one mod- 2099 ule. The space is recovered at the end of each module. 2100 2101 Max token list/tree space: 2102 This is the largest number of tokens in all the token lists 2103 and token trees of any one module. A token tree is formed 2104 when analyzing an expression: each operand is a leaf of the 2105 tree, and the operators are the nodes. Therefore this num- 2106 ber is a measure of the maximum complexity of an individual 2107 module. For instance a module with many long arithmetic 2108 expressions will have a high number. Note that unlike token 2109 text described above, the number of tokens is independent of 2110 the length of the variable names or literal constants in the 2111 expressions. 2112 2113 Number of subprogram invocations: 2114 This is the sum over all modules of the number of CALL 2115 statements and function invocations (except intrinsic func- 2116 tions and statement functions). 2117 2118 Number of common block decls: 2119 This is the sum over all modules of the number of common 2120 block declarations. That is, each declaration of a block in 2121 a different module is counted separately. (The standard 2122 allows multiple declarations of a block within the same mod- 2123 ule; these are counted as only one declaration since they 2124 are equivalent to a single long declaration.) 2125 2126 Number of array dim & param ptrs: 2127 This is the sum over all modules of the number of array 2128 dimension and parameter definition text strings saved for 2129 use by the -makedcls option. The length of the text strings 2130 is not counted. Each dimension of a multidimensional array 2131 is counted separately. 2132 2133 These numbers are obviously not the same when project files are 2134 used in place of the original source code. Even the numbers for 2135 global entities may be different, since some redundant informa- 2136 tion is eliminated in project files. 2137 2138 2139 2140 -sixchar 2141 One of the goals of the ftnchek program is to help users to 2142 write portable Fortran programs. One potential source of non- 2143 portability is the use of variable names that are longer than 2144 six characters. Some compilers just ignore the extra charac- 2145 ters. This behavior could potentially lead to two different 2146 variables being considered as the same. For instance, variables 2147 named AVERAGECOST and AVERAGEPRICE are the same in the first six 2148 characters. If you wish to catch such possible conflicts, use 2149 this flag. Default = no. 2150 2151 Use the -f77=long-names if you want to list all variables longer 2152 than six characters, not just those pairs that are the same in 2153 the first six. 2154 2155 See also: -f77, -portability. 2156 2157 2158 2159 -sort 2160 Specifies that a sorted list of all modules used in the program 2161 be printed. This list is in ''prerequisite'' order, i.e. each 2162 module is printed only after all the modules from which it is 2163 called have been printed. This is also called a ''topological 2164 sort'' of the call tree. Each module is listed only once. Rou- 2165 tines that are not in the call tree of the main program are 2166 omitted. If there are any cycles in the call graph (illegal in 2167 standard Fortran) they will be detected and diagnosed. Default 2168 = no. 2169 2170 See also: -calltree, -crossref, -reference, -symtab, -vcg. 2171 2172 2173 2174 -source=list 2175 This setting controls certain options about the form of the 2176 Fortran source code. The list consists of keywords separated by 2177 commas or colons. There are three special keywords: all to turn 2178 on all the options, none to turn them all off, and help to print 2179 the list of all the keywords with a brief explanation of each. 2180 If list is omitted, -source is equivalent to -source=all, and 2181 -nosource is equivalent to -source=none. 2182 2183 For compatibility with previous versions of ftnchek, a numeric 2184 form of this setting is also accepted: the list is replaced by 2185 a number which is the sum of the numbers in parentheses beside 2186 the keywords in the following list. (The fixed and free options 2187 do not have numeric values.) The warning keywords with their 2188 meanings are as follows: 2189 2190 fixed: 2191 Interpret the source as fixed form (with supported exten- 2192 sions such as exclamation mark for comments). Statements 2193 must be in columns 7 to 72 (unless the -cols setting has 2194 been used to change this), and blanks are not significant 2195 outside character context (but warned about under the 2196 -pretty option). This is the default mode unless the 2197 source file extension is .f90 or .F90. this option cannot 2198 be given together with -source=free. 2199 2200 free: Interpret the source as free form. Statements may be any- 2201 where in columns 1 to 132, comments can only begin with an 2202 exclamation mark, and blanks are required in some places 2203 such as between identifiers and keywords. This is the 2204 default mode if the source file extension is .f90 or .F90. 2205 This option cannot be given together with -source=fixed or 2206 -source=dec-tab 2207 2208 dec-tab (1): 2209 Accept DEC-style tab-formatted source. A line beginning 2210 with an initial tab will be treated as a new statement 2211 line unless the character after the tab is a nonzero 2212 digit, in which case it is treated as a continuation line. 2213 The next column after the tab or continuation mark is 2214 taken as column 7. A warning will be given in the case 2215 where the line is a continuation, if -f77=dec-tab is in 2216 effect. 2217 2218 vms-include (2): 2219 Accept VMS-style INCLUDE statements. These follow the 2220 normal syntax, but with the following additional features: 2221 (1) the file extension, if not given, defaults to the same 2222 as a normal source file extension; and (2) the option 2223 /LIST or /NOLIST can be appended to the include-file name, 2224 to control listing of its contents. 2225 2226 unix-backslash (4): 2227 Handle UNIX-style backslash escapes in character strings. 2228 The escape sequence following the backslash will be evalu- 2229 ated according to the ANSI standard for strings in C: up 2230 to three digits signify an octal value, an x signifies the 2231 start of a hexadecimal constant, any of the letters a b f 2232 n r t signify special control codes, and any other charac- 2233 ter (including newline) signifies the character itself. 2234 When this source code option is in effect, a warning will 2235 be given if the -f77=backslash setting is specified. 2236 2237 The default behavior is to treat the backslash like any 2238 other normal character, but a warning about portability 2239 will be generated if the -portability flag is set. 2240 Because of the fact that some compilers treat the back- 2241 slash in a nonstandard way, it is possible for standard- 2242 conforming programs to be non-portable if they use the 2243 backslash character in strings. 2244 2245 Since ftnchek does not do much with the interpreted 2246 string, it is seldom necessary to use this option. It is 2247 needed in order to avoid spurious warnings only if (a) the 2248 program being checked uses backslash to embed an apostro- 2249 phe or quote mark in a string instead of using the stan- 2250 dard mechanism of doubling the delimiter; (b) the back- 2251 slash is used to escape the end-of-line in order to con- 2252 tinue a string across multiple source lines; or (c) a 2253 PARAMETER definition uses an intrinsic string function 2254 such as LEN with such a string as argument, and that value 2255 is later used to define array dimensions, etc. 2256 2257 param-implicit-type (8): 2258 Implicit typing of a parameter by the data type of the 2259 value assigned. Some non-standard compilers may allow the 2260 data type of the value to override the Fortran 77 default 2261 type of a parameter that is based on the first letter of 2262 the parameter name. This option only applies to PARAMETER 2263 statements of the standard form which has parentheses. A 2264 parameter that has been explicitly declared in a type 2265 statement prior to the PARAMETER statement is not affected 2266 by this option. A warning will be given under the 2267 -f77=param-implicit-type or -portabil- 2268 ity=param-implicit-type option. 2269 2270 Note that this implicit typing is treated as equivalent to 2271 an explicit type declaration for the parameter. There- 2272 fore, if you use -makedcls=undeclared-only to generate 2273 declarations only of undeclared variables, these parame- 2274 ters will not be included. 2275 2276 dec-param-standard-type (16): 2277 Follow the Fortran 77 rule for data typing of DEC Fortran 2278 style parameters. These are declared using a nonstandard 2279 form of the PARAMETER statement which lacks parentheses. 2280 According to DEC Fortran, parameters defined by this form 2281 of the statement have their data type given by the data 2282 type of the value assigned. Use this option to tell 2283 ftnchek not to follow this rule but instead to use the 2284 same rule as for standard PARAMETER statements. This 2285 option does not apply to PARAMETER statements of the stan- 2286 dard form. 2287 2288 By default, all these source code options are turned off, except 2289 for the vms-include option, which is on by default in the VMS 2290 version.. 2291 2292 See also: -f77, -include, -portability. 2293 2294 2295 2296 -style=list 2297 Provides extra-picky warnings about obsolescent or old-fash- 2298 ioned programming constructions. This option is helpful for 2299 efforts to follow a modern programming style. (Most of the 2300 things complained about under this option are forbidden in the F 2301 subset language.) By default, all warnings are turned off. 2302 2303 The list consists of keywords separated by commas or colons. 2304 There are three special keywords: all to turn on all the 2305 options, none to turn them all off, and help to print the list 2306 of all the keywords with a brief explanation of each. If list 2307 is omitted, -style is equivalent to -style=all, and -nostyle is 2308 equivalent to -style=none. The warning keywords with their 2309 meanings are as follows: 2310 2311 block-if: 2312 Complain about arithmetic IF statement. Accept block IF 2313 or logical IF (which controls a single statement). 2314 2315 construct-name: 2316 Complain about unnamed block constructs: IF, DO, and 2317 SELECT CASE. Note that if a construct name is present on 2318 the opening statement of a construct, then it is required 2319 to be present on all other component statements (ELSE, END 2320 IF, etc.) of the construct. In that case a missing con- 2321 struct name on those statements generates a syntax error 2322 regardless of this option. The purpose of this option is 2323 to warn if the construct completely lacks the optional 2324 name. 2325 2326 distinct-do: 2327 Complain if two DO loops share a common terminator state- 2328 ment. 2329 2330 do-construct: 2331 Complain if terminator of a DO loop is anything other than 2332 an END DO or CONTINUE statement. This is the requirement 2333 in order for the loop to meet the Fortran 90 definition of 2334 a do-construct. 2335 2336 do-enddo: 2337 Complain if terminator of a DO loop is anything other than 2338 an END DO statement. (This option overrides the do-con- 2339 struct option, being even stricter.) 2340 2341 end-name: 2342 Complain about the absence of the subprogram name on 2343 structured END statements. 2344 2345 format-stmt: 2346 Complain about the presence of FORMAT statements. Only 2347 the FORMAT statements themselves are flagged, not the ref- 2348 erences to them in I/O lists. 2349 2350 goto: Complain about the presence of unconditional, computed or 2351 assigned GOTO statements. Also complain about alternate 2352 returns (but not about labels as subprogram arguments). 2353 2354 labeled-stmt: 2355 Complain about the presence of labels (numbers) on state- 2356 ments other than FORMAT statements. (Since FORMAT state- 2357 ments are arguably convenient and not readily abused, com- 2358 plaints about them are controlled by the separate for- 2359 mat-stmt keyword.) 2360 2361 program-stmt: 2362 Complain about the absence of a PROGRAM statement at the 2363 head of the main program. 2364 2365 structured-end: 2366 Complain about the use of a plain END statement to end a 2367 subprogram, rather than a structured END statement (END 2368 PROGRAM, END SUBROUTINE, END FUNCTION, or END BLOCK DATA). 2369 2370 See also: -f77, -f90, -f95, -pretty, -portability. 2371 2372 2373 2374 -symtab 2375 A symbol table will be printed out for each module, listing all 2376 identifiers mentioned in the module. This table gives the name 2377 of each variable, its datatype, and the number of dimensions for 2378 arrays. An asterisk (*) indicates that the variable has been 2379 implicitly typed, rather than being named in an explicit type 2380 declaration statement. The table also lists all subprograms 2381 invoked by the module, all COMMON blocks declared, etc. Default 2382 = no. 2383 2384 Also, for each module, a label table will be printed. The table 2385 lists each label defined in the module; the line on which said 2386 statement label is defined; and the statement type (executable, 2387 format, or specification). The labels are listed in sequential 2388 order. 2389 2390 Also printed is a table describing the I/O units used by the 2391 module, together with information about how they are used: what 2392 operations are performed, whether the access is sequential or 2393 direct, and whether the I/O is formatted or unformatted. 2394 2395 See also: -calltree, -crossref, -list, -reference, -sort, -vcg. 2396 2397 2398 2399 -truncation=list 2400 Warn about possible truncation (or roundoff) errors. Most of 2401 these are related to integer arithmetic. By default, all warn- 2402 ings are turned on. 2403 2404 This setting provides detailed control over the warnings about 2405 possible truncation errors. The list consists of keywords sepa- 2406 rated by commas or colons. Since all warnings are on by 2407 default, include a keyword prefixed by no- to turn off a partic- 2408 ular warning. There are three special keywords: all to turn on 2409 all the warnings about truncation, none to turn them all off, 2410 and help to print the list of all the keywords with a brief 2411 explanation of each. If list is omitted, -truncation is equiva- 2412 lent to -truncation=all, and -notruncation is equivalent to 2413 -truncation=none. The warning keywords with their meanings are 2414 as follows: 2415 2416 int-div-exponent: 2417 use of the result of integer division as an exponent. 2418 This suggests that a real quotient is intended. An exam- 2419 ple would be writing X**(1/3) to evaluate the cube root of 2420 X. The correct expression is X**(1./3.). 2421 2422 int-div-real: 2423 Conversion of an expression involving an integer division 2424 to real. This suggests that a real quotient is intended. 2425 2426 int-div-zero: 2427 division in an integer constant expression that yields a 2428 result of zero. 2429 2430 int-neg-power: 2431 exponentiation of an integer by a negative integer (which 2432 yields zero unless the base integer is 1 in magnitude). 2433 This suggests that a real base is intended. 2434 2435 promotion: 2436 automatic conversion of a lower precision quantity to one 2437 of higher precision. The loss of accuracy for real vari- 2438 ables in this process is comparable to the corresponding 2439 demotion. No warning is given for promotion of integer 2440 quantities to real since this is ordinarily exact. 2441 2442 real-do-index: 2443 use of a non-integer DO index in a loop with integer 2444 bounds. An integer DO index with real bounds is always 2445 warned about regardless of this setting. 2446 2447 real-subscript: 2448 use of a non-integer array subscript. 2449 2450 significant-figures: 2451 overspecifying a single precision constant. This may 2452 indicate that a double precision constant was intended. 2453 2454 size-demotion: 2455 automatic conversion of a higher precision quantity to one 2456 of lower precision of the same type. This warning only 2457 occurs when an explicit size is used in declaring the type 2458 of one or both operands in an assignment. For example, a 2459 warning wil be issued where a REAL*8 variable is assigned 2460 to a REAL variable, if the default wordsize of 4 is in 2461 effect. A warning is also issued if a long integer is 2462 assigned to a shorter one, for example, if an INTEGER 2463 expression is assigned to an INTEGER*2 variable. There is 2464 one exception to this last case, namely if the right hand 2465 side of the assignment is a small literal constant (less 2466 than 128). type-demotion: automatic conversion of a 2467 higher precision quantity to one of lower precision of 2468 different type. This warning includes conversion of real 2469 quantities to integer, double precision to single preci- 2470 sion real, and assignment of a longer character string to 2471 a shorter one. 2472 2473 The warnings about promotion and demotion also apply to complex 2474 constants, considering the precision to be that of the real or 2475 imaginary part. Warnings about promotions and demotions are 2476 given only when the conversion is done automatically, e.g. in 2477 expressions of mixed precision or in an assignment statement. 2478 If intrinsic functions such as INT are used to perform the con- 2479 version, no warning is given. 2480 2481 See also: -portability, -wordsize. 2482 2483 2484 2485 -usage=list 2486 Warn about unused or possible uninitialized variables, unused 2487 common blocks, undefined or unused statement labels, and unused 2488 or undefined subprograms. By default, all warnings are turned 2489 on. 2490 2491 This setting provides detailed control over the warnings about 2492 possible usage errors. The list consists of keywords separated 2493 by commas or colons. Since all warnings are on by default, 2494 include a keyword prefixed by no- to turn off a particular warn- 2495 ing. There are three special keywords: all to turn on all the 2496 warnings about usage, none to turn them all off, and help to 2497 print the list of all the keywords with a brief explanation of 2498 each. If list is omitted, -usage is equivalent to -usage=all, 2499 and -nousage is equivalent to -usage=none. These warnings cover 2500 four main categories of objects: subprogram dummy arguments, 2501 common blocks and variables, subprograms and functions, and 2502 local variables. Warnings include undefined items, multiply 2503 defined items, unused items, etc. The warning keywords with 2504 their meanings are as follows: 2505 2506 arg-alias: 2507 a scalar dummy argument is actually the same as another 2508 and is (or may be) modified. The Fortran 77 standard 2509 (section 15.9.3.6) prohibits modifying an argument that is 2510 aliased to another. 2511 2512 arg-array-alias: 2513 a dummy argument which is an array or array element is in 2514 the same array as another and is modified. This flag is 2515 similar to arg-alias but provides separate control over 2516 array arguments. It is harder to tell if aliasing is 2517 occurring in the case of arrays, so if ftnchek gives too 2518 many false warnings, this flag allows the array-related 2519 ones to be turned off without suppressing the warnings for 2520 scalars. 2521 2522 arg-common-alias: 2523 a scalar dummy argument is the same as a common variable 2524 in the subprogram, and either is modified. This is also 2525 prohibited by the Fortran 77 standard. If common checking 2526 is not exact (see the -common setting), it is harder to 2527 tell if aliasing is occurring, so the warning is given if 2528 the variable is anywhere in a common block that is 2529 declared by the subprogram. 2530 2531 arg-common-array-alias: 2532 a dummy argument which is an array or array element is in 2533 the same array as a common variable, and either is modi- 2534 fied. If common checking is not exact, the variable can 2535 be anywhere in a common block that is declared by the sub- 2536 program. 2537 2538 arg-const-modified: 2539 a subprogram modifies an argument which is a constant or 2540 an expression. Such an action could cause anomalous 2541 behavior of the program. 2542 2543 arg-unused: 2544 a dummy argument is declared but never used. This is sim- 2545 ilar to the var-unused keyword described below, but 2546 applies only to arguments. 2547 2548 com-block-unused: 2549 a common block is declared but none of the variables in it 2550 are used by any subprogram. This warning is suppressed if 2551 the common strictness setting is 0. 2552 2553 com-block-volatile: 2554 a common block may lose the definition of its contents if 2555 common blocks are volatile. This option only has an 2556 effect if the -common=volatile flag is in effect. See the 2557 discussion of the -common setting above. 2558 2559 com-var-set-unused: 2560 a common variable is assigned a value, but its value is 2561 not used by any subprogram. This warning is suppressed if 2562 the common strictness setting is 0. 2563 2564 com-var-uninitialized: 2565 a common variable's value is used in some subprogram, but 2566 is not set anywhere. Unfortunately, ftnchek does not do a 2567 thorough enough analysis of the calling sequence to know 2568 which routines are called before others. So warnings 2569 about this type of error will only be given for cases in 2570 which a variable is used in some routine but not set in 2571 any other routine. Checking of individual COMMON vari- 2572 ables is done only if the -common setting is 3 (variable 2573 by variable agreement). This warning is suppressed if the 2574 common strictness setting is 0. 2575 2576 com-var-unused: 2577 a common variable is declared but not used by any subpro- 2578 gram. This warning is suppressed if the common strictness 2579 setting is 0. 2580 2581 do-index-modified: 2582 a variable that is the index of a DO loop is modified by 2583 some statement within the range of the loop. The Standard 2584 permits an active DO variable to be modified only by the 2585 incrementation mechanism of the DO statement. 2586 2587 ext-multiply-defined: 2588 an external (a subroutine or function) is defined more 2589 than once. Definition of an external means providing the 2590 body of its source code. 2591 2592 ext-declared-only: 2593 a name is declared in an EXTERNAL statement in some mod- 2594 ule, but is not defined or used anywhere. 2595 2596 ext-undefined: 2597 an external is used (invoked) but not defined anywhere. 2598 This option is equivalent to the -external flag. If the 2599 subprogram is invoked more than once, those invocations 2600 will still be checked for consistency. 2601 2602 ext-unused: 2603 an external is defined (its subprogram body is present) 2604 but it is not used. A subprogram is considered unused 2605 even if it is invoked by some other subprogram, if it can- 2606 not be called from any thread of execution starting with 2607 the main program. The agreement of the subprogram's argu- 2608 ments with its invocations is still checked even if this 2609 warning is turned off. If there is no main program, then 2610 this warning is issued only if the subprogram is not 2611 invoked anywhere. This warning is suppressed in library 2612 mode, but library mode has the additional effect of sup- 2613 pressing argument checking for unused routines. 2614 2615 label-undefined: 2616 a statement refers to a label that has not been defined. 2617 2618 label-unused: 2619 a statement label is defined, but never referred to. 2620 2621 var-set-unused: 2622 a local variable is assigned a value, but that value is 2623 not used. 2624 2625 var-uninitialized: 2626 a local variable's value may be used before it is 2627 assigned. Sometimes ftnchek makes a mistake in the warn- 2628 ings about local variable usage. Usually it errs on the 2629 side of giving a warning where no problem exists, but in 2630 rare cases it may fail to warn where the problem does 2631 exist. See the section on Bugs for examples. If vari- 2632 ables are equivalenced, the rule used by ftnchek is that a 2633 reference to any variable implies the same reference to 2634 all variables it is equivalenced to. For arrays, the rule 2635 is that a reference to any array element is treated as a 2636 reference to all elements of the array. 2637 2638 var-unused: 2639 a local variable is declared (for instance, in a type dec- 2640 laration) but is not used in the module. Does not apply 2641 to dummy arguments: warnings about them are controlled by 2642 the keyword arg-unused described above. 2643 2644 Note: In versions of ftnchek prior to 2.10, the -usage flag took 2645 a numeric argument instead of a list of options. For the sake 2646 of users who may have written scripts invoking ftnchek in this 2647 way, the numeric form is still accepted. The numeric setting is 2648 composed of three digits. The first digit (hundreds place) con- 2649 trols warnings about subprograms (functions and subroutines), 2650 the second digit (tens place) warnings about common blocks and 2651 common variables,, and the third digit (ones place) warnings 2652 about local variables. Each digit controls warnings according 2653 to the convention that a 1 means warn about undefined items and 2654 variables that are used before set, a 2 means warn about items 2655 that are unused, and a 3 means warn about both types. These 2656 numbers are now converted to the appropriate values for the 2657 above-listed keywords, except for com-block-volatile, which is 2658 not affected by the numeric argument. 2659 2660 See also: -common, -declare, -extern, -library. 2661 2662 2663 2664 -vcg 2665 Produce the call graph in the form of a VCG graph description. 2666 This description is written to a separate file, with the same 2667 stem as the file containing the main program, and suffix .vcg. 2668 This file is able to be given directly to xvcg(1L) to visualize 2669 the call graph. (If input is from the standard input, then the 2670 graph description is sent to standard output.) This switch is 2671 equivalent to -calltree=vcg. Default = no. 2672 2673 The VCG description as created is more complex than it need be. 2674 VCG allows graphs and nested subgraphs: each subroutine is cre- 2675 ated as a subgraph nested inside its calling routines. This 2676 allows you to interactively display subgraphs or summarise them. 2677 2678 The -vcg option for ftnchek was written by Dr. Philip Rubini of 2679 Cranfield University, UK. 2680 2681 xvcg is a graph visualisation tool which runs under the X win- 2682 dows system. It is freely available from ftp.cs.uni-sb.de. It 2683 was written by G. Sander of the University of Saarland, Germany. 2684 2685 See also: -calltree, -crossref, -reference, -sort. 2686 2687 2688 2689 -version 2690 This option causes ftnchek to print a line giving the version 2691 number, release date, and patch level of the program. If no 2692 files are given, it then exits. If files are given, the effect 2693 of this option is to include the patch level (normally omitted) 2694 in the version information printed at the start of processing. 2695 Default = no. 2696 2697 See also: -help. 2698 2699 2700 2701 -volatile 2702 Assume that COMMON blocks are volatile. Default = no. 2703 2704 This flag is superseded by -common=volatile, and should no 2705 longer be used. It may be eliminated in a future release of 2706 ftnchek. 2707 2708 See also: -common, -usage. 2709 2710 2711 2712 -wordsize=num 2713 Specifies the default word size to be num bytes. This is the 2714 size of logical and single-precision numeric variables that are 2715 not given explicit precisions. (Explicit precisions for non- 2716 character variables are an extension to the Fortran 77 Standard, 2717 and are given by type declarations such as REAL*8 X.) Double- 2718 precision and complex variables will be twice this value, and 2719 double complex variables four times. Quad-precision constants 2720 and intrinsic function results will be four times this value. 2721 Note that variables declared as REAL*16 will be regarded as quad 2722 precision only if the word size is 4 bytes. Default = turn-on = 2723 4 bytes. 2724 2725 The word size value does not matter for checking standard-con- 2726 forming programs that do not declare explicit precisions for 2727 non-character variables or store Hollerith data in variables. 2728 This setting also does not affect the default size of character 2729 variables, which is always 1 byte. Hollerith constants also are 2730 assumed to occupy 1 byte per character. 2731 2732 The word size is used to determine whether truncation occurs in 2733 assignment statements, and to catch precision mismatches in sub- 2734 program argument lists and common block lists. The exact warn- 2735 ings that are issued will depend on the status of other flags. 2736 Under both the -portability=mixed-size and the -nowordsize flag, 2737 any mixing of explicit with default precision objects (character 2738 expressions not included) is warned about. This applies to 2739 arithmetic expressions containing both types of objects, and to 2740 subprogram arguments and COMMON variables. Under control of the 2741 -truncation=demotion and promotion options, a warning is given 2742 for assignment of an expression to a shorter variable of the 2743 same type, or for promotion of a lower precision value to higher 2744 precision in an arithmetic expression or an assignment state- 2745 ment. 2746 2747 Giving a word size of 0, or equivalently, using -nowordsize 2748 means that no default value will be assumed. This is equivalent 2749 to specifying -portability=mixed-size. Use it to find cases of 2750 mixing default and explicit precision, for example to flag 2751 places where REAL*8 is treated as equivalent to DOUBLE PRECI- 2752 SION. 2753 2754 See also: -pointersize, -portability, -truncation. 2755 2756 2757 2758 -wrap=col 2759 Controls the wrapping of error messages. Long error messages 2760 that would run past the specified column will be broken up into 2761 separate lines between the words of the message for better read- 2762 ability. If turned off with -nowrap, each separate error mes- 2763 sage will be printed on one line, leaving it up to the display 2764 to wrap the message or truncate it. Default = turn-on = 79. 2765 2766 2767 2768CHANGING THE DEFAULTS 2769 ftnchek includes two mechanisms for changing the default values of all 2770 options: by defining environment variables or by creating a preferences 2771 file. When ftnchek starts up, it looks in its environment for any 2772 variables whose names are composed by prefixing the string FTNCHEK_ 2773 onto the uppercased version of the option name. If such a variable is 2774 found, its value is used to specify the default for the corresponding 2775 switch or setting. In the case of settings (for example, the -common 2776 strictness setting) the value of the environment variable is read as 2777 the default setting value. In the case of switches, the default switch 2778 will be taken as true or yes unless the environment variable has the 2779 value 0 or NO. 2780 2781 Note that the environment variable name must be constructed with the 2782 full-length option name, which must be in uppercase. For example, to 2783 make ftnchek print a source listing by default, set the environment 2784 variable FTNCHEK_LIST to 1 or YES or anything other than 0 or NO. The 2785 names FTNCHEK_LIS (not the full option name) or ftnchek_list (lower 2786 case) would not be recognized. 2787 2788 2789 Here are some examples of how to set environment variables on various 2790 systems. For simplicity, all the examples set the default -list switch 2791 to YES. 2792 2793 1. UNIX, Bourne shell: $ FTNCHEK_LIST=YES 2794 $ export FTNCHEK_LIST 2795 2796 2. UNIX, C shell: % setenv FTNCHEK_LIST YES 2797 2798 3. VAX/VMS: $ DEFINE FTNCHEK_LIST YES 2799 2800 4. MSDOS: $ SET FTNCHEK_LIST=YES 2801 2802 After processing any environment variables, ftnchek looks for a prefer- 2803 ences file containing options and settings. It will search in the fol- 2804 lowing order, using only the first file found: (1) .ftnchekrc in the 2805 current directory, (2) ftnchek.ini in the current directory, (3) 2806 .ftnchekrc in the user's home directory, (4) ftnchek.ini in the home 2807 directory. If such a file is found, the options defined in it are used 2808 as defaults in place of the built-in defaults and overriding any 2809 defaults set in the environment.. 2810 2811 Each option or setting in the preferences file must be on a separate 2812 line. They are given in the same form as on the command line, except 2813 without the initial dash. The preferences file can contain blank lines 2814 and comments. Comments are introduced at any point in a line by a 2815 space character (blank or tab) or the '#' character, and are terminated 2816 by the end of the line. 2817 2818 Command-line options override the defaults set in the environment or in 2819 the preferences file, in the same way as they override the built-in 2820 defaults. 2821 2822 2823 2824USING PROJECT FILES 2825 This section contains detailed information on how to use project files 2826 most effectively, and how to avoid some pitfalls. 2827 2828 One can divide the checks ftnchek does into two categories, local and 2829 global. Local checking is restricted to within a single routine, and 2830 catches things like uninitialized variables, unintended loss of preci- 2831 sion in arithmetic expressions, etc. This sort of checking can be done 2832 on each subprogram independently. Furthermore, local checking of a 2833 subprogram does not need to be repeated when some other subprogram is 2834 changed. Global checking catches things like calling a subroutine with 2835 the wrong argument types, or disagreeing in common block declarations. 2836 It requires looking at the whole set of subprograms interacting with 2837 each other. 2838 2839 The purpose of project files is to allow the local checking and global 2840 checking steps to be separated. Assuming that each subprogram is in 2841 its own source file, you can run ftnchek once on each one to do local 2842 checking while suppressing global checking. Then ftnchek can be run 2843 once on all the project files together to do the global checking. The 2844 sample makefile below shows how to automate this task. The ''.f.prj'' 2845 target updates a project file for a particular file any time the source 2846 file changes. The information needed for global checking is saved in 2847 the project file. The ''check'' target does the combined global check- 2848 ing. Typically ''make check'' would repeat the ''ftnchek -project'' 2849 step only on changed source files, then do the global check. This is 2850 obviously a big advantage for large programs, when many subprograms 2851 seldom if ever change. 2852 2853 It is best when using project files to place each subprogram in a sepa- 2854 rate source file. If each source file may contain more than one sub- 2855 program, it complicates the definition of ''local'' and ''global'' 2856 checking because there is some inter-module checking that is contained 2857 within a file. ftnchek tries to do the right thing in this case, but 2858 there are some complications (described below) due to the trade-off 2859 between avoiding re-doing cross-checks and preserving information about 2860 the program's structure. 2861 2862 Ordinarily, to do the least amount of re-checking, project files should 2863 be created with the -library flag in effect and trimming turned on. In 2864 this mode, the information saved in the project file consists of all 2865 subprogram declarations, all subprogram invocations not resolved by 2866 declarations in the same file, and one instance of each COMMON block 2867 declaration. This is the minimum amount of information needed to check 2868 agreement between files. 2869 2870 If the source file contains more than one routine, there are some pos- 2871 sible problems that can arise from creating the project file in library 2872 mode, because the calling hierarchy among routines defined within the 2873 file is lost. Also, if the routines in the file make use of COMMON 2874 blocks that are shared with routines in other files, there will not be 2875 enough information saved for the correct checking of set and used 2876 status of COMMON blocks and COMMON variables according to the -usage 2877 setting. Therefore if you plan to use project files when -usage check- 2878 ing is turned on (which is the default situation), and if multiple rou- 2879 tines in one project file share COMMON blocks with routines in other 2880 files, the project files should be created with the -library flag 2881 turned off. In this mode, ftnchek saves, besides the information 2882 listed above, one invocation of each subprogram by any other subprogram 2883 in the same file, and all COMMON block declarations. This means that 2884 the project file will be larger than necessary, and that when it is 2885 read in, ftnchek may repeat some inter-module checks that it already 2886 did when the project file was created. If each project file contains 2887 only one module, there is no loss of information in creating the 2888 project files in library mode. 2889 2890 Because of the possible loss of information entailed by creating a 2891 project file with the -library flag in effect, whenever that project 2892 file is read in later, it will be treated as a library file regardless 2893 of the current setting of the -library flag. On the other hand, a 2894 project file created with library mode turned off can be read in later 2895 in either mode. 2896 2897 The foregoing discussion assumes that the trimming options of the 2898 -project setting are turned on when the project file is created. This 2899 is the normal situation. The no-trim options of the -project setting 2900 are provided in case one wants to use the project files for purposes 2901 other than checking the program with ftnchek. For instance, one could 2902 write a Perl script to analyze the project files for information about 2903 how the different subprograms are called. You should not use the 2904 no-trim options to deal with the issues of information loss discussed 2905 above, since they cause more information than necessary to be stored. 2906 This makes the project files bigger and causes ftnchek to do more work 2907 later when it reads them to check your complete program. Ordinarily, 2908 you should use the -library option to control how much information to 2909 store for later use by ftnchek in checking your program. 2910 2911 2912 Here is an example of how to use the UNIX make utility to automatically 2913 create a new project file each time the corresponding source file is 2914 altered, and to check the set of files for consistency. Add these 2915 lines to your makefile. The example assumes that a macro OBJS has been 2916 defined which lists all the names of object files to be linked together 2917 to form the complete executable program. (In this makefile, the 2918 indented lines should each begin with a tab, not blanks.) If any 2919 source file contains multiple routines that share common blocks among 2920 themselves, then the no-com-\* option should be removed from NOGLOBAL, 2921 and/or drop the -library flag. 2922 2923 # tell make what a project file suffix is 2924 .SUFFIXES: .prj 2925 2926 # these options suppress global checks. 2927 NOGLOBAL=-usage=no-ext-undefined,no-com-\* 2928 2929 # tell make how to create a .prj file from a .f file 2930 .f.prj: 2931 ftnchek -project $(NOGLOBAL) -library $< 2932 2933 # set up macro PRJS containing project filenames 2934 PRJS= $(OBJS:.o=.prj) 2935 2936 # "make check" will check everything that has been changed. 2937 check: $(PRJS) 2938 ftnchek $(PRJS) 2939 2940 When a program uses many routines defined in a large number of differ- 2941 ent source files in different directories, it can be cumbersome to 2942 specify all the different project files needed to check the program 2943 properly. To deal with such cases, ftnchek allows project files to be 2944 concatenated into a single large file. This single file can then be 2945 given to ftnchek to provide the information for checking the use of any 2946 or all of the routines defined in the combined project files. When 2947 using such a ''library'' project file, you may want ftnchek's error 2948 reports to document precisely the name of the file where the specific 2949 function is defined. If the various source files are in several direc- 2950 tories, an error report that gives only the file name may be ambiguous, 2951 and rather should include the path to the file. The solution is to 2952 create each of the individual project files by giving the complete path 2953 to the source file. Then this complete path will appear in the error 2954 reports. For example, suppose that all of the library subprogram 2955 source files are in subdirectories of a directory named /util/lib. 2956 Then the individual project files could first be created by a command 2957 such as 2958 2959 find /util/lib -name '*.f' -exec ftnchek -project '{}' ';' 2960 (Possibly other options would be provided to ftnchek as discussed 2961 above. Also, this step could be handled instead by a revised makefile 2962 rule that would provide the complete source file path instead of just 2963 the local name when invoking ftnchek.) Next, concatenate all of these 2964 project files manually. 2965 2966 find /util/lib -name '*.prj' -exec cat '{}' ';' > ourlib.prj 2967 Then a program source file can be checked by using the command 2968 2969 ftnchek prog.f ... -lib ourlib.prj 2970 and an error message related to any library routine will include the 2971 full path to the routine's source file. 2972 2973 At present, there is no archive utility like ar to manage the contents 2974 of a concatenated project file like the one in the illustration above. 2975 If changes are made to one of the library routines, the only way to 2976 update the combined project file is to concatenate all the individual 2977 project files once again. Such a utility would be quite easy to write. 2978 Someone should do so and contribute it to the ftnchek effort. 2979 2980AN EXAMPLE 2981 The following simple Fortran program illustrates the messages given by 2982 ftnchek. The program is intended to accept an array of test scores and 2983 then compute the average for the series. 2984 2985 2986 C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO 2987 C DATE: MAY 8, 1989 2988 2989 C Variables: 2990 C SCORE -> an array of test scores 2991 C SUM -> sum of the test scores 2992 C COUNT -> counter of scores read in 2993 C I -> loop counter 2994 2995 REAL FUNCTION COMPAV(SCORE,COUNT) 2996 INTEGER SUM,COUNT,J,SCORE(5) 2997 2998 DO 30 I = 1,COUNT 2999 SUM = SUM + SCORE(I) 3000 30 CONTINUE 3001 COMPAV = SUM/COUNT 3002 END 3003 3004 3005 PROGRAM AVENUM 3006 C 3007 C MAIN PROGRAM 3008 C 3009 C AUTHOR: LOIS BIGBIE 3010 C DATE: MAY 15, 1990 3011 C 3012 C Variables: 3013 C MAXNOS -> maximum number of input values 3014 C NUMS -> an array of numbers 3015 C COUNT -> exact number of input values 3016 C AVG -> average returned by COMPAV 3017 C I -> loop counter 3018 C 3019 3020 PARAMETER(MAXNOS=5) 3021 INTEGER I, COUNT 3022 REAL NUMS(MAXNOS), AVG 3023 COUNT = 0 3024 DO 80 I = 1,MAXNOS 3025 READ (5,*,END=100) NUMS(I) 3026 COUNT = COUNT + 1 3027 80 CONTINUE 3028 100 AVG = COMPAV(NUMS, COUNT) 3029 END 3030 3031 The compiler gives no error messages when this program is compiled. 3032 Yet here is what happens when it is run: 3033 3034 3035 $ run average 3036 70 3037 90 3038 85 3039 <EOF> 3040 $ 3041 3042 What happened? Why didn't the program do anything? The following is 3043 the output from ftnchek when it is used to debug the above program: 3044 3045 3046 3047 3048 $ ftnchek -list -symtab average 3049 3050 FTNCHEK Version 3.3 November 2004 3051 3052 File average.f: 3053 3054 1 C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO 3055 2 C DATE: MAY 8, 1989 3056 3 3057 4 C Variables: 3058 5 C SCORE -> an array of test scores 3059 6 C SUM -> sum of the test scores 3060 7 C COUNT -> counter of scores read in 3061 8 C I -> loop counter 3062 9 3063 10 REAL FUNCTION COMPAV(SCORE,COUNT) 3064 11 INTEGER SUM,COUNT,J,SCORE(5) 3065 12 3066 13 DO 30 I = 1,COUNT 3067 14 SUM = SUM + SCORE(I) 3068 15 30 CONTINUE 3069 16 COMPAV = SUM/COUNT 3070 ^ 3071 Warning near line 16 col 20: integer quotient expr SUM/COUNT converted to 3072 real 3073 17 END 3074 3075 Module COMPAV: func: real 3076 3077 Variables: 3078 3079 Name Type Dims Name Type Dims Name Type Dims Name Type Dims 3080 COMPAV real COUNT intg I intg* J intg 3081 SCORE intg 1 SUM intg 3082 3083 * Variable not declared. Type has been implicitly defined. 3084 3085 3086 Warning in module COMPAV: Variables declared but never referenced: 3087 J declared at line 11 3088 3089 Warning in module COMPAV: Variables may be used before set: 3090 SUM used at line 14 3091 SUM set at line 14 3092 3093 3094 Statement labels defined: 3095 3096 Label Line StmtType 3097 <30> 15 exec 3098 3099 18 3100 19 3101 20 PROGRAM AVENUM 3102 21 C 3103 22 C MAIN PROGRAM 3104 23 C 3105 24 C AUTHOR: LOIS BIGBIE 3106 25 C DATE: MAY 15, 1990 3107 26 C 3108 27 C Variables: 3109 28 C MAXNOS -> maximum number of input values 3110 29 C NUMS -> an array of numbers 3111 30 C COUNT -> exact number of input values 3112 31 C AVG -> average returned by COMPAV 3113 32 C I -> loop counter 3114 33 C 3115 34 3116 35 PARAMETER(MAXNOS=5) 3117 36 INTEGER I, COUNT 3118 37 REAL NUMS(MAXNOS), AVG 3119 38 COUNT = 0 3120 39 DO 80 I = 1,MAXNOS 3121 40 READ (5,*,END=100) NUMS(I) 3122 41 COUNT = COUNT + 1 3123 42 80 CONTINUE 3124 43 100 AVG = COMPAV(NUMS, COUNT) 3125 44 END 3126 3127 Module AVENUM: prog 3128 3129 External subprograms referenced: 3130 3131 COMPAV: real* 3132 3133 Variables: 3134 3135 Name Type Dims Name Type Dims Name Type Dims Name Type Dims 3136 AVG real COUNT intg I intg MAXNOS intg* 3137 NUMS real 1 3138 3139 * Variable not declared. Type has been implicitly defined. 3140 3141 3142 Warning in module AVENUM: Variables set but never used: 3143 AVG set at line 43 3144 3145 I/O Operations: 3146 3147 Unit ID Unit No. Access Form Operation Line 3148 5 SEQ FMTD READ 40 3149 3150 Statement labels defined: 3151 3152 Label Line StmtType Label Line StmtType 3153 <80> 42 exec <100> 43 exec 3154 3155 3156 0 syntax errors detected in file average.f 3157 6 warnings issued in file average.f 3158 3159 Warning: Subprogram COMPAV argument data type mismatch at position 1: 3160 Dummy arg SCORE in module COMPAV line 10 file average.f is type intg 3161 Actual arg NUMS in module AVENUM line 43 file average.f is type real 3162 3163 According to ftnchek, the program contains variables which may be used 3164 before they are assigned an initial value, and variables which are not 3165 needed. ftnchek also warns the user that an integer quotient has been 3166 converted to a real. This may assist the user in catching an unintended 3167 roundoff error. Since the -symtab flag was given, ftnchek prints out a 3168 table containing identifiers from the local module and their corre- 3169 sponding datatype and number of dimensions. Finally, ftnchek warns 3170 that the function COMPAV is not used with the proper type of arguments. 3171 3172 With ftnchek's help, we can debug the program. We can see that there 3173 were the following errors: 3174 3175 1. SUM and COUNT should have been converted to real before doing the 3176 division. 3177 3178 2. SUM should have been initialized to 0 before entering the loop. 3179 3180 3. AVG was never printed out after being calculated. 3181 3182 4. NUMS should have been declared INTEGER instead of REAL. 3183 3184 We also see that I, not J, should have been declared INTEGER in func- 3185 tion COMPAV. Also, MAXNOS was not declared as INTEGER, nor COMPAV as 3186 REAL, in program AVENUM. These are not errors, but they may indicate 3187 carelessness. As it happened, the default type of these variables 3188 coincided with the intended type. 3189 3190 Here is the corrected program, and its output when run: 3191 3192 3193 C AUTHORS: MIKE MYERS AND LUCIA SPAGNUOLO 3194 C DATE: MAY 8, 1989 3195 C 3196 C Variables: 3197 C SCORE -> an array of test scores 3198 C SUM -> sum of the test scores 3199 C COUNT -> counter of scores read in 3200 C I -> loop counter 3201 C 3202 REAL FUNCTION COMPAV(SCORE,COUNT) 3203 INTEGER SUM,COUNT,I,SCORE(5) 3204 C 3205 SUM = 0 3206 DO 30 I = 1,COUNT 3207 SUM = SUM + SCORE(I) 3208 30 CONTINUE 3209 COMPAV = FLOAT(SUM)/FLOAT(COUNT) 3210 END 3211 C 3212 C 3213 PROGRAM AVENUM 3214 C 3215 C MAIN PROGRAM 3216 C 3217 C AUTHOR: LOIS BIGBIE 3218 C DATE: MAY 15, 1990 3219 C 3220 C Variables: 3221 C MAXNOS -> maximum number of input values 3222 C NUMS -> an array of numbers 3223 C COUNT -> exact number of input values 3224 C AVG -> average returned by COMPAV 3225 C I -> loop counter 3226 C 3227 C 3228 INTEGER MAXNOS 3229 PARAMETER(MAXNOS=5) 3230 INTEGER I, NUMS(MAXNOS), COUNT 3231 REAL AVG,COMPAV 3232 COUNT = 0 3233 DO 80 I = 1,MAXNOS 3234 READ (5,*,END=100) NUMS(I) 3235 COUNT = COUNT + 1 3236 80 CONTINUE 3237 100 AVG = COMPAV(NUMS, COUNT) 3238 WRITE(6,*) 'AVERAGE =',AVG 3239 END 3240 $ run average 3241 70 3242 90 3243 85 3244 <EOF> 3245 AVERAGE = 81.66666 3246 $ 3247 3248 With ftnchek's help, our program is a success! 3249 3250 3251INTERPRETING THE OUTPUT 3252 The messages given by ftnchek include not only syntax errors but also 3253 warnings and informational messages about things that are legal Fortran 3254 but that may indicate errors or carelessness. Most of these messages 3255 can be turned off by command-line options. Which option controls each 3256 message depends on the nature of the condition being warned about. See 3257 the descriptions of the command-line flags in the previous sections, 3258 and of individual messages below. Each message is prefixed with a word 3259 or phrase indicating the nature of the condition and its severity. 3260 3261 ''Error'' means a syntax error. The simplest kind of syntax errors are 3262 typographical errors, for example unbalanced parentheses or misspelling 3263 of a keyword. This type of error is caught by the parser and appears 3264 with the description ''parse error'' or ''syntax error'' (depending on 3265 the version of the parser generator and whether it is GNU bison or UNIX 3266 yacc). This type of error message cannot be suppressed. Be aware that 3267 this type of error often means that ftnchek has not properly inter- 3268 preted the statement where the error occurs, so that its subsequent 3269 checking operations will be compromised. You should eliminate all syn- 3270 tax errors before proceeding to interpret the other messages ftnchek 3271 gives. 3272 3273 ''Warning: Nonstandard syntax'' indicates an extension to Fortran that 3274 ftnchek supports but that is not according to the Fortran 77 Standard. 3275 The extensions that ftnchek accepts are described in the section on 3276 Extensions below. One example is the DO ... ENDDO construction. If a 3277 program uses these extensions, warnings will be given according to 3278 specifications under the -f77 setting. The default behavior is to give 3279 no warnings. 3280 3281 ''Warning'' in other cases means a condition that is suspicious but 3282 that may or may not be a programming error. Frequently these condi- 3283 tions are legal under the standard. Some are illegal but do not fall 3284 under the heading of syntax errors. Usage errors are one example. 3285 These refer to the possibility that a variable may be used before it 3286 has been assigned a value (generally an error), or that a variable is 3287 declared but never used (harmless but may indicate carelessness). The 3288 amount of checking for usage errors is controlled by the -usage flag, 3289 which specifies the maximum amount of checking by default. 3290 3291 Truncation warnings cover situations in which accuracy may be lost 3292 unintentionally, for example when a double precision value is assigned 3293 to a real variable. These warnings are controlled by the -truncation 3294 setting, which is on by default. 3295 3296 ''Nonportable usage'' warns about some feature that may not be accepted 3297 by some compilers even though it is not contrary to the Fortran 77 3298 Standard, or that may cause the program to perform differently on dif- 3299 ferent platforms. For example, equivalencing real and integer vari- 3300 ables is usually a non-portable practice. The use of extensions to the 3301 standard language is, of course, another source of non-portability, but 3302 this is handled as a separate case. To check a program for true porta- 3303 bility, both the -portability and the -f77 flags should be used. They 3304 are both turned off by default. The -wordsize setting is provided to 3305 check only those nonportable usages that depend on a particular machine 3306 wordsize. 3307 3308 ''Possibly misleading appearance'' is used for legal constructions that 3309 may not mean what they appear to mean at first glance. For example, 3310 Fortran is insensitive to blank space, so extraneous space within vari- 3311 able names or the lack of space between a keyword and a variable can 3312 convey the wrong impression to the reader. These messages can be sup- 3313 pressed by turning off the -pretty flag, which is on by default. 3314 3315 Other messages that are given after all the files are processed, and 3316 having to do with agreement between modules, do not use the word 3317 ''warning'' but generally fall into that category. Examples include 3318 type mismatches between corresponding variables in different COMMON 3319 block declarations, or between dummy and actual arguments of a subpro- 3320 gram. These warnings are controlled by the -common and -arguments set- 3321 tings respectively. By default both are set for maximum strictness of 3322 checking. 3323 3324 Another group of warnings about conditions that are often harmless 3325 refer to cases where the array properties of a variable passed as a 3326 subprogram argument differ between the two routines. For instance, an 3327 array element might be passed to a subroutine that expects a whole 3328 array. This is a commonly-used technique for processing single rows or 3329 columns of two-dimensional arrays. However, it could also indicate a 3330 programming error. The -array setting allows the user to adjust the 3331 degree of strictness to be used in checking this kind of agreement 3332 between actual and dummy array arguments. By default the strictness is 3333 maximum. 3334 3335 ''Oops'' indicates a technical problem, meaning either a bug in ftnchek 3336 or that its resources have been exceeded. 3337 3338 The syntax error messages and warnings include the filename along with 3339 the line number and column number. ftnchek has two different options 3340 for the appearance of these error messages. If -novice is in effect, 3341 which is the default, the messages are in a style approximating normal 3342 English. (In default style, the filename is not printed in messages 3343 within the body of the program if -list is in effect.) The other style 3344 of error messages is selected by the -nonovice option. In this style, 3345 the appearance of the messages is similar to that of the UNIX lint pro- 3346 gram. 3347 3348 ftnchek is still blind to some kinds of syntax errors. The two most 3349 important ones are detailed checking of FORMAT statements, and almost 3350 anything to do with control of execution flow by means of IF, DO, and 3351 GOTO statements: namely correct nesting of control structures, matching 3352 of opening statements such as IF ... THEN with closing statements such 3353 as ENDIF, and the proper use of statement labels (numbers). Most com- 3354 pilers will catch these errors. See the section on Limitations for a 3355 more detailed discussion. 3356 3357 If ftnchek gives you a syntax error message when the compiler does not, 3358 it may be because your program contains an extension to standard For- 3359 tran which is accepted by the compiler but not by ftnchek. (See the 3360 section on Extensions.) On a VAX/VMS system, you can use the compiler 3361 option /STANDARD to cause the compiler to accept only standard Fortran. 3362 On most UNIX or UNIX-like systems, this can be accomplished by setting 3363 the flag -ansi. 3364 3365 Many of the messages given by ftnchek are self-explanatory. Those that 3366 need some additional explanation are listed below in alphabetical 3367 order. 3368 3369 Common block NAME: data type mismatch at position n 3370 The n-th variable in the COMMON block differs in data type in 3371 two different declarations of the COMMON block. By default 3372 (-common strictness level 3), ftnchek is very picky about COMMON 3373 blocks: the variables listed in them must match exactly by data 3374 type and array dimensions. That is, the legal pair of declara- 3375 tions in different modules: 3376 COMMON /COM1/ A,B 3377 and 3378 COMMON /COM1/ A(2) 3379 will cause ftnchek to give warnings at strictness level 3. 3380 These two declarations are legal in Fortran since they both 3381 declare two real variables. At strictness level 1 or 2, no 3382 warning would be given in this example, but the warning would be 3383 given if there were a data type mismatch, for instance, if B 3384 were declared INTEGER. Controlled by -common setting. 3385 3386 3387 Common block NAME has long data type following short data type 3388 Some compilers require alignment of multi-byte items so that 3389 each item begins at an address that is a multiple of the item 3390 size. Thus if a short (e.g. single-precision real) item is fol- 3391 lowed by a long (e.g. double precision real) item, the latter 3392 may not be aligned correctly. Controlled by -portability=com- 3393 mon-alignment option. 3394 3395 3396 Common block NAME has mixed character and non-character variables 3397 The ANSI standard requires that if any variable in a COMMON 3398 block is of type CHARACTER, then all other variables in the same 3399 COMMON block must also be of type CHARACTER. Controlled by 3400 -f77=mixed-common option. 3401 3402 3403 Common block NAME: varying length 3404 For -common setting level 2, this message means that a COMMON 3405 block is declared to have different numbers of words in two dif- 3406 ferent subprograms. A word is the amount of storage occupied by 3407 one integer or real variable. For -common setting level 3, it 3408 means that the two declarations have different numbers of vari- 3409 ables, where an array of any size is considered one variable. 3410 This is not necessarily an error, but it may indicate that a 3411 variable is missing from one of the lists. Note that according 3412 to the Fortran 77 Standard, it is an error for named COMMON 3413 blocks (but not blank COMMON) to differ in number of words in 3414 declarations in different modules. Given for -common setting 2 3415 or 3. 3416 3417 3418 Error: Badly formed logical/relational operator or constant 3419 3420 Error: Badly formed real constant 3421 The syntax analyzer has found the start of one of the special 3422 words that begin and end with a period (e.g. .EQ.), or the start 3423 of a numeric constant, but did not succeed in finding a complete 3424 item of that kind. 3425 3426 3427 Error: cannot be adjustable size in module NAME 3428 A character variable cannot be declared with a size that is an 3429 asterisk in parentheses unless it is a dummy argument, a parame- 3430 ter, or the name of the function defined in the module. 3431 3432 3433 Error: cannot be declared in SAVE statement in module NAME 3434 Only local variables and common blocks can be declared in a SAVE 3435 statement. 3436 3437 3438 Error: No path to this statement 3439 ftnchek will detect statements which are ignored or by-passed 3440 because there is no foreseeable route to the statement. For 3441 example, an unnumbered statement (a statement without a state- 3442 ment label), occurring immediately after a GOTO statement, can- 3443 not possibly be executed. 3444 3445 3446 Error: Parse error 3447 This means that the parser, which analyzes the Fortran program 3448 into expressions, statements, etc., has been unable to find a 3449 valid interpretation for some portion of a statement in the pro- 3450 gram. If your compiler does not report a syntax error at the 3451 same place, the most common explanations are: (1) use of an 3452 extension to ANSI standard Fortran that is not recognized by 3453 ftnchek, or (2) the statement requires more lookahead than 3454 ftnchek uses (see section on Bugs). 3455 3456 NOTE: This message means that the affected statement is not 3457 interpreted. Therefore, it is possible that ftnchek's subse- 3458 quent processing will be in error, if it depends on any matters 3459 affected by this statement (type declarations, etc.). 3460 3461 3462 Error: Syntax error 3463 This is the same as ''Error: Parse error'' (see above). It is 3464 generated if your version of ftnchek was built using the UNIX 3465 yacc parser generator rather than GNU bison. 3466 3467 3468 Identifiers which are not unique in first six chars 3469 Warns that two identifiers which are longer than 6 characters do 3470 not differ in the first 6 characters. This is for portability: 3471 they may not be considered distinct by some compilers. Con- 3472 trolled by -sixchar option. 3473 3474 3475 Nonportable usage: argument precision may not be correct for intrinsic 3476 function 3477 The precision of an argument passed to an intrinsic function may 3478 be incorrect on some computers. Issued when a numeric variable 3479 declared with explicit precision (e.g. REAL*8 X) is passed to a 3480 specific intrinsic function (e.g. DSQRT(X)). Controlled by 3481 -portability=mixed-size and -wordsize. 3482 3483 3484 Nonportable usage: character constant/variable length exceeds 255 3485 Some compilers do not support character strings more than 255 3486 characters in length. Controlled by -portability=long-string. 3487 3488 3489 Nonportable usage: File contains tabs 3490 ftnchek expands tabs to be equivalent to spaces up to the next 3491 column which is a multiple of 8. Some compilers treat tabs dif- 3492 ferently, and also it is possible that files sent by electronic 3493 mail will have the tabs converted to blanks in some way. There- 3494 fore files containing tabs may not be compiled correctly after 3495 being transferred. ftnchek does not give this message if tabs 3496 only occur within comments or character constants. Controlled 3497 by -portability=tab. 3498 3499 3500 Nonportable usage: non-integer DO loop bounds 3501 This warning is only given when the DO index and bounds are non- 3502 integer. Use of non-integer quantities in a DO statement may 3503 cause unexpected errors, or different results on different 3504 machines, due to roundoff effects. Controlled by -portabil- 3505 ity=real-do. 3506 3507 3508 Possibly it is an array which was not declared 3509 This message is appended to warnings related to a function invo- 3510 cation or to an argument type mismatch, for which the possibil- 3511 ity exists that what appears to be a function is actually meant 3512 to be an array. If the programmer forgot to dimension an array, 3513 references to the array will be interpreted as function invoca- 3514 tions. This message will be suppressed if the name in question 3515 appears in an EXTERNAL or INTRINSIC statement. Controlled by 3516 the -novice option. 3517 3518 3519 Possibly misleading appearance: characters past 72 columns 3520 The program is being processed with the statement field width at 3521 its standard value of 72, and some nonblank characters have been 3522 found past column 72. In this case, ftnchek is not processing 3523 the characters past column 72, and is notifying the user that 3524 the statement may not have the meaning that it appears to have. 3525 These characters might be intended by the programmer to be sig- 3526 nificant, but they will be ignored by the compiler. Controlled 3527 by -pretty=long-line. 3528 3529 3530 Possibly misleading appearance: Common block declared in more than one 3531 statement 3532 Such multiple declarations are legal and have the same effect as 3533 a continuation of the original declaration of the block. This 3534 warning is only given if the two declarations are separated by 3535 one or more intervening statements. Controlled by -pretty=mul- 3536 tiple-common. 3537 3538 3539 Possibly misleading appearance: Continuation follows comment or blank 3540 line 3541 ftnchek issues this warning message to alert the user that a 3542 continuation of a statement is interspersed with comments, mak- 3543 ing it easy to overlook. Controlled by -pretty=continuation. 3544 3545 3546 Possibly misleading appearance: Extraneous parentheses 3547 Warns about parentheses surrounding a variable by itself in an 3548 expression. When a parenthesized variable is passed as an argu- 3549 ment to a subprogram, it is treated as an expression, not as a 3550 variable whose value can be modified by the called routine. 3551 Controlled by -pretty=parentheses. 3552 3553 3554 Subprogram NAME: argument data type mismatch at position n 3555 The subprogram's n-th actual argument (in the CALL or the usage 3556 of a function) differs in datatype or precision from the n-th 3557 dummy argument (in the SUBROUTINE or FUNCTION declaration). For 3558 instance, if the user defines a subprogram by 3559 SUBROUTINE SUBA(X) 3560 REAL X 3561 and elsewhere invokes SUBA by 3562 CALL SUBA(2) 3563 ftnchek will detect the error. The reason here is that the num- 3564 ber 2 is integer, not real. The user should have written 3565 CALL SUBA(2.0) 3566 3567 When checking an argument which is a subprogram, ftnchek must be 3568 able to determine whether it is a function or a subroutine. The 3569 rules used by ftnchek to do this are as follows: If the subpro- 3570 gram, besides being passed as an actual argument, is also 3571 invoked directly elsewhere in the same module, then its type is 3572 determined by that usage. If not, then if the name of the sub- 3573 program does not appear in an explicit type declaration, it is 3574 assumed to be a subroutine; if it is explicitly typed it is 3575 taken as a function. Therefore, subroutines passed as actual 3576 arguments need only be declared by an EXTERNAL statement in the 3577 calling module, whereas functions must also be explicitly typed 3578 in order to avoid generating this error message. Controlled by 3579 -arguments setting. 3580 3581 3582 Subprogram NAME: argument arrayness mismatch at position n 3583 Similar to the preceding situation, but the subprogram dummy 3584 argument differs from the corresponding actual argument in its 3585 number of dimensions or number of elements. Controlled by 3586 -array together with -arguments settings. 3587 3588 3589 Subprogram NAME: argument mismatch at position n 3590 A character dummy argument is larger than the corresponding 3591 actual argument, or a Hollerith dummy argument is larger than 3592 the corresponding actual argument. Controlled by -arguments 3593 setting. 3594 3595 3596 Subprogram NAME: argument usage mismatch 3597 ftnchek detects a possible conflict between the way a subprogram 3598 uses an argument and the way in which the argument is supplied 3599 to the subprogram. The conflict can be one of two types, as 3600 outlined below. 3601 3602 3603 Dummy arg is modified, Actual arg is const or expr 3604 A dummy argument is an argument as named in a SUBROUTINE or 3605 FUNCTION statement and used within the subprogram. An actual 3606 argument is an argument as passed to a subroutine or function by 3607 the caller. ftnchek is saying that a dummy argument is modified 3608 by the subprogram, implying that its value is changed in the 3609 calling module. The corresponding actual argument should not be 3610 a constant or expression, but rather a variable or array element 3611 which can be legitimately assigned to. Controlled by the 3612 -usage=arg-const-modified option. 3613 3614 3615 Dummy arg used before set, Actual arg not set 3616 Here a dummy argument may be used in the subprogram before hav- 3617 ing a value assigned to it by the subprogram. The corresponding 3618 actual argument should have a value assigned to it by the caller 3619 prior to invoking the subprogram. Controlled by the 3620 -usage=var-uninitialized option. 3621 3622 This warning is not affected by the -arguments setting. 3623 3624 3625 Subprogram NAME invoked inconsistently 3626 Here the mismatch is between the datatype of the subprogram 3627 itself as used and as defined. For instance, if the user 3628 declares 3629 INTEGER FUNCTION COUNT(A) 3630 and invokes COUNT in another module as 3631 N = COUNT(A) 3632 without declaring its datatype, it will default to real type, 3633 based on the first letter of its name. The calling module 3634 should have included the declaration 3635 INTEGER COUNT 3636 3637 Given for -arguments setting 2 or 3. 3638 3639 3640 Subprogram NAME: varying length argument lists: 3641 An inconsistency has been found between the number of dummy 3642 arguments (parameters) a subprogram has and the number of actual 3643 arguments given it in an invocation. ftnchek keeps track of all 3644 invocations of subprograms (CALL statements and expressions 3645 using functions) and compares them with the definitions of the 3646 subprograms elsewhere in the source code. The Fortran compiler 3647 normally does not catch this type of error. Given for -argu- 3648 ments setting 1 or 3. 3649 3650 3651 Variable not declared. Type has been implicitly defined 3652 When printing the symbol table for a module, ftnchek will flag 3653 with an asterisk all identifiers that are not explicitly typed 3654 and will show the datatype that was assigned through implicit 3655 typing. This provides support for users who wish to declare all 3656 variables as is required in Pascal or some other languages. 3657 This message appears only when the -symtab option is in effect. 3658 Alternatively, use the -declare flag if you want to get a list 3659 of all undeclared variables. 3660 3661 3662 Variables declared but never referenced 3663 Detects any identifiers that were declared in your program but 3664 were never used, either to be assigned a value or to have their 3665 value accessed. Variables in COMMON are excluded. Controlled 3666 by the -usage=var-unused option. 3667 3668 3669 Variables set but never used 3670 ftnchek will notify the user when a variable has been assigned a 3671 value, but the variable is not otherwise used in the program. 3672 Usually this results from an oversight. Controlled by the 3673 -usage=var-set-unused option. 3674 3675 3676 Variables used before set 3677 This message indicates that an identifier is used to compute a 3678 value prior to its initialization. Such usage may lead to an 3679 incorrect value being computed, since its initial value is not 3680 controlled. Controlled by the -usage=var-uninitialized option. 3681 3682 3683 Variables may be used before set 3684 Similar to used before set except that ftnchek is not able to 3685 determine its status with certainty. ftnchek assumes a variable 3686 may be used before set if the first usage of the variable occurs 3687 prior in the program text to its assignment. Controlled by the 3688 -usage=var-uninitialized option. 3689 3690 3691 Warning: DO index is not integer 3692 This warning is only given when the DO bounds are integer, but 3693 the DO index is not. It may indicate a failure to declare the 3694 index to be an integer. Controlled by -truncation=real-do 3695 option. 3696 3697 3698 Warning: integer quotient expr ... converted to real 3699 The quotient of two integers results in an integer type result, 3700 in which the fractional part is dropped. If such an integer 3701 expression involving division is later converted to a real 3702 datatype, it may be that a real type division had been intended. 3703 Controlled by -truncation=int-div-real option. 3704 3705 3706 Warning: Integer quotient expr ... used in exponent 3707 The quotient of two integers results in an integer type result, 3708 in which the fractional part is dropped. If such an integer 3709 expression is used as an exponent, it is quite likely that a 3710 real type division was intended. Controlled by -trunca- 3711 tion=int-div-exponent option. 3712 3713 3714 Warning: NAME not set when RETURN encountered 3715 The way that functions in Fortran return a value is by assigning 3716 the value to the name of the function. This message indicates 3717 that the function was not assigned a value before the point 3718 where a RETURN statement was found. Therefore it is possible 3719 that the function could return an undefined value. 3720 3721 3722 Warning: Nonstandard syntax: adjustable size cannot be concatenated 3723 here 3724 The Fortran 77 Standard (sec. 6.2.2) forbids concatenating char- 3725 acter variables whose size is an asterisk in parentheses, except 3726 in an assignment statement. Controlled by -f77=mixed-expr. 3727 3728 3729 Warning: Nonstandard syntax : significant characters past 72 columns 3730 This warning is given under the -f77=long-line setting if the 3731 -columns setting has been used to increase the statement field 3732 width, and a statement has meaningful program text beyond column 3733 72. Standard Fortran ignores all text in those columns, but 3734 some compilers do not. Thus the program may be treated differ- 3735 ently by different compilers. 3736 3737 3738 Warning: Nonstandard syntax : Statement out of order. 3739 ftnchek will detect statements that are out of the sequence 3740 specified for ANSI standard Fortran 77. Table 1 illustrates the 3741 allowed sequence of statements in the Fortran language. State- 3742 ments which are out of order are nonetheless interpreted by 3743 ftnchek, to prevent ''cascades'' of error messages. The 3744 sequence counter is also rolled back to prevent repetition of 3745 the error message for a block of similar statements. Controlled 3746 by the -f77=statement-order option. 3747 3748 3749 -------------------------------------------------------- 3750 | | implicit 3751 | parameter |--------------------- 3752 | | other specification 3753 format |---------------|--------------------- 3754 and | | statement-function 3755 entry | data |--------------------- 3756 | | executable 3757 -------------------------------------------------------- 3758 3759 Table 1 3760 3761 3762 Warning: Possible division by zero 3763 This message is printed out wherever division is done (except 3764 division by a constant). Use it to help locate a runtime divi- 3765 sion by zero problem. Controlled by -division option. 3766 3767 3768 Warning: real truncated to intg 3769 ftnchek has detected an assignment statement which has a real 3770 expression on the right, but an integer variable on the left. 3771 The fractional part of the real value will be lost. If you 3772 explicitly convert the real expression to integer using the INT 3773 or NINT intrinsic function, no warning will be printed. A simi- 3774 lar message is printed if a double precision expression is 3775 assigned to a single precision variable, etc. Controlled by 3776 -truncation=demotion option. 3777 3778 3779 Warning: subscript is not integer 3780 Since array subscripts are normally integer quantities, the use 3781 of a non-integer expression here may signal an error. Con- 3782 trolled by -truncation=real-subscript option. 3783 3784 3785 Warning: Unknown intrinsic function 3786 This message warns the user that a name declared in an INTRINSIC 3787 statement is unknown to ftnchek. Probably it is a nonstandard 3788 intrinsic function, and so the program will not be portable. 3789 The function will be treated by ftnchek as a user-defined func- 3790 tion. This warning is not suppressed by any option, since it 3791 affects ftnchek's analysis of the program. However, if the 3792 intrinsic function is in one of the supported sets of nonstan- 3793 dard intrinsics, you can use the -intrinsic setting to cause 3794 ftnchek to recognize it. 3795 3796 3797LIMITATIONS AND EXTENSIONS 3798 ftnchek accepts ANSI standard Fortran-77 programs with some minor limi- 3799 tations and numerous common extensions. 3800 3801 Limitations: 3802 The dummy arguments in statement functions are treated like 3803 ordinary variables of the program. That is, their scope is the 3804 entire subprogram, not just the statement function definition. 3805 3806 The checking of FORMAT statements is lax, tolerating missing 3807 separators (comma, etc.) between format descriptors in places 3808 where the Standard requires them, and allowing .d fields on 3809 descriptors that should not have them. It does warn under 3810 -f77=format-edit-descr about nonstandard descriptor types (like 3811 O), and supported extensions. 3812 3813 There are some syntactic extensions and Fortran 90 elements that 3814 ftnchek accepts but does very little checking. For instance, 3815 pointer usage (whether the nonstandard Cray syntax or the For- 3816 tran 90 syntax) is not checked other than for set and used sta- 3817 tus. It is hoped that some day more thorough checking will be 3818 implemented, but for now the user should regard the acceptance 3819 of these syntactic features simply as a convenience to enable 3820 checking of other aspects of code that contains them. See the 3821 section Extensions for specifics about what features are 3822 accepted but not fully checked. 3823 3824 If a user-supplied subprogram has the same name as one of the 3825 nonstandard intrinsic functions recognized by ftnchek, it must 3826 be declared in an EXTERNAL statement in any routine that invokes 3827 it. Otherwise it will be subject to the checking normally given 3828 to the intrinsic function. Since the nonstandard intrinsics are 3829 not standard, this EXTERNAL statement is not required by the 3830 Fortran 77 Standard. Using the -intrinsic=none setting, recog- 3831 nition of most nonstandard intrinsics (excepting only those 3832 needed to support the double complex data type) can be turned 3833 off. See the lists of supported nonstandard intrinsic functions 3834 under the discussion of the -intrinsic setting above. 3835 3836 Extensions: 3837 All of these extensions (except lower-case characters) will gen- 3838 erate warnings if the relevant -f77 option is set. Some of the 3839 extensions listed below are part of the Fortran-90 Standard. 3840 These are indicated by the notation (F90). 3841 3842 Tabs are permitted, and translated into equivalent blanks which 3843 correspond to tab stops every 8 columns. The standard does not 3844 recognize tabs. Note that some compilers allow tabs, but treat 3845 them differently. The treatment defined for DEC FORTRAN can be 3846 achieved using the -source=dec-tab setting. 3847 3848 Strings may be delimited by either quote marks or apostrophes. 3849 A sequence of two delimiter characters is interpreted as a sin- 3850 gle embedded delimiter character. (F90) 3851 3852 Strings may contain UNIX-style backslash escape sequences. They 3853 will be interpreted as such if the -source=unix-backslash set- 3854 ting is given. Otherwise the backslash character will be 3855 treated as a normal printing character. 3856 3857 Source code can be in either Fortran 90 free format or tradi- 3858 tional fixed format. (F90) 3859 3860 A semicolon is allowed as a statement separator. (F90) 3861 3862 Lower case characters are permitted, and are converted inter- 3863 nally to uppercase except in character strings. The standard 3864 specifies upper case only, except in comments and strings. 3865 (F90) 3866 3867 Hollerith constants are permitted, in accordance with the For- 3868 tran 77 Standard, appendix C. They should not be used in 3869 expressions, or confused with datatype CHARACTER. 3870 3871 The letter 'D' (upper or lower case) in column 1 is treated as 3872 the beginning of a comment. There is no option to treat such 3873 lines as statements instead of comments. 3874 3875 Statements may be longer than 72 columns provided that the set- 3876 ting -columns was used to increase the limit. According to the 3877 standard, all text from columns 73 through 80 is ignored, and no 3878 line may be longer than 80 columns. 3879 3880 Variable names may be longer than six characters. The standard 3881 specifies six as the maximum. ftnchek permits names up to 31 3882 characters long (F90). 3883 3884 Variable names may contain underscores and dollar signs (or 3885 other non-alphabetic characters as specified by the -identi- 3886 fier-chars option). These characters are are treated the same 3887 as alphabetic letters. The default type for variables beginning 3888 with these characters is REAL. In IMPLICIT type statements 3889 specifying a range of characters, the dollar sign follows Z and 3890 is followed by underscore. (Any other user-defined characters 3891 are treated the same as the dollar sign.) Fortran 90 permits 3892 underscores in variable names. 3893 3894 The UNIX version tolerates the presence of preprocessor direc- 3895 tives, namely lines beginning with the pound sign (#). These 3896 are treated as comments, except for #line directives, which are 3897 interpreted, and are used to set the line number and source file 3898 name for warnings and error messages. Note that #include direc- 3899 tives are not processed by ftnchek. Programs that use them for 3900 including source files should be passed through the preprocessor 3901 before being input to ftnchek. As noted below, ftnchek does 3902 process INCLUDE statements, which have a different syntax. An 3903 optional program, ftnpp(1L) (available separately) provides 3904 preprocessing that properly handles INCLUDE files. 3905 3906 The Fortran 90 DO ... ENDDO control structure is permitted. 3907 The CYCLE and EXIT statements are accepted. All of these may 3908 have an optional do-construct name, but construct names are not 3909 checked for consistency. (F90) 3910 3911 The Fortran 90 SELECT CASE construct is accepted. (F90) 3912 3913 Construct names are also accepted on IF, THEN, ELSE, ENDIF and 3914 SELECT CASE statements. (F90) 3915 3916 The ACCEPT and TYPE statements (for terminal I/O) are permitted, 3917 with the same syntax as PRINT. 3918 3919 The so-called ''Cray pointer'' syntax is tolerated. It is not 3920 the same as the Fortran 90 POINTER statement. There is no real 3921 checking of the statement other than basic syntax. The form of 3922 this statement is 3923 POINTER (pointer, pointee) [,(pointer, pointee)] 3924 The pointer variables are assigned a data type of INTEGER *4. 3925 Usage checking of the pointee variables is suppressed, since in 3926 practice they are accessed indirectly via the pointers. 3927 3928 The following Fortran 90 pointer related syntaxes are accepted: 3929 ALLOCATABLE, POINTER, and TARGET statements and the same 3930 attributes in type declarations; ALLOCATE, DEALLOCATE, and NUL- 3931 LIFY executable statements; pointer assignment using => opera- 3932 tor; and the intrinsic functions ALLOCATED and ASSOCIATED. Lit- 3933 tle semantic checking of pointer variables and operations is 3934 done beyond basic set and used status. For instance, there is 3935 no checking for such errors as dangling pointers, or use of 3936 unallocated arrays. 3937 3938 Statements may have any number of continuation lines. The For- 3939 tran 77 and Fortran 90 standards allow a maximum of 19 in fixed 3940 source form. The Fortran 90 standard allows a maximum of 39 in 3941 free source form. 3942 3943 Relational (comparison) operators composed of punctuation, 3944 namely: < <= == /= > >= are allowed. (F90) 3945 3946 Inline comments, beginning with an exclamation mark, are permit- 3947 ted. (F90) 3948 3949 NAMELIST I/O is supported. The syntax is the same as in Fortran 3950 90. 3951 3952 FORMAT statements can contain a dollar sign to indicate suppres- 3953 sion of carriage-return. An integer expression enclosed in 3954 angle brackets can be used anywhere in a FORMAT statement where 3955 the Fortran 77 Standard allows an integer constant (except for 3956 the length of a Hollerith constant), to provide a run-time value 3957 for a repeat specification or field width. 3958 3959 Nonstandard keywords are allowed in I/O statements, correspond- 3960 ing to those in VMS Fortran. 3961 3962 The IMPLICIT NONE statement is supported. The meaning of this 3963 statement is that all variables must have their data types 3964 explicitly declared. Rather than flag the occurrences of such 3965 variables with syntax error messages, ftnchek waits till the end 3966 of the module, and then prints out a list of all undeclared 3967 variables, as it does for the -declare option. (F90) 3968 3969 Data types INTEGER, REAL, COMPLEX, and LOGICAL are allowed to 3970 have an optional precision specification in type declarations. 3971 For instance, REAL*8 means an 8-byte floating point data type. 3972 The REAL*8 datatype is not necessarily considered equivalent to 3973 DOUBLE PRECISION, depending on the -wordsize setting. The For- 3974 tran 77 Standard allows a length specification only for CHARAC- 3975 TER data. 3976 3977 ftnchek supports the DOUBLE COMPLEX type specification for a 3978 complex quantity whose real and imaginary parts are double pre- 3979 cision. Mixed-mode arithmetic involving single-precision com- 3980 plex with double-precision real data, prohibited under the Stan- 3981 dard, yields a double complex result. 3982 3983 Combined type declarations and data-statement-like initializers 3984 are accepted. These have the form of a standard Fortran 77 type 3985 declaration, followed by a slash-delimited list of constants 3986 like that used in a DATA statement. An example of the syntax is 3987 INTEGER N / 100 / 3988 This bastard form of initializing declaration was not adopted in 3989 Fortran 90. Such declarations should be written using the stan- 3990 dard form described below, which is accepted by ftnchek. 3991 3992 There is limited support for Fortran 90 attribute-based type 3993 declarations. This style of declaration is distinguished by the 3994 use of a double colon (::) between the list of attributes and 3995 the list of declared variables. The features supported may be 3996 adequate for novice programmers, but are not yet sufficient for 3997 professional-quality Fortran 90 programs. I hope to add support 3998 for more features in future releases. I invite volunteers to 3999 assist in this task. See the ToDo file in the source code dis- 4000 tribution for details. The attributes currently accepted, 4001 besides all the usual data types, are DIMENSION, EXTERNAL, 4002 INTRINSIC, PARAMETER, and SAVE. The new form of declaration 4003 also allows assignment of values to the variables declared. At 4004 present, the (LEN=value) form of specifying character lengths is 4005 also accepted. Kind specifications, using (KIND=value) are 4006 parsed but are not processed: all kinds are treated as default 4007 kind. Also, there is little checking of these declarations 4008 beyond basic syntax. 4009 4010 Many commonly found nonstandard intrinsic functions are pro- 4011 vided. See the discussion of -intrinsic for a list of functions 4012 and how to control which ones are recognized. 4013 4014 Argument checking is not tight for those nonstandard intrinsics 4015 that take arrays or mixed argument types. 4016 4017 ftnchek permits the INCLUDE statement, which causes inclusion of 4018 the text of the given file. The syntax is 4019 INCLUDE 'filename' 4020 This is compatible with Fortran 90. If the -source=vms-include 4021 option is given, ftnchek follows VMS conventions with respect to 4022 this statement: it assumes a default extension of .for if no 4023 filename extension is given, and allows the qualifier /[NO]LIST 4024 following the filename, to control the listing of the included 4025 file. There is no support for including VMS text modules. 4026 4027 In diagnostic output relating to items contained in include 4028 files, the location of the error is specified by both its loca- 4029 tion in the include file and the location in the parent file 4030 where the file was included. 4031 4032 ftnchek accepts PARAMETER statements which lack parentheses. 4033 These will be warned about if the -f77=param-noparen flag is 4034 given. 4035 4036 ftnchek accepts PARAMETER definitions that involve intrinsic 4037 functions and exponentiation by a non-integer exponent. Both of 4038 these cases are prohibited by the Fortran 77 Standard, and will 4039 be warned about if the -f77=param-intrinsic flag is given. If 4040 an intrinsic function value is a compile-time integer constant, 4041 ftnchek will evaluate it. This allows better checking if the 4042 parameter is used in declaring array sizes. Fortran 90 allows 4043 intrinsic functions in PARAMETER definitions. 4044 4045 The intrinsic functions that are evaluated are: 4046 4047 ABS IABS DIM IDIM MAX 4048 MAX0 MIN MIN0 MOD SIGN 4049 ISIGN LEN ICHAR INDEX 4050 4051 The functions of integer arguments are evaluated only if the 4052 arguments are integer constant expressions. (These may involve 4053 integer constants, parameters, and evaluated intrinsic func- 4054 tions.) The function LEN is evaluated if its argument is an 4055 expression involving only character constants and variables 4056 whose length is not adjustable. The functions ICHAR and INDEX 4057 are evaluated only if the arguments are character constants. 4058 ftnchek gives a warning if it needs the value of some intrinsic 4059 function that is not evaluated. 4060 4061 4062NEW FEATURES 4063 Here are the changes from Version 3.2 to Version 3.3: 4064 4065 1. Front-end has been rewritten for unlimited lookahead, eliminating 4066 the longstanding bug that caused incorrect interpretation of state- 4067 ments whose ambiguity was not resolved in the first line. 4068 4069 2. The -mkhtml option is now available in the MS-DOS version. 4070 4071 3. Added support for Fortran 90 pointer related syntax: ALLOCATE, 4072 DEALLOCATE, and NULLIFY statements; the ALLOCATABLE, POINTER and 4073 TARGET attributes in type declarations; the pointer assigment oper- 4074 ator => and intrinsic functions ALLOCATED and ASSOCIATED; and 4075 deferred-shape array declarations. At present these new syntax 4076 features are accepted but not properly checked. This feature was 4077 added by Robert Landrito. 4078 4079 4. The -f77 and -f90 pointer option controlling warnings about ''Cray 4080 pointers'' has been renamed to cray-pointer. The -f77=pointer 4081 option now instead controls warnings for code containing Fortran 90 4082 pointer-related syntax. 4083 4084 5. Re-implemented -mkhtml processing so it is now much faster on 4085 source files containing many routines. 4086 4087 6. Changed the arrangement of the test directory so there is no longer 4088 any need to modify the distribution in order to run the test suite 4089 (check.bat) under MS-DOS. 4090 4091 7. Fixed bug in reading numeric settings on command line when setting 4092 name abbreviated to 3 characters. 4093 4094 8. Fixed bug causing spurious warning for a GOTO referring to a 4095 labeled END statement when the statement before END was a FORMAT. 4096 4097 9. New flag -f77=character to control warnings about extensions to the 4098 Fortran 77 character data type. Accompanying this new flag is sup- 4099 port for Fortran 90 rules for character variable declarations that 4100 evaluate to zero or negative length, allowing them and treating 4101 negative length values as zero. 4102 4103 10. Fixed minor bug in printing of comments and blank lines following 4104 last END statement in -list mode. 4105 4106 4107BUGS 4108 ftnchek still has much room for improvement. Your feedback is appreci- 4109 ated. We want to know about any bugs you notice. Bugs include not 4110 only cases in which ftnchek issues an error message where no error 4111 exists, but also if ftnchek fails to issue a warning when it ought to. 4112 Note, however, that ftnchek is not intended to catch all syntax errors 4113 (see section on Limitations). Also, it is not considered a bug for a 4114 variable to be reported as used before set, if the reason is that the 4115 usage of the variable occurs prior in the text to where the variable is 4116 set. For instance, this could occur when a GOTO causes execution to 4117 loop backward to some previously skipped statements. ftnchek does not 4118 analyze the program flow, but assumes that statements occurring earlier 4119 in the text are executed before the following ones. 4120 4121 We especially want to know if ftnchek crashes for any reason. It is 4122 not supposed to crash, even on programs with syntax errors. Sugges- 4123 tions are welcomed for additional features which you would find useful. 4124 Tell us if any of ftnchek's messages are incomprehensible. Comments on 4125 the readability and accuracy of this document are also welcome. 4126 4127 You may also suggest support for additional extensions to the Fortran 4128 language. These will be included only if it is felt that the exten- 4129 sions are sufficiently widely accepted by compilers. 4130 4131 If you find a bug in ftnchek, first consult the list of known bugs 4132 below to see if it has already been reported. Also check the section 4133 entitled ''Limitations and Extensions'' above for restrictions that 4134 could be causing the problem. If you do not find the problem docu- 4135 mented in either place, then send a report including 4136 4137 1. The operating system and CPU type on which ftnchek is running. 4138 4139 2. The version of ftnchek and values of any environment options or 4140 settings defined in startup file. (Capturing the output of ftnchek 4141 -help is useful for this.) 4142 4143 3. A brief description of the bug. 4144 4145 4. If possible, a small sample program showing the bug. 4146 4147 The report should be sent to Dr. Robert Moniot (see contact information 4148 in section entitled ''Installation and Support''). 4149 4150 Highest priority will be given to bugs which cause ftnchek to crash. 4151 4152 Certain problems that arise when checking large programs can be fixed 4153 by increasing the sizes of the data areas in ftnchek. (These problems 4154 are generally signaled by error messages beginning with ''Oops''.) The 4155 simplest way to increase the table sizes is by recompiling ftnchek with 4156 the LARGE_MACHINE macro name defined. Consult the makefile and README 4157 file for the method of doing this. 4158 4159 The following is a list of known bugs. 4160 4161 1. Bug: Used-before-set message is suppressed for any variable which 4162 is used as the loop index in an implied-do loop, even if it was in 4163 fact used before being set in some earlier statement. For example, 4164 consider J in the statement 4165 4166 WRITE(5,*) (A(J), J=1,10) 4167 4168 Here ftnchek parses the I/O expression, A(J), where J is used, 4169 before it parses the implied loop where J is set. Normally this 4170 would cause ftnchek to report a spurious used-before-set warning 4171 for J. Since this report is usually in error and occurs fairly 4172 commonly, ftnchek suppresses the warning for J altogether. 4173 4174 Prognosis: A future version of ftnchek is planned which will han- 4175 dle implied-do loops correctly. 4176 4177 2. Bug: Variables used (not as arguments) in statement-function sub- 4178 programs do not have their usage status updated when the statement 4179 function is invoked. 4180 4181 Prognosis: To be fixed in a future version of ftnchek. 4182 4183 3. Bug: VAX version does not expand wildcards in filenames on the com- 4184 mand line if they are followed without space by an option, e.g. 4185 ftnchek *.f/calltree would not expand the *.f. This is because 4186 VMS-style options without intervening space are not supported by 4187 the GNU shell_mung routine that is used to expand wildcards. 4188 4189 Prognosis: unlikely to be fixed. 4190 4191 4. Bug: checking for nonstandard format edit descriptors is done only 4192 in FORMAT statements, not in character strings used as formats. 4193 4194 Prognosis: may be fixed someday. 4195 4196 4197ACKNOWLEDGEMENTS 4198 ftnchek was designed by Dr. Robert Moniot, professor at Fordham Univer- 4199 sity. During the academic year of 1988-1989, Michael Myers and Lucia 4200 Spagnuolo developed the program to perform the variable usage checks. 4201 During the following year it was augmented by Lois Bigbie to check sub- 4202 program arguments and COMMON block declarations. Brian Downing 4203 assisted with the implementation of the INCLUDE statement. John Quinn 4204 wrote the common block usage checks. Heba Elsayed wrote the label ta- 4205 ble printout and label usage checks. Nelson H. F. Beebe of the Univer- 4206 sity of Utah added most of the new code to implement the -makedcls fea- 4207 ture and wrote the dcl2inc script. The -mkhtml feature was contributed 4208 by Mark McVeigh of Framatome ANP, Inc. The -reference feature was con- 4209 tributed by Gerome Emmanuel, Ecole des mines, U. Nancy (slightly modi- 4210 fied). The -vcg option was contributed by Dr. Philip Rubini of Cran- 4211 field University, UK. The support for Cray pointer syntax was provided 4212 by John Dannenhoffer of United Technologies Research Center. John C. 4213 Bollinger of Indiana University added the parser syntax for the SELECT 4214 CASE construct. Robert Landrito added the parser syntax for F90 4215 pointer-related features. Additional features will be added as time 4216 permits. As of Version 2.5, the name was changed from forchek to 4217 ftnchek, to avoid confusion with a similar program named forcheck, 4218 developed earlier at Leiden University. 4219 4220 We would like to thank John Amor of the University of British Columbia, 4221 Reg Clemens of the Air Force Phillips Lab in Albuquerque, Markus 4222 Draxler of the University of Stuttgart, Victor Eijkhout of the Univer- 4223 sity of Tennessee at Knoxville, Greg Flint of Purdue University, Daniel 4224 P. Giesy of NASA Langley Research Center, Fritz Keinert of Iowa State 4225 University, Judah Milgram of the University of Maryland College Park, 4226 Hugh Nicholas of the Pittsburgh Supercomputing Center, Dan Severance of 4227 Yale University, Phil Sterne of Lawrence Livermore National Laboratory, 4228 Larry Weissman of the University of Washington, Warren J. Wiscombe of 4229 NASA Goddard, and Nelson H. F. Beebe of the University of Utah, for 4230 pointing out bugs and suggesting some improvements. Stefan A. 4231 Deutscher, Gunnar Duus, Clive Page of the University of Leicester, 4232 Stephan Wefing of Heidelberg University, and Bob Wells of Oxford Uni- 4233 versity were extremely helpful as alpha testers. We also thank Jack 4234 Dongarra for putting ftnchek into the netlib library of publicly avail- 4235 able software. 4236 4237INSTALLATION AND SUPPORT 4238 The ftnchek program is free software. It can be obtained by anonymous 4239 ftp from many software servers, including ftp://netlib.org/fortran . 4240 Note that on Netlib the distribution is named ftnchek.tar.gz whereas on 4241 most other servers the file name includes the version number, e.g. 4242 ftnchek-3.3.0.tar.gz. If the file extension is .Z, uncompress with the 4243 Unix uncompress(1) utility. If the file extension is .gz, uncompress 4244 with the GNU gunzip(1L) program. Then use tar(1) to unpack the files 4245 into a subdirectory. 4246 4247 Installation requires a C compiler for your computer. See the INSTALL 4248 file provided with the distribution for instructions on installing 4249 ftnchek on your system. Executable binary for particular systems such 4250 as IBM PC or Macintosh, as available, can be obtained by anonymous ftp 4251 from ftp://ftp.dsm.fordham.edu/pub/ftnchek . Assistance in preparing 4252 such executable binary forms is welcome. 4253 4254 4255 The nroff version of this document is named ftnchek.man. On UNIX sys- 4256 tems, this file can be used as the man page, but actually it is a 4257 multi-purpose source file which is used to produce the other forms of 4258 the documentation. The cleaned-up man page document, created during 4259 installation of ftnchek, is named ftnchek.1. The distribution also 4260 includes a plain ASCII version named ftnchek.doc, a PostScript version 4261 named ftnchek.ps, an HTML version in directory html, and a VMS HELP 4262 version named ftnchek.hlp. 4263 4264 Information about the latest version and the status of the project can 4265 be obtained by visiting ftnchek's home page, http://www.dsm.ford- 4266 ham.edu/~ftnchek . For further information and to report bugs, you may 4267 contact Dr. Robert Moniot, whose contact information can be found by a 4268 Web search for his name and Fordham University. (E-mail address is not 4269 provided here because it attracts unsolicited commercial e-mail, but it 4270 is easily constructed by combining his last name with the name of the 4271 university and the edu domain.) 4272 4273 4274SEE ALSO 4275 dcl2inc(1L), dtoq(1L), dtos(1L), f77(1), fd2s(1L), fs2d(1L), ftnpp(1L), 4276 pfort(1L), qtod(1L), sf3(1L), stod(1L). xsf3(1L), xvcg(1L). 4277 4278 4279 4280 November 2004 FTNCHEK 3.3(1L) 4281