Index Page
gdpool_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 gdpool_c ( ConstSpiceChar * name,
                   SpiceInt         start,
                   SpiceInt         room,
                   SpiceInt       * n,
                   SpiceDouble    * values,
                   SpiceBoolean   * found )

Abstract

   Return the d.p. value of a kernel variable from the kernel pool.

Required_Reading

   KERNEL

Keywords

   CONSTANTS
   FILES


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.
   values     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
              numeric type, found will be SPICEFALSE.

   start      is the index of the first component of name to return.
              The index follows the C convention of being 0 based.
              If start is less than 0, it will be treated as 0.  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
              SPICETRUE

   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 values). 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 numeric type, no value
              is given to n.

   values     is the array of values associated with name.
              If name is not in the pool with numeric type, no
              values are given to the elements of values.

   found      is SPICETRUE if the variable is in the pool and has
              numeric type, 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 the input string pointer is null, the error SPICE(NULLPOINTER)
      will be signaled.

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

Files

   None.

Particulars

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

   This routine should be used in place of rtpool_c when possible
   as it avoids errors associated with writing data past the
   end of an array.

   See also the entry points gipool_c and gcpool_c.

Examples

   The following code fragment demonstrates how the data stored
   in a kernel pool variable can be retrieved in pieces.  Using the
   kernel "test.ker" which contains

   \begindata

   CTEST_VAL = ('LARRY', 'MOE', 'CURLY' )

   ITEST_VAL = ( 3141, 186, 282 )

   DTEST_VAL = ( 3.1415, 186.282, .0175 )


   The program...

   #include <stdio.h>
   #include <string.h>

   #include "SpiceUsr.h"
   #include "SpiceZmc.h"

   #define   NUMVALS 2


   void main()
      {

      SpiceInt          n;
      SpiceInt          i;

      SpiceBoolean      found;

      SpiceDouble       vals[NUMVALS];


      ldpool_c ( "test.ker" );


      /. Is data available by that name. ./

      gdpool_c ( "DTEST_VAL", 0, NUMVALS, &n, vals, &found );


      /. If so, show me the values. ./

      if ( !found )
         {
         printf ( "No dp data available for DTEST_VAL.\n" );
         }

      else
         {

         for ( i=0; i < NUMVALS; i++ )
            {
            gdpool_c ( "DTEST_VAL", i, NUMVALS, &n, vals, &found );

            printf ( "%f \n", vals[i] );
            }

         }

      exit(0);
      }


   Output should be

      186.282000
      0.017500

Restrictions

   None.

Literature_References

   None.

Author_and_Institution

   W.L. Taber  (JPL)
   E.D. Wright (JPL)

Version

   -CSPICE Version 2.1.0 22-JUN-1999   (EDW)

      Re-implemented routine without dynamically allocated, temporary
      strings.

      Added local variable to return boolean/logical values.  This
      fix allows the routine to function if int and long are different
      sizes.

   -CSPICE Version 2.0.1 08-FEB-1998   (EDW)

      The start parameter is now zero based as per C convention.

   -CSPICE Version 1.0.1, 6-JAN-1998    (EDW)

      Replaced example routine.  Included the data for a test kernel.

   -CSPICE Version 1.0.0, 25-OCT-1997   (EDW)

Index_Entries

   RETURN the d.p. value of a pooled kernel variable
   RETURN the numeric value of a pooled kernel variable
Wed Apr  5 17:54:35 2017