Table of contents
CSPICE_EKLEF loads an EK file, making it accessible to the EK readers.
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.
None.
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
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.
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.
See description of `fname' in -I/O.
1) EK files containing columns having the same name but
inconsistent declarations are not diagnosed. Such kernels
are invalid in any case.
EK.REQ
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-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)
load EK file
load E-Kernel
|