MAINSAIL Language Manual, Section 36.18

previous   next   top   contents   index   framed top   this page unframed

36.18. The Global Symbol Table PROCEDUREs

MAINSAIL supports a method of establishing dynamic records that are visible to every MODULE in the current execution. The records are established using a STRING key. A key should be chosen to be unique; it should be long and descriptive, including at least the name of the program or system using it.

36.18.1. General Global Symbol PROCEDUREs

Each record established by a user program is prefixed by the CLASS $globalSymbol:

CLASS $globalSymbol (STRING $key);

The PROCEDUREs shown in Figure 36–15 are used to manipulate the global symbol table. $globalLookup returns the record with $key equal to key, or NULLPOINTER if no such record exists. $globalEnter enters the record pointed to by p into the global symbol table. The effect is undefined if p.$key is the key of a record already in the global symbol table; call $globalLookup before entering p to ensure that p's key is unique. $globalRemove removes and returns the record with $key equal to key; if no such record exists, it returns NULLPOINTER. $globalNext allows a program to iterate through the global symbol table. It returns the next global symbol in the global symbol table after p. If p is NULLPOINTER, it returns the first global symbol in the table. If p is the last symbol in the table, it returns NULLPOINTER. The order in which the $globalSymbol records are returned is not specified.

Keys are case-sensitive. The key abc is not considered the same as ABC.

The symbol table manipulated by the global symbol table PROCEDUREs is not related to the compiler global symbol table in which entries are made by the directive $GLOBALREDEFINE.

Figure 36–15. Global Symbol Table PROCEDUREs
POINTER($globalSymbol)
PROCEDURE   $globalLookUp
                        (STRING key);

PROCEDURE   $globalEnter
                        (POINTER($globalSymbol) p);

POINTER($globalSymbol)
PROCEDURE   $globalRemove
                        (STRING key);

POINTER($globalSymbol)
PROCEDURE   $globalNext (POINTER($globalSymbol) p);

36.18.2. Sample Use of Global Symbol PROCEDUREs

Suppose a MODULE M has a large number of data sections that wish to share some data with the key:

"M: shared data"

In the INITIAL PROCEDURE of M, declare:

CLASS($globalSymbol) mSharedData (... extra fields...);
POINTER(mSharedData) p;

If the first data section of M is to establish the field values, and all subsequent data sections to use those values, the code would look something like:

IF NOT p := $globalLookup("M: shared data") THENB
    p := new(mSharedData); p.$key := "M: shared data";
    ... set other fields of p...
    $globalEnter(p) END;
... use fields of p...

$SHARED variables or interface fields of a bound data section provide a more efficient (but sometimes less convenient) repository for data shared among many MODULE instances.

36.18.3. STRING Global Symbols

A special CLASS, $stringGlobalSymbol, is declared for the commonly used case of STRING-valued global symbols. Two PROCEDUREs specifically manipulate records of this CLASS, as shown in Figure 36–16.

Figure 36–16. STRING Global Symbol Table PROCEDUREs and the CLASS $stringGlobalSymbol
CLASS($globalSymbol) $stringGlobalSymbol (
    STRING $value;
);

STRING
PROCEDURE   $stringGlobalLookUp
                        (STRING key);

PROCEDURE   $stringGlobalEnter
                        (STRING key,value);

$stringGlobalLookUp and $stringGlobalEnter look up and enter records of the CLASS $stringGlobalSymbol, which has a single STRING value in the global symbol record. $stringGlobalLookUp verifies that key is the key for a record of the CLASS $stringGlobalSymbol, and issues an error message if it is a key for a record of some other CLASS. It returns the null STRING (without issuing an error message) if no record with that key is found. $stringGlobalEnter enters a $stringGlobalSymbol record with $key equal to key and $value equal to value.

There are MAINEX subcommands that set and examine STRING-valued global symbols. This makes it easy to establish program parameters in a bootstrap file, a v1620.prm file in your current or home directory, or in the site.cmd file on the MAINSAIL directory (this file of MAINEX subcommands is always read when MAINSAIL starts execution). For more information on creating and manipulating $stringGlobalSymbol records from MAINEX, see Section 21.2.21 of the MAINSAIL Utilities User's Guide.

previous   next   top   contents   index   framed top   this page unframed

MAINSAIL Language Manual, Section 36.18