basic.common Statement/BASIC Program

basic.common

Command basic.common Statement/BASIC Program
Applicable release versions: AP, R83
Category BASIC Program (486)
Description declares data elements to share among different Pick/BASIC modules.

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 abscence 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 Pick/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.
Syntax common {/id/} variable{,variable...} {,array(dimension1{,dimension2})...}
Options
Example
The main program:

common x,y,z(10)
...
call process.it
for i = 1 to 10
print z(i)
next i
...
end

The "process.it" subroutine:

subroutine process.it
common x,y,z(10)
....
for y = 1 to 10
call get.input
next y
...
return

The "get.input" subroutine:

subroutine get.input
common x,y,z(10)
....
input x
z(y)=x
....
return

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:

program get.data
common /mydata/ name,zip
input name
input zip
execute "display.data"
end

program display.data
common /mydata/ name,zip
print name
print zip
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.
Purpose
Related basic.statements
basic.precision
basic.enter
basic.dim
tcl.run
basic.assigned
basic.clear
variables
file.control.block
global.common
basic.performance
basic.call
basic.chain
basic.subroutine
basic.file.variable
named.common
basic.com