Index Page furnsh_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void furnsh_c ( ConstSpiceChar  * file )
#### Abstract
       Load one or more SPICE kernels into a program.
#### Required_Reading
        None.
#### Keywords
        UTILITY
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       file       I   Name of SPICE kernel file (text or binary).
#### Detailed_Input
       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.
#### Detailed_Output
       None. The routine loads various SPICE kernels for use by your
       application.
#### Parameters
       None.
#### Exceptions
       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, or if an error
          occurs while trying to load a file specified by this
          assignment, the error will be diagnosed by a routine in the
          call tree of this routine, and this routine will return. Any
          files loaded prior to encountering the failure, including
          those referenced by the KERNELS_TO_LOAD assignment, will
          remain loaded.

       3) If an attempt to load a text kernel fails while the kernel is
          being parsed, any kernel variable assignments made before
          the failure occurred will be retained in the kernel pool.

       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.

       8) The error SPICE(BADVARNAME) signals if the a pool
          variable name length exceeds 32.
#### Files
       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.

       In this version of the toolkit the maximum number of kernels that
       can loaded together is limited to 5300. Each time a kernel is loaded
       via furnsh_c, an internal kernel database entry is created for that
       kernel. If a meta-kernel is loaded, a database entry is created for
       the meta-kernel itself and for all files referenced in the
       meta-kernel's KERNELS_TO_LOAD specification. Unloading a kernel or
       meta-kernel deletes database entries created when the file was
       loaded.

       The value above is an upper bound on number of SPICE kernels that
       can be loaded at any time via the furnsh_c interface, but the number
       of kernels that can be loaded may be smaller, since re-loading a
       loaded kernel or meta-kernel results in creation of additional
       database entries.

       Kernels loaded via furnsh_c are subject to constraints imposed by
       lower-level subsystems. The binary kernel systems (SPK, CK, binary
       PCK, EK, and DSK) have their own limits on the maximum number of
       kernels that may be loaded.

       The total number of DAF-based files (this set includes SPKs, CKs,
       and binary PCKs) and DAS-based files (this set includes EKs and
       DSKs) that may be loaded at any time may not exceed 5000. This
       limit applies whether the files are loaded via furnsh_c or
       lower-level loaders such as spklef_c or dafopr_c. File access
       performance normally will degrade slightly as the number of loaded
       kernels increases.
#### Particulars
       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.
#### Examples
       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'         )
#### Restrictions
       1) A meta-kernel cannot reference another meta-kernel.

       2) Failure during an attempt to load a text kernel or a
          meta-kernel can result in a subset of the intended kernel
          variables being set or a subset of the intended files
          being loaded. furnsh_c does not "clean up" so as to undo the
          effects of a failed load operation.
#### Literature_References
       None.
#### Author_and_Institution
       C.H. Acton      (JPL)
       N.J. Bachman    (JPL)
       B.V. Semenov    (JPL)
       W.L. Taber      (JPL)
#### Version
       -CSPICE Version 1.3.4, 01-FEB-2017 (BVS)

          Updated discussion in the Files section to mention the maximum
          number of kernels that can be loaded together.

       -CSPICE Version 1.3.3, 01-JUL-2014 (NJB)

          Updated discussion of partially completed kernel loading.

       -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)
#### Index_Entries
       Load SPICE data from a list of items
#### Link to routine furnsh_c source file furnsh_c.c

    Wed Apr  5 17:54:35 2017