FUNCTION

Purpose

The FUNCTION statement is the first statement of a function subprogram.

Syntax


   .------------.                                   
   V            |                                   
>>---+--------+-+--FUNCTION--name--+------------+--------------->
     '-prefix-'                    |   (1)      |   
                                   '-*------len-'   

                                  .--------------------------------------------------------.   
                                  V                                                        |   
>--(--+---------------------+--)----+----------------------------------------------------+-+-><
      '-dummy_argument_list-'       +-RESULT--(--result_name--)--------------------------+     
                                    |      (2)                                           |     
                                    '-BIND------(--C--+-----------------------------+--)-'     
                                                      '-, -NAME-- = --binding_label-'

Notes:

IBM extension.
Fortran 2003

prefix

is one of the following:

declaration_type_spec
ELEMENTAL
IMPURE
MODULE
PURE
RECURSIVE

declaration_type_spec

specifies the type and type parameters of the function result. See Type Declaration for details about declaration_type_spec.

name

The name of the function subprogram.

len

An unsigned integer literal or a parenthesized scalar integer constant expression. The value of len specifies the length of the function's result variable. It can be included only when you specify the type in the FUNCTION statement. The type cannot be DOUBLE PRECISION, DOUBLE COMPLEX, BYTE, or a derived type.

binding_label

a scalar character constant expression.

Rules

At most one of each kind of prefix can be specified. You cannot specify both the RECURSIVE and ELEMENTAL prefix specifiers. You cannot specify both the PURE and IMPURE prefix specifiers.

At most one RESULT clause and at most one BIND clause may appear. They can appear in any order.

The type and type parameters of the function result can be specified by either declaration_type_spec or by declaring the result variable in the declaration part of the function subprogram, but not by both. If they are not specified at all, the implicit typing rules are in effect. A length specifier cannot be specified by both declaration_type_spec and len.

If RESULT is specified, result_name becomes the function result variable. name must not be declared in any specification statement in the subprogram, although it can be referenced. result_name must not be the same as name. If RESULT is not specified, name becomes the function result variable.

Fortran 2003 begins The BIND keyword implicitly or explicitly defines a binding label by which a procedure is accessed from the C programming language. The result variable must be a scalar that is interoperable. A dummy argument cannot be zero-sized. A dummy argument for a procedure with the BIND attribute must have interoperable types and type parameters, and cannot have the ALLOCATABLE or POINTER attribute.

If the FUNCTION statement appears as part of an interface body that describes a dummy procedure, the NAME= specifier must not appear. An elemental procedure cannot have the BIND attribute. Fortran 2003 ends

If the result variable is an array or pointer, the DIMENSION or POINTER attributes, respectively, must be specified within the function body.

If the function result is a pointer, the shape of the result variable determines the shape of the value returned by the function. If the result variable is a pointer, the function must either associate a target with the pointer or define the association status of the pointer as disassociated.

If the result variable is not a pointer, the function must define its value.

If the name of an external function is of derived type, the derived type must be a sequence derived type if the type is not use-associated or host-associated.

The function result variable must not appear within a variable format expression, nor can it be specified in a COMMON, DATA, integer POINTER, or EQUIVALENCE statement, nor can it have the PARAMETER, INTENT, OPTIONAL, or SAVE attributes. The STATIC and AUTOMATIC attributes can be specified only when the result variable is not an allocatable object, an array or a pointer, and is not of character or derived type.

The function result variable is associated with any entry procedure result variables. This is called entry association. The definition of any of these result variables becomes the definition of all the associated variables having that same type and type parameters, and is the value of the function regardless of the entry point.

If the function subprogram contains entry procedures, the result variables are not required to be of the same type unless the type is of character or derived type, or if the variables have the ALLOCATABLE or POINTER attribute, or if they are not scalars. The variable whose name is used to reference the function must be in a defined state when a RETURN or END statement is executed in the subprogram. An associated variable of a different type must not become defined during the execution of the function reference, unless an associated variable of the same type and type parameters redefines it later during execution of the subprogram.

You can specify the MODULE prefix specifier for the FUNCTION statement of a module subprogram or of a nonabstract interface body that is declared in the scoping unit of a module or submodule. See Example 2.

When you specify the MODULE prefix specifier for the FUNCTION statement of a module subprogram, the module subprogram is a separate module procedure.
When you specify the MODULE prefix specifier for the FUNCTION statement of a nonabstract interface body, the interface body is a module procedure interface body.

The BIND attribute with the NAME= specifier is not allowed on an internal procedure.

Example 1

RECURSIVE FUNCTION FACTORIAL (N) RESULT (RES)
  INTEGER RES
  IF (N.EQ.0) THEN
    RES=1
  ELSE
    RES=N*FACTORIAL(N-1)
  END IF
END FUNCTION FACTORIAL

PROGRAM P
  INTERFACE OPERATOR (.PERMUTATION.)
    ELEMENTAL FUNCTION MYPERMUTATION(ARR1,ARR2)
      INTEGER :: MYPERMUTATION
      INTEGER, INTENT(IN) :: ARR1,ARR2
    END FUNCTION MYPERMUTATION
  END INTERFACE

  INTEGER PERMVEC(100,150),N(100,150),K(100,150)
  ...
  PERMVEC = N .PERMUTATION. K
  ...
END

Example 2 (Fortran 2008)

MODULE m
  ! The MODULE prefix specifier is specified for the FUNCTION
  ! statement of a module procedure interface body.
  INTERFACE
    INTEGER MODULE FUNCTION func(a, b)
      INTEGER :: a, b
    END FUNCTION
  END INTERFACE
END MODULE

SUBMODULE (m) n
  
  CONTAINS
    ! The MODULE prefix specifier is specified for the FUNCTION
    ! statement of a separate module procedure.
    INTEGER MODULE FUNCTION func(a, b) RESULT (res)
      INTEGER :: a, b
      res = a + b
    END FUNCTION
END SUBMODULE

Related information

Function and subroutine subprograms
ENTRY
BIND (Fortran 2003)
Function reference
Dummy arguments
Statement Function
Recursion
-qrecur option in the XL Fortran Compiler Reference
Pure procedures
Elemental procedures
Interoperability of procedures
Modules
Submodules (Fortran 2008)
Separate module procedures (Fortran 2008)

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum