Procedure

     EKUEF  ( EK, unload event file )

     ENTRY EKUEF ( HANDLE )

Abstract

     Unload an EK file, making its contents inaccessible to the
     EK reader routines, and clearing space in order to allow other
     EK files to be loaded.

Required_Reading

     EK

Keywords

     EK
     FILES

Declarations

    INTEGER               HANDLE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle of EK file.

Detailed_Input

     HANDLE   is a file handle returned by EKLEF.

Detailed_Output

     None.

     See $Particulars for a description of the effect of this routine.

Parameters

     None.

Exceptions

     1)  Unloading a file that is not loaded has no effect.

Files

     This routine unloads a binary EK file from the EK query system.

Particulars

     This routine removes information about an EK file from the
     EK system, freeing space to increase the number of other EK
     files that can be loaded. The file is also unloaded from
     the DAS system and closed.

Examples

     The numerical results shown for this example 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. Unload the previous
        file before each new file is loaded. Unloading files prevents
        them from being searched during query execution.

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

     None.

Literature_References

     None.

Author_and_Institution

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

Version

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

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Added complete
        code example

    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)