The COMMON statement creates or references a common block. Common blocks are useful when there are variables that need to be accessed by several IDL procedures or when the value of a variable within a procedure must be preserved across calls. Once a common block has been defined, any program unit referencing that common block can access variables in the block as though they were local variables. Variables in a common statement have a global scope within procedures defining the same common block. Unlike local variables, variables in common blocks are not destroyed when a procedure is exited.
There are two types of common block statements: definition statements and reference statements. See the Examples section for details.
Note on Common Block Variable Names
Variables in IDL COMMON blocks do not actually have names. Rather, IDL represents COMMON blocks internally as an array of variables, and these variables are referenced by their positional index. Hence, the first variable is at position 0, the second at position 1, and so forth. When you specify a COMMON block declaration in an IDL routine, you specify names to be used for these variables within the scope of that routine.
The first routine in which a COMMON block is defined is remembered by IDL as part of the state of that block. When another routine defines the same COMMON block, it is allowed to omit the variable names. In this case, IDL uses the same names used in the original defining routine. Since good programming practice dictates that the same names be used everywhere, this result usually causes no confusion. However, different routines are allowed to use entirely different names to refer to a given variable. For example, the DIV routine written for Common Block Reference Statements (below) could have been written like this:
PRO DIV2, D
COMMON SHARE2, X, Y, Z
D = X / Y
PRINT, D, X, Y, Z
RETURN
END
In this scenario, the variable referred to by the name E in the MULT routine is referred to by the name X in the DIV2 routine. Similarly, the variable name F is replaced by Y, and the name G is replaced by Z. Only the names by which the variables are called has changed; the underlying variables are the same. While this type of COMMON block reference is legal, it can quickly become confusing, and most programmers use the same names in every case.
Examples
Common Block Definition Statements
The common block definition statement creates a common block with the designated name and places the variables whose names follow into that block. Variables defined in a common block can be referenced by any program unit that declares that common block. The general form of the COMMON block definition statement is as follows:
COMMON Block_Name, Variable1, Variable2, ..., Variablen
The number of variables appearing in the common block cannot change after the common block has been defined. The first program unit (main program, function, or procedure) to define the common block sets the number of included variables; other program units can reference the common block with any number of variables up to the number originally specified. Different program units can give the variables different names, as shown in the example below.
Common blocks share the same space for all procedures. In IDL, common block variables are matched variable to variable, unlike FORTRAN, where storage locations are matched. The third variable in a given IDL common block will always be the same as the third variable in all declarations of the common block regardless of the size, type, or structure of the preceding variables.
Note that common blocks must appear before any of the variables they define are referenced in the procedure.
Variables in common blocks can be of any type and can be used in the same manner as normal variables. Variables appearing as parameters cannot be used in common blocks. There are no restrictions on the number of common blocks used, although each common block uses dynamic memory.
Example
The two procedures in the following example show how variables defined in common blocks are shared.
PRO ADD, A
COMMON SHARE1, X, Y, Z, Q, R
A = X + Y + Z + Q + R
PRINT, X, Y, Z, Q, R, A
RETURN
END
PRO SUB, T
COMMON SHARE1, A, B, C, D
T = A - B - C - D
PRINT, A, B, C, D, T
RETURN
END
The variables X, Y, Z, and Q in the procedure ADD are the same as the variables A, B, C, and D, respectively, in procedure SUB. The variable R in ADD is not used in SUB. If the procedure SUB were to be compiled before the procedure ADD, an error would occur when the COMMON definition in ADD was compiled. This is because SUB has already declared the size of the COMMON block, SHARE1, which cannot be extended.
Common Block Reference Statements
The common block reference statement duplicates the COMMON block and variable names from a previous definition. The COMMON block need only be defined in the first routine to be compiled that references the block.
Example
The two procedures in the following example share the COMMON block SHARE2 and all its variables.
PRO MULT, M
COMMON SHARE2, E, F, G
M = E * F * G
PRINT, M, E, F, G
RETURN
END
PRO DIV, D
COMMON SHARE2
D = E / F
PRINT, D, E, F, G
RETURN
END
The MULT procedure uses a common block definition statement to define the block SHARE2. The DIV procedure then uses a COMMON block reference statement to gain access to all the variables defined in SHARE2. (Note that MULT must be defined before DIV in order for the COMMON block reference to succeed.)
Syntax
COMMON Block_Name, Variable1, ..., Variablen
Version History