Index Page
Symbol Tables

Table of Contents 


   Symbol Tables
      Abstract
      Note on FORTRAN and C Versions
      Revisions
      What are Symbol Tables?
      Illustration of Symbol Table Representation
      Why use Symbol Tables?
      Symbol Subroutine Naming Conventions
      Symbol Table Initialization
      A Comprehensive Example
         Creating a symbol
         Deleting a symbol
         Duplicating a symbol
         Renaming a symbol
         Obtaining the name of a symbol
         Adding a new value to a symbol
         Deleting a value from a symbol
         Obtaining values associated with a symbol
         Reordering the values associated with a symbol
         Determining the dimension of a symbol
      Three Letter Mnemonics used in Subroutine Names
      Calling Sequences


Top

Symbol Tables




Last revised on 2008 JAN 17 by B. V. Semenov.



Top

Abstract



Symbol tables are SPICE data structures used to associate variable names with sets of values.



Top

Note on FORTRAN and C Versions



This document covers the FORTRAN version of the interfaces of this subsystem. CSPICE provides f2c translated equivalents for all, and native C wrappers for some of them. If you wish to use the C versions of the interfaces described in this document, refer to the CSPICE Required Reading, cspice.req, for more information on naming conventions, locations, and usage of the f2c'ed routines and native C wrappers.



Top

Revisions



June 15, 1992

    The document differs from the previous version of December 2, 1989 in that a number of typographical errors were corrected and a paragraph in the section on Symbol Table Initialization was modified to improve its clarity.



Top

What are Symbol Tables?



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.



Top

Illustration of Symbol Table Representation



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.0D0
This 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.



Top

Why use Symbol Tables?



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.



Top

Symbol Subroutine Naming Conventions



The names of the symbol table subroutines in SPICELIB are assigned as follows. Each name is of the form SYfffx.

SY

indicates that the subroutine belongs to the symbol table family of subroutines.
fff

is a three letter mnemonic code indicating the function of the subroutine.
x

indicates the data type of the values associated with the symbols in the name table. The data types are: C for character, D for double precision, and I for integer.
In the descriptive text that follows, the generic routines are referred to by their mnemonic codes, and specific routines are referred to by their full names. For example, the notation DEL refers to the generic routine, DEL, for deleting a symbol. The notation SYDELC refers to the particular routine that deletes a symbol from a character symbol table.



Top

Symbol Table Initialization



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 (cells.req) 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.



Top

A Comprehensive Example



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.



Top

Creating 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 MOTION
To create a symbol giving it more than one value, use the PUT routine.

If the VALUES array contains the elements, 

   ELECTRIC CHARGE
   PHOTOELECTRIC EFFECT
N 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 EFFECT
Imagine 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


Top

Deleting a symbol



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


Top

Duplicating a symbol



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 FISSION
The 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 )


Top

Renaming a symbol



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


Top

Obtaining the name of a symbol



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


Top

Adding a new value to a symbol



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 FISSION
Let 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


Top

Deleting a value from a symbol



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 FISSION
If there are no remaining values associated with the symbol after VALUE has been popped, the symbol is removed from the symbol table.



Top

Obtaining values associated with a symbol



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

the number of values returned
VALUES

an array containing the symbol's values
FOUND

indicates whether or not the symbol was found in the symbol table
The following information is returned for the symbol `EINSTEIN': 

   N        3
 
   VALUES   GENERAL RELATIVITY
            BROWNIAN MOTION
            PHOTOELECTRIC EFFECT
 
   FOUND    TRUE


Top

Reordering the values associated with a symbol



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 FISSION
In 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


Top

Determining the dimension of a symbol



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.



Top

Three Letter Mnemonics used in Subroutine Names



The following is a list of the three letter mnemonics and their related functions.

DEL

delete a symbol
DIM

return the dimension of a symbol (function)
DUP

duplicate a symbol
ENQ

enque a value onto an existing symbol
FET

fetch the name of the Nth symbol
GET

return all of the values associated with a symbol
NTH

return the Nth value associated with a symbol
ORD

order the values associated with a symbol
POP

pop a value associated with a symbol
PSH

push a value onto a symbol
PUT

create a symbol with several associated values
REN

rename an existing symbol
SET

create a symbol with one associated value
SEL

select a subset of values associated with a symbol
TRN

transpose two values associated with a symbol


Top

Calling Sequences



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 )