Top  Previous  Next


The COMMON statement declares variables in a common block.





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




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



             VAR3, VAR4


or after the block name


      VAR1, VAR2,

      VAR3, VAR4


The same common block could be defined as







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


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






IF NOT(INITIALISED) THEN initialisation tasks...




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





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


has three variables, one of which is a matrix:



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:





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


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




See also: