3 GXCHK - Global Cross Checks

3.1 Introduction

GXCHK takes the symbol tables written by SPAG and combines them to form a global view of data usage within a program. The process is analogous to the more familiar procedure of compiling and linking. The symbol tables are analogous to object files, and GXCHK works like a linker to combine them into a single global report. The AUTOMAKE tool, which automates compiling and linking can also be used to rebuild the global report file with minimal re-analysis.

GXCHK produces a series of reports; the first two identify errors and other anomalous conditions. These include:

actual arguments inconsistent with the dummy arguments in the subprogram definition, or with each other.
inconsistent COMMON block definitions. GXCHK can check each COMMON block element, or just the overall size.
globally unused subprograms, INCLUDE files, COMMON blocks, COMMON variables and PARAMETERs.
COMMON variables assigned a value but never used, or used but never assigned a value.
COMMON variable name in more than one COMMON block.
COMMON block or PARAMETER defined in more than one INCLUDE file.
PARAMETER defined with different values in different subprograms.
clashes between names of different types (e.g. local variable the same as COMMON variable).
missing or multiply-defined subprograms.

Subsequent reports contain documentation of the program, including charts showing where and how each symbol is used. For example, these charts could be used to identify which subprograms modify a particular COMMON variable, and which use it without changing it. A separate report is produced for each type of symbol (subprograms, INCLUDE files, COMMON blocks, COMMON variables and PARAMETERs). Also included is a CALL tree.

GXCHK may also embed a block of comments containing a summary of the interface of each subprogram into the restructured code produced by SPAG. This summary includes lists of calls from and to this subprogram, COMMON variables used and/or modified, dummy arguments, local variables and PARAMETERs.

An interactive mode allows users to query the GXCHK database, and obtain all available information about any symbol without reference to the output reports.

GXCHK is also used to make final adjustments to the source code of the main program prior to a dynamic analysis run. See Section 2.8 for a discussion of dynamic analysis.

3.2 The GXCHK Command Line

To start a run, simply type gxchk followed by the name of the symbol table file(s) you wish to process. You can use wild-cards to specify more than one file. For example:

      gxchk a*.smb b*.smb

processes the contents of all files in the current directory which fit either wildcard.

Under DOS/Windows and VMS, .smb is assumed if no extension is specified (b* is treated as b*.smb). The default file name is *.smb. Thus, if you just type gxchk, all .smb files in the current directory are processed.

Under UNIX, the extension must be specified, and there is no default file name.

The operation of GXCHK may be modified by command line switches. Currently the following switches are available:

FIG=	specifies the configuration file name (see section 3.3). If you don't specify a file name in this way, GXCHK assumes that the configuration file is in a file called gxchk.fig. In either case, the search rules defined in section 1.4 are followed. If no configuration file can be found, GXCHK uses internal defaults for all configuration items. If a '?' is appended (e.g. FIG=GXCHK.FIG? or FIG=?), GXCHK lists the contents of the active configuration file to the screen, with a pause after each screen full.
nnn=	specifies the value of item nnn in the GXCHK configuration file (see section 3.4). Items specified in this way over-ride those read from the configuration file. This is particularly useful for switching individual errors on and off.
TO=	specifies the name of the file to which the main GXCHK output reports are sent. The default file name is gxchk.out. An abbreviated version of this report is written to the screen as GXCHK runs.
SAVE=	specifies the name of the binary file in which GXCHK will save its database, if item 307 of the configuration data is set to 1. This save file may be used for interactive GXCHK sessions. The default save file name is gxchk.sav.

For example

      gxchk a*.smb to=gxmary.out fig=gxmary.fig 311=1 321=1

This command causes GXCHK to analyze all files in the current directory whose name fits the template a*.smb. Configuration options are read from gxmary.fig, but the controls on records 311 and 321 are both set to 1. The output report is sent to gxmary.out.

3.3 The GXCHK Configuration File

The GXCHK configuration file has the same general format as the SPAG configuration file (see Section 2.5). The item numbers for GXCHK are in the range 300-450, and all items are integers. There is no overlap between GXCHK and SPAG item numbers.

An example configuration file is shown below. The meaning of each data item is explained in detail in the next section. The values shown in this example are, in fact, the defaults which are used by GXCHK if no configuration file is found.

Example GXCHK Configuration File

 ============================ GXCHK controls ===============================

302=0   0 - system default box drawing chars  1 - use IBM PC box drawing chars
        2 - use only ASCII characters
303=200 number of lines per page (if >=200 no pages within reports)
304=78  width of output reports
305=0   used to economize on storage/time in GXCHK
        0=keep everything                     1=keep all except local variables
        2=keep sub-programs & COMMON blocks   3=keep sub-programs only
306=0   0=batch operation                     1=interactive operation
307=1   0=no library file    1=write library file   2=read from library file
308=1   0=no subroutine interface summaries   1=embed summaries in SPAGged code
309=1   0=no preparation for dynamic analysis 1=prompt to modify main program
        2=modify main program - no prompt

 ====================== Controls on Error Reporting ========================
                            (see also 401-450)

311=2   0=no errors relating to sub-programs      1=one line message  2=verbose
312=2   0=no errors relating to COMMON blocks     1=one line message  2=verbose
313=2   0=no errors relating to INCLUDE files     1=one line message  2=verbose
314=2   0=no errors relating to COMMON variables  1=one line message  2=verbose
315=2   0=no errors relating to PARAMETERs        1=one line message  2=verbose
316=1   0=no type check of subprogram arguments   1=argument type checking

318=0   0=assume default type lengths throughout  1=only for dummy args
319=1   0=no special treatment
        1=summary table only for 'Subprogram used but not defined'
                                 'Subprogram defined but not used'
                                 'PARAMETER is never used'

 =================== Controls on Cross Reference Reports ===================

320=1   0=no sub-program index         1=index of sub-program source code
321=1   0=no sub-program     reports   1=where called
322=3   0=no COMMON block    reports   1=where modified  3=where referenced
323=3   0=no INCLUDE file    reports   1=where modified  3=where referenced
324=3   0=no COMMON variable reports   1=where modified  3=where referenced
325=1   0=no PARAMETER       reports   1=where used

330=1   0=no CALL tree   1=minimal CALL tree   2=show unresolved references
        3=expand every occurrence of every reference
331=0   0=full X-ref charts  1=suppress 'var not used' in X-ref charts
332=1   0=keep all branches  1=suppress 'orphan' branches in CALL tree

340=1   0=No Y2K report      1=Y2K report
349=0   0=no qualifiers      1=keep qualifiers on symbol names

 ================== Controls on Individual Error Messages ===================
                    0 to suppress   >0 specifies severity

401=1   Subprogram used but not defined
402=3   Subprogram defined more than once
403=2   Subprogram defined but not used
404=4   Subprogram used in conflicting ways
405=4   Subprogram has varying argument counts
406=4   Subprogram has varying result types
407=1   Subprogram name is used in other contexts
408=3   Subprogram is called recursively
409=8
410=8
411=2   COMMON block has varying component counts
412=2   COMMON is defined in and out of INCLUDE file
413=2   COMMON is defined in different INCLUDE files
414=2   nothing in COMMON block is ever referenced
415=2   COMMON block name is used in other contexts
416=2   COMMON block defined with varying sizes
417=1   COMMON not in MAIN (for dynamic analysis)
418=8
419=8
420=8
421=1   PARAMETER defined in and out of INCLUDE file
422=1   PARAMETER defined in different INCLUDE files
423=1   PARAMETER is never used
424=1   PARAMETER name is used in other contexts
425=1   PARAMETER defined with different values
426=8
427=8
428=8
429=8
430=2   nothing in INCLUDE file is ever referenced
431=2   COMMON variable is not consistently named
432=2   COMMON array dimensioned in different ways
433=2   COMMON variable is not consistently typed
434=2   COMMON var has varying position in COMMON
435=2   COMMON var name appears in different COMMONs
436=2   COMMON variable is never referenced
437=4   COMMON var is used, but never given a value
438=2   COMMON var is given a value, but never used
439=1   COMMON variable name used in other contexts
440=8
441=4   Argument mismatch - Alternate Rtn expected
442=4   Argument mismatch - Variable expected
443=4   Argument mismatch - Subprogram name expected
444=4   Argument mismatch - Array expected
445=4   Argument mismatch - Scalar expected
446=4   Subprogram may modify non-variable argument
447=4   Argument mismatch - incorrect data type
448=4   Argument mismatch - incorrect type-length
449=8
450=8

3.4 GXCHK Configuration Data

Item 302

Box Drawing Characters

Specifies whether IBM PC box drawing characters should be used in the output report. Possible values are:

0	Use the system default box drawing characters. On MS-DOS based PCs, the IBM box drawing characters are used. On UNIX and VMS systems, ASCII characters are used.
1	Use IBM box drawing characters.
2	Use only ASCII characters

On some non-IBM compatible MS-DOS computers (e.g. the NEC PC) this control should be set to 2, to force the use of ASCII characters.

Item 303

Lines per Page

Specifies the required number of lines per page for the GXCHK output file. If this item is set to 200 or more, there is no limit to the number of lines per page, though a new page will be output at the head of each report.

Item 304

Page Width in Characters

Specifies the target width (in characters) of the GXCHK output file. Must be between 65 and 160. Certain single line messages may exceed the specified width.

Item 305

Filter Input Data

May be used to filter out some symbol table entries. This may be done to allow GXCHK to process larger programs than would otherwise be possible, to make GXCHK run more quickly, or to reduce the amount of output. Possible values are:

0	All symbols are retained.
1	All symbols are retained with the exception of local variables. GXCHK will be unable to detect some anomalies relating to local variables (e.g. local and COMMON variables with the same name).
2	Only COMMON block and subprogram names are retained. This setting significantly reduces GXCHK's diagnostic capabilities.
3	Only subprogram names are retained. This setting significantly reduces GXCHK's diagnostic capabilities.

The size of the symbol tables produced by SPAG may often be reduced by setting item 2 of the SPAG configuration data to 2 or less (see the description of that item for a discussion). This is usually a better approach to capacity problems than filtering the GXCHK input data.

Item 306

Interactive Operation

If this item is set greater than 0, GXCHK does not produce an output report, but instead enters an interactive mode, in which the user enters a symbol name, and GXCHK responds with information about the symbol. For example, if the user enters a subprogram name, GXCHK reports the type of the subprogram, the number of arguments, the name of the file containing the source code, and lists

routines which call the specified routine.
routines called from the specified routine.
COMMON blocks and variables modified within the specified routine.
COMMON blocks and variables used by the specified routine.

In addition, any errors relating to the symbol are enumerated.

Apart from subprograms, GXCHK can return information about COMMON variables, PARAMETERs, local variables, dummy arguments, COMMON blocks and INCLUDE files. GXCHK halts when the user enters a blank line in response to the symbol name prompt.

A batch file (shell script under UNIX, DCL file under VMS) called gxview which starts GXCHK in interactive mode may be found in the plusFORT release directory.

If you intend to GXCHK interactively, we recommend that you set up a 'Save-File' (see below).

Item 307

Save-File Input and Output.

Specifies whether GXCHK is to read from, or write to a Save-File called gxchk.sav (or as specified using SAVE=). Possible values are:

0	GXCHK does not read from, or write to a Save-File.
1	before finishing, GXCHK writes its database in binary form to a Save-File.
2	GXCHK reads from a Save-File instead of deriving its data from input symbol tables. This is a much faster way to start the program, most useful when using the GXCHK interactive mode.

Item 308

Interface Summary Output

Specifies whether GXCHK should embed interface summary reports into the restructured source code. The summary replaces a special marker inserted in the restructured code by SPAG if item 8 of the SPAG configuration data is set greater than 0. Possible values are:

0	No interface summary reports.
1	Embed interface summary reports in the restructured source code.

Interface summary reports are discussed in detail in Section 3.6.

Item 309

Preparation for Dynamic Analysis

Specifies whether GXCHK is to prepare the main program for a dynamic analysis run. Possible values are:

0	Do not prepare main program for dynamic analysis.
1	Prepare main program for dynamic analysis. Prompt user before changing main program.
2	Prepare main program for dynamic analysis. Do not prompt user before changing main program.

If this option is set, GXCHK adjusts the main program to ensure that COMMON variables initialized in a BLOCKDATA (or in any other subprogram) are not overwritten by the dynamic analysis code. Calls to dynamic analysis routines are commented out as necessary by inserting the characters CINIT- or !INIT- in columns 1-6. The Fortran 95 compliant form (!INIT-) is used if the item is set to a negative value (-1 or -2 instead of 1 or 2).

GXCHK also reports conditions which may weaken or invalidate the dynamic analysis, including unresolved references and COMMON blocks not defined in the main program.

GXCHK will modify the main program only if the input symbol tables were produced by SPAG while preparing the source code for dynamic analysis (item 1 of the SPAG configuration data was set to 4).

Item 311

Subprogram Error Reporting

Controls reporting of errors and other conditions relating to subprograms. These are

401	Subprogram used but not defined.
402	Subprogram defined more than once.
403	Subprogram defined but not used.
404	Subprogram used in conflicting ways.
405	Subprogram has varying argument counts.
406	Subprogram has varying result types.
407	Subprogram name is used in other contexts.
408	Subprogram is called recursively.

Possible values are:

0	The above conditions are not reported.
1	The above conditions are reported by a single line message.
2	The above conditions are reported with supporting detail where appropriate.

Recursive subprogram calls are detected only if item 330 is set greater than 0. See items 401-450 for controls on individual messages.

Item 312

COMMON Block Error Reporting

Controls reporting of errors and other conditions relating to COMMON blocks. These are:

411	COMMON block has varying component counts.
412	COMMON is defined in and out of INCLUDE file.
413	COMMON is defined in different INCLUDE files.
414	Nothing in COMMON block is ever referenced.
415	COMMON block name is used in other contexts.
416	COMMON block defined with varying sizes.
417	COMMON not in MAIN (for dynamic analysis).

Possible values are as for item 311. See items 401-450 for controls on individual messages.

Item 313

INCLUDE file Error Reporting

Controls reporting of errors and other conditions relating to INCLUDE files. The only one is:

430	Nothing in INCLUDE file is ever referenced.

Possible values are as for item 311. See items 401-450 for controls on individual messages.

Item 314

COMMON Variable Error Reporting

Controls reporting of errors and other conditions relating to COMMON variables. These are:

431	COMMON variable is not consistently named.
432	COMMON array dimensioned in different ways.
433	COMMON variable is not consistently typed.
434	COMMON var has varying position in COMMON.
435	COMMON var name appears in different COMMONs.
436	COMMON variable is never referenced.
437	COMMON var is used, but never given a value.
438	COMMON var is given a value, but never used.
439	COMMON variable name used in other contexts.

Possible values are as for item 311. See items 401-450 for controls on individual messages.

Item 315

PARAMETER Error Reporting

Controls reporting of errors and other conditions relating to PARAMETERs. These are:

421	PARAMETER defined in and out of INCLUDE file.
422	PARAMETER defined in different INCLUDE files.
423	PARAMETER is never used.
424	PARAMETER name is used in other contexts.
425	PARAMETER defined with different values

Possible values are as for item 311. See items 401-450 for controls on individual messages.

Item 316

Argument Type Checking

If item 316 is set greater than zero, GXCHK produces a report showing any inconsistencies between the actual arguments of CALLs and function references, and the dummy arguments in the subroutine or function definitions. For example, if an actual argument is an integer variable, but the subprogram expects a real variable, GXCHK will report an error. Similarly, if the actual argument is a variable, and the dummy argument an array, a different error is reported.

The full set of argument mismatch messages is shown below:

441	Argument mismatch - Alternate Rtn expected. The dummy argument is an alternate return, but the actual argument is not.
442	Argument mismatch - Variable expected. The dummy argument is an array or variable, but the actual argument is an alternate return or function name.
443	Argument mismatch - Subprogram name expected. The dummy argument is a subprogram name, but the actual argument an alternate return or function name.
444	Argument mismatch - Array expected. The dummy argument is an array, but the actual argument is not (e.g. a scalar variable or expression).
445	Argument mismatch - Scalar expected. The dummy argument is a scalar, but the actual argument is an array name. Note that if the actual argument is an array element, the dummy argument may be either a scalar or an array.
446	Subprogram may modify non-variable argument. The actual argument is a constant, expression or DO variable, and the subprogram may modify the corresponding dummy argument. This would violate the ANSI standard, and may cause the program to behave unpredictably.
447	Argument mismatch - incorrect data type. The actual and dummy arguments have different data types (e.g. REAL and INTEGER).
448	Argument mismatch - incorrect type-length. The actual and dummy arguments have different precisions (e.g. 2 and 4 byte INTEGERs).

The error messages also detail the types of the actual and dummy arguments using three character abbreviations of the form R8E, I4L etc. For alternate returns, the abbreviation is ALT; otherwise the three characters are interpreted as described below.

The first character indicates the data type (I for INTEGER, R for REAL, L for LOGICAL, C for CHARACTER, D for DOUBLE PRECISION, X for COMPLEX, Y for DOUBLE COMPLEX or B for BYTE).

The second character indicates the element size (e.g. 8 for REAL*8 or DOUBLE PRECISION items). Letters are used for element sizes between 10 and 35. + indicates an element size greater than 35, and * that the size is variable.

The third character specifies what sort of entity the argument is (V for variable, E for constant, expression or DO variable, L for an array element, A for an array name or, F for a subprogram name. If a dummy argument is specified as E, this indicates that the subprogram does not change the value of the dummy argument, and that the actual argument may be an expression, constant or DO variable.

Item 319

Summary Tables

If item 319 is set greater than 0, certain error reports are reduced to compact summary tables for ease of reference. The errors affected are:

401	Subprogram used but not defined.
403	Subprogram defined but not used.
423	PARAMETER is never used.

Item 320

Subprogram Location Report

If item 320 is set greater than 0, GXCHK produces a report showing the subprograms that have been analyzed, the number of executable statements in each one, and the name of the file containing the source code (together with the start and finish line numbers). A summary at the end of the report shows the total number of subprograms, the total number of lines of code, and the total number of executable statements.

Item 321

Subprogram Documentation

Controls the generation of reports showing calls in and out of each subprogram (SUBROUTINE or FUNCTIONs). Possible values are:

0	The report is suppressed.
1	For each subprogram, the report lists the subprograms which CALL it, and the subprograms which are CALLed by it. In this context, a CALL includes a FUNCTION reference.

Item 322

COMMON block Documentation

Controls the generation of reports showing where COMMON blocks are referenced or modified. Possible values are:

0	The report is suppressed.
1	The report lists the subprograms which modify or initialize each COMMON block.
2	In addition, the report lists, under a separate heading, subprograms which may indirectly modify the COMMON block, either via an EQUIVALENCE relation, or by passing a COMMON block item as an argument to another subprogram.
3	In addition, the report lists, under a third heading, subprograms which reference the COMMON block. Note that the report excludes subprograms which redundantly include the COMMON block definition, but do not reference any part of it.

Item 323

INCLUDE file Documentation

Controls the generation of reports showing where INCLUDE files are referenced or modified. Possible values are:

0	The report is suppressed.
1	The report lists the subprograms which modify or initialize any variable defined in the INCLUDE file.
2	In addition, the report lists, under a separate heading, subprograms which may indirectly modify a variable defined in the INCLUDE file, either via an EQUIVALENCE relation, or by passing it as an argument to another subprogram.
3	In addition, the report lists, under a third heading, subprograms which reference any variable or PARAMETER defined in the INCLUDE file. Note that the report excludes subprograms where the INCLUDEd file is present but redundant.

Item 324

COMMON Variable Documentation

Controls the generation of reports showing where COMMON variables are referenced or modified. Possible values are:

0	The report is suppressed.
1	The report lists the subprograms which modify or initialize each COMMON variable.
2	In addition, the report lists, under a separate heading, subprograms which may indirectly modify the COMMON variable, either via an EQUIVALENCE relation, or by passing it as an argument to another subprogram.
3	In addition, the report lists, under a third heading, subprograms which reference the COMMON variable. Note that the report excludes subprograms in which the COMMON variable is declared but not used.

Item 325

PARAMETER Documentation

Controls the generation of reports showing where PARAMETERs (particularly those defined in INCLUDE files) are used. Possible values are:

0	The report is suppressed.
1	The report lists the subprograms which reference each PARAMETER.

Item 330

Call Tree

Controls the generation of a call tree; the call tree shows the calling structure of a program in a graphical format. Possible values are:

0	The call tree is suppressed.
1	A minimal call tree is generated. Unresolved references are not shown, and replicated branches are expanded only once. Pointers to the branch are inserted as required. This produces a compact call-tree with no clutter.
2	A minimal call tree is generated, but with the addition of unresolved references.
3	A full call tree is generated. Unresolved references are shown, and replicated branches are expanded as required. This style of call tree is probably too wordy for most purposes.

If a call tree is generated, GXCHK also detects and reports recursive subroutine calls.

Item 331

'Used by Nothing' Reports

If item 331 is set greater than 0, lines of the form

      VARNAME        used by ** NOTHING **

are suppressed in the INCLUDE file, COMMON block, COMMON variable and PARAMETER cross reference charts.

Item 332

Orphan Branches

If item 332 is set greater than 0, 'orphan branches' are suppressed in the call tree. An orphan branch is one which stems from a subroutine or function which is defined but not used.

Item 340

Year 2000 Date Variable Scan

If item 340 is set greater than 0, GXCHK produces a report showing possible date related variables. A list of search strings must be supplied in a file called y2k.txt. See section 3.7 for a description of this facility.

Items 401-450

Error Severity Codes

Items 401 to 450 specify the severity code for the corresponding error numbers (GXCHK errors have numbers between 401 and 450). If the severity code is set to 0, the error is suppressed. Error numbers may be found by reference to the documentation of items 311 to 316 above, or from the error summary report produced at the end of a GXCHK run.

For example, at the end of a GXCHK run, you may see a summary of the form:

 82 occurrences of error 401 Subprogram used but not defined 
 11 occurrences of error 407 Subprogram name is used in other contexts
  1 occurrences of error 408 Subprogram is called recursively 
  1 occurrences of error 425 PARAMETER defined with different values 
 40 occurrences of error 431 COMMON variable is not consistently named 
  4 occurrences of error 435 COMMON var name appears in different COMMONs 
  3 occurrences of error 437 COMMON var is used, but never given a value 
 84 occurrences of error 439 COMMON variable name used in other contexts 
  2 occurrences of error 444 Argument mismatch - Array expected 
  2 occurrences of error 447 Argument mismatch - incorrect data type 
  7 occurrences of error 448 Argument mismatch - incorrect type-length

You can then repeat the run, suppressing all occurrences of errors 401 and 407 by typing

      gxchk  *.smb  401=0  407=0

Most versions of GXCHK return the highest severity code encountered as an exit code (see Section 1.6), which can be examined by the operating system procedure which runs GXCHK.

3.5 Using GXCHK

3.5.1 COMMON Variable Consistency

GXCHK is able to examine the usage of COMMON variables in a program wide context. For example if a COMMON variable is used somewhere in the program, but is nowhere assigned a value, GXCHK reports an error. For the purposes of these checks, GXCHK assumes that a given COMMON block should appear the same wherever it occurs. This is good practice, but goes beyond the requirements of standard Fortran. For example the ANSI standard permits COMMON variable names to be different in different subprograms. If you find yourself plagued with messages reporting such differences, and it is not practical to remove their cause, you may prefer to switch off COMMON variable checks (item 314 of the configuration file).

3.5.2 Symbol Table Size

In order to be sure that GXCHK catches all cases of globally unreferenced COMMON variables, you should ensure that:

either	Symbol tables are created with item 2 of the SPAG configuration file set to 3. This can result in much larger symbol tables than otherwise.
or	Every INCLUDEd file appears in a PROGRAM or BLOCKDATA segment.

The latter option is to be preferred for large programs.

3.5.3 Name Clashes

Name clashes are not always errors, but they do deserve attention. For example a 'COMMON variable name is used in other contexts' message may indicate that a COMMON variable is being used, but the COMMON block definition has been omitted. Even if there is no error, there may be cause for action. For example, if a COMMON block is inserted in a subprogram, then there will be a problem if an existing local variable has the same name as one of the COMMON variables. Even with explicit typing, the compiler has no way of knowing that anything is wrong, except, perhaps, that the variable appears in two type declaration statements.

If name clashes are eliminated, that sort of problem cannot occur. One effective technique is to use a naming convention to distinguish symbols of different types. SPAG has a variable renaming facility which can be used to convert existing programs to use a naming convention.

3.5.4 GXCHK Messages

The 'error' conditions reported by GXCHK range from clear errors (e.g. Subprogram defined more than once) through clutter checks (e.g. COMMON variable is given a value but never used), to indications of possible future problems (e.g. COMMON variable name used in other contexts). It may be that not all messages require corrective action, though all should be evaluated.

3.5.5 Some Pitfalls

If you use SPAG to insert declarations in INCLUDE files, turn symbol table output off, or delete the symbol tables before running GXCHK.

3.6 Interface Summaries

3.6.1 What Are They?

If item 8 of the SPAG configuration data and item 308 of the GXCHK configuration data is set to 1, GXCHK embeds a brief summary of the external interface of each subprogram into the restructured output produced by SPAG. A sample interface summary is shown below:

**--***************************************************************
*A INPUT  - FIRST  - dummy arguments
*A INPUT  - LAST   - space for user descriptions here
*A OUTPUT - CNTL
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
* calls       FRLIST   FRWHER   FRWNAM   FRWTOP   OPUT     OTRIM
* called by   PRDIAL   PRY2K
* modifies    /PROGA3/ IWORK1
* uses value  /PROGA2/ /PROGA3/ /PROGA4/ /PRCHZ2/ FATHER   FUNREC
*             IORDER   LONG_NCHTZM       NMTZMB   NUMDIM   OWNERZ  
*             TZUSES   ZBUTTN   ZMODIF   ZSCOPE   ZTBAGE   ZTBEDZ
* local vars  DAD      DEF1     DEFS     I        IL       IOS  
*             J        JJ       K        L        MXWID    NLIST
* uses PARAMs MAXFRQ   MAXUUB
**++***************************************************************

The summary takes the form of a series of Fortran comments. It contains sections describing dummy arguments, external subprograms, COMMON variables, local variables and PARAMETERs. These are described below.

3.6.2 Dummy Arguments

Each dummy argument is listed on a line beginning with the two characters '*A' (or '!A' if Fortran 95 free form source is used). Columns 4 to 9 specify the way the argument is used. Possible values are:

INPUT	The argument is used within the subprogram, but not changed.
OUTPUT	The value of the argument is modified within the subprogram.
PASSED	The argument is not used within the subprogram, but is passed as an argument to other routines.
UNUSED	The argument is not used within the subprogram

The name of the argument is inserted at column 13. The remainder of the line is intended to contain an explanation, written by the user, of the purpose of the variable.

3.6.3 External Subprograms

The second section contains lists of subprograms called or referenced by this subprogram, and of other subprograms which call or reference this one.

3.6.4 COMMON Variables

The next section shows every COMMON variable that is used by the subprogram. There may be up to three sub-sections, for different types of use:

modifies	is followed by a list of COMMON variables whose value is changed within this subprogram.
passes arg	is followed by a list of COMMON variables which are not accessed directly within this subprogram, but which are passed as actual arguments to other subprograms.
uses value	is followed by a list of COMMON variables whose value is used, but not changed within this subprogram.

3.6.5 Local Variables and PARAMETERs

The last two sections show the local variables and PARAMETERs used by the subprogram.

3.7 Year 2000 Date Variables

If item 340 of gxchk.fig is set to 1, GXCHK produces a report showing all variables and other symbols whose names suggest they may relate to date calculations. This report provides a valuable starting point in any audit for Year 2000 related problems in a Fortran program, particularly when used in conjunction with the Dynamic Analysis method offered by SPAG.

GXCHK uses a file called y2k.txt to guide its search for date variables. If this file is not in the current directory, GXCHK attempts to find it by following the search rules described in Section 1.4. A sample version of this file follows.

Sample y2k.txt

      day
      mon
      year
      yr
      dat
      -update
      -data
      dataccess
      eoy
      period
      week
      ddmmyy

The table specifies that GXCHK should locate any symbols that contain one of the strings listed ('day', 'mon' etc.). However, any which contain one of the strings 'update', or 'data' (i.e. those on lines beginning with a '-') should be excluded. Despite that exclusion, any variables containing the string 'dataccess' will be included, because that string is specified after the exclusion of 'data'. The conditions are applied in the order they appear, with the last match found taking precedence.