NAME

common - declare variables as common

SYNOPSIS

common [shared] [ /block/ ] Var[, Var]. . . 

DESCRIPTION

The common statement is used in a variety of contexts to declare variables as shared among subprograms, modules and/or chained programs.  A single common statement may serve any or all of these contexts. 

By default, a variable that appears within a subprogram is different from a variable with the same name and type outside that subprogram.  That is, the scope of the variable does not include the subprogram.  If the word shared is used in the common statement, the scope of a variable so declared includes the subprograms of the module.  Nevertheless, within any particular subprogram, this declaration of the variable may be nullified and the default restored by a static declaration (see static) or by a declaration as a formal parameter. 

Variables named in a module are not available to other modules.  A common statement makes a block of values (called a common block) available among modules.  Block is a word (see The BASIC Language in the introductory section of this manual).  Block identifies the common block.  If block is omitted, the statement refers to a block distinct from all others known as the unlabeled common block. 

In addition, the unlabeled common block is also made available across a chain (see chain).  These are the only variable values available across a chain. 

Var may be a simple variable or a simple or dynamic array.  A simple variable is declared by its identifier.  A simple array is declared by its identifier followed by an empty pair of parentheses.  A dynamic array is declared by its identifier followed by a single parentheses enclosed constant which represents the number of dimensions in the array. 

A common block is composed of the values of the variables declared in the common statements that refer to the common block.  The order of the values in a common block is the same as the order in which the declarations appear.  A variable may appear in a common declaration no more than once. 

Each module that uses a common block requires its own set of common statements.  A variable may be declared by different names in different modules but other attributes of the variable (type, simple variable vs. array, static vs. dynamic array) must be the same.  A common block need not be the same length in all modules that use it.  Variables at the end of a common block that are not used by a module need not be declared. 

Common statements must appear in a module after the dimensioning of any static arrays that are declared in the common statements but before any executable statements.  Note that the dimensioning of a dynamic array is an executable statement.  So the location of the common statements with respect to the statements that dimension the arrays is after those for static and before those for dynamic. 

EXAMPLE

In the program

	dim c(10)
	common a, b, c(), d(1), e$
	redim d(5)
	e$ = "hello"
	chain "prog2"

the variables a, b, e, and the arrays c and d are declared as common so that their values can be passed to the program "prog2" as part of the chaining action in the last line.  If the source for "prog2" looks like

	dim h(10)
	common f, g, h(), i(1), j$
	print j$

then the execution of the first program produces the output

	hello

The following example illustrates the use of the common statement to access data between modules and subprograms.  Suppose we have a main module:

	common /stuff/ x
	x = 0
	call fortytwo
	print x

and the secondary module:

	common shared /stuff/ y
	sub fortytwo static
		y = 42
	end sub

when compiled and loaded together this program will produce the output

	42

SEE ALSO

chain, $include, static

USAGE NOTES

A convenient way to share common areas between programs is to place common declarations and the required dim statements in a separate file.  By using the $include metacommand in the sources of both programs, this file can become part of both programs.  Future changes involving the shared variables need only be made in this separate file and the likelihood of a typographical error in one of the actual source files causing a catastrophe is minimized. 

Because the compiler has no knowledge of modules other than the one it is compiling, the unlabelled common data preserved across a chain is limited to that declared in the main module. 

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber