gcpool_c

Index Page gcpool_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 gcpool_c ( ConstSpiceChar * name,
                       SpiceInt         start,
                       SpiceInt         room,
                       SpiceInt         lenout,
                       SpiceInt       * n,
                       void           * cvals,
                       SpiceBoolean   * found )
#### Abstract
       Return the character 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.
       lenout     I   The length of the output string.
       n          O   Number of values returned for name.
       cvals      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
                  character 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 cvals). If room is
                  less than 1 the error SPICE(BADARRAYSIZE) will be
                  signalled.

       lenout     The allowed length of the output string.  This length
                  must large enough to hold the output string plus the
                  terminator.  If the output string is expected to have x
                  characters, lenout needs to be x + 1.
#### 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 character type, no
                  value is given to n.

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

                  If the length of cvals is less than the length of
                  strings stored in the kernel pool (see MAXCHR) the
                  values returned will be truncated on the right.

       found      is SPICETRUE if the variable is in the pool and has
                  character 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 cvals has declared length less than the size of a
          string to be returned, the value will be truncated on
          the right.  See MAXCHR in pool.c for the maximum stored size of
          string variables.

       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.

       5) If the output string has length less than two characters, it
          is too short to contain one character of output data plus a null
          terminator, so it cannot be passed to the underlying Fortran
          routine.  In this event, the error SPICE(STRINGTOOSHORT) is
          signaled.
#### Files
       None.
#### Particulars
       This routine provides the user interface to retrieving
       character 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.

       C requires the length of the output character array to be defined
       prior to calling the converted gcpool_c routine.  The size of the
       cvals output array is user defined and passed as the variable
       lenout.

       Also see the entry points gdpool_c and gipool_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.397 )

       The program...

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

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

       #define LENOUT 20
       #define NUMVALS 2
       #define START   1

       void main()
          {

          SpiceInt          n;
          SpiceChar         cvals[NUMVALS][LENOUT];
          SpiceBoolean      found;
          SpiceInt          i;

           ldpool_c ( "test.ker" );

           /.
           Get 2 values (NUMVALs) starting at the second value
           in the list (START).  Each value will be of length LENOUT.
           ./

           gcpool_c ( "CTEST_VAL", START, NUMVALS, LENOUT, &n, cvals,
                      &found );

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

           exit(0);
          }

       Will give output of
       MOE
       CURLY
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       W.L. Taber  (JPL)
#### Version
       -CSPICE Version 2.2.1 07-SEP-2007   (EDW)

          Edited the 'lenout' description in the Detailed_Input to
          remove the recommendation of 32 as a general use value
          for 'lenout'.

       -CSPICE Version 2.2.0 18-MAY-2001   (WLT)

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

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

          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.3 09-FEB-1998   (EDW)

          Removed the output dynamically allocated string.  Conversion
          of cval from string to array now accomplished via the
          F2C_ConvertStrArray call.

       -CSPICE Version 2.0.2 01-FEB-1998   (EDW)

          Removed the input and work dynamically allocated strings.

       -CSPICE Version 2.0.1 28-JAN-1998   (EDW)

          The start parameter is now zero based as per C convention.
          Adjusted the amount of memory for the strings to lenout-1.

       -CSPICE Version 2.0.0 07-JAN-1998   (EDW)

         The routine now function properly for room > 1.  Previously
         only a single value could be returned.

       -CSPICE Version 1.0.0 23-OCT-1997   (EDW)
#### Index_Entries
       RETURN the character value of a pooled kernel variable
       RETURN the string value of a pooled kernel variable
#### Link to routine gcpool_c source file gcpool_c.c

    Thu Apr 16 08:58:08 2009