Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
pool

Table of contents
Procedure
Abstract
Required_Reading
Keywords
Declarations
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version

Procedure

     POOL ( Maintain a pool of kernel variables )

     SUBROUTINE POOL ( FNAME,  UNIT,   NAME,   NAMES,  NNAMES,
    .                  AGENT,  N,      VALUES, FOUND,  UPDATE,
    .                  START,  ROOM,   CVALS,  IVALS,  TYPE,
    .                  UWVARS, UWPTRS, UWPOOL, UWAGNT, USRCTR )

Abstract

     Maintain a pool of variables read from SPICE ASCII kernel files.

Required_Reading

     KERNEL

Keywords

     CONSTANTS
     FILES

Declarations

     IMPLICIT NONE

     INCLUDE              'zzctr.inc'

     INTEGER               MAXVAR
     PARAMETER           ( MAXVAR =  26003 )

     INTEGER               MAXVAL
     PARAMETER           ( MAXVAL = 400000 )

     INTEGER               MAXLIN
     PARAMETER           ( MAXLIN =  15000 )

     INTEGER               MAXCHR
     PARAMETER           ( MAXCHR =     80 )

     INTEGER               MAXLEN
     PARAMETER           ( MAXLEN =     32 )

     INTEGER               MAXAGT
     PARAMETER           ( MAXAGT =   1000 )

     INTEGER               MXNOTE
     PARAMETER           ( MXNOTE =  MAXVAR * 5 )

     INTEGER               LBCELL
     PARAMETER           ( LBCELL = -5 )

     INTEGER               LBPOOL
     PARAMETER           ( LBPOOL = -5 )


     CHARACTER*(*)         FNAME
     INTEGER               UNIT
     CHARACTER*(*)         NAME
     CHARACTER*(*)         NAMES     ( * )
     INTEGER               NNAMES
     CHARACTER*(*)         AGENT
     INTEGER               N
     DOUBLE PRECISION      VALUES    ( * )
     LOGICAL               FOUND
     LOGICAL               UPDATE
     INTEGER               START
     INTEGER               ROOM
     CHARACTER*(*)         CVALS     ( * )
     INTEGER               IVALS     ( * )
     CHARACTER*(*)         TYPE
     CHARACTER*(*)         UWVARS    ( LBCELL : * )
     INTEGER               UWPTRS    ( * )
     INTEGER               UWPOOL    ( 2, LBCELL : * )
     CHARACTER*(*)         UWAGNT    ( * )
     INTEGER               USRCTR    ( CTRSIZ )

Brief_I/O

     VARIABLE  I/O  ENTRY POINTS
     --------  ---  --------------------------------------------------
     FNAME      I   LDPOOL
     UNIT       I   WRPOOL
     NAME       I   RTPOOL, EXPOOL, GIPOOL, GDPOOL, GCPOOL, PCPOOL,
                    PDPOOL, PIPOOL, DTPOOL, SZPOOL, DVPOOL, GNPOOL
     NAMES      I   SWPOOL
     NNAMES     I   SWPOOL
     AGENT      I   CVPOOL, DWPOOL, SWPOOL
     N         I-O  RTPOOL, GIPOOL, GCPOOL, GDPOOL, DTPOOL, PCPOOL,
                    PDPOOL, PIPOOL, LMPOOL, SZPOOL, GNPOOL
     VALUES    I-O  RTPOOL  GDPOOL, PDPOOL
     FOUND      O   RTPOOL, EXPOOL, GIPOOL, GCPOOL, GDPOOL, DTPOOL,
                    SZPOOL, GNPOOL
     UPDATE     O   CVPOOL, ZZPCTRCK
     START      I   GIPOOL, GDPOOL, GCPOOL, GNPOOL
     ROOM       I   GIPOOL, GDPOOL, GCPOOL. GNPOOL
     CVALS     I-O  GCPOOL, PCPOOL, LMPOOL, GNPOOL
     IVALS     I-O  GIPOOL, PIPOOL
     TYPE       O   DTPOOL
     UWVARS     O   ZZVUPOOL
     UWPTRS     O   ZZVUPOOL
     UWPOOL     O   ZZVUPOOL
     UWAGNT     O   ZZVUPOOL
     USRCTR    I-O  ZZPCTRCK

     MAXVAR     P   (All)
     MAXLEN     P   (All)
     MAXVAL     P   (All)
     MAXAGT     P   (All)
     MXNOTE     P   (All)
     BEGDAT     P   WRPOOL
     BEGTXT     P   WRPOOL
     CTRSIZ     P   ZZPCTRCK

Detailed_Input

     See the ENTRY points for a discussion of their arguments.

Detailed_Output

     See the ENTRY points for a discussion of their arguments.

Parameters

     MAXVAR   is the maximum number of variables that the
              kernel pool may contain at any one time.
              MAXVAR should be a prime number.

              Here's a list of primes that should make
              it easy to upgrade MAXVAR when/if the need arises.

                  103
                  199
                  307
                  401
                  503
                  601
                  701
                  751
                  811
                  911
                 1013
                 1213
                 1303
                 1511
                 1811
                 1913
                 2003
                 2203
                 2503
                 2803
                 3203
                 3607
                 4001
                 4507
                 4801
                 5003 Current Value
                 6007
                 6521
                 7001
                 7507
                 8009
                 8501
                 9001
                 9511
                10007
                10501
                11003
                11503


     MAXLEN   is the maximum length of the variable names that
              can be stored in the kernel pool (also set in
              zzrvar.f).

     MAXVAL   is the maximum number of distinct values that
              may belong to the variables in the kernel pool.
              Each variable must have at least one value, and
              may have any number, so long as the total number
              does not exceed MAXVAL. MAXVAL must be at least
              as large as MAXVAR.

     MAXAGT   is the maximum number of agents that can be
              associated with a given kernel variable.

     MAXCHR   is the maximum number of characters that can be
              stored in a component of a string valued kernel
              variable.

     MXNOTE   is the maximum sum of the sizes of the sets of
              agents in the range of the mapping that associates
              with each watched kernel variable a set of agents
              that "watch" that variable.

     MAXLIN   is the maximum number of character strings that
              can be stored as data for kernel pool variables.

     CTRSIZ   is the dimension of the counter array used by
              various SPICE subsystems to uniquely identify
              changes in their states. This parameter is
              defined in the private include file 'zzctr.inc'.

Exceptions

     1)  If POOL is called directly, the error SPICE(BOGUSENTRY) is
         signaled.

Files

     See the ENTRY points for a discussion of their arguments.

Particulars

     POOL should never be called directly, but should instead be
     accessed only through its entry points.

     The purpose of this routine is to maintain a pool of variables
     read from ASCII kernel files. The following entry points may be
     used to access the pool.

           CLPOOL         Clears the pool.

           LDPOOL         Loads the variables from a kernel file into
                          the pool.

           RTPOOL         Returns the value of a variable from
                          the pool. (Obsolete use GDPOOL)

           EXPOOL         Confirms the existence of a numeric
                          variable in the pool.

           WRPOOL         Writes the contents of the pool to an
                          ASCII kernel file.

           SWPOOL         Sets up a "watcher" on a variable so that
                          various "agents" can be notified when a
                          variable has been updated.

           CVPOOL         Indicates whether or not an agent's
                          variable has been updated since the last
                          time an agent checked with the pool.

           GCPOOL         Returns the value of a string valued
                          variable in the pool.

           GDPOOL         Returns the d.p. value of a numeric valued
                          variable in the pool.

           GIPOOL         Returns the integer value of a numeric valued
                          variable in the pool.

           DTPOOL         Returns the attributes of a variable in the
                          pool.

           PCPOOL         Allows the insertion of a character variable
                          directly into the kernel pool without
                          supplying a text kernel.

           PDPOOL         Allows the insertion of a double precision
                          variable directly into the kernel pool
                          without supplying a text kernel.

           PIPOOL         Allows the insertion of an integer variable
                          directly into the kernel pool without
                          supplying a text kernel.

           LMPOOL         Similar to LDPOOL, but the text kernel is
                          stored in an array of strings instead of an
                          external file.

           SZPOOL         allows run time retrieval of kernel pool
                          memory parameters.

           DVPOOL         allows deletion of a specific variable from
                          the kernel pool. (CLPOOL deletes all
                          variables from the kernel pool.)

           GNPOOL         assists in determining which variables are
                          defined in the kernel pool via variable name
                          template matching.

           DWPOOL         deletes a watch from the watcher system.

     Nominally, the kernel pool contains up to MAXVAR separate
     variables, up to MAXVAL numeric values, and up to MAXLIN string
     values. The names of the individual variables may contain up to
     MAXLEN characters.

Examples

     The following code fragment demonstrates how the data from
     several kernel files can be loaded into a kernel pool. After the
     pool is loaded, the values in the pool are written to a kernel
     file.

     C
     C     Store in an array the names of the kernel files whose
     C     values will be loaded into the kernel pool.
     C
           FNAME (1) = 'AXES.KER'
           FNAME (2) = 'GM.KER'
           FNAME (3) = 'LEAP_SECONDS.KER'

     C
     C     Clear the kernel pool. (This is optional.)
     C
           CALL CLPOOL

     C
     C     Load the variables from the three kernel files into the
     C     the kernel pool.
     C
           DO I = 1, 3
             CALL LDPOOL ( FNAME (I) )
           END DO

     C
     C     We can examine the values associated with any d.p. variable
     C     in the kernel pool using GDPOOL.
     C
           CALL GDPOOL ( VARIABLE, START, ROOM, NVALS, VALUES, FOUND )

     C
     C     Open the text file 'NEWKERNEL.KER'.
     C
           CALL TXTOPN ( NEWKERNEL.KER', UNIT )

     C
     C     Write the values in the kernel pool to the file.
     C
           CALL WRPOOL ( UNIT )

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     H.A. Neilan        (JPL)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     R.E. Thurman       (JPL)
     F.S. Turner        (JPL)
     I.M. Underwood     (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 10.2.0, 27-AUG-2021 (JDR) (BVS) (NJB)

        Changed input argument name KERNEL to FNAME in entry point
        LDPOOL for consistency with other routines.

        Edited the header of the umbrella routine and all its entry
        points.

        Updated SZPOOL $Detailed_Input section.

    SPICELIB Version 10.1.0, 14-JUL-2014 (NJB) (BVS)

        Updated header of WRPOOL to improve accuracy of
        that routine's output description.

        Updated header of CVPOOL to improve accuracy of
        the description of the output argument UPDATE.

        Updated header of CLPOOL to improve the description
        of behavior of the watcher subsystem.

        Last update was 17-JAN-2014 (BVS) (NJB)

        Increased key POOL parameters as follows:

           MAXVAR    5003 ->  26003
           MAXVAL  200000 -> 400000
           MAXLIN    4000 ->  15000

        Decreased MXNOTE factor F (MXNOTE=MAXVAR*F) from 10 to 5.

        Updated the main umbrella argument list to include the POOL
        state counter. Added the private entry point ZZPCTRCK allowing
        other routines to check their saved POOL state counter against
        the current POOL state counter to detect and act on the POOL
        state change.

        Updated $Index_Entries sections of entry points PCPOOL, PDPOOL,
        and PIPOOL.

    SPICELIB Version 10.0.0, 24-MAY-2010 (EDW) (NJB)

        Added an error check on the length of the kernel pool variable
        name argument in:

           PCPOOL
           PDPOOL
           PIPOOL

        to enforce the variable name length does not exceed MAXLEN.

        Increased MAXVAL to 200000.

    SPICELIB Version 9.0.0, 19-MAR-2009 (NJB)

        Added watch deletion entry point DWPOOL and private entry
        point ZZVUPOOL. Re-implemented watcher system to improve
        efficiency, particularly of watch deletion. Bug fix: corrected
        watcher overflow detection logic in SWPOOL. Updated header
        code examples to use TXTOPN instead of GETLUN and a Fortran
        OPEN statement; also to use GDPOOL instead of RTPOOL, except in
        the header of RTPOOL itself.

        Code examples in SWPOOL and CVPOOL were updated to handle
        kernel pool fetch failures.

        Existing entry points modified as part of this update were:

           POOL
           CLPOOL
           CVPOOL
           DTPOOL
           DVPOOL
           EXPOOL
           GCPOOL
           GDPOOL
           GIPOOL
           GNPOOL
           LDPOOL
           LMPOOL
           PCPOOL
           PDPOOL
           PIPOOL
           RTPOOL
           SWPOOL
           WRPOOL

        Code examples using RTPOOL were updated to use GDPOOL, except
        in the header of RTPOOL itself. Code examples using GETLUN and
        an in-line Fortran OPEN statement were updated to use TXTOPN.

        Various typos in comments throughout this file were fixed.


    SPICELIB Version 8.3.0, 22-DEC-2004 (NJB)

        Fixed bug in DVPOOL. Made corrections to comments in
        other entry points. The updated routines are DTPOOL,
        DVPOOL, EXPOOL, GCPOOL, GDPOOL, GIPOOL, RTPOOL.

    SPICELIB Version 8.2.0, 24-JAN-2003 (BVS)

        Increased MAXVAL to 40000.

    SPICELIB Version 8.1.0, 13-MAR-2001 (FST) (NJB)

        Increased kernel pool size and agent parameters. MAXVAR is now
        5003, MAXVAL is 10000, MAXLIN is 4000, MXNOTE is 2000, and
        MAXAGT is 1000.

        Modified Fortran output formats used in entry point WRPOOL to
        remove list-directed formatting. This change was made to
        work around problems with the way f2c translates list-
        directed I/O.


    SPICELIB Version 8.0.0, 04-JUN-1999 (WLT)

        Added the entry points PCPOOL, PDPOOL and PIPOOL to allow
        direct insertion of data into the kernel pool without having
        to read an external file.

        Added the interface LMPOOL that allows SPICE
        programs to load text kernels directly from memory
        instead of requiring a text file.

        Added the entry point SZPOOL to return kernel pool definition
        parameters.

        Added the entry point DVPOOL to allow the removal of a variable
        from the kernel pool.

        Added the entry point GNPOOL to allow users to determine
        variables that are present in the kernel pool

    SPICELIB Version 7.0.0, 20-SEP-1995 (WLT)

        The implementation of the kernel pool was completely redone
        to improve performance in loading and fetching data. In
        addition the pool was upgraded so that variables may be
        either string or numeric valued.

        The entry points GCPOOL, GDPOOL, GIPOOL and DTPOOL were added
        to the routine.

        The entry point RTPOOL should now be regarded as obsolete
        and is maintained solely for backward compatibility with
        existing routines that make use of it.

    SPICELIB Version 6.0.0, 31-MAR-1992 (WLT)

        The entry points SWPOOL and CVPOOL were added.

    SPICELIB Version 5.0.0, 22-AUG-1990 (NJB)

        Increased value of parameter MAXVAL to 5000 to accommodate
        storage of SCLK coefficients in the kernel pool.

    SPICELIB Version 4.0.0, 12-JUN-1990 (IMU)

        All entry points except POOL and CLPOOL now initialize the
        pool if it has not been done yet.

    SPICELIB Version 3.0.0, 23-OCT-1989 (HAN)

        Added declaration of FAILED. FAILED is checked in the
        DO-loops in LDPOOL and WRPOOL to prevent infinite looping.

    SPICELIB Version 2.0.0, 18-OCT-1989 (RET)

       A FAILED test was inserted into the control of the DO-loop which
       reads in each kernel variable in LDPOOL.

    SPICELIB Version 1.2.0, 09-MAR-1989 (HAN)

        Parameters BEGDAT and BEGTXT have been moved into the
        $Declarations section.

    SPICELIB Version 1.1.0, 16-FEB-1989 (IMU) (NJB)

        Parameters MAXVAR, MAXVAL, MAXLEN moved into $Declarations.
        (Actually, MAXLEN was implicitly 32 characters, and has only
        now been made an explicit---and changeable---limit.)

        Declaration of unused function FAILED removed.

    SPICELIB Version 1.0.0, 08-JAN-1989 (IMU)
Fri Dec 31 18:36:39 2021