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

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 ( KERNEL, 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*(*)         KERNEL
      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
     --------  ---  --------------------------------------------------
     KERNEL     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
           KERNEL (1) = 'AXES.KER'
           KERNEL (2) = 'GM.KER'
           KERNEL (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 ( KERNEL (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)
     H.A. Neilan     (JPL)
     B.V. Semenov    (JPL)
     W.L. Taber      (JPL)
     F.S. Turner     (JPL)
     R.E. Thurman    (JPL)
     I.M. Underwood  (JPL)

Version

    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, 9-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, 8-JAN-1989 (IMU)
Wed Apr  5 17:47:04 2017