Table of contents
CSPICE_BADKPV determines if a kernel pool variable is present and if so
that it has the correct size and type.
Given:
caller the scalar string name of the routine calling this routine to
check correctness of kernel pool variables.
help, caller
STRING = Scalar
name the scalar string name of a kernel pool variable that the
calling program expects to be present in the kernel pool.
help, name
STRING = Scalar
comp the scalar character comparison operator to use when comparing
the number of components of the kernel pool variable specified
by `name' with the integer `size'.
help, comp
STRING = Scalar
If `dim' is the actual size of the kernel pool variable then
cspice_badkpv will check that the sentence
dim comp size
is a true statement. If it is not a true statement
an error will be signaled.
Allowed values for `comp' and their meanings are:
'=' dim eq size
'<' dim lt size
'>' dim gt size
'=>' dim ge size
'<=' dim le size
size a scalar integer to compare with the actual number of components
of the kernel pool variable specified by `name'.
help, size
LONG = Scalar
divby a scalar integer that is one of the factors of the actual
dimension of the specified kernel pool variable.
help, divby
LONG = Scalar
In other words, it is expected that `divby' evenly divides the
actual dimension of `name'. In those cases in which the factors
of the dimension of `name' are not important, set `divby' to 1
in the calling program.
type a scalar character describing the kernel pool variable's
expected type.
help, type
STRING = Scalar
Recognized values are
'C' for character type
'N' for numeric type (integer and double precision)
The case of `type' is insignificant. If the value
of `type' is not one of the 2 values given above
no check for the type of the variable will be
performed.
the call:
cspice_badkpv, caller, name, comp, size, divby, type
returns:
None.
The procedure does not return a value. The call signals a SPICE error
if the kernel pool variable lacks the described properties, otherwise
the call has not effect.
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Suppose that you need to fetch a number of variables
from the kernel pool and want to check that the requested
items are in fact available prior to performing further
computations. The code example shows how you might use
this routine to handle the details of checking of
the various items.
Although by default the SPICE error handling system will
report the error and halt the execution of the program, in
this example we have decided to change this behaviour to
display the error messages and continue the execution of
the program.
Use the kernel shown below to define some variables related
to the Earth.
KPL/PCK
File name: badkpv_ex1.tpc
The contents of this kernel are not intended for
real applications. Use only with this example.
\begindata
BODY_399_DATA = ( 3.1416, 2.71828, 0.5, 12.0 )
BODY_399_NAMES = ( 'PI', 'E', 'HALF', 'DOZEN' )
\begintext
End of constants kernel
Example code begins here.
PRO badkpv_ex1
;;
;; Local parameters.
;;
CALLER = 'BADKPV_EX1'
;;
;; Load the test kernel.
;;
cspice_furnsh, 'badkpv_ex1.tpc'
;;
;; Create an error handler.
;;
catch, err
;;
;; Assume that we need some data for body 399 and we expect
;; there to be an even number of items available and at
;; least 4 such items. Moreover we expect these items to be
;; numeric. Note that the variable assignments below are
;; present only to assist in understanding the calls to
;; cspice_badkpv.
;;
name = 'BODY_399_DATA'
comp = '=>'
size = 4L
divby = 2L
type = 'N'
;;
;; Wrap the call, providing an output message on error.
;;
if err eq 0 then begin
;;
;; Execute the call. If an error occurs, the first statement
;; after "catch, err" executes.
;;
cspice_badkpv, CALLER, name, comp, size, divby, type
print, 'Expected form of variable ', name, $
' found in kernel pool.'
print
endif else begin
;;
;; cspice_badkpv signaled an error. Output the error message.
;;
print, !Error_State.Msg
endelse
;;
;; Cancel the error handler.
;;
catch, /cancel
;;
;; Perform another run in the same manner as above. Create an error
;; handler respond if an error signals.
;;
catch, err
;;
;; In addition we need the names given to these items.
;; Improperly indicate the array has type numeric.
;;
name = 'BODY_399_NAMES'
comp = '=>'
size = 4L
divby = 1L
type = 'N'
;;
;; Wrap the call, providing an output message on error.
;;
if err eq 0 then begin
;;
;; Execute the call. If an error occurs, the first statement
;; after "catch, err" executes.
;;
cspice_badkpv, CALLER, name, comp, size, divby, type
print, 'Expected form of variable ', name, $
' found in kernel pool.'
print
endif else begin
;;
;; cspice_badkpv signaled an error. Output the error message.
;;
print, !Error_State.Msg
endelse
catch, /cancel
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_unload, 'badkpv_ex1.tpc'
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Expected form of variable BODY_399_DATA found in kernel pool.
CSPICE_BADKPV: SPICE(BADVARIABLETYPE): [badkpv_c->BADKPV]
BADKPV_EX1: The kernel pool variable
'BODY_399_NAMES' must be of type "NUMERIC".
However, the current type is character.
(CSPICE_N0066)
Note that, as expected, the error SPICE(BADVARIABLETYPE) is
signaled by the second cspice_badkpv call, since we have improperly
indicated that the requested array is numeric, when actually
it is of character type.
This routine takes care of routine checking that often needs
to be done by programs and routines that rely upon kernel
pool variables being present and having the correct attributes.
It checks for the presence of the kernel pool variable and
examines the type and dimension of the variable to make sure
they conform to the requirements of the calling routine.
1) If the kernel pool variable specified by `name' is not present
in the kernel pool, the error SPICE(VARIABLENOTFOUND) is
signaled by a routine in the call tree of this routine.
2) If the comparison operator specified by `comp' is unrecognized,
the error SPICE(UNKNOWNCOMPARE) is signaled by a routine in
the call tree of this routine.
3) If the expected type of the kernel pool variable `type' is not
one of the supported types, the error SPICE(INVALIDTYPE) is
signaled by a routine in the call tree of this routine.
4) If the comparison of the actual size of the kernel pool
variable with `size' is not satisfied, the error
SPICE(BADVARIABLESIZE) is signaled by a routine in the call
tree of this routine.
5) If the variable does not have the expected type, the error
SPICE(BADVARIABLETYPE) is signaled by a routine in the call
tree of this routine.
6) If any of the input arguments, `caller', `name', `comp',
`size', `divby' or `type', is undefined, an error is signaled
by the IDL error handling system.
7) If any of the input arguments, `caller', `name', `comp',
`size', `divby' or `type', is not of the expected type, or it
does not have the expected dimensions and size, an error is
signaled by the Icy interface.
None.
None.
ERROR.REQ
ICY.REQ
KERNEL.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.0, 05-SEP-2021 (JDR)
Added exception SPICE(INVALIDTYPE) for the case of unknown
expected kernel pool variable type.
Edited the header to comply with NAIF standard. Added complete
code example based on existing fragment. Added required
readings references.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.0, 29-AUG-2006 (EDW)
Check the properties of a kernel pool variable
|