QMBasic - Common Blocks
Variables are normally available to all statements within a single QMBasic program or subroutine. Although the language provides an internal subroutine call through the GOSUB statement, this does not automatically bring in the concept of the internal subroutine having its own variables or any other aspect of variable scope found in many other languages.
QMBasic extends the language definition by adding the concept of variables that are private to an internal subroutine. This is achieved by use of the LOCAL statement and the associated PRIVATE variable declaration statement. Variables declared in this way are private to the one internal subroutine and cannot be accessed by other parts of the program. Furthermore, they are stacked if the subroutine calls itself, either directly or indirectly via another intermediate subroutine. For more information, see the description of the LOCAL statement.
QMBasic provides common blocks for data which is to be shared between two or more programs in the same QM process. These are declared by a statement of the form
COMMON /name/ var1, var2, var3,...
where name is the name by which the common block is to be known. A common block may contain any number of variables and is created when it is first referenced. It remains in existence until the user leaves QM. Once a common block is created, subsequent programs using the same common block name within the same process access the same data. The number of variables in the common block may not be increased by later definition but programs can define fewer variables than in the actual common block. Normally, the structure of a common block is best defined in an include file so that the same definition is used by all parts of the application.
Where programs use separate COMMON statements to reference the same block, note that the variables are defined by their position in the list, not the names used. Thus it would be valid (but not a good idea) for one program to have
COMMON /MYCOMMON/ A, B, C
and another program
COMMON /MYCOMMON/ D, E, F
where the data stored in B by the first program would be visible to the second program as E.
The name of a common block must conform to the same rules as a variable name. There is also an unnamed common (sometimes known as blank or unlabelled common) which is defined by a COMMON statement without a name:
COMMON A, B, C
This operates in exactly the same way except that each command processor level has its own unnamed common. Thus, an EXECUTE statement used to run one program from within another would result in a new unnamed common block being created for the executed program, the original being restored on return. The unnamed common is discarded on return to the command processor. Thus, running two unrelated programs that use unnamed common one after the other at the same command processor level will not carry the common block from the first program into the second program.
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,
IF NOT(INITIALISED) THEN
do initialisation tasks
INITIALISED = @TRUE
Note how the names of the variables within the common block may extend from one line to the next. The compiler will continue the common block definition over multiple lines wherever the line ends with a comma.
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 the previous definitions.
Common blocks may also contain matrices. These are defined by including the row and column bounds in the COMMON statement, for example
COMMON /MYCOMMON/ MAT1(5,3)
Except when using Pick style matrices, the size of a matrix in common may be changed by a later DIM statement. The size given in the COMMON declaration is the initial size of the matrix.
The matrix in the example above may be made smaller by a statement such as
or made larger by a statement such
It will then keep the changed row and column bounds, within the current program and in any other program that shares the common block, regardless of the row and column bounds specified in the COMMON statement. This allows matrices to be freely shared between programs, with their dimensions being changed as needed.