TITLE:Back-To-Basics: Commons

ISSUE:Multi-value Solutions Oct'98

AUTHOR:Nathan Rector

COMPANY:Natec Systems

EMAIL:nater@northcoast.com

HTTP:www.northcoast.com/~nater/

Syntax

common {/id/} variable{,variable...} {,array(dimension1{,dimension2})...}

Commons declare variables to be shared among different BASIC programs.

The "common" (or "com") statement must appear before any variable. It is used to allocate variables to a common location, so that more than one program may have specified variables in a predetermined sequence.

Common variables (including dimensioned arrays) are allocated in the order they are declared. In the absence of a "common" statement, variables are allocated in an undefined order.

Dimensioned arrays may be declared in a "common" statement by specifying the dimensions enclosed in parentheses. For example, "common a(10)" declares an array with 10 elements. Arrays that are declared in a common statement must be declared with a constant number of elements, and may not be redimensioned with a "dim" statement.

The "common" statement may be used to share variables between programs and other programs or subroutines. It may also be used in BASIC subroutines that are called from attribute-defining items. In this case, the values in the common variables are preserved between calls to the subroutine.

All standard variable types are allowed for common variables as well. The most frequent use of common is to store string or numeric values, but other types, such as file.variables or select variables are equally valid.

The order of variables in "common" statements is critical. The names of the variables are ignored and the order of appearance determines the association. The subroutine being called must have the same number (or less) values in its "common" statement than the main program.

The "/id/" option is used to specify a unique common area called a "named common" area. The "id" parameter must be unique within the program module where it appears. During execution, all program modules that declare named common areas using the same id reference the same variable space regardless of the location of the declaration within the program.

Multiple unique named common areas may be declared within the same program module. Named common space is preserved during an entire logon session.

All declarations of a named common in multiple modules must occupy the same amount of space (i.e., have the same number of variables and arrays, each array having the same number of elements). Multiple levels of a process share a given named common space which may be initialized at any level.

Arguments listed in both the "call" and "subroutine" statements should not be duplicated in the argument lists. Arguments that are also defined as "common" variables in both calling programs and subroutine programs should not be used in argument lists, since the data is already accessible through the common allocations. Violation of these rules can result in unpredictable values being passed between the programs.

Example

The main program:

001 common x,y,z(10)

002 call process.it

003 for i = 1 to 10

004 print z(i)

005 next i

006 end

The "process.it" subroutine:

001 subroutine process.it

002 common x,y,z(10)

003 for y = 1 to 10

004 call get.input

005 next y

006 return

007 end

The "get.input" subroutine:

001 subroutine get.input

002 common x,y,z(10)

003 input x

004 z(y)=x

005 return

006 end

The variables, "x,y,z(10)", are global within a given main program and all of its subroutines. Passing variables in common tends to be more efficient than passing them as subroutine arguments.

Example of named common usage:

001 program get.data

002 common /mydata/ name,zip

003 input name

004 input zip

005 execute "display.data"

006 end

001 program display.data

002 common /mydata/ name,zip

003 print name

004 print zip

005 end

Both modules in this example are main programs. All programs can share information declared in a named common block. The information stored in /mydata/ is valid until the user logs off, making it available to any other applications declaring a named common block of the same id.

TITLE:Back-To-Basics: Commons

ISSUE:Multi-value Solutions Oct'98

AUTHOR:Nathan Rector

COMPANY:Natec Systems

EMAIL:nater@northcoast.com

HTTP:www.northcoast.com/~nater/

Syntax

common {/id/} variable{,variable...} {,array(dimension1{,dimension2})...}

Commons declare variables to be shared among different BASIC programs.

The "common" (or "com") statement must appear before any variable. It is used to allocate variables to a common location, so that more than one program may have specified variables in a predetermined sequence.

Common variables (including dimensioned arrays) are allocated in the order they are declared. In the absence of a "common" statement, variables are allocated in an undefined order.

Dimensioned arrays may be declared in a "common" statement by specifying the dimensions enclosed in parentheses. For example, "common a(10)" declares an array with 10 elements. Arrays that are declared in a common statement must be declared with a constant number of elements, and may not be redimensioned with a "dim" statement.

The "common" statement may be used to share variables between programs and other programs or subroutines. It may also be used in BASIC subroutines that are called from attribute-defining items. In this case, the values in the common variables are preserved between calls to the subroutine.

All standard variable types are allowed for common variables as well. The most frequent use of common is to store string or numeric values, but other types, such as file.variables or select variables are equally valid.

The order of variables in "common" statements is critical. The names of the variables are ignored and the order of appearance determines the association. The subroutine being called must have the same number (or less) values in its "common" statement than the main program.

The "/id/" option is used to specify a unique common area called a "named common" area. The "id" parameter must be unique within the program module where it appears. During execution, all program modules that declare named common areas using the same id reference the same variable space regardless of the location of the declaration within the program.

Multiple unique named common areas may be declared within the same program module. Named common space is preserved during an entire logon session.

All declarations of a named common in multiple modules must occupy the same amount of space (i.e., have the same number of variables and arrays, each array having the same number of elements). Multiple levels of a process share a given named common space which may be initialized at any level.

Arguments listed in both the "call" and "subroutine" statements should not be duplicated in the argument lists. Arguments that are also defined as "common" variables in both calling programs and subroutine programs should not be used in argument lists, since the data is already accessible through the common allocations. Violation of these rules can result in unpredictable values being passed between the programs.

Example

The main program:

001 common x,y,z(10)

002 call process.it

003 for i = 1 to 10

004 print z(i)

005 next i

006 end

The "process.it" subroutine:

001 subroutine process.it

002 common x,y,z(10)

003 for y = 1 to 10

004 call get.input

005 next y

006 return

007 end

The "get.input" subroutine:

001 subroutine get.input

002 common x,y,z(10)

003 input x

004 z(y)=x

005 return

006 end

The variables, "x,y,z(10)", are global within a given main program and all of its subroutines. Passing variables in common tends to be more efficient than passing them as subroutine arguments.

Example of named common usage:

001 program get.data

002 common /mydata/ name,zip

003 input name

004 input zip

005 execute "display.data"

006 end

001 program display.data

002 common /mydata/ name,zip

003 print name

004 print zip

005 end

Both modules in this example are main programs. All programs can share information declared in a named common block. The information stored in /mydata/ is valid until the user logs off, making it available to any other applications declaring a named common block of the same id.