Arguments

Argument association

Argument association is the linkage of actual argument to dummy argument that initially occurs when a procedure having arguments is invoked. During the execution of the referenced procedure, the dummy arguments are effectively aliases for the actual arguments. After control returns to the program unit making the reference, the dummy arguments and actual arguments are no longer associated, and the actual arguments may no longer be referenced by the dummy argument names.

The principle of argument association is positional: the first item in the list of actual arguments is associated with the first item in the list of dummy arguments, and so on with the remaining arguments in each list. However, the programmer can use the keyword option to override this positional correspondence; see “Keyword option”.

Dummy and actual arguments must agree in kind, type, and rank. The corresponding dummy and actual arguments must both be scalars or both arrays; if they are both arrays, they must have the same dimensionality. Likewise, if an actual argument is an expression or a reference to a function, it must match the type and kind of the dummy argument.

The following sections provide more detailed information about these types of dummy arguments:

Array dummy argument

If the dummy argument is an assumed-shape array, the corresponding actual argument must match in kind, type, and rank; the dummy argument takes its shape from the actual argument, resulting in an element-by-element association between the actual and dummy arguments.

If the dummy argument is an explicit-shape or assumed-size array, the kind and type of the actual argument must match but the rank need not. The elements are sequence associated—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 in array element order.

A consequence of 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 referenced procedure.

For example, if an actual argument has this declaration:

REAL a(0:3,0:2)

and the corresponding dummy argument has this declaration:

REAL d(2,3,2)

then the correspondence between elements of the actual and dummy arguments is as follows:

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 the 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 are matched, and the successive characters—rather than array elements—are matched.

The next example illustrates character sequence association. Assuming this declaration of the actual argument:

CHARACTER*2 a(3,4)

and this declaration of the corresponding dummy argument:

CHARACTER*4 d(2,3)

then the correspondence between elements of the actual and dummy arguments is as follows:

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 associating an array section with any other but an assumed-shape dummy argument may cause a copy of the array section to be generated and is likely to result in a degradation in performance.

For information about the different types of arrays, see “Array declarations”.

Procedure dummy argument

If a dummy argument is a procedure, 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 (see “Procedure interface”). Internal procedures, statement functions, and generic names may not be passed as actual arguments.

If the actual argument is an intrinsic procedure, the appropriate specific name must be used in the reference. It must have the INTRINSIC attribute.

The following example, intrinsic_arg.f90, declares the intrinsics QSIN and QCOS with the INTRINSIC attribute so that they can be passed as arguments to the user-defined subroutine call_int_arg. Note that the dummy argument, trig_func, is declared in the subroutine with the EXTERNAL attribute to indicate that it is a dummy procedure. This declaration does not conflict with the declaration of the actual arguments in the main program unit because each occurs in different scoping units.

Example 7-4 intrinsic_arg.f90

PROGRAM main ! declare the intrinsics QSIN and QCOS with the INTRINSIC ! attribute to allow them to be passed as arguments REAL(16), INTRINSIC :: QSIN, QCOS CALL call_int_arg(QSIN) CALL call_int_arg(QCOS) END PROGRAM main SUBROUTINE call_int_arg(trig_func) ! trig_func is an intrinsic function--see the declarations ! of the actual arguments in the main program. trig_func ! is declared here as EXTERNAL to indicate that it is a ! dummy procedure. REAL(16), EXTERNAL :: trig_func REAL(16), PARAMETER :: pi=3.1415926 INTEGER :: i DO i = 0, 360, 45 ! Convert degrees to radians (i*pi/180) and call the ! intrinsic procedure passed as trig_func. WRITE(6, 100) i,” degrees “, trig_func(i*pi/180) END DO 100 FORMAT (I4, A9, F12.8) END SUBROUTINE call_int_arg

Here are the command lines to compile and execute the program, along with the output from a sample run:

$ f90 intrinsic_arg.f90 $ a.out 0 degrees 0.00000000 45 degrees 0.70710675 90 degrees 1.00000000 135 degrees 0.70710686 180 degrees 0.00000015 225 degrees -0.70710665 270 degrees -1.00000000 315 degrees -0.70710697 360 degrees -0.00000030 0 degrees 1.00000000 45 degrees 0.70710681 90 degrees 0.00000008 135 degrees -0.70710670 180 degrees -1.00000000 225 degrees -0.70710691 270 degrees -0.00000023 315 degrees 0.70710659 360 degrees 1.00000000

See Chapter 10, “HP Fortran Statements,” for information about the EXTERNAL and INTRINSIC statements. Intrinsic procedures are fully described in Chapter 11 “Intrinsic procedures”.

Keyword option

The keyword option allows the programmer to specify actual arguments in a procedure reference independently of the position of the dummy arguments. Using the keyword option, the programmer explicitly pairs an actual argument with its dummy argument, as shown by the syntax:

dummy-argument = actual-argument

If the keyword option is used for an argument, it must be followed by other arguments with the keyword option. If all arguments in the argument list use the keyword option, the actual arguments may appear in any order.

As an example of how to use the keyword option, consider the SUM intrinsic function. As described in “SUM(ARRAY, DIM, MASK)”, this intrinsic has three arguments: array, dim, and mask, in that order; dim and mask are optional arguments. The following are therefore valid references to SUM:

SUM(a,2)
SUM(a,mask=a.gt.0)
SUM(dim=2,array=a)

The following is an invalid reference—the mask keyword must be specified:

SUM(a,dim=2,a.gt.0)     ! ILLEGAL, mask keyword missing

Optional arguments

An actual argument may be omitted from the argument list of a procedure reference if its corresponding dummy argument is optional. A dummy argument is optional if it is declared with the OPTIONAL attribute and appears at the end of the argument list. The procedure reference may also omit trailing arguments with the OPTIONAL attribute. Otherwise, keywords must be provided to maintain an identifiable correspondence (see “Keyword option”). Only procedures with an explicit interface may have optional arguments.

The following example, optional_arg.f90, references an internal function that declares one of its dummy arguments with the OPTIONAL attribute. (Internal functions have an explicit interface, making them eligible for optional arguments; see “Internal procedures”.) The function uses the PRESENT intrinsic to test whether or not the optional argument is present. If the intrinsic returns .TRUE. (an actual argument is associated with the optional dummy argument), the function returns the sum of the two arguments; otherwise, it returns the required argument incremented by 1.

Example 7-5 optional_arg.f90

PROGRAM main ! illustrates the optional argument feature INTEGER :: arg1 = 10, arg2 = 20 PRINT *, add_or_inc(arg1) ! omit optional argument PRINT *, add_or_inc(arg1, arg2) CONTAINS ! internal procedure with explicit interface INTEGER FUNCTION add_or_inc(i1, i2) ! return the sum of both arguments if the second argument ! (declared as optional) is present; otherwise, return the ! first argument incremented by 1 INTEGER :: i1 INTEGER, OPTIONAL :: i2 ! optional argument ! use PRESENT intrinsic to see if i2 has an actual ! argument associated with it IF (PRESENT(i2)) THEN add_or_inc = i1 + i2 ! add both arguments ELSE add_or_inc = i1 + 1 ! increment required argument END IF END FUNCTION add_or_inc END PROGRAM main

Here are the command lines to compile and execute the program, along with the output from a sample run:

$ f90 optional_arg.f90
$ a.out
 11
 30

For information about the syntax, rules and restrictions governing the OPTIONAL statement and attribute, see “OPTIONAL (statement and attribute)”. For information about the PRESENT intrinsic see “PRESENT(A)”.

Duplicated association

If a procedure reference would cause a data object to be associated with two or more dummy arguments, the object must not be redefined within the referenced procedure. Consider the following example:

PROGRAM p
   CALL s (a,a)
CONTAINS
   SUBROUTINE s (c,d)
     c = 22.01        ! ILLEGAL 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 procedure includes an assignment to c, the effect of which is to redefine a. This attempt to redefine a is invalid. This rule actual arguments that 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 direct reference to a 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   ! direct reference to a is ILLEGAL
     ...
  END SUBROUTINE
END PROGRAM

INTENT attribute

To enable additional compile-time checking of arguments and to avoid possibly unwanted side effects, the 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:

See “INTENT (statement and attribute)” for more information about the INTENT attribute.

%VAL and %REF built-in functions

By default, HP Fortran passes noncharacter arguments by reference. Instead of passing the value of the actual argument to the referenced procedure, Fortran passes its address, with which the name of the dummy argument becomes associated—as explained in “Argument association”. When HP Fortran passes character arguments, it includes a hidden length parameter along with the address of the actual argument.

However, it is possible to change the way arguments are passed by using the %VAL and %REF built-in functions, which HP Fortran provides as extensions:

These built-in functions are typically used to pass arguments from Fortran to a procedure written in another language, such as a C function. The following example illustrates this use. The program consists of a Fortran 90 main program unit and a C function. The main program calls the C function, passing 4 arguments: an integer constant, a real variable, a character variable, and an integer expression. The main program uses the built-in functions to change Fortran’s argument-passing conventions to conform to C. C expects all arguments except the string—Fortran’s character variable—to be passed by value. It expects the string to be passed by reference, without the hidden length parameter.

Example 7-6 pass_args.f90

PROGRAM main REAL :: x = 3.4 INTEGER :: i1 = 5, i2 = 7 ! C expects strings to be null-terminated, so use the ! concatenation operator to append a null character. CHARACTER(LEN=5) :: str = "Hi!"//CHAR(0) ! Pass 4 arguments--a constant, a variable, a character ! variable, and an expression--to a function written in C. ! Use HP Fortran’s built-in functions to change the ! argument-passing conventions to conform to C. CALL get_args(%VAL(20), %VAL(x), %REF(str), %VAL(i1+i2)) END PROGRAM main

Example 7-7 get_args.c

#include <stdio.h> /* accept 4 arguments from a Fortran 90 program, which are * passed as C expects them to be passed */ void get_args(int i1, float x, char *s, int i2) { /* display argument values */ printf("First argument: %i\n", i1); printf("Second argument: %f\n", x); printf("Third argument: %s\n", s); printf("Fourth argument: %i\n", i2); }

Here are the command lines to compile and link both files, and to execute the program, along with the output from a sample run:

$ cc -Aa -c get_args.c
$ f90 pass_args.f90 get_args.o
$ a.out
First argument:   20
Second argument:  3.400000
Third argument:   Hi!
Fourth argument:  12

For additional information about multi-language programming, refer to the HP Fortran Programmer’s Guide. The built-in functions can also be used with the ALIAS directive, where they have a slightly different syntax.