Table of contents
CSPICE_GCPOOL returns the value of a string kernel variable
(scalar or array) from the kernel pool.
Given:
name the scalar string name of a pool variable associated to string
values.
help, name
STRING = Scalar
start a scalar integer value for the index indicating the first
component of the data vector assigned to `name' for return
(index 0 for all elements).
help, start
LONG = Scalar
room the scalar integer specifying the maximum number of components
that can return for `name'.
help, room
LONG = Scalar
cvalen the scalar integer value describing the maximum length to allow
for the data strings assigned to `name' (if the output string is
expected to have x characters, `cvalen' needs to be x + 1 to
accommodate a null terminator).
help, cvalen
LONG = Scalar
the call:
cspice_gcpool, name, start, room, cvalen, cvals, found
returns:
cvals a string array of the values assigned to `name' beginning at
index `start'.
help, cvals
STRING = Array[N]
found a scalar boolean that flags whether `name' exists in the kernel
pool and has character type.
help, found
BOOLEAN = Scalar
`cvals' has a size of `room' or less.
MAXCHR is the maximum number of characters that can be
stored in a component of a string valued kernel
variable. This value is currently 80.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) The following code example demonstrates how the data stored
in a kernel pool variable can be retrieved in pieces.
Use the kernel shown below to load the kernel pool with the
variables used within the example.
KPL/MK
File name: gcpool_ex1.tm
This kernel is intended to support operation of SPICE
example programs.
\begindata
CTEST_VAL = ('LARRY', 'MOE', 'CURLY' )
ITEST_VAL = ( 3141, 186, 282 )
DTEST_VAL = ( 3.1415, 186. , 282.397 )
\begintext
End of meta-kernel
Example code begins here.
PRO gcpool_ex1
;;
;; Load the test data.
;;
cspice_furnsh, 'gcpool_ex1.tm'
;;
;; Retrieve up-to 'ROOM' character entries for
;; kernel pool variable named 'CTEST_VAL' to
;; the array named 'cvals'. The first index to return,
;; 'START', has value 0 (this returns all strings).
;; Use a string length of 80.
;;
VAR = 'CTEST_VAL'
ROOM = 25
LENGTH = 81
START = 0
cspice_gcpool, VAR, START, ROOM, LENGTH, cvals, found
if (found) then begin
print, 'Found ' + VAR + ' in the kernel pool'
for i=0, n_elements(cvals)-1 do begin
print, ' Element ' + string(i) + ' of ' + VAR + $
': ``', cvals[i], '``'
endfor
endif
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Found CTEST_VAL in the kernel pool
Element 0 of CTEST_VAL: ``LARRY``
Element 1 of CTEST_VAL: ``MOE``
Element 2 of CTEST_VAL: ``CURLY``
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.
See also the routines cspice_gdpool and cspice_gipool.
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, `cvalen', less than the size of
a string to be returned, the value will be truncated on the
right. See MAXCHR for the maximum stored size of string
variables.
3) If any of the input arguments, `name', `start', `room' or
`cvalen', is undefined, an error is signaled by the IDL error
handling system.
4) If any of the input arguments, `name', `start', `room' or
`cvalen', is not of the expected type, or it does not have the
expected dimensions and size, an error is signaled by the Icy
interface.
5) If any of the output arguments, `cvals' or `found', is not a
named variable, an error is signaled by the Icy interface.
None.
None.
ICY.REQ
KERNEL.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.0, 10-AUG-2021 (JDR)
Changed the input argument name "length" to "cvalen" for
consistency with other routines.
Edited the -Examples section to comply with NAIF standard. Added
example's meta-kernel and problem statement. Modified example
to use "cspice_kclear".
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.3, 26-AUG-2016 (EDW) (JDR)
Edit to example code. Typos in kernel names; "pool_t.ker"
and "pool_t.pro" rather than "pool_t.tm."
-Icy Version 1.0.2, 08-AUG-2008 (EDW)
Minor edits to header text.
-Icy Version 1.0.1, 03-JAN-2007 (EDW)
Edit to -I/O section for 'room' and 'start' to improve clarity.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
RETURN the character value of a pooled kernel variable
RETURN the string value of a pooled kernel variable
|