[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP Fortran for OpenVMS
Language Reference Manual


Previous Contents Index

8.3.1 Module References

A program unit references a module in a USE statement. This module reference lets the program unit access the public definitions, specifications, and procedures in the module.

Entities in a module are public by default, unless the USE statement specifies otherwise or the PRIVATE attribute is specified for the module entities.

A module reference causes use association between the using program unit and the entities in the module.

For More Information:

8.3.2 USE Statement

The USE statement gives a program unit accessibility to public entities in a module. It takes one of the following forms:


  • USE name [, rename-list]
  • USE name, ONLY : [only-list]

name

Is the name of the module.

rename-list

Is one or more items having the following form:

  • local-name => mod-name

local-name

Is the name of the entity in the program unit using the module.

mod-name

Is the name of a public entity in the module.

only-list

Is the name of a public entity in the module or a generic identifier (a generic name, defined operator, or defined assignment).

An entity in the only-list can also take the form:


  • [local-name =>] mod-name

Rules and Behavior

If the USE statement is specified without the ONLY option, the program unit has access to all public entities in the named module.

If the USE statement is specified with the ONLY option, the program unit has access to only those entities following the option.

If more than one USE statement for a given module appears in a scoping unit, the following rules apply:

  • If one USE statement does not have the ONLY option, all public entities in the module are accessible, and any rename-lists and only-lists are interpreted as a single, concatenated rename-list.
  • If all the USE statements have ONLY options, all the only-lists are interpreted as a single, concatenated only-list. Only those entities named in one or more of the only-lists are accessible.

If two or more generic interfaces that are accessible in a scoping unit have the same name, the same operator, or are both assignments, they are interpreted as a single generic interface. Otherwise, multiple accessible entities can have the same name only if no reference to the name is made in the scoping unit.

The local names of entities made accessible by a USE statement must not be respecified with any attribute other than PUBLIC or PRIVATE. The local names can appear in namelist group lists, but not in a COMMON or EQUIVALENCE statement.

Examples

The following shows examples of the USE statement:



MODULE MOD_A
  INTEGER :: B, C
  REAL E(25,5), D(100)
END MODULE MOD_A
...
SUBROUTINE SUB_Y
  USE MOD_A, DX => D, EX => E   ! Array D has been renamed DX and array E
  ...                           ! has been renamed EX. Scalar variables B
END SUBROUTINE SUB_Y            ! and C are also available to this subrou-
...                             ! tine (using their module names).
SUBROUTINE SUB_Z
  USE MOD_A, ONLY: B, C         ! Only scalar variables B and C are
  ...                           !   available to this subroutine
END SUBROUTINE SUB_Z
...

The following example shows a module containing common blocks:


MODULE COLORS
  COMMON /BLOCKA/ C, D(15)
  COMMON /BLOCKB/ E, F
  ...
END MODULE COLORS
...
FUNCTION HUE(A, B)
  USE COLORS
  ...
END FUNCTION HUE

The USE statement makes all of the variables in the common blocks in module COLORS available to the function HUE.

To provide data abstraction, a user-defined data type and operations to be performed on values of this type can be packaged together in a module. The following example shows such a module:


MODULE CALCULATION
  TYPE ITEM
    REAL :: X, Y
  END TYPE ITEM

  INTERFACE OPERATOR (+)
    MODULE PROCEDURE ITEM_CALC
  END INTERFACE

CONTAINS
  FUNCTION ITEM_CALC (A1, A2)
    TYPE(ITEM) A1, A2, ITEM_CALC
    ...
  END FUNCTION ITEM_CALC
  ...
END MODULE CALCULATION

PROGRAM TOTALS
USE CALCULATION
TYPE(ITEM) X, Y, Z
  ...
  X = Y + Z
  ...
END

The USE statement allows program TOTALS access to both the type ITEM and the extended intrinsic operator + to perform calculations.

8.4 Block Data Program Units

A block data program unit provides initial values for nonpointer variables in named common blocks. It takes the following form:


  • BLOCK DATA [name]
  • [specification-part]
  • END [BLOCK DATA [name]]

name

Is the name of the block data program unit.

specification-part

Is one or more of the following statements:
COMMON INTRINSIC STATIC
DATA PARAMETER TARGET
Derived-type definition POINTER Type declaration 2
DIMENSION RECORD 1 USE 3
EQUIVALENCE Record structure declaration 1  
IMPLICIT SAVE  

1For more information on the RECORD statement and record structure declarations, see Section B.12.
2Can only contain attributes: DIMENSION, INTRINSIC, PARAMETER, POINTER, SAVE, STATIC, or TARGET.
3Allows access to only named constants.

Rules and Behavior

A block data program unit need not be named, but there can only be one unnamed block data program unit in an executable program.

If a name follows the END statement, it must be the same as the name specified in the BLOCK DATA statement.

An interface block must not appear in a block data program unit and a block data program unit must not contain any executable statements.

If a DATA statement initializes any variable in a named common block, the block data program unit must have a complete set of specification statements establishing the common block. However, all of the variables in the block do not have to be initialized.

A block data program unit can establish and define initial values for more than one common block, but a given common block can appear in only one block data program unit in an executable program.

The name of a block data program unit can appear in the EXTERNAL statement of a different program unit to force a search of object libraries for the block data program unit at link time.

Examples

The following is an example of a block data program unit:


BLOCK DATA BLKDAT
  INTEGER S,X
  LOGICAL T,W
  DOUBLE PRECISION U
  DIMENSION R(3)
  COMMON /AREA1/R,S,U,T /AREA2/W,X,Y
  DATA R/1.0,2*2.0/, T/.FALSE./, U/0.214537D-7/, W/.TRUE./, Y/3.5/
END

For More Information:

8.5 Functions, Subroutines, and Statement Functions

Functions, subroutines, and statement functions are user-written subprograms that perform computing procedures. The computing procedure can be either a series of arithmetic operations or a series of Fortran statements. A single subprogram can perform a computing procedure in several places in a program, to avoid duplicating a series of operations or statements in each place.

The following table shows the statements that define these subprograms, and how control is transferred to the subprogram:

Subprogram Defining Statements Control Transfer Method
Function FUNCTION or ENTRY Function reference 1
Subroutine SUBROUTINE or ENTRY CALL statement 2
Statement function Statement function definition Function reference

1A function can also be invoked by a defined operation (see Section 8.9.4).
2A subroutine can also be invoked by a defined assignment (see Section 8.9.5).

A function reference is used in an expression to invoke a function; it consists of the function name and its actual arguments. The function reference returns a value to the calling expression that is used to evaluate the expression.

The following topics are described in this section:

For More Information:

8.5.1 General Rules for Function and Subroutine Subprograms

A subprogram can be an external, module, or internal subprogram. The END statement for an internal or module subprogram must be END SUBROUTINE [name] for a subroutine, or END FUNCTION [name] for a function. In an external subprogram, the SUBROUTINE and FUNCTION keywords are optional.

If a subprogram name appears after the END statement, it must be the same as the name specified in the SUBROUTINE or FUNCTION statement.

Function and subroutine subprograms can change the values of their arguments, and the calling program can use the changed values.

A SUBROUTINE or FUNCTION statement can be optionally preceded by an OPTIONS statement.

Dummy arguments (except for dummy pointers or dummy procedures) can be specified with an intent and can be made optional.

The following sections describe recursion, pure procedures, and user-defined elemental procedures.

For More Information:

8.5.1.1 Recursive Procedures

A recursive procedure can reference itself directly or indirectly. Recursion is permitted if the keyword RECURSIVE is specified in a FUNCTION or SUBROUTINE statement, or if RECURSIVE is specified as a compiler option or in an OPTIONS statement.

If a function is directly recursive and array valued, the keywords RECURSIVE and RESULT must both be specified in the FUNCTION statement.

The procedure interface is explicit within the subprogram in the following cases:

  • When RECURSIVE is specified for a subroutine
  • When RECURSIVE and RESULT are specified for a function

The keyword RECURSIVE must be specified if any of the following applies (directly or indirectly):

  • The subprogram invokes itself.
  • The subprogram invokes a subprogram defined by an ENTRY statement in the same subprogram.
  • An ENTRY procedure in the same subprogram invokes one of the following:
    • Itself
    • Another ENTRY procedure in the same subprogram
    • The subprogram defined by the FUNCTION or SUBROUTINE statement

For More Information:

  • On the FUNCTION statement, see Section 8.5.2.
  • On the SUBROUTINE statement, see Section 8.5.3.
  • On compiler options, see the HP Fortran for OpenVMS User Manual.
  • On the OPTIONS statement, see Section 13.3.

8.5.1.2 Pure Procedures

A pure procedure is a user-defined procedure that is specified by using the prefix PURE (or ELEMENTAL) in a FUNCTION or SUBROUTINE statement. Pure procedures are a feature of Fortran 95.

A pure procedure has no side effects. It has no effect on the state of the program, except for the following:

  • For functions: It returns a value.
  • For subroutines: It modifies INTENT(OUT) and INTENT(INOUT) parameters.

The following intrinsic and library procedures are implicitly pure:

  • All intrinsic functions
  • The elemental intrinsic subroutine MVBITS
  • The library routines in the HPF_LIBRARY

A statement function is pure only if all functions that it references are pure.

Rules and Behavior

Except for procedure arguments and pointer arguments, the following intent must be specified for all dummy arguments in the specification part of the procedure:

  • For functions: INTENT(IN)
  • For subroutines: any INTENT (IN, OUT, or INOUT)

A local variable declared in a pure procedure (including variables declared in any internal procedure) must not:

  • Specify the SAVE attribute
  • Be initialized in a type declaration statement or a DATA statement

The following variables have restricted use in pure procedures (and any internal procedures):

  • Global variables
  • Dummy arguments with INTENT(IN) (or no declared intent)
  • Objects that are storage associated with any part of a global variable

They must not be used in any context that does either of the following:

  • Causes their value to change. For example, they must not be used as:
    • The left side of an assignment statement or pointer assignment statement
    • An actual argument associated with a dummy argument with INTENT(OUT), INTENT(INOUT), or the POINTER attribute
    • An index variable in a DO or FORALL statement, or an implied-do clause
    • The variable in an ASSIGN statement
    • An input item in a READ statement
    • An internal file unit in a WRITE statement
    • An object in an ALLOCATE, DEALLOCATE, or NULLIFY statement
    • An IOSTAT or SIZE specifier in an I/O statement, or the STAT specifier in a ALLOCATE or DEALLOCATE statement
  • Creates a pointer to that variable. For example, they must not be used as:
    • The target in a pointer assignment statement
    • The right side of an assignment to a derived-type variable (including a pointer to a derived type) if the derived type has a pointer component at any level

A pure procedure must not contain the following:

  • Any external I/O statement (including a READ or WRITE statement whose I/O unit is an external file unit number or *)
  • A PAUSE statement
  • A STOP statement

A pure procedure can be used in contexts where other procedures are restricted; for example:

  • It can be called directly in a FORALL statement or be used in the mask expression of a FORALL statement.
  • It can be called from a pure procedure. Pure procedures can only call other pure procedures.
  • It can be passed as an actual argument to a pure procedure.

If a procedure is used in any of these contexts, its interface must be explicit and it must be declared pure in that interface.

Examples

The following shows a pure function:



PURE INTEGER FUNCTION MANDELBROT(X)
  COMPLEX, INTENT(IN) :: X
  COMPLEX  :: XTMP
  INTEGER  :: K
  ! Assume SHARED_DEFS includes the declaration
  ! INTEGER ITOL
  USE SHARED_DEFS

  K = 0
  XTMP = -X
  DO WHILE (ABS(XTMP)<2.0 .AND. K<ITOL)
    XTMP = XTMP**2 - X
    K = K + 1
  END DO
  ITER = K
END FUNCTION

The following shows the preceding function used in an interface block:


INTERFACE
  PURE INTEGER FUNCTION MANDELBROT(X)
    COMPLEX, INTENT(IN) :: X
  END FUNCTION MANDELBROT
END INTERFACE

The following shows a FORALL construct calling the MANDELBROT function to update all the elements of an array:


FORALL (I = 1:N, J = 1:M)
  A(I,J) = MANDELBROT(COMPLX((I-1)*1.0/(N-1), (J-1)*1.0/(M-1)))
END FORALL

For More Information:

  • On the FUNCTION statement, see Section 8.5.2.
  • On the SUBROUTINE statement, see Section 8.5.3.
  • On pure procedures in FORALLs, see Section 4.2.5.
  • On pure procedures in interface blocks, see Section 8.9.2.
  • On how to use pure procedures, see the HP Fortran for OpenVMS User Manual.

8.5.1.3 Elemental Procedures

An elemental procedure is a user-defined procedure that is a restricted form of pure procedure. An elemental procedure can be passed an array, which is acted upon one element at a time. Elemental procedures are a feature of Fortran 95.

To specify an elemental procedure, use the prefix ELEMENTAL in a FUNCTION or SUBROUTINE statement.

An explicit interface must be visible to the caller of an ELEMENTAL procedure.

For functions, the result must be scalar; it cannot have the POINTER attribute.

Dummy arguments have the following restrictions:

  • They must be scalar.
  • They cannot have the POINTER attribute.
  • They (or their subobjects) cannot appear in a specification expression, except as an argument to one of the intrinsic functions BIT_SIZE, LEN, KIND, or the numeric inquiry functions.
  • They cannot be *.
  • They cannot be dummy procedures.

If the actual arguments are all scalar, the result is scalar. If the actual arguments are array-valued, the values of the elements (if any) of the result are the same as if the function or subroutine had been applied separately, in any order, to corresponding elements of each array actual argument.

Elemental procedures are pure procedures and all rules that apply to pure procedures also apply to elemental procedures.

Examples

Consider the following:


MIN (A, 0, B)             ! A and B are arrays of shape (S, T)

In this case, the elemental reference to the MIN intrinsic function is an array expression whose elements have the following values:


MIN (A(I,J), 0, B(I,J)), I = 1, 2, ..., S, J = 1, 2, ..., T

For More Information:

8.5.2 Functions

A function subprogram is invoked in an expression and returns a single value (a function result) that is used to evaluate the expression.

The FUNCTION statement is the initial statement of a function subprogram. It takes the following form:


  • [prefix] FUNCTION name ([d-arg-list]) [RESULT (r-name)]

prefix

Is one of the following:

  • type [keyword]
  • keyword [type]

type

Is a data type specifier.

keyword

Is one of the following:
Keyword Meaning
RECURSIVE Permits direct recursion to occur. If a function is directly recursive and array valued, RESULT must also be specified (see Section 8.5.1.1).
PURE Asserts that the procedure has no side effects (see Section 8.5.1.2).
ELEMENTAL Restricted form of pure procedure that acts on one array element at a time (see Section 8.5.1.3).

name

Is the name of the function. If RESULT is specified, the function name must not appear in any specification statement in the scoping unit of the function subprogram.

The function name can be followed by the length of the data type. The length is specified by an asterisk (*) followed by any unsigned, nonzero integer that is a valid length for the function's type. For example, REAL FUNCTION LGFUNC*8 (Y, Z) specifies the function result as REAL(8) (or REAL*8).

This optional length specification is not permitted if the length has already been specified following the keyword CHARACTER.

d-arg-list

Is a list of one or more dummy arguments.

r-name

Is the name of the function result. This name must not be the same as the function name.

Rules and Behavior

The type and kind parameters (if any) of the function's result can be defined in the FUNCTION statement or in a type declaration statement within the function subprogram, but not both. If no type is specified, the type is determined by implicit typing rules in effect for the function subprogram.

Execution begins with the first executable construct or statement following the FUNCTION statement. Control returns to the calling program unit once the END statement (or a RETURN statement) is executed.

If you specify CHARACTER*(*), the function assumes the length declared for it in the program unit that invokes it. This type of character function can have different lengths when it is invoked by different program units; it is an obsolescent feature in Fortran 95.

If the length is specified as an integer constant, the value must agree with the length of the function specified in the program unit that invokes the function. If no length is specified, a length of 1 is assumed.

If the function is array-valued or a pointer, the declarations within the function must state these attributes for the function result name. The specification of the function result attributes, dummy argument attributes, and the information in the procedure heading collectively define the interface of the function.

The value of the result variable is returned by the function when it completes execution. Certain rules apply depending on whether the result is a pointer, as follows:

  • If the result is a pointer, its allocation status must be determined before the function completes execution. (The function must associate a target with the pointer, or cause the pointer to be explicitly disassociated from a target.)
    The shape of the value returned by the function is determined by the shape of the result variable when the function completes execution.
  • If the result is not a pointer, its value must be defined before the function completes execution. If the result is an array, all the elements must be defined; if the result is a derived-type structure, all the components must be defined.

A function subprogram cannot contain a SUBROUTINE statement, a BLOCK DATA statement, a PROGRAM statement, or another FUNCTION statement. ENTRY statements can be included to provide multiple entry points to the subprogram.

You can use a CALL statement to invoke a function as long as write the function is not one of the following types:

  • REAL(8)
  • REAL(16)
  • COMPLEX(8)
  • COMPLEX(16)
  • CHARACTER

Section 8.5.2.1 describes the RESULT keyword and Section 8.5.2.2 describes function references.

Examples

The following example uses the Newton-Raphson iteration method
( F(X) = cosh(X) + cos(X) - A = 0 ) to get the root of the function:


FUNCTION ROOT(A)
  X  = 1.0
  DO
    EX = EXP(X)
    EMINX = 1./EX
    ROOT  = X - ((EX+EMINX)*.5+COS(X)-A)/((EX-EMINX)*.5-SIN(X))
    IF (ABS((X-ROOT)/ROOT) .LT. 1E-6) RETURN
    X  = ROOT
  END DO
END

In the preceding example, the following formula is calculated repeatedly until the difference between Xi and Xi+1 is less than 1.0E--6:
X_i+1 = X_i - cosh(X_i)+cos(X_i)-A sinh(X_i)-sin(X_i)


Previous Next Contents Index