| eklef_c |
|
Table of contents
Procedure
eklef_c ( EK, load event file )
void eklef_c ( ConstSpiceChar * fname,
SpiceInt * handle )
AbstractLoad an EK file, making it accessible to the EK readers. Required_ReadingEK KeywordsEK FILES SEARCH Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- fname I Name of EK file to load. handle O File handle of loaded EK file. Detailed_Inputfname is the name of a binary EK file to be loaded. Detailed_Output
handle is the handle of the EK file. The file is
accessible by the EK reader routines once it
has been loaded.
ParametersNone. 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 `fname' input string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
12) If the `fname' input string has zero length, the error
SPICE(EMPTYSTRING) is signaled.
FilesSee description of `fname' in -Detailed_Input. ParticularsThis 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. Examples
The numerical results shown for these examples may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, 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.
/.
Program eklef_ex1
./
#include <stdio.h>
#include "SpiceUsr.h"
int main( )
{
/.
Local parameters.
./
#define EKNMLN 18
#define ERRLEN 1841
/.
Local variables
./
SpiceChar errmsg [ERRLEN];
SpiceChar * query;
SpiceInt handle;
SpiceInt i;
SpiceInt nmrows;
SpiceBoolean error;
/.
Set up the array holding the EK file names.
./
SpiceChar eknams [2][EKNMLN] = {
"S78_CIMSSSUPa.bep", "S79_CIMSSSUPa.bep" };
/.
Load the EK files. This call could be replaced by a call
to furnsh_c (in this case, a meta-kernel listing the EKs
to be loaded could also be used).
./
for ( i = 0; i < 2; i++ )
{
eklef_c ( eknams[i], &handle );
printf( "Loading EK: %s\n", eknams[i] );
}
/.
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.
./
ekfind_c ( query, ERRLEN, &nmrows, &error, errmsg );
/.
Check whether an error occurred while processing the
SELECT clause. If so, output the error message.
./
printf( "\n" );
if ( error )
{
printf( "SELECT clause error: %s\n", errmsg );
}
else
{
/.
If no error, `nmrows' contains the number of rows
matching the constraints specified in the query
string.
./
printf( "Number of matching rows: %2d\n", nmrows );
}
return ( 0 );
}
When this program was executed on a Mac/Intel/cc/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.
/.
Program eklef_ex2
./
#include <stdio.h>
#include "SpiceUsr.h"
int main( )
{
/.
Local parameters.
./
#define EKNMLN 18
#define ERRLEN 1841
/.
Local variables
./
SpiceChar errmsg [ERRLEN];
SpiceChar * query;
SpiceInt handle;
SpiceInt i;
SpiceInt nmrows;
SpiceBoolean error;
/.
Set up the array holding the EK file names.
./
SpiceChar eknams [2][EKNMLN] = {
"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 furnsh_c.
./
for ( i = 0; i < 2; i++ )
{
eklef_c ( eknams[i], &handle );
printf( "Loading EK: %s\n", eknams[i] );
/.
Query the EK system for data rows matching the
SELECT constraints.
./
ekfind_c ( query, ERRLEN, &nmrows, &error, errmsg );
/.
Check whether an error occurred while processing the
SELECT clause. If so, output the error message.
./
if ( error )
{
printf( "SELECT clause error: %s\n", errmsg );
}
else
{
/.
If no error, `nmrows' contains the number of rows
matching the constraints specified in the query
string.
./
printf( "Number of matching rows: %2d\n", nmrows );
}
/.
Unload the current file. Unloading files prevents
them from being searched during query execution.
./
ekuef_c ( handle );
printf( "Unloading EK: %s\n", eknams[i] );
printf( "\n" );
}
return ( 0 );
}
When this program was executed on a Mac/Intel/cc/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
Restrictions
1) EK files containing columns having the same name but
inconsistent declarations are not diagnosed. Such kernels
are invalid in any case.
Literature_ReferencesNone. Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) Version
-CSPICE Version 1.0.1, 10-AUG-2021 (NJB) (JDR)
Edited the header to comply with NAIF standard. Added complete
code examples based on existing fragments.
-CSPICE Version 1.0.0, 26-MAR-1998 (NJB)
Based on SPICELIB Version 1.0.1, 07-JUL-1996 (NJB)
Index_Entriesload EK file load E-Kernel |
Fri Dec 31 18:41:06 2021