June 15, 1992
Symbol tables are storage structures used to associate multiple values
with one variable name called a symbol. This storage structure
consists of three arrays. The first array, called the name table,
contains the names of the symbols. The second array, called the
pointer table, contains the pointers which associate the symbol name
with its values. The third array, called the value table, contains
values associated with the symbol names in the name table.
As implemented in SPICELIB, there are three types of symbol tables: character, double precision, and integer. While the symbol names are always character strings, the type of the symbol table is determined by the data type of the values. For example, an integer symbol table has integer values associated with its symbol names.
This is an illustration of how the contents of a symbol table are
represented in the SPICELIB documentation. This symbol table is a
double precision symbol table.
symbol name associated values -------------- ----------------- BODY4_GM --> 4.282628654899D4 BODY4_POLE_DEC --> 5.2886D1 -6.1D-2 0.0D0 BODY4_POLE_RA --> 3.17681D2 -1.08D-1 0.0D0This symbol table contains three symbols. One of the symbols, BODY4 GM, points to a single value. The other two symbols each point to three values.
The primary use of symbol tables is to implement associative arrays:
that is, arrays which are indexed by character strings rather than by
indices. For example, you may wish to store the masses for several
planets and satellites, without knowing ahead of time which ones you
will be using. You might use a double precision symbol table for this,
storing the mass of Jupiter as element `JUPITER', the mass of Europa
as element `EUROPA', and so on.
The fact that more than one value may be stored under a single name (symbol) allows you to store polynomials, vectors, matrices, or any set of associated values under one name. Examples from the SPICELIB kernel pool include: three axes for one body under the name `BODYxxx AXES'; polynomials for the right ascension and declination of the pole of a body (three terms each) under the name `BODYxxx POLE RA' and `BODYxxx POLE DEC'. Other examples might be to list the names of active satellites under the name of the parent planet; to list one or more vidicom matrices under the name `K-MATRIX'; and to store scalar, vector, and matrix values in a simulated desk calculator.
In short, any time you need to store something and look it up later, you can use symbol tables. The advantages come into play mostly when the things to be stored are not known until run-time, or when a program is undergoing development and the things to be stored are subject to rapid change.
The names of the symbol table subroutines in SPICELIB are assigned as
follows. Each name is of the form SYfffx.
Symbol tables are implemented using cells, another SPICELIB data
structure. Hence, the restrictions that apply to cells also apply to
symbol tables. The size and cardinality of the components of a symbol
table must be initialized before the symbol table can be used
properly. The cell routines SSIZEx should be used for this
initialization. Consult the Required Reading for the family of cell
routines if you are not familiar with their use.
Before using the symbol tables, you must initialize the name table, pointer table, and value table. This initialization sets the size and cardinality of the component tables.
The size of the name table must equal the size of the pointer table. In other words, both must contain the same number of elements. Also, the size of the value table should be large enough to accommodate the maximum number of values anticipated. If the size of any of the component tables of a symbol table is too small, it is treated as an error by the symbol table routines.
The cardinality of the component tables should be set to zero before using a symbol table.
The following piece of code demonstrates the easiest way to initialize a symbol table. Using the cell routines SSIZEx to create a symbol table containing up to thirty symbols and up to one hundred-fifty values, the initialization looks like this:
Initialize the name table:
CALL SSIZEC ( 30, TABSYM )Initialize the pointer table:
CALL SSIZEI ( 30, TABPTR )Initialize the value table:
CALL SSIZEC ( 150, TABVAL )The name table always contains character values and is initialized with SSIZEC. Likewise, the pointer table always contains integer values and is thus initialized with SSIZEI. The initialization of the value table is different for each of the types of symbol tables. In the example above the routine SSIZEC was used to initialize the value table for a character symbol table. A double precision value table should be initialized using SSIZED, and an integer values table should be initialized using SSIZEI.
The following examples illustrate how each symbol table routine is
used. The first five examples illustrate how to create a symbol,
delete a symbol, duplicate a symbol, rename a symbol, and fetch the
name of a symbol. The next four examples demonstrate how to add a
value, delete a value, obtain the values, and reorder the values
associated with an existing symbol. The final example illustrates how
to determine the number of values associated with a symbol.
Suppose that you want to create a symbol table of famous scientists
and their fields of study. First, you must create a symbol and give it
one or more associated values. SET and PUT create symbols. If you want
to create a symbol with one value, use the SET routine. Otherwise, use
the PUT routine. The routine used depends on the initial number of
values associated with the symbol. The call below demonstrates how to
create the symbol `EINSTEIN' with the associated value `BROWNIAN
MOTION'. Because this symbol has one value, the SET routine should be
used.
The call,
CALL SYSETC ( 'EINSTEIN', 'BROWNIAN MOTION', TABSYM, TABPTR, TABVAL )creates the symbol table:
EINSTEIN --> BROWNIAN MOTIONTo create a symbol giving it more than one value, use the PUT routine.
If the VALUES array contains the elements,
ELECTRIC CHARGE PHOTOELECTRIC EFFECTN is 2 (the number of elements in the VALUES array), and the symbol you want to create is named `MILLIKAN', the call,
CALL SYPUTC ( 'MILLIKAN', VALUES, N, TABSYM, TABPTR, TABVAL )creates a new symbol in the symbol table. The symbol table now looks like this:
EINSTEIN --> BROWNIAN MOTION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECTImagine now that the symbol table has several symbols.
BARDEEN --> TRANSISTOR EFFECT SUPERCONDUCTIVITY EINSTEIN --> BROWNIAN MOTION HAHN --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT PLANCK --> ELEMENTARY QUANTA
The routine DEL deletes a symbol from the symbol table.
The call,
CALL SYDELC ( 'PLANCK', TABSYM, TABPTR, TABVAL )deletes the scientist PLANCK from the table. The symbol table now looks like this:
BARDEEN --> TRANSISTOR EFFECT SUPERCONDUCTIVITY EINSTEIN --> BROWNIAN MOTION HAHN --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT
Perhaps after doing some research, you find that the scientist
STRASSMAN also worked on NUCLEAR FISSION. You'd like to add him to the
symbol table. Well, you can do this in two ways. You could create a
symbol `STRASSMAN', or you could duplicate the symbol `HAHN' and give
it the name `STRASSMAN' since their associated values are the same.
The routine DUP duplicates a symbol.
Using the DUP routine,
CALL SYDUPC ( 'HAHN', 'STRASSMAN', TABSYM, TABPTR, TABVAL )changes the symbol table contents to:
BARDEEN --> TRANSISTOR EFFECT SUPERCONDUCTIVITY EINSTEIN --> BROWNIAN MOTION HAHN --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT STRASSMAN --> NUCLEAR FISSIONThe same results could have been achieved using the SET routine to create a symbol with one associated value, or the PUT routine if the symbol you wanted to create had more than one associated value. The call for creating the symbol `STRASSMAN' with the value `NUCLEAR FISSION' would look like this:
CALL SYSETC ( 'STRASSMAN', 'NUCLEAR FISSION', TABSYM, TABPRT, TABVAL )
The routine REN exists for renaming a symbol.
Using the REN routine,
CALL SYRENC ( 'HAHN', 'FERMI', TABSYM, TABPTR, TABVAL )the symbol `HAHN' is renamed to `FERMI'.
The symbol table now looks like this:
BARDEEN --> TRANSISTOR EFFECT SUPERCONDUCTIVITY EINSTEIN --> BROWNIAN MOTION FERMI --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT STRASSMAN --> NUCLEAR FISSION
The routine FET allows you to obtain the name of a particular symbol
in the symbol table. Perhaps you want to know the names of the first
four symbols in the symbol table. (Note that the FET routine does not
modify the contents of the symbol table.)
The following code will `fetch' and write to the screen the names of the first four symbols in the symbol table.
DO I = 1, 4 CALL SYFETC ( I, TABSYM, TABPTR, TABVAL, NAME, FOUND ) WRITE (6,*) NAME END DO
Suppose that you want to add a value to a symbol. This can be done by
either `pushing' or `enqueueing' a value onto the symbol. Pushing a
value onto a symbol means that the value becomes the first value
associated with the symbol. Enqueueing the value onto the symbol means
that the value becomes the last value associated with the symbol. The
routines PSH or ENQ are used to add a value to the values already
associated with a symbol.
If the call is,
CALL SYPSHC ( 'EINSTEIN', 'GENERAL RELATIVITY', TABSYM, TABPTR, TABVAL )the contents of the symbol table are now:
BARDEEN --> TRANSISTOR EFFECT SUPERCONDUCTIVITY EINSTEIN --> GENERAL RELATIVITY BROWNIAN MOTION FERMI --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT STRASSMAN --> NUCLEAR FISSIONLet the next call be:
CALL SYENQC ( 'EINSTEIN', 'PHOTOELECTRIC EFFECT', TABSYM, TABPTR, TABVAL )The contents of the symbol table are modified to be:
BARDEEN --> TRANSISTOR EFFECT SUPERCONDUCTIVITY EINSTEIN --> GENERAL RELATIVITY BROWNIAN MOTION PHOTOELECTRIC EFFECT FERMI --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT STRASSMAN --> NUCLEAR FISSION
The only value that can be deleted is the first value associated with
a symbol. The first value associated with the symbol is deleted using
the POP routine. The call below demonstrates how to `pop' a value
associated with the symbol `BARDEEN'.
The call,
CALL SYPOPC ( 'BARDEEN', TABSYM, TABPTR, TABVAL, VALUE, FOUND )results in the symbol table:
BARDEEN --> SUPERCONDUCTIVITY EINSTEIN --> GENERAL RELATIVITY BROWNIAN MOTION PHOTOELECTRIC EFFECT FERMI --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT STRASSMAN --> NUCLEAR FISSIONIf there are no remaining values associated with the symbol after VALUE has been popped, the symbol is removed from the symbol table.
Some symbol table routines exist to obtain values associated with a
particular symbol. All of the values can be obtained, a subset of the
values, or just a particular value associated with a symbol. The
routines to do this are GET, SEL, and NTH respectively. These routines
do not modify the symbol tables. To obtain all the values associated
with the symbol `EINSTEIN' use the GET routine.
Calling the GET routine,
CALL SYGETC ( 'EINSTEIN', TABSYM, TABPTR, TABVAL, N, VALUES, FOUND )returns the following information about the symbol:
N 3 VALUES GENERAL RELATIVITY BROWNIAN MOTION PHOTOELECTRIC EFFECT FOUND TRUE
Two routines exist for reordering the values associated with a symbol.
The routine ORD will order the values in increasing order from the
first value to the last. Character values are ordered according to the
ASCII collating sequence. The second routine, TRN, transposes two
values associated with a symbol.
Calling the ORD routine to order the values associated with the symbol `EINSTEIN',
CALL SYORDC ( 'EINSTEIN', TABSYM, TABPTR, TABVAL )the contents of the symbol table are modified to be:
BARDEEN --> SUPERCONDUCTIVITY EINSTEIN --> BROWNIAN MOTION GENERAL RELATIVITY PHOTOELECTRIC EFFECT FERMI --> NUCLEAR FISSION MILLIKAN --> ELECTRIC CHARGE PHOTOELECTRIC EFFECT STRASSMAN --> NUCLEAR FISSIONIn order to transpose the first and second value associated with the symbol `MILLIKAN', use the TRN routine.
The call,
CALL SYTRNC ( 'MILLIKAN', 1, 2, TABSYM, TABPTR, TABVAL )Changes the symbol table to look like this:
BARDEEN --> SUPERCONDUCTIVITY EINSTEIN --> BROWNIAN MOTION GENERAL RELATIVITY PHOTOELECTRIC EFFECT FERMI --> NUCLEAR FISSION MILLIKAN --> PHOTOELECTRIC EFFECT ELECTRIC CHARGE STRASSMAN --> NUCLEAR FISSION
The integer function DIM exists for determining how many values are
associated with a symbol. (Note that the DIM function does not modify
the symbol table.)
The code,
NUMSUB = SYDIMC ( 'EINSTEIN', TABSYM, TABPTR, TABVAL )returns the value of 3 for NUMSUB.
The following is a list of the three letter mnemonics and their
related functions.
The following is a list of the calling sequences of the generic symbol
table routines in SPICELIB.
Subroutines:
SYDELx ( NAME, TABSYM, TABPTR, TABVAL ) SYDUPx ( NAME, COPY, TABSYM, TABPTR, TABVAL ) SYENQx ( NAME, VALUE, TABSYM, TABPTR, TABVAL ) SYFETx ( NTH, TABSYM, TABPTR, TABVAL, NAME, FOUND ) SYGETx ( NAME, TABSYM, TABPTR, TABVAL, N, VALUES, FOUND ) SYNTHx ( NAME, NTH, TABSYM, TABPTR, TABVAL, VALUE, FOUND ) SYORDx ( NAME, TABSYM, TABPTR, TABVAL ) SYPOPx ( NAME, TABSYM, TABPTR, TABVAL, VALUE, FOUND ) SYPSHx ( NAME, VALUE, TABSYM, TABPTR, TABVAL ) SYPUTx ( NAME, VALUES, N, TABSYM, TABPTR, TABVAL ) SYRENx ( OLD, NEW, TABSYM, TABPTR, TABVAL ) SYSELx ( NAME, BEGIN, END, TABSYM, TABPTR, TABVAL, VALUES, FOUND ) SYSETx ( NAME, VALUE, TABSYM, TABPTR, TABVAL ) SYTRNx ( NAME, I, J, TABSYM, TABPTR, TABVAL )Functions:
SYDIMx ( NAME, TABSYM, TABPTR, TABVAL )