SUBROUTINES AND SUBROUTINE SUBPROGRAMS

(3)

FUNCTION MOM(N,L)

Because of implicit typing, a subprogram beginning with the above statement generates an integer value unless its type is changed by a type statement or IMPLICIT statement within the subprogram. A reference to this function could be of the form I=MOM(J,K). In the calling program unit, the function reference would be implicitly typed integer unless declared otherwise (see 2.4).

REAL FUNCTION MOM(X,Y)

A function defined by a subprogram beginning with the above statement is explicitly typed real, so the value generated is real for a

function call such as X=MOM(P,Q). The function reference would then have to be declared real in the calling program unit.

FUNCTION AVERAGE(A,N) REAL A(N)

SUM = 0.0 DO 10 I=1,N

SUM = SUM + A(I) 10 CONTINUE

AVERAGE = SUM/N

END

The above function subprogram uses a dummy array and a DO loop to compute an average of the N values contained in an actual array. See 4.3 concerning arrays and 6.3 concerning DO loops. Notice that the function name is defined within the subprogram.

2.5.2 SUBROUTINES AND SUBROUTINE SUBPROGRAMS

A subroutine is an executable entity that is invoked only by a CALL statement within a program unit or other procedure. A subroutine is distinct from a function in that it is called only by the CALL statement and has no data value associated with its name. A subroutine name cannot be used in an expression, and it has no data type.

A subroutine can be specified by either a Fortran subprogram or a non-Fortran procedure (described in appendix F). A Fortran subprogram that specifies a subroutine is a subroutine subprogram.

Users of Cray computer systems have access to a library of subroutines for a variety of purposes, including mathematical, scientific, and system utilities. These are described in the Programmer's Library Reference Manual, CRI publication SR-Ol13.

If a subroutine is to process data known to the calling program unit, variables in the subroutine and program unit must be associated; that is, they must represent the same memory locations. This association can be established by an argument list (see 2.6) or by common blocks (see 4.6).

A subroutine subprogram normally executes from beginning to end; then control transfers to the statement following the CALL statement that called the subroutine. This sequence can be altered in the following ways (see 2.5.3):

• The subprogram can begin executing at any point that an ENTRY statement appears.

• The RETURN statement can end execution before the end.

• The RETURN statement can specify a different point in the calling program unit to resume execution. This is an alternate return.

2.5.2.1 Requirements

A subroutine subprogram begins with a SUBROUTINE statement containing the subroutine's name and the names of any dummy arguments or alternate

return specifiers, and ends with an END statement. A subroutine

subprogram cannot contain a BLOCK DATA, FUNCTION, or PROGRAM statement, or a second SUBROUTINE statement.

The name of a subroutine or subroutine entry is global, and within the calling program unit cannot be used as a local name, function name, function entry name, or namelist.

2.5.2.2 CALL statement (subroutine reference)

The CALL statement causes execution of the subroutine specified in the statement. It can specify actual arguments to be associated with dummy arguments in the subroutine, to allow the subroutine to process data as needed by the calling program unit. The CALL statement can also specify different statements to which control can be returned.

CALL sub [([a[,a] •.. ])]

sub Symbolic name of a subroutine, subroutine entry (see 2.5.3.1), or dummy subroutine. sub can be a dummy

subroutine name only within a subprogram, one of whose dummy arguments is sub (see 2.6.4).

a Actual argument or alternate return specifier. Permitted actual arguments are discussed in 2.6.2. An alternate return specifier (*s, denoting a statement label) allows control to be transferred to a different statement in the calling program unit (see the RETURN statement, 2.5.3.2).

The types of actual arguments specified in a CALL statement must agree with associated dummy arguments defined in the called subroutine. In standard Fortran, the number of actual and dummy arguments must also

agree, but this requirement is not enforced by CFT77. However, if a dummy argument that is not associated with an actual argument is referenced, an error or undefined value will result. To prevent this, any dummy argument not associated with an actual argument must follow, in the dummy argument list, all dummy arguments that are associated with actual arguments.

Examples:

~LLS~

CALL GEORGE(X,-7.) CALL TOM(*10,X,*20,Y)

Corresponding to the examples shown for the SUBROUTINE statement (2.5.2.3, following), the first example above calls subroutine S~;

the second calls subroutine GEORGE with actual arguments X and -7.;

and the third calls subroutine TOM with actual arguments X and Y and alternate return specifiers for statements 10 and 20.

Execution of a CALL statement results in the following:

• Evaluation of actual arguments that are expressions (see 2.6.2)

• Association of actual arguments with the corresponding dummy arguments, as described in 2.6.2.

• The actions specified by the referenced subroutine

Control can be returned to the first executable statement following the CALL statement or to a statement indicated by an alternate return

specifier in the CALL statement. Return of control to the referencing program unit completes execution of the CALL statement.

2.5.2.3 SUBROUTINE statement

The SUBROUTINE statement identifies a subroutine subprogram. It contains the subroutine name and an optional list of dummy arguments or asterisks corresponding to alternate return specifiers.

SUBROUTINE sub [([d[,d] ••. ])]

sub Symbolic name of the subroutine; the name is global.

d Dummy argument or asterisk. A dummy argument represents an entity used in the subprogram, corresponding to an actual argument in the CALL statement that calls the subprogram.

An asterisk corresponds to an alternate return specifier in the CALL statement (see CALL statement, 2.5.2.2 and RETURN statement, 2.5.3.2).

Examples:

SUBROUTINE SAM

SUBROUTINE GEORGE(A,B) SUBROUTINE TOM(*,X,*,Y)

The first example is the first statement of subroutine SAM, which has no dummy arguments or alternate returns. The second example is for a subroutine with dummy arguments A and B. The third is for a

subroutine with dummy arguments X and Y, and two asterisks

corresponding to alternate return specifiers in the CALL statement.

The examples shown for the CALL statement (2.5.2.2, previous) correspond to these examples.

2.5.3 ALTERING THE TRANSFER OF CONTROL BETWEEN PROGRAM UNITS

The following statements let you choose, with some restrictions, where execution of a subprogram begins and ends, and to choose where execution resumes in the calling program unit after execution of a subroutine.

2.5.3.1 ENTRY statement

The ENTRY statement is used in a procedure subprogram to allow execution to begin at a point within the subprogram's execution sequence, rather than at the beginning. In the procedure call, the name in the ENTRY statement is used instead of the name appearing in the subprogram's FUNCTION or SUBROUTINE statement.

The ENTRY statement is nonexecutable and can appear anywhere in a

procedure subprogram after the FUNCTION or SUBROUTINE statement, except within a DO-loop or IF structure (see 6.1). Execution begins at the ENTRY statement. A procedure subprogram can contain one or more ENTRY

statements following its FUNCTION or SUBROUTINE statement.

ENTRYen[([d[,d] ... ])]

en Entry name; this name is a subroutine name or function name used in procedure calls in the normal way. Restrictions are listed in a subsequent paragraph.

d Dummy argument representing a variable name, array name, procedure name, or an asterisk associated with an alternate return specifier (only in a subroutine subprogram). 2.6.2 discusses requirements for dummy and actual arguments.

Dummy arguments in an ENTRY statement need not agree with those specified in a FUNCTION, SUBROUTINE, or other ENTRY statement in the same

subprogram. Any dummy argument must be named in an ENTRY statement or header statement before i t appears in an executable statement or statement function statement.

Restrictions on the entry name en are as follows:

• en cannot be used as a dummy argument in the same subprogram.

• In a function subprogram, en must not appear as a variable in any statement preceding the ENTRY statement, except a type statement.

• en cannot be the same as any global name in the same executable program.

• en cannot appear in a POINTER or NAMELIST statement.

• In a function subprogram of type character, en must be of type character, with the same declared length as the function name,

In a function subprogram, the function name en specified in an ENTRY statement can appear as a result variable within the subprogram. Even if it does not appear, it is associated with all other result variables within the subprogram, including the function name shown in the FUNCTION statement. Rules of association appiy as described in 4.5. Entry names can differ in type from the name in the FUNCTION statement, except when the type is character.

Example:

PROGRAM ENTRYEX REAL MEAN

A=MEAN(ARR1) J=MEDIAN(ARR2) END

REAL FUNCTION MEAN (ARRX) ENTRY MEDIAN (ARRX)

MEAN = •••

IF ( ••. ) RETURN MEDIAN =

END

In this example, because the functions MEAN and MEDIAN use some of the same code, they are combined into one function subprogram. The entry name MEDIAN is used as a function reference in the calling program unit and as a result variable in the subprogram. Note that MEAN is real and MEDIAN is integer type.

Because all result variables are associated, a conditional RETURN statement is needed so that the value for function reference MEAN is not changed by the assignment to MEDIAN. A change to MEAN would give at least an unintended result in the calling program unit, and in this case would create an undefined value because the two variables are of different types. If MEDIAN and MEAN were of the same type, the assignment to MEDIAN could instead be to MEAN, with the same result, because they are associated.

2.5.3.2 RETURN statement

A RETURN statement returns control from a procedure subprogram to the referencing program unit. The statement is used only in function subprograms and subroutine subprograms. A subprogram can contain more than one RETURN statement but need not contain any RETURN statements because executing an END statement in a function or subroutine subprogram has the same effect as executing a RETURN statement.

In a function subprogram, the statement consists of only the word RETURN. In a subroutine subprogram, the format is as follows:

i

RETURN [i]

Integer expression specifying an alternate return. i indicates the ith return specifier in the list of dummy arguments in a subroutine subprogram; see the next paragraph.

An alternate return allows a subroutine to return control to a