Procedure

     KCLEAR ( Keeper clear )

     ENTRY KCLEAR

Abstract

     Clear the KEEPER subsystem: unload all kernels, clear the kernel
     pool, and re-initialize the subsystem. Existing watches on kernel
     variables are retained.

Required_Reading

     None.

Keywords

     KERNEL

Declarations

    None.

Brief_I/O

     None.

Detailed_Input

     None. This routine operates by side effects. See $Particulars
     below.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If an error occurs when setting a kernel pool watch or
         checking watched variables, the error is signaled by a routine
         in the call tree of this routine.

Files

     See $Particulars.

Particulars

     This entry point allows you re-initialize the KEEPER system with
     a single call.

     This routine unloads all kernels from their kernel-type-specific
     kernel management subsystems (SPKBSR, CKBSR, etc.), clears the
     kernel pool, clears KEEPER's internal file database, and re-sets
     the watch status for the kernel variables used to load kernels
     via meta-kernels. As a side effect of clearing the kernel pool,
     all watched variables are marked as updated. Note that clearing
     the kernel pool does not delete watches (aka "watchers"). Watches
     can be deleted by calling the POOL entry point DWPOOL.

     This capability, though implemented in Fortran, is particularly
     relevant to SPICE implementations such as Icy, for which the
     state of the KEEPER system persists after any Icy-based IDL
     script is run. Successive runs of Icy-based scripts may perform
     in unexpected ways when scripts access data loaded during runs of
     previous scripts.

     Cleaning up after such programs using explicit UNLOAD commands is
     tedious and error-prone. One call to this routine sets the
     KEEPER system to its initial state, preventing unintentional
     interaction between scripts via KEEPER's state.

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 a meta-kernel containing three kernels, and count the
        number of files in the kernel pool before and after calling
        KCLEAR.

        Use the meta-kernel shown below to load the required SPICE
        kernels.


           KPL/MK

           File name: kclear_ex1.tm

           This meta-kernel is intended to support operation of SPICE
           example programs. The kernels shown here should not be
           assumed to contain adequate or correct versions of data
           required by SPICE-based user applications.

           In order for an application to use this meta-kernel, the
           kernels referenced here must be present in the user's
           current working directory.

           The names and contents of the kernels referenced
           by this meta-kernel are as follows:

              File name                     Contents
              ---------                     --------
              de421.bsp                     Planetary ephemeris
              pck00009.tpc                  Planet orientation and
                                            radii
              naif0012.tls                  Leapseconds

           \begindata

              KERNELS_TO_LOAD = ( 'de421.bsp',
                                  'naif0012.tls',
                                  'pck00009.tpc' )

           \begintext

           End of meta-kernel


        Example code begins here.


              PROGRAM KCLEAR_EX1
              IMPLICIT NONE

        C
        C     Local variables.
        C
              INTEGER               COUNT

        C
        C     Load several kernel files.
        C
              CALL FURNSH ( 'kclear_ex1.tm' )

        C
        C     Count the number of loaded kernel files.
        C
              CALL KTOTAL ( 'ALL', COUNT )

              WRITE(*,'(A,I2)') 'The total number of kernels after '
             . //               'FURNSH: ', COUNT

        C
        C     Clear the KEEPER system, retrieve the number of loaded
        C     after the clear.
        C
              CALL KCLEAR()

              CALL KTOTAL ( 'ALL', COUNT )

              WRITE(*,'(A,I2)') 'The total number of kernels after '
             . //               'KCLEAR: ', COUNT

              END


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


        The total number of kernels after FURNSH:  4
        The total number of kernels after KCLEAR:  0

Restrictions

     1)  Calling this routine will wipe out any kernel pool data
         inserted via the SPICELIB API routines to put data into the
         kernel pool (PCPOOL, PDPOOL and PIPOOL).

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 5.0.1, 08-AUG-2021 (JDR)

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

        Improved $Restrictions section.

    SPICELIB Version 5.0.0, 01-FEB-2017 (NJB) (BVS)

        Updated to support use of DSKs.

        Updated the $Author_and_Institution section.

    SPICELIB Version 1.0.1, 01-JUL-2014 (NJB) (EDW)

        Updated the discussion of kernel variable watchers.

     Last update was 13-APR-2011 (EDW)

        Trivial edit to $Restrictions, replaced P*POOL with
        PXPOOL. The "*" character causes the HTML documentation
        script to create a link for the "POOL" substring.

    SPICELIB Version 1.0.0, 15-NOV-2006 (NJB)