1 /*
2 
3 -Procedure kclear_c ( Keeper clear )
4 
5 -Abstract
6 
7    Clear the KEEPER subsystem: unload all kernels, clear the kernel
8    pool, and re-initialize the subsystem. Existing watches on kernel
9    variables are retained.
10 
11 -Disclaimer
12 
13    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
14    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
15    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
16    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
17    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
18    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
19    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
20    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
21    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
22    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
23 
24    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
25    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
26    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
27    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
28    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
29    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
30 
31    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
32    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
33    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
34    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
35 
36 -Required_Reading
37 
38    None.
39 
40 -Keywords
41 
42    KERNEL
43 
44 */
45 
46    #include "SpiceUsr.h"
47    #include "SpiceZfc.h"
48 
kclear_c(void)49    void kclear_c ( void )
50 
51 /*
52 
53 -Brief_I/O
54 
55    VARIABLE  I/O  DESCRIPTION
56    --------  ---  --------------------------------------------------
57    None.
58 
59 -Detailed_Input
60 
61    None.  This routine operates by side effects.  See Particulars
62    below.
63 
64 -Detailed_Output
65 
66    None.
67 
68 -Parameters
69 
70    None.
71 
72 -Exceptions
73 
74    1) Any errors that occur when setting a kernel pool watch
75       or checking watched variables will be diagnosed by
76       routines in the call tree of this routine.
77 
78 -Files
79 
80    See Particulars.
81 
82 -Particulars
83 
84    This entry point allows you re-initialize the KEEPER system with
85    a single call.  The KEEPER system is the kernel management system
86    underlying the set of CSPICE APIs
87 
88       furnsh_c
89       ktotal_c
90       kdata_c
91       kinfo_c
92       kclear_c
93       unload_c
94 
95    This routine unloads all kernels from their kernel-type-specific
96    kernel management subsystems (SPKBSR, CKBSR, etc.), clears the
97    kernel pool, clears KEEPER's internal file database, and re-sets
98    the watch status for the kernel variables used to load kernels
99    via meta-kernels. As a side effect of clearing the kernel pool,
100    all watched variables are marked as updated. Note that clearing
101    the kernel pool does not delete watchers.
102 
103    This capability, though implemented in Fortran, is particularly
104    relevant to SPICE implementations such as Icy, for which the
105    state of the KEEPER system persists after any Icy-based IDL
106    script is run. Successive runs of Icy-based scripts may perform
107    in unexpected ways when scripts access data loaded during runs of
108    previous scripts.
109 
110    Cleaning up after such programs using explicit unload_c commands is
111    tedious and error-prone.  One call to this routine sets the
112    KEEPER system to its initial state, preventing unintentional
113    interaction between scripts via KEEPER's state.
114 
115 -Examples
116 
117    Clear the KEEPER system; check for residual loaded files.
118    We shouldn't find any.
119 
120        kclear_c ();
121        ktotal_c ( "ALL", &n );
122 
123        printf ( "Count of loaded kernels after kclear_c call\n", n );
124 
125 
126 -Restrictions
127 
128    Calling this routine will wipe out any kernel pool data
129    inserted via the p*pool_c API routines.
130 
131 -Literature_References
132 
133    None.
134 
135 -Author_and_Institution
136 
137    N.J. Bachman    (JPL)
138 
139 -Version
140 
141    -CSPICE Version 1.0.1, 01-JUL-2014 (NJB)
142 
143       The header Particulars section was updated to more
144       completely describe the effect of this routine on
145       kernel pool watchers. Header section order was corrected.
146 
147    -CSPICE Version 1.0.0, 15-NOV-2006 (NJB)
148 
149 -Index_Entries
150 
151    Re-initialize the keeper system
152    Clear the keeper system
153    Unload all kernels
154 
155 -&
156 */
157 
158 { /* Begin kclear_c */
159 
160 
161    /*
162    Participate in error tracing.
163    */
164    chkin_c ( "kclear_c" );
165 
166 
167    kclear_();
168 
169 
170    chkout_c ( "kclear_c" );
171 
172 } /* End kclear_c */
173