Symbol Tables

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 )