Procedure

     BODVRD ( Return d.p. values from the kernel pool )

     SUBROUTINE BODVRD ( BODYNM, ITEM, MAXN, DIM, VALUES )

Abstract

     Fetch from the kernel pool the double precision values
     of an item associated with a body.

Required_Reading

     KERNEL
     NAIF_IDS

Keywords

     CONSTANTS

Declarations

     IMPLICIT NONE

     INCLUDE               'zzctr.inc'

     CHARACTER*(*)         BODYNM
     CHARACTER*(*)         ITEM
     INTEGER               MAXN
     INTEGER               DIM
     DOUBLE PRECISION      VALUES  ( * )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     BODYNM     I   Body name.
     ITEM       I   Item for which values are desired. ('RADII',
                    'NUT_PREC_ANGLES', etc. )
     MAXN       I   Maximum number of values that may be returned.
     DIM        O   Number of values returned.
     VALUES     O   Values.

Detailed_Input

     BODYNM   is the name of the body for which ITEM is requested.
              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     is the item to be returned. 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     is the maximum number of values that may be returned.
              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.

Detailed_Output

     DIM      is the number of values returned; this is always the
              number of values associated with the requested kernel
              variable unless an error has been signaled.

     VALUES   is the array of values associated with the requested
              kernel variable. If VALUES is too small to hold all
              of the values associated with the kernel variable, the
              returned values of DIM and VALUES are undefined.

Parameters

     None.

Exceptions

     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.

     2)  If the requested kernel variable is not found in the kernel
         pool, the error SPICE(KERNELVARNOTFOUND) is signaled.

     3)  If the requested kernel variable is found but the associated
         values aren't numeric, the error SPICE(TYPEMISMATCH) is
         signaled.

     4)  If the dimension of VALUES indicated by MAXN is too small to
         contain the requested values, the error SPICE(ARRAYTOOSMALL)
         is signaled. 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.

Files

     None.

Particulars

     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 GDPOOL should be used instead. 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
     GDPOOL should be used.

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) 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.


              PROGRAM BODVRD_EX1
              IMPLICIT NONE

        C
        C     Local parameters.
        C
              INTEGER               NVALS
              PARAMETER           ( NVALS = 3 )


        C
        C     Local variables.
        C
              DOUBLE PRECISION      VALUES (NVALS)

              INTEGER               DIM

        C
        C     Load a PCK.
        C
              CALL FURNSH ( 'pck00008.tpc' )

        C
        C     When the kernel variable
        C
        C        BODY399_RADII
        C
        C     is present in the kernel pool---normally because a PCK
        C     defining this variable has been loaded (as is the case
        C     here)---the call
        C
              CALL BODVRD ( 'EARTH', 'RADII', 3, DIM, VALUES )

        C
        C     returns the dimension and values associated with the
        C     variable 'BODY399_RADII'
        C
              WRITE(*,'(A,3F10.3)') 'EARTH RADII: ', VALUES

        C
        C     The call
        C
              CALL BODVRD ( 'earth', 'RADII', 3, DIM, VALUES )

        C
        C     will produce the same results since the case of the
        C     input argument BODYNM is not significant.
        C
              WRITE(*,'(A,3F10.3)') 'earth RADII: ', VALUES

        C
        C     The call
        C
              CALL BODVRD ( '399', 'RADII', 3, DIM, VALUES )

        C
        C     will also produce the same results since strings
        C     containing integer codes are accepted
        C     by this routine.
        C
              WRITE(*,'(A,3F10.3)') '''399'' RADII: ', VALUES

        C
        C     The ITEM variable possesses case sensitivity. This
        C     call should cause an error.
        C
              CALL BODVRD ( 'EARTH', 'radii', 3, DIM, VALUES )
              WRITE(*,'(A,3F10.3)') 'EARTH radii: ', VALUES

              END


        When this program was executed on a Mac/Intel/gfortran/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

        ============================================================***

        Toolkit version: N0066

        SPICE(KERNELVARNOTFOUND) -- The Variable Was not Found in th***
        Pool.

        The variable BODY399_radii could not be found in the kernel ***

        A traceback follows.  The name of the highest level module i***
        BODVRD

        Oh, by the way:  The SPICELIB error handling actions are USER-
        TAILORABLE.  You can choose whether the Toolkit aborts or co***
        when errors occur, which error messages to output, and where***
        the output.  Please read the ERROR "Required Reading" file, ***
        the routines ERRACT, ERRDEV, and ERRPRT.

        ============================================================***


        Warning: incomplete output. 8 lines extended past the right
        margin of the header and have been truncated. These lines are
        marked by "***" at the end of each line.


        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.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.2.1, 27-AUG-2021 (JDR)

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

        Removed note about GDPOOL being entry point of POOL from
        $Particulars section.

    SPICELIB Version 1.2.0, 19-SEP-2013 (BVS)

        Updated to save the input body name and ZZBODTRN state counter
        and to do name-ID conversion only if the counter has changed.

    SPICELIB Version 1.1.0, 22-JUL-2004 (NJB)

        Updated to use BODS2C.

    SPICELIB Version 1.0.0, 23-FEB-2004 (NJB) (BVS) (WLT) (IMU)