void furnsh_c ( ConstSpiceChar * file )
Load one or more SPICE kernels into a program.
None.
UTILITY
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
file I Name of SPICE kernel file (text or binary).
file is the name of a SPICE kernel file. The file may be
either binary or text. If the file is a binary SPICE
kernel it will be loaded into the appropriate SPICE
subsystem. If `file' is a SPICE text kernel it will be
loaded into the kernel pool. If `file' is a SPICE
meta-kernel containing initialization instructions
(through use of the correct kernel pool variables), the
files specified in those variables will be loaded into
the appropriate SPICE subsystem.
The SPICE text kernel format supports association of
names and data values using a "keyword = value" format.
The keyword-value pairs thus defined are called "kernel
variables."
While any information can be placed in a text kernel
file, the following string valued kernel variables are
recognized by SPICE as meta-kernel keywords:
KERNELS_TO_LOAD
PATH_SYMBOLS
PATH_VALUES
Each kernel variable is discussed below.
KERNELS_TO_LOAD is a list of SPICE kernels to be
loaded into a program. If file
names do not fit within the kernel
pool 80 character limit, they may be
continued to subsequent array
elements by placing the continuation
character ('+') at the end of an
element and then placing the
remainder of the file name in the
next array element. (See the
examples below for an illustration
of this technique or consult the
routine stpool_c for further
details.)
Alternatively you may use a
PATH_SYMBOL (see below) to
substitute for some part of a file
name.
PATH_SYMBOLS is a list of strings (without
embedded blanks), which if
encountered following the '$'
character will be replaced with the
corresponding PATH_VALUES string.
Note that PATH_SYMBOLS are
interpreted only in the
KERNELS_TO_LOAD variable. There must
be a one-to-one correspondence
between the values supplied for
PATH_SYMBOLS and PATH_VALUES.
PATH_VALUES is a list of expansions to use when
PATH_SYMBOLS are encountered. See
the examples section for an
illustration of use of PATH_SYMBOLS
and PATH_VALUES.
These kernel pool variables persist within the kernel
pool only until all kernels associated with the
variable KERNELS_TO_LOAD have been loaded. Once all
specified kernels have been loaded, the variables
KERNELS_TO_LOAD, PATH_SYMBOLS and PATH_VALUES are
removed from the kernel pool.
None. The routine loads various SPICE kernels for use by your
application.
None.
1) If a problem is encountered while trying to load `file', it will
be diagnosed by a routine from the appropriate SPICE subsystem.
2) If the input `file' is a meta-kernel and some file in
the KERNELS_TO_LOAD assignment cannot be found, the error
SPICE(CANTFINDFILE) will be signaled and the routine will
return. Any files loaded prior to encountering the missing
file will remain loaded.
3) If an error is encountered while trying to load one of the files
specified by the KERNELS_TO_LOAD assignment, the routine will
discontinue attempting to perform any other tasks and return.
4) If a PATH_SYMBOLS assignment is specified without a corresponding
PATH_VALUES assignment, the error SPICE(NOPATHVALUE) will be
signaled.
5) If a meta-kernel is supplied that contains instructions
specifying that another meta-text kernel be loaded, the error
SPICE(RECURSIVELOADING) will be signaled.
6) If the input `file' argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
7) If the input `file' argument is the empty string, the error
SPICE(EMPTYSTRING) will be signaled.
6) The error 'SPICE(BADVARNAME)' signals if the a pool
variable name length exceeds 32.
The input file is examined and loaded into the appropriate
SPICE subsystem. If the file is a meta-kernel, any kernels
specified by the KERNELS_TO_LOAD keyword (and if present,
the PATH_SYMBOLS and PATH_VALUES keywords) are loaded as well.
This routine provides a uniform interface to the SPICE kernel
loading systems. It allows you to easily assemble a list of
SPICE kernels required by your application and to modify that set
without modifying the source code of programs that make use of
these kernels.
Text kernels input to this routine need not have native line
terminators for the platform. Lower level CSPICE routines can
read and process non-native text files. This functionality does
not exist in the Fortran SPICELIB.
Only text kernel readers include the non-native read capability,
(ldpool_c and furnsh_c), the generic text file line reader, rdtext_c
requires native text files.
Please refer to kernel.req for additional information.
Kernel pool variable names are restricted to a length of 32
characters or less.
Example 1
---------
Load the leapseconds kernel naif0007.tls and the planetary ephemeris
SPK file de405s.bsp.
furnsh_c ( "naif0007.tls" );
furnsh_c ( "de405s.bsp" );
Example 2
---------
This example illustrates how you could create a meta-kernel file for
a program that requires several text and binary kernels.
First create a list of the kernels you need in a text file as
shown below.
\begintext
Here are the SPICE kernels required for my application
program.
Note that kernels are loaded in the order listed. Thus we
need to list the highest priority kernel last.
\begindata
KERNELS_TO_LOAD = ( '/home/mydir/kernels/spk/lowest_priority.bsp',
'/home/mydir/kernels/spk/next_priority.bsp',
'/home/mydir/kernels/spk/highest_priority.bsp',
'/home/mydir/kernels/text/leapsecond.ker',
'/home/mydir/kernels+',
'/custom+',
'/kernel_data/constants.ker',
'/home/mydir/kernels/text/sclk.tsc',
'/home/mydir/kernels/ck/c-kernel.bc' )
Note that the file name
/home/mydir/kernels/custom/kernel_data/constants.ker
is continued across several lines in the right hand side of the
assignment of the kernel variable KERNELS_TO_LOAD.
Once you've created your list of kernels, call furnsh_c near the
beginning of your application program to load the meta-kernel
automatically at program start up.
furnsh_c ( "myfile.txt" );
This will cause each of the kernels listed in your meta-kernel
to be loaded.
Example 3
---------
This example illustrates how you can simplify the previous
kernel list by using PATH_SYMBOLS.
\begintext
Here are the SPICE kernels required for my application
program.
We are going to let A substitute for the directory that
contains SPK files; B substitute for the directory that
contains C-kernels; and C substitute for the directory that
contains text kernels. And we'll let D substitute for
a "custom" directory that contains a special planetary
constants kernel made just for our mission.
Note that the order in which we list our PATH_VALUES must be
the same order that the corresponding PATH_SYMBOLS are
listed.
\begindata
PATH_VALUES = ( '/home/mydir/kernels/spk',
'/home/mydir/kernels/ck',
'/home/mydir/kernels/text',
'/home/mydir/kernels/custom/kernel_data' )
PATH_SYMBOLS = ( 'A',
'B',
'C'
'D' )
KERNELS_TO_LOAD = ( '$A/lowest_priority.bsp',
'$A/next_priority.bsp',
'$A/highest_priority.bsp',
'$C/leapsecond.ker',
'$D/constants.ker',
'$C/sclk.tsc',
'$B/c-kernel.bc' )
None.
None.
C.H. Acton (JPL)
N.J. Bachman (JPL)
W.L. Taber (JPL)
-CSPICE Version 1.3.2, 10-FEB-2010 (EDW)
Corrected header section order. Added mention of the
restriction on kernel pool variable names to 32 characters
or less.
-CSPICE Version 1.0.4, 17-OCT-2005 (EDW)
Added text to Particulars section informing of the
non-native kernel text file reading capability.
-CSPICE Version 1.0.3, 29-JUL-2003 (NJB) (CHA)
Numerous updates to improve clarity. Some corrections
were made.
-CSPICE Version 1.0.2, 03-JUL-2002 (NJB)
Documentation fix: corrected second code example. The example
previously used the kernel variable PATH_NAMES; that name has been
replaced with the correct name PATH_VALUES.
-CSPICE Version 1.0.1, 13-APR-2000 (NJB)
Replaced single quotes with double quotes in a code example.
-CSPICE Version 1.0.0, 01-SEP-1999 (NJB) (WLT)
Load SPICE data from a list of items
Link to routine furnsh_c source file furnsh_c.c
|