This tool generates Fortran interface blocks to define the interface to external procedures. Wherever an external procedure is referenced the appropriate interface block is made visible. This allows a compiler to perform better checking of argument passage, especially if the program is made up of several files. nag_mkintf95, in the process of building interface blocks, carries out global argument passage checking (except procedure parameters) over multiple files. The interface blocks generated by nag_mkintf95 provide information to a Fortran compiler which enable it to carry out the checking of procedure parameters when the code is subsequently compiled.
By default the interface blocks are placed in a module and then appropriate USE statements placed in each scope to make the interface blocks visible. Alternatively the -inline option can be used to place interface blocks inline in the source code wherever they are needed.
The tool works best with a complete program unit, but if it is not possible to supply the source for all external procedures (e.g. if pre-compiled libraries are being used or externals are written in another language) the tool by default will build interface blocks based on the actual arguments passed in calls to the missing external procedure (see ``BUILDING INTERFACES FOR MISSING EXTERNAL PROCEDURES'' below).
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.
More Advanced Options
REAL a(5) . . CALL sub_1(a(3))
sub_1's dummy argument may be a scalar of type REAL or an array of type REAL.
Because of this ambiguity the tool by default will not generate an interface block in this situation and a warning will be generated. This option causes the tool to assume that the dummy argument is an array and so enable interface block generation. This may be an incorrect assumption (a warning is generated).
General Options
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)
This option does not affect the interpretation of byte-length specifiers (an extension to Fortran 77).
BUILDING INTERFACES FOR MISSING EXTERNAL PROCEDURES
The tool works best with complete programs, however if there are missing procedures the tool, by default, will still try to generate the best interface blocks possible for the missing ones. In certain circumstances the interface blocks inferred by the tool for the missing procedure may be subject to certain limitations. These are discussed in the following sections.
If the source for an external procedure is not supplied, and an explicit interface cannot be found, by default an interface block will still be built if enough information regarding the argument structure can be inferred from calls to the external procedure.
The user should be aware that if a call to an external procedure which has not been supplied is incorrect, obviously the interface block built will be incorrect (though the tool will check that calls are consistent). There are also some cases where there is not enough information available to fully ascertain the nature of a dummy argument (detailed in ``IMPRECISE SPECIFICATION OF DUMMY ARGUMENTS''). In these situations the tool will generate the best possible.
The tool will always issue a warning if it infers an interface for a missing external procedure. The -nocallproc flag can be used to stop the tool building interfaces for missing external procedures.
In the following example the tool will generate an interface block for sub_2, where sub_2 is missing, by evaluating the overall type of each expression passed as an argument:
PROGRAM main EXTERNAL sub_2 INTEGER :: a = 2 REAL :: b = 3.4 . . CALL sub_2(6,a*b) . END
The first argument of sub_2 will be declared as a default-kind integer and the second argument as a default-kind real.
If however a missing external procedure is only passed as an argument in the source code and not called directly:
INTEGER, EXTERNAL :: f . . CALL sub_3(f)
the tool cannot currently generate an interface block for the missing external procedure (a warning is generated).
BUILDING INTERFACES FOR DUMMY PROCEDURES
If an external procedure has a dummy procedure argument but there is
no interface
block to define the dummy procedure's argument structure,
the tool by default will build an interface block based on
calls to the dummy procedure from within the external procedure.
The user
should be aware that if a call to a dummy procedure
is incorrect, obviously the interface block built
will be incorrect (though the tool will check that calls are consistent).
There are also some cases where there is not
enough information available to fully ascertain the nature
of a dummy argument (detailed
in ``IMPRECISE SPECIFICATION OF DUMMY ARGUMENTS'').
In these situations the tool will generate the best possible.
The tool will always issue a warning if it infers an interface for a dummy procedure. The -nodummy flag can be used to stop the tool building interfaces for dummy procedures.
In the following example, the tool will generate an interface block to define the arguments of dummy procedure dumproc. This will be placed inline in procedure sub_4 as well as within the interface block generated for sub_4 in the interface block module:
SUBROUTINE sub_4(dumproc) EXTERNAL dumproc . . CALL dumproc(3) . END SUBROUTINE sub_4
If however a dummy procedure is only passed as an argument and not called directly:
SUBROUTINE sub_5(dumproc) EXTERNAL dumproc . . CALL next(dumproc) . END SUBROUTINE sub_5
the tool cannot currently generate an interface block for the dummy procedure (a warning is generated).
IMPRECISE SPECIFICATION OF DUMMY ARGUMENTS
If the tool is building an interface for a missing external procedure or dummy procedure based on a call, enough information will usually be available to the tool to generate an accurate interface (provided the arguments passed in the call are correct). The following situations are those where the tool has incomplete information. In these cases the tool will generate the best possible.
Array arguments
If an array is passed as an argument, e.g.
REAL,DIMENSION(20,20) :: a CALL sub_6(a)
the expressions which define the dummy argument array bounds are not available. In this case the tool will generate an assumed-size array specification:
INTERFACE
SUBROUTINE sub_6(sub_6_0)
REAL :: sub_6_0(*)
END SUBROUTINE sub_6
END INTERFACE
Also if a reference to an array element is used as an actual argument the corresponding dummy argument may be an array or a scalar, e.g.
REAL a(5) CALL sub_7(a(3))
sub_7's dummy argument may be a scalar of type REAL or an array of type REAL. The tool will not generate an interface block for sub_7 and a warning is generated. The -array flag may be used to force the tool to assume it is an array.
Character string arguments
If an actual argument is a character string the tool will generate len=* for the corresponding dummy argument in the interface block.
Dummy procedure arguments
An interface block will not be generated for a dummy procedure argument. Note this is true even if the actual procedure passed as argument has an explicit interface in the current scope.
Kind numbers
The kind number expression of an actual argument is evaluated and the result used as the kind number for the corresponding dummy argument. The kind numbers generated follow the NAGWare f95 compiler kind numbering scheme in force when the tool is invoked, see -kind.
TOOL GENERATED DUMMY ARGUMENT NAMES
If the tool generates an interface block for a missing external procedure or dummy procedure, the tool uses the following naming scheme for the dummy arguments:
The argument names take the form <procedure_name>_<num> where num is the position of the argument in any call, e.g.
EXTERNAL sub_8 CALL sub_8(6,0.5)
yields:
INTERFACE
SUBROUTINE sub_8(sub_8_0,sub_8_1)
INTEGER :: sub_8_0
REAL :: sub_8_1
END SUBROUTINE sub_8
END INTERFACE
Note that a name clash can occur if, in the above example, an argument is of a user defined type named sub_8_0 (an unlikely occurrence).
CHARACTER ARGUMENT LENGTH EXPRESSIONS
If a dummy argument of an external procedure is of type character and has a constant expression defining its length, the expression is evaluated and the result used in the interface block.
ASSUMED LENGTH CHARACTER FUNCTIONS
Assumed length character functions, e.g.
CHARACTER(len=*) FUNCTION f() END FUNCTION f
will not have an interface block generated (if the function is not supplied in the source code it is assumed to be len=*).
WARNING
When a module containing all the interfaces is created, it is possible, but unlikely, that a cyclic dependency of USE statements might result. This could happen where a module procedure calls an external procedure with a derived type argument defined in that same module. Either the -inline option must be used or all the problematic derived types can be moved to a separate module or modules.
The nag_mkintf95 tool is being improved and some of the above restrictions will be removed in subsequent releases of the tool.
Copyright, Numerical Algorithms Group, Oxford, 1997-2001