NAGWare Fortran Tools - f95 Tools - nag_prest95

 

Index

NAME
DESCRIPTION
OPTIONS
THE PRECISION PARAMETER
REAL AND COMPLEX DECLARATIONS
IMPLICIT VARIABLES
CONSTANTS
FUNCTION DECLARATIONS
MIXED PRECISION PROGRAMS
INTERFACE BLOCKS
EQUIVALENCE AND THE TRANSFER FUNCTION
INTRINSIC FUNCTIONS
SEE ALSO

 

NAME

nag_prest95 - Precision standardiser

 

DESCRIPTION

The purpose of this tool is to standardise the precision of real and complex variable declarations, real and complex constants and some intrinsic functions. Precision is specified by a KIND number which is an integer parameter. The name and value of this parameter will be set according to user options. Its definition can be either an INTEGER, PARAMETER statement or a USE statement.

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


   Precision Parameter Options

"Precision parameter name" (-ppname name)
Specifies the name of the precision parameter used in the KIND number of real and complex declarations, real and complex constants etc. The name chosen should be a legal identifier that does not conflict with names in any program unit. [Default: WP].

"INTEGER, PARAMETER :: name=KIND(0.0[e or d]0)" (-parameter value)
Specifies that a declaration of the precision parameter has or will have the form:
INTEGER,PARAMETER :: name = value
Where name is specified by the ppname option. Value must be one of the following:
      1, 2, 3, 4, 8 or 16
      KIND(0.0E0)
      KIND(0.0D0)     [Default]

Each procedure, except internal procedures, is checked for a declaration of this form, if it does not exist this statement is inserted.

"USE modname, ONLY name=>[sp, dp or qp]" (-use modname)
Specifies that a declaration of the precision parameter has or will have the form:
USE modname, ONLY : name
Where name is specified by the ppname option. Each procedure, except internal procedures, is checked for a declaration of this form, if it does not exist this statement is inserted. The -parameter and -use options are mutually exclusive. If you specify -use and not -rename sp, -rename dp or -rename qp the -use_kind option must be set.

"Use existing precision parameter" (-exwp)
If this option is set, the Precision Standardiser uses the precision parameter as specified by the -ppname option (or WP by default), if it already exists. This must be an INTEGER, PARAMETER and its value is checked for consistency with the value specified (or implied) by the -parameter, rename or -use_kind option. If a program unit does not have a definition of this precision parameter one is added in the form specified by the -ppname, -parameter, -use and -rename options (or defaults).
  

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 PRECISION PARAMETER

The user may specify the form of declaration of the precision parameter using the above options. The forms recognised are:


     INTEGER, PARAMETER :: wp = 1 | 2 | 3 | 4 | 8 | 16
     INTEGER, PARAMETER :: wp = KIND(0.0E0)
     INTEGER, PARAMETER :: wp = KIND(0.0D0)
     USE modname, ONLY : wp
     USE modname, ONLY : wp => SP
     USE modname, ONLY : wp => DP
     USE modname, ONLY : wp => QP
     USE modname, ONLY : wp => rename

The name of the precision parameter may be specified using the -ppname option, the default wp is used in the above examples and in the rest of this document. In the last example rename may be specified using the -rename option.

If no Precision Parameter Options are specified the default is:


     INTEGER, PARAMETER :: wp = KIND(0.0D0)

In all of the above forms of the declaration only the precision parameter may be present in the statement.

If -exwp is not set, the tool searches each procedure, except internal procedures, for a declaration of the specified form. If this exists in exactly the form specified no precision parameter declaration will be added. If one of the forms listed above exists and the current options specify a different form, the existing statement is deleted and the form specified is inserted in the standard place.

If present, the precision parameter declaration statement must precede all REAL and COMPLEX declarations, irrespective of whether these use the precision parameter. The new precision parameter statement, if added, will be inserted at the first legal position for the statement type.

If the precision parameter declaration is added, the procedure is checked to ensure that there is no name clash introduced. If there is, an error message is written to stderr. The unwanted definition of the precision parameter must be removed before the output code can be processed. One way to do this is to change the name of the unwanted precision parameter using nag_chname95.

If the -exwp option is set, the Precision Standardiser uses the precision parameter as specified by the -ppname option (or WP by default), if it already exists. The declaration and initialisation of the precision parameter may be in any form, but it must be an INTEGER, PARAMETER. Its value is checked for consistency with the value specified (or implied) by the -parameter, -rename, or -use_kind option as appropriate. If a program unit does not have a definition of this precision parameter one is added in the form specified by the -ppname, -parameter, -use and -rename options (or defaults).

 

REAL AND COMPLEX DECLARATIONS

All real, double precision and complex declarations are changed to the form:


          REAL (KIND=wp) :: x...
          COMPLEX (KIND=wp) :: z...

or


          REAL (wp) :: x...
          COMPLEX (wp) :: z...

This is done everywhere, including interface blocks. The precision parameter wp can be specified by the user. The presence of the optional ``KIND='' is controlled by a polish option, see nag_polopt95. The quadruple precision forms of the precision parameter statement are only available on some platforms, see the Technical Information note for details.

 

IMPLICIT VARIABLES

All implicitly typed real, double precision and complex variables are declared as above.

 

CONSTANTS

All real constants (including real and imaginary parts of complex constants) have the WP kind appended. For example:


          A=0.0D0

becomes


          A=0.0E0_WP

 

FUNCTION DECLARATIONS

Real, double precision and complex functions are declared with a separate declaration, within the function, for the function name, e.g.


          REAL FUNCTION FUNC1(A)

is declared thus:


          FUNCTION FUNC1(A)
          USE precision, ONLY: wp => sp
          REAL (KIND=wp) :: func1

Implicitly typed real and complex functions are given a declaration as above.

Functions that have a RESULT clause have the result variable declared not the function name.

 

MIXED PRECISION PROGRAMS

The purpose of the tool is to change all reals and complex to a standard precision. If there is more than one precision in the input program, a warning message is generated, and all real and complex entities are converted to the specified type.

 

INTERFACE BLOCKS

The tool adds a precision parameter declaration to each interface. nag_prest95 will convert the precision of any real and complex arguments and functions in interface blocks. Obviously it is important either to ensure that the precision is unchanged, or that the routine to which the interface block refers is processed in the same way. Generic interfaces may be changed by the tool in such a way as to render the code illegal. A warning message is produced if a generic interface is processed.

 

EQUIVALENCE AND THE TRANSFER FUNCTION

All EQUIVALENCE statements are checked. If they contain real or complex data type, an appropriate warning message is generated. The tool will continue to produce an output file, but this may not be legal code or the meaning of an equivalence may have been changed. For example, changing the value of the precision parameter may change the meaning of an equivalence.

Similarly all TRANSFER function references are checked.

 

INTRINSIC FUNCTIONS

A first pass converts all non-generic intrinsics to their generic form. Also, the generic ``DBLE'' is converted to ``REAL'', and the optional KIND parameter is added to the intrinsics ``REAL'' (but not when its argument data type is complex) and ``CMPLX''.

If an intrinsic function is explicitly typed or used as an actual argument, the tool will error terminate. If the name of the replacement generic intrinsic function is already used for some other purpose, the specific intrinsic will not be replaced, and a warning message produced.

The DPROD intrinsic function is left unchanged. A warning message is output when a program unit contains the DPROD intrinsic.

Simple Intrinsic Function Replacements

Non-generic              Generic Replacement
  DSINH                         SINH               
  DCOSH                         COSH               
  DTANH                         TANH               
  IFIX                          INT                
  IDINT                         INT           
  FLOAT                         REAL               
  SNGL                          REAL               
  DINT                          AINT               
  DNINT                         ANINT              
  IDNINT                        NINT              
  IABS                          ABS                
  DABS                          ABS                
  CABS                          ABS                
  AMOD                          MOD                
  DMOD                          MOD                
  ISIGN                         SIGN               
  DSIGN                         SIGN               
  IDIM                          DIM                
  DDIM                          DIM                
  MAX0                          MAX                
  AMAX1                         MAX                
  DMAX1                         MAX         
  MIN0                          MIN     
  AMIN1                         MIN    
  DMIN1                         MIN    
  DSQRT                         SQRT   
  CSQRT                         SQRT   
  ALOG10                        LOG10 
  DLOG10                        LOG10 
  DEXP                          EXP     
  CEXP                          EXP     
  ALOG                          LOG     
  DLOG                          LOG     
  CLOG                          LOG     
  DSIN                          SIN     
  CSIN                          SIN     
  DCOS                          COS     
  CCOS                          COS     
  DTAN                          TAN     
  DASIN                         ASIN   
  DACOS                         ACOS   
  DATAN                         ATAN   
  DATAN2                        ATAN2 
  DBLE                          REAL

More Complex Intrinsic Function Replacements

Non-generic        Generic Replacement 
  AMAX0(...)          REAL(MAX(...)) 
  AMIN0(...)          REAL(MIN(...)) 
  MAX1(...)           INT(MAX(...)) 
  MIN1(...)           INT(MIN(...))

Double Complex Function Replaceements

Non-generic       Generic Replacement 
  CDABS               ABS
  DCMPLX              CMPLX
  DCONJG              CONJG
  DIMAG               AIMAG
  DREAL               REAL

Note: The -dcfuns option must be specified for the tools to recognise the Double Complex non-generic form.

 

SEE ALSO

nag_polopt95, nag_modules95, nag_chname95.

Copyright, Numerical Algorithms Group, Oxford, 1997-2001