COMMON, EQUIVALENCE and BLOCK DATA

Before modules, Fortran shared data between program units through a named block of memory: every unit that declared COMMON /STATS/ COUNT, TOTAL got the same two words, whatever it called them and whatever types it gave them. BLOCK DATA initialised such a block, and EQUIVALENCE made two names share storage inside one unit. All three are still in the language, all three still compile, and the first is the reason so much old code is hard to change. This lesson runs them, breaks one on purpose, and shows what replaces them.

A common block

The program and the subroutine below declare the same block, in the same order, with the same types. The program calls the subroutine twice and prints what the block holds; the third unit is a block data program that gives the block its starting values.

The file common.f:

C A COMMON BLOCK SHARED BY TWO UNITS PROGRAM COMMON_DEMO IMPLICIT NONE COMMON /STATS/ COUNT, TOTAL REAL TOTAL INTEGER COUNT CALL ADD(2.5) CALL ADD(3.5) PRINT 10, COUNT, TOTAL 10 FORMAT('COUNT = ', I3, ' TOTAL = ', F6.1) END SUBROUTINE ADD(X) IMPLICIT NONE COMMON /STATS/ COUNT, TOTAL REAL TOTAL, X INTEGER COUNT COUNT = COUNT + 1 TOTAL = TOTAL + X END BLOCK DATA INIT IMPLICIT NONE COMMON /STATS/ COUNT, TOTAL REAL TOTAL INTEGER COUNT DATA COUNT, TOTAL /0, 0.0/ END

gfortran -Wall -Wextra -std=legacy -ffixed-form common.f -o common
./common

COUNT =   2  TOTAL =   6.0

The block is named STATS and holds an integer and a real, in that order. Each unit declares the layout itself, because COMMON is not a declaration of a type: it is an offset into a region of memory that the linker gives every unit that names it. The name of the variable in one unit need not match the name in another; what must match is the order, the types and the sizes.

BLOCK DATA

DATA may not appear in a main program for a variable in a common block, so the initialisation of such a block lives in a BLOCK DATA program unit. The unit has no executable statements, is compiled and linked with the others, and runs before the program starts. The DATA statement in it is the only one that may set those values.

Without it, the block starts as whatever the loader left in memory, which is zero on a modern system by accident rather than by rule. A block data unit with a complete DATA statement makes the starting values part of the program, and a compiler that supports -finit-local-zero is not a substitute for it.

The order is the contract

Declare the same block in the other order in one unit and nothing complains. The program below keeps the same subroutine and swaps the two names in its own declaration, so the real total overlays the integer count and the other way round:

The file mismatch.f:

C THE SAME BLOCK, DECLARED IN THE OTHER ORDER PROGRAM MISMATCH IMPLICIT NONE COMMON /STATS/ TOTAL, COUNT REAL TOTAL INTEGER COUNT COUNT = 0 TOTAL = 0.0 CALL ADD(2.5) CALL ADD(3.5) PRINT 10, COUNT, TOTAL 10 FORMAT('COUNT = ', I3, ' TOTAL = ', F10.1) END SUBROUTINE ADD(X) IMPLICIT NONE COMMON /STATS/ COUNT, TOTAL REAL TOTAL, X INTEGER COUNT COUNT = COUNT + 1 TOTAL = TOTAL + X END

gfortran -Wall -Wextra -std=legacy -ffixed-form mismatch.f -o mismatch
./mismatch

COUNT = ***  TOTAL =       0.0

The subroutine increments the first word, which the program reads as a real and finds to be a denormal too small to print, and accumulates into the second, which the program reads as an integer and finds to be a bit pattern that does not fit in three columns: the stars are Fortran's way of saying that, and the status is still 0. There is no error, no warning and no type check across units, because the compiler compiles each unit alone and COMMON tells it nothing about the others. That is the whole danger of the feature, and the reason a project that still has common blocks keeps a table of their layouts.

EQUIVALENCE

EQUIVALENCE does the same thing inside one unit: two names share the same storage. Old code used it to save memory and to look at one value as another type, which is how a program printed the bits of a real before TRANSFER existed.

The file equiv.f:

C EQUIVALENCE AND THE BITS OF A REAL PROGRAM EQUIV_DEMO IMPLICIT NONE REAL WORD(2) INTEGER BITS EQUIVALENCE (WORD(1), BITS) WORD(1) = 1.0 WORD(2) = 2.0 PRINT 10, BITS 10 FORMAT('BITS OF 1.0 = ', Z8.8) PRINT 20, WORD(1), BITS 20 FORMAT('WORD(1) = ', F5.1, ' BITS = ', Z8.8) END

gfortran -Wall -Wextra -std=legacy -ffixed-form equiv.f -o equiv
./equiv

BITS OF 1.0 = 3F800000
WORD(1) =   1.0  BITS = 3F800000

3F800000 is the IEEE single-precision representation of one, the number lesson 011 wrote out. The two names are the same four bytes: writing the real changes the integer, and a reader who does not know the EQUIVALENCE statement sees an integer that changes by itself.

The storage is also a trap for the optimiser. A compiler that is told two names share memory must reload one after a write to the other, and the rules that let it do otherwise are the ones EQUIVALENCE relaxes only in the ways the standard allows. Code that stores a real in one component and reads it as an integer in the next is undefined unless the types are the same size and the compiler agrees, which is exactly the kind of assumption a modern program should not make.

The modern replacements

Both features have a replacement that the standard defines and the compiler can check. A module with SAVE replaces a common block, and TRANSFER replaces the type punning of EQUIVALENCE. The program below is the second half of equiv.f in free form, with no legacy flag:

The file transfer.f90:

program transfer_demo implicit none real :: x integer :: bits x = 1.0 bits = transfer(x, bits) print '(a,z8.8)', 'BITS OF 1.0 = ', bits end program transfer_demo

gfortran -Wall -Wextra -std=f2018 transfer.f90 -o transfer
./transfer

BITS OF 1.0 = 3F800000

The same digits from a statement that says what it does. TRANSFER copies the bits of its first argument into a variable of the type of its second and returns that value, so it needs no shared storage, works on a copy, and cannot be broken by a declaration elsewhere in the file. The module that replaces the common block is the subject of lesson 068 and of the porting lesson at the end of this part.

Rules for old storage

When reading code with COMMON, write down every block with its order, its types and every unit that declares it; that table is the interface the compiler does not have. Check every EQUIVALENCE for a size mismatch, which is the one case the standard forbids, and replace the harmless ones with TRANSFER as you touch them. Do not add a variable to the middle of a common block in a program that other files still declare: append it at the end, or replace the block with a module and change every user in one commit.

Exercises

  1. Add a third variable to the end of the block in all three units of common.f and print it. What does the block data unit need?
  2. Add the variable in the middle of only the subroutine's declaration. What does the program print, and where does the wrong value come from?
  3. Delete the BLOCK DATA unit and run common.f again. What are the starting values on this machine, and why is the answer not guaranteed?
  4. Write the equiv.f program with TRANSFER and a module instead of the two storage statements. Which lines disappear?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does a COMMON statement share?

    Answer

    A named region of memory that every unit declaring it can use

    The block has no type of its own.

  2. What must match between two units that declare the same block?

    Answer

    The order, the types and the sizes

    The names may differ; the layout may not.

  3. What happens when the order differs?

    Answer

    The program compiles and prints nonsense, with no warning

    Each unit is compiled alone.

  4. What is BLOCK DATA for?

    Answer

    Initialising a common block

    DATA may not do it in a main program.

  5. What do the stars in COUNT = *** mean?

    Answer

    The value does not fit the field width

    The bit pattern read as an integer is far too large.

  6. What does EQUIVALENCE do?

    Answer

    Makes two names share storage in one unit

    COMMON is the one that crosses units.

  7. What is 3F800000 the bits of?

    Answer

    The single-precision real 1.0

    It appears in both programs.

  8. Which statement replaces the type punning of EQUIVALENCE?

    Answer

    TRANSFER

    It copies bits into a value of another type.

  9. What replaces a common block in modern Fortran?

    Answer

    A module with a saved variable

    The module is compiled with its users, so it can be checked.

  10. Where may a new variable be added to a common block other files still declare?

    Answer

    At the end, in every unit

    The order is the contract.

The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image