Procedure

     GCPOOL (Get character data from the kernel pool)

     ENTRY GCPOOL ( NAME, START, ROOM, N, CVALS, FOUND )

Abstract

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

Required_Reading

     KERNEL

Keywords

     CONSTANTS
     FILES

Declarations

    CHARACTER*(*)         NAME
    INTEGER               START
    INTEGER               ROOM
    INTEGER               N
    CHARACTER*(*)         CVALS    ( * )
    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.
     CVALS      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
              character 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 CVALS). 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 character type, no
              value is given to N.

     CVALS    is the array of values associated with NAME.
              If NAME is not in the pool with character type, no
              values are given to the elements of CVALS.

              If the length of CVALS is less than the length of
              strings stored in the kernel pool (see MAXCHR) the
              values returned will be truncated on the right.

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

Parameters

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

Exceptions

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

     2)  If CVALS has declared length less than the size of a
         string to be returned, the value will be truncated on
         the right. See MAXCHR for the maximum stored size of
         string variables.

Files

     None.

Particulars

     This routine provides the user interface to retrieving
     character 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 GIPOOL.

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
        CHARACTER*(80)        CVALS(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 GCPOOL ( VARNAM, START, ROOM, N, CVALS, FOUND )

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

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

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

           DO WHILE ( N .EQ. ROOM )

              START = START + N
              CALL GCPOOL ( VARNAM, START, ROOM, N, CVALS, FOUND )

              DO I = 1, N
                 WRITE (*,*) INDENT, CVALS(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.1, 17-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard. Added MAXCHR
        description in $Parameters.

    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.