USER'S MANUAL FORTRAN-lint SOURCE CODE ANALYZER Version 4.32 IPT Corporation Since 1974 1076 East Meadow Circle Palo Alto, CA 94303 Tel: (650) 494-7500 Fax: (650) 494-2758 E-mail: lint@iptcorp.com FORTRAN-lint USER'S MANUAL A SOURCE LEVEL CODE ANALYZER For FORTRAN PROGRAMMING On UNIX and VMS SYSTEMS September 1998 Version 4.32 Note: Licensed users may photocopy for distribution. Direct comments concerning this manual to: IPT 1076 East Meadow Circle, Palo Alto, California 94303 Tel: (650) 494-7500 Fax: (650) 494-2758 E-mail: lint@iptcorp.com Copyright 1987-1998 IPT NOTICE OF COPYRIGHTS Copyrighted by IPT as an unpublished work. All rights reserved. In claiming any copyright protection which may be applicable, IPT re- serves and does not waive any other rights that it may have (by agree- ment, statutory or common law, or otherwise) with respect to this mat- erial. See Notice of Proprietary Rights. NOTICE OF PROPRIETARY RIGHTS This manual and the material on which it is recorded are the property of IPT. Its use, reproduction, transfer and/or disclosure to others, in this or any other form, is prohibited except as permitted by a written License Agreement with IPT. IPT reserves the right to update this document without prior notification. FORTRAN-lint is a registered trademark of IPT Corp. Xlint is a trademark of IPT Corp. SunOS is a registered trademark of Sun Microsystems, Incorporated. UNIX is a registered trademark of AT&T Bell Laboratories. DEC, ULTRIX, VAX, and VMS are registered trademarks of Digital Equip- ment. Table of Contents 1. Introduction 2. Getting Started 2.1 Analyzing Programs 2.2 Managing the Output 2.3 Call Trees and Cross Reference Tables 3. Command Reference 3.1 Command-Line Options 3.2 Summary of Options 3.3 Configuration Files 3.4 Environment Variables / Logicals 4. FORTRAN-lint Source Conventions 4.1 Source Format 4.2 Include Files 4.3 'C' Preprocessor (UNIX only) 4.4 CDD and DBMS Support (VMS only) 4.5 FORTRAN-77 Extensions 4.6 Fortran 90 Extensions 4.7 Specifying FORTRAN Dialect 4.8 Default Sizes 4.9 High Performance Fortran (HPF) 5. Controlling Analysis 5.1 Setting the Scope 5.2 Message Classification 5.3 Selecting Analysis Level 5.4 Suppressing Individual Messages 5.5 Portability Checking 6. Analysis Output 6.1 Overview 6.2 Summary Mode 6.3 Analysis Output 6.4 Statistics Output 6.5 Exit Status 7. Call Trees 7.1 Overview 7.2 Tree Options 7.3 Call Tree Format 7.4 Call Tree Content 7.5 Recursion 7.6 Dummy Routines 7.7 Entry Points 7.8 Fortran 90 Internal Subprograms 8. Cross Reference 8.1 Overview 8.2 Layout 8.3 Format Selection 8.4 Content Selection 9. Library Support 9.1 Overview 9.2 Creating Library Files 9.3 Library Precedence 9.4 Library Shells 9.5 Miscellaneous Library Issues 10. Database Files 10.1 Overview 10.2 Creating Database Files 10.3 Using Database Files 11. Xlint Introduction 12. Learning About Xlint 12.1 Screen Layout 12.2 File Menu 12.3 Search Menu 12.4 Build Menu 12.5 Source Window 12.6 Lint Window 12.7 Tree Window 12.8 Cross Reference Window 12.9 Control Panel 12.10 Mouse Functions 13. Database Files and Xlint 13.1 Overview 13.2 Loading Database Files 13.3 Rebuilding Database Files under Xlint 14. Xlint: Getting Started 14.1 Configuration Setup 14.2 Running Xlint 14.3 Sample Sessions 15. More About Xlint 15.1 Resizing Windows 15.2 Window Interaction 15.3 Command-Line Options 15.4 Advanced Example 16. Resource Files 16.1 Overview 16.2 XLint and XLINT.DAT Appendix A - Installation under UNIX Appendix B - Installation under VMS Appendix C - License Manager Appendix D - Sample Output: Fortran 90 Appendix E - Sample Output: FORTRAN 77 Appendix F - Diagnostic Messages Appendix G - Performance Appendix H - Xlint Installation under UNIX Appendix I - Xlint Installation under VMS Chapter 1 Introduction 1.1 Overview FORTRAN-lint is a programming tool that simplifies the debugging and maintenance of FORTRAN 77 and Fortran 90 programs. FORTRAN-lint includes a source code analyzer that can detect a wide range of potential problems, including: inappropriate arguments passed to functions inconsistencies in common block declarations non-portable code type usage conflicts across different subprograms/program units unused functions, subroutines, and variables variables which are referenced but not set FORTRAN-lint can be used to: check source files before they are compiled isolate obscure problems identify problems before debugging is required map out unfamiliar programs enforce programming standards The diagnostic messages produced by FORTRAN-lint are more detailed than those produced by standard compilers, and cover a wider range of problems. FORTRAN-lint analyzes source files both individually and as a group, and can therefore identify problems that are beyond the scope of a compiler. Chapter 2 Getting Started 2.1 Analyzing Programs To run FORTRAN-lint, use a command of the form: flint -options file1.f file2.f file3.f under UNIX or flint /options file1.for file2.for file3.for under VMS where "options" may be one or more options, and each of the specified files is a FORTRAN source file containing any number of FORTRAN program units. Options may be intermixed with or appear after file names. If FORTRAN-lint is invoked without any options or parameters, a "help" screen will be displayed: flint If source files are specified, but no options are given, FORTRAN-lint will perform a basic analysis of the source files and output the results to the console. For example, to analyze a single source file, use a command of the form: flint demo.f under UNIX or flint demo.for under VMS The following commands will perform a more detailed analysis: flint -fgs demo.f under UNIX or flint /FYI /GLOBAL /STATISTICS demo.for under VMS ---------------------------------------------------------------------- 2.2 Managing the Output When FORTRAN-lint is used on a large program for the first time, it may report hundreds or thousands of inconsistencies. FORTRAN-lint has several features which simplify management of the output. 2.2.1 Redirection The command-line option "-Sname" (under UNIX) or "/SPLIT=name" (under VMS) will cause FORTRAN-lint to redirect output from the console to the following files: Under UNIX: Analysis output --> name.lnt Statistics (-s) --> name.stt Call tree (-t) --> name.tre Cross-reference (-x) --> name.xrf Under VMS: Analysis output --> name.lnt Statistics ( /STATISTICS) --> name.stt Call tree ( /TREE) --> name.tre Cross-reference ( /XREF) --> name.xrf For example, the following commands will analyze demo.f (or demo.for), send analysis output to demo.lnt, and send statistics output to demo.stt: flint -fgs demo.f -Sdemo under UNIX or flint /FYI /GLOBAL /STAT demo.for /SPLIT=demo under VMS 2.2.2 Statistics Output The command-line option "-s" (under UNIX) or /STATISTICS (under VMS) enables statistics and related output. If this option is used, FLINT displays a screen after analysis is completed which includes I/O statistics, structural statistics (subroutine counts, etc.) and a list of the error messages which occurred most frequently in the source code. 2.2.3 Summary Mode The command-line option "-+" (under UNIX) or /SUMMARY (under VMS) combines three operations: (a) This option displays a progress meter which tracks the progress of FORTRAN-lint in real time. (b) It redirects FORTRAN-lint output (as explained in section 2.2.1). By default, "-+" (or /SUMMARY) redirects the output to files named flint.lnt, flint.tre, etc. "-S" (or /SPLIT) may be used to specify a different base name. (c) It displays an error-message summary (as described in section 2.2.2). For example, the following commands will analyze demo.f (or demo.for), display a progress meter, send analysis output to flint.lnt, and display an error-message summary after analysis is completed: flint -fg+ demo.f under UNIX or flint /FYI /GLOBAL /SUMMARY demo.for under VMS ---------------------------------------------------------------------- 2.3 Call Trees and Cross Reference Tables FORTRAN-lint will optionally generate a diagram of program structure (i.e., a "call tree") and a symbol-table cross-reference. For example, the following commands will analyze demo.f (or demo.for), output a call tree to the file demo.tre, and output a cross-reference to the file demo.xrf: flint -tx demo.f -Sdemo under UNIX or flint /TREE /XREF demo.for /SPLIT=demo under VMS For additional information on call trees, see chapter 7. For additional information on cross-reference tables, see chapter 8. Chapter 3 Command Reference 3.1 Command-Line Options 3.1.1 Command Format To run FORTRAN-lint, use the command flint, followed by zero or more option switches and one or more file names: flint [options] [file1 [file2 ...]] [file3.lbt ...] [file4.fdb ...] "file1 file2 ..." are FORTRAN source files. ".lbt" files are optional call-interface library files (explained in chapter 9). ".fdb" files are optional Xlint database files (explained in chapter 13). If no options or file names are specified, flint will display a "help" screen. FORTRAN source files may use any valid FORTRAN filename extension. ".F" is a special case; under UNIX, if a source file has the ".F" extension, FORTRAN-lint will run the 'C' preprocessor on the file before analyzing it. Option switches may be specified in any order, and may be intermixed with filename arguments. 3.1.2 Option Format Under UNIX, options are specified by single-character switches; for example, "-x". Lower-case options take no arguments, and may be combined into a single switch. For example, "-stx" is equivalent to "-s -t -x". Upper-case options require one or more arguments; these options cannot be combined. Arguments are specified for UNIX switches as follows: -P argument single -argument switches or -P arg1,arg2,arg3,... multi -argument switches Under VMS, options are specified by "word" switches (for example, /XREF). "Word" switches are not case-sensitive. They may be abbreviated, provided that the abbreviations are unique. For example, /XREF is an abbreviation for /XREFERENCE. Arguments are specified for VMS switches as follows: /PORT=argument single- argument switches or /PORT=(arg1,arg2,arg3,...) multi- argument switches Note: Under VMS, switches should not include spaces. Switch arguments are cumulative. For example, under UNIX, the following commands are equivalent: flint -O 123 -O 200,375foo.f flint -O 123,200,375 foo.f Under VMS, these commands are equivalent: flint /SUPPRESS=123 /SUPPRESS=(200,375) foo.for flint /SUPPRESS=(123,200,375) foo.for To disable an option under UNIX, add an extra dash to the option switch. For example, "-w" enables warning messages and "--w" disables them. To disable an option under VMS, add the word "NO" to the option switch. For example, /WARN enables warning messages and /NOWARN disables them. When an option is disabled, arguments accumulated up to that point are discarded. If the option is re-enabled subsequently, it "starts over". For example, under UNIX, the following commands are equivalent: flint -P ANSI,CRAY --P -P SGI foo.f flint -P SGI foo.f Under VMS, these commands are equivalent: flint /PORT=(ANSI,CRAY) /NOPORT /PORT=SGI foo.for flint /PORT=SGI foo.for Configuration files may be used to set default values for options. The FORTRAN-lint package includes a predefined configuration file named flint.cfg; for additional information, see section 3.3. 3.1.3 List of Options The FORTRAN-lint options are listed below: -a, /ANSI Description: Reports non-ANSI constructs. If FORTRAN-lint is run in FORTRAN 77 mode, this switch has the same effect as "-P ansi77" (or /PORT=ansi77). If FORTRAN-lint is run in Fortran 90 mode, this switch has the same effect as "-P ansi90" (or /PORT=ansi90). Note: To set the language mode, use the -7, -9 and/or /LANG switches. UNIX syntax: -a VMS syntax: /ANSI -B, /DATABASE= Description: Creates a specified database (.fdb) file. FORTRAN- lint and Xlint use database files to regenerate call trees, cross-reference tables, and diagnostic messages. For additional information on database files, see chapter 13. Note: FORTRAN-lint adds the ".fdb" filename extension automatically. UNIX syntax: -B file VMS syntax: /DATABASE=file -d, /DLINES Description: Source lines starting with "D" in column one (or "Y", for EPC code) are "debug" lines. By default, "debug" lines are treated as comment lines. If "-d" (or /DLINES) is specified, FORTRAN-lint will process "debug" lines along with normal source code. Note: This option is valid only for fixed-form code. UNIX syntax: -d VMS syntax: /DLINES -D Description: (UNIX only.) Defines symbols for the 'C' preprocessor. Applies only if source files are preprocessed (".F" filename extension or "-p" option). For additional information, see section 4.3. UNIX syntax: -D symbol[=value],... VMS syntax: N/A -e, /EXTEND Description: By default, if the source format is fixed form, characters past column 72 are ignored. If this option is specified, the source-line width is extended to 132 columns. For additional information, see section 4.1. UNIX syntax: -e VMS syntax: /EXTEND -E, /FILES= Description: Reads a specified file and adds its contents to the FORTRAN-lint command line. The file may contain source-file names and/or command-line option switches. Entries may be separated by commands, newlines, or spaces, and may be specified in any order. Nested expansions are allowed. I.e., the specified file may use the "-E" (or /FILES) option to process lower- level files. Wildcard are not supported. I.e., the specified file cannot include entries of the form "*.for". This option cannot be suppressed. I.e., "--E" and /NOFILES are not supported. For additional information, see section 3.3. UNIX syntax: -E file,... VMS syntax: /FILES=(file,...) /FORM= See "-R". -f, /FYI Description: Enables FYI (or "for your information") diagnostics. FYI diagnostics are informational messages which may (or may not) indicate problems. UNIX syntax: -f VMS syntax: /FYI -g, /GLOBAL Description: Global analysis. This option is strongly recommended. By default, subprograms are processed on an individual basis, and call interface checking is not performed. The "-g" (or /GLOBAL) option enables "global" analysis. If this option is used, FORTRAN-lint checks for inconsistencies between subprograms; for example, invalid arguments or common-block problems. This option also improves usage checking and enhances cross-reference output. UNIX syntax: -g VMS syntax: /GLOBAL -i, /INCLUDE Description: Expands INCLUDE files in source listings. This option applies only when source listings are enabled (see "-l" or /LISTING). UNIX syntax: -i VMS syntax: /INCLUDE -I, /PATH= Description: Adds one or more directories to the include-file searchlist. This switch affects both INCLUDE files and "#include" files. For additional information, see sections 4.2 and 4.3. UNIX syntax: -I path,... VMS syntax: /PATH=([path],...) Example: -I ../myftn,/usr/sam/headers under UNIX /PATH=([FTNCODE],[USR.HEADERS]) under VMS /IMPLICIT See "-m". /LANG= See "-7" and "-9". -l, /LISTING Description: Outputs a source listing with line numbers. UNIX syntax: -l (lower-case ell) VMS syntax: /LISTING -L, /LIBRARY= Description: Creates or updates a library template file. This option adds interface information for the current source files to the specified library template (or ".lbt") file. ".lbt" files may be used to speed up subse quent runs. For additional information, see chapter 9. Note: This option causes FORTRAN-lint to run in a special mode, bypassing normal analysis. Consequently, source files must be free of errors before this option is used. UNIX syntax: -L file.lbt VMS syntax: /LIBRARY=file.lbt Example: flint -L vmslib.lbt vmslib.lsh under UNIX flint /LIBRARY=mylib.lbt mylib.for under VMS /LPP= See "-Y". -m, /IMPLICIT Description: Reports the use of implicit data typing. UNIX syntax: -m VMS syntax: /IMPLICIT -M, /MISC= (F90 only) Description: Miscellaneous options: ansi_maxloc Modifies the rules used for HPF checking. For additional information, see section 4.9. depend If this sub-option is specified, Fortran 90 source- file order is irrelevant. Note: This sub-option adds an extra pass, which reduces processing speed slightly. depend:filename FORTRAN-lint will output the FORTRAN-lint sorted file list and the file dependencies via USE association to the specified file. The filename extension ".dep" is added auto matically. If the source files are in order, depend is not required. help Outputs a "help" screen describing these sub- options. hpf Enables HPF checking. For additional informa tion, see section 4.9. noexit For UNIX users who use shell scripts to check FORTRAN-lint results. This sub-option tells FORTRAN-lint to return zero unless errors were detected. uselbt Modifies the precedence rules used for library template (.lbt) files. For additional information, see section 9.3. UNIX syntax: -M option,... VMS syntax: /MISC=(option,...) /NOI4 See "-2". -O, /SUPPRESS= Description: Disables or enables individual diagnostic messages. UNIX syntax: -O msg#,msg#,... disables messages by number -O +msg#,+msg#,... enables messages by number -O all disables all numbered messages -O +all enables all numbered messages -O msg#,+msg#,... disable/enable can be mixed VMS syntax: /SUPPRESS=(msg#,...) disables messages by number /SUPPRESS=(+msg#,...) enables messages by number /SUPPRESS=ALL disables all numbered messages /SUPPRESS=+ALL enables all numbered messages disable/enable can be mixed /SUPPRESS=(msg#,+msg#,...) /OUTPUT= Description: (VMS only.) Redirects output to a specified file. Note: Under UNIX, use standard-I/O redirection (flint ... > file). UNIX syntax: N/A VMS syntax: /OUTPUT=file See also: -S or /SPLIT -p Description: (UNIX only.) Sends all source files through the 'C' preprocessor. Note: FORTRAN-lint sends files with the ".F" filename extension through the 'C' preprocessor, whether or not the "-p" option is selected. UNIX syntax: -p VMS syntax: N/A -P, /PORT= Description: Checks for portability issues related to one or more compilers or FORTRAN dialects. Supported environments include: ANSI77 (FORTRAN 77) HPUX ANSI90 (Fortran 90) LAHEY CRAY SGI DECUNIX SUN DECVMS VAXULTRIX EPC For additional information, see sections 4.5 through 4.7. UNIX syntax: -P system,... VMS syntax: /PORT[ABILITY]=(system,...) -q, /QUIT Description: This option is related to FORTRAN- lint's license manager (see appendix C). By default, FORTRAN-lint waits for a free license, if none is available. If "-q" (or /QUIT) is specified, FORTRAN-lint terminates immediately, in this case. UNIX syntax: -q VMS syntax: /QUIT -R, /FORM= Description: When Fortran 90 sources are processed, FORTRAN-lint normally determines the source format (fixed or free) based on the filename extension. "-R" (or /FORM) may be used to specify the source format explicitly. For additional information, see section 4.1. Note: This option does not apply to FORTRAN 77 code. UNIX syntax: -R fixed Specifies fixed form -R free Specifies free form VMS syntax: /FORM=fixed Specifies fixed form /FORM=free Specifies free form -s, /STATISTICS Description: Enables statistics and related output. If this option is used, FLINT displays a screen after analysis is completed which includes I/O statistics, structural statistics (subroutine counts, etc.) and a list of the error messages which occurred most frequently in the source code. UNIX syntax: -s VMS syntax: /STATISTICS See also: -+ (or /SUMMARY) -S, /SPLIT= Description: Sends FORTRAN-lint output to a group of text files. If this option is used, FORTRAN-lint stores its output as fol-lows: Analysis output --> name.lnt Statistics ( /STATISTICS) --> name.stt Call tree ( /TREE) --> name.tre Cross-reference ( /XREF) --> name.xrf where name is specified by "-S name" (under UNIX) or "/SPLIT=name" (under VMS). UNIX syntax: -S name VMS syntax: /SPLIT=name See also: -+ (or /SUMMARY) /SUMMARY See "-+" at the end of this list. /SYSTEM= See "-V". -t, /TREE Description: Generates a "call tree"; i.e., a structural diagram of the "call" structure used by the source code. For call- tree format options, see "-T" or /TREE. For additional information on call trees, see chapter 7. UNIX syntax: -t VMS syntax: /TREE See also: -T -T, /TREE= Description: Sets call-tree sub-options and generates a call tree. (The "help" sub-option is a special case.) The following sub-options are supported: alphabetical FORTRAN-lint normally displays sub-trees using the order in which routines were called. If "alphabetical" is used, sub-trees are displayed in alphabetical order. "alphabetical" may be abbreviated to "alpha". To restore the default mode of operation, use "-T noalpha" (or /TREE=noalpha). condensed Merges multiple calls to the same routine. To restore the default mode of operation, use "-T nocondensed" (or /TREE=nocondensed). graphics=xxx Changes the graphics characters used to print the call tree. For additional information, see section 7.3.5. head:symbol Generates a call tree starting at the specified symbol. help Displays a "help" screen describing the call- tree options. No processing is done, if this sub-option is selected. nolibrary Suppresses calls to routines defined in librar- ies (i.e., ".lbt" files). For additional infor- mation, see section 7.4.3 and chapter 9. noundefined Suppresses calls to undefined routines. squish To improve readability, FORTRAN-lint normally adds extra white space to call trees. "squish" removes the extra space. To restore the default mode of operation, use "-T nosquish" (or /TREE=nosquish). trim This sub-option merges redundant sub-trees to reduce the size of the output. The configuration file shipped with FORTRAN- lint enables trim, by default. To disable this sub-option, use "-T notrim" (or /TREE=notrim). "trim" is strongly recommended for systems which are low on disk space. For additional information on call trees, see chapter 7. UNIX syntax: -T option,... Note: To set call-tree options without generating a call tree, use -T option,... followed by "--t". VMS syntax: /TREE=(option,...) Note: To set call-tree options without generating a call tree, use /TREE=(option,...) followed by "--t". -u, /USAGE Description: Enables variable usage checking. For example, this feature de-tects variables which are referenced, but not set. The configuration file shipped with FORTRAN-lint enables this option, by default. If usage checking is not required for a given project, "--u" (or /NOUSAGE) may be used to disable this option. Some operations will be slightly faster if usage checking is disabled. UNIX syntax: -u VMS syntax: /USAGE /UNIXHELP See "-?" at the end of this list. -V, /SYSTEM= Description: FORTRAN-lint normally assumes that the FORTRAN compiler running on the host system will be used. To select a different environment, use this option. "-V" (or /SYSTEM) tells FORTRAN-lint to assume that a specific compiler (or FORTRAN dialect) will be used. This allows FORTRAN-lint to resolve ambiguous extensions (constructs that look similar, but are handled differently in different environments). Supported environments include: ANSI77 (FORTRAN 77) HPUX ANSI90 (Fortran 90) LAHEY CRAY SGI DECUNIX SUN DECVMS VAXULTRIX EPC For additional information, see sections 4.5 through 4.7. UNIX syntax: -V system VMS syntax: /SYSTEM=system -w, /WARNINGS Description: Enables "warning" messages. The configuration file shipped with FORTRAN-lint enables this option, by default. To disable warnings, use --w (or /NOWARNINGS). UNIX syntax: -w VMS syntax: /WARNINGS -W, /WIDTH= Description: Sets output width in columns. This option affects all output, including diagnostic messages and cross- reference tables. Any value between 40 and 500 may be used. Under UNIX, the default width is 80 columns. Under VMS, the default width is 80 columns unless /OUTPUT is used; in this case, the default width is 132 columns. UNIX syntax: -W number VMS syntax: /WIDTH=number -x, /XREF Description: Generates a cross-reference table. For cross- reference format options, see "-X" or /XREF. For additional information on cross-reference tables, see chapter 8. UNIX syntax: -x VMS syntax: /XREF or /XREFERENCE -X, /XREF= Description: Sets cross-reference sub-options and generates a cross-reference table. The following sub-options are supported: freeform Selects a compact variable-width format. This is the default setting. tabular Selects a fixed-width (132 column) format. linenumbers Locations by line numbers rather than by sub- program. noequiv By default, the cross-reference entry for a given variable includes usage information for the associated equivalences, whether or not the variable is used directly. noequiv suppresses equivalence usage information. nolegend Suppresses the legend which describes line num-ber usage codes. filters FORTRAN-lint supports cross-reference filters. Filters may be used to generate cross- reference tables for items which meet specific constraints. For additional information, see sections 8.3 and 8.4. For additional information on cross-reference tables, see chapter 8. UNIX syntax: -X option,... Note: To set cross-reference options without generating a cross-reference, use "-X option,..." followed by "--x". VMS syntax: /XREF[ERENCE]=(option,...) Note: To set cross-reference options without generating a cross-reference, use /XREF=(option,...) followed by "--x". -Y, /LPP= Description: Sets lines per output page. To disable pagination, use a page length of zero. The default value is zero for console output and 60 lines per page if "-S", "-+", /OUTPUT, /SPLIT, and/or /SUMMARY are used to redirect output. UNIX syntax: -Y number VMS syntax: /LPP=number -2, /NOI4 Description: On most systems, integers and logicals are four bytes long, by default. If "-2" (or /NOI4) is used, FORTRAN-lint interprets INTEGER and LOGICAL as INTEGER*2 and LOGICAL*2. Additionally, integer and logical constants are treated as two-byte values unless they are too large to fit into the smaller size. UNIX syntax: -2 VMS syntax: /NOI4 -7, /LANG= @@@ -9 Description: This option may be used to specify the input language (FORTRAN 77 or Fortran 90). UNIX syntax: -7 Selects FORTRAN 77 -9 Selects Fortran 90 VMS syntax: /LANG=F77 Selects FORTRAN 77 /LANG=F90 Selects Fortran 90 -+, /SUMMARY Description: The command-line option "-+" (under UNIX) or /SUMMARY (under VMS) combines three operations: (a) This option displays a progress meter which tracks the progress of FORTRAN-lint in real time. (b) It redirects FORTRAN-lint output (as explained in section 2.2.1). By default, "-+" (or /SUMMARY) redirects the output to files named flint.lnt, flint.tre, etc. "-S" (or /SPLIT) may be used to specify a different base name. (c) It displays an error-message summary (as described in section 2.2.2). UNIX syntax: -+ VMS syntax: /SUMMARY -?, /UNIXHELP Description: (VMS only.) Displays FORTRAN-lint's "letter" option switches. This option is not supported under UNIX. To display the "letter" switches under UNIX, execute flint with no parameters. For additional information, see section 3.1.2. UNIX syntax: N/A VMS syntax: -? or /UNIXHELP 3.1.4 Using UNIX Switches Under VMS FORTRAN-lint's "letter" option switches (-letter) can be also used under VMS. "Letter" switches can be used inside flint configuration files with no special rules or restrictions. However, if "letter" switches are used on the VMS command line, three rules apply: (a) "letter" switches do not include white space (b) "letter" switches are limited to one argument per switch (c) upper-case switches must be double-quoted For example, the following VMS flint commands are equivalent: flint /PORT=sgi foo.for flint "-Psgi" foo.for To specify multiple arguments for a "letter" switch on the VMS command line, use multiple copies of the switch. For example, the following commands are equivalent: flint /TREE=(condensed,nolibrary) foo.for flint "-Tcondensed" "-Tnolibrary" foo.for As under UNIX, lower-case "letter" options may be combined into a single switch. For example, the following commands are equivalent: flint /IMPLICIT /XREF /NOI4 foo.for flint -mx2 foo.for Additional VMS examples: 1) flint /IMPLICIT foo.for flint -m foo.for 2) flint /SPLIT=result /WARNINGS /WIDTH=50 foo.for flint "-Sresult" -w "-W50" foo.for 3) flint /ANSI /FYI /GLOBAL /SUPPRESS=(201,202) foo.for flint -afg "-O201" "-O202" foo.for ---------------------------------------------------------------------- 3.2 Summary of Options 3.2.1 UNIX Option Summary Source configuration options: -d Process "debug" lines -e Extend source width to 132 columns -I path,... Set search path for INCLUDE files -p Send source files through preprocessor (CPP) -R form Specify Fortran 90 source form -V system Specify FORTRAN dialect -2 Two-byte integers and logicals -7 Select FORTRAN 77 -9 Select Fortran 90 Diagnostic options: -a Report non-ANSI constructs -f Report FYI messages -g Enable global processing -m Report implicit typing -O number,... Suppress individual error messages -P system,... Enable portability checking -u Check data usage -w Enable warnings Cross-reference options: -x Generate cross-reference table -X option,... Specify cross-reference sub-options Call tree options: -t Generate "call tree" -T option,... Specify "call tree" options Output format options: -I (Upper-case eye) Expand INCLUDE files -l (Lower-case ell) Generate source listing -W number Set output page width -Y number Set output page length Other output control options: -+ "Progress/summary" mode (implies -S) -B file Create database (.fdb) file -L file Create library (.lbt) file -s Generate statistics -S file Split output and redirect it Miscellaneous options: -D definition,... Define preprocessor-level symbols -E file Expand configuration file -M option,... Miscellaneous options -q Quit if no licenses are available 3.2.2 VMS Option Summary Source configuration options: /DLINES Process "debug" lines /EXTEND Extend source width to 132 columns /FORM=form Specify Fortran 90 source form /LANG=language Specify language (F77 or F90) /NOI4 Two-byte integers and logicals /SYSTEM=system Specify FORTRAN dialect /PATH=([path],...) Set search path for INCLUDE files Diagnostic options: /ANSI Report non-ANSI constructs /FYI Report FYI messages /GLOBAL Enable global processing /IMPLICIT Report implicit typing /PORT=(system,...) Enable portability checking /SUPPRESS=(number,...) Suppress individual error messages /USAGE Check data usage /WARNINGS Enable warnings Cross-reference options: /XREF Generate cross-reference table /XREF=(option,...) Specify cross-reference sub-options Call tree options: /TREE Generate "call tree" /TREE=(option,...) Specify "call tree" sub-options Output format options: /INCLUDE Expand INCLUDE files /LIST Generate source listing /LPP=number Set output page length /WIDTH=number Set output width Other output control options: /DATABASE=file Create database (.fdb) file /LIBRARY=file Create library (.lbt) file /OUTPUT=file Redirect output to a specified file /SPLIT=file Split output and redirect it /STATISTICS Generate statistics /SUMMARY "Progress/summary" mode (implies /SPLIT) Miscellaneous options: /FILES=file Expand configuration file /MISC=(option,...) Miscellaneous options /QUIT Quit if no licenses are free /UNIXHELP or -? Display UNIX "letter" options ---------------------------------------------------------------------- 3.3 Configuration Files Command-line arguments may be specified indirectly, using text files. If bar.txt is a text file containing option switches or filenames, the following commands will add the contents of bar.txt to the FORTRAN- lint argument list: flint -E bar.txt foo.f under UNIX or flint /FILE=bar.txt foo.for under VMS bar.txt may specify any number of switches or filenames. There are two restrictions: (a) Arguments must be separated by white space or newlines (b) Under UNIX, wildcards (such as "*.for") are not supported Files used this way are called configuration files. FORTRAN-lint may be used for multiple purposes: quick syntax checks, mapping out unfamiliar programs, etc. Configuration files are a convenient way to select different sets of options. To set FORTRAN-lint options automatically, create a configuration file named flint.cfg and add option switches to this file. FORTRAN-lint searches for flint.cfg in the following directories: (a) Current working directory (b) Directories specified by the environment variable FLINTCFG (under UNIX) or logical FLINTCFG (under VMS) (c) FORTRAN-lint installation directory, as specified by the env- ironment variable FLINTHOME (under UNIX) or logical FLINTHOME (under VMS) Note: Command-line option switches may be used to override options set by flint.cfg. Multiple configuration files may be used; e.g., for different projects. FLINTCFG should be set appropriately for users working on each project. For additional information on FLINTCFG and FLINTHOME, see section 3.4. FORTRAN-lint does not impose a fixed limit on configuration-file line length. However, system constraints may impose a limit of 1024 characters per line for some environments. This is a typical flint.cfg file: -w ! Enable warnings -u ! Enable usage checking -O207 ! Suppress Hollerith constant warning -O261 ! Suppress "initializer data type converted" -Ttrim ! Make TRIM the default call-tree format --t ! Default setting: turn call tree off ! Eliminate unreferenced parameters -Xno_unreferenced_parameters ! Show common variables only where they are used -Xno_unused_common_variables --x ! Default setting: turn cross-reference off Note: VMS configuration files may use "letter" switches without special rules or restrictions. However, several restrictions apply if "letter" switches are used on the VMS command line. For additional information, see section 3.1.2. For the current set of default options, see the copy of flint.cfg provided with FORTRAN-lint. ---------------------------------------------------------------------- 3.4 Environment Variables / Logicals FORTRAN-lint recognizes the following environment variables (under UNIX) or logicals (under VMS): Variable Description ----------- -------------------------------------------------------- FLINTCFG Directory that contains alternate support files (see be- low) FLINTHOME FORTRAN-lint installation directory FLINTHOST Hostname of syetem running license-manager daemon TMPDIR (UNIX only) Directory used for temporary files SYS$SCRATCH (VMS only) Directory used for temporary files FLINTHOME specifies the location of the main FORTRAN-lint directory (i.e., the directory where FORTRAN-lint was installed). This variable is set during installation (see appendix A or appendix B). FORTRAN-lint includes a license-manager daemon (see appendix C). FLINTHOST specifies the system where the daemon resides. This variable is also set during installation. FORTRAN-lint uses the following run-time support files: flint.cfg Configuration file (see section 3.4) flint.err Error messages flint.hls "Help" file unixlib.lbt UNIX library definitions (see chapter 9) vmslib.lbt VMS library definitions By default, FORTRAN-lint uses the copies stored in the main FORTRAN- lint directory (i.e., the FLINTHOME directory). However, if FLINTCFG is defined, FORTRAN-lint searches the FLINTCFG directory for support files before it loads the default copies. Users may set this variable to load customized versions of the support files. Under UNIX, FLINTCFG specifies one or more directories using the following format: directory-path or directory-path:...:directory-path Note: Directory paths must be separated by colons. Under VMS, FLINTCFG specifies one or more directories using the following format: directory-path or directory-path,...,directory-path Under VMS, directory paths must be separated by commas. Users may define TMPDIR (under UNIX) or SYS$SCRATCH (under VMS) to set or change the directory where FORTRAN-lint stores its temporary files. Note: TMPDIR is ignored on UNIX systems which don't support the standard library routine "tempnam()". Chapter 4 FORTRAN-lint Source Conventions 4.1 Source Format FORTRAN-lint accepts one or more FORTRAN source files as input. Each source file may contain one or more FORTRAN subprograms (or program units). A subprogram/program unit may be a subroutine, a function, a block data module, or a main program. INCLUDE-file names should not be specified explicitly on the command line or in configuration files. FORTRAN-lint understands several different source formats. In FORTRAN 77 mode (-7 or /LANG=F77 option), FORTRAN-lint assumes ANSI-standard fixed format, with a continuation indicator at column 6 and a comment field starting at column 73. To process FORTRAN 77 code that extends past column 72, add the option "-e" (under UNIX) or /EXTEND (under VMS). In Fortran 90 mode (-9 or /LANG=F90 option), sources may use either free format or FORTRAN 77 fixed format. Variable-position comments (starting with '!') may be used in either fixed or free format. FORTRAN 77-style comments (starting with a 'C' in column 1) may be used only in fixed format. Free-format lines may contain up to 132 characters. TAB formatting is supported for target environments that allow it. I.e., if the label field contains a TAB character, processing skips to the first non-blank character. If that character is a non-zero digit, the source line is treated as a continuation line; otherwise, the line is treated as a statement. TAB-formatted lines may be intermixed with normal fixed-format lines. FORTRAN-lint normally distinguishes between free-format files and fixed-format files based on filename extension. By default, ".f90" files are assumed to be free format and other files are assumed to be fixed or TAB format. To override the default setting, use the "-R" option (under UNIX) or the /FORM option (under VMS). For additional information, see chapter 3. The maximum number of continuation lines supported is 1,000 lines per statement, and there is a maximum of 32,000 significant characters per statement. 4.1.1 "Debug" Lines Source lines starting with "D" in column one (or "Y", for EPC code) are "debug" lines. By default, "debug" lines are treated as comment lines. If "-d" (or /DLINES) is specified, FORTRAN-lint will process "debug" lines along with normal source code. ---------------------------------------------------------------------- 4.2 Include Files Standard INCLUDE statements are supported. FORTRAN-lint searches the following directories for INCLUDE files: (a) The directory which contains the source file that the current INCLUDE statement belongs to. (b) The user's current directory (at the time when FORTRAN-lint was started). (c) (VMS only.) The absolute path specified by the INCLUDE state- ment (taking logicals into account). (d) Directories specified by "-I" (or /INCLUDE) option switches, moving from left to right. (e) (UNIX only.) The standard directory "/usr/include". If an INCLUDE file can't be located, FORTRAN-lint prints an error message and attempts to continue. INCLUDE files may be nested up to 10 levels deep. Note: Under UNIX, FORTRAN programs may use both INCLUDE statements and "#include" statements. "#include" is similar to INCLUDE; however, "#include" statements are handled by the 'C' preprocessor. For additional information, see the next section. ---------------------------------------------------------------------- 4.3 'C' preprocessor (UNIX only) Under UNIX, FORTRAN-lint supports the 'C' preprocessor. I.e., source files may use standard 'C' "#define", "#ifdef", and "#include" statements. Source files with ".F" filename extensions are sent through the preprocessor automatically. If the command-line option "-p" is used, FORTRAN-lint sends all source files through the preprocessor, regardless of filename extension. Preprocessor output is then checked at the FORTRAN level. Line numbers used for error messages are translated appropriately. By default, FORTRAN-lint assumes that the preprocessor is /usr/lib/cpp. To use a different preprocessor, run flpatch and patch the cpp parameter in the flint executable. (For additional information, see appendix A.) The option switch "-D" may be used to define symbols at the preprocessor level, and the option switch "-I" may be used to specify "#include" directories. For additional information, see chapter 3. FORTRAN-lint passes the following command-line arguments to the preprocessor: (a) "-D" and/or "-I" option switches, if any (b) FORTRAN source-file name (c) Output-file name Note: Files loaded by INCLUDE statements are loaded directly by FORTRAN-lint; i.e., these files are not preprocessed. ---------------------------------------------------------------------- 4.4 CDD and DBMS Processing (VMS Only) 4.4.1 CDD (Common Data Dictionary) Declarations FORTRAN-lint supports standard DICTIONARY statements. DICTIONARY is similar to INCLUDE in that it adds declarations to the current routine. However, DICTIONARY differs from INCLUDE in that it takes data structures from a CDD dictionary instead of a source file. FORTRAN-lint uses the FORTRAN compiler as a preprocessor to expand DICTIONARY statements into normal code. 4.4.2 DBMS Support (FDML Statements) FORTRAN-lint supports FDML statements (for example, invoke, ready, use, commit, rollback, disconnect, connect, erase, get, modify, fetch, find, free, also, null, within, keep, reconnect, and store). invoke statements are preprocessed by the FORTRAN compiler in the same manner as DICTIONARY statements. FORTRAN-lint processes all other FDML statements directly. Note: Usage checking is suppressed for variables that are created by invoke statements. 4.4.3 CDD/DBMS Requirements FORTRAN-lint uses the FORTRAN compiler to expand DICTIONARY and invoke statements into normal code. The FORTRAN compiler must therefore be installed before these statements can be processed. Additionally, the VMS CDD package must be installed before DICTIONARY statements can be processed, and the VMS DBMS package must be installed before invoke statements can be processed. ---------------------------------------------------------------------- 4.5 FORTRAN 77 Extensions FORTRAN-lint's FORTRAN 77 support is based on the 1978 ANSI FORTRAN 77 standard. FORTRAN-lint also supports extensions implemented by the following compilers: System Compiler Dialect code ------------------------- ----------------------- ------------------ (ANSI standard) FORTRAN, ANSI X3.9-1978 ANSI Cray YMP UNICOS CFT77 5.0 CRAY HP9000 Series HPUX FORTRAN/9000 8.05 HPUX Silicon Graphics IRIS-4D 3.3 FORTRAN 77 SGI SunOS Sun FORTRAN 1.4 SUN VAX/VMS DEC FORTRAN Version 6.0 DECVMS Alpha/Digital UNIX (OSF1) DEC FORTRAN 6.0 DECUNIX VAX Ultrix VAX FORTRAN VAXULTRIX Extensions supported by FORTRAN-lint include, but are not limited to, the following: Data-type size specifiers (for example, INTEGER*4) Records, structures, and unions Cray-style and Apollo-style pointers Debugging lines with "D" or "Y" in the first column TAB formatting In-line comments (both "!" and ";" styles) Long symbol names with non-alphanumeric characters Numerous binary, octal, and hex constant formats Hollerith constants Namelist I/O Dozens of system-specific I/O statement specifiers Hundreds of intrinsic functions All I/O format strings, including embedded expressions Abbreviated and symbolic expression operators Recursion Array sections and array expressions ---------------------------------------------------------------------- 4.6 Fortran 90 Extensions FORTRAN-lint's Fortran 90 support is based on the 1992 ANSI Fortran- Extended (Fortran 90) standard. FORTRAN-lint also supports extensions implemented by the following compilers: System Compiler Dialect code ------------------------- ------------------------- -------------- (ANSI standard) Fortran, ANSI X3.198-1992 ANSI90 DEC VAX/Alpha OpenVMS DEC Fortran 90 DECVMS Alpha/Digital UNIX (OSF1) DEC Fortran 90 DECUNIX Cray Y-MP UNICOS 7.0+ CF90 Release 1.0 CRAY Silicon Graphics IRIX 6.1 MIPSpro Fortran 90 SGI EPC EPC Fortran 90 EPC In particular, FORTRAN-lint supports High Performance Fortran (HPF). For additional information on HPF, see section 4.9. Note: If FORTRAN-lint is used in Fortran 90 mode, the FORTRAN 77 extensions are supported, with the exception that debugging lines are not allowed in free format. ---------------------------------------------------------------------- 4.7 Specifying FORTRAN Dialect FORTRAN-lint normally assumes that the FORTRAN compiler running on the host system will be used. To select a different compiler, use the "-V" option (under UNIX) or /SYSTEM (under VMS) and specify a dialect code from section 4.5 or 4.6. (For option syntax, see chapter 3.) To flag code that is not supported by a specific dialect, use "-P" (under UNIX) or /PORT (under VMS), instead. ---------------------------------------------------------------------- 4.8 Default Sizes On most systems, integers and logicals are four bytes long, by default. To change the default size, use the option "-2" (under UNIX) or /NOI4 (under VMS). If either of these options are selected, FORTRAN-lint interprets INTEGER and LOGICAL as INTEGER*2 and LOGICAL*2. Additionally, integer and logical constants are treated as two-byte values, unless they are too large into fit into the smaller size. ---------------------------------------------------------------------- 4.9 High Performance Fortran (HPF) FORTRAN-lint supports High Performance Fortran (HPF). By default, HPF statements are treated as normal comments. To enable HPF checking, use the option "-Mhpf" (under UNIX) or /MISC=hpf (under VMS). To add HPF processors and templates to a cross-reference, enable HPF checking and select linenumbers or tabular output format: Under UNIX, use: -Mhpf -Xlinenumbers or -Mhpf -Xtabular Under VMS, use: /MISC=hpf /XREF=linenumbers or /MISC=hpf /XREF=tabular For additional information on the linenumbers and tabular formats, see section 8.3. For non-DEC target systems, FORTRAN-lint normally checks argument lists for MAXLOC() and MINLOC() using the following rules: MAXLOC (ARRAY, DIM, MASK) MINLOC (ARRAY, DIM, MASK) ARRAY must be an integer or real array DIM is optional; if present, must be integer scalar MASK is optional; if present, must be of local type and conformable with ARRAY To apply the ANSI X3.198-1992 rules for MAXLOC() and MINLOC(), use the option "-Mansi_maxloc" (under UNIX) or /MISC=ansi_maxloc (under VMS). This option disallows the DIM argument. Note that "ansi_maxloc" does not apply to DEC targets (i.e., Digital Fortran 90). Chapter 5 Controlling Analysis 5.1 Setting the Scope To enable global (inter-module) checking, use the "-g" option (under UNIX) or /GLOBAL (under VMS). Global checking analyzes FORTRAN sources as a group; this enables interface checking and improves usage checking of variables passed as actual arguments. If "-g" (or /GLOBAL) is not specified, subprograms are processed on an individual basis, and call interface checking is not performed. ---------------------------------------------------------------------- 5.2 Message Classification FORTRAN-lint checks for the following five general classes of prob- lems: syntax problems subprogram interface problems variable usage problems portability problems implicitly typed variables Syntax problems are constructs that will not compile or that may be interpreted by the compiler in a different way than the programmer intended. This includes symbol names that have embedded blanks, re-declared or re-dimensioned variables, and poorly structured branches using GOTOs. Interface problems are problems with the interaction between subprograms. This includes inconsistent argument lists in function or subroutine calls, inconsistent common block organization, and unused or missing subroutines and functions. Usage problems cover improper use of variables and arrays. Variables should be both set and referenced; any deviation from this is flagged. Attempted redefinition of constants in subprogram calls is also flagged. Portability problems are constructs that are allowed on the host system but are not recognized or are interpreted differently on other systems. This includes structures, pointers, data type length specifiers, and other extensions. Implicitly-typed variables can be flagged whether or not the "IMPLICIT NONE" statement is used. If "IMPLICIT NONE" is used, they will be categorized as syntax errors. FORTRAN-lint breaks syntax problems, interface problems, data usage problems, and portability problems down into three levels of severity: Error messages are the most serious and indicate that the code will not compile or, probably, will not operate correctly. Warning messages flag constructs that may not operate as intended, that may cause intermittent problems, or that may make no sense. FYI (or "for your information") messages are used to flag minor issues which may or may not be problems. ---------------------------------------------------------------------- 5.3 Selecting Analysis Level Categories of messages may be enabled or disabled using the following options: Syntax Always enabled Interface "-g" (under UNIX) or /GLOBAL (under VMS) Usage "-u" or /USAGE (This option is on, by default.) Portability "-a" or /ANSI -Psystem or /PORTABILITY=system (see section 5.5) Implicit typing "-m" or /IMPLICIT Note: If global interface checking (-g or /GLOBAL) is enabled, usage checking will detect a wider range of problems. Severity level of messages in the above categories is controlled with the following options: Errors Always enabled Warnings "-w" or /WARNINGS (This option is on, by de- fault.) FYIs "-f" or /FYI To disable a category or level, add an extra dash (e.g., "--w") under UNIX or "NO" (e.g., /NOWARNINGS) under VMS. Examples: To perform a comprehensive analysis, use the options "-gamf" (under UNIX) or "/GLOBAL /ANSI /IMPLICIT /FYI" (under VMS). To perform basic syntax checking, use "--uw" (under UNIX) or "/NOUSAGE /NOWARNINGS" (under VMS). ---------------------------------------------------------------------- 5.4 Suppressing Individual Messages To suppress individual diagnostic messages, use the "-O" (omit) option (under UNIX) or /SUPPRESS (under VMS). "-O" and /SUPPRESS accept message numbers as arguments. Message num- bers are shown between the category/severity field and the message text. Multiple instances of the same message have the same number. For additional information, see appendix E. "-O" and /SUPPRESS also accept the word "all" as an argument (e.g., "-Oall" or /SUPPRESS=all). "all" suppresses all numbered messages, including syntax errors. If message numbers (or the word "all") are preceded with a plus sign ("+"), the specified message or messages are "unsuppressed". E.g., if "-O201" is used to suppress message #201, "-O+201" will re-enable it. Note that an unsuppressed message will be shown only if its analysis category and level were selected. Summary: -O arg /SUPPRESS=arg Action ------------- ----------------------- n Suppress message #n all Suppress all messages +n Unsuppress message #n +all Unsuppress all messages Example: "-Oall,+279,+281" (under UNIX) or "/SUPPRESS=(all,+279,+281)" (under VMS) will suppress all messages but #279 and #281. Since messages #279 and #281 are interface FYIs, the options "-gf" or "/GLOBAL /FYI" must also be selected in order for these messages to be produced. ---------------------------------------------------------------------- 5.5 Portability Checking To check for portability problems (problems that may occur when FORTRAN code is ported to different systems), use the "-P" option (under UNIX) or /PORT (under VMS). "-P" and /PORT take target-system names as arguments. Target systems are discussed in section 4.5 (FORTRAN 77 extensions) and section 4.6 (Fortran 90 extensions). System names include ANSI, ANSI90, CRAY, DECUNIX, DECVMS, EPC, HPUX, NCUBE, OS32, SGI, SUN, and VAXULTRIX. Multiple targets may be specified. To flag non-ANSI constructs, use "-a" (under UNIX) or /ANSI (under VMS). If FORTRAN-lint is run in Fortran 90 mode, these options have the same effect as "-Pansi90" and /PORT=ANSI90. Otherwise, they have the same effect as "-Pansi" and /PORT=ANSI. Example: If FORTRAN code is being ported to both VAX/VMS and CRAY systems, use "-Pdecvms -Pcray" (under UNIX) or "/PORT=(DECVMS,CRAY)" (under VMS) to check for portability problems related to either target system. Chapter 6 Analysis Output 6.1 Overview By default, FORTRAN-lint sends all text output to the console (stdout under UNIX or SYS$OUTPUT under VMS). The output is divided into sections, which are printed in the following order: Section Controlled by Current options List of source files Source listing -l -i /LISTING /INCLUDE Analysis output -g -u -m -P -a -w -f -O /GLOBAL /USAGE /IMPLICIT /PORT /ANSI /WARNINGS /FYI /SUPPRESS Call tree -t -T /TREE /TREE= Cross reference tables -x -X /XREF /XREF= Statistics -s /STATISTICS To redirect output under UNIX, use the standard UNIX redirection operators or FORTRAN-lint's "-S" and "-+" options. To redirect output under VMS, use the options /OUTPUT, /SPLIT, or /SUMMARY. For additional information on "-S" and /SPLIT, see section 2.2.1 or chapter 3. For additional information on "-+" and /SUMMARY, see section 2.2.3 or chapter 3. To modify the output page width or page length, use "-W" and "-Y" (under UNIX) or /WIDTH and /LPP (under VMS). ---------------------------------------------------------------------- 6.2 Summary Mode FORTRAN-lint provides an optional progress meter. The progress meter is a stationary counter (displayed on the console) which tracks the progress of analysis from 0% to 100%. To display the progress meter, use "-+" (under UNIX) or /SUMMARY (under VMS). By default, these options divert normal flint output to a set of text files. Specifically, enabling the progress meter also sets the option "-Sflint" (under UNIX) or /SPLIT= flint (under VMS). These options send analysis output to flint.lnt, statistics output to flint.stt, etc. To specify a different base name, add an explicit "-S" (or /SPLIT) option to the command line. Note: After analysis is complete, FORTRAN-lint erases the progress meter and displays a summary of the messages produced. For additional information, see sections 2.2.1 and 2.2.3. ---------------------------------------------------------------------- 6.3 Analysis Output 6.3.1 Options and Filenames The first line of the analysis output shows the FORTRAN-lint revision number and the current date and time. The next few lines show the selected options, along with where they were specified. Default options are options that were specified in the flint.cfg configuration file in the installation directory. These are the system defaults. User options are options that were specified in a flint.cfg configuration file in the directory named in the environment variable FLINTCFG. These are a user's custom tailored defaults. Local options are options that were specified in a flint.cfg configuration file in the local directory. These are usually the defaults for a specific project. Expanded options are options that were specified in a configuration file expanded onto the command line with the "-E" or /FILES option. Command options are options that were placed on the command line. The selected source file names are shown next, grouped by directory. A source listing follows (if requested), along with diagnostic messages. 6.3.2 Source Listing To produce a source listing, use the "-l" (dash ell) option (under UNIX) or /LISTING (under VMS). By default, the listing does not expand include files. To expand include files, use the "-i" option (under UNIX) or /INCLUDE (under VMS). 6.3.3 Diagnostic Messages FORTRAN-lint generates a diagnostic message for each problem detected within a subprogram/program unit. Each message includes the source line and a pointer to the column where the problem appears. Also shown are the name of the source file, the subprogram/program unit name, the line number, the message category and severity, the message number, and the message text. A typical message looks like this: > CALL DIPSTAT( 4, CURITEM) > ^ demo.f:PRINTIT line 43: INTERFACE ERROR #59- constant is changed by subprogram. Messages are generally printed in the order they appear in the source file, and are grouped by subprogram/program unit. Each message group starts with a header consisting of a row of "*" characters followed by subprogram/program unit information. The header looks like this: ************************************************************* Subroutine PRINTIT File demo.f Line 39 Additional diagnostic messages may be printed after a subprogram/pro- gram unit is completely processed or after all subprograms are pro- cessed. For example: IMPLICIT- symbols were implicitly typed: A, AQDATA, DELTI USAGE ERROR- local variables referenced but never set: J, K SYNTAX FYI- unused labels: 150 ---------------------------------------------------------------------- 6.4 Statistics Output To generate statistical reports, use the "-s" option (under UNIX) or /STATISTICS (under VMS). Statistical reports include program size, comment density, and diagnostic messages summarized by number, category, and severity. Program size statistics appear first. The number of source files is shown, followed by the number of lines and bytes of code for the source files, the include files, and the total of the two: Number of source files: 1 Source files: 52 lines, 1314 bytes ( 5% comments, 95% code ) Include files: 44 lines, 1052 bytes ( 14% comments, 86% code ) Total parsed: 96 lines, 2366 bytes ( 9% comments, 91% code ) Counts on "Include files" reflect all appearances of the include files and will be much higher than that of the include files alone. "Total parsed" is calculated after all include files are expanded. Byte counts do not include the newline characters. Comment percentage is based on byte counts and takes both comment lines and inline comments into account. The comment percentage for include files and total parsed is calculated after all include files are expanded. This multiplies the weight of an include file comment by how many times it is included. A breakdown of subprograms/program units follows: Total subprograms: 7 Subroutines: 6 Functions: 0 Program: 1 Block Data: 0 Modules: 0 Shown next is a breakdown of the messages produced. Messages are sorted by frequency of appearance. Displayed for each message are its category, severity, number, frequency, and message text. Context-dependent fields in the message text are shown as astericks (*). Individual message summary ------------------------------------------------------------------ INTRFC ERR #57- 2x: too many arguments. INTRFC WARN #63- 2x: expression is changed by subprogram. SYNTAX WARN #47- 1x: branch into do loop via label *. INTRFC ERR #56- 1x: not enough arguments. INTRFC ERR #59- 1x: constant is changed by subprogram. INTRFC ERR #95- 1x: this name is defined as a subroutine. The number of messages is displayed last, shown both in total and by category and severity. The code , meaning "suppressed", is shown for message categories and severities that were not selected. Total messages: 18 Errors Warnings FYIs ------ -------- ---- Syntax: 0 1 0 Interface: 8 4 0 Data usage: 2 1 2 Implicit typing: ---------------------------------------------------------------------- 6.5 Exit Status FORTRAN-lint return status output is as follows: On VMS systems: 0x18000001 : No errors/warnings/FYIs; 0x18000003 : FYIs produced; 0x18000000 : Warnings (and FYIs) produced; 0x18000002 : Errors (and warning/FYIs) produced; 0x18000004 : Fatal errors caused FORTRAN-lint to terminate before completion. On UNIX systems: 0 : No errors/warnings/FYIs; 1 : FYIs produced; 2 : Warnings (and FYIs) produced; 3 : Errors (and warning/FYIs) produced; 4 : Fatal errors caused FORTRAN-lint to terminate before completion. Note that that under UNIX, return status 0, 1, or 2 indicates that FORTRAN-lint did not detect any errors with the specified options. If "-Mnoexit" is used, FORTRAN-lint will return 0 (only), unless errors are detected. Chapter 7 Call Trees 7.1 Overview "Call trees" are diagrams which outline the calling structure used by the FORTRAN input source files. To generate call trees, use the "-t" option (under UNIX) or /TREE (under VMS). A typical call tree (using the default format) looks like this: FORTRAN-lint (call tree) This is a primary tree starting at the program 'PROCDAT' PROCDAT-+-GETUNIT | +-READNAME | +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT* | | | +-GETTING | +-PRINT--PRINTIT-+-DIPSTAT--*PRINT* | +-GETTING For the source code used by this example, see appendix E. ---------------------------------------------------------------------- 7.2 Tree Options To modify the call tree format, use the "-T" option (under UNIX) or /TREE (under VMS). These switches take one or more sub-options as arguments, specified as follows: -Toption1,option2,option2, ... under UNIX or /TREE=(option1,option2,option2, ...) under VMS For a list of sub-options, see the next section. 7.2.1 Arguments "-T" and /TREE accept the following sub-options: {no}alphabetic Calls are normally listed using the order in which they occur. This sub-option sorts call trees alphabetically. The condensed option is recommended, in this mode. {no}condensed Condenses multiple calls to the same routine. If a routine calls the same routine many times, these calls are merged into one call. (For older versions of FORTRAN-lint, this is the default mode.) disable Disables call-tree output. This sub-option has the same effect as "--t" (under UNIX) or /NOTREE (under VMS). enable Enables call-tree output. This sub-option has the same effect as "-t" (under UNIX) or /TREE (under VMS). graphics=xx:xx:... Changes the tree graphics characters. The values given are the hex codes for the following shapes: (1) (2) (3) (4) (5) | | | ----- | --+-- +-- +-- | | | The values are two-digit hex codes separated by colons. For example, if the IBM extended character set is available, the following values may be used: graphics=C4:B3:C2:C3:C0 nographics Restores the default graphics characters (- | + + +). head:symbol Suppresses the full call tree and shows a call tree with the specified symbol as the top node. Multiple top nodes may be specified. help Outputs a help screen describing tree sub-options and terminates FORTRAN-lint. {no}library Shows calls made to routines defined in library template (.lbt) files. For additional information, see chapter 9. {no}squish Compresses call trees vertically by removing excess line graphics. The resulting trees are less readable, but require only half the space. {no}trim Trims the call tree by suppressing repeated subtrees. This is the default mode of operation. notrim may be used to disable trimming. Note: "notrim" may produce call trees which require a significant amount of disk space. {no}undefined Shows calls made to routines that are undefined in the source code or libraries. ---------------------------------------------------------------------- 7.3 Call Tree Format The call tree displays routines, subroutine calls, and function references in a graphical format. The starting routine is shown at the left top of the graph, and each level of routine calls is shown to the right of the calling routine. Each routine is connected to its called routines by lines drawn from dashes, vertical bars, and plus signs. Within each routine, calls are shown in the order they appear in the source code. Routines which are not the program routine and are not called by any other routine are considered "detached". They will not appear in the main tree, but will be shown as the head of their own detached trees. Symbol Explanation ( ) Parentheses are used to flag undefined routines { } Braces are used to mark library routines (from ".lbt" libraries) [ ] Square brackets are used to mark Fortran 90 internal sub- programs @ Precedes calls to dummy routines ** Marks recursive chains that are chopped after the first iteration 7.3.1 Trimmed Trees The size of call trees grows exponentially with program size. This makes generating a complete call tree of a large program impractical, if not impossible. To "trim" a call tree, FORTRAN-lint removes duplicate subtrees. This brings the size of the tree down to a reasonable level. At each "trim" point, FORTRAN-lint prints a subtree number which indicates where a master copy of the associated subtree can be found. The default FORTRAN-lint configuration file includes the option "-Ttrim"; trees are therefore trimmed by default. Example: PROCDAT-+-GETUNIT | +-READNAME | +-SETTYPE--PRINT (1)--PRINTIT-+-DIPSTAT--*PRINT* | | | +-GETUNIT | +-PRINT see 1 7.3.2 Condensing Multiple Calls By default, call trees show all of the calls made inside a given program. If one routine calls another several times, every call is displayed. To produce a call tree based on the relationship between routines rather than the exact calling sequence, use the option "-Tcondensed" (under UNIX) or /TREE=CONDENSED (under VMS). The "con- densed" option merges multiple calls from one routine to another into a single association. Example: PROCDAT-+-GETUNIT | +-READNAME | +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT* | | | +-GETUNIT | +-PRINT--PRINTIT-+-DIPSTAT--*PRINT* | +-GETUNIT 7.3.3 Sorting Alphabetically Calls are normally shown in order of appearence. To sort calls alphabetically (by routine name), use "-Talphabetical,condensed" (under UNIX) or "/TREE=ALPHABETICAL,CONDENSED" (under VMS). Example: PROCDAT-+-GETUNIT | +-PRINT--PRINTIT-+-DIPSTAT--*PRINT* | | | +-GETUNIT | +-READNAME | +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT* | +-GETTING 7.3.4 Squished Trees Call trees are normally double-spaced to improve readability. To produce single-spaced trees, use the option "-Tsquish" (under UNIX) or /TREE=SQUISH (under VMS). Limitations of the ASCII character set make single-spaced trees harder to read. If an extended ASCII character set with line-drawing characters is available, the graphics option should be used in conjunction with squish. For additional information, see section 7.3.5. Example: PROCDAT-+-GETUNIT +-READNAME +-SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT* | +-GETTING +-PRINT--PRINTIT-+-DIPSTAT--*PRINT* +-GETTING 7.3.5 Graphic Character Set By default, the call tree uses the ASCII characters "-", "|", and "+" to connect the routine names. To specify alternate characters, use: -Tgraphics=xx:xx:xx:xx:xx under UNIX or /TREE=(GRAPHICS=xx:xx:xx:xx:xx) under VMS where the xx entries are ASCII character codes expressed as two-digit hexadecimal values. The five entries are interpreted as follows: (a) 1st code: horizontal connector (b) 2nd code: vertical connector (c) 3rd code: T intersection (d) 4th code: "|-" intersection (e) 5th code: L intersection For example, if the IBM extended character set is available, use c4:b3:c2:c3:c0. The default values are 2d:7c:2b:2b:2b, for the characters -, |, +, +, and +. To restore the default values, use "-Tnographics" (under UNIX) or /TREE=NOGRAPHICS (under VMS). ---------------------------------------------------------------------- 7.4 Call Tree Content 7.4.1 Top Node Call trees can be generated with any routine as the top routine. When the top routine is selected, the full tree and detached trees are suppressed. To generate a tree starting at the routine name, use the option switch "-Thead:name" (under UNIX) or /TREE=HEAD:name (under VMS). To display multiple trees, specify multiple routine names. For example: -Thead:PRINT,head:SETTYPE under UNIX or /TREE=(HEAD:PRINT,HEAD:SETTYPE) under VMS will show trees for both "PRINT" and "SETTYPE": FORTRAN-lint (call tree) This is a primary tree starting at the program 'PRINT' PRINT--PRINTIT-+-DIPSTAT--*PRINT* | +-GETTING This is a primary tree starting at the program 'SETTYPE' SETTYPE--PRINT--PRINTIT-+-DIPSTAT--*PRINT* | +-GETTING To cancel a previously-specified "-Thead" (or /TREE=HEAD) switch, add "-Tnohead" (under UNIX) or /TREE=NOHEAD (under VMS) to the command line. This will restore the full call tree. 7.4.2 Undefined Routines Call trees normally include all calls, whether or not the called routines are defined in the current input files. FORTRAN-lint uses parentheses to flag undefined routines. To suppress calls to undefined routines, use "-Tnoundef" (under UNIX) or /TREE= NOUNDEF (under VMS). If these options are used, call trees will be restricted to calls between routines defined in the current input files. To restore the default mode of operation (e.g., if "-Tnoundef" was set in a configuration file), use "-Tundefined" (under UNIX) or /TREE=UNDEFINED (under VMS). 7.4.3 Library Routines If "library" (.lbt) files are specified on the command line, call trees will include calls to the associated library routines. FORTRAN- lint uses curly braces ({}) to flag library calls. Calls to library routines will be displayed whether or not the noundef sub-option is used (see section 7.4.2). However, calls between library routines are not displayed, in either case. To generate call trees which exclude library calls, use "-Tnolib" (under UNIX) or /TREE=NOLIB (under VMS). To restore the default mode of operation, use "-Tlibrary" (under UNIX) or /TREE= LIBRARY (under VMS). For additional information on library files, see chapter 9. ---------------------------------------------------------------------- 7.5 Recursion FORTRAN-lint uses a pair of astericks to flag recursive calls. For example: See *PRINT* in section 7.4.1. ---------------------------------------------------------------------- 7.6 Dummy Routines FORTRAN-lint uses "@" characters to flag indirect calls; i.e., calls to a routine which are made indirectly through the argument list of another routine. ---------------------------------------------------------------------- 7.7 Entry Points The ">" symbol in a call tree indicates that the call was made through an entry point. For example: | +-ENTRPT>SUB1 | where ENTRPT is the entry point into subroutine or function SUB1. ---------------------------------------------------------------------- 7.8 Fortran 90 Internal Subprograms Square brackets ([ ]) surrounding a routine name indicate that the routine is a Fortran 90 internal subprogram or a module subprogram: MAIN-+-M | +-M_INNER | +-OUTER--M | +-[MAIN_INNER] Chapter 8 Cross Reference 8.1 Overview To generate a symbol table cross-reference, use the option "-x" (under UNIX) or /XREF (under VMS). Cross-reference tables can be generated from source files or from database files (see chapter 10). The option switches "-X" and /XREF may be used to specify sub-options that control the format and content of the cross-reference table. The UNIX cross-reference format/content sub-options are: -Xfreeform Free-form cross-reference -X{no}tabular Selects tabular format (vs. freeform) -X{no}equiv Selects equivalence usage information -X{no}line Line resolution (vs. subprogram resolution) -X{no}legend Selects legend for line resolution codes The VMS cross-reference format/content sub-options are: /XREF=freeform Free-form cross-reference /XREF={no}tabular Tabular format (vs. freeform) /XREF={no}equiv Selects equivalence usage information /XREF={no}line Line resolution (vs. subprogram resolution) /XREF={no}legend Selects legend for line resolution codes Two cross-reference formats are supported: freeform and tabular. freeform is the default format. This format uses variable-length lines and shows information using a compact layout. The default sub-options for this format are "-Xnoline" and "-Xnolegend" (under UNIX) or /XREF=noline and /XREF= nolegend (under VMS). The tabular cross-reference format organizes fields into columns. This format is at least 132 characters wide. The default sub-options for tabular cross-references are "-Xline" and "-Xlegend" (under UNIX) or /XREF=line and /XREF=legend (under VMS). The line or noline sub-option sets the cross reference to either line resolution or subprogram/program unit resolution, respectively. Subprogram/program unit resolution shows usage of a symbol within a subprogram/program unit, while line resolution shows usage of a symbol on each line in which that symbol appears. This must be set during source analysis to have effect. If the "-g" (or /GLOBAL) option is used, the cross-reference will include additional information. Specifically, dummy argument usage is shown for subroutine and function definitions. In addition, the usage of the variables and arrays that are passed as actual arguments are determined. ---------------------------------------------------------------------- 8.2 Layout Symbols are grouped into the following categories: programs block data subprograms/program units subroutines functions modules (F90 only) common blocks structures records variables and arrays parameters Symbols are sorted alphabetically by name within each group. If a symbol appears in more than one context (e.g., as a variable in one subprogram /program unit and as a subroutine name in another), the symbol is shown in both groups. In the tabular format cross reference, the program, block data, module (F90 only), subroutine, and function sections are combined, as are the records and variable/array sections. The information shown for each symbol will vary by category. 8.2.1 Program Routines This symbol name is derived from the program name given on a program statement. If an unnamed program routine exists, it is given the name "Program". Multiple unnamed programs are named "Program2, Program3, ..., etc.". The filename and the line number where the program routine begins are shown along with the program name. 8.2.2 Block Data Routines These are the symbol names from block data statements. Like program symbols, unnamed block data subprograms/program units are named "Blockdata", "Blockdata2", etc. The filename and the line number where the block data subprogram/program unit begins are shown along with the block data name. 8.2.3 Subroutines and Functions External procedures, internal procedures (F90 only), module procedures (F90 only), intrinsic procedures, and statement functions are shown in this section and are labeled correspondingly. For functions, the data type is shown. This is normally the data type of the function definition. If the function is undefined, the data type used by the first function call is used. An internal subprogram (F90 only) has its parent routine as a qualifier using a double colon (::); for example, SUB::SUB_INNER. If the code for the subroutine or function appeared in the sources analyzed, the filename and line number of the subroutine/function statement are shown. If the definition was in a FORTRAN-lint library (.lbt) file, the name of the library is shown. Argument descriptions of external, internal, and statement functions are also shown if the "-g" or /GLOBAL option was used during analysis. The argument descriptions show the class, data type, and usage of each argument. Argument class is one of the following: variable array variable or record array subprogram function or subroutine return alternate return --- unused argument Argument usage is indicated by the single-letter codes listed below: Code Description ---- ----------------- S set R referenced (used) X undetermined For external and internal subroutines and functions, called routines are shown. If the table is in tabular format, the line number of each call is shown. Finally, all calls to the function, subroutine or F90 module are listed. In the tabular cross reference, the locations of the calls are shown by subprogram/program unit, filename, and line number in the References columns. 8.2.4 Modules (F90 only) These are the symbol names from module statements. The filename and the line number where the module subprogram/program unit begins are shown along with the module name. Modules referenced by this module are shown. If the table is in tabular format, the line number of each module reference is shown in the Calls column. Finally, all references to the module via USE association are listed. In the tabular cross reference, the locations of the calls are shown by subprogram/program unit, filename, and line number in the References column. 8.2.5 Common Blocks Common blocks are shown along with their size (in bytes) and a list of their members. The routines that the common blocks appear in are shown, categorized into the following groups: model the definition used for comparison (shown as "same" if freeform) same same declaration as the model names differ member types and sizes match model but have different names layout differs member types or sizes do not match the model 8.2.6 Structures and Structure Components The cross-reference lists all structures used by the program, including their size, format, and members. Structures of the same name, size, and format are merged. If the linenumbers or tabular format is selected, the cross-reference also includes a section labelled "Structure components" which lists occurrences of structure components. For additional information on the linenumbers and tabular formats, see section 8.3. 8.2.7 Variables, Arrays, and Records Variables, arrays, and records are shown in this section. This includes automatic (local), dummy, common block members, and F90 module entities. Arrays are distinguished by the dimension list. Each dimension is shown as either an upper bound or a lower/upper bound pair separated by a colon. If the lower or upper bounds are adjustable, "adj" appears. For open-ended dimensions, an asterisk ("*") appears as the upper bound. The Type column shows the data type including a length specifier for symbols or the name of the associated structure for records. The Kind column shows the kind parameter of the symbol, if specified. The Attributes column shows the attributes of each symbol. Attributes include local, pointer, pointer based, and common block members. Common block members are shown with the name and byte offset of the common block to which they belong. The References column shows the cross reference information for each symbol. The location resolution is either per subprogram/program unit or per line, depending on the setting of the "-Xlinenumbers" or /XREF=linenumbers option when the sources are analyzed. Subprogram/program unit resolution will show usage within each sub program/program unit and is described in words. Line resolution will show usage for each line the symbol appears on, and its usage is described in single-letter codes. Symbol usage is described as one or more of the following: Line Subprogram Description resolution resolution codes codes ---------- ---------- --------------------------------------- --- Unused Symbol was not referenced, set, or in- determinate A Actual arg Symbol passed as an actual argument B Array bound Symbol was used as an adjustable bound for an array D --- Symbol appeared in a declaration (type decl, dim, common) E Equivalenced Appeared in an equivalence statement F SF Dummy arg Appeared as a statement function dummy argument G Ref as Label An assigned goto jumped to label as- signed to this symbol I Indirect Init A symbol Equivalenced to this symbol was initialized I Initialized Initialized in data statement, or when given data type L Set to Label Symbol was assigned a label M Allocated Symbol was allocated N Nullified Symbol was nullified O Optl dummy arg Symbol appeared as an optional dummy argument P Dummy arg Symbol appeared in a subroutine or function statement R Ref Symbol was referenced (its value was used) S Set Symbol was assigned a value X Indeterminate May be ref or set, but exact usage can- not be determined Z Deallocated Symbol was deallocated Usage information (Ref/Set) is carried through all variable associations, including actual/dummy argument, common block member, and equivalence associations. The default is to suppress unused common blocks. For additional information, see section 8.4. 8.2.8 Parameters Parameters are shown along with their data type and their value. Parameters from different routines that have the same name and the same value will be merged. The following usage codes apply to parameters: Line Subprogram Description resolution resolution codes codes ---------- ---------- --------------------------------------- D --- Symbol appeared in a declaration (type decl, parameter) R Ref Symbol was referenced (its value was used) S Set Symbol was assigned a value (parameter statement) The default is to suppress unreferenced parameters. For additional information, see section 8.4. 8.2.9 Equivalences Entries for variables include equivalence information. For non-common block members, equivalences are named variables in the same scoping unit or the parent scoping unit. For common-block members, equivalences belong to the same common block. Note: When a variable is equivalenced to an array element, FORTRAN- lint recognizes only the array name as an equivalence. Consequently, when two variables that are not common block members are equivalenced to different elements of the same array, FORTRAN-lint will show the two variables and the array as the equivalence of one another. In case of two different scalar members of the same common block that are equivalenced to different array elements of the same array, FORTRAN- lint will show the array as the equivalence of both scalar members. 8.2.10 High Performance Fortran (HPF) If HPF checking is enabled, and if the linenumbers or tabular format is selected, the cross-reference includes a section which displays occurrences of HPF processors and templates. For additional information on HPF, see section 4.9. For additional information on the linenumbers and tabular formats, see section 8.3. ---------------------------------------------------------------------- 8.3 Format Selection FORTRAN-lint allows users to select different formats for the cross reference table by using the "-X" option (under UNIX) or /XREF (under VMS). Available formats include: -Xfreeform /XREF=freeform -X{no}tabular /XREF={no}tabular -X{no}equiv /XREF={no}equiv -X{no}linenumbers /XREF={no}linenumbers -X{no}legend /XREF={no}legend A) freeform / tabular "-Xtabular" (under UNIX) or /XREF=tabular (under VMS) selects a table style that uses fixed-width columns. The output is 132 or more columns wide. The default line numbering mode for this format is "-Xlinenumbers" (under UNIX) or /XREF=linenumbers (under VMS). "-Xfreeform" (under UNIX) or /XREF=freeform (under VMS) selects a more compact style with fields separated by single spaces. The default line numbering mode for this format is "-Xnolinenum" (under UNIX) or /XREF=nolinenum (under VMS). B) equiv / noequiv By default, the cross-reference entry for a given variable in- cludes usage information for the associated equivalences, whether or not the variable is used directly. To suppress equivalence usage information, use "-Xnoequiv" (under UNIX) or /XREF=noequiv (under VMS). C) linenumbers / nolinenum To produce cross-reference tables with line numbers, use "-Xlinenumbers" (under UNIX) or /XREF=linenumbers (under VMS). To limit cross-reference tables to the subprogram/program unit level, use "-Xnolinenum" (under UNIX) or /XREF=nolinenum (under VMS). Note: To be effective, linenumbers or nolinenum must be specified after "-Xtabular", "-Xfreeform", /XREF=tabular, or /XREF=freeform on the command line. D) legend / nolegend If linenumbers is selected, FORTRAN-lint prints single-character usage codes along with line numbers. Usage codes are described in a legend printed at the end of the cross-reference. To suppress the legend, use "-Xnolegend" (under UNIX) or /XREF= nolegend (under VMS). To restore the legend (if it has been disabled), use "-Xlegend" (under UNIX) or /XREF=legend (under VMS). Note: To be effective, legend or nolegend must be specified after "-Xtabular", "-Xfreeform", /XREF=tabular, or /XREF=freeform on the command line. ---------------------------------------------------------------------- 8.4 Content Selection "-X" and /XREF both accept content selection arguments. Content selection arguments are sentence fragments composed of one to six words, separated by underlines or dashes. Each sentence fragment describes a criterion that can be used to select, add to, or filter cross-reference output. A complete content selection includes the following words as its arguments: under UNIX: -X{conjunction}{_usage}{_scope}{_class}{_named_xxx} under VMS: /XREF={conjunction}{_usage}{_scope}{_class}{_named_xxx} CONJUNCTIONS USAGE (ADJECTIVE) SCOPE (ADJECTIVE) CLASS (NOUN) only used/unused local (*) routines and ref/unref dummy/non... programs no set/unset statement/non... subroutines called/uncalled intrinsic/non... functions indeterm/determ global (*) blockdata actual/notactual common/non... modules init/uninit external/non... extern decl/undecl internal/non... (*) blocks equiv/unequiv structures variables scalars arrays records parameters Note: The default conjunction is "only". (*) dummy or nondummy, common or noncommon, internal or noninternal, etc. While any of the words composing the criteria sentence are optional, the order of the words is significant. All words may be abbreviated, as long as they remain unambiguous. A few examples are: Example Result ------------------------ ------------------------------------------ -Xno_unused_variables Suppress unused variables -Xand_par_named_+oo Also show parameters with names ending in "oo" -Xonly_ref_dum_var_nam_i Show referenced dummy variables named "i" /XREF=common_arrays Show arrays in common blocks /XREF=arr_named_a?b+c Show arrays named a{any-letter}b{zero-or-more-letters}c (1) The conjunction, if specified, must be first. This word specifies whether the criteria sentence is a selection, filter, or addition. The default mode of operation is "ONLY". Word Type Description ---- --------- ------------------------------------------------- ONLY selection suppress everything but the following (default) NO filter suppress the following AND addition add the following to what is already selected (will not be subject to previous filter criteria) (2) The usage adjective, if specified, must be next. This word acts on symbols at the subprogram/program unit level. If a symbol is used in a particular subprogram/program unit in the fashion described by the usage adjective, the use of that symbol within the subprogram/program unit is included in the selection. If the usage adjective is omitted, FORTRAN-lint disregards usage when determining the selection. Word Antonym Description ------------- -------------- --------------------------------- used unused Referenced, set, called, or inde- terminate) referenced unreferenced set unset called uncalled indeterminate determinate actualarg notactualarg Variables passed to external rou- tines initialized uninitialized declared undeclared Data type, dimensions, or common equivalenced unequivalenced Filtering acts on references at a subprogram/program unit level, filtering out the references to a symbol that match the filter criteria. If all references to a symbol are filtered out, the symbol itself is suppressed. (3) The scope adjective, if specified, must be next. This is used in a similar fashion to the usage adjective but relates to the scope of the symbol. If the scope adjective is omitted, scope is not used in determining the selection. Word Antonym Description ------------- -------------- --------------------------------- local --- Dummy, Statement, Intrinsic, or Automatic dummy nondummy Dummy argument statement nonstatement Statement function intrinsic nonintrinsic Intrinsic function global --- Common or External common noncommon Common block or common block mem- ber external nonexternal External routine (4) The class noun, if specified, must be next. This specifies the class of the symbol. The class noun describes categories of symbols. If the class noun is omitted, the selection contains all categories of symbols limited by the usage and scope adjectives. Class Subclasses Description ---------- ----------- ---------------------------------------- routines Programs, subroutines, etc. programs subroutines Includes dummy subroutines functions Includes statement, dummy, and intrinsic functions blockdata external External routines which are undefined and unused blocks --- Common blocks structures --- variables Includes scalars, arrays, and records scalars Single-valued variables arrays records Structured records parameters --- Defined in parameter statement (5) The symbol name is specified last. This is composed of two words, the word "named" followed by the actual symbol name. The following wildcards are allowed: * or + matches zero or more characters ? or . matches one character Wildcards may be combined. Example: -Xnamed_ab+f.h under UNIX or /XREF=named_ab+f.h under VMS The default content of the cross reference table is everything except unused common variables and unreferenced parameters. UNIX examples: -Xno_intrinsic Suppress intrinsic functions -Xuncalled_routines Only routines that have not been called -Xand_unused_parameters Show unused parameters, too -Xno_unused_common_variables Don't show declarations of common varia- bles where they are unused (if a symbol is never used, its name does not appear) VMS examples: /XREF=routines Only show routine names /XREF=no_common Suppress common blocks and common block members /XREF=unset_functions Show only undefined functions /XREF=unused_dummy_arrays Show array dummy arguments that are unused Multiple phrases may be given; these are checked in order from left to right. The phrases may be either on the same option or on separate options. UNIX example: -Xset_variables -Xno_unref_common_arrays -Xand_init_common_var This will show set variables that are not unreferenced array common block members and any common block members that are initialized. VMS example: /XREF=routines,and_common_blocks This will show routines and common blocks. Remember, the default conjunction is "only". The following combination will produce unexpected results: -Xused_variables -Xequivalenced_variables under UNIX or /XREF=used_variables /XREF=equivalenced_variables under VMS If the intent is to produce a cross-reference table with only variables that are used or equivalenced, the above command line option will not work. The second argument (equivalenced_variables) will override the first argument (used_variables), since the default conjunction is "only". The cross-reference table produced by this option will only include equivalenced variables. To perform the desired operation, use: -Xused_variables -Xand_equivalenced_variables under UNIX or /XREF=used_variables /XREF=and_equivalenced_variables under VMS Chapter 9 Library Support 9.1 Overview FORTRAN-lint can be used to create library template (or ".lbt") files for use in subsequent analysis operations. A library template (or ".lbt") file is a binary file which describes the interface structure of one or more FORTRAN subroutines or functions. ".lbt" files contain FORTRAN "stubs" which are similar in concept to ANSI 'C' prototypes. ".lbt" files may be used to speed up interface checking where a project depends on a stable (unchanging) library or package. Adding a single ".lbt" file to the FORTRAN-lint command line is effectively the same as adding all of the associated FORTRAN source files. Two pre-defined ".lbt" files unixlib.lbt and vmslib.lbt are provided with FORTRAN-lint. unixlib.lbt and vmslib.lbt describe standard UNIX and VMS library routines, respectively. If system library routines are used (and if these routines are not defined in user-specified ".lbt" files), FORTRAN-lint searches unixlib.lbt or vmslib.lbt automatically. ---------------------------------------------------------------------- 9.2 Creating Library Files To create or update an ".lbt" file, use commands of the form: flint -L mylib.lbt file1.f file2.f ... under UNIX or flint /LIBRARY=mylib.lbt file1.for file2.for ... under VMS These commands add all routines in the specified source files to the file mylib.lbt. If mylib.lbt does not exist, it will be created. Otherwise, the existing file will be updated. The "-L" and /LIBRARY options cause FORTRAN-lint to run in a special mode which bypasses normal analysis. Consequently, source files must be debugged and error-free before ".lbt" files are created. If a library routine is modified, repeat the original "-L" or /LIBRARY operation to update the associated ".lbt" file. Note that FORTRAN-lint will not update ".lbt" files automatically. ---------------------------------------------------------------------- 9.3 Library Precedence For analysis purposes, FORTRAN-lint searches for definitions as fol- lows (highest precedence first): (1) Definitions found in FORTRAN source files (2) Definitions found in the intrinsic table for the current tar- get system (3) Definitions found in user-specified ".lbt" files (4) Definitions found in unixlib.lbt or vmslib.lbt By default, the intrinsic table takes precedence over user-specified ".lbt" files. To search user-specified ".lbt" files before the intrinsic table, use the option "-Muselbt" (under UNIX) or /MISC=uselbt (under VMS). If uselbt is specified, FORTRAN-lint uses the following search order: (1) Definitions found in FORTRAN source files (2) Definitions found in user-specified ".lbt" files (3) Definitions found in the intrinsic table for the current tar- get system (4) Definitions found in unixlib.lbt or vmslib.lbt Note that the default library templates unixlib.lbt and vmslib.lbt have the lowest precedence, whether or not uselbt is specified. ---------------------------------------------------------------------- 9.4 Library Shells Users can create ".lbt" files for specific libraries or packages. FORTRAN-lint provides an option "-L" (under UNIX) or /LIBRARY (under VMS) which translates user-composed library shell (or ".lsh") files into corresponding ".lbt" files. Library shell files are text files which contain FORTRAN "stubs" describing the interface structure of a library or package. The FORTRAN-lint package includes two sample ".lsh" files unixlib.lsh and vmslib.lsh, which may be used as starting points for new shell files. unixlib.lsh is the source file for unixlib.lbt, and vmslib.lsh is the source file for vmslib.lbt. The ".lsh" files may be used to extend the ".lbt" files. To rebuild the ".lbt" files, modify the ".lsh" files as desired and use commands of the form: flint -L unixlib.lbt unixlib.lsh under UNIX or flint /LIBRARY=vmslib.lbt vmslib.lsh under VMS The required elements of a library shell file are: (1) definition of the return value (2) name of the function (3) dummy argument list The data types of the dummy arguments and their usage need to be defined within the shell of the function. Switches on the arguments have been designed to allow FORTRAN-lint to handle the shell more efficiently. Function argument switches may only be used on the arguments in function shells, not in subroutine shells. Available switches include: /v Parameter passed by value. [call foo(%val(3))] /q Suppress error #251 (scalar passed to array) and data type checking. This switch is used to allow binary data to be passed in any form without the data type being checked. For example, a quadword may be passed in any of the following forms: LOG*1 FOO(8), INTEGER*2 FOO(4), or INTEGER*4 FOO(2). /z Suppress all interface checking with regard to this argument. The argument is of unspecified data type. /o This argument is optional. [call foo(a,,b,,c,d)] Optional argument switches: /l (Lower-case ell.) The rest of the argument list (starting with the argument flagged by "/l") is optional. This switch may be used to handle routines with variable-length argument lists. /s This argument is set in the function. /r This argument is referenced in the function. /i This argument is indeterminate. Each "shell" is a simple FORTRAN subprogram/program unit that takes the same arguments as the associated library subprogram/program unit and references or sets these arguments in a similar fashion. The examples below show the structure of some of the FORTRAN library shells found in unixlib.lbt: INTEGER FUNCTION SIGNAL (SIGNUM/r, PROC, FLAG/r) INTEGER SIGNUM, FLAG EXTERNAL PROC CALL PROC END REAL FUNCTION R_COPYSIGN (X/r, Y/s) REAL X,Y END The following example tells FORTRAN-lint that only the first two arguments in the argument list are required; the rest of them are optional. Note that arguments CLASS1, CLASS2, CLASS3, and CLASS4 all need to specify the "/l" switch. INTEGER FUNCTION STUDENT (NAME/r, CREDITS/r, CLASS1/rl, CLASS2/rl, CLASS3/rl, CLASS4/rl) CHARACTER*40 NAME INTEGER CREDITS INTEGER CLASS1, CLASS2, CLASS3, CLASS4 END ---------------------------------------------------------------------- 9.5 Miscellaneous Library Issues 9.5.1 Interaction with Cross Reference and Call Trees Cross-reference tables and call trees automatically include referenced library routines. Cross-reference tables print library names along with routine names. Call trees use curly braces ({}) to flag library routines. 9.5.2 File Format ".lbt" files are revision-locked. FORTRAN-lint will print a warning message if incompatible ".lbt" files are used. Chapter 10 Database Files 10.1 Overview FORTRAN-lint can be used to create database (or ".fdb") files for use in subsequent analysis operations. A database (or ".fdb") file is a binary file which contains symbolic information obtained from one or more FORTRAN source files. Files with the extension ".fdb" are database files generated by FORTRAN-lint during source code analysis. ".fdb" database files contain symbolic information for the modules processed. ".fdb" files may be used to re-generate cross-reference tables, call trees, diagnostic messages, etc., without re-analysis of the original source code. ---------------------------------------------------------------------- 10.2 Creating Database Files To create database files, use the "-B" option (under UNIX) or /DATABASE (under VMS) as follows: flint -Bdbfile foo1.f foo2.f foo3.f ... under UNIX or flint /DATABASE=dbfile foo1.for foo2.for foo3.for ... under VMS dbfile specifies the base name which should be used for the database. The filename extension ".fdb" will be added automatically. If the specified database file already exists, it will be overwritten. To suppress console error messages during database creation, add the option switch "-Oall" (under UNIX) or /SUPPRESS=ALL (under VMS) to the FORTRAN-lint command line. ---------------------------------------------------------------------- 10.3 Using Database Files To extract information from an existing database file, use a normal flint command with the database file as an argument. For example: flint -t dbfile.fdb under UNIX or flint /TREE dbfile.fdb under VMS The command line should not specify any other database files or FORTRAN source files. All call tree options are available when database files are processed. Most of the cross-reference options are available; line is an exception. "-Xline" and /XREF=line are ignored; flint uses the line value set when the database file was generated. Additionally, if "unreferenced parameters" or "unused common block members" are not selected when the database file is created, the associated messages will not be provided by subsequent database queries. ".fdb" files should be regenerated whenever the associated source code is modified. Chapter 11 Xlint Introduction Xlint is a Motif-based programming tool. It is designed to provide FORTRAN developers with an interactive graphical user interface which can be used to browse FORTRAN source files. Xlint operates on the database (or ".fdb") files generated by FORTRAN-lint. With four windows displaying information, Xlint allows the developer to step through potential errors and to see the relationships between source code, call tree and symbol table information, all on one screen. Symbol cross reference information can be automatically brought up, showing all code references to any symbol in the analyzed program. Each occurrence of a symbol can quickly be found in the source code; at the same time, the appropriate node is highlighted in the displayed call tree. Chapter 12 Learning About Xlint This chapter will cover the basics that users need to know before running Xlint and will help them understand the usage and function of the many options available within this product. 12.1 Screen Layout The Xlint screen is made up of four windows and a control panel. The four windows from top to bottom are Source, Lint, Tree, and Cross Reference. They are used to display specific information relating to the current database being analyzed. When information in any of the windows exceeds the size of the window, a scroll bar will appear on the bottom and/or right hand side. Each window can be enlarged or reduced at the expense or benefit of the other windows. The Control Panel bar between the Source and Lint windows contains a text input field and three buttons. Popup menus are supported by all four windows and can be called up by a click of the right mouse button, with the pointer anywhere in the appropriate window. Options in the popup menus can be selected by simply holding down the right button, dragging the pointer to the desired option, and then releasing the button. When the button is released, the option will be set and the menu will disappear. On-screen help is available. A help menu can be called up by a click of the left mouse button on the help option at the top of the Xlint screen. (For figure 12.1, see printed version of manual.) ---------------------------------------------------------------------- 12.2 File Menu The File menu is used to select the database or source file. A submenu with five options can be brought up by a click of the left mouse button. Load Database Used to load a pre-existing database. A database must beloaded before symbol information can be displayed in the windows. View File Used to load an arbitrary file into the Source window. It will stay loaded until an action from another window calls up a different source file. Save File Used to save any edits made to the file in the Source window. Editing must be enabled first. Enable Editing Allows the file in the Source window to be modified and saved. Changes are only saved when the Save File menu item is selected. When the Source window is in the editing mode, the Disable Editing option replaces Enable Editing in the submenu and disallows any editing in the Source window. Quit Exits Xlint. ---------------------------------------------------------------------- 12.3 Search Menu The Search menu allows text searches on the Source window, using the currently-highlighted text as the search string. Previous Searches backwards for the selected text. Next Searches forwards for the selected text. Go To Line Uses the selected text as the line number and goes to that line. For example, if the highlighted text is the number "27", then if line 27 exists, the program cursor moves to the 27th line. ---------------------------------------------------------------------- 12.4 Build Menu The Build menu is used to create or update a database (.fdb) file. The status field on the control bar shows the status of the most recent rebuild. Configure Used to select the name of the database, the source files, and options used during source processing. Rebuild Runs FORTRAN-lint with the configured options and files to regenerate the database file. Kill Rebuild Process Stops the source processing; available only during a re- build. Use Rebuilt Database Loads the database that was last rebuilt by the Rebuild menu selection. This has the same effect as loading the database from within the File menu. View Build Output Pops up a window that shows the output from FORTRAN-lint during the rebuild process. The FORTRAN-lint output can be used to determine why a "build" operation failed. ---------------------------------------------------------------------- 12.5 Source Window The source code currently being analyzed is displayed in this window. Action in other windows will cause files to load automatically and jump to the appropriate point in the source. A lookup can be performed on highlighted items that can affect the Tree and Cross Reference windows. The popup menu can be used to select the source related to what is currently highlighted in the other windows. With these options, users can step through the cross reference entries one by one or repeat a text search with a click of the mouse. Previous Xref Goes to the text referred by the cross reference entry one before the current highlight in the Cross Reference window. Current Xref Goes to the text referred by the cross reference entry currently highlighted in the Cross Reference window. Next Xref Goes to the text referred by the cross reference entry one after the current highlight in the Cross Reference window. Previous Text Goes to the previous occurrence of the text currently highlighted in the Source window. Next Text Goes to the next occurrence of the text currently highlighted in the Source window. Lint Goes to the text referred by the lint message currently highlighted in the Lint window. Note: If the Lint window is currently in the "summary" mode, the cursor in the Source window will not be affected. Tree Goes to the function or subroutine currently highlighted in the Tree window. ---------------------------------------------------------------------- 12.6 Lint Window The current FORTRAN-lint analysis messages pre-generated by FORTRAN-lint are displayed in this window. When a database is initially loaded, a summary of the FORTRAN-lint source analysis is shown. Double-clicking an item in the summary calls up the actual instances of that message. Double-clicking a message instance causes lookups in the other windows specified for action in Lint's popup menu. Summary Shows a summary of FORTRAN-lint analysis output. Example: IMPLCT #125 7x: symbols were implicitly typed as *: * where 7x means that there are 7 instances of such message. All Messages Shows all the actual message instances of the FORTRAN-lint source analysis. Each message includes the line number, the subroutine it belongs to, the message number, and the message itself. Example: demo.f(33)[PRINT] #125: symbols were implicitly typed as I*4: IUNIT Action The Action popup menu determines which of the other windows are influenced by actions taken in the Lint window. If a message is double-clicked in the Lint window, depending on the selections in the Action popup menu, one or more of the other windows is changed to reflect the new selection. The Tree window will change to reflect the routine where the message was reported. The Cross Reference window will change to reflect symbol information associated with the message. By default, both Cross Reference and Tree are selected. ---------------------------------------------------------------------- 12.7 Tree Window This window contains a graphical representation of the program's "call" structure, centered around a given routine. Each node of the call tree represents a routine. The selected routine is placed in the center. The routines to the left and right are the predecessors and descendants of the selected routine, respectively. Clicking a node will highlight it and make it selectable from the popup menus of the other windows. Double-clicking a node will recenter the tree around that node. Double-clicking a node while holding the Shift key (double-click) will cause lookups in the other windows specified for action in the Tree's popup menu. The popup menu in the Tree window allows the tree root to be set from the current routine in the Source, Lint, or Cross Reference window. Selected Routine Uses the currently highlighted routine name from the Source window or the text input field. Routine Containing Lint Redisplays the Tree window with a tree centered around the routine containing the current lint message. Routine Containing Xref Redisplays the Tree window with a tree centered around the routine containing the current Cross Reference entry. Action Selects the affected windows when a shift double-click is done on a tree routine. By default, the Source and Lint windows will reflect the change on the Tree window. ---------------------------------------------------------------------- 12.8 Cross Reference Window The Cross Reference window contains a cross-reference for the selected symbol. Symbols may be selected by name and may contain wildcard characters. The cross reference entries are filtered by the settings in the Xref Filter selection box in the Control Panel (see next section). The folllowing wildcard characters are accepted: * zero or more characters ? any character Double-clicking a cross reference entry calls up the source and/or call tree related to that entry, depending on the action settings. Options available in the popup menu are as follows. Lookup Selected Symbol Looks up the symbol currently highlighted in the source window. Lookup Tree Routine Allows users to look up the cross reference messages related to the routine currently highlighted in the Tree window. Lint References Shows cross-reference information regarding the lint message highlighted in the Lint window. Action Determines the affected windows when a double-click is done on a cross-reference entry. ---------------------------------------------------------------------- 12.9 Control Panel The control panel bar between the Source and Lint windows has four labels which will perform various functions. A description of each option follows: Select Allows the user to type in a symbol in the field next to the Select option for lookup. To perform the lookup, the user can either hit return at the end of the text or click on the Lookup button. Lookup Uses the highlighted text from the Source window to affect the windows selected for action by the Source window's popup menu. If no text is highlighted, the text specified in the Select field to the left will be used. If text is entered into this Select field and is pressed, the entered text is used regardless of what is highlighted in the Source window. Xref Filter Calls up a selection box to select the types of symbols to show in the Cross Reference window. Any number of qualifiers may be selected. Tree Brings up a selection box to set the "parent" and "child" depths of the call tree to be displayed in the Tree window, as well as condensing multiple calls. Parent depth is the number of levels shown upward in the call stack in relation to the selected tree routine. Child depth is similar, but in a downward direction. The toggle for Condense mode causes multiple calls from one routine to another to be shown as one link, rather than duplicated. Library includes the library routines defined in ".lbt" files. Undefined shows all routines which are called, whether or not they are defined in the current input files. ---------------------------------------------------------------------- 12.10 Mouse Functions The functions of the mouse are consistent with standard Motif usage. Left button Used to select menu options and buttons; can also be used to highlight or mark text in the Source window. Highlighting is accomplished by pointing to the beginning of the text the user wishes to mark and, while holding the left button down, dragging to the end of the text and then releasing the left button. Middle button Used to paste highlighted text at the current cursor location or text prompt. Pasting or inserting cannot be done into the Source window. Right button Used to call up the popup menus and select the options in these menus. Chapter 13 Database Files and Xlint 13.1 Overview As explained in chapter 10, database (or ".fdb") files are binary files which contain symbolic information for one or more FORTRAN source files. Xlint uses the information stored in ".fdb" files to browse the associated source files and/or analysis output. Database files may be created from the command line (using FORTRAN- lint), or they may be generated inside Xlint. For the command-line procedure, see section 10.2. Section 13.3 covers the Xlint proce- dure. Note: This chapter assumes that the environment variable (or VMS logical) XLINTPATH is set properly. If Xlint is being run from a directory other than the directory which contains project sources, XLINTPATH should point to the directory which contains the sources. ---------------------------------------------------------------------- 13.2 Loading Database Files Before Xlint can be used, a database (".fdb") file must be loaded. To load a database file inside Xlint, proceed as follows: 1) Select the File menu from the options at the top of the screen. 2) Select Load Database from the File menu. This will bring up a dir- ectory and file selection screen. 3) Select the appropriate directory. To select the desired ".fdb" file, double-click the file or click the file to highlight it and then click OK. The "lint" summary for the specified ".fdb" file should appear in the Lint window. Alternatively, a database file may be specified on the Xlint command line. For additional information, see section 15.3. ---------------------------------------------------------------------- 13.3 Rebuilding Database Files under Xlint The Build menu on top of the Source window can be used to rebuild an existing database (or to create a new one). The "build" procedure is as follows: 1) Select Configure on the Build menu. Enter the database name (without the ".fdb" extension) in the Database field. Enter the associated source file names in the Source Files field. Set the other options as desired. (See figure 13.1) 2) Select Rebuild on the Build menu. The Status field in the Control Panel may be used to monitor "build" status. 3) When the Status field shows "Rebuilding completed", the new data- base may be loaded. (To do this, select Use Rebuilt Database on the Build menu.) Users may also see the FORTRAN-lint output by using the View Build Output on the Build menu. If the "build" failed, View Build Output can be used to determine the cause. (For additional information, see section 12.4.) (For figure 13.1, see printed version of manual.) Chapter 14 Xlint: Getting Started 14.1 Configuration Setup For installation instructions, see appendix H or I. In particular, note that a "resource file" should be copied to the appropriate directory. (For additional information on resource files, see the installation instructions and chapter 16.) Also note that three UNIX environment variables (or VMS logicals) should be set for each Xlint user: XLINTHOME Path for the directory which contains the Xlint support files. XLINTHOST Network name (or node name) for the system running the Xlint license manager. XLINTPATH Path for the directory which contains the user's FORTRAN source files. ---------------------------------------------------------------------- 14.2 Running Xlint Before Xlint can be used, the user must create a project database (or ".fdb" file). For additional information, see chapters 10 and 13. To run the browser, enter the command xlint: xlint The Xlint menu will appear, along with four empty windows. Next, use Load Database on the File sub-menu to load the appropriate database. (For additional information, see section 13.2.) After the ".fdb" file is loaded, source-analysis output will appear in the Lint window. To display all lint messages, scroll through the lint message summary. To display all occurrences of a given message, double-click the message. The Lint window will be updated appropriately. For detailed information on a given occurrence, double-click the occurrence. Xlint will display related source code, call tree output, and cross-reference information. For on-screen help, click the left mouse button on the Help field in the upper right corner of the Xlint screen. To load another database, select Load Database on the File menu. To exit Xlint, select Quit on the File menu. ---------------------------------------------------------------------- 14.3 Sample Sessions The FORTRAN-lint / Xlint package includes sample FORTRAN 77 and Fortran 90 project files. The sample FORTRAN 77 files include demo.for (an F77 source file) and demo.fdb (the associated database file). demo.for may be used to rebuild demo.fdb; for additional information, see section 13.2. Similarly, the sample Fortran 90 files include demo90.for (an F90 source file) and demo90.fdb (the associated database file). demo90.for may be used to rebuild demo90.fdb. Session 1: 1) Under the FORTRAN-lint / Xlint installation directory, run: xlint demo.fdb This will bring up the Xlint menu and analysis output for demo.fdb. 2) To find all symbols starting with "I", enter "I*" in the Select field on the Control Panel and press . This will bring up cross reference information for all variables beginning with the letter "I". 3) To bring up information related to a specific symbol, double-click the appropriate line in the Cross Reference window. For example, to display information related to the variable "INUIT", double- click the following line: INUIT,I*4 variable,in demo.f(43)[PRINTIT] is Set,Actual arg The Source window should display demo.for with line 43 (containing INUIT) highlighted. The Tree window should display a tree centered around the PRINTIT routine. (See figure 14.3) 4) Double-click another cross reference entry. For example: I, I*4 variable, in demo.f(6)[PROCDAT] is Ref Note the changes in the Source and Tree windows. Session 2: 1) Run: xlint This will bring up the Xlint menu with four empty windows. 2) Click on File in the upper left corner of the screen. Select Load Database to bring up the Load Database dialog box. Use the Direct- ories and Filter options to go to the FORTRAN-lint / Xlint instal- lation directory. Double-click demo.fdb to select it or single- click to highlight demo.fdb and press OK. Xlint should display analysis output for "demo.for" in the Lint window. 3) To display all the occurrences of a particular lint message, double-click the message with the left mouse button. For example, double-click the following message: IMPLCT #125 7x: symbols were implicitly typed as *: * to display all occurrences of IMPLCT #125. Note that 7x means that there are 7 instances of this message. 4) After all instances are displayed, double-clicking one of the in- stances will display information related to the instance. For example, double-click the following instance: demo.f(33)[PRINT] #125: symbols were implicitly typed as I*4: IUNIT The Source window should display source code with the highlight on IUNIT in line 33. The Tree window should display a call tree cen- tered around the PRINT routine. In the Cross Reference window, the following line should be high-lighted: IUNIT, I*4 variable, in demo.f(33)[PRINT] is Dummy arg 5) Double-click a lint instance that is not currently highlighted. For example: demo.f(49)[DIPSTAT] #125: symbols were implicitly typed as R*4: PRINT ### The Source window now redisplays the source file with the highlight on "PRINT" in line 49. The Tree window shows a tree centered around DIPSTAT. The Cross Reference window shows the following in- formation: PRINT, subroutine, in demo.f(49)[DIPSTAT] is called 6) To see the lint summary again, use the right mouse button to select Summary in the Lint window. (For figure 14.1, see printed version of manual.) Chapter 15 More About Xlint 15.1 Resizing Windows Any of the Source, Lint, Tree, or Cross Reference windows in the Xlint screen can be enlarged or reduced at the expense or benefit of the other windows. To resize a window, press the left or middle mouse button on the small box between two windows, and drag it to the new boundary line users desire. Then release the button. When the information in any of the windows exceeds the size of the window, a scroll bar will appear on the bottom and/or right hand side of the window. ---------------------------------------------------------------------- 15.2 Window Interaction Window interaction is controlled by the Action sub-menu in each of the Lint, Tree, and Cross Reference windows. The settings in these Action menus determine how changes in that particular window will affect the other windows. Depending on the action settings, all the windows may be updated to reflect information relative to the changed window. To view or change the action settings for a particular window, move the mouse cursor to any location within that window and press the right mouse button. The popup menu for that window will now be displayed. Move the mouse to the Action option and press the right button again. The action options will now be displayed. To toggle an option on or off, simply point to that option box, and press the right mouse button. The default settings for window interaction are set so that an action in any window will affect the others. For example, if the user double-clicks a cross reference entry, the corresponding source code and the tree information will appear in the Source and Tree windows. ---------------------------------------------------------------------- 15.3 Command-Line Options Xlint supports the standard "X" command-line options (i.e., -bg, -fg, -display, etc...). For additional information on these options, see the system vendor's "X" documentation. Additionally, a database (".fdb") file may be specified on the command line. For example: xlint foo.fdb To specify an alternate resource file (e.g., bar.dat), use an option of the following form: xlint -rf bar.dat This option loads both the default resource file and the user- specified file. Options in the user-specified file take precedence. ---------------------------------------------------------------------- 15.4 Advanced Example The following session will use "demo.fdb" as the example. Sample session 3: 1) In the FORTRAN-lint / Xlint installation directory, run: xlint demo.fdb This will bring up an Xlint screen with analysis output for the "demo" project in the Lint window. 2) Click the left mouse button to bring up the File menu. Select the View File command. Select "demo.for" (or "demo.f"). The Source window should display FORTRAN source code for the "demo" project. 3) Symbols can be located throughout the loaded source file by highlighting the text of a symbol in the Source window, clicking the right mouse button to bring up the popup menu, and selecting Next Text. For instance, highlight "PRINT" in line 9 in the Source window. To search for the next "PRINT" in "demo.for", click the right mouse button anywhere in the Source window to call up the popup menu. Select Next Text. The next "PRINT" highlighted in the Source window is in the SETTYPE subroutine. 4) To see all occurrences of "PRINT", use the right mouse button in the Cross Reference window to call up the submenu. Choose Lookup Selected Symbol. 5) To make a cross reference entry available as a selection for the Source and/or Tree windows, highlight the entry using a click of the left mouse button. For example: PRINT, subroutine, in demo.f(33)[PRINT] is defined 6) To see the tree related to this highlighted cross reference entry, use the right mouse button to select the Routine Containing Xref in the Tree's popup menu. The Tree window shows a call tree centered around the PRINT rou- tine. 7) To see where in the source code the highlighted "PRINT" in the Cross Reference window refers to, use the right mouse button to select "Current Xref" in the Source window. The highlight in the Source window now moves to the symbol "PRINT" in line 33. Note that the combined result of steps 5-7 can be done by simply double-clicking the cross reference entry in step 5. (See figure 15.4) 8) double-click the SETTYPE routine in the Tree window. The Source window moves the highlight to "SETTYPE" in line 27. The Cross Reference window shows all the cross reference information about SETTYPE. Users can change the setting for any window at any time. For example, the depth of the parent or child tree in the Tree window can be changed by using the Tree Option in the Control Panel. The tree will be redisplayed with the new depth. (For figure 15.1, see printed version of manual.) Chapter 16 Resource Files 16.1 Overview A resource file is an ASCII text file that contains the configuration information needed for Xlint to run. Xlint resource files conform to the standard X Window resource file conventions. The default resource file is named XLint (under UNIX) or XLINT.DAT (under VMS). It is strongly suggested that the original copy of this resource file not be altered. If users need to modify the default configuration, they should create modified copies. Users may load modified versions of the resource file in various ways; for additional information, see section 16.2. ---------------------------------------------------------------------- 16.2 XLint and XLINT.DAT The Xlint resource file is named XLint (under UNIX) or XLINT.DAT (under VMS). A copy of this file should be placed in the home directory for each Xlint user. By default, Xlint uses this copy. Users may specify alternate versions on the Xlint command line; for additional information, see section 15.3. Alternatively, under UNIX, users may set the standard environment variable XAPPLRESDIR or use the standard app-defaults directory. Under VMS, two logicals DECW$SYSTEM_DEFAULTS and DECW$USER_ DEFAULTS are used. To install a copy of XLINT.DAT for system-wide use, place it in the directory specified by DECW$SYSTEM_DEFAULTS. To install a copy of XLINT.DAT for use by an individual user, place it in the directory specified by DECW$USER_DEFAULTS for that user. If Xlint finds copies of the resource file in two or more places, all of the specified options are used, but options in individual user resource files take precedence over options in system-wide resource files. If a resource file is specified on the Xlint command line, options in the specified file take precedence. For additional information, see section 15.3. Appendices Appendix A Installation Under UNIX A.1 Pre-installation Starting with revision 2.81, FORTRAN-lint incorporates a license manager that requires a daemon to be loaded before the product will run. The daemon is called iptlm for versions below 2.90 and iptlmd for versions 2.90 and above. The daemon can be started by non-privileged users. However, root privileges are required if the product is to be installed in system directories. Note: The FORTRAN-lint "installation directory" mentioned in the following sections is the directory that contains the FORTRAN-lint support files (for example, flint.err and flint.cfg). ---------------------------------------------------------------------- A.2 Installation Procedure 1. Log in as system manager. 2. Create a temporary directory. Go to the new directory. 3. Insert the tape (or other media) provided and enter a command of the form: tar xvf /dev/device_name where device_name is the UNIX device name for the media used (1/4" cartridge tapes, 3 1/2" floppy diskettes, etc.). 4. Step 3 will load a number of files, including: demo.f demo source files demo.inc demo include file demo90.f90 demo90 source files demo90.inc demo90 include file flint.1 man page flint.cfg flint default configuration file flint.err error message text flint.hls flint help file unixlib.lsh standard UNIX library description text unixlib.lbt standard UNIX library file vmslib.lsh standard VMS library description text vmslib.lbt standard VMS library file The basic executables include: demo demo script demo90 demo90 script flint FORTRAN-lint executable flpatch executable patch program install_flint installation script for FORTRAN-lint iptlma license administration program iptlmd license manager daemon iptlmr license usage report generator Multiple versions of flint may be loaded. For example, flint_sun4 is the executable for SUN 4 systems. The installation procedure will select the correct version and rename it appropriately. If the Xlint option was purchased, the following additional files will be loaded: demo.fdb database generated from demo.f demo90.fdb database generated from demo90.f90 xlint Xlint executable XLint Xlint resource file 5. After the tape is loaded, run install_flint and follow the in- structions on the screen. 6. Modify the user configuration for each FORTRAN-lint user as fol- lows: (a) Set the environment variable FLINTHOST to the host name for the server where the license manager is installed. (To obtain the host name, execute the UNIX command hostname on the server.) (b) Set the environment variable FLINTHOME to a full path for the directory which contains the FORTRAN-lint support files (flint. err, etc.). For example, if the user is using csh, use commands of the form: setenv FLINTHOST hostname setenv FLINTHOME installation_directory If the user is using sh, use commands of the form: FLINTHOST=hostname; export FLINTHOST FLINTHOME=installation_directory; export FLINTHOME 7. Add $FLINTHOME to the user's search list. For csh users, use a command of the form: set path=($path $FLINTHOME) For sh users, use a command of the form: PATH=$FLINTHOME:$PATH To make the changes permanent, add the new commands to the appro- priate login scripts. For example, for csh users, modify ".cshrc". 8. Optional: The FORTRAN-lint package includes a utility program named flpatch that can be used to patch the FORTRAN-lint installa- tion directory and server host name directly into the flint execut- able. To patch the executable, use commands of the form: flpatch flint host flpatch flint home For additional information on FLPATCH, see section A.4. 9. Users are now ready to activate FORTRAN-lint. ---------------------------------------------------------------------- A.3 Activation Procedure Every FORTRAN-lint license must be assigned a unique authorization number (or "activation key") by IPT before the package will run. 1. To proceed, execute the following command: flint activate The software will provide users with a server code, and it will prompt them to call IPT for activation. If users have not already received an activation key, they will need to contact IPT. IPT will then generate an activation key based on the server code. 2. Once the activation key is acquired, execute the following command: flint activate again, and enter the activation code when prompted. Note: A file called 02.lic or 07.lic will be created in the FORTRAN-lint installation directory. This file stores information related to the activation key. 3. The activation procedure in step 2 also creates a script file called startup under the installation directory. This file will allow users to load the daemon from the command line. Users will need to run startup every time they reboot their system or kill the license manager. After the key file has been successfully installed in the instal- lation directory, FORTRAN-lint will ask users if they want to put a command to start the license daemon in the system boot file (/etc/rc.local). If users answer "yes", the license manager daemon will be started automatically whenever the system is booted. To complete the installation procedure, in this case, simply reboot the system. However, users must have sufficient privileges to do so. If users answer "no", they will need to start the daemon manually if they reboot the system or kill the daemon. 4. If users have elected not to have the boot file modified, they need to run: $FLINTHOME/startup at the next prompt to start the daemon. After being started, the daemon requires a three minute period for initialization. 5. When three minutes are up, enter the command: flint FORTRAN-lint should display a "help" screen. 6. FORTRAN-lint is now ready for use. Note: At this point, Xlint may be installed. For additional infor- mation, see appendix H. ---------------------------------------------------------------------- A.4 Patching FORTRAN-lint Some of the default parameters in FORTRAN-lint can be modified within the FORTRAN-lint executable. This is accomplished using the "flpatch" program. This program takes the following command-line arguments: 1st: name of the executable (required) 2nd: parameter to patch 3rd: desired value If the second or third arguments are not given, the user will be prompted for them. The patchable parameters in FORTRAN-lint are: Name Description Default value ------------ ---------------------- -------------------------- home installation directory /usr/local/flint host license server host ? preprocessor path of C preprocessor /usr/lib/cpp bootfile system boot file /etc/rc.local (a) The home parameter sets the default for the directory of the FORTRAN-lint support files. home can be overridden by the environment variable FLINTHOME. (b) The host parameter is used by the license manager to locate the machine on which the license manager daemon is running. This helps improve performance since the application does not have to search the entire network for the location of the daemon. This parameter is set during the installation procedure and need not change, ex- cept in the event of changing the hostname of the current mach- ine. host can be overridden by the environment variable FLINTHOST. For the daemon hostname, there are two special values: (1) a ? causes a system-wide search for the daemon (2) a ! causes an error to be reported unless FLINTHOST is set (c) The preprocessor parameter allows FORTRAN-lint to pass the source code through a preprocessor, usually cpp, before analyzing it. The preprocessor must take the same arguments as cpp. (d) The bootfile parameter sets the name of the boot file, which can optionally be modified during the activation procedure to automat- ically start the license daemon when rebooting the system. Appendix B Installation Under VMS B.1 Pre-installation Starting with revision 2.82, FORTRAN-lint incorporates a license manager that requires a detached process to be loaded before the product will run. The daemon is called iptlm for versions below 2.90, and iptlmd for versions 2.90 and above. Installation can be done by non-privileged users. However, root privileges are required if the product is to be installed in system directories. Note: The FORTRAN-lint "installation directory" mentioned in the following sections is the directory that contains the FORTRAN-lint support files (for example, flint.err and flint.cfg). ---------------------------------------------------------------------- B.2 Installation Procedure 1. Log in as system manager. 2. Create an installation directory. Go to the new directory. 3. Load the tape (or other media) provided and execute commands of the following form: MOUNT /FOR device_name BACKUP /LOG device_name:FLINT [] DISMOUNT device_name where device_name is the VMS device name for the media used (TK-50 cartridge tape, 1600 bpi mag tape, etc.). 4. Step 3 will load a number of files, including: DEMO.FOR demo source files DEMO.INC demo include file DEMO90.F90 demo90 source files DEMO90.INC demo90 include file FLINT.CFG FLINT default configuration file FLINT.ERR error message text FLINT.HLP FLINT help file, use with VMS HELP FLINT.HLS FLINT help file, command line options VMSLIB.LSH standard VMS library description text VMSLIB.LBT standard VMS library file UNIXLIB.LSH standard UNIX library description text UNIXLIB.LBT standard UNIX library file The basic executables include: DEMO.COM demo script DEMO90.COM demo90 script IPTLMA.EXE license administration program IPTLMD.EXE license manager detached process IPTLMR.EXE license usage report generator FLINT.EXE FORTRAN-lint executable FLPATCH.EXE executable patch program If the Xlint option was purchased, the following additional files will be loaded: DEMO.FDB database file for demo.for DEMO90.FDB database file for demo90.f90 XLINT.DAT Xlint resource file XLINT.EXE Xlint executable file 5. Modify the user configuration for each FORTRAN-lint user as fol- lows: (a) If the FORTRAN-lint license manager is installed on a DECNET server, set the logical FLINTHOST to the node name for the ser- ver. Otherwise, set FLINTHOST to "NO_DECNET". Note: To obtain the node name, execute the command "show logical SYS$NODE" on the server. Discard any "colon" charac- ters. define FLINTHOST "node_name" (b) Set the logical FLINTHOME to a full path for the FORTRAN-lint installation directory. define FLINTHOME $disk:[installation_directory] (c) Define the symbol FLINT as a foreign command to execute FLINT.EXE (located in the installation directory): FLINT :== $FLINTHOME:FLINT.EXE (d) Define the symbol FLPATCH as a foreign command to execute FLPATCH.EXE (located in the installation directory): FLPATCH :== $FLINTHOME:FLPATCH.EXE To make the changes permanent, add the new commands to the appro- priate LOGIN.COM files. Example: DEFINE FLINTHOST "GUMBY" DEFINE FLINTHOME $disk3:[USR.PETER.FLINT] FLINT :== $FLINTHOME:FLINT.EXE FLPATCH :== $FLINTHOME:FLPATCH.EXE 6. Optional: The FORTRAN-lint package includes a utility program named FLPATCH.EXE that can be used to patch the host directory path and server node name directly into the FLINT.EXE executable. To patch the executable, use commands of the form: FLPATCH FLINT.EXE HOME $disk:[directory_path] FLPATCH FLINT.EXE HOST "node_name" disk:[directory_path] should specify the FORTRAN-lint installation directory. node_name should be the appropriate node name (or "NO_DECNET"), as explained in step 5. For additional information on FLPATCH, see section B.4. 7. Users are now ready to activate FORTRAN-lint. ---------------------------------------------------------------------- B.3 Activation Procedure Every FORTRAN-lint license must be assigned a unique authorization number (or "activation key") by IPT before the package will run. 1. To proceed, execute the following command: flint /license=activate The software will provide users with a server code, and it will prompt them to call IPT for activation. If users have not already received an activation key, they will need to contact IPT. IPT will then generate an activation key based on the server code. 2. After the activation code is obtained, execute the command: flint /license=activate again, and enter the activation code when prompted. Note: A file called 02.lic or 07.lic will be created in the FORTRAN-lint installation directory. This file stores information related to the activation key. 3. The activation procedure in step 2 also creates a script file call- ed STARTUP.COM in the installation directory. This file will allow users to load the daemon from the command file. To start the license daemon, execute the following command: @FLINTHOME:startup Users will need to run @FLINTHOME:STARTUP if they reboot the system or kill the detached process. Alternatively, add this command to the appropriate system startup script. 4. The startup script in step 3 requires a three minute period for initialization. When the three minutes are up, enter the command: flint FORTRAN-lint should display a "help" screen. 5. FORTRAN-lint is now ready for use. Note: At this point, Xlint may be installed. For additional infor= mation, see appendix I. ---------------------------------------------------------------------- B.4 Patching FORTRAN-lint Some of the default parameters in FORTRAN-lint can be modified within the FORTRAN-lint executable. This is accomplished using the FLPATCH program. This program takes three command-line arguments: 1st: name of the executable (required) 2nd: parameter to patch 3rd: desired value If the second or third arguments are not given, the user will be prompted for them. The patchable parameters in FORTRAN-lint are: Name Description Default value ---- ---------------------- ------------------------------ home installation directory "!" host license server host "NO_DECNET" To patch FORTRAN-lint, use a command of the following form: FLPATCH flint.exe home $disk2:[appl.FLINT] (a) The home parameter sets the default for the application support directory. home can be overridden by the system logical FLINTHOME. The default value "!" for the home parameter indicates that the installation directory is not specified. Unless the FLINTHOME logical is specified, an error message will be issued reporting that the product is not yet installed. (b) The host parameter is used by the license manager to locate the machine on which the license manager detached process is running. If the license manager is not installed on a DECNET server, this parameter should be set to "NO_DECNET". The host parameter can be overridden by setting the logical FLINTHOST. For the detached process hostname, there are two special values: 1) a ? causes a system-wide search for the detached process. 2) a ! causes an error to be reported unless FLINTHOST is set. Appendix C License Manager Starting with version 2.81, FORTRAN-lint incorporates a license manager that requires a daemon to be loaded before the product will run. This daemon is called iptlm for versions below 2.90 and iptlmd for versions 2.90 and above. C.1 License Manager Commands C.1.1 User Commands 1) By default, FORTRAN-lint will queue a job when there are no more licenses available. The "-q" option under UNIX or "/quit" under VMS when added to the "flint" command line will force the application to quit when there are no available licenses. flint -q [options] files under UNIX or flint /quit [options] files under VMS 2) FORTRAN-lint needs to identify the node on which the license manager was loaded. To accomplish this, it uses the UNIX environ- ment variable (or VMS logical) FLINTHOST. To define FLINTHOST under UNIX, use commands of the form: setenv FLINTHOST hostname for csh users or FLINTHOST=hostname for sh users export FLINTHOST hostname should be the network name of the user's license server host. (To obtain the host name under UNIX, execute the command hostname on the server.) To define FLINTHOST under VMS, use a command of the form: define FLINTHOST "nodename" If the license server is installed on a DECNET host, nodename should be the node name of the host. Otherwise, nodename should be "NO_DECNET". (To obtain the node name under VMS, execute the command "show logical SYS$NODE" on the server. Discard any "colon" characters.) 3) Another environment variable (or logical) FLINTHOME tells FORTRAN- lint where the installation directory is located. This variable can be used to override the directory value patched into the execu- table during installation. To define FLINTHOME under UNIX, use commands of the form: setenv FLINTHOME directory for csh users or FLINTHOME=directory for sh users export FLINTHOME directory should be a full path. To define FLINTHOME under VMS, use a command of the form: define FLINTHOME $disk:[installation_directory] 4) Under VMS, the qualifier /system may be added to the commands in 2) and 3) to place the definitions of FLINTHOST and FLINTHOME in the system logical table. Note that users need to log in with SYSNAM privileges to add definitions to the system logical table. C.1.2 Administrative Commands Under UNIX Under VMS Description -------------- ----------------------- --------------------------- flint activate flint /license=activate Enter an activation key flint users flint /license=users Show licenses in use flint servers not supported List active license daemons flint report flint /license=report Cumulative usage report flint daily flint /license=daily Daily usage report flint kill flint /license=kill Kill license daemon (*) (*) Requires superuser privileges. C.1.3 License Manager Options (at daemon startup only) 1) iptlmd -e dir:dir:dir... Key file directories (required) Directories must be full pathnames separated by colons. 2) iptlmd -r file Reserve file This file allows licenses to be reserved for specific users or machines. The format of this file is: product:group:client1,...,clientN:K Each group, with the client members, has K licenses for FORTRAN- lint. Under UNIX, the group name is unrelated to normal UNIX system group names. It is only the name you wish to call this group of users. A client is either a user name or a host name preceded by the at sign ("@"). Example: flint:hackers:wendy,jeff,sara,fred:3 flint:lab:@gumby:1 Here Fred is a user name, and @gumby is a host name. Comment lines begin with "#". 3) iptlmd -l logfile Log file (needed for usage reports; recommended) 4) iptlmd -m size Maximum log file size. This limits the size of the log file. When this size is reached, the log file is copied to file.old and is cleared. The size is given as a floating number followed by either "m" for megabytes or "k" for kilobytes. Examples: -m 100k -m 0.5m 5) iptlmd -v # Log file verbosity. The default value is 3. Lower numbers produce less out- put and higher numbers produce more output. 6) iptlmd -f Run in foreground. The license manager normally "backgrounds" itself and ex- its. This option keeps it in the foreground. Appendix D Sample Output: Fortran 90 For sample Fortran 90-related output, see printed version of manual. Appendix E Sample Output: FORTRAN 77 For sample FORTRAN 77-related output, see printed version of manual. Appendix F Diagnostic Messages F.1 Format FORTRAN-lint's diagnostic messages are defined in a text file named flint.err. This file contains one message per line in the following format: ### XX Text where ### is a three-digit message number XX is a two-letter diagnostic code Text is the message text Example: 157 SE no matching "(". If the message number is less than three digits long, it is right- justified in a three-column field. The first letter of the diagnostic code specifies a basic error cate- gory as follows: Letter Type of problem ------ ------------------------- S Syntax U Data usage I Call interface P Portability M Implicit typing O Overflow (limit exceeded) The second letter of the diagnostic code specifies a severity level as follows: Letter Type of problem ------ ------------------------- E Error W Warning F Hint (FYI) Lines that start with an "I" are not diagnostic messages. These lines contain information used during portability checking. Appendix G Performance G.1 Disk Space G.1.1 Program Size FORTRAN-lint requires approximately 2 MB of disk space for the package itself. Additional space is required during analysis (see below). G.1.2 Temporary Files FORTRAN-lint generates temporary files during processing. These files are automatically deleted upon program termination, including aborts. Under UNIX, the library function tempnam() is used to obtain names for the temporary files. On most systems, the environment variable TMPDIR may be used to control the directory used by tempnam(); if TMPDIR is not set, tempnam() normally uses /usr/tmp or /tmp. For additional in- formation, see the UNIX "man" page for tempnam(). Under VMS, temporary files are placed in the directory specified by SYS$SCRATCH. Generally speaking, temporary files will require 2 MB of disk space (or above) for every 10,000 lines of source code. Cross-reference tables and call trees will increase the amount of disk space required. Appendix H Xlint Installation Under UNIX H.1 Pre-installation The Xlint installation procedure assumes that FORTRAN-lint has already been installed and activated. If FORTRAN-lint has not been installed, see the instructions in appendix A. Note: The FORTRAN-lint / Xlint "installation directory" mentioned in the following sections is the directory that contains the FORTRAN-lint / Xlint support files (for example, flint.err and flint.cfg). ---------------------------------------------------------------------- H.2 Installation Procedure 1. Log in as system manager. 2. Go to the FORTRAN-lint / Xlint installation directory. The follow- ing Xlint support files should already be present: xlint # Xlint executable XLint # Xlint resource file demo.fdb # demo database generated from demo.f 3. Modify the user configuration for each Xlint user as follows: (a) Set the environment variable XLINTHOST to the host name of the system where the Xlint license manager will be running. (To obtain the host name, execute the UNIX command hostname on the server.) (b) Set the environment variable XLINTPATH to a full path for the directory which contains the user's own FORTRAN source files. (c) Set the environment variable XLINTHOME to a full path for the Xlint installation directory. For example, if the user is using csh, use commands of the form: setenv XLINTHOST nodename setenv XLINTPATH source_path setenv XLINTHOME installation_directory If the user is using sh, use commands of the form: XLINTHOST=nodename; export XLINTHOST XLINTPATH=source_path; export XLINTPATH XLINTHOME=installation_directory; export XLINTHOME Note: There should no white space on either side of the "equals" sign. For other shells, substitute the appropriate commands. 4. Add $XLINTHOME to the user's search path. This step can be omitted if $FLINTHOME points to the same directory as $XLINTHOME and $FLINTHOME has been already been added to the search path. For csh users, use the command: set path=($path $XLINTHOME) For sh users, use the command: PATH=$XLINTHOME:$PATH To make the changes permanent, add the new command to the appropri- ate login scripts. For example, for csh users, modify ".cshrc". 5. Optional: The Xlint package includes a utility program flpatch that can be used to patch the Xlint installation directory and ser- ver name directly into the xlint executable. To patch the executable, use commands of the form: flpatch xlint home flpatch xlint host Replace directory with the Xlint installation directory, and hostname with the host name for the system that will be running the Xlint license manager. Note: The install_flint shell script runs flpatch automatically. flpatch therefore should be needed only if one of these parameters changes. 6. Copy the Xlint resource file (XLint) to the appropriate directory or directories. A copy of this file should be placed in the home directory for each Xlint user. By default, Xlint uses this copy. Users may specify alternate versions on the Xlint command line; for additional infor- mation, see section 15.3. Alternatively, users may set the standard environment variable XAPPLRESDIR or use the standard app-defaults directory. For addi- tional information, see the operating system vendor's "X" document- ation. 7. Users are now ready to activate Xlint. ---------------------------------------------------------------------- H.3 Activation Procedure Every Xlint license must be assigned a unique authorization number (activation key) before the package will run. 1. To proceed, execute the following command: xlint activate The software will provide users with a server code, and it will prompt them to call IPT for activation. IPT will use the server code to generate a unique authorization number for the software. 2. After an activation key is obtained, execute the command: xlint activate again, and enter the activation key when prompted. 3. If the license manager process iptlmd has not already been started, users will need to execute the command: startup from the installation directory. Note that a single iptlmd pro- cess will allow both FORTRAN-lint and Xlint to run. Users will need to run startup every time they reboot the system or kill the license manager. To avoid this step, add the startup command to the appropriate system boot script. 4. The license manager daemon requires a three minute period after be- ing started for initialization. When the three minutes are up, execute the command: xlint Xlint is now ready for use. Note: For license manager options, see appendix C. Appendix I Xlint Installation Under VMS I.1 Pre-installation The Xlint installation procedure assumes that FORTRAN-lint has already been installed and activated. If FORTRAN-lint has not been installed, see the instructions in appendix B. Note: The FORTRAN-lint / Xlint "installation directory" mentioned in the following sections is the directory that contains the FORTRAN-lint / Xlint support files (for example, flint.err and flint.cfg). ---------------------------------------------------------------------- I.2 Installation Procedure 1. Log in as system manager. 2. Go to the FORTRAN-lint / Xlint installation directory. The follow- ing Xlint support files should already be present: XLINT.EXE ! Xlint executable file XLINT.DAT ! Xlint resource file DEMO.FDB ! demo database file for demo.for 3. Modify the user configuration for each Xlint user as follows: (a) If the Xlint license manager is installed on a DECNET server, set the logical XLINTHOST to the node name for the server. Otherwise, set XLINTHOST to "NO_DECNET". Note: To obtain the node name, execute the command "show logi- cal SYS$NODE" on the server. Discard any "colon" characters. (b) Set the logical XLINTPATH to a full path for the directory which contains the user's own FORTRAN source files. (c) Set the logical XLINTHOME to a full path for the Xlint installation directory. (d) Set the logical XLINT to a full pathname for the executable file XLINT.EXE in the installation directory. Add the new commands to the appropriate login.com files. Example: define XLINTHOST "nodename" define XLINTPATH [source_path] define XLINTHOME [installation_directory] XLINT :== $XLINTHOME:XLINT.EXE 4. Optional: The FORTRAN-lint package includes a utility program named FLPATCH.EXE that can be used to patch the Xlint installation dir- ectory and server node name directly into the Xlint executable file. To patch Xlint, use commands of the form: FLPATCH XLINT.EXE HOME disk:[directory_path] FLPATCH XLINT.EXE HOST nodename disk:[directory_path] should specify the Xlint installation direct- ory. nodename should be the appropriate node name (or "NO_DECNET"), as explained in step 3. 5. Copy the resource file (XLINT.DAT) to the appropriate directory or directories. Two logicals are used: DECW$SYSTEM_DEFAULT -- System directory (same for all users) DECW$USER_ DEFAULTS -- Per-user directory To install a copy of XLINT.DAT for system-wide use, place it in the directory specified by DECW$SYSTEM_DEFAULTS. To install a copy of XLINT.DAT for use by an individual user, place it in the directory specified by DECW$USER_DEFAULTS for that user. Note that users may an alternate resource file on the Xlint command line; for additional information, see section 15.3. 6. Users are now ready to activate Xlint. ---------------------------------------------------------------------- I.3 Activation Procedure Every Xlint license must be assigned a unique authorization number (activation key) before the package will run. 1. To proceed, execute the following command: FLINT /LICENSE=ACTIVATE The software will provide users with a server code, and it will prompt them to call IPT for activation. IPT will then use this in- formation to provide them with a unique authorization number needed to run the software. 2. After an activation key is obtained, execute the command: FLINT /LICENSE=ACTIVATE again, and enter the activation code when prompted. 3. If the license manager (iptlmd) hasn't already been started, users will need to execute the command: @FLINTHOME:STARTUP.COM This will start the license daemon. Note that a single iptlmd process will allow both FORTRAN-lint and Xlint to run. Users will need to run @FLINTHOME:STARTUP again if they reboot the system or kill the detached process. Alternatively, simply add the STARTUP command to the appropriate system startup script. 4. The detached process requires a three minute period after being started for initialization. When the three minutes are up, execute the command: XLINT Xlint is now ready for use. Note: For license manager options, see appendix C.