Procedures

Intrinsic procedures are those available for use without any declaration or definition. They are described in detail in Chapter 11.

Intrinsic procedures provide a way to incorporate into standard Fortran 90 the most common computations important to scientific and engineering applications. Standard Fortran 90 has 108 intrinsic functions and 5 intrinsic subroutines. Table 12 lists the different categories of intrinsic functions and gives the total number of intrinsic functions for each category.

Some intrinsic procedures are known as elemental; that is, they can also take scalar arguments to produce a scalar result, but they can accept conformable arrays as arguments, in which case they operate on each array element separately and return an array as a result.

Several different intrinsic procedures can be called using the same name when the actual arguments are of different kinds, types and ranks. For example when using SQRT(x), x can be of type real or complex, it can be of any defined kind, and it can be an array of any of these types, of any rank. The name used is a generic name for a set of procedures, each of which accepts an argument of a fixed kind, type, and rank.

An external procedure is a separately compilable program unit whose name and any additional entry points have global scope.

A module procedure can appear only within a module. Its name can be made available outside the scope of its host only by use association. It is not otherwise accessible outside of its host.

An internal procedure can appear only within a main program, an external subprogram, or a module subprogram. It cannot have additional entry points, and it is not accessible outside its host. It appears between a CONTAINS and END statement of its host.

A subroutine subprogram is referenced by using the CALL statement specifying the subroutine name, one of its entry point names, or when the subroutine is implementing an assignment operation.

The syntax of the CALL statement is:

CALL subroutine-name [([actual-argument-spec-list])]

label is permitted in HP Fortran 90 in fixed source form only.

Alternate returns are arguments which permit control to branch to a particular label following the call. label is the statement label of an executable statement in the same scoping unit as the CALL statement.

A function subprogram is referenced by its name, by one of its entry point names or by the operator defined by the function.

The syntax of a function reference is:

function-name ([actual-argument-spec-list])

where actual-argument-spec is as above, except that an alternate return cannot be included.

On invocation, the calling program unit can identify actual arguments that are then associated with dummy arguments in the procedure definition. This is also applicable to subroutine subprograms.

The interface of a procedure is the information required to compile a call to the procedure. This information includes the characteristics of the dummy arguments and of the result for a function procedure. It is explicit if all of these characteristics are defined within the scope of the reference. If they are not, the compiler may be able to make sufficient assumptions about them and the interface is then implicit. Under many circumstances an explicit interface is mandatory. Internal procedures and module procedures always have an explicit interface.

Explicit interfaces can be specified by means of an INTERFACE block. An INTERFACE block is also used to define the extended use of the standard operators, to define new operators and to extend the definition of the assignment operator. Additionally, it provides the capability of using a generic name to reference any one of a set of procedures.

The user can define a generic name and code several procedures to cater for the required different combinations of argument characteristics. Then, by including the specifications of these routines within an interface definition, use just the generic name for referencing any of the procedures (the choice of procedure being determined by matching actual and dummy arguments). The technique can also be used to extend the selection of argument types.

HP Fortran 90 provides two functions, %VAL and %REF, that can be used to communicate with procedures written in programming languages other than Fortran that have different argument passing conventions. These functions specify how an actual argument is to be passed in a procedure reference.

These two routines may only be used in either an interface block, or in the actual CALL statement or function reference.

For information about %VAL and %REF, see the description of the CALL statement in Chapter 10 and of the ALIAS directive in Chapter 14.

The following example uses %VAL and %REF in an interface block:

PROGRAM foobar 

   INTERFACE

       SUBROUTINE fred(%VAL(X))

         INTEGER :: x

       END SUBROUTINE fred

       FUNCTION foo (%REF(ip))

         INTEGER :: ip, foo

       END FUNCTION foo

   END INTERFACE

   ...

CALL fred(i)  ! The value of i is passed to fred

j = foo(i)    ! i passed to foo by reference,

              ! foo receives a reference to

              ! the value of i.

END PROGRAM

In the next example, %REF and %VAL appear in the actual procedure references:

   PROGRAM foobar

      INTEGER :: foo

      EXTERNAL foo, fred

      ...

      CALL fred (%VAL(i))

      j = foo(%REF(i))

   END PROGRAM

Procedure interfaces and interface blocks are described later in this chapter.

Functions and subroutines are defined in Fortran 90 by means of subprograms.

A subroutine subprogram has the form:

subroutine-statement  

     [specification-part]

     [execution-part]

     [internal-subprogram-part]

end-subroutine-statement

A function subprogram has the form:

function-statement

    [specification-part]

    [execution-part]

    [internal-subprogram-part]

end-function-statement

Internal procedures are defined by internal subprograms in the internal subprogram part of a main, external, or module program unit. Internal subprograms can be recursive. The following restrictions apply to internal subprograms:

Following is an example of an internal function:

SUBROUTINE printav

! Start of external subprogram.

  REAL, DIMENSION(3) :: x

  ! Specification part.

  x=(/2.0,5.0,7.0/)

  PRINT *,av(x)

  ! Reference to function av.

  CONTAINS

    REAL FUNCTION av(a)

    ! Start of internal subprogram.

      REAL a(:)

      av=SUM(a)/SIZE(a)

      ! References to intrinsic functions.

    END FUNCTION av

END SUBROUTINE printav

An internal or external procedure that directly or indirectly invokes itself is recursive. Such a procedure must have the word RECURSIVE added to the FUNCTION or SUBROUTINE statement.

If both RECURSIVE and a result clause are specified in the FUNCTION statement , then the interface of the function being defined is explicit within the subprogram.

The following is a recursive function:

RECURSIVE FUNCTION factorial (n) RESULT(r)

  INTEGER :: n, r

  IF (n.ne.0) THEN

    r = n*factorial(n-1)

  ELSE

    r = 1

  ENDIF

END FUNCTION factorial

If an evaluation of a function with a scalar value can be expressed in just one Fortran assignment statement, such a definition can be included in the specification part of a main program unit or subprogram. This definition is known as a statement function, and is local to the scope in which it is defined. The syntax is:

function-name (dummy-argument-list) = scalar-expression

All dummy arguments must be scalars. All entities used in the expression must have been declared earlier in the specification part. A statement function can reference another statement function that has already been declared. The name cannot be passed as a procedure-name argument.

The following example declartes and uses the statement function vol:

vol(r,h) = 3.14*h*r**2

! Definition, within the specification part

! of the subprogram.

   ...

      total = n * vol(0.5*d,x)

! Reference to the statement function, from

! within the same program unit.

If no keyword= component of an actual-argument-spec is included in the reference, then each actual argument is assumed to correspond with the dummy argument in the equivalent position in the dummy argument list. The actual arguments may appear in any order if the keyword option is used for all arguments. Actual arguments without the keyword option may be followed by an argument with the keyword option. However, an argument with the keyword option must only be followed by other arguments with the keyword option.

Dummy arguments can be declared with the OPTIONAL attribute. If they appear at the end of the dummy argument list, the reference can omit any trailing arguments that are not required. Otherwise, keywords must be provided to maintain an identifiable correspondence.

Example of argument correspondence

The intrinsic function SUM (described in Chapter 11) has three arguments: array, dim, and mask, in that order, and dim and mask are optional arguments. The following are valid references:

SUM(a,2)

SUM(a,MASK=a.gt.0)

SUM(DIM=2,ARRAY=a)

The following is an invalid reference—the mask keyword should have been specified:

SUM(a,DIM=2,a.gt.0) ! Invalid

Dummy and actual arguments must agree in kind, type, and usually in rank—that is, both scalars, or both arrays of the same dimensionality. An actual argument that is an expression or a reference to a function procedure must match the type and kind of the dummy argument.

Array dummy argument

The different sorts of Fortran 90 arrays are described in Chapter 4.

If the dummy argument is an assumed-shape array, then the corresponding actual argument must match in kind, type, and rank; the dummy argument assumes its shape (the number of elements in each dimension) from the actual argument, resulting in an element-by-corresponding-element association between the actual and dummy arguments.

If the dummy argument has explicit shape or assumed size, the kind and type of the actual argument must match but the rank need not, as the elements are matched by sequence association. That is, the actual and dummy arguments are each considered to be a linear sequence of elements in storage without regard to rank or shape, and corresponding elements in each sequence are associated with each other.

A consequence of this sequence association is that the overall size of the actual argument must be at least that of the dummy argument, and only elements within the overall size of the dummy argument can be accessed by this subprogram.

The following example illustrates sequence association.

Assuming that an actual array argument is declared thus:

REAL a(0:3,0:2)

And that the corresponding dummy array argument is declared thus:

REAL d(2,3,2)

Then the following correspondence between elements of the actual and dummy argument is achieved:

Dummy <=> Actual

d(1,1,1) <=> a(0,0)d(2,1,1) <=> a(1,0)

d(1,2,1) <=> a(2,0)

...

d(2,3,2) <=> a(3,2)

When an actual argument and associated dummy argument are default character arrays, they may be of unequal character length. If this is the case, then the first character of the dummy and actual arguments will be matched, and the successive characters, rather than array elements, will be matched.

The next example illustrates character sequence association.

Assuming that an actual argument array is declared thus:

CHARACTER*2 a(3,4)

and that the corresponding dummy array argument is declared thus:

CHARACTER*4 d(2,3)

then the following correspondence between elements of the actual and dummy argument is achieved:

Dummy <=> Actual

d(1,1) <=> a(1,1)//a(2,1)

d(2,1) <=> a(3,1)//a(1,2)

...

d(2,3) <=> a(2,4)//a(3,4)

An actual argument may be an array section, but passing an array section to a nonassumed shape dummy argument may cause a copy of the array section to be generated and is likely to result in a degradation in performance.

Procedure dummy argument

If a dummy argument of a procedure is used as a procedure name within the procedure, then the actual argument must be the name of an appropriate subprogram, and its name must have been declared as EXTERNAL in the calling unit or defined in an interface block. Internal procedures, statement functions and generic names may not be passed as actual arguments.

If the actual argument is an intrinsic procedure, then the appropriate specific name must be used in the reference, and must be declared as INTRINSIC in the calling unit.

Example

DOUBLE PRECISION dsin,x,y,fun

INTRINSIC dsin

...

y=fun(dsin,x)

...

DOUBLE PRECISION FUNCTION fun(proc,y)

DOUBLE PRECISION y, proc

...

fun=proc(y)

...

END

If a subroutine call or function reference would cause a data object to be associated with two or more dummy arguments, then that data object must not be (re)defined within the subroutine or function. Consider the following example:

PROGRAM p

   CALL s (a,a)

CONTAINS

   SUBROUTINE s (c,d)

     c = 22.01        ! invalid definition of

                      ! one of the dummy

                      ! arguments associated

                      ! with data object a

    ...

  END SUBROUTINE

END PROGRAM

Both dummy arguments, c and d, are associated with the actual argument a. The definition of a, through the assignment to the dummy argument c, is invalid. The above rule is extended to when the actual arguments are overlapping sections of the same array.

Similarly, if a data object is available to a procedure through both argument association and either use, host, or storage association, then the data object must be defined and referenced only through the dummy argument.

In the following code, the data object a is available to the subroutine as a consequence of argument association and host association. The reference to a directly in the subroutine is illegal.

PROGRAM p

   CALL s (a,b)

CONTAINS

   SUBROUTINE s (c,d)

     c = 22.01     ! valid definition of a

                   ! through the dummy

                   ! argument

     d = 3.0*a     ! reference to a directly

                   ! is illegal

    ...

  END SUBROUTINE

END PROGRAM

To enable additional checking to be performed on argument matching and to avoid possible unwanted side effects, an INTENT attribute can be declared for each dummy argument, which may be specified as INTENT(IN), INTENT(OUT) or INTENT(INOUT).

The values that may be specified for the INTENT attribute have the following significance:

When an external procedure (one which is outside the prevailing scope) or a dummy procedure is referenced, it is sometimes necessary for its interface to be made explicit. This is achieved by the provision of an interface block which is accessible to the scoping unit containing the procedure reference. An interface block can also be used to:

An explicit interface is described by an interface block, which appears in the specification part of the programming unit containing the procedure reference. An interface block may appear in any program unit, except a block data program unit.

The syntax for an interface-block is:

INTERFACE [generic-spec]

   [interface-body]...

   [MODULE PROCEDURE module-procedure-name-list]

END INTERFACE

The MODULE PROCEDURE statement is permitted in an interface block only if there is a generic-spec present.

In the following example, the procedure interface for the function av is made explicit by the inclusion of the interface block in the main program.

Example

REAL FUNCTION av(a)

! External function av with one assumed-shape

! dummy argument.

  REAL a(:)

  av = SUM(a)/SIZE(a)

END

PROGRAM main

REAL,DIMENSION(3) :: x

INTERFACE

  REAL FUNCTION av(a)

  REAL, INTENT(IN) :: a(:)

  END FUNCTION av

END INTERFACE

x=(/2.0,4.0.7.0/)

PRINT *, av(x)

END

The concept of generic names and procedures was introduced in Fortran with the provision of generic intrinsic procedures. In Fortran 90, this concept is extended to allow user-defined generic procedures.

Two or more procedures are said to be generic if they can be referenced with the same name; the name that the procedures may be referenced by is the generic name.

A generic name is defined by an interface block containing a generic-spec and the specifications of the procedures which may be invoked by referencing the generic name. The procedure specifications in the interface block must be distinguishable from each other in one or more of the following ways:

There may be more than one interface block with the same generic name, but the procedure specifications in all such interface blocks must be distinguishable by the above criteria.

When a generic name is referenced it must be possible to determine to which of the specific procedures the generic name refers; the generic reference must resolve to a unique specific procedure name. Selection of the specific procedure is based on the properties of the actual argument list, including:

The specific procedure whose dummy argument list matches the actual argument list is selected and invoked from the list of procedure specifications contained in the interface block that defines the generic name. The dummy argument list of exactly one of the procedure specifications contained in the interface block must match the actual arguments in the reference of the generic name.

The MODULE PROCEDURE statement can be used to extend the list of procedure specifications that comprises the interface block, by naming procedures that are accessible to the program unit containing the interface block. In the MODULE PROCEDURE statement only the specific names of the procedures are given as their procedure interfaces are already explicit. The MODULE PROCEDURE statement may only appear in an interface block that has a generic specification, and the interface block must either be in the module containing the definitions of the named procedures or, in a program unit in which the procedures are accessible through use association.

In the following example, it is assumed that two subroutines have been coded for solving linear equations: rlineq for when the coefficients are real, and zlineq for when the coefficients are complex. A generic name, lineq, is declared as follows and then used for either reference.

INTERFACE lineq

   SUBROUTINE rlineq(ra,rb,rx)

      REAL,DIMENSION(:,:) :: ra

      REAL,DIMENSION(:) :: rb,rx

   END SUBROUTINE rlineq

   SUBROUTINE zlineq(za,zb,zx)

      COMPLEX,DIMENSION(:,:) :: za

      COMPLEX,DIMENSION(:) :: zb,zx

   END SUBROUTINE zlineq

END INTERFACE lineq

The OPERATOR (operator) generic specification can be used to either define a new user-defined operator symbol, or to extend the behavior of an already defined or intrinsic operator.

When the OPERATOR (operator) generic specification is present in the INTERFACE statement, the procedure specifications that immediately follow must only describe function subprograms. The functions described are those that are to be used to implement the operator for various type, kind, and rank combinations of operand. These functions must have only one or two mandatory arguments, which correspond to the operand(s) of a unary or binary operator. The functions return the result of an expression of the form:

operator operand

or

operand1 operator operand2

as appropriate. Each dummy argument of the functions described in the interface block must have the INTENT(IN) attribute. If operator is one of the Fortran 90 intrinsic operators, then each of the specified functions must take the same number of arguments as the intrinsic operator has operands, and the arguments must be distinguishable from those normally associated with the intrinsic operation.

Argument keywords must not be specified in a reference to a user-defined operator function when the operator syntax, rather than the name of the specific function, is used in an expression.

An interface block that defines or extends an operator is analogous to defining a generic procedure name, with the operator being the generic name. Similarly a reference to a user-defined operator must resolve to a unique specific function name. The selection of the function is accomplished by matching the number, type, kind, and rank of the operand(s) with the dummy argument lists of the function specifications contained in the interface block. As with generic names exactly one such specification must match the properties of the operands, and the function whose specification does match is selected and invoked.

See the examples in the next section.

The ASSIGNMENT(=) option allows you to specify one or more subroutines that extend the assignment operation. Each subroutine must have only two mandatory arguments; the first argument can have either the INTENT(OUT) or the INTENT(INOUT) attribute ; the second argument must have the INTENT(IN) attribute. The first argument corresponds to the variable on the left-hand side of the assignment statement, and the second to the expression on the right-hand side.

In a similar manner to generic names and defined operators, defined assignment must resolve to a unique specific subroutine. The subroutine whose dummy arguments match the left and right-hand sides of the assignment statement in all of kind, type, and rank is selected and invoked from the list of subroutine specifications contained in the defined assignment interface block.

The following example illustrates the definition of a user-defined unary operator, .eigenvalues. , that, when applied to an object of type matrix, computes its eigenvalues:

INTERFACE OPERATOR (.eigenvalues.)

   TYPE (vector) FUNCTION &

         find_eigenvalues(matrix_1)

      USE new_types

      TYPE (matrix), INTENT(IN) :: matrix_1

   END FUNCTION find_eigenvalues

END INTERFACE

TYPE (matrix) :: a; TYPE (vector) :: b

! Compute the eigenvalues of a.

b = .eigenvalues. a

The next example extends the * operator and assignment in order to work with entities of derived types.

! Extend the * operator.

INTERFACE OPERATOR (*)

   MODULE PROCEDURE polar_mul, interval_mul

END INTERFACE

! Extend assignment.

INTERFACE ASSIGNMENT (=)

   MODULE PROCEDURE assign_polar_to_complex

END INTERFACE

TYPE (polar) :: p1, p2

TYPE (interval) :: v1, v2, v

COMPLEX :: c

   ...

! A defined operation and an intrinsic

!  assignment.

v = v1*v2

! A defined operation and an defined assignment.

c = p1*p2