Procedure

     EKLEF ( EK, load event file )

     ENTRY EKLEF ( FNAME, HANDLE )

Abstract

     Load an EK file, making it accessible to the EK readers.

Required_Reading

     EK

Keywords

     EK
     FILES
     SEARCH

Declarations

    CHARACTER*(*)         FNAME
    INTEGER               HANDLE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     FNAME      I   Name of EK file to load.
     HANDLE     O   File handle of loaded EK file.

Detailed_Input

     FNAME    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.

Parameters

     None.

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. 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. 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. 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. 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. 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. 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.

Files

     See description of FNAME in $Detailed_Input.

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.

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
              IMPLICIT NONE

        C
        C     Include the EK Maximum length of an input query,
        C     MAXQRY.
        C
              INCLUDE 'ekqlimit.inc'

        C
        C     Local parameters.
        C
              INTEGER               EKNMLN
              PARAMETER           ( EKNMLN = 17 )

              INTEGER               ERRLEN
              PARAMETER           ( ERRLEN = 1840 )

        C
        C     Local variables
        C
              CHARACTER*(EKNMLN)    EKNAMS ( 2 )
              CHARACTER*(ERRLEN)    ERRMSG
              CHARACTER*(MAXQRY)    QUERY

              INTEGER               HANDLE
              INTEGER               I
              INTEGER               N
              INTEGER               NMROWS

              LOGICAL               ERROR

        C
        C     Set up the array holding the EK file names.
        C
              DATA                  EKNAMS / 'S78_CIMSSSUPa.bep',
             .                               'S79_CIMSSSUPa.bep'  /

        C
        C     Load the EK files. This call could be replaced by a call
        C     to FURNSH (in this case, a meta-kernel listing the EKs
        C     to be loaded could also be used).
        C
              DO I = 1, 2

                 CALL EKLEF ( EKNAMS(I), HANDLE )
                 WRITE(*,'(2A)') 'Loading EK: ', EKNAMS(I)

              END DO

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

        C
        C     Query the EK system for data rows matching the
        C     SELECT constraints.
        C
              CALL EKFIND ( QUERY, NMROWS, ERROR, ERRMSG )

        C
        C     Check whether an error occurred while processing the
        C     SELECT clause. If so, output the error message.
        C
              WRITE(*,*)
              IF ( ERROR ) THEN

                 WRITE(*,'(2A)') 'SELECT clause error: ', ERRMSG

              ELSE

        C
        C        If no error, NMROWS contains the number of rows
        C        matching the constraints specified in the query
        C        string.
        C
                 WRITE(*,'(A,I3)') 'Number of matching rows: ', NMROWS

              END IF


              END


        When this program was executed on a Mac/Intel/gfortran/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
              IMPLICIT NONE

        C
        C     Include the EK Maximum length of an input query,
        C     MAXQRY.
        C
              INCLUDE 'ekqlimit.inc'

        C
        C     Local parameters.
        C
              INTEGER               EKNMLN
              PARAMETER           ( EKNMLN = 17 )

              INTEGER               ERRLEN
              PARAMETER           ( ERRLEN = 1840 )

        C
        C     Local variables
        C
              CHARACTER*(EKNMLN)    EKNAMS ( 2 )
              CHARACTER*(ERRLEN)    ERRMSG
              CHARACTER*(MAXQRY)    QUERY

              INTEGER               HANDLE
              INTEGER               I
              INTEGER               N
              INTEGER               NMROWS

              LOGICAL               ERROR

        C
        C     Set up the array holding the EK file names.
        C
              DATA                  EKNAMS / 'S78_CIMSSSUPa.bep',
             .                               'S79_CIMSSSUPa.bep'  /

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

        C
        C     Load the EK files. This call could be replaced by a call
        C     to FURNSH.
        C
              DO I = 1, 2

                 CALL EKLEF ( EKNAMS(I), HANDLE )
                 WRITE(*,'(2A)') 'Loading EK: ', EKNAMS(I)

        C
        C        Query the EK system for data rows matching the
        C        SELECT constraints.
        C
                 CALL EKFIND ( QUERY, NMROWS, ERROR, ERRMSG )

        C
        C        Check whether an error occurred while processing the
        C        SELECT clause. If so, output the error message.
        C
                 IF ( ERROR ) THEN

                    WRITE(*,'(2A)') 'SELECT clause error: ', ERRMSG

                 ELSE

        C
        C           If no error, NMROWS contains the number of rows
        C           matching the constraints specified in the query
        C           string.
        C
                    WRITE(*,'(A,I3)') 'Number of matching rows: ',
             .                        NMROWS

                 END IF

        C
        C        Unload the current file. Unloading files prevents
        C        them from being searched during query execution.
        C
                 CALL EKUEF ( HANDLE )
                 WRITE(*,'(2A)') 'Unloading EK: ', EKNAMS(I)
                 WRITE(*,*)

              END DO


              END


        When this program was executed on a Mac/Intel/gfortran/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_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)

Version

    SPICELIB Version 2.2.0, 06-JUL-2021 (JDR)

        Added IMPLICIT NONE statement.

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

    SPICELIB Version 2.1.0, 09-FEB-2015 (NJB)

        Now uses ERRHAN to insert DAS file name into
        long error messages.

    SPICELIB Version 2.0.0, 16-NOV-2001 (NJB)

        Bug fix: When an already loaded kernel is opened with EKOPR,
        it now has its link count reset to 1 via a call to EKCLS.

    SPICELIB Version 1.0.1, 07-JUL-1996 (NJB)

        Previous version line was changed from "Beta" to "SPICELIB."

    SPICELIB Version 1.0.0, 23-OCT-1995 (NJB)