8 Procedure and Module

8.1 Program units

In FORTRAN95 there are 3 types of procedures: Subroutines, SUBROUTINE) Functions (FUNCTION) and the Blockdata-program unit (BLOCKDATA). In addition there is the MODULE and the PROGRAM (main program) program unit available Subroutines and functions can be defines as external

procedures. (FORTRAN77) or internal procedures (integrated into in a PROGRAM, external procedure or MODULE program unit).
External program units represent program units which are compiled independently from each other. The loader (ld-command) finally combines the main program (program) and the program units referenced by the already included program units (starting from a PROGRAM) into an executable program. Each program unit can be managed for its own and may be stored in an individual source code file. The compiler will create an object file from an individual procedure source code other then a PROGRAM. An executable program can be created by compiling only if a main program (PROGRAM) is included into the list of source code files.
Procedures (subroutines and functions) can be declared as external or as internal procedures within a main program, a module or another procedure.
Internal procedures are valid only within that program unit in which they are defined in. However they know all definitions that are valid within this program unit and thus do not need an argument list for the exchange of data.
A external procedure or a program unit must be terminated by an end statement.
External procedures can be folded in libraries which can be managed by the ld-command when linking the program. Procedures are accessed by their name and an optional argument list.

Usage of program units offer some advantages:

• create more structured program
• usage within different programs
• independent development and testing
• improved optimization by some compilers
• creation of (procedure-) libraries

8.2 Functions

Functions (FUNCTION) represent a procedure which will return a value (or data structure, derived data type or array) by the FUNCTION's name. The FUNCTION can get data by an argument list, while these arguments remain unchanged. Thus FUNCTION may be used only if a single value should to be returned. The type of the FUNCTION defines the type of the value which is returned by the FUNCTION's name. If no trype is assigned to the functions's name the typing rules for FORTRAN (variables) are applied.

• [type:] FUNCTION fname ([p_''1'', p_''2'', +_''3'',...]} [RESULT (ergval)]
  ...
  fname= ...
  ...
  RETURN
  END
  type type of the FUNCTION (i.e. Type of the returned value)
  fname name of the FUNCTION
  p_''i'' argument
  ergval return value

Almost all FORTRAN 95 instructions can be used within a FUNCTION. The END-statement completes the source text area of the FUNCTION program unit. A external function may contain internal procedures.
The execution of a FUNCTION is terminated when a RETURN statement is executed. The execution then is continued in the calling program. In a FUNCTION several RETURN statements are permitted. Before leaving the FUNCTION (executing the RETURN statement) a value must be assigned to the FUNCTION's name.
The call of a FUNCTION is made by a reference to the FUNCTION name (with corresponding list of arguments). The value returned by a FUNCTION can be used as a data values of the same type.
A FUNCTION with no argument list is indicated by an empty pair of brackets ().

Please see Example 1

8.2.1 Formula Functions

A formula function (statement function) is not a program unit but represents a FUNCTION which is valid only within the program unit where it is defined. It is restricted to a single expression. It returns a value as a FUNCTION of the elements specified in the argument list. The type of a formula function is defined by its name. The definition of a formula function must be located within the declaration part of the program unit (before the first executable statement is specified).

• fname ([p_''1'',p_''2'',p_''3'',...]} = expression
  fname name of the FUNCTION
  p_''i'' argument

Please see Example 2

Please do Tasks 8.3 and 8.4

8.3 Subroutines

A SUROUTINE is a program unit for which all elements of the argument list can be changed within the SUROUTINE. The changed values are available in the calling program unit after leaving the SUROUTINE.

• SUBROUTINE sname ([p_''1'',p_''2'',p_''3'',...]}
  ...
  RETURN
  END[SUBROUTINE sname]]
  sname name of the SUBROUTINE
  p_''n'' argument

The execution of a SUBROUTINE is terminated when a RETURN statement is executed. There may be more than one RETURN statements. The END-statement completes the source text area of the SUROUTINE. The first RETURN statement which is reached in the course of the program execution causes a jump back into the calling program unit.

• CALL sname ([V_''1'',v_''2'',v_''3'',...]}
  ...
  sname name of the SUBROUTINE
  v_''n'' argument

The call of a SUROUTINE is carried out by the CALL statement specifying the name of the SUROUTINE and its argument list. The number and order of the elements in the argument list must be consistent (in order, type, structure, shape) with the argument list specified by the subroutine declaration.

Please see Example 3

Please do Tasks 8.2 and 8.6

8.4.2 Internal Procedures

A procedure (SUBROUTINE or FUNCTION) which only exists within a program unit is called an internal procedure. It must be declared within the CONTAINS - END section (at the end) of a program unit. It can be accessed only within the program unit (see. Fig. above) where it is defined. All variables declared in the program unit are accessible for all internal procedures without being specified in an argument list. Module procedures (procedures internal to a MODULE) however are accessible for all program units which make use of the module.

Please see Example 5

Please do Tasks 8.5 and 8.7

8.4.2 Internal Procedures

A procedure (SUBROUTINE or FUNCTION) which only exists within a program unit is called an internal procedure. It must be declared within the CONTAINS - END section (at the end) of a program unit. It can be accessed only within the program unit (see. Fig. above) where it is defined. All variables declared in the program unit are accessible for all internal procedures without being specified in an argument list. Module procedures (procedures internal to a MODULE) however are accessible for all program units which make use of the module.

Please see Example 5

Please do Tasks 8.5 and 8.7

8.4.4 Recursive Procedures

FORTRAN95 permits the declaration of procedures which can call themselves. These (recursive) procedures must be declared by the keyword RECURSIVE. In addition recursive FUNCTIONs must specify a RESULT variable which keeps the function's result.

• RECURSIVE SUBROUTINE sname ([p_''1'',p_''2'',p_''3'',...]
  ...
  RETURN
  END [SUBROUTINE [sname}]]
  or:
  RECURSIVE [type] FUNCTION sname ([p_''1'', p_''2'', p_''3'',...]} RESULT (res)
  ...
  res = ...
  RETURN
  END [FUNCTION [fname]]
  sname name of the SUBROUTINE
  fname name of the FUNCTION
  type type of the FUNCTION
  p_''i'' argument
  res result variable

Please see Example 7

8.5 Procedure arguments

8.5.1 Handing over variables and arrays

The handing over of parameters from the calling program to a procedure is done according to the argument list provided by the procedure's specification. The number, data type, structure, and shape of quantities specified in the argument list must be identical for the calling and called program unit. Exceptions are possible for optional (need not be included) and keyword (variable position) arguments. For arrays or sub-arrays the order of elements in memory is relevant even if sub-arrays are specified in the argument list. However only the address of the first element is handed over to the procedure.

Please see Example 8

In FORTRAN95 the ordering of elements in the argument list may be changed when calling a procedure (keyword argument) or arguments may be omitted (optional arguments).

Please see Example 9

Please see Example 10

Please do Tasks 8.9 and 8.11

8.5.2 Handing over character strings to procedures

To be able to submit character strings of variable length to a procedure, the corresponding argument must be declared with length * within the procedure.

Please see Example 11

8.5.3 Handing over arrays of variable size

It is possible to keep the size of arrays handed over to a procedures variable. The size of dimension of an array can be handed over to a procedure by elements of the argument list.

Please see Example 12

Also there is the possibility to not specify the topmost dimension of a field handed over in the argument list. In this case the (topmost) dimension has to be specified with size *.

Please see Example 13

In this case it must be ensured that the index range is not violated when accessing array elements during program execution. There is no array bound check available. Accessing array elements out of range may lead to unpredictable results.

8.5.4 Handing over procedure names

The name of an external (or intrinsic) procedure can by passed to a procedure if is declared by use of the INTRINSIC or EXTERNAL statement (in the calling program unit as well as in the procedure).

• EXTERNAL uname _''1'' [,...,uname_''n'']
  uname name of the external procedure

Intrinsic procedures are those functions and subroutine that are internal to the FORTRAN 90 system. This declaration must be located in the declaration part of the program unit.

• INTRINSIC uname _''1'' [,...,uname_''n'']
  uname name of the intrinsic procedure

8.6 Properties (attributes) of procedure Arguments

Variables specified in the argument list of a procedure call may have specific attributes (INTENT, SAVE, OPTIONAL, KEYWORD etc.). The have to be specified in the procedure's type declaration:

The sequence of arguments may be different for the list specified in the procedure definition if the name of the argument is used as keyword (i.e. varname=value)

Please see Example 14

8.6.1 SAVE attribute

A variable local to a procedure (not part of the arguments list, of COMMON-block or modules) exist only during the runtime of the procedure.
If a local variables is defined with attribute save its value is kept and unchanged if the procedure is called again. Variables exchanged with the calling program (procedure arguments) cannot have the save attribute.
For variables declared with save attribute within Module their values are kept for all program units that use the module. Thus they represent a 'common' variable (in the sense of COMMON-blocks).

8.7 Interface blocks

Interface blocks contain information which the compiler needs to ensure a correct call of external procedures. Interface blocks are required particularly in the following cases, however they should be provided for all external procedures:

• calling a procedure with keyword parameters
• calling a procedure with optional parameters
• using overloaded operators
• using overloaded assignments
• calling a functions which returns an arrays
• using generic procedures

An INTERFACE block has the following structure:

• INTERFACE name or
  INTERFACE operator
  Proc-definition
  [...]
  END INTERFACE
  Proc-definition definition of the procedure-interface: specifying the program unit and the elements
  of the argument list

Please see Example 15

8.8 COMMON blocks

An additional method to provide data to a procedure is the use of common memory areas. They are declared by use of the COMMON statement. The data stored in common blocks are available in all those program units for which the COMMON block is referred to. The storage for elements associated with a COMMON block are stored in memory only once. Thus all access to an element is carried out for the same memory location. COMMON blocks offer therefore the possibility to avoid long argument lists for procedure calls and may save memory space too.

COMMON [/name/] v_i [,v₂, v₃,...]
name name of the Common-Block
v_''i'' variable of array

There can be one unnamed COMMON block. The COMMON statement is a non-executable statement and thus must be located in the declaration part of a program unit.
In FORTRAN 95 the functionality of COMMON blocks should be replace by use of MODULES.

Please see Example 16

8.9 Blockdata (obsolet!)

The non executable program unit BLOCKDATA is needed for assigning (initial) data to COMMON block elements.

• BLOCK DATA [name]
  specifications
  END
  name name of the BLOCKDATA procedure

In a BLOCKDATA procedure only PARAMETER, IMPLICIT, DIMENSION, COMMON, EQUIVALENCE and DATA statements are permitted as well as the END statement for marking the end of a BLOCKDATA program unit.

Please see Example 17

8.10 Scope

Every procedure has its own independent set of labels. Thus the same label may be use in a main program and its internal procedures without causing a conflict.
The scope of a name is restricted to the program unit where it is defined. The scope of the internal procedure and of its number and type of arguments extend throughout the complete program unit and therefore all other internal procedures. There are smaller scoping units : TYPE-declarations, internal functions, etc.
The scope of a name declared within a module extents to all program units that use the module unless the name has the attribute PRIVATE.

Please see Example 18

Please do Tasks 8.1, 8.8, 8.10, 8.12, and 8.15

1. Module

2. MODULE mname
   [declaration part]
   [executable part]
   [CONTAINS
   Produce definition(s)
   ...]
   END MODULE mname
   mname name of the MODULE

A MODULE is a non-executable program unit which may contain only definitions, specifications and (internal) procedures. It permits the common use of procedures and variables by different program units, without an explicit use of argument (exchange) lists. The variables specified in a MODULE are located in the memory only once. The module concept contains among others the COMMON block concept available under FORTRAN 77. Thus the COMMON blocks shouldn't be used any more!

Please see Example 19

A module is assigned to a program unit by applying of the USE statement. It must be the first statement in a program unit.

• USE mname or
  USE mname, local_name_''i'' => varname_''i'' [,...] or
  USE mname [, ONLY : varname_''i'' [,...]] or
  USE mname [, ONLY : local_name_''i''=> varname_''i'' [,...]]
  mname name of the module
  varname_''i'' name of a module variable
  local_name local name of the module variable varname_''i'' within a program unit which uses
  the module

Please see Example 20

The PRIVATE statement defines variable or module procedures as not visible outside the module. This prevents the modification (and access) to these variables and procedures from outside the MODULE.

PRIVATE or<<BR>> PRIVATE

sname_''i'' [,...] or
PRIVATE :: varname_''i'' [,...]
sname name of the MODULE procedure
varname_''i'' name of a MODULE variable

The PUBLIC statement (default) causes that the according variable or module procedures may be used from program unit using the MODULE.

PUBLIC or<<BR>> PUBLIC

sname_''i'' [,...] or
PUBLIC :: vqrname_''i'' [,...]
sname name of the MODULE procedure
varname_''i'' name of a MODULE variable

Hence procedures and data (which have not declared to be PRIVATE) defined in a MODULE are available to all programs units which have included the module by applying the USE statement.

Please see Example 21

Please do Tasks 8.13 and 8.14