USE

Purpose

The USE statement is a module reference that provides local access to the public entities of a module.

Syntax

Read syntax diagramSkip visual syntax diagram>>-USE--+-----------------------------------+--module_name--+---------------------------+-><
        |                              (1)  |               +-,--rename_list------------+
        '-+----------------------+--::------'               '-,--ONLY--:--+-----------+-'
          '-,--+-INTRINSIC-----+-'                                        '-only_list-'
               '-NON_INTRINSIC-'
 
Notes:
  1. Fortran 2003 Standard

rename
is the assignment of a local name to an accessible data entity: local_name => use_name
only
is a rename, a generic specification, or the name of a variable, procedure, derived type, named constant, or namelist group

Rules

The USE statement can only appear prior to all other statements in specification_part. Multiple USE statements may appear within a scoping unit.

IBM Extension

At the time the file containing the USE statement is being compiled, the specified module must precede the USE statement in the file or the module must have been already compiled in another file. Each referenced entity must be the name of a public entity in the module.

End of IBM Extension

Entities in the scoping unit become use-associated with the module entities, and the local entities have the attributes of the corresponding module entities.

Fortran 2003 Standard

By default, either an intrinsic module or a non-intrinsic module with the specified name is accessed. If both an intrinsic module and a non-intrinsic module have this name, the non-intrinsic module is accessed. If you specify INTRINSIC or NON_INTRINSIC, only an intrinsic module or only a non-intrinsic module can be accessed.

End of Fortran 2003 Standard

In addition to the PRIVATE attribute, the ONLY clause of the USE statement provides further constraint on which module entities can be accessed. If the ONLY clause is specified, only entities named in the only_list are accessible. If no list follows the keyword, no module entities are accessible. If the ONLY clause is absent, all public entities are accessible.

If a scoping unit contains multiple USE statements, all specifying the same module, and one of the statements does not include the ONLY clause, all public entities are accessible. If each USE statement includes the ONLY clause, only those entities named in one or more of the only_lists are accessible.

You can rename an accessible entity for local use. A module entity can be accessed by more than one local name. If no renaming is specified, the name of the use-associated entity becomes the local name. The local name of a use-associated entity cannot be redeclared. However, if the USE statement appears in the scoping unit of a module, the local name can appear in a PUBLIC or PRIVATE statement.

If multiple generic interfaces that are accessible to a scoping unit have the same local name, operator, or assignment, they are treated as a single generic interface. In such a case, one of the generic interfaces can contain an interface body to an accessible procedure with the same name. Otherwise, any two different use-associated entities can only have the same name if the name is not used to refer to an entity in the scoping unit. If a use-associated entity and host entity share the same name, the host entity becomes inaccessible through host association by that name.

The accessed entities have the attributes specified in the module, except that an entity may have a different accessibility attribute or it may have the VOLATILE attribute in the local scoping unit even if the associated module entity does not.

A module must not reference itself, either directly or indirectly. For example, module X cannot reference module Y if module Y references module X.

Consider the situation where a module (for example, module B) has access through use association to the public entities of another module (for example, module A). The accessibility of module B's local entities (which includes those entities that are use-associated with entities from module A) to other program units is determined by the PRIVATE and PUBLIC attributes, or, if absent, through the default accessibility of module B. Of course, other program units can access the public entities of module A directly.

Examples

   MODULE A
     REAL :: X=5.0
   END MODULE A
   MODULE B
     USE A
     PRIVATE :: X               !  X cannot be accessed through module B
     REAL :: C=80, D=50
   END MODULE B
   PROGRAM TEST
     INTEGER :: TX=7
     CALL SUB
     CONTAINS

     SUBROUTINE SUB
     USE B, ONLY : C
     USE B, T1 => C
     USE B, TX => C             !  C is given another local name
     USE A
     PRINT *, TX                !  Value written is 80 because use-associated
                                !  entity overrides host entity
     END SUBROUTINE
   END
Fortran 2003 Standard

The following example is invalid:

Module mod1
    use, intrinsic :: ieee_exceptions
end Module

Module mod2
   use, non_intrinsic :: ieee_exceptions
end Module

Program invalid_example
   use mod1
   use mod2
! ERROR: a scoping unit must not access an
! intrinsic module and a non-intrinsic module
! with the same name.

end program
End of Fortran 2003 Standard

Related information