The USE statement gives the program unit access to public entities in the module and is defined as follows:

USE module_name [, rename_list ]

USE module_name, ONLY: [ only_list ]

local_name => use_name

generic_spec

only_use_name

only_rename

use_name

local_name=>use_name

Specifying a USE statement with a rename_list allows any of the public entities in the module to be renamed to avoid name conflicts or to blend with the readability flavor in the using program unit.

Examples:

USE FOURIER
USE S_LIB, PRESSURE => X_PRES

With both USE statements in the preceding example, all public entities in the respective modules are made accessible. In the case of FOURIER, the names are those specified in the module. In the case of S_LIB, the entity named X_PRES is renamed PRESSURE in the program unit using the module. The other entities accessed from S_LIB have the same name in the using program unit as in the module.

To restrict the entities accessed from a module, specify ONLY on the USE statement, as follows:

USE module_name, ONLY: only_list

In this case, the using program unit has access only to those entities explicitly identified in the ONLY clause of the USE statement. All items in this list must identify public entities in the module. As with the unrestricted form of the USE statement, named accessed entities may be renamed for local purposes. The possible forms of each item in the only_list are as follows:

The local_name, if present, specifies the name of the module entity in the using program unit.

USE MTD, ONLY:  X, Y, OPERATOR( .ROTATE. )
USE MONTHS, ONLY: JANUARY => JAN, MAY, JUNE => JUN

In the case of MTD, only X, Y, and the defined operator .ROTATE. are accessed from the module, with no renaming. In the case of MONTHS, only JAN, MAY, and JUN are accessed. JAN is renamed JANUARY and JUN is renamed JUNE.

In addition, specifying the statement on the left is equivalent to specifying the two statements on the right:

USE MTD, ONLY:  X, Y          USE MTD, ONLY:  X
                              USE MTD, ONLY:  Y

The following items can be defined, declared, or specified in a module, and may be public. They are accessed through the USE statement by other program units. Any public entity, except a defined operator or assignment interface, can be renamed in the using program unit.

Note that the preceding list does not contain the implicit type rules of the module; these are not accessible through a USE statement.

A common block can be declared in a module. Because a common block name is global, however, it is not one of the name categories that is made available to another program unit via a USE statement. The names of the members of the common block in a module, though, are made available through the USE statement; these member names can be given local names through the USE statement renaming clauses. Consider, for example, the following module:

MODULE definer
COMMON /def/ i, j, r
END MODULE

All three of the members of common block DEF are made accessible to a program unit containing the following USE statement because all three variables are public entities of the module:

USE definer

The following USE statement limits access to only common block member R and gives it the local name MY_R:

USE def, ONLY: MY_R => R

The default accessibility for all entities in a module is PUBLIC unless this default has been changed by a PRIVATE statement with an empty entity list. If the default has been turned to PRIVATE, an entity can be made PUBLIC by its appearance in a PUBLIC statement or in a type declaration that contains the PUBLIC attribute. An entity can be specified to be PRIVATE in a PRIVATE statement or in a type declaration statement that contains the PRIVATE attribute.

Each named entity in a module is classified as either public or private. Regardless of this classification, all module entities can be used freely within the module, including within module procedures in the module; within a module procedure a module entity is governed only by the rules of host association. Outside the module, however, only the public entities are accessible (via the USE statement). Figure 3-3 illustrates these rules:

Figure 3-3. Use of public and private module entities

When using modules, name conflicts can occur in the following two ways:

Example:

MODULE BLUE
   INTEGER  A, B, C, D
END MODULE BLUE
MODULE GREEN
   USE BLUE, ONLY : AX => A
   REAL  B, C
END MODULE GREEN
! in program RED:
! integer A is accessed as AX or A
! integer B is accessed as B
!   real B is accessed as BX
! neither C is accessible, because
!   there is a name conflict
PROGRAM RED
   USE BLUE            ! accesses A, B, C, and D
   USE GREEN, BX => B  ! accesses A as AX, B as
                       ! BX, and C
   REAL D              ! Illegal; D cannot be
   . . .               ! redeclared locally.
END

The USE statement gives a program unit access to other entities not defined or specified locally within the using program. The association between a module entity and a local entity in the using program unit is termed use association. Host association is analogous, but host association applies only to a module and its module procedures and to internal procedures and their hosts. There are many similarities between use association and host association. Their rules, however, are different in the following two ways:

The only exception to the second rule is that if the using program unit is another module, then the using module can specify an entity from the used module to be PRIVATE in the using module, rather than maintaining public accessibility. This is perhaps best illustrated with an example. In the following code, program units using module M2, defined as follows, can access X but not Y, even though Y is a public entity of M1:

MODULE M2
   USE M1, ONLY: X, Y
   PRIVATE  Y
      . . .
END MODULE M2

The prohibition on respecifying entities accessed via use association includes the use of module data objects in locally specified COMMON and EQUIVALENCE specifications.

While a name accessed from a module must not be respecified locally, the same name can be imported from another module under either of the following conditions:

A module provides an easy way of making type definitions and data declarations global in a program. Data in a module does not have an implied storage association or an assumption of any form of sequence or any order of appearance, unless it is a sequence structure or in a common block. Global data in a module can be of any type or combination of types, as follows:

MODULE MODELS
   COMPLEX           :: GTX(100, 6)
   REAL              :: X(100)
   REAL, ALLOCATABLE :: Y(:), Z(:, :)
   INTEGER              CRX, GT, MR2
END MODULE

There are alternative ways to use the preceding module. The following statement makes all the data (and their attributes) of the module available:

USE MODELS

The following statement makes only the data named X and Y and their attributes available to the program using the module:

USE MODELS, ONLY: X, Y

The following statement makes the data object named Z available, but it is renamed to T for that particular application. In addition, it makes the other public entities of the module MODELS available with the same names they have in the module:

USE MODELS, T => Z

One way of packaging common blocks is by putting them in a module. Consider the following program:

MODULE LATITUDE
   COMMON . . .
   COMMON . . .
   COMMON /BLOCK1/ . . .
END MODULE
   . . .
PROGRAM NAVIGATE
USE LATITUDE
   . . .
END

The USE statement in the preceding example makes all of the variables in the common blocks in the module available to the program NAVIGATE. These common blocks can be made available to other program units in the same way.

Unless there is a reason for variables to have their storage association in a particular order, there is no need to include a common block in a module. The data in a module is already global.

A derived type defined in a module is a user-defined type that can be made accessible to other program units. The same type definition can be referenced through a USE statement by more than one program unit. Consider the following code:

MODULE NEW_TYPE
   TYPE TAX_PAYER
      INTEGER SSN
      CHARACTER(20) NAME
   END TYPE TAX_PAYER
END MODULE NEW_TYPE

In the preceding example, the module NEW_TYPE contains the definition of a new type called TAX_PAYER. Procedures using the module NEW_TYPE may declare objects of type TAX_PAYER.

An interface block can declare new operators or give additional meanings to the intrinsic ones, such as +, .EQ., .OR., and //. The assignment symbol = also can be given additional meanings and may be redefined for derived-type intrinsic assignment. (Derived-type assignment is the only instance of an intrinsic operation or assignment that can be redefined.) These extensions require that the OPERATOR or ASSIGNMENT option be on the interface block, the details of which appear in Section 4.8 in Chapter 4.

A simple example of an OPERATOR interface for matrix inversion requires a function and an interface block defining the new operator. In the following example, which normally (but not necessarily) would be in a module, the function INVERSE defines the desired operation, and the operator .INVERSE. can be used in an expression to reference the function:

INTERFACE OPERATOR(.INVERSE.)
   FUNCTION INVERSE(MATRIX_1)
      TYPE(MATRIX), INTENT(IN) :: MATRIX_1
      TYPE(MATRIX) :: INVERSE
   END FUNCTION INVERSE
END INTERFACE

An example of its use might be as follows (assuming + also has been extended to add a real value and a MATRIX):

1.0 + (.INVERSE. A)

Data type definitions and operations can be packaged together in a module. Program units using this module will have the convenience of a new data type specific to a particular application. The following is a simple example:

MODULE POLAR_COORDINATES
   TYPE POLAR
      PRIVATE
      REAL RHO, THETA
   END TYPE POLAR
   INTERFACE OPERATOR(*)
      MODULE PROCEDURE POLAR_MULT
   END INTERFACE
CONTAINS
   FUNCTION POLAR_MULT(P1, P2)
      TYPE(POLAR),INTENT(IN) :: P1,P2
      TYPE(POLAR) :: POLAR_MULT
      POLAR_MULT = &
            POLAR(P1%RHO   * P2%RHO,  &
                  P1%THETA + P2%THETA)
   END FUNCTION POLAR_MULT
      . . .
END MODULE POLAR_COORDINATES

In the function POLAR_MULT, the structure constructor POLAR computes a value that represents the result of multiplication of two arguments in polar coordinates. Any program unit using the module POLAR_COORDINATES has access to both the type POLAR and the extended intrinsic operator * for polar multiplication.

A module can contain a collection of interface blocks for related procedures. Argument keywords, as well as optional arguments, can be used to differentiate various applications using these procedures. The following is a simple example:

MODULE ENG_LIBRARY
   INTERFACE
      FUNCTION FOURIER(X, Y)
          . . .
      END
      SUBROUTINE INPUT(A, B, C, L)
         OPTIONAL C
         . . .
      END SUBROUTINE INPUT
   END INTERFACE
END MODULE ENG_LIBRARY

The following example shows that an input routine can be called using optional or keyword arguments:

CALL INPUT (AXX, L = LXX, B = BXX)

A collection of related procedures that need to access the same type definitions and data declarations can be placed in a module. The following example shows this:

MODULE BOOKKEEPING
   TYPE, PRIVATE :: ID_DATA
      INTEGER ID_NUMBER
      CHARACTER(20) NAME, ADDRESS(3)
      REAL BALANCE_OR_SALARY
   END TYPE ID_DATA
   REAL, PRIVATE :: GROSS_INCOME, EXPENSES,  &
                    PROFIT, LOSS
   INTEGER, PARAMETER :: NUM_CUST = 1000,  &
                         NUM_SUPP = 100,  &
                         NUM_EMP  = 10
CONTAINS
   SUBROUTINE ACCTS_RECEIVABLE(CUST_ID, AMOUNT)
      . . .
   END SUBROUTINE ACCTS_RECEIVABLE
   SUBROUTINE ACCTS_PAYABLE(CUST_ID, AMOUNT)
      . . .
   END SUBROUTINE ACCTS_PAYABLE
   SUBROUTINE PAYROLL(EMP_ID, AMOUNT)
      . . .
   END SUBROUTINE PAYROLL
   FUNCTION BOTTOM_LINE(AMOUNT)
      . . .
   END FUNCTION BOTTOM_LINE
END MODULE