Index Page gnpool_c
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 Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void gnpool_c ( ConstSpiceChar    * name,
                       SpiceInt            start,
                       SpiceInt            room,
                       SpiceInt            lenout,
                       SpiceInt          * n,
                       void              * kvars,
                       SpiceBoolean      * found  )
#### Abstract
       Return names of kernel variables matching a specified template.
#### Required_Reading
       KERNEL
#### Keywords
       CONSTANTS
       FILES
#### 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.
       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.
#### Detailed_Input
       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.
                  'name' is restricted to a length of 32 characters or less.

       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.
#### 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.

       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.
#### Parameters
       None.
#### Exceptions
       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.

       6) The error 'SPICE(BADVARNAME)' signals if the kernel pool
          variable name length exceeds 32.
#### 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 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 );
          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       W.L. Taber     (JPL)
#### Version
       -CSPICE Version 1.1.1,  10-FEB-2010 (EDW)

          Added mention of the restriction on kernel pool variable
          names to 32 characters or less.

       -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)
#### Index_Entries
       return names of kernel pool variables matching a template
#### Link to routine gnpool_c source file gnpool_c.c

    Wed Jun  9 13:05:24 2010