COMMON

COMMON

Top  Previous  Next

 

The COMMON statement declares variables in a common block.

 

 

Format

 

COMMON {/name/} var1 {,var2...}

 

where

 

nameis the name of the common block

 

var1, etcare variable names

 

 

The COMMON statement is used to define variables as being in common blocks, that is, memory areas that may be used to pass data between different programs and subroutines.

 

The variable names may extend over multiple lines by splitting the statement after a comma. For example

 

COMMON /VARS/ VAR1, VAR2,

             VAR3, VAR4

 

or after the block name

COMMON /VARS/

      VAR1, VAR2,

      VAR3, VAR4

 

The same common block could be defined as

 

COMMON/VARS/ VAR1

COMMON/VARS/ VAR2

COMMON/VARS/ VAR3

COMMON/VARS/ VAR4

 

The compiler assumes that definitions of variables with the same common block name are a continuation of previous definitions in the same block.

 

Common blocks are identified by the name that is used in the COMMON statement. The name of a common block must conform to the same rules as a variable name. Multiple programs in the same process using the same name share the same variables. Named common blocks are created on the first reference to the name and remain in existence until exit from QM. There is also a common block with no name (unnamed common) which may be referred to by a COMMON statement of the form

 

COMMON var1, var2

or

COMMON // var1, var2

 

The unnamed common block is associated with a single command and is discarded on termination of the command that created it. Use of the EXECUTE statement saves and removes any current unnamed common and restores it on completion of the executed command.

 

A common block may contain any number of variables but the number of variables may not be increased by later redefinition. It is valid for a program to define fewer variables than in the original common block declaration. This is useful if a new item has been added at the end of a common block but not all programs have yet been recompiled.

 

Variables within a common block are referenced internally by position, not by name. Thus it would be possible (though not recommended) for different programs to use different names when accessing the same common block. Normally, the structure of a common block is best defined in an include record so that the same definition is used by all parts of the application.

 

By default, the variables in a common block are initialised to integer zero when the block is created. It is thus possible to include QMBasic code to perform further initialisation just once by statements of the form

 

COMMON /MYCOMMON/ INITIALISED,

                 VAR1,

                 VAR2,

                 VAR3,...etc...

IF NOT(INITIALISED) THEN

  ...do initialisation tasks...

  INITIALISED = @TRUE

END

 

For compatibility with some other systems, the UNASSIGNED.COMMON option of the $MODE compiler directive can be used to specify that common blocks are to be created with their component variables left unassigned instead of being set to zero. This directive only affects the program that actually creates the common block (i.e. the first program executed that references the common). It has no effect if the common has already been created. It is possible for an application to mix assigned and unassigned common by careful placement of the $MODE directive.

 

 

Common blocks may contain matrices. These are defined by including the row and column bounds in the COMMON statement, for example

 

COMMON /MYCOMMON/ MAT1(5,3)

 

 

QM supports two styles of matrix with different characteristics. The $MODE compiler directive can be used to select Pick style matrices.

 

The default style of matrix includes a zero element and is resizeable. A common block declared as

COMMON A,B(3),C

has three variables, one of which is a matrix:

common1

 

A matrix of this type in a common block can be re-dimensioned by a later DIM statement.

 

Pick style matrices do not have a zero element and cannot be resized. A matrix of this type in a common block is equivalent to a series of simple variables:

 

common2

 

 

Although not recommended, three programs could use very different views of the same five element common block when using Pick style matrices:

COMMON A,B(3),C

COMMON X(2),Y,Z(2)

COMMON P,Q,R,S,T

 

 

See also:

CLEARCOMMON