COMMON Statement Details

Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Syntax► ◄Details► ◄Example► ◄Contents► ◄Index► ◄Back► ────────────────────────────────────────────────────────────────────────────── COMMON defines global variables for sharing between modules or for chaining to another program. COMMON [SHARED][/blockname/] variablelist ■ 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]]... variable Any valid BASIC variable name. AS type Declares the type of the variable. The type may be INTEGER, LONG, SINGLE, DOUBLE, STRING (for variable-length strings), STRING * length (for fixed-length strings), CURRENCY, or a user-defined type. 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: COMMON ║ DEFtype ║ OPTION BASE ║ STATIC CONST ║ DIM (for static ║ REM ║ TYPE...END TYPE DATA ║ arrays) ║ SHARED ║ All metacommands DECLARE ║ ║ ║ ■ 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).