Understanding External Subprograms in Programming

1. Chapter 10 Modules andprogrammingwithsubroutines

2. External functions • In the chapter 9, it is stated that function subprograms can be classified in three ways: 1) Internal subprograms 2) Module subprograms 3) External subprograms • we have already studied internal and module subprograms (functions) in detail in the previous chapter. We shall focus on external subprograms. EXTERNAL SUBPROGRAMS • A subprogram can be made accessible to a program unit by attaching it after the end statement of the program unit; in this case it is called an external subprogram. • In the following example, the function subprogram Fahr_to_Celsius is an external subprogram attached to program Temperature_Conversion_3. Note that Fahr_to_Celsius is declared in both the main program and the subprogram.

3. Example Program Temperature_Conversion_3 real :: Fahr_to_Celsius real :: FahrenheitTemp, CelsiusTemp character(1) :: Response do write (*, ‘(1X, A)’, advance = “no”) “Enter a Fahrenheit temperature: “ read *, FahrenheitTemp CelsiusTemp = Fahr_to_Celsius(FahrenheitTemp) print ‘(1X, 2(F6.2, A))’, FahrenheitTemp, “ in Fahrenheit is equivalent & to “, CelsiusTemp, “ in Celsius” write (*, ‘(/ 1X, A)’, advance = “no”) & “More temperatures to convert (Y or N) ? ” read *, Response if (Response /= “Y”) exit end do end program Temperature_Conversion_3 function Fahr_to_Celsius (Temperature)

4. Example (cont.) implicit none real :: Fahr_to_Celsius real, intent(in) :: Temperature Fahr_to_Celsius = (Temperature - 32.0) / 1.8 end function Fahr_to_Celsius

5. Interfaces • A main program and external subprograms are separate, independent program units. Neither the main program nor any subprogram can access any of the items declared locally in any other subprogram, not can an external subprogram access any of the items declared in the main program. The only way that information is passed from one program unit to another is by means of the arguments and the function name. • Since internal subprograms are contained within a host, the compiler can check each reference to the subprogram to determine if it has the correct number and types of arguments (and other properties) and for a function subprogram, whether the value returned is used correctly. • Similarly, module subprograms are referenced in statements within that module or in statements that follow a use statement for that module, and the compiler can check that the arguments and result returned are used correctly. In both cases, the subprogram has an explicit interface. • An external subprogram is separate from the main program and from other program units, and the compiler may not be able to check whether references to it are correct. Consequently, external subprograms are said to have implicit interfaces.

6. Interfaces • Interface blocks can be used to provide these explicit interfaces. They have several different forms and uses, but the form needed for external subprograms is interface interface-body end interface where interface-body consists of: 1) The subprogram heading (except that different names may be used for the formal arguments) 2) Declarations of the argument and the result type in the case of a function 3) An end function (or end subroutine) statement

7. Example for interface • Following example illustrates the use of an interface block to provide an explicit interface for the function Fahr_to_Celsius. program Temperature_Conversion_4 implicit none interface function Fahr_to_Celsius (Temperature) real :: Fahr_to_Celsius real, intent (in) :: Temperature end function Fahr_to_Celsius end interface real :: FahrenheitTemp, CelsiusTemp character (1) :: Response do write (*, ‘(1X, A)’, advance = “no”) “Enter a Fahrenheit temperature: “ read *, FahrenheitTemp

8. Example for interface CelsiusTemp = Fahr_to_Celsius(FahrenheitTemp) print ‘(1X, 2(F6.2, A))’, FahrenheitTemp, “ in Fahrenheit is equivalent & to “, CelsiusTemp, “ in Celsius” write (*, ‘(/ 1X, A)’, advance = “no”) & “More temperatures to convert (Y or N) ? ” read *, Response if (Response /= “Y”) exit end do end program Temperature_Conversion_4 function Fahr_to_Celsius (Temperature) implicit none real :: Fahr_to_Celsius real, intent(in) :: Temperature Fahr_to_Celsius = (Temperature - 32.0) / 1.8 end function Fahr_to_Celsius

9. Introduction to recursion • All of the examples of function references considered thus far have involved a main program referencing a subprogram or one subprogram referencing another subprogram. In fact, a subprogram may even reference itself, a phenomenon known as recursion. • In general, a function is said to be defined recursively if its definition consists of two parts: 1) An anchor or base case, in which the value of the function is specified for one or more values of the argument(s). 2) An inductive or recursive step, in which the function’s value for the current value of the argument(s) is defined in terms of previously defined function values and/or argument values. Examples: 1) The factorial function is computed by 0! = 1 (The anchor or base case) For n>0, n! = n*(n-1)! (The inductive or recursive step) 2) The power function is computed by x0 = 1 (The anchor or base case) For n>0, xn = x*xn-1 (The inductive or recursive step)

10. Recursion • In each definition, the first statement specifies a particular value of the function, and the second statement defines its value for n in terms of its value for n-1. • Subprograms may be declaredto be recursive byattaching the word recursive at the beginning of the subprogram heading. For a recursive function, a result clause must also be attached at the end of the function heading to specify a variable that will be used to return the function result rather than the function name. To illustrate, consider the factorial function again. The recursive definition of this function can be implemented as a recursive function in Fortran in a straightforward manner: ! Factorial ! Function to calculate factorials (recursively) ! Accepts: integer n>= 0 ! Returns: n! recursive function Factorial(n) result (Fact) integer :: Fact ! result variable integer, intent (in) :: n if (n == 0) then Fact = 1

11. Recursion (cont) else Fact = n * Factorial (n-1) end if end function Factorial • When this function is referenced, the inductive step else Fact = n* Factorial (n-1) causes the function to reference itself repeatedly, each time with a smaller argument, until the anchor case if ( n == 0) then Fact = 1 is reached.

12. Subroutine subprograms • Subprograms in Fortran can be either functions or subroutines. In the proceeding chapter, we considered only function subprograms. From now on we will focus on subroutine subprograms. • Subroutine subprograms differ from function subprograms in the following respects: • Functions are designed to return a single value to the program unit that references them. Subroutines often return more than one value, or they may return no value at all. • Functions return values via function names; subroutines return values via arguments. • A function is referenced by using its name in an expression, whereas a subroutine is referenced by a call statement. • A subroutine subprogram opens with a subroutine statement that names the procedure that is being defined and lists its dummy arguments, if any; if there are no arguments, an empty pair of parenthesis is required. The subprogram closes with an end subroutine statement:

13. Subroutine subprograms • The form of a subroutine subprogram is subroutine heading specification part execution part end subroutine statement • The subroutine heading is a subroutine statement of the form subroutinesubroutine-name (formal-argument-list) or for a recursive subroutine, recursive subroutinesubroutine-name (formal-argument-list) • A subroutine is referenced by a call statement of the form call subroutine-name (formal-argument-list) This statement calls the named subroutine. When execution of the subroutine is completed, execution of the original program unit resumes with the statement following the call statement.

14. Example for subroutine subprogram program Angles_1 ! Program demonstrating the use of a subroutine PrintDegrees to ! Display an angle in degrees. ! Input : NumDegrees, NumMinutes, NumSeconds, Response ! Output : Equivalent measure in degrees (displayed by PrintDegrees) implicit none integer :: NumDegrees, NumMinutes, NumSeconds character (1) :: Response do write (*, ‘ (1X, A) ‘, advance = “no”) “Enter degrees, minutes, and seconds: “ read *, NumDegrees, NumMinutes, NumSeconds call PrintDegrees (NumDegrees, NumMinutes, NumSeconds) write (*, ‘ (/ 1X, A) ‘, advance = “no”) “More angles ( Y or N) ? “ read *, Response if (Response /= “Y”) exit end do contains

15. Example for subroutine subprogram (cont.) subroutine PrintDegrees (Degrees, Minutes, Seconds) integer, intent (in) :: Degrees, Minutes, Seconds print *, Degrees, Minutes, Seconds, & real (Degrees) + real (Minutes) / 60.0 + real (Seconds) / 3600.0 end subroutine PrintDegrees end program Angles_1

16. Argument association • Assume that the call statement call Convert_to_Rectangular (RCoord, TCoord, XCoord. YCoord) is executed in the main program, and the corresponding subroutine is written in the following way: subroutine Convert_to_Rectangular (R, Theta, X, Y) real, intent (in) :: R, Theta real, intent (out) :: X, Y • The values of the actual arguments RCoord and TCoord are passed to the formal arguments R and Theta, respectively: Actual Formal ArgumentsArguments RCoord R TCoord Theta XCoord X YCoord Y R and Theta have been declared to be in arguments because the intent is that values are only to be passed to them and used within the subroutine.

17. Argument association • The formal arguments X and Y are declared to have the intent (out) attribute because they are intended only to pass values back to the calling program unit. Actual Formal ArgumentsArguments RCoord R TCoord Theta XCoord X YCoord Y • A formal argument may also be declared to have the intent (inout) attribute. Such arguments can be used to pass information both to and from the subroutine: actual-argumentformal-argument • Because both out and inout arguments are intended to pass values back to the calling program unit, the corresponding actual arguments must be variables.

18. Exercises • Read pages between 80-99 (Ellis’s Book). • Study pages between 193-226 (Ellis’s Book). • Do example 8.1 on page 194 and self-tests 8.1& 8.2 (Ellis’s Book).

19. Subprograms as arguments • In our examples of subprograms so far, the actual arguments have been constants, variables, or expressions, but Fortran also permits functions and subroutines as arguments for other subprograms. In this case, the function or subroutine must be a module subprogram, an external subprogram, or an intrinsic subprogram. MODULE SUBPROGRAMS AS ARGUMENTS We wish to use a subroutine integrate in an other program to calculate the integral of the function Integrand(x), defined by integrand (x) = ex2, for 0 <= x <= 1. program Definite_Integral_2 Main program: use Integrand_Function ! Module containingIntegrand call Integrate(Integrand, A, B, Num_Of_Subintvals) contains subroutine Integrate (F, A, B, N) end subroutine Integrate end program Definite_Integral_2

20. Module subprograms as arguments Module: module Integrand_Function contains function Integrand (x) end function Integrand end module Integrand_Function

21. External subprograms as arguments • If an external function is to be passed as an argument to some other subprogram, it must be declared to have the externalattribute. This can be done by using an external specifier in its type declaration, type, external :: function-name or by using a separate external statement of the form external list of external subprogram names only the second form can be used for subroutines, because they are not declared (since they have no type associated with them).

22. Intrinsic subprograms as arguments • Suppose that we would like to approximate the integral of the sine function from 0 to 0.5, we can simply change the definition of Integrand to Integrand = sin (x) and re-use the previous approach. An alternative is to remove the use statement in module section or delete the function subprogram Integrandin external section, and pass the intrinsic function sinas an argument to integrate. In this case we must indicate that it is an intrinsic function by using an intrinsic statement of the form intrinsic List of intrinsic subprogram names or by using an intrinsic specifier in a type declaration: type, intrinsic :: function-name

23. Interface blocks • When an external subprogram is used in a program, the actual arguments must be associated correctly with the corresponding formal arguments, and for a function, the value returned by the function must be used appropriately • In some cases the compiler does not have enough information about the arguments to ensure that the subprogram is being used correctly. Example: Consider the same trapezoidal approximation of an integral. Program Definite_Integral_5 . . Interface function Integrand (X) real :: integrand real, intent (in) :: X end function Integrand end interface contains subroutine Integrate

24. Interface blocks end program Definite_Integral_5 function Integrand (X) real :: Integrand real, intent (in) :: X Integrand = exp(X**2) end function Integrand • Most compilers would not detect any errors even though a function with two arguments is passed to the formal argument if we do not use the interface. • Note that the external attribute is not specified for the function Integrand. In general, interface blocks and externalspecifiers cannot both be used to declare subprograms, nor can interface blocks be used for module subprograms or intrinsic subprograms.

25. Procedure arguments • In this section, we will summarise the procedure arguments used and passed in subprograms more detail. Here are key concepts related to procedure arguments: 1) Each dummy argument that appears in the header statement of a subprogram must be the name of a variable, which may be a scalar variable, an array variable, or a structure of any type. A dummy argument must not be an array element or section designator, a structure component designator, or a substring designator. 2) Each actual argument used in any reference to the procedure is an expression, which may be a constant or a variable name. 3) The number of actual arguments in the procedure reference must agree with the number of dummy arguments in the procedure header. Except for keyword arguments, the correspondence between dummy and actual arguments depends on their respective positions in the argument list. The names of the actual arguments may be different from the names of the corresponding dummy arguments.

26. Procedure arguments 4) The type, kind type parameter, and rank (number of dimensions) of each actual argument must match those of the corresponding dummy argument. 5) A procedure may have no arguments, one argument, or more than one argument. If there are no arguments, a function or subroutine statement must include empty parentheses. Thus, the subprogram header statement of a subprogram may have any of the following forms: subroutine Subroutine name (Dummy argument list) subroutine Subroutine name recursive subroutine Subroutine name (Dummy argument list) pure function Function name (Dummy argument list) result (Result name) pure function Function name ()result (Result name) recursive pure function Function name (Dummy argument list) result (Result name)

27. I / O arguments • An intent attribute must be declared for each dummy argument in a procedure, except that pointers and dummy procedures can not have an intent attribute. This attribute is specified in a type declaration, and has one of three forms: intent (in) intent (out) intent (inout) • Arguments with intent (out) or intent (inout) are not permitted in a function subprogram.

28. Arrays in a procedure • A dummy argument array is an assumed-shape array; its shape is assumed (taken) from the actual argument array. • Besides dummy argument arrays, a procedure may, of course, have local arrays. It may also inherit other arrays from a host program or subprogram or import arrays from modules. • Fixed-shape local arrays are those declared with constant expressions for upper bounds and for any lower bounds that are not omitted. • Automatic-shape local arrays (which may appear in a subprogram, but not in a main program nor in the specification part of a module) are declared with dimension bound expressions that are specification expressions involving one or more variables that have defined values at procedure entry. • The name, type and kind, and rank of an assumed-shape dummy argument array are declared in the subprogram, but its shape (extent along each dimension) is left unspecified. For example: real (kind = SRK7), dimension ( : , : ), intent (in) :: Data_Array