Q(uick)BASIC Statement: COMMON

Quick View

COMMON

A non-executable statement that declares global variables for sharing between modules, or for chaining to another program

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

COMMON [SHARED] variablelist

Description/Parameter(s)

SHARED

Indicates that variables are shared with all SUB or FUNCTION procedures.

variablelist

One or more variables to be shared:

variable[( )] [AS type] [, variable[( )] [AS type]]…
variable	A Basic variable name. Variable names can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).
type	The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

Unless it has been declared as a static array in a preceding DIM statement, an array variable in a COMMON statement is a dynamic array. Its dimensions must be set in a later DIM or REDIM statement.

Syntax

COMMON [SHARED][/blockname/] variablelist

Description/Parameter(s)

SHARED	An optional attribute indicating that the variables are to be shared with all SUB or FUNCTION procedures in the module. SHARED can eliminate the need for a SHARED statement inside SUB or FUNCTION procedures.
blockname	A valid BASIC identifier (up to 40 characters) used to identify a group of variables. Use a blockname to share only specific groups of variables. When a blockname is used, the COMMON block is a named COMMON block. When blockname is omitted, the block is a blank COMMON block. Items in a named COMMON block are not preserved across a chain to a new program. See "Using Named COMMON" and "Using COMMON with Chain," below.
variablelist	A list of variables to be shared between modules or chained-to programs. The same variable may not appear in more than one COMMON statement in a module.

A variablelist has the following syntax:

variable[()][AS type][, variable[()][AS type]]…

The following list describes the parts of a variablelist:

variable	Any valid BASIC variable name.
AS type	Declares variable to be of type type. The type may be INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type.

Note:

Older versions of BASIC required the number of dimensions to appear after the name of a dynamic array in a COMMON statement. The number of dimensions is no longer required, although QuickBASIC accepts the older syntax to maintain compatibility with earlier versions.

A COMMON statement establishes storage for variables in a special area that allows them to be shared between modules or with other programs invoked with a CHAIN statement.

Because COMMON statements establish global variables for an entire program, they must appear before any executable statements. All statements are executable, except the following:

COMMON
CONST
DATA
DECLARE
DEFtype
DIM (for static arrays)
OPTION BASE
REM
SHARED
STATIC
TYPE…END TYPE
All metacommands

Variables in COMMON blocks are matched by position and type, not by name. Thus, variable order is significant in COMMON statements. In the following fragment, it is the order of the variables in the COMMON statements that links the variables, not the names:

' Main program.
COMMON A, D, E
A = 5 : D = 8 : E = 10
⋮
' Common statement in another module.
COMMON A, E, D 'A = 5, E = 8, D = 10
⋮

Both static and dynamic arrays are placed in COMMON by using the array name followed by parentheses. A static array must be dimensioned with integer-constant subscripts in a DIM statement preceding the COMMON statement. A dynamic array must be dimensioned in a later DIM or REDIM statement. The elements of a dynamic array are not allocated in the COMMON block. Only an array descriptor is placed in common.

The size of a common area can be different from that in another module or chained program if a blank COMMON block has been used. When a BASIC program shares COMMON blocks with a routine in the user library, the calling program may not redefine the COMMON block to a larger size.

Errors caused by mismatched COMMON statements are subtle and difficult to find. An easy way to avoid mismatched COMMON statements is to place COMMON declarations in a single "include" file and use the $INCLUDE metacommand in each program.

The following program fragment shows how to use the $INCLUDE metacommand to share a file containing COMMON statements among programs:

'This file is menu.bas.
'$INCLUDE:'COMDEF.BI'
⋮
CHAIN "PROG1"
END
'This file is prog1.bas.
'$INCLUDE:'COMDEF.BI'
⋮
END
'This file is comdef.bi.
DIM A(100),B$(200)
COMMON I,J,K,A()
COMMON A$,B$(),X,Y,Z
'End comdef.bi.

The next three sections discuss using named COMMON blocks, using the SHARED keyword, and using COMMON when chaining programs.

Using Named COMMON

A named COMMON block provides a convenient way to group variables so that different modules have access only to the common variables that they need.

The following program fragment, which calculates the volume and density of a rectangular prism, uses named COMMON blocks to share different sets of data with two subprograms. The subprogram VOLUME needs to share only the variables representing the lengths of the sides (in COMMON block SIDES). The subprogram DENSITY also needs variables representing the weight (in COMMON block WEIGHT).

'Main program.
DIM S(3)
COMMON /Sides/ S()
COMMON /Weight/ C
C=52
S(1)=3:S(2)=3:S(3)=6
CALL Volume
CALL Density
END
'Subprogram VOLUME in a separate module.
DIM S(3)
COMMON SHARED /Sides/ S()
SUB Volume STATIC
Vol=S(1)*S(2)*S(3)
⋮
END SUB
'Subprogram DENSITY in a separate module.
DIM S(3)
COMMON SHARED /Sides/ S()
COMMON SHARED /Weight/ W
SUB Density STATIC
Vol=S(1)*S(2)*S(3)
Dens=W/Vol
⋮
END SUB

Note:

Named COMMON blocks are not preserved across chained programs. Use blank COMMON blocks to pass variables to a chained program.

Using COMMON with CHAIN

The COMMON statement provides the only way to pass the values of variables directly to a chained program. To pass variables, both programs must contain COMMON statements. Remember that variable order and type are significant, not variable names. The order and type of variables must be the same for all COMMON statements communicating between chaining programs.

Although the order and type of variables is critical for making sure the right values are passed, the COMMON blocks do not have to be the same size. If the COMMON block in the chained-to program is smaller than the COMMON block in the chaining program, the extra COMMON variables in the chaining program are ignored. If the size of the COMMON block in the chained-to program is larger, then additional COMMON numeric variables are initialized to zero. Additional string variables are initialized to null strings.

Static arrays passed in COMMON by the chaining program must be declared as static in the chained-to program. Similarly, dynamic arrays placed in common by the chaining program must be dynamic in the chained-to program.

Note:

To use COMMON with CHAIN when you are compiling outside the BASIC environment, you must use the BRUN45.EXE module. This module is used when you compile from the command line without the /O option or when you use the option from the Make EXE dialog box called 'EXE Requiring BRUN45.EXE.'

Example

COM1_EX.BAS and COM2_EX.BAS are two program files that illustrate the use of the COMMON statement. They are in the subdirectory ADVR_EX. To look at the program text in the View window and, optionally, to run the programs, load COM1_EX.BAS using the File menu Open Program command. Be sure COM2_EX.BAS is in the current working directory.
The COMMON statement is used to pass variables between two chained programs. The first program reads in a series of numeric values, stores the values in an array, and then chains to the other program. The second program finds and prints the average of the values.

Syntax

COMMON [SHARED][/blockname/] variablelist

Description/Parameter(s)

SHARED indicates that the variables are shared with all SUB or FUNCTION procedures in the module. The SHARED attribute can eliminate the need for a SHARED statement inside SUB or FUNCTION procedures.
The blockname is a valid BASIC identifier (up to 40 characters) that identifies a group of variables. Use blockname to share only specific groups of variables. You cannot use a type-declaration character (%, &, !, #, @, $) in the identifier.
When a blockname is used, the COMMON block is a named COMMON block. When blockname is omitted, the block is a blank COMMON block. Items in a named COMMON block are not preserved across a chain to a new program. See "Using Named COMMON" and "Using COMMON With CHAIN," below.
The variablelist is a list of variables to be shared between modules or chained-to programs. The same variable may not appear in more than one COMMON statement in a module. The syntax of variablelist is:

variable[()] [AS type] [, variable[()] [AS type]]…

COMMON	DEFtype	OPTION BASE	STATIC
CONST	DIM (for static arrays)	REM	TYPE…END TYPE
DATA	DECLARE	SHARED	All metacommands

Usage Notes

Older versions of BASIC required the number of dimensions to appear after the name of a dynamic array in a COMMON statement. The number of dimensions is no longer required, although the current version of BASIC accepts the older syntax to maintain compatibility with earlier versions.
A COMMON statement establishes storage for variables in a special area that allows them to be shared between modules or with other programs invoked with a CHAIN statement.
Because COMMON statements establish global variables for an entire program, they must appear before any executable statements. All statements are executable, except the following:

Variables in COMMON blocks are matched by position and type, not by name. Thus, variable order is significant in COMMON statements. In the following fragment, it is the order of the variables in the COMMON statements that links the variables, not the names:

' Main program.
COMMON a, D, E
a = 5: D = 8: E = 10
⋮
' Common statement in another module.
COMMON a, E, D 'A = 5, E = 8, D = 10
⋮

Both static and dynamic arrays are placed in COMMON by using the array name followed by parentheses. The dimensions for a static array must be set with integer-constant subscripts in a DIM statement preceding the COMMON statement. The dimensions for a dynamic array must be set in a later DIM or REDIM statement. The elements of a dynamic array are not allocated in the COMMON block. Only an array descriptor is placed in common. For more information about static and dynamic arrays, see Appendix B, "Data Types, Constants, Variables, and arrays " in the Programmer's Guide."
The size of a common area can be different from that in another module or chained program if a blank COMMON block has been used. When a BASIC program shares COMMON blocks with a routine in the user library, the calling program may not redefine the COMMON block to a larger size.
Errors caused by mismatched COMMON statements are subtle and difficult to find. An easy way to avoid mismatched COMMON statements is to place COMMON declarations in a single include file and use the $INCLUDE metacommand in each module.
The following program fragment shows how to use the $INCLUDE metacommand to share a file containing COMMON statements among programs:

'This file is menu.bas.
'$INCLUDE: 'comdef.bi'
⋮
CHAIN "PROG1"
END
'This file is prog1.bas.
'$INCLUDE: 'comdef.bi'
⋮
END
'This file is comdef.bi.
DIM a(100), B$(200)
COMMON I, J, K, a()
COMMON a$, B$(), X, Y, Z
'End comdef.bi.

Using Named COMMON

A named COMMON block provides a convenient way to group variables so that different modules have access only to the common variables that they need.
The following program fragment, which calculates the volume and density of a rectangular prism, uses named COMMON blocks to share different sets of data with two SUB procedures. The SUB procedure Volume needs to share only the variables representing the lengths of the sides (in COMMON block Sides). The SUB procedure Density also needs variables representing the weight (in COMMON block Weight).

'Main program.
DIM S(3)
COMMON /Sides/ S()
COMMON /Weight/ C
C = 52
S(1) = 3: S(2) = 3: S(3) = 6
CALL Volume
CALL Density
END
'SUB procedure VOLUME in a separate module.
DIM S(3)
COMMON SHARED /Sides/ S()
SUB Volume STATIC
Vol = S(1) * S(2) * S(3)
⋮
END SUB
'SUB procedure DENSITY in a separate module.
DIM S(3)
COMMON SHARED /Sides/ S()
COMMON SHARED /Weight/ W
SUB Density STATIC
Vol = S(1) * S(2) * S(3)
Dens = W / Vol
⋮
END SUB

Named COMMON blocks are not preserved across chained programs. Use blank COMMON blocks to pass variables to a chained program.

Using COMMON with CHAIN

The COMMON statement provides the only way to pass the values of variables directly to a chained program. To pass variables, both programs must contain COMMON statements. Remember that variable order and type are significant, not variable names. The order and type of variables must be the same for all COMMON statements communicating between chaining programs.
Although the order and type of variables is critical for making sure the right values are passed, the COMMON blocks do not have to be the same size. If the COMMON block in the chained-to program is smaller than the COMMON block in the chaining program, the extra COMMON variables in the chaining program are discarded. If the size of the COMMON block in the chained-to program is larger, then additional COMMON numeric variables are initialized to zero. Additional string variables are initialized to null strings.
Static arrays passed in a COMMON block by the chaining program must be declared as static in the chained-to program. Similarly, dynamic arrays placed in common by the chaining program must be dynamic in the chained-to program.

Important

When you compile a program with the /O option, common variables are not preserved across the chain. To preserve values across a chain, you must compile without the /O option (using BC) or by selecting "EXE Requiring BRT Module" from the "Make EXE File" dialog box (using QBX).

Example

This example uses the COMMON statement to pass variables between two chained programs. It uses the CHAIN statement, in the first program, to load and run a second program which finds and prints the average of the values.
NOTE: After running this example from QBX, you will be left in PROG2.BAS.

'Set up the variables that are passed from PROG1 to PROG2.
DIM values(1 TO 50)
COMMON values(), NumValues%
 
'The following few lines of code creates the second program on the disk
'so that it can load and run with the CHAIN statement. It is, in fact, a
'series of PRINT # statements to put the proper BASIC statements in a file.
 
OPEN "PROG2.BAS" FOR OUTPUT AS #1
PRINT #1, "'This is PROG2 for the CHAIN and COMMON statement examples"
PRINT #1, "DIM X(1 TO 50)"
PRINT #1, "COMMON X(), N%"
PRINT #1, "PRINT"
PRINT #1, "IF N% > 0 THEN"
PRINT #1, "   Sum% = 0"
PRINT #1, "   FOR I% = 1 TO N%"
PRINT #1, "      Sum% = Sum% + X(I%)"
PRINT #1, "   NEXT I%"
PRINT #1, "   PRINT "; CHR$(34); "The average of the values is";
PRINT #1, CHR$(34); "; Sum% / N%"
PRINT #1, "END IF"
PRINT #1, "END"
CLOSE #1
'End of PROG2 creation section.
 
CLS
PRINT "Enter values one per line. Type 'END' to quit."
NumValues% = 0
DO
   INPUT "-> ", N$
   IF I% >= 50 OR UCASE$(N$) = "END" THEN EXIT DO
   NumValues% = NumValues% + 1
   values(NumValues%) = VAL(N$)
LOOP
PRINT "Press any key to continue... "
DO WHILE INKEY$ = ""
LOOP
CHAIN "PROG2.BAS"
END