Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page gnpool_c

Table of contents

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

       gnpool_c (Get names of kernel pool variables)

       void gnpool_c ( ConstSpiceChar    * name,
                       SpiceInt            start,
                       SpiceInt            room,
                       SpiceInt            cvalen,
                       SpiceInt          * n,
                       void              * cvals,
                       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.
       cvalen     I   Length of strings in output array cvals.
       n          O   Number of values returned for name.
       cvals      O   Kernel pool variables whose names match name.
       found      O   SPICETRUE 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.

       cvalen      is the length of strings in the output array cvals. This
                   length includes room for the terminating null in each
                   string. To ensure that the output names are not
                   truncated, cvalen 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.

       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.

                   The declaration of cvals should be equivalent to

                      SpiceChar  cvals [room][cvalen];

       found       is SPICETRUE if the some variable name in the kernel pool
                   matches name, SPICEFALSE 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 by a routine in the call tree
           of this routine.

       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.

       3)  If the `name' input string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       4)  If the `name' input string has zero length, the error
           SPICE(EMPTYSTRING) is signaled.

       5)  If the `cvals' output string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       6)  If the `cvals' output string has length less than two
           characters, the error SPICE(STRINGTOOSHORT) is signaled, since
           the output string is too short to contain one character of
           output data plus a null terminator.

#### 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 numerical results shown for this example may differ across
       platforms. The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       1) Load a PCK kernel, create a template for Jupiter kernel
          variables, and after performing a query for them, output all the
          variable names found in the kernel pool that match that template.

          Use the PCK kernel below to load the triaxial ellipsoidal shape
          model and orientation data for Jupiter.

             pck00010.tpc

          Example code begins here.

          /.
             Program gnpool_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {

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

             SpiceBoolean            found;

             SpiceChar               cvals [ROOM][LNSIZE];

             SpiceInt                i;
             SpiceInt                n;
             SpiceInt                start;

             /.
              Load a PCK kernel.
             ./
             furnsh_c ( "pck00010.tpc" );

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

             start  =  0;

             gnpool_c ( TEMPLATE, start, ROOM, LNSIZE, &n, cvals, &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", cvals[i] );
                }

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

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

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

             }

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, the output was:

          Kernel pool variables:

             BODY599_PM
             BODY599_LONG_AXIS
             BODY599_RADII
             BODY599_NUT_PREC_DEC
             BODY599_NUT_PREC_PM
             BODY599_POLE_RA
             BODY599_POLE_DEC
             BODY599_NUT_PREC_RA

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

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

#### Version

       -CSPICE Version 1.2.0, 10-AUG-2021 (JDR)

           Changed the argument names "lenout" and "kvars" to "cvalen" and
           "cvals" for consistency with other routines.

           Edited the header to comply with NAIF standard.
           Replaced "ldpool_c" by "furnsh_c" in the code example. Added
           example's problem statement and solution.

           Added MAXLEN parameter description, corrected entry #2 in
           -Exceptions section, added entry #5, and removed non-applicable
           entry, which indicated that an error is signaled if a kernel
           pool variable name exceeds MAXLEN.

       -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

    Fri Dec 31 18:41:08 2021