USE

Statement: Gives a program unit accessibility to public entities in a module.

Syntax

USE [[, mod-nature] ::] name [, rename-list ] ...
USE [[, mod-nature] ::] name, ONLY : [, only-list ]

mod-nature
Is INTRINSIC or NON_INTRINSIC. If INTRINSIC is used, name must be the name of an intrinsic module. If NON_INTRINSIC is used, name must be the name of an nonintrinsic module. If mod-nature is not specified, name must be the name of an intrinsic or nonintrinsic module. If both are provided, the nonintrinsic module is used. It is an error to specify a user module and an intrinsic module of the same name in the same program unit (see Examples).

name
Is the name of the module.

rename-list
Is one or more items having the following form:

local-name => mod-name

local-name
Is the name of the entity in the program unit using the module or is "OPERATOR (op-name)", where op-name is the name of a defined operator in the program unit using the module.

mod-name
Is the name of a public entity in the module or is "OPERATOR (op-name)", where op-name is the name of a public entity in the module.

only-list
Is the name of a public entity in the module or a generic identifier (a generic name, a defined operator specified as "OPERATOR (op-name)", or defined assignment).

An entity in the only-list can also take the form:

[local-name =>] mod-name

Description

If the USE statement is specified without the ONLY option, the program unit has access to all public entities in the named module.

If the USE statement is specified with the ONLY option, the program unit has access to only those entities following the option.

If more than one USE statement for a given module appears in a scoping unit, the following rules apply:

• If one USE statement does not have the ONLY option, all public entities in the module are accessible, and any rename-lists and only-lists are interpreted as a single, concatenated rename-list.
  
  
• If all the USE statements have ONLY options, all the only-lists are interpreted as a single, concatenated only-list. Only those entities named in one or more of the only-lists are accessible.

If two or more generic interfaces that are accessible in a scoping unit have the same name, the same operator, or are both assignments, they are interpreted as a single generic interface. Otherwise, multiple accessible entities can have the same name only if no reference to the name is made in the scoping unit.

The local names of entities made accessible by a USE statement must not be respecified with any attribute other than PUBLIC or PRIVATE. The local names can appear in namelist group lists, but not in a COMMON or EQUIVALENCE statement.

The local names of entities made accessible by a USE statement must not be respecified with any attribute other than ASYNCHRONOUS or VOLATILE. However, they can appear in a PUBLIC or PRIVATE statement.

The local names can appear in namelist group lists, but not in a COMMON or EQUIVALENCE statement.

See Also: Program Units and Procedures, USE overview (more examples)

Examples

The following shows examples of the USE statement:

MODULE MOD_A
  INTEGER :: B, C
  REAL E(25,5), D(100)
END MODULE MOD_A
...
SUBROUTINE SUB_Y
  USE MOD_A, DX => D, EX => E   ! Array D has been renamed DX and array E
  ...                           ! has been renamed EX. Scalar variables B
END SUBROUTINE SUB_Y            ! and C are also available to this subrou-
...                             ! tine (using their module names).
SUBROUTINE SUB_Z
  USE MOD_A, ONLY: B, C         ! Only scalar variables B and C are
  ...                           !   available to this subroutine
END SUBROUTINE SUB_Z
...

You must not specify a user module and an intrinsic module of the same name in the same program unit. For example, if you specify a user module named ISO_FORTRAN_ENV, then it is illegal to specify the following in the same program unit:

USE :: ISO_FORTRAN_ENV
USE, INTRINSIC :: ISO_FORTRAN_ENV

The following example shows a module containing common blocks:

MODULE COLORS
  COMMON /BLOCKA/ C, D(15)
  COMMON /BLOCKB/ E, F
  ...
END MODULE COLORS
...
FUNCTION HUE(A, B)
  USE COLORS
  ...
END FUNCTION HUE

The USE statement makes all of the variables in the common blocks in module COLORS available to the function HUE.

To provide data abstraction, a user-defined data type and operations to be performed on values of this type can be packaged together in a module. The following example shows such a module:

MODULE CALCULATION
  TYPE ITEM
    REAL :: X, Y
  END TYPE ITEM

  INTERFACE OPERATOR (+)
    MODULE PROCEDURE ITEM_CALC
  END INTERFACE

CONTAINS
  FUNCTION ITEM_CALC (A1, A2)
    TYPE(ITEM) A1, A2, ITEM_CALC
    ...
  END FUNCTION ITEM_CALC
  ...
END MODULE CALCULATION

PROGRAM TOTALS
USE CALCULATION
TYPE(ITEM) X, Y, Z
  ...
  X = Y + Z
  ...
END

The USE statement allows program TOTALS access to both the type ITEM and the extended intrinsic operator + to perform calculations.

The following shows another example:

 ! Module containing original type declarations
 MODULE geometry
 type square
    real side
    integer border
 end type
 type circle
    real radius
    integer border
 end type
 END MODULE

 ! Program renames module types for local use.
 PROGRAM test
 USE GEOMETRY,LSQUARE=>SQUARE,LCIRCLE=>CIRCLE
 ! Now use these types in declarations
 type (LSQUARE) s1,s2
 type (LCIRCLE) c1,c2,c3

The following shows a defined operator in a USE statement:

 USE mymod, OPERATOR(.localop.) => OPERATOR(.moduleop.)