Table of contents
CSPICE_GNPOOL queries the kernel pool for names of pool variables
matching a user defined template.
Given:
name the scalar string cspice_matchi template to use when searching
for variable names in the kernel pool.
help, name
STRING = Scalar
The characters '*' and '%' are used for the wild card string
and wild card character respectively. For details of string
pattern matching see the header of the routine cspice_matchi.
start a scalar integer value for the index indicating the first
component of the data vector to 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 of
strings in the output array `cvals'.
help, cvalen
LONG = Scalar
This length shall include room for the terminating null in each
string.
the call:
cspice_gnpool, name, start, room, cvalen, cvals, found
returns:
cvals a string array of kernel variable names matching the template
`name', beginning with match number `start'.
help, cvals
STRING = Array[N]
found a scalar boolean that flags whether any kernel variable names
matched the `name' template (True) or not (False).
help, found
BOOLEAN = Scalar
`cvals' has a size of `room' or less.
MAXLEN is the maximum length of the variable names that
can be stored in the kernel pool. This value is
currently 32.
Any numerical results shown for these examples may differ between
platforms as the results depend on the SPICE kernels used as input
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.
PRO gnpool_ex1
;;
;; Load a PCK kernel.
;;
cspice_furnsh, 'pck00010.tpc'
;;
;; A template for Jupiter kernel variables.
;;
VAR = 'BODY599*'
;;
;; Query for the variable name, return all matches from
;; index 0.
;;
INDEX = 0
ROOM = 10
STRLEN = 81
cspice_gnpool, VAR, INDEX, ROOM, STRLEN, kervar, found
if (found) then begin
;;
;; Output the returned variable names.
;;
for i=0, n_elements(kervar)-1 do begin
print, ' Variable ' + string(i) + ' matching ' + VAR $
+ ' : ', kervar[i]
endfor
endif else begin
print, 'Failed to find ' + VAR + ' in the kernel pool'
endelse
;;
;; 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:
Variable 0 matching BODY599* : BODY599_PM
Variable 1 matching BODY599* : BODY599_LONG_AXIS
Variable 2 matching BODY599* : BODY599_RADII
Variable 3 matching BODY599* : BODY599_NUT_PREC_DEC
Variable 4 matching BODY599* : BODY599_NUT_PREC_PM
Variable 5 matching BODY599* : BODY599_POLE_RA
Variable 6 matching BODY599* : BODY599_POLE_DEC
Variable 7 matching BODY599* : BODY599_NUT_PREC_RA
2) Obtain from the kernel pool the names of the first
10 variables stored. Use the * wildcard character
as a template to indicate a request for all kernel
variables.
Use the PCK kernel below to load the triaxial ellipsoidal shape
model and orientation data for all the Solar System planets.
pck00010.tpc
Example code begins here.
PRO gnpool_ex2
;;
;; Return to the array 'kervar' the names of the first
;; 'ROOM' pool variables. Use the * wildcard character
;; as a template to indicate a request for all kernel
;; variables.
;;
;;
;; Return all matches from 'INDEX' zero.
;;
INDEX = 0
ROOM = 10
STRLEN = 81
;;
;; Load a meta kernel listing leapseconds and
;; the default SPICE PCK kernels.
;;
cspice_furnsh, 'pck00010.tpc'
;;
;; Retrieve the variables from the pool.
;;
cspice_gnpool, '*', index, ROOM, STRLEN, kervar, found
;;
;; Output the returned variable names.
;;
if (found) then begin
;;
;; Output the returned variable names.
;;
for i=0, n_elements(kervar)-1 do begin
print, ' Variable ' + string(i) + ' : ', kervar[i]
endfor
endif else begin
print, 'Failed to find any variable in the kernel pool'
endelse
;;
;; 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:
Variable 0 : BODY611_LONG_AXIS
Variable 1 : BODY4_NUT_PREC_ANGLES
Variable 2 : BODY604_POLE_RA
Variable 3 : BODY605_POLE_DEC
Variable 4 : BODY399_N_GEOMAG_CTR_DIPOLE_LAT
Variable 5 : BODY399_POLE_RA
Variable 6 : BODY703_NUT_PREC_PM
Variable 7 : BODY708_LONG_AXIS
Variable 8 : BODY501_NUT_PREC_RA
Variable 9 : BODY710_NUT_PREC_PM
Note, the seemingly random order of the output list reflects the
order used by the SPICE kernel subsystem to store/lookup the
variable names.
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.
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 variable name to be returned, the name will be truncated on
the right. See MAXLEN for the maximum size of variable names.
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" and "kvars" to "cvalen"
and "cvals" for consistency with other routines.
Edited the -Examples section to comply with NAIF standard. Added
examples' problem statement and a reference to the required PCK.
Added cspice_kclear to both examples.
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.2, 29-APR-2011 (EDW)
Edits to -I/O section so as to parallel Mice version.
-Icy Version 1.0.1, 02-JAN-2007 (EDW)
Edit to -I/O section for 'room' and 'start' to improve clarity.
Minor edit to example comments concerning output list order.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
return names of kernel pool variables matching a template
|