common Statement

The common statement declares data elements to share among different FlashBASIC or BASIC modules.

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.

WARNING

It is possible that a program can open a file, store the file variable in common, and delete the file. Another module could still have access to that file variable which now points to invalid space. Using this invalid file variable could have damaging results. A warning message displays in this case.

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, Performance Tips, precision Statement, run Command, Statements and Functions, subroutine Statement, Variables