common statement

Syntax

common {/ID/} var{,var...} {,array(dimension1{,dimension2})...}

Synonym(s)

com

Description

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

common variables (including dimensioned arrays) are allocated in the order they are declared.

Dimensioned arrays can 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 cannot be redimensioned with a dim statement.

The common statement can be used to share variables between programs and other programs or subroutines. It can also be used in FlashBASIC or 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 but 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 can 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 (that is, 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 that can 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, because the data is already accessible through the common allocations. Violation of these rules can result in unpredictable values being passed between the programs.

On D3, it is necessary to follow the com abbreviation with a space.

Example(s)

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.

See also

assigned() function, call statement, $chain statement, clear statement, enter statement, File control block, File variable, Global Common, Named common, Compiling programs, precision statement, run command, Statements and functions, subroutine statement, Variables