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
- 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?
- 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?
- 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?
- 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.
-
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.
-
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.
-
What happens when the order differs?
Answer
The program compiles and prints nonsense, with no warning
Each unit is compiled alone.
-
What is BLOCK DATA for?
Answer
Initialising a common block
DATA may not do it in a main program.
-
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.
-
What does EQUIVALENCE do?
Answer
Makes two names share storage in one unit
COMMON is the one that crosses units.
-
What is
3F800000the bits of?Answer
The single-precision real 1.0
It appears in both programs.
-
Which statement replaces the type punning of EQUIVALENCE?
Answer
TRANSFER
It copies bits into a value of another type.
-
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.
-
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