Language Reference

COMMON

Purpose

The COMMON statement specifies common blocks and their contents. A common block is a storage area that two or more scoping units can share, allowing them to define and reference the same data and to share storage units.

Format

>>-COMMON--+-----------------------------+--object_list--------->
           '-/--+-------------------+--/-'
                '-common_block_name-'
 
>--+-----------------------------------------------------+-----><
   | .-------------------------------------------------. |
   | V                                                 | |
   '---+---+--/--+-------------------+--/--object_list-+-'
       '-,-'     '-common_block_name-'
 
 

object

>>-variable_name--+--------------------------------+----------->< '-(--explicit_shape_spec_list--)-'

Rules

object cannot refer to a dummy argument, automatic object, allocatable object , an object of a derived type that has an allocatable ultimate component, pointee, function, function result, or entry to a procedure. object cannot have the STATIC or AUTOMATIC attributes.

If an explicit_shape_spec_list is present, variable_name must not have the POINTER attribute. Each dimension bound must be a constant specification expression. This form specifies that variable_name has the DIMENSION attribute.

If object is of derived type, it must be a sequence derived type. Given a sequenced structure where all the ultimate components are nonpointers, and are all of character type or all of type default integer, default real, default complex, default logical or double precision real, the structure is treated as if its components are enumerated directly in the common block.

A pointer object in a common block can only be storage associated with pointers of the same type, type parameters, and rank.

An object in a common block with TARGET attribute can be storage associated with another object. That object must have the TARGET attribute and have the same type and type parameters.

+-------------------------------IBM Extension--------------------------------+

Pointers of type BYTE can be storage associated with pointers of type INTEGER(1) and LOGICAL(1). Integer and logical pointers of the same length can be storage associated if you specify the -qintlog compiler option.

+----------------------------End of IBM Extension----------------------------+

If you specify common_block_name, all variables specified in the object_list that follows are declared to be in that named common block. If you omit common_block_name, all variables that you specify in the object_list that follows are in the blank common block.

Within a scoping unit, a common block name can appear more than once in the same or in different COMMON statements. Each successive appearance of the same common block name continues the common block specified by that name. Common block names are global entities.

The variables in a common block can have different data types. You can mix character and noncharacter data types within the same common block. Variable names in common blocks can appear in only one COMMON statement in a scoping unit, and you cannot duplicate them within the same COMMON statement.

+-------------------------------IBM Extension--------------------------------+

By default, common blocks are shared across threads, and so the use of the COMMON statement is thread-unsafe if any storage unit in the common block needs to be updated by more than one thread, or is updated by one thread and referenced by another. To ensure your application uses COMMON in a thread-safe manner, you must either serialize access to the data using locks, or make certain that the common blocks are local to each thread. The Pthreads library module provides mutexes to allow you to serialize access to the data using locks. See Chapter 17, Pthreads Library Module for more information. The lock_name attribute on the CRITICAL directive also provides the ability to serialize access to data. See CRITICAL / END CRITICAL for more information. The THREADLOCAL and THREADPRIVATE directives ensure that common blocks are local to each thread. See THREADLOCAL and THREADPRIVATE for more information.

+----------------------------End of IBM Extension----------------------------+

Common Association

Within an executable program, all nonzero-sized named common blocks with the same name have the same first storage unit. There can be one blank common block, and all scoping units that refer to nonzero-sized blank common refer to the same first storage unit.

All zero-sized common blocks with the same name are storage-associated with one another. All zero-sized blank common blocks are associated with one another and with the first storage unit of any nonzero-sized blank common blocks. Use association or host association can cause these associated objects to be accessible in the same scoping unit.

Because association is by storage unit, variables in a common block can have different names and types in different scoping units.

Common Block Storage Sequence

Storage units for variables within a common block in a scoping unit are assigned in the order that their names appear within the COMMON statement.

You can extend a common block by using an EQUIVALENCE statement, but only by adding beyond the last entry, not before the first entry. For example, these statements specify X:

      COMMON /X/ A,B      ! common block named X
      REAL C(2)
      EQUIVALENCE (B,C)

The contents of common block X are as follows:

            |    |    |    |    |    |    |    |    |    |    |    |    |
Variable A: |         A         |
Variable B:                     |         B         |
Array C:                        |        C(1)       |       C(2)        |

Only COMMON and EQUIVALENCE statements that appear in a scoping unit contribute to the common block storage sequences formed in that unit, not including variables in common made accessible by use association or host association.

An EQUIVALENCE statement cannot cause the storage sequences of two different common blocks to become associated. While a common block can be declared in the scoping unit of a module, it must not be declared in another scoping unit that accesses entities from the module through use association.

Use of COMMON can lead to misaligned data. Any use of misaligned data can adversely affect the performance of the program.

Size of a Common Block

The size of a common block is equal to the number of bytes of storage needed to hold all the variables in the common block, including any extensions resulting from equivalence association.

Differences Between Named and Blank Common Blocks

• Within an executable program, there can be more than one named common block, but only one blank common block.
• In all scoping units of an executable program, named common blocks of the same name must have the same size, but blank common blocks can have different sizes. (If you specify blank common blocks with different sizes in different scoping units, the length of the longest block becomes the length of the blank common block in the executable program.)
• You can initially define objects in a named common block by using a BLOCK DATA program unit containing a DATA statement or a type declaration statement. You cannot initially define any elements of a common block in a blank common block.

  If a named common block, or any part of it, is initialized in more than one scoping unit, the initial value is undefined. To avoid this problem, use block data program units or modules to initialize named common blocks; each named common block should be initialized in only one block data program unit or modules .

Examples

INTEGER MONTH,DAY,YEAR
COMMON /DATE/ MONTH,DAY,YEAR
REAL          R4
REAL          R8
CHARACTER(1)  C1
COMMON /NOALIGN/ R8,C1,R4     ! R4 will not be aligned on a
                              ! full-word boundary

Related Information

• Chapter 17, Pthreads Library Module
• THREADLOCAL
• Block Data Program Unit
• Explicit-Shape Arrays
• The Scope of a Name, for details on global entities
• Storage Classes for Variables