Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
cspice_eklef

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_EKLEF loads an EK file, making it accessible to the EK readers.

I/O


   Given:

      fname    the name of a binary EK file to be loaded.

               help, fname
                  STRING = Scalar

   the call:

      cspice_eklef, fname, handle

   returns:

      handle   the handle of the EK file.

               help, handle
                  LONG = Scalar

               The file is accessible by the EK reader routines once it has
               been loaded.

Parameters


   None.

Examples


   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 two EK files and perform a query on them. During query
      execution, all files will be searched.

      Use the EK kernel below to load the Cassini Science Plan
      SPICE E-Kernel File based upon the integrated science
      plan #78.

         S78_CIMSSSUPa.bep

      Use the EK kernel below to load the data based upon the
      integrated science plan #79.

         S79_CIMSSSUPa.bep


      Example code begins here.


      PRO eklef_ex1

         ;;
         ;; Set up the array holding the EK file names.
         ;;
         eknams = ['S78_CIMSSSUPa.bep', 'S79_CIMSSSUPa.bep']

         ;;
         ;; Load the EK files. This call could be replaced by a call
         ;; to cspice_furnsh (in this case, a meta-kernel listing the EKs
         ;; to be loaded could also be used).
         ;;
         for i=0L, 1L do begin

            cspice_eklef, eknams[i], handle
            print, format='(2A)', 'Loading EK: ', eknams[i]

         endfor

         ;;
         ;; The EK files contain a table 'CASSINI_SP_OBSERVATION',
         ;; that contains columns named:
         ;;
         ;;    NOTES, OBSERVATION_ID, OBSERVATION_TITLE,
         ;;    OBS_DESCRIPTION, SCIENCE_OBJECTIVE, SEQUENCE,
         ;;    SUBSYSTEM
         ;;
         ;; Define a set of constraints to perform a query on all
         ;; loaded EK files (the SELECT clause).
         ;;
         query  = 'Select SUBSYSTEM, SCIENCE_OBJECTIVE, OBSERVATION_ID ' +   $
                  'from CASSINI_SP_OBSERVATION order by SUBSYSTEM'

         ;;
         ;; Query the EK system for data rows matching the
         ;; SELECT constraints.
         ;;
         cspice_ekfind, query, nmrows, error, errmsg

         ;;
         ;; Check whether an error occurred while processing the
         ;; SELECT clause. If so, output the error message.
         ;;
         print
         if ( error ) then begin

            print, format='(2A)', 'SELECT clause error: ', errmsg

         endif else begin

            ;;
            ;; If no error, `nmrows' contains the number of rows
            ;; matching the constraints specified in the query
            ;; string.
            ;;
            print, format='(A,I3)', 'Number of matching rows: ', nmrows

         endelse

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Loading EK: S78_CIMSSSUPa.bep
      Loading EK: S79_CIMSSSUPa.bep

      Number of matching rows:   9


   2) Repeat the previous exercise, using the same input kernels,
      but this time unloading the previous file before each new
      file is loaded. Unloading files prevents them from being
      searched during query execution.


      Example code begins here.


      PRO eklef_ex2

         ;;
         ;; Set up the array holding the EK file names.
         ;;
         eknams = ['S78_CIMSSSUPa.bep', 'S79_CIMSSSUPa.bep']

         ;;
         ;; The EK files contain a table 'CASSINI_SP_OBSERVATION',
         ;; that contains columns named:
         ;;
         ;;    NOTES, OBSERVATION_ID, OBSERVATION_TITLE,
         ;;    OBS_DESCRIPTION, SCIENCE_OBJECTIVE, SEQUENCE,
         ;;    SUBSYSTEM
         ;;
         ;; Define a set of constraints to perform a query on all
         ;; loaded EK files (the SELECT clause).
         ;;
         query  = 'Select SUBSYSTEM, SCIENCE_OBJECTIVE, OBSERVATION_ID ' +   $
                  'from CASSINI_SP_OBSERVATION order by SUBSYSTEM'

         ;;
         ;; Load the EK files. This call could be replaced by a call
         ;; to cspice_furnsh.
         ;;
         for i=0L, 1L do begin

            cspice_eklef, eknams[i], handle
            print, format='(2A)', 'Loading EK: ', eknams[i]

            ;;
            ;; Query the EK system for data rows matching the
            ;; SELECT constraints.
            ;;
            cspice_ekfind, query, nmrows, error, errmsg

            ;;
            ;; Check whether an error occurred while processing the
            ;; SELECT clause. If so, output the error message.
            ;;
            if ( error ) then begin

               print, format='(2A)', 'SELECT clause error: ', errmsg

            endif else begin

               ;;
               ;; If no error, `nmrows' contains the number of rows
               ;; matching the constraints specified in the query
               ;; string.
               ;;
               print, format='(A,I3)', 'Number of matching rows: ', nmrows

            endelse

            ;;
            ;; Unload the current file. Unloading files prevents
            ;; them from being searched during query execution.
            ;;
            cspice_ekuef, handle
            print, format='(2A)', 'Unloading EK: ', eknams[i]
            print

         endfor

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Loading EK: S78_CIMSSSUPa.bep
      Number of matching rows:   4
      Unloading EK: S78_CIMSSSUPa.bep

      Loading EK: S79_CIMSSSUPa.bep
      Number of matching rows:   5
      Unloading EK: S79_CIMSSSUPa.bep


Particulars


   This routine makes EK files known to the EK system. It is
   necessary to load EK files using this routine in order to
   query the files using the EK readers.

   Note: This routine has been superseded by cspice_furnsh.

Exceptions


   1)  If the EK file indicated by `fname' contains a column whose name
       matches that of a column in an already loaded EK, but whose
       declared attributes don't match those of the loaded column of
       the same name, the error SPICE(BADATTRIBUTES) is signaled by a
       routine in the call tree of this routine. `handle' is is
       undefined in this case.

   2)  Loading an EK file that is already loaded does not cause side
       effects. The handle already associated with the file will be
       returned.

   3)  If a file open error occurs, the error is signaled by a
       routine in the call tree of this routine. `handle' is undefined
       in this case.

   4)  If loading the input file would cause the maximum number of
       loaded EK files to be exceeded, the error
       SPICE(EKFILETABLEFULL) is signaled by a routine in the call
       tree of this routine. `handle' is undefined in this case. This
       routine will attempt to unload the file from the DAS system.

   5)  If loading the input file would cause the maximum number of
       loaded DAS files to be exceeded, an error is signaled by a
       routine in the call tree of this routine. `handle' is undefined
       in this case. This routine will attempt to unload the file
       from the DAS system.

   6)  If loading the input file would cause the maximum number of
       segments allowed in loaded EK files to be exceeded, the error
       SPICE(EKSEGMENTTABLEFULL) is signaled by a routine in the call
       tree of this routine. `handle' is undefined in this case. This
       routine will attempt to unload the file from the DAS system.

   7)  If loading the input file would cause the maximum number of
       columns allowed in loaded EK files to be exceeded, the error
       SPICE(EKCOLDESCTABLEFULL) is signaled by a routine in the call
       tree of this routine. `handle' is undefined in this case. This
       routine will attempt to unload the file from the DAS system.

   8)  If loading the input file would cause the maximum allowed
       number of columns having distinct attributes in loaded EK
       files to be exceeded, the error SPICE(EKCOLATTRTABLEFULL) is
       signaled by a routine in the call tree of this routine. `handle'
       is undefined in this case. This routine will attempt to unload
       the file from the DAS system.

   9)  If loading the input file would cause the maximum number of
       instrument codes allowed in loaded EK files to be exceeded,
       the error SPICE(EKIDTABLEFULL) is signaled by a routine in the
       call tree of this routine. `handle' is undefined in this case.
       This routine will attempt to unload the file from the DAS
       system.

   10) If the input file does not contain at least one segment, the
       error SPICE(EKNOSEGMENTS) is signaled by a routine in the call
       tree of this routine.

   11) If the input argument `fname' is undefined, an error is
       signaled by the IDL error handling system.

   12) If the input argument `fname' is not of the expected type, or
       it does not have the expected dimensions and size, an error is
       signaled by the Icy interface.

   13) If the output argument `handle' is not a named variable, an
       error is signaled by the Icy interface.

Files


   See description of `fname' in -I/O.

Restrictions


   1)  EK files containing columns having the same name but
       inconsistent declarations are not diagnosed. Such kernels
       are invalid in any case.

Required_Reading


   EK.REQ
   ICY.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.1, 17-JUN-2021 (JDR)

       Edited the header to comply with NAIF standard. Added complete
       code examples based on existing fragments.

       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)

Index_Entries


   load EK file
   load E-Kernel



Fri Dec 31 18:43:04 2021