| SPICE Kernel Pool Required Reading |
Table of Contents
Abstract
Managing Kernels
The Generic Kernel Loader furnsh_c
Kernel Priority
Path Symbols
Keeping Track of Loaded Kernels
Reloading Kernels
Load Limits
Finding Out What's Loaded
Unloading Kernels
Loading of Non-native Text and Binary Kernels
Introduction of Text Kernels and Kernel Pool
The SPICE Text Kernel File Format
String Continuation
Fetching Data from the Kernel Pool
Informational Functions
Changing Kernel Pool Contents
Detecting Changes in the Kernel Pool
SPICE Subsystems that Rely on SPICE Text Kernels
PCK-related Functions
Time Conversion Functions
Frame Transformation Functions
Instrument Description Functions
Summary of Functions
Summary of Calling Sequences
Last revised on 2006 NOV 14 by E. D. Wright. Abstract
Managing KernelsThe Generic Kernel Loader furnsh_c
Previous versions of CSPICE loaded kernels using functions specific to each kernel type: SPK, CK, PCK, IK, LSK, EK; the binary kernel systems also supported a kernel unload facility. CSPICE continues to provide the original kernel loaders and unloaders, but you should use furnsh_c to load SPICE kernels. NAIF recommends that when loading multiple kernels, rather than sequential calls to furnsh_c, use a ``metakernel.'' A metakernel is a SPICE text kernel that lists the names of the kernels to load. At run time, the application supplies the name of the metakernel as an input argument to furnsh_c. For example, instead of loading kernels using the code fragment:
#include "SpiceUsr.h"
.
.
.
furnsh_c ( "leapseconds.ker" );
furnsh_c ( "mgs.tsc" );
furnsh_c ( "generic.bsp" );
furnsh_c ( "mgs.bc" );
furnsh_c ( "earth.bpc" );
furnsh_c ( "mgs.bes" );
one now may write
#include "SpiceUsr.h"
.
.
.
furnsh_c ( "kernels.txt" );
where the file kernels.txt is a SPICE text kernel containing the lines
\begindata
KERNELS_TO_LOAD = ( 'leapseconds.ker',
'mgs.tsc',
'generic.bsp',
'mgs.bc',
'earth.bpc',
'mgs.bes' )
This technique has the advantage of enabling a user to change the set of
kernels loaded by the application without modifying source code.
It also possible to use furnsh_c to load kernels in the older CSPICE style: the names of kernels to load can be supplied as input arguments to furnsh_c. For example, instead of using the series of loader calls shown earlier, one now may write
#include "SpiceUsr.h"
.
.
.
#define NKER 6
char * kernels[NKER] = { "leapseconds.ker",
"mgs.tsc",
"generic.bsp",
"mgs.bc",
"earth.bpc",
"mgs.bes" };
for ( int i = 0; i < NKER; i++ )
{
furnsh_c ( kernels[i] );
}
Kernel Priority
Path Symbols
PATH_VALUES PATH_SYMBOLSTo create symbols for path names, one assigns an array of path names to the variable PATH_VALUES. Next, one assigns an array of corresponding symbol names to the variable PATH_SYMBOLS. The nth symbol in the second array represents the nth path name in the first. Finally, one prefixes with path symbols the kernel names specified in the KERNELS_TO_LOAD variable. Each symbol is prefixed with a dollar sign to indicate that it is in fact a symbol. Suppose in our example above that the MGS kernels reside in the path
/flight_projects/mgs/SPICE_kernelsand the other kernels reside in the path
/generic/SPICE_kernelsThen we can add paths to our metakernel as follows:
\begindata
PATH_VALUES = ( '/flight_projects/mgs/SPICE_kernels',
'/generic/SPICE_kernels' )
PATH_SYMBOLS = ( 'MGS',
'GEN' )
KERNELS_TO_LOAD = ( '$GEN/leapseconds.ker',
'$MGS/mgs.tsc',
'$GEN/generic.bsp',
'$MGS/mgs.bc',
'$GEN/earth.bpc',
'$MGS/mgs.bes' )
It is not required that paths be abbreviated using path symbols; it's
simply a convenience.
Note the symbols defined here are not related to the symbols supported by a host shell or any other operating system interface. Keeping Track of Loaded Kernels
When a loaded kernel is loaded via furnsh_c, a new entry is created in the record of loaded kernels, whether or not the kernel is already loaded. All load or unload (see the discussion of unload_c below) operations affect the list of loaded files and therefore affect the results returned by the routines ktotal_c, kdata_c, and kinfo_c, all of which are discussed below under ``Finding Out What's Loaded.'' Reloading Kernels
The recommended method of increasing the priority of a loaded binary kernel, or of a metakernel containing binary kernels, is to unload it using unload_c (see below), then reload it using furnsh_c. This technique helps reduce clutter in furnsh_c's kernel list. Load Limits
The DAF/DAS handle manager system imposes its own lower limit on the number of DAF and DAS files that may be loaded simultaneously. This limit is currently set to a total of 1000 DAF and DAS files. Finding Out What's Loaded
CSPICE provides kernel access routines to support these needs. For every loaded kernel, an application can find the name of kernel, the kernel type (text or one of SPK, CK, PCK, or EK), the kernel's DAF or DAS handle if applicable, and the name of the metakernel used to load the kernel, again if applicable. The function ktotal_c returns the count of loaded kernels of a given type. The function kdata_c returns information on the nth kernel of a given type. The two functions are normally used together. Following is an example of how an application could retrieve summary information on the currently loaded SPK files:
#include <stdio.h>
#include "SpiceUsr.h"
#define FILLEN 128
#define TYPLEN 32
#define SRCLEN 128
SpiceInt which;
SpiceInt handle;
SpiceChar file [FILLEN];
SpiceChar filtyp[TYPLEN];
SpiceChar source[SRCLEN];
SpiceBoolean found;
.
.
.
ktotal_c ( "spk", &count );
if ( count == 0 )
{
printf ( "No SPK files loaded at this time.\n" );
}
else
{
printf ( "The loaded SPK files are: \n\n" );
}
for ( which = 0; which < count; which++ )
{
kdata_c ( which, "spk", FILLEN, TYPLEN, SRCLEN,
file, filtyp, &source, &handle, &found );
printf ( "%s\n", file );
}
Above, the input argument "spk" is a kernel type specifier. The allowed
set of values is
SPK --- All SPK files are counted in the total.
CK --- All CK files are counted in the total.
PCK --- All binary PCK files are counted in the
total.
EK --- All EK files are counted in the total.
TEXT --- All text kernels that are not meta-text
kernels are included in the total.
META --- All meta-text kernels are counted in the
total.
ALL --- Every type of kernel is counted in the
total.
In this example, filtyp is a string indicating the type of kernel.
handle is the file handle if the file is a binary SPICE kernel. source
is the name of the metakernel used to load the file, if applicable.
found indicates whether a file having the specified type and index was
found.
CSPICE also contains the function kinfo_c which returns summary information about a file whose name is already known. kinfo_c is called as follows:
kinfo_c ( file, TYPLEN, SRCLEN,
filtyp, source, &handle, &found );
Unloading Kernels
Text kernels and metakernels may be unloaded as well. Unloading a metakernel involves unloading the files referenced by the metakernel. Text kernels are unloaded by clearing the kernel pool and then reloading the other text kernels not designated for removal. Note that unloading text kernels has the side effect of wiping out kernel variables that have been set via the kernel pool's function write access interface. It is important to consider whether this side effect is acceptable when writing code that may unload text kernels or metakernels. unload_c is called as follows:
unload_c ( kernel );
Loading of Non-native Text and Binary Kernels
Environment Native End-Of-Line
Indicator
___________ _____________________
PC DOS/Windows <CR><LF>
Unix <LF>
Linux <LF>
Alpha Digital Unix <LF>
Mac OS X <LF>
Macintosh Classic (OS9) <CR>
As of CSPICE N0059, the CSPICE text kernel loaders, furnsh_c and
ldpool_c, can read and parse non-native text files. The FORTRAN SPICELIB
does not include this capability.
Please be aware the CSPICE text file reader, rdtext_c, does not possess the capability to read non-native text files. Starting with the N0052 release of the SPICE Toolkit (January, 2002) certain supported platforms are able to read DAF-based binary files (SPK, CK and binary PCK) that were written using a different, or non-native, binary representation. This access is read-only; any operations requiring writing to the file (adding information to the comment area, or appending additional ephemeris data, for example) require prior conversion of the file to the native binary file format. See the Convert User's Guide, CONVERT.UG, for details. Introduction of Text Kernels and Kernel Pool
The kernel pool system interface is composed of two parts: a text file format and kernel pool access software. The software includes functions that read files conforming to the format, routines that allow direct insertion of data into the pool via function calls, functions that fetch data from the kernel pool, functions that return information about the current state of the pool, and utilities that manipulate various aspects of the pool. The SPICE text kernel format has a ``name = value'' structure similar to the format used to assign values to variables in languages such as C and FORTRAN. Details of the format are described below. The kernel pool may be viewed abstractly as a repository of associative arrays which map names to lists of numeric or string values. The kernel pool allows CSPICE-based programs to read data from SPICE text kernel files while maintaining the ``name = value'' associations established in the files. Alternatively, associative arrays may be inserted into the kernel pool via the pool's programming interface. Once name-value associations have been stored in the kernel pool, you may access the stored data through kernel pool look-up functions. These look-up functions use the names as keys to find the associated values. The look-up and other access functions are described in detail below. The SPICE Text Kernel File Format
We illustrate this format by way of example using an excerpt from a SPICE text planetary constants kernel (PCK) file. The format description given below applies to all SPICE text kernels; the specific data names shown below apply only to text PCK files.
Planets first. Each has quadratic expressions for the direction
(RA, Dec) of the north pole and the rotation of the prime meridian.
Planets with satellites (except Pluto) also have linear expressions
for the auxiliary (phase) angles used in the nutation and libration
expressions of their satellites.
\begindata
BODY399_POLE_RA = ( 0. -0.64061614 -0.00008386 )
BODY399_POLE_DEC = ( +90. -0.55675303 +0.00011851 )
BODY399_PM = ( 10.21 +360.98562970 +0. )
BODY399_LONG_AXIS = ( 0. )
BODY3_NUT_PREC_ANGLES = ( 125.045 -1935.53
249.390 -3871.06
196.694 -475263.
176.630 +487269.65
358.219 -36000. )
\begintext
Each satellite has similar quadratic expressions for the pole and
prime meridian. In addition, some satellites have nonzero nutation
and libration amplitudes. (The number of amplitudes matches the
number of auxiliary phase angles of the primary.)
\begindata
BODY301_POLE_RA = ( 270.000 -0.64061614 -0.00008386 )
BODY301_POLE_DEC = ( +66.534 -0.55675303 +0.00011851 )
BODY301_PM = ( 38.314 +13.1763581 0. )
BODY301_LONG_AXIS = ( 0. )
BODY301_NUT_PREC_RA = ( -3.878 -0.120 +0.070 -0.017 0. )
BODY301_NUT_PREC_DEC = ( +1.543 +0.024 -0.028 +0.007 0. )
BODY301_NUT_PREC_PM = ( +3.558 +0.121 -0.064 +0.016 +0.025 )
\begintext
Finally, we include the radii of the satellites and planets.
\begindata
BODY399_RADII = ( 6378.140 6378.140 6356.755 )
BODY301_RADII = ( 1738. 1738. 1738. )
In this example are several comment blocks. All are introduce by the
control word:
\begintextA comment block may contain any number of comment lines. Once a comment block has begun, no special characters are required to introduce subsequent lines of comments within that block. A comment block is terminated by the control word
\begindataThis control word also serves to introduce a block of data that will be stored in the kernel pool. Each of these control words must appear on a line by itself. Each variable definition consists of three components:
Direct assignments supersede previous assignments, whereas incremental assignments are added to previous assignments. For example, the series of assignments
BODY301_NUT_PREC_RA = -3.878 BODY301_NUT_PREC_RA += -0.120 BODY301_NUT_PREC_RA += +0.070 BODY301_NUT_PREC_RA += -0.017 BODY301_NUT_PREC_RA += 0.has the same effect as the single assignment
BODY301_NUT_PREC_RA = ( -3.878 -0.120 +0.070 -0.017 0 )Dates, e.g.,
FOOBAR_CALIBRATION_DATES = ( @31-JAN-1987,
@2/4/87,
@March-7-1987-3:10:39.221 )
may be entered in a wide variety of formats. There are two restrictions
regarding the format of dates. They may not contain embedded blanks, and
they must begin with the character
@Internally, dates are converted to TDB seconds past J2000 as they are read. As a result, dates, are treated as numeric data in the pool. Strings may be supplied by quoting the string value.
MISSION_UNITS = ( 'KILOMETERS',
'SECONDS',
'KILOMETERS/SECOND' )
If you need to include a quote in the string value, use the FORTRAN
convention of "doubling" the quote.
MESSAGE = ( 'You can''t always get what you want.' )The maximum length of as string that can be assigned as the value of a scalar kernel variable, or as an element of an array-valued kernel variable, is 80 characters. The types of values assigned to a kernel pool variable must all be the same. If you attempt to make an assignment such as the one shown here:
ERROR_EXAMPLE = ( 1, 2, 'THREE', 4, 'FIVE' )The kernel pool reader will regard the assignment as erroneous and reject it and any subsequent kernel pool assignments that appear in the text kernel. String Continuation
//is used as a continuation mark, the assignment
CONTINUED_STRINGS = ( 'This // ',
'is // ',
'just //',
'one long //',
'string.',
'Here''s a second //',
'continued //'
'string.' )
allows the string array elements on the right hand side of the
assignment to be treated as the two strings
This is just one long string. Here's a second continued string.The CSPICE function stpool_c provides the capability of retrieving continued strings from the kernel pool. See the discussion below under ``Fetching Data from the Kernel Pool'' or the header of stpool_c for further information. Fetching Data from the Kernel Pool
\literal gcpool_c( name, first, room, lenout, nvalues, values, found ); gdpool_c( name, first, room, nvalues, values, found ); gipool_c( name, first, room, nvalues, values, found ); stpool_c( name, nth, contin, lenout, string, size, found );The meanings of the arguments are as follows:
Informational Functions
Changing Kernel Pool Contents
Below, buffer is a character array and n is the size of the array.
#include "SpiceUsr.h"
.
.
.
#define LNSIZE 81
#define BUFSIZE 28
static SpiceChar text [BUFSIZE][LNSIZE] =
{
"DELTET/DELTA_T_A = 32.184",
"DELTET/K = 1.657D-3",
"DELTET/EB = 1.671D-2",
"DELTET/M = ( 6.239996D0",
" 1.99096871D-7 )",
"DELTET/DELTA_AT = ( 10, @1972-JAN-1",
" 11, @1972-JUL-1",
" 12, @1973-JAN-1",
" 13, @1974-JAN-1",
" 14, @1975-JAN-1",
" 15, @1976-JAN-1",
" 16, @1977-JAN-1",
" 17, @1978-JAN-1",
" 18, @1979-JAN-1",
" 19, @1980-JAN-1",
" 20, @1981-JUL-1",
" 21, @1982-JUL-1",
" 22, @1983-JUL-1",
" 23, @1985-JUL-1",
" 24, @1988-JAN-1",
" 25, @1990-JAN-1",
" 26, @1991-JAN-1",
" 27, @1992-JUL-1",
" 28, @1993-JUL-1",
" 29, @1994-JUL-1",
" 30, @1996-JAN-1",
" 31, @1997-JUL-1",
" 32, @1999-JAN-1)"
};
/*
Add the contents of the buffer to the kernel pool:
*/
lmpool_c ( text, BUFSIZE );
Detecting Changes in the Kernel Pool
SPICE Subsystems that Rely on SPICE Text KernelsPCK-related Functions
Time Conversion Functions
Frame Transformation Functions
Instrument Description Functions
Summary of Functions
bodfnd_c ( Find values from the kernel pool ) bodvar_c ( Return values from the kernel pool ) clpool_c ( Clear the pool of kernel variables ) cvpool_c ( Check variable in the pool for update ) dtpool_c ( Data for a kernel pool variable ) dvpool_c ( Delete a variable from the kernel pool ) expool_c ( Confirm the existence of a pool kernel variable ) furnsh_c ( Furnish a program with SPICE kernels ) gcpool_c ( Get character data from the kernel pool ) gdpool_c ( Get d.p. values from the kernel pool ) getfov_c ( Get instrument FOV configuration ) gipool_c ( Get integers from the kernel pool ) gnpool_c ( Get names of kernel pool variables ) kdata_c ( Kernel Data ) kinfo_c ( Kernel Information ) ktotal_c ( Kernel Totals ) ldpool_c ( Load variables from a kernel file into the pool ) lmpool_c ( Load variables from memory into the pool ) pcpool_c ( Put character strings into the kernel pool ) pdpool_c ( Put d.p.'s into the kernel pool ) pipool_c ( Put integers into the kernel pool ) stpool_c ( String from pool ) swpool_c ( Set watch on a pool variable ) szpool_c ( Get size limitations of the kernel pool) unload_c ( Unload a kernel ) Summary of Calling Sequences
bodfnd_c ( body, item ) bodvar_c ( body, item, &dim, values ) clpool_c () cvpool_c ( agent, &update ) dtpool_c ( name, &found, &n, type [1] ) dvpool_c ( name ) expool_c ( name, &found ) furnsh_c ( file ) gcpool_c ( name, start, room, lenout, &n, cvals, &found ) gdpool_c ( name, start, room, &n, dvals, &found ) getfov_c ( instid, room, shapelen, framelen, shape, frame, bsight, &n, bounds ) gipool_c ( name, start, room, &n, ivals, &found ) gnpool_c ( name, start, room, lenout, &n, kvars, &found ) kdata_c ( which, kind, fillen, typlen, srclen, file, filtyp, source, &handle, &found ) kinfo_c ( file, typlen, srclen, filtyp, source, &handle, &found ) ktotal_c ( kind, &count ) ldpool_c ( filename ) lmpool_c ( cvals, lenvals, n ) pcpool_c ( name, n, lenvals, cvals ) pdpool_c ( name, n, dvals ) pipool_c ( name, n, ivals ) stpool_c ( item, nth, contin, lenout, string, &size, &found ) swpool_c ( agent, nnames, lenvals, names ) szpool_c ( name, &n, &found ) unload_c ( file ) |