Table of contents
CSPICE_STPOOL retrieves the nth string from a kernel pool variable, where
the string may be continued across several components of the kernel pool
variable.
Given:
item the name of a kernel pool variable for which the caller wants
to retrieve a full (potentially continued) string component.
help, item
STRING = Scalar
nth the number of the string to retrieve from the kernel pool.
help, nth
LONG = Scalar
The range of `nth' is 0 to one less than the number of full
strings that are present.
contin a sequence of characters which (if they appear as the last
non-blank sequence of characters in a component of a value of
a kernel pool variable) act as a continuation marker: the
marker indicates that the string associated with the
component is continued into the next literal component of the
kernel pool variable.
help, contin
STRING = Scalar
If `contin' is blank, all of the components of `item' will be
retrieved as a single string.
the call:
cspice_stpool, item, nth, contin, nthstr, size, found
returns:
nthstr the `nth' full string associated with the kernel pool
variable specified by `item'.
help, nthstr
STRING = Scalar
size the index of last non-blank character of the continued string
as it is represented in the kernel pool.
help, size
LONG = Scalar
If the value of `nthstr' should be a blank, then `size' will
be set to 1.
found a logical variable indicating success of the request to
retrieve the `nth' string associated with `item'.
help, found
BOOLEAN = Scalar
If an nth string exists, `found' will be set to True;
otherwise `found' will be set to False.
None.
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) Retrieve the "nth" string from the kernel pool variable
"item", where the string may be continued across several
components of the kernel pool variable.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File: stpool_ex1.tm
This meta-kernel is intended to support operation of SPICE
example programs.
This meta-kernel contains a single variable assigned to an
array of two character strings that are split over several
components of the variable, with '//' as continuation
marker.
\begindata
LONG_VAL = ( 'String 1: inserted into //'
'the kernel pool using //'
'3 components.'
'String 2: split up as 2 //'
'components of a kernel pool variable.' )
\begintext
End of meta-kernel.
Example code begins here.
PRO stpool_ex1
;;
;; Load the meta-kernel kernel containing the variable
;; assignment.
;;
cspice_furnsh, 'stpool_ex1.tm'
;;
;; Retrieve the 'nth' entry for kernel pool variable
;; 'LONG_VAL' to 'string'.
;;
item = 'LONG_VAL'
contin = '//'
for nth = 0, 2 do begin
;;
;; Call the function.
;;
cspice_stpool, item, nth, contin, string, size, found
;;
;; Output the value and size if 'nth' element of 'item'
;; was found.
;;
print, 'String index: ', nth
if ( found ) then begin
print, 'String size : ', size
print, 'Found string: '
print, ' ', string
endif else begin
print, 'No string found.'
endelse
print
endfor
;;
;; 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:
String index: 0
String size : 59
Found string:
String 1: inserted into the kernel pool using 3 components.
String index: 1
String size : 61
Found string:
String 2: split up as 2 components of a kernel pool variable.
String index: 2
No string found.
The SPICE Kernel Pool provides a very convenient interface
for supplying both numeric and textual data to user application
programs. However, any particular component of a character
valued component of a kernel pool variable is limited to 80
or fewer characters in length.
This routine allows you to overcome this limitation by
"continuing" a character component of a kernel pool variable.
To do this you need to select a continuation sequence
of characters and then insert this sequence as the last non-blank
set of characters that make up the portion of the component
that should be continued.
For example, you may decide to use the sequence '//' to indicate
that a string should be continued to the next component of
a kernel pool variable. Then set up the
kernel pool variable as shown below
LONG_STRINGS = ( 'This is part of the first component //'
'that needs more than one line when //'
'inserting it into the kernel pool.'
'This is the second string that is split //'
'up as several components of a kernel pool //'
'variable.' )
When loaded into the kernel pool, the variable LONG_STRINGS
will have six literal components:
component[0] = 'This is part of the first component //'
component[1] = 'that needs more than one line when //'
component[2] = 'inserting it into the kernel pool.'
component[3] = 'This is the second string that is split //'
component[4] = 'up as several components of a kernel pool //'
component[5] = 'variable.'
These are the components that would be retrieved by the call
cspice_gcpool, 'LONG_STRINGS', 0L, 6L, 81, component, found
However, using the routine cspice_stpool you can view the variable
LONG_STRINGS as having two long components.
strgna = 'This is part of the first component that ' + $
'needs more than one line when inserting ' + $
'it into the kernel pool. '
strgnb = 'This is the second string that is split ' + $
'up as several components of a kernel pool ' + $
'variable. '
These string components would be retrieved by the following two
calls.
cspice_stpool, 'LONG_STRINGS', 0, '//', strgna, size, found
cspice_stpool, 'LONG_STRINGS', 1, '//', strgnb, size, found
1) If the variable specified by `item' is not present in the kernel
pool or is present but is not character valued, `nthstr' will be
returned as a blank, `size' will be returned with the value 0
and `found' will be set to False. In particular if `nth' is less
than 1, `nthstr' will be returned as a blank, `size' will be zero
and `found' will be False.
2) If the variable specified has a blank string associated
with its `nth' full string, `nthstr' will be blank, `size'
will be 1 and `found' will be set to True.
3) If the continuation character is a blank, every component
of the variable specified by `item' will be inserted into
the output string.
4) If the continuation character is blank, then a blank component
of a variable is treated as a component with no letters. For
example:
STRINGS = ( 'This is a variable'
'with a blank'
' '
'component.' )
Is equivalent to
STRINGS = ( 'This is a variable'
'with a blank'
'component.' )
from the point of view of cspice_stpool if `contin' is set to the
blank character.
5) If any of the input arguments, `item', `nth' or `contin', is
undefined, an error is signaled by the IDL error handling
system.
6) If any of the input arguments, `item', `nth' or `contin', is
not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
7) If any of the output arguments, `nthstr', `size' 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, 01-NOV-2021 (JDR)
Changed output argument name "string" to "nthstr" for consistency
with other routines.
Edited the header to comply with NAIF standard. Added
example's problem statement and meta-kernel. Example updated
to use "cspice_kclear".
Added -Parameters, -Particulars, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
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.0, 16-JUN-2003 (EDW)
Retrieve a continued string value from the kernel pool
|