Procedure

     GIPOOL (Get integers from the kernel pool)

     ENTRY GIPOOL ( NAME, START, ROOM, N, IVALS, FOUND )

Abstract

     Return the integer value of a kernel variable from the
     kernel pool.

Required_Reading

     KERNEL

Keywords

     CONSTANTS
     FILES

Declarations

    CHARACTER*(*)         NAME
    INTEGER               START
    INTEGER               ROOM
    INTEGER               N
    INTEGER               IVALS    ( * )
    LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     NAME       I   Name of the variable whose value is to be returned.
     START      I   Which component to start retrieving for NAME
     ROOM       I   The largest number of values to return.
     N          O   Number of values returned for NAME.
     IVALS      O   Values associated with NAME.
     FOUND      O   .TRUE. if variable is in pool.

Detailed_Input

     NAME     is the name of the variable whose values are to be
              returned. If the variable is not in the pool with
              numeric type, FOUND will be .FALSE.

     START    is the index of the first component of NAME to return.
              If START is less than 1, it will be treated as 1. If
              START is greater than the total number of components
              available for NAME, no values will be returned (N will
              be set to zero). However, FOUND will still be set to
              .TRUE.

     ROOM     is the maximum number of components that should be
              returned for this variable. (Usually it is the amount
              of ROOM available in the array IVALS). If ROOM is
              less than 1 the error SPICE(BADARRAYSIZE) will be
              signaled.

Detailed_Output

     N        is the number of values associated with NAME that
              are returned. It will always be less than or equal
              to ROOM.

              If NAME is not in the pool with numeric type, no value
              is given to N.

     IVALS    is the array of values associated with NAME. Any
              numeric value having non-zero fractional part is
              rounded to the closest integer. If NAME is not in the
              pool or does not have numeric type, no values are
              assigned to the elements of IVALS.

     FOUND    is .TRUE. if the variable is in the pool and has numeric
              type, .FALSE. if it is not.

Parameters

     None.

Exceptions

     1)  If the value of ROOM is less than one, the error
         SPICE(BADARRAYSIZE) is signaled.

     2)  If a value requested is outside the valid range
         of integers, the error SPICE(INTOUTOFRANGE) is signaled.

Files

     None.

Particulars

     This routine provides the user interface for retrieving
     integer data stored in the kernel pool. This interface
     allows you to retrieve the data associated with a variable
     in multiple accesses. Under some circumstances this alleviates
     the problem of having to know in advance the maximum amount
     of space needed to accommodate all kernel variables.

     However, this method of access does come with a price. It is
     always more efficient to retrieve all of the data associated
     with a kernel pool data in one call than it is to retrieve
     it in sections.

     See also the entry points GDPOOL and GCPOOL.

Examples

     The following code fragment demonstrates how the data stored
     in a kernel pool variable can be retrieved in pieces.

     First we need some declarations.

        INTEGER               ROOM
        PARAMETER           ( ROOM = 3 )

        CHARACTER*(8)         VARNAM
        CHARACTER*(3)         INDENT
        INTEGER               START
        INTEGER               N
        LOGICAL               FOUND
        INTEGER               IVALS(ROOM)


     Next load the data in the file 'typical.ker' into the
     kernel pool.

        CALL LDPOOL ( 'typical.ker' )

     Next we shall print the values stored for the kernel pool
     variable 'MYDATA'

        VARNAM = 'MYDATA'
        INDENT = ' '
        START  =  1

        CALL GIPOOL ( VARNAM, START, ROOM, N, IVALS, FOUND )

        IF ( .NOT. FOUND )
           WRITE (*,*) 'There is no numeric data available for MYDATA.'
        ELSE

           WRITE (*,*) 'Values for MYDATA.'
           WRITE (*,*)

           DO I = 1, N
              WRITE (*,*) INDENT, IVALS(I)
           END DO

           DO WHILE ( N .EQ. ROOM )

              START = START + N
              CALL GIPOOL ( VARNAM, START, ROOM, N, IVALS, FOUND )

              DO I = 1, N
                 WRITE (*,*) INDENT, IVALS(I)
              END DO

           END DO

        END IF

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 8.1.2, 17-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 8.1.1, 14-JUL-2014 (NJB)

        Updated description of IVALS in $Detailed_Output
        header section.

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

        ZZPINI call was updated for compatibility
        with new watcher system implementation.

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

        Corrected an in-line comment relating to finding the
        head node of the conflict resolution list for NAME.

    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.