COMMON Statement

Shares values between program modules.

Syntax

COM{MON} {/common-name/} variable{, variable}...

Syntax Elements

common-name The identifier of a named common section. If omitted, the local common section is used.

variable The identifier to be used for the common variable.

An array specified in a COMMON statement must not be declared in a DIMENSION statement.

Operation

COMMON Variables

The names used for common variables are local to the module (program or subroutine) that declares them - the same common variables can be referred to by different names in different modules. Common variables are allocated space in the appropriate storage area in the order in which they are declared. For example, the following shows how two different modules might refer to the same common variables.

Note that, although it is possible for different modules to use different names for the same common variables (as above), this is not recommended. It is best to place common variable declarations in an item that is included in every module (using the INCLUDE statement).

Currently, simple variables can be matched up with parts of dimensioned arrays and vice versa; however, future support for this is not guaranteed and it is recommended that you do not use them in this way.

Arrays

Arrays included in a COMMON statement are specified by declaring the dimensions (in parentheses) immediately following the array name. An array specified in a COMMON statement must not be declared in a DIMENSION statement.

When dimensioning common arrays, the same restrictions apply as for the DIMENSION statement.

Using COMMON Variables

Use of the COMMON statement in main programs and external subroutines is recommended, because it is more efficient than passing values in argument lists.

The COMMON statement can be used to pass variables among cataloged programs and among uncataloged programs. One cataloged program can use the ENTER statement to enter another cataloged program: COMMON variables are automatically passed. One uncataloged program can exit to another uncataloged program by means of the CHAIN statement, but the CHAIN statement must specify the RUN command with the I option to inhibit reinitialization of the COMMON variables.

Named COMMON Sections

COMMON sections may be either local or named. A local common section is shared between just a particular DataBasic program and its subroutines (including those started with ENTER and CHAIN). In contrast, named common sections, once initiated, persist for the duration of a logon session and are accessible from all perform levels. They have the following advantages over the local common section:

• Several routines can keep data in a named common block.

• Data may be shared easily and conveniently between program levels.

• Data is not lost when the program ends.

There is one disadvantage - named common variables are only normally released when you log off. This means that the space remains in use and any open files remain open and possibly locked. However, an administrator can manually clear a named common section with the NC.RESET command.

Named common sections are essential for sharing data between RealWeb subroutines and between Embedded Basic routines.

Example 1

COMMON A, B, C(10)
COMMON X, Y, Z(10)

These statements, contained in different programs, cause the variables A and X, B and Y, and the arrays C and Z to share the same locations.

Example 2

COMMON /SHARE/ A, B, C(10)
COMMON /SHARE/ X, Y, Z(10)

This example is the same as Example 1, but uses the named common section called SHARE.

Example 3

COMMON A,B(3)
A=2
FOR I = 1 TO 3
    B(I)=I*I
NEXT I
CHAIN "RUN BP PGM2 (I)"
END

COMMON X,Y(3)
FOR I = 1 TO 3
    PRINT X,X*Y(I)
NEXT I
END

The first program declares variables A and B to be COMMON variables, and dimensions array B to three elements. The CHAIN statement exits to execute PGM2 without reinitialization.

The second program associates X and Y to A and B above and dimensions Y as an array with three elements.

A = 2
B(1) = 1*1 = 1
B(2) = 2*2 = 4
B(1) = 3*3 = 9

X = A = 2
X*Y(1) = 2*1 = 2
X*Y(2) = 2*4 = 8
X*Y(3) = 2*9 = 18

2
2
2

2
8
18

Example 4

COMMON /SHARE/ A,B(3)
A=2
FOR I = 1 TO 3
    B(I)=I*I
NEXT I
CHAIN "RUN BP PGM2"
END

COMMON /SHARE/ X,Y(3)
FOR I = 1 TO 3
    PRINT X,X*Y(I)
NEXT I
END

This example is the same as Example 3, but uses the named common section called SHARE instead of specifying that the local common section should not be reinitialised. The result is the same as for Example 3.