NAGWare Fortran Tools - f95 Tools - nag_decs95

Index

NAME
DESCRIPTION
OPTIONS
THE PROGRAM TEMPLATE
DECLARATIVE SECTION FORMAT
DERIVED TYPES
INTERFACE BLOCKS
DEPENDENCIES OF DECLARATIONS
SEE ALSO

NAME

nag_decs95 - Declaration standardiser

DESCRIPTION

nag_decs95 is the NAGWare f95 Tools declaration standardiser. This tool can either rebuild the declarative part of a Fortran program unit declaring all names or alternatively add declarations for all implicitly typed names. Name means a variable, common block, function or subroutine, parameter name etc.

Declarations added by nag_decs95 in -rebuild mode are divided into logical sections that are delimited by standard comments. nag_decs95 recognises these comments, if they exist in the input file, and will retain the same section order.

If a filename with no extension is provided the tool will look for a file with the extension `.f95', and if that does not exist, for a file with the extension `.f90'.

If a file has the extension `.f90' or `.f95', it will be assumed to contain free format Fortran code. If a file has the extension `.f', `.for', `.f77', or `.ftn', the file is assumed to contain fixed format Fortran code. The options -fixed and -free may be used to override this behaviour.

The input file is backed up to infile.original and the output file replaces the input file.

Modules (and include files) are expected to exist in the current working directory or in a directory named by the -I option, see nag_modules95.

OPTIONS

Declaration Standardiser Options

"Rebuild declarations" (-rebuild)

The existing declarations are deleted, and are replaced by new declarations in standard sections (which are documented later). This mode is the default.

"Declare implicits" (-declare)

All implicit names are declared explicitly. A section named `Previously Untyped Declarations' is added to the program unit's declarations, if required. Otherwise the declarations in the input program are substantially unchanged, hence "Removal of unused names" options have no effect.

"Array declarations in COMMON block" (-ardicb)

Dimensions of arrays which are in COMMON are declared, by default, in type statements. If this option is set then the dimensions are declared inside the common block statement. This option has no effect with -declare. -ardicb means ARray Declared In Common Block.

"Combine character length declarations" (-comb_chlens)

Combine character length declarations. By default separate CHARACTER statements are produced for each length of CHARACTER variable e.g.

CHARACTER(6) :: A, C
CHARACTER(10) :: B

If this option is set CHARACTER variable declarations are combined in one CHARACTER statement in each section with a length specifier following each name, e.g.

CHARACTER :: A*6, B*10, C*6

"Dimension arrays using DIMENSION attribute" (-dimatr)

By default in each section array dimensions are output following the array name in type statements e.g.

REAL :: x(12),y(20)

If this option is set the array dimension will be output in the DIMENSION attribute. E.g.

REAL,DIMENSION(12) :: x
REAL,DIMENSION(20) :: y

This option has no effect with -declare.

"Executable statement header" (-exehdr)

Setting this option causes the Declaration Standardiser to generate the section header `Executable Statements', if it does not already exist, immediately before the first executable statement. -exehdr means EXEcutable statement HeaDeR. This option has no effect in -declare mode.

"Expand include lines" (-expand_include)

Include files are always opened, read and analysed. By default variables defined in include files, however, are not placed in the declarations that are generated by this tool. If this option is set then the variables defined in include files will be declared in the type statements generated by nag_decs95, and output of INCLUDE statements will be suppressed.

"Group common objects with COMMON blocks" (-group_common)

By default three sections; `Scalars in Common', `Structures in Common' and `Arrays in Common' are generated for the type declaration of COMMON variables. In rebuild mode, this option groups declarations of COMMON objects with their COMMON blocks. Type declarations for COMMON variables immediately precede each COMMON statement in the `Common blocks' section. This option has no effect in -declare mode.

"Add IMPLICIT NONE statement" (-imp_none)

Normally any IMPLICIT statement, including IMPLICIT NONE, is deleted. If this option is set and a program unit, excluding interface blocks, contains an IMPLICIT NONE statement, this is retained, otherwise one is added in an ``Implicit None Statement'' section. This option has no effect in -declare mode.

"Removal of unused names"

"Log removal of unused names" (-logremove): A warning message will be written on standard error for each unused name which is removed. This is the default.
"No removal of unused names" (-noremove): All unused variable declarations are retained.
"Silent removal of unused names" (-silentremove) Unused names are removed without warning messages.

nag_decs95 will not remove EQUIVALENCEd or COMMON variables, or dummy arguments. This option has no effect if "Declare implicits" is on.

"Add Module accessibility section" (-modacc)

By default the PRIVATE and PUBLIC attribute is output in type declarations for non-default access variables in a module. A section is added for the accessibility of procedure names, if required, at the end of the move able sections.

If -split is set PRIVATE or PUBLIC statements are output for all non-default accessibility names in the appropriate -split section.

The -modacc option causes all accessibility statements to appear near the top of a module. A section is created to declare all non-default accessibility names immediately after the default accessibility section. This option has no effect in -declare mode.

"No structure sections" (-nostruct_sects)

By default, separate sections are output for ``Structure Arguments'', ``Structures in Common'' and ``Local Structures''. If this option is set, derived types are treated like any other data type and are output in the appropriate section in the order specified by the -order option. This option has no effect in -declare mode.

"No section trailer comments" (-notrailers)

Suppresses the generation of nag_decs95 section trailer comments.

"Datatype order" (-order name,name,name,name,name,name,name)

Specifies the order in which the type statements should be placed within each section. This option has no effect in -declare mode.

"Retain blank lines in declarations" (-retain_blanks)

By default nag_decs95 deletes any blank lines among the comments in the declaration section. If this option is set, such blank lines are retained.

"Section order" (-sectorder orderlist)

This option may be used to specify the order you wish the declaration sections to be output. Not all sections can be moved.

This option specifies a global section ordering for the whole input file. Any existing nag_decs95 section headers within program units will still be read and their order will override the order specified by this option, for that program unit only. Any sections not found in the program unit will have the order specified by this option.

This option has no effect in -declare mode.

"Split attribute declarations" (-split)

Split declarations with multiple attributes into their component parts, and place them in all sections to which the attributes apply. E.g.

CHARACTER,SAVE::var

is split into local scalars, and save statements:

CHARACTER :: var

and

SAVE :: var

Seven more sections are added to cover attributes which do not normally have a section. This option has no effect in -declare mode.

General Options

"Source format" (-fixed, -free)

Forces the tool to assume fixed or free format for the input file. If "Automatic" is set, .f90 files will be assumed to contain free format code , .f, .for, .f77, or .ftn are assumed to contain fixed format code.

"Include and module directories" (-I)

Add pathname to the list of directories which are to be searched for include files. The current working directory is always searched first, then any directories named in -I options.

"Fixed format source line length" (-132)

Increase the length of each fixed source form input line from 72 characters to 132 characters. This has no effect on free source form input.

"Allow double complex specific intrinsics" (-dcfuns)

Enable recognition of non-standard double precision complex intrinsic functions. These act as specific versions of the standard generic intrinsics as follows:

    Non-standard      Equivalent Fortran 95 Intrinsic
     CDABS(A)            ABS(A)
     DCMPLX(X,Y)         CMPLX(X,Y,KIND=KIND(0d0))
     DCONJG(Z)           CONJG(Z)
     DIMAG(Z)            AIMAG(Z)
     DREAL(Z)            REAL(Z) or DBLE(Z)

"Downgrade legacy code errors to warning" (-dusty)

Allows the analysis of ``legacy'' software by downgrading the category of common errors found in such software from ``Error'' to ``Warning'' (which may then be suppressed entirely with the -w option).

"Suppress information messages" (-info)

Suppress output of tool analysis stages information messages.

"Kind numbers"

"Byte kinds" (-kind=byte): Alter the kind numbering system used so that the kind numbers for INTEGER, REAL and LOGICAL match the number of bytes of storage (e.g. default REAL is 4 and DOUBLE PRECISION is 8). Note that COMPLEX kind numbers are the same as its REAL components, and thus half of the total byte length in the entity.
"Sequential kinds" (-kind=sequential): This confirms the default kind numbering system where all datatypes are numbered sequentially from 1 and increase with precision.

This option does not affect the interpretation of byte-length specifiers (an extension to Fortran 77).

"Downgrade argument checks between routines in different files" (-mismatch)

Downgrade consistency checking of procedure argument lists so that mismatches produce warning messages instead of error messages. This only affects calls to a routine which is not in the current file; calls to a routine in the file being compiled must still be correct.

"Downgrade argument checks between routines in the same file" (-mismatch_all)

Further downgrade consistency checking of procedure argument lists so that calls to routines in the same file which are incorrect will produce warnings instead of error messages.

"Continuation line limit" (-maxcontin)

Increase the limit on the number of continuation lines to N. The default, as specified by the Fortran standard, is 19 for fixed source form and 39 for free source form. This will not decrease the limit below the standard number.

"Output strict Fortran 95 obsolescent messages" (-strict95)

Produce obsolescence warning messages for use of ``CHARACTER*'' syntax. This message is not produced by default since most programs contain this syntax.

"Suppress warning messages" (-w=all)

Switch on or off tool analysis stages warning messages.

"Suppress obsolescent feature warning messages" (-w=obs)

Switch on or off warning messages about the use of obsolescent features.

"Suppress unused entity warning messages" (-w=unused)

Suppresses warning messages about unused entities. It is equivalent to -w=uda -w=uei -w=ulv -w=usy.

"Suppress unused dummy argument warning messages" (-w=uda)

Switch on or off warning messages about unused dummy arguments.

"Suppress unused explicit import warning messages" (-w=uei)

Switch on or off warning messages about unused explicit imports.

"Suppress unused local variable warning messages" (-w=ulv)

Switch on or off warning messages about unused local variables.

"Suppress unused symbol warning messages" (-w=usy)

Switch on or off warning messages about unused symbols.

"Suppress Fortran 77 extension warning messages" (-w=x77)

Switch on or off extension warnings for common extensions to FORTRAN 77. These are TAB format, byte-length specifiers and Hollerith constants.

"Suppress Fortran 95 extension warning messages" (-w=x95)

Switch on or off extension warnings for extensions to Fortran 95.

THE PROGRAM TEMPLATE

nag_decs95 considers the program unit to begin with an optional program unit header with preceding and following comments, followed by a number (possibly zero) of ``declarative sections'' and then by the executable statements.

USE statements are always declared first in any program unit as this is required by Fortran (this is why the Use statement section cannot be moved).

Type statements in a declarative section are ordered according to the -order option.

Any existing nag_decs95 section headers within program units will be read and their order will override the default order, or the order specified by the -sectorder and -movebefore options, for that program unit only. Any sections not found in the program unit will have the order specified by these options or the default order.

nag_decs95 will itself insert all necessary declarative sections which do not appear in the source code.

DECLARATIVE SECTION FORMAT

Each declarative section begins with a nag_decs95 section header and ends (optionally) with a nag_decs95 section trailer. The body of a declarative section consists of a number of comments followed by the declarations themselves. nag_decs95 checks to see if the header and trailer comments exist already and only inserts them if they do not. This allows nag_decs95 to be applied to a program unit more than once without duplication of comments.

The nag_decs95 section headers have the form: "!.. Section Name..", where there may be any number of spaces between the '!' and the '..', and the rest of the header matches the name of a declarative section. If the text following the '..' does not match a section name, then the comment is treated as a normal comment. The comparison between the source and the section names is done on a case-insensitive basis. These section headers may subsequently be moved, by you, in the declarative section. If you move, for example, the Local Arrays section header before the Local Scalars section header then, in that program unit only when the file is reprocessed by nag_decs95, the Local Arrays will be declared before the Local Scalars. This is not the same as -sectorder or -movebefore which specify the order in all program units. Any pre-existing section headers override the order specified by -sectorder or -movebefore.

If it is not possible to output the ``Function Return Value'' section in the specified (or default) place, because of a dependency on another declaration, this section will be output after all other sections.

The user is advised not to move section headers marked with an asterisk in the table below.

Sections may be moved, in this way, or using the -sectorder or -movebefore options, in order to declare names used in other declarations first. This will eliminate declarations in the ``Dependents'' section.

The optional nag_decs95 section trailer has the form "!.." where there may be any number of spaces between the '!' and the '..'.

The following tables show the names of all possible declarative sections.

Section (Abbreviation)

Use Statements (*)
Implicit None Statement (*)
Default Accessibility (*)
Include Lines (*)
Function Return Value (FR)
Entry Points (EP)
Parameters (PS)
Generic Interface Blocks (IG)
Non-generic Interface Blocks (IN)
Derived Type Declarations (DT)
Structure Arguments (AD)
Scalar Arguments (AS)
Array Arguments (AA)
Function Arguments (AF)
Subroutine Arguments (AB)
Local Structures (LD)
Local Scalars (LS)
Local Arrays (LA)
External Functions (XF)
External Subroutines (XB)
Intrinsic Functions (IF)
Structures in Common (CD)
Scalars in Common (CS)
Arrays in Common (CA)
Common Blocks (CB)
Namelists (NL)
Equivalences (EQ)
Save Statements (SV)
Statement Functions (SF)
Statement Function Definitions (SD)
Data Statements (*)
Dependents (*)
Previously Untyped Declarations (*)
Executable Statements (*) 


Declaration Section Names and Abbreviations



* Cannot be moved with the -sectorder option.





Section Name

Private Statements
Public Statements
Allocatable Arrays
Optional Statements
Target Statements
Pointer Statements
Intent Arguments


Non-movable Sections added by the -split option.

DERIVED TYPES

No changes are made to the definition of derived types.

INTERFACE BLOCKS

Interface Blocks are processed as if they were program units. IMPLICIT NONE statements are not added to Interface Blocks when the -imp_none option is set.

DEPENDENCIES OF DECLARATIONS

Within declaration statements names are output in alphabetical order. If there exist dependencies in, for example, array dimension expressions or initialisation expressions, the output of names that depend on other names will be suppressed until the dependencies have been output. This means that such names may appear at the end of the statement or at the end of the declarative section. In rare cases it may be necessary to output a declaration in a final section for declarations that could not be output before, called ``Dependents''.

Sections may be moved as described in the Declarative Section Format section in order to eliminate declarations in the ``Dependents'' section.