Procedure

     GNPOOL (Get names of kernel pool variables)

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

Abstract

     Return names of kernel variables matching a specified template.

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   Template that names should match.
     START      I   Index of first matching name to retrieve.
     ROOM       I   The largest number of values to return.
     N          O   Number of values returned for NAME.
     CVALS      O   Kernel pool variables whose names match NAME.
     FOUND      O   .TRUE. if there is at least one match.

Detailed_Input

     NAME     is a MATCHI template which will be used when searching
              for variable names in the kernel pool. The characters
              '*' and '%' are used for the wild string and wild
              characters respectively. For details of string
              pattern matching see the header of the routine MATCHI.


     START    is the index of the first variable name to return that
              matches the NAME template. The matching names are
              assigned indices ranging from 1 to NVAR, where NVAR is
              the number of matching names. The index of a name does
              not indicate how it compares alphabetically to another
              name.

              If START is less than 1, it will be treated as 1. If
              START is greater than the total number of matching
              variable names, no values will be returned and N will
              be set to zero. However, FOUND will still be set to
              .TRUE.


     ROOM     is the maximum number of variable names that should
              be returned for this template. If ROOM is less than 1
              the error SPICE(BADARRAYSIZE) will be signaled.

Detailed_Output

     N        is the number of variable names matching NAME that are
              returned. It will always be less than or equal to
              ROOM.

              If no variable names match NAME, N is set to zero.


     CVALS    is an array of kernel pool variables whose names match
              the template NAME and which have indices ranging from
              START to START+N-1.

              Note that in general the names returned in CVALS are
              not sorted.

              If no variables match NAME, no values are assigned to
              the elements of CVALS.

              If the length of CVALS is less than the length of the
              variable names, the values returned will be truncated
              on the right. To ensure that names are not truncated,
              CVALS should be declared to be at least
              CHARACTER*(32).


     FOUND    is .TRUE. if the some variable name in the kernel pool
              matches NAME, .FALSE. if it is not.

Parameters

     MAXLEN   is the maximum length of the variable names that
              can be stored in the kernel pool. This value is
              currently 32.

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 variable
         name to be returned, the name will be truncated on the right.
         See MAXLEN for the maximum size of variable names.

Files

     None.

Particulars

     This routine provides the user interface for retrieving the names
     of kernel pool variables. This interface allows you to retrieve
     the names matching a template via multiple accesses. Under some
     circumstances this alleviates the problem of having to know in
     advance the maximum amount of space needed to accommodate all
     matching names.

     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 variable in one call than it is to retrieve it in
     sections. The parameter MAXVAR defines the upper bound on the
     number of possible matching names.

Examples

     The following code fragment demonstrates how the names of kernel
     pool variables matching a template can be retrieved in pieces.

     First we need some declarations.

        INTEGER               ROOM
        PARAMETER           ( ROOM = 3 )

        CHARACTER*(3)         INDENT
        CHARACTER*(80)        CVALS  (ROOM)
        CHARACTER*(8)         VARNAM

        INTEGER               START
        INTEGER               N

        LOGICAL               FOUND


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

        CALL LDPOOL ( 'typical.ker' )

     Next we shall print the names of kernel variables that match the
     template 'BODY599*'.

        VARNAM = 'BODY599*'
        INDENT = ' '
        START  =  1

        CALL GNPOOL ( VARNAM, START, ROOM, N, CVALS, FOUND )

        IF ( .NOT. FOUND ) THEN

           WRITE (*,*) 'There are no matching variables ' //
       .               'in the kernel pool.'
        ELSE

           WRITE (*,*) 'Kernel pool variables:'
           WRITE (*,*)

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

           DO WHILE ( N .EQ. ROOM )

              START = START + N
              CALL GNPOOL ( 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 MAXLEN
        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.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