gipool_c

Index Page gipool_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 gipool_c ( ConstSpiceChar * name,
                       SpiceInt         start,
                       SpiceInt         room,
                       SpiceInt       * n,
                       SpiceInt       * ivals,
                       SpiceBoolean   * found )
#### Abstract
       Return the integer 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.
       ivals      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 ivals). If room is
                  less than 1 the error SPICE(BADARRAYSIZE) will be
                  signalled.
#### 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.

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

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

       2) If a value requested is outside the valid range
          of integers, the error SPICE(INTOUTOFRANGE) is signalled.

       3) If the input string pointer is null, the error SPICE(NULLPOINTER)
          will be signaled.

       4) If the input string has length zero, the error SPICE(EMPTYSTRING)
          will be signaled.
#### Files
       None.
#### Particulars
       This routine provides the user interface for retrieving
       integer 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.

       See also the entry points gdpool_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;

          SpiceInt          ivals[NUMVALS];

          ldpool_c ( "test.ker" );

          /. Is data available by that name. ./

          gipool_c ( "ITEST_VAL", 0, NUMVALS, &n, ivals, &found );

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

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

          else
             {

             for ( i=0; i < NUMVALS; i++ )
                {
                gipool_c ( "ITEST_VAL", 1, NUMVALS, &n, ivals, &found );

                printf ( "%d \n", ivals[i] );
                }

             }

          exit(0);
          }

       Output should be

         186
         282
#### 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.0, 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 integer value of a pooled kernel variable
#### Link to routine gipool_c source file gipool_c.c

    Thu Apr 16 08:58:17 2009