COMMON Statement

The COMMON statement is used to specify the sequence in which the listed variables are allocated space. It allows programs and external subroutines to access the same variables.

Format

COM[MON] [/name/] var1 [, var2 , ...]

Parameter(s)

name	Name (enclosed in /) of the common block where the variables are to be temporarily stored. A maximum of five named COMMON statements may be included in an mvBASIC program. Note that multiple COMMON statements in mvBASIC programs must be contiguous, and cannot be separated by executable statements.
var...	Names of the variables to be shared. var can be a simple variable, file variable, or array variable.

Description

The COMMON statement provides a storage area for the listed variables which is accessible by other programs and by external subroutines. The variables may be defined using different names in separate programs and subroutines, but they must be defined in the same exact order. The COMMON statement must precede any use of the variables that it names during compilation.

Simple variables that have not been declared with a COMMON statement are allocated space as they appear, and array variables are allocated space after simple variables. By using a COMMON statement, the sequence in which they are allocated space is explicitly set, and other programs using the same COMMON area can access the same variables by position. By using COMMON, variables do not have to be supplied in CALL and SUBROUTINE statements, and programs runs more efficiently. COMMON may also be used for programs that have been linked via the CHAIN statement, as long as the I option is used with the RUN command to prevent reinitialization.

NOTE

It is crucial that the number and order of variables which are listed in COMMON statements be consistent between programs and subroutines. It is not necessary, however, that the variables have the same definitions (see second example). Once a COMMON statement is changed, all other subroutines and programs using the same COMMON area need to be recompiled with the same change in COMMON. For that reason it is suggested that if the COMMON area is used, the same variable names be used in programs and subroutines and that the COMMON statement be placed in a library, to be read via an $INCLUDE or $INSERT statement: this way, a change needs to be made only once, although all related programs and subroutines still need to be recompiled.

Arrays may be declared in a COMMON statement, with the same syntax as in a DIMENSION statement. If an array is declared by a COMMON statement, it should not also be declared in a DIMENSION statement, or an error will occur at compile-time.

Examples

If PROGRAM1 contains the line:

COMMON A, B, ADDRESSES(3,3)

and SUBR2 contains:

COMMON X, Y, MATRIX(3,3)

then, if PROGRAM1 calls SUBR2 with the line:

CALL SUBR2

variables A and X will be equivalent, variables B and Y will be equivalent, and elements of the dimensioned arrays ADDRESSES and MATRIX will be equivalent.

Named Common Example

If PROGRAM2 contains the line:

COMMON /FILES/ CUST, INV, ORDERS

and SUBR3 contains:

COMMON /FILES/ FVAR(3)

then, if PROGRAM2 calls SUBR3 with the line:

CALL SUBR3

variables CUST, INV, and ORDERS will be equivalent to the elements of the dimensioned array FVAR, respectively.

NOTE	The state of all variables declared in a named common statement are retained until the user logs off the system.