Argument association

Actual arguments are associated with dummy arguments when a function or subroutine is referenced. In a procedure reference, the actual argument list identifies the correspondence between the actual arguments provided in the list and the dummy arguments of the subprogram.

When there is no argument keyword, an actual argument is associated with the dummy argument that occupies the corresponding position in the dummy argument list. The first actual argument becomes associated with the first dummy argument , the second actual argument with the second dummy argument, and so forth. Each actual argument must be associated with a dummy argument.

When a keyword is present, the actual argument is associated with the dummy argument whose name is the same as the argument keyword. In the scoping unit that contains the procedure reference, the names of the dummy arguments must exist in an accessible explicit interface.

Argument association within a subprogram terminates upon execution of a RETURN or END statement in the subprogram. There is no retention of argument association between one reference of a subprogram and the next reference of the subprogram, unless the persistent suboption of the -qxlf77 compiler option is specified and the subprogram contains at least one entry procedure.

If associated with a null argument in a procedure reference, the corresponding dummy argument is undefined.

IBM Extension

Except when %VAL is used, the subprogram reserves no storage for the dummy argument. It uses the corresponding actual argument for calculations. Therefore, the value of the actual argument changes when the dummy argument changes. If the corresponding actual argument is an expression or an array section with vector subscripts, the calling procedure reserves storage for the actual argument, and the subprogram must not define, redefine, or undefine the dummy argument.

If the actual argument is specified with %VAL, or the corresponding dummy argument has the VALUE attribute, the subprogram does not have access to the storage area of the actual argument.

End of IBM Extension

Actual arguments must agree in type and type parameters with their corresponding dummy arguments (and in shape if the dummy arguments are pointers or assumed-shape), except for two cases: a subroutine name has no type and must be associated with a dummy procedure name that is a subroutine, and an alternate return specifier has no type and must be associated with an asterisk.

Argument association can be carried through more than one level of procedure reference.

If a subprogram reference causes a dummy argument in the referenced subprogram to become associated with another dummy argument in the referenced subprogram, neither dummy argument can become defined, redefined, or undefined during that subprogram. For example, if a subroutine definition is:

   SUBROUTINE XYZ (A,B)

and it is referenced by:

   CALL XYZ (C,C)

the dummy arguments A and B each become associated with the same actual argument C and, therefore, with each other. Neither A nor B can be defined, redefined, or undefined during the execution of subroutine XYZ or by any procedures referenced by XYZ.

If a dummy argument becomes associated with an entity in a common block or an entity accessible through use or host association, the value of the entity must only be altered through the use of the dummy argument name, while the entity is associated with the dummy argument. If any part of a data object is defined through a dummy argument, the data object can be referenced only through that dummy argument, either before or after the definition occurs. These restrictions also apply to pointer targets.

IBM Extension

If you have programs that do not conform to these restrictions, using the compiler option -qalias=nostd may be appropriate. See the -qalias Option in the XL Fortran Compiler Reference for details.

End of IBM Extension
IBM Extension

%VAL and %REF

To call subprograms written in languages other than Fortran (for example, user-written C programs, or Linux operating system routines), the actual arguments may need to be passed by a method different from the default method used by XL Fortran. The default method passes the address of the actual argument and, if it is of type character, the length. (Use the -qnullterm compiler option to ensure that scalar character initialization expressions are passed with terminating null strings. See -qnullterm in the XL Fortran Compiler Reference for details.)

The default passing method can be changed by using the %VAL and %REF built-in functions in the argument list of a CALL statement or function reference, or with the dummy arguments in interface bodies. These built-in functions specify the way an actual argument is passed to the external subprogram.

%VAL and %REF built-in functions cannot be used in the argument lists of Fortran procedure references, nor can they be used with alternate return specifiers.

The argument list built-in functions are:

%VAL
This built-in function can be used with actual arguments that are CHARACTER(1), logical, integer, real, complex expressions, or sequence derived type. Objects of derived type cannot contain character structure components whose lengths are greater than 1 byte, or arrays.

%VAL cannot be used with actual arguments that are arrays, procedure names, or character expressions of length greater than 1 byte.

%VAL causes the actual argument to be passed as 32-bit or 64-bit intermediate values. If the actual argument is of type real or complex, it is passed as one or more 64-bit intermediate values. If the actual argument is of integer, logical, or sequence derived type, it is passed as one or more 32-bit intermediate values. An integer actual argument shorter than 32 bits is sign-extended to a 32-bit value, while a logical actual argument shorter than 32 bits is padded with zeros to a 32-bit value.

Byte named constants and variables are passed as if they were INTEGER(1). If the actual argument is a CHARACTER(1), it is padded on the left with zeros to a 32-bit value, regardless of whether the -qctyplss compiler option is specified.

%REF
This built-in function causes the actual argument to be passed by reference; that is, only the address of the actual argument is passed. Unlike the default passing method, %REF does not pass the length of a character argument. If such a character argument is being passed to a C routine, the string must be terminated with a null character (for example, using the -qnullterm option) so that the C routine can determine the length of the string.

Examples of %VAL and %REF

  EXTERNAL FUNC
  CALL RIGHT2(%REF(FUNC))       ! procedure name passed by reference
  REAL XVAR
  CALL RIGHT3(%VAL(XVAR))       ! real argument passed by value

  IVARB=6
  CALL TPROG(%VAL(IVARB))       ! integer argument passed by value

See VALUE for a standard-conforming alternative to %VAL.

See Interlanguage calls for more information.

End of IBM Extension

Intent of dummy arguments

With the INTENT attribute, you can explicitly specify the intended use of a dummy argument. Use of this attribute may improve optimization of the program's calling procedure when an explicit interface exists. Also, the explicitness of argument intent may provide more opportunities for error checking. See INTENT for syntax details.

IBM Extension

The following table outlines XL Fortran's passing method for internal procedures (not including assumed-shape dummy arguments and pointer dummy arguments):

Table 13. Passing method and intent
Argument Type Intent(IN) Intent(OUT) Intent(INOUT) No Intent
Non-CHARACTER Scalar VALUE default default default
CHARACTER*1 Scalar VALUE REFERENCE REFERENCE REFERENCE
CHARACTER*n Scalar REFERENCE REFERENCE REFERENCE REFERENCE
CHARACTER*(*) Scalar default default default default
Derived Type 1 Scalar VALUE default default default
Derived Type 2 Scalar default default default default
Non-CHARACTER Array default default default default
CHARACTER*1 Array REFERENCE REFERENCE REFERENCE REFERENCE
CHARACTER*n Array REFERENCE REFERENCE REFERENCE REFERENCE
CHARACTER*(*) Array default default default default
Derived Type 3 Array default default default default
End of IBM Extension

Optional dummy arguments

The OPTIONAL attribute specifies that a dummy argument need not be associated with an actual argument in a reference to a procedure. Some advantages of the OPTIONAL attribute include:

See OPTIONAL for details about syntax and rules.

Restrictions on optional dummy arguments not present

A dummy argument is present in an instance of a subprogram if it is associated with an actual argument, and the actual argument is either a dummy argument that is not optional in the invoking subprogram or a dummy argument that is not present in the invoking subprogram. A dummy argument that is not optional must be present.

An optional dummy argument that is not present must conform to the following rules:

Length of character arguments

If the length of a character dummy argument is a nonconstant specification expression, the object is a dummy argument with a run-time length. If an object that is not a dummy argument has a run-time length, it is an automatic object. See Automatic objects for details.

If a dummy argument has a length specifier of an asterisk in parentheses, the length of the dummy argument is "inherited" from the actual argument. The length is inherited because it is specified outside the program unit containing the dummy argument. If the associated actual argument is an array name, the length inherited by the dummy argument is the length of an array element in the associated actual argument array. %REF cannot be specified for a character dummy argument with inherited length.

Variables as dummy arguments

If the actual argument is scalar, the corresponding dummy argument must be scalar, unless the actual argument is an element or substring of an element of an array that is not an assumed-shape or pointer array. If the actual argument is allocatable, the corresponding dummy argument must also be allocatable. If the procedure is referenced by a generic name or as a defined operator or defined assignment, the ranks of the actual arguments and corresponding dummy arguments must agree. A scalar dummy argument can be associated only with a scalar actual argument.

Fortran 95

The following apply to dummy arguments used in elemental subprograms:

End of Fortran 95

If a scalar dummy argument is of type character, its length must be less than or equal to the length of the actual argument. The dummy argument is associated with the leftmost characters of the actual argument. If the character dummy argument is an array, the length restriction applies to the entire array rather than each array element. That is, the lengths of associated array elements can vary, although the whole dummy argument array cannot be longer than the whole actual argument array.

If the dummy argument is an assumed-shape array, the actual argument must not be an assumed-size array or a scalar (including a designator for an array element or an array element substring).

If the dummy argument is an explicit-shape or assumed-size array, and if the actual argument is a noncharacter array, the size of the dummy argument must not exceed the size of the actual argument array. Each actual array element is associated with the corresponding dummy array element. If the actual argument is a noncharacter array element with a subscript value of as, the size of the dummy argument array must not exceed the size of the actual argument array + 1 - as. The dummy argument array element with a subscript value of ds becomes associated with the actual argument array element that has a subscript value of as + ds - 1.

If an actual argument is a character array, character array element, or character substring, and begins at a character storage unit acu of an array, character storage unit dcu of an associated dummy argument array becomes associated with character storage unit acu+dcu-1 of the actual array argument.

You can define a dummy argument that is a variable name within a subprogram if the associated actual argument is a variable. You must not redefine a dummy argument that is a variable name within a subprogram if the associated actual argument is not definable.

If the actual argument is an array section with a vector subscript, the associated dummy argument cannot be defined

If a nonpointer dummy argument is associated with a pointer actual argument, the actual argument must be currently associated with a target, to which the dummy argument becomes argument associated. Any restrictions on the passing method apply to the target of the actual argument.

If the dummy argument is neither a target nor a pointer, any pointers associated with the actual argument do not become associated with the corresponding dummy argument on invocation of the procedure.

If both the dummy and actual arguments are targets, with the dummy argument being a scalar or an assumed-shape array (and the actual argument is not an array section with a vector subscript):

  1. Any pointers associated with the actual argument become associated with the corresponding dummy argument on invocation of the procedure.
  2. When execution of the procedure completes, any pointers associated with the dummy argument remain associated with the actual argument.

If both the dummy and actual arguments are targets, with the dummy argument being either an explicit-shape array or an assumed-size array, while the actual argument is not an array section with a vector subscript:

  1. Whether any pointers associated with the actual argument become associated with the corresponding dummy argument on invocation of the procedure is processor dependent.
  2. When execution of the procedure completes, whether any pointers associated with the dummy argument remain associated with the actual argument is processor dependent.

If the dummy argument is a target and the corresponding actual argument is not a target or is an array section with a vector subscript, any pointers associated with the dummy argument become undefined when execution of the procedure completes.

Fortran 2003 Standard

Allocatable objects as dummy arguments

An allocatable dummy argument has an actual argument which is also allocatable associated with it. If the allocatable dummy argument is an array, the associated actual argument must also be an array.

On procedure entry, the allocation status of an allocatable dummy argument becomes that of the associated actual argument. If the dummy argument is INTENT(OUT) and the associated actual argument is currently allocated, the actual argument is deallocated on procedure invocation so that the dummy argument has an allocation status of not currently allocated. If the dummy argument is not INTENT(OUT) and the actual argument is currently allocated, the value of the dummy argument is that of the associated actual argument.

While the procedure is active, an allocatable dummy argument that does not have INTENT(IN) may be allocated, deallocated, defined, or become undefined. No reference to the associated actual argument is permitted via another alias if any of these events occur.

On exit from the routine, the actual argument has the allocation status of the allocatable dummy argument (there is no change, of course, if the allocatable dummy argument has INTENT(IN)). The usual rules apply for propagation of the value from the dummy argument to the actual argument.

Automatic deallocation of the allocatable dummy argument does not occur as a result of execution of a RETURN or END statement in the procedure of which it is a dummy argument.

Note:
An allocatable dummy argument that has the INTENT(IN) attribute must not have its allocation status altered within the called procedure. The main difference between such a dummy argument and a normal dummy argument is that it might be unallocated on entry (and throughout execution of the procedure).

Example

SUBROUTINE LOAD(ARRAY, FILE)
   REAL, ALLOCATABLE, INTENT(OUT) :: ARRAY(:, :, :)
   CHARACTER(LEN=*), INTENT(IN) :: FILE
   INTEGER UNIT, N1, N2, N3
   INTEGER, EXTERNAL :: GET_LUN
   UNIT = GET_LUN() ! Returns an unused unit number
   OPEN(UNIT, FILE=FILE, FORM='UNFORMATTED')
   READ(UNIT) N1, N2, N3
   ALLOCATE(ARRAY(N1, N2, N3))
   READ(UNIT) ARRAY
   CLOSE(UNIT)
END SUBROUTINE LOAD

End of Fortran 2003 Standard

Pointers as dummy arguments

If a dummy argument is a pointer, the actual argument must be a pointer and their types, type parameters, and ranks must match. The actual argument reference is to the pointer itself, not to its target. When the procedure is invoked:

The association status can change during execution of the procedure. When the procedure finishes executing, the dummy argument's association status becomes undefined, if it is associated.

IBM Extension

The passing method must be by reference; that is, %VAL must not be specified for the pointer actual argument.

End of IBM Extension

Procedures as dummy arguments

A dummy argument that is identified as a procedure Fortran 2003 Begins or a procedure pointer Fortran 2003 Ends is called a dummy procedure or Fortran 2003 Begins dummy procedure pointer, Fortran 2003 Ends respectively.

Fortran 2003 Standard

If a dummy argument is a dummy procedure without the POINTER attribute, the associated actual argument must be the specific name of an external procedure, module procedure, dummy procedure, or intrinsic procedure whose name can be passed as an argument, an associated procedure pointer, or a reference to a function that returns an associated procedure pointer. If the specific name is also a generic name, only the specific procedure is associated with the dummy argument.

If a dummy argument is a procedure pointer, the associated actual argument must be a procedure pointer, a reference to a function that returns a procedure pointer, or a reference to the NULL intrinsic function.

If an external procedure name or a dummy procedure name is used as an actual argument, its interface must be explicit or it must be explicitly declared with the EXTERNAL attribute.

If the interface of the dummy argument is explicit, the characteristics must be the same for the associated actual argument and the corresponding dummy argument, except that a pure actual argument may be associated with a dummy argument that is not pure.

If the interface of the dummy argument is implicit and either the name of the dummy argument is explicitly typed or it is referenced as a function, the dummy argument must not be referenced as a subroutine and the actual argument must be a function, function procedure pointer, or dummy procedure.

If the interface of the dummy argument is implicit and a reference to it appears as a subroutine reference, the actual argument must be a subroutine, subroutine procedure pointer, or dummy procedure.

End of Fortran 2003 Standard

Internal subprograms cannot be associated with a dummy procedure argument. FORTRAN 95 BeginsYou cannot use a non-intrinsic elemental procedure as an actual argument in Fortran 95. FORTRAN 95 Ends

Examples of procedures as dummy arguments

PROGRAM MYPROG
INTERFACE
  SUBROUTINE SUB (ARG1)
    EXTERNAL ARG1
    INTEGER ARG1
  END SUBROUTINE SUB
END INTERFACE
EXTERNAL IFUNC, RFUNC
REAL RFUNC

CALL SUB (IFUNC)    ! Valid reference
CALL SUB (RFUNC)    ! Invalid reference
!
! The first reference to SUB is valid because IFUNC becomes an
! implicitly declared integer, which then matches the explicit
! interface. The second reference is invalid because RFUNC is
! explicitly declared real, which does not match the explicit
! interface.
END PROGRAM
SUBROUTINE ROOTS
  EXTERNAL NEG
  X = QUAD(A,B,C,NEG)
  RETURN
END
FUNCTION QUAD(A,B,C,FUNCT)
  INTEGER FUNCT
  VAL = FUNCT(A,B,C)
  RETURN
END

FUNCTION NEG(A,B,C)
  RETURN
END

Related information

Asterisks as dummy arguments

A dummy argument that is an asterisk can only appear in the dummy argument list of a SUBROUTINE statement or an ENTRY statement in a subroutine subprogram. The corresponding actual argument must be an alternate return specifier, which indicates the statement label of a branch target statement in the same scope as the CALL statement, to which control is returned.

Example of an alternate return specifier

   CALL SUB(*10)
   STOP                  ! STOP is never executed
10 PRINT *, 'RETURN 1'
   CONTAINS
     SUBROUTINE SUB(*)
          ...
       RETURN 1          ! Control returns to statement with label 10
     END SUBROUTINE
   END

Resolution of procedure references

The subprogram name in a procedure reference is either established to be generic, established to be only specific, or not established.

A subprogram name is established to be generic in a scoping unit if one or more of the following is true:

A subprogram name is established to be only specific in a scoping unit when it has not been established to be generic and one of the following is true:

If a subprogram name is not established to be either generic nor specific, it is not established.

Rules for resolving procedure references to names

The following rules are used to resolve a procedure reference to a name established to be generic:

  1. If there is an interface block with that name in the scoping unit or accessible through use association, and the reference is consistent with a non-elemental reference to one of the specific interfaces of that interface block, the reference is to the specific procedure associated with the specific interface.
  2. If Rule 1 does not apply, the reference is to an intrinsic procedure if the procedure name in the scoping unit is specified with the INTRINSIC attribute or accesses a module entity whose name is specified with the INTRINSIC attribute, and the reference is consistent with the interface of that intrinsic procedure.
  3. If neither Rule 1 nor Rule 2 applies, but the name is established to be generic in the host scoping unit, the name is resolved by applying Rule 1 and Rule 2 to the host scoping unit. For this rule to apply, there must be agreement between the host scoping unit and the scoping unit of which the name is either a function or a subroutine.
  4. If Rule 1, Rule 2 and Rule 3 do not apply, the reference must be to the generic intrinsic procedure with that name.

The following rules are used to resolve a procedure reference to a name established to be only specific:

  1. If the scoping unit is a subprogram, and it contains either an interface body with that name or the name has the EXTERNAL attribute, and if the name is a dummy argument of that subprogram, the dummy argument is a dummy procedure. The reference is to that dummy procedure.
  2. If Rule 1 does not apply, and the scoping unit contains either an interface body with that name or the name has the EXTERNAL attribute, the reference is to an external subprogram.
  3. In the scoping unit, if a statement function or internal subprogram has that name, the reference is to that procedure.
  4. In the scoping unit, if the name has the INTRINSIC attribute, the reference is to the intrinsic procedure with that name.
  5. The scoping unit contains a reference to a name that is the name of a module procedure that is accessed through use association. Because of possible renaming in the USE statement, the name of the reference may differ from the original procedure name.
  6. If none of these rules apply, the reference is resolved by applying these rules to the host scoping unit.

The following rules are used to resolve a procedure reference to a name that is not established:

  1. If the scoping unit is a subprogram and if the name is the name of a dummy argument of that subprogram, the dummy argument is a dummy procedure. The reference is to that dummy procedure.
  2. If Rule 1 does not apply, and the name is the name of an intrinsic procedure, the reference is to that intrinsic procedure. For this rule to apply, there must be agreement between the intrinsic procedure definition and the reference that the name is either a function or subroutine.
  3. If neither Rule 1 nor 2 applies, the reference is to the external procedure with that name.

Resolving procedure references to generic names

When resolving a procedure reference to a generic name, the following rules apply:


1.
A data object of derived type with no array components or CHARACTER*n components, (where n > 1).
2.
A data object of derived type with array components or CHARACTER*n components, (where n > 1).
3.
A data object of derived type with components of any type, size and rank.