Return names of kernel variables matching a specified template.

   KERNEL

   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.
   lenout     I   Length of strings in output array kvars.
   n          O   Number of values returned for name.
   kvars      O   Kernel pool variables whose names match name.
   found      O   True if there is at least one match.

   name       is a matchi_c 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_c.


   start      is the index of the first variable name to return that
              matches the name template.  The matching names are
              assigned indices ranging from 0 to NVAR-1, 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 0, it will be treated as 0.  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
              SPICETRUE.


   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.

   lenout     is the length of strings in the output array kvars.  This
              length includes room for the terminating null in each
              string.  To ensure that the output names are not
              truncated, lenout should be at least 33.

   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.


   kvars      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 kvars are
              not sorted.

              If no variables match name, no values are assigned to
              the elements of kvars.

              If the length of kvars is less than the length of the
              variable names, the values returned will be truncated
              on the right.

              The declaration of kvars should be equivalent to

                 SpiceChar  kvars [room][lenout];


   found      is SPICETRUE if the some variable name in the kernel pool
              matches name, SPICEFALSE if it is not.

   None.

   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.

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

      #include <stdio.h>
      #include "SpiceUsr.h"

      int main()
      {

         #define  ROOM           3
         #define  LNSIZE         81
         #define  TEMPLATE       "BODY599*"

         SpiceBoolean            found;

         SpiceChar               kvars [ROOM][LNSIZE];

         SpiceInt                i;
         SpiceInt                n;
         SpiceInt                start;

         /.
         Load the data in the file "typical.ker" into the kernel pool.
         ./
         ldpool_c ( "typical.ker" );

         /.
         Print the names of kernel variables that match TEMPLATE.
         ./

         start  =  0;

         gnpool_c ( TEMPLATE, start, ROOM, LNSIZE, &n, kvars, &found );

         if ( !found )
         {
            printf ( "There are no matching variables in the "
                     "kernel pool\n"                           );
         }
         else
         {
            printf ( "Kernel pool variables:\n"
                     "\n"                       );

            for ( i = 0;  i < n;  i++ )
            {
               printf ( "   %s\n", kvars[i] );
            }

            while ( n == ROOM )
            {
               start += n;

               gnpool_c ( TEMPLATE,  start,  ROOM,   LNSIZE,
                          &n,        kvars,  &found          );

               for ( i = 0;  i < n;  i++ )
               {
                  printf ( "   %s\n", kvars[i] );
               }
            }
         }
         /.
         This is the end of the if block following the first gnpool_c
         call.
         ./

         return ( 0 );
      }

   None.

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

   2) If kvars has declared length less than the size (including
      terminating null character) of a name to be returned, the name
      will be truncated on the right.  The parameter MAXCHR sets
      the maximum stored size of string variables.

   3) If either the input or output string pointers are null, the error
      SPICE(NULLPOINTER) will be signaled.

   4) If the input string has length zero, the error SPICE(EMPTYSTRING)
      will be signaled.

   5) The caller must pass a value indicating the length of the output
      string.  If this value is not at least 2, the error
      SPICE(STRINGTOOSHORT) will be signaled.

   None.

   N.J. Bachman   (JPL)
   W.L. Taber     (JPL)

   None.

   -CSPICE Version 1.1.0, 18-MAY-2001 (WLT)

      Added a cast to (char *) in the call to F2C_ConvertStrArr

   -CSPICE Version 1.0.0, 08-JUN-1999 (NJB) (WLT)

   return names of kernel pool variables matching a template