Table of contents
CSPICE_BODVRD returns from the kernel pool the double precision values
of an item associated with a body.
Given:
bodynm the name of the body for which `item' is requested.
help, bodynm
STRING = Scalar
`bodynm' is case-insensitive, and leading and trailing blanks
in `bodynm' are not significant. Optionally, you may supply the
integer ID code for the object as an integer string. For example
both 'MOON' and '301' are legitimate strings that indicate the
moon is the body of interest.
item the item to be returned.
help, item
STRING = Scalar
Together, the NAIF ID code of the body and the item name
combine to form a kernel variable name, e.g.,
'BODY599_RADII'
'BODY401_POLE_RA'
The values associated with the kernel variable having
the name constructed as shown are sought. Below
we'll take the shortcut of calling this kernel variable
the "requested kernel variable."
Note that `item' *is* case-sensitive. This attribute
is inherited from the case-sensitivity of kernel
variable names.
maxn the maximum number of values that may be returned.
help, maxn
LONG = Scalar
The output array `values' must be declared with size at least
`maxn'. It's an error to supply an output array that is too
small to hold all of the values associated with the requested
kernel variable.
the call:
cspice_bodvrd, bodynm, item, maxn, values
returns:
values the array of values associated with the requested kernel
variable.
help, values
DOUBLE = Array[N]
`values' returns a vector even when `item' refers to a scalar,
i.e. a scalar returns in values[0].
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) Retrieve the radii of the Earth from the kernel pool, using both
'RADII' and 'radii' as the item name to return. Since the `item'
variable possesses case sensitivity, the later case should fail.
Trap the error and print it to the output.
Use the PCK kernel below to load the required triaxial
ellipsoidal shape model for the Earth.
pck00008.tpc
Example code begins here.
PRO bodvrd_ex1
;;
;; Load a PCK.
;;
cspice_furnsh, 'pck00008.tpc'
;;
;; When the kernel variable
;;
;; BODY399_RADII
;;
;; is present in the kernel pool---normally because a pck
;; defining this variable has been loaded (as is the case
;; here)---the call
;;
cspice_bodvrd, 'EARTH', 'RADII', 3, values
;;
;; returns the dimension and values associated with the
;; variable 'BODY399_RADII'
;;
print, format='(A,3F10.3)', 'EARTH RADII: ', values[0], values[1], $
values[2]
;;
;; The call
;;
cspice_bodvrd, 'earth', 'RADII', 3, values
;;
;; will produce the same results since the case of the
;; input argument `bodynm' is not significant.
;;
print, format='(A,3F10.3)', 'earth RADII: ', values[0], values[1], $
values[2]
;;
;; The call
;;
cspice_bodvrd, '399', 'RADII', 3, values
;;
;; will also produce the same results since strings
;; containing integer codes are accepted
;; by this routine.
;;
print, format='(A,3F10.3)', '''399'' RADII: ', values[0], values[1], $
values[2]
;;
;; The `item' variable possesses case sensitivity. This
;; call should cause an error.
;;
catch, error
if error eq 0 then begin
cspice_bodvrd, 'EARTH', 'radii', 3, values
endif
catch, /cancel
;;
;; The variable `error' has value 0 after the catch command. If Icy
;; signals an error, the value resets to non-zero then program
;; execution continues at the first executable line after the catch.
;;
;; Check the value of `error' to see what happened.
;;
if error ne 0 then begin
print, ''
print, !ERROR_STATE.NAME
print, !ERROR_STATE.MSG
return
endif else begin
print, format='(A,3F10.3)', 'EARTH radii: ', $
values[0], values[1], values[2]
endelse
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
EARTH RADII: 6378.140 6378.140 6356.750
earth RADII: 6378.140 6378.140 6356.750
'399' RADII: 6378.140 6378.140 6356.750
ICY_M_SPICE_ERROR
CSPICE_BODVRD: SPICE(KERNELVARNOTFOUND): [bodvrd_c->BODVRD] The
variable BODY399_radii could not be found in the
kernel pool. (CSPICE_N0066)
Note that, usually, the last call will cause a
SPICE(KERNELVARNOTFOUND) error to be signaled, because this
call will attempt to look up the values associated with a
kernel variable of the name
'BODY399_radii'
Since kernel variable names are case sensitive, this
name is not considered to match the name
'BODY399_RADII'
which normally would be present after a text PCK
containing data for all planets and satellites has
been loaded.
This routine simplifies looking up PCK kernel variables by
constructing names of requested kernel variables and by
performing error checking.
This routine is intended for use in cases where the maximum number of
values that may be returned is known at compile time. The caller fetches
all of the values associated with the specified kernel variable via a
single call to this routine. If the number of values to be fetched cannot
be known until run time, the lower-level routine cspice_gdpool should be
used instead. cspice_gdpool supports fetching arbitrary amounts of data
in multiple "chunks."
This routine is intended for use in cases where the requested
kernel variable is expected to be present in the kernel pool. If
the variable is not found or has the wrong data type, this
routine signals an error. In cases where it is appropriate to
indicate absence of an expected kernel variable by returning a
boolean "found flag" with the value False, again the routine
cspice_gdpool should be used.
1) If the input body name cannot be translated to an ID code,
and if the name is not a string representation of an integer
(for example, '399'), the error SPICE(NOTRANSLATION) is
signaled by a routine in the call tree of this routine.
2) If the requested kernel variable is not found in the kernel
pool, the error SPICE(KERNELVARNOTFOUND) is signaled by a
routine in the call tree of this routine.
3) If the requested kernel variable is found but the associated
values aren't numeric, the error SPICE(TYPEMISMATCH) is
signaled by a routine in the call tree of this routine.
4) If the dimension of `values' indicated by `maxn' is too small to
contain the requested values, the error SPICE(ARRAYTOOSMALL)
is signaled by a routine in the call tree of this routine. The
output array `values' must be declared with sufficient size to
contain all of the values associated with the requested kernel
variable.
5) If the input dimension `maxn' indicates there is more room in
`values' than there really is---for example, if `maxn' is 10 but
values is declared with dimension 5---and the dimension of the
requested kernel variable is larger than the actual dimension
of `values', then this routine may overwrite memory. The results
are unpredictable.
6) If any of the input arguments, `bodynm', `item' or `maxn', is
undefined, an error is signaled by the IDL error handling
system.
7) If any of the input arguments, `bodynm', `item' or `maxn', is
not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
8) If the output argument `values' is not a named variable, an
error is signaled by the Icy interface.
None.
None.
ICY.REQ
NAIF_IDS.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.1, 05-SEP-2021 (JDR)
Edited the header to comply with NAIF standard. Added complete
code example based on the existing fragments.
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, 16-JUN-2003 (EDW)
fetch constants for a body from the kernel pool
physical constants for a body
|