COMMON Statement Details
 
Syntax
  COMMON [SHARED][/blockname/] variablelist
 
  Argument       Description
 
  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:
 
  Argument   Description
 
  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.'