| unload |
|
Table of contents
Procedure
UNLOAD ( Unload a kernel )
ENTRY UNLOAD ( FILE )
Abstract
Unload a SPICE kernel.
Required_Reading
None.
Keywords
KERNEL
Declarations
CHARACTER*(*) FILE
Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
FILE I The name of a kernel to unload.
Detailed_Input
FILE is the name of a file to unload. This file
should be one loaded through the interface FURNSH.
If the file is not on the list of loaded kernels
no action is taken.
Note that if FILE is a meta-text kernel, all of
the files loaded as a result of loading the meta-text
kernel will be unloaded.
Detailed_Output
None.
Parameters
None.
Exceptions
Error free.
1) If the specified kernel is not on the list of loaded kernels
no action is taken.
Files
None.
Particulars
The call
CALL UNLOAD ( FILE )
has the effect of "erasing" the last previous call:
CALL FURNSH ( FILE )
This interface allows you to unload binary and text kernels.
Moreover, if you used a meta-text kernel to set up your
working environment, you can unload all of the kernels loaded
through the meta-kernel by unloading the meta-kernel.
The usual usage of FURNSH is to load each file needed by your
program exactly one time. However, it is possible to load a
kernel more than one time. (Usually, this is a result of loading
meta-kernels without taking the care needed to ensure that the
meta-kernels do not specify the same file more than once.) The
effect of unloading a kernel that has been loaded more than once
is to "undo" the last loading of the kernel. Depending upon the
kernel and its relationship to other loaded kernels, this may
have no visible effect on the working of your program. To
illustrate this behavior suppose that you have a collection of
files FILE1, FILE2, FILE3, FILE4, FILE5, FILE6, FILE7, FILE8,
META1, META2 where FILE1 ... FILE8 are SPICE kernels and META1
and META2 are meta-kernels with the specified kernels to load as
shown below.
META1:
KERNELS_TO_LOAD = ( FILE2,
FILE3,
FILE4,
FILE5 )
META2:
KERNELS_TO_LOAD = ( FILE2,
FILE3,
FILE7,
FILE8 )
The following sequence of calls
CALL FURNSH ( FILE1 )
CALL FURNSH ( FILE2 )
CALL FURNSH ( FILE3 )
CALL FURNSH ( META1 )
CALL FURNSH ( FILE6 )
CALL FURNSH ( META2 )
has the effect:
"Load" FILE1
"Load" FILE2
"Load" FILE3
"Load" META1 as a text kernel and then...
"Load" FILE2 (note that it was loaded from META1)
"Load" FILE3 (note that it was loaded from META1)
"Load" FILE4 (note that it was loaded from META1)
"Load" FILE5 (note that it was loaded from META1)
"Load" FILE6
"Load" META2 as a text kernel and then...
"Load" FILE2 (note that it was loaded from META2)
"Load" FILE3 (note that it was loaded from META2) *
"Load" FILE7 (note that it was loaded from META2)
"Load" FILE8 (note that it was loaded from META2)
If we UNLOAD FILE3
CALL UNLOAD ( FILE3 )
we locate the last time FILE3 was loaded (* above) and modify the
state of loaded kernels so that it looks as if we had made the
following sequence of "load" operations.
"Load" FILE1
"Load" FILE2
"Load" FILE3
"Load" META1 as a text kernel and then...
"Load" FILE2 (note that it was loaded from META1)
"Load" FILE3 (note that it was loaded from META1)
"Load" FILE4 (note that it was loaded from META1)
"Load" FILE5 (note that it was loaded from META1)
"Load" FILE6
"Load" META2 as a text kernel and then...
"Load" FILE2 (note that it was loaded from META2)
"Load" FILE7 (note that it was loaded from META2)
"Load" FILE8 (note that it was loaded from META2)
As you can see, the data from FILE3 is still available to the
program. All that may have changed is the usage priority
associated with that data.
If we unload META2 (or META1) we remove all remaining files that
are noted as being loaded from META2 (or META1)
CALL UNLOAD ( META2 )
produces the following load state for the program:
"Load" FILE1
"Load" FILE2
"Load" FILE3
"Load" META1 as a text kernel and then...
"Load" FILE2 (note that it was loaded from META1)
"Load" FILE3 (note that it was loaded from META1)
"Load" FILE4 (note that it was loaded from META1)
"Load" FILE5 (note that it was loaded from META1)
"Load" FILE6
If we had unloaded META1 instead, we would have this load state.
"Load" FILE1
"Load" FILE2
"Load" FILE3
"Load" FILE6
"Load" META2 as a text kernel and then...
"Load" FILE2 (note that it was loaded from META2)
"Load" FILE7 (note that it was loaded from META2)
"Load" FILE8 (note that it was loaded from META2)
So we see that unloading a file does not necessarily make its
data unavailable to your program. Unloading modifies the
precedence of the files loaded in your program. The data
associated with an unloaded file becomes unavailable only when
the file has been unloaded as many times as it was loaded.
When would you encounter such a scenario? The situation of
loading a file more than once might appear if you were trying to
contrast the results of computations performed with two
different meta-kernels. In such a scenario you might load a
"baseline" set of kernels early in your program and then load
and unload meta-kernels to compare results between the two
different sets of data.
Unloading Text Kernels or Meta-Kernels
--------------------------------------
Part of the action of unloading text (or meta-kernels) is
the clearing of the kernel pool and re-loading any kernels that
were not in the specified set of kernels to unload. Since
loading of text kernels is not a very fast process, unloading
text kernels takes considerably longer than unloading binary
kernels. Moreover, since the kernel pool is cleared, any kernel
pool variables you have set from your program by using one of the
interfaces PCPOOL, PDPOOL, PIPOOL, or LMPOOL will be removed from
the kernel pool. For this reason, if you plan to use this
feature in your program, together with one of the routines
specified above, you will need to take special precautions to
make sure kernel pool variables required by your program do not
inadvertently disappear.
As a side effect of unloading a text kernel, all watched kernel
variables are marked as updated. Note that unloading a text
kernel does not delete watchers. Watchers can be deleted by
calling the POOL entry point DWPOOL.
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 with a PCK, an LSK and an SPK, and
separately, a text kernel and a binary PCK. Loop over the
loaded kernels, outputting file information for each of
them.
Then unload the text kernels, check that they have been
unloaded, and finally unload the meta-kernel.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: unload_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
Use the PCK kernel below as the binary PCK required for the
example.
earth_latest_high_prec.bpc
Use the FK kernel below as the text kernel required for the
example.
RSSD0002.TF
Example code begins here.
PROGRAM UNLOAD_EX1
IMPLICIT NONE
C
C Local constants.
C
INTEGER FNAMLN
PARAMETER ( FNAMLN = 256 )
INTEGER FTYPLN
PARAMETER ( FTYPLN = 33 )
INTEGER SRCLEN
PARAMETER ( SRCLEN = 256 )
C
C Local variables.
C
CHARACTER*(FNAMLN) FILE
CHARACTER*(FTYPLN) FILTYP
CHARACTER*(SRCLEN) SRCFIL
INTEGER COUNT
INTEGER HANDLE
LOGICAL FOUND
C
C Load several kernel files.
C
CALL FURNSH ( 'unload_ex1.tm' )
CALL FURNSH ( 'RSSD0002.TF' )
CALL FURNSH ( 'earth_latest_high_prec.bpc' )
C
C Count the number of loaded kernel files.
C
CALL KTOTAL ( 'ALL', COUNT )
WRITE(*,'(A,I2)') 'The total number of kernels after '
. // 'final FURNSH: ', COUNT
WRITE(*,*) ' '
C
C Unload the text kernels.
C
CALL KTOTAL ( 'TEXT', COUNT )
WRITE(*,*) ' '
WRITE(*,'(A,I2,A)') 'Unloading', COUNT,
. ' text kernels...'
WRITE(*,*) ' '
DO WHILE ( COUNT .NE. 0 )
CALL KDATA ( 1, 'TEXT', FILE, FILTYP,
. SRCFIL, HANDLE, FOUND )
C
C If the kernel is found in the pool, unload it.
C
IF ( FOUND ) THEN
CALL UNLOAD ( FILE )
C
C Check if the file has been unloaded.
C
CALL KINFO ( FILE, FILTYP, SRCFIL, HANDLE, FOUND )
IF ( FOUND ) THEN
WRITE(*,'(A)') ' Error unloading ' // FILE
ELSE
WRITE(*,'(A)') ' Success unloading ' // FILE
END IF
C
C Something is not working. Inform NAIF.
C
ELSE
WRITE(*,*) ' ERROR: No kernel found but KTOTAL '
. // 'returns ', COUNT
END IF
C
C Check if we have more text kernels to unload from
C the kernel pool. Note that unloading a text kernel
C or meta-kernel implies that the kernel pool is
C cleared, and any kernel(s) that were not to be
C unloaded are re-loaded. Therefore the COUNT value
C changes, and the indexing of the files within the
C kernel pool too.
C
CALL KTOTAL ( 'TEXT', COUNT )
END DO
CALL KTOTAL ( 'ALL', COUNT )
WRITE(*,*) ' '
WRITE(*,'(A,I2)') 'The total number of kernels after '
. // 'UNLOAD calls: ', COUNT
C
C Unload the meta-kernel and retrieve the number of loaded
C after the clear.
C
CALL UNLOAD ( 'unload_ex1.tm' )
CALL KTOTAL ( 'ALL', COUNT )
WRITE(*,*) ' '
WRITE(*,'(A,I2)') 'The total number of kernels after '
. // 'final UNLOAD: ', COUNT
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
The total number of kernels after final FURNSH: 6
Unloading 3 text kernels...
Success unloading naif0012.tls
Success unloading pck00009.tpc
Success unloading RSSD0002.TF
The total number of kernels after UNLOAD calls: 3
The total number of kernels after final UNLOAD: 1
Restrictions
1) See the note regarding the unloading of Text and meta-text
Kernels.
Literature_References
None.
Author_and_Institution
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
B.V. Semenov (JPL)
W.L. Taber (JPL)
Version
SPICELIB Version 5.0.1, 08-AUG-2021 (JDR)
Edited the header to comply with NAIF standard.
Created complete code example from existing code fragments.
SPICELIB Version 5.0.0, 01-FEB-2017 (NJB) (BVS)
Updated to support use of DSKs.
Bug fix: now unloads binary kernels via low-level
unload routines only when those kernels have just
one entry in the KEEPER database.
Updated the $Author_and_Institution section.
SPICELIB Version 3.0.1, 01-JUL-2014 (NJB)
Updated discussion of kernel variable watchers.
SPICELIB Version 3.0.0, 15-NOV-2006 (NJB)
Bug fix: corrected update of source pointers when a
meta-kernel is unloaded. Previously source pointers
having higher indices than those of the files referenced
by the meta kernel were not adjusted when the database
was compressed.
SPICELIB Version 2.0.0, 23-AUG-2001 (WLT)
Added code to make sure that UNLOAD has the effect of
loading all remaining kernels in the order they were first
introduced.
SPICELIB Version 1.0.0, 01-JUL-1999 (WLT)
|
Fri Dec 31 18:37:04 2021