Procedure

     SCLD01 ( SCLK lookup of double precision data, type 1 )

     ENTRY SCLD01 ( NAME, SC, MAXNV, N, DVAL )

Abstract

     Look up double precision type 1 SCLK data from the kernel pool.

Required_Reading

     KERNEL
     SCLK

Keywords

     UTILITY

Declarations

    CHARACTER*(*)         NAME
    INTEGER               SC
    INTEGER               MAXNV
    INTEGER               N
    DOUBLE PRECISION      DVAL   ( * )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     NAME,
     SC         I   Name of kernel data item, NAIF spacecraft ID code.
     MAXNV      I   Maximum number of d.p. values to return.
     N          O   Number of values actually returned.
     DVAL       O   Requested kernel data item.
     MXCOEF     P   Maximum number of coefficient sets in SCLK kernel.

Detailed_Input

     NAME,
     SC       are, respectively, a name and a NAIF integer code
              of a spacecraft that together define the name of a
              requested kernel data item. NAME is the full name
              as it appears in the SCLK kernel, except that it
              lacks the final underscore and spacecraft integer
              code (actually, the negative of the spacecraft
              code).  This routine combines NAME and SC to
              make up the appropriate kernel variable name.

              For example, to look up data associated with the
              name

                 SCLK01_COEFFICIENTS_77

              you would supply NAME as

                 SCLK01_COEFFICIENTS

              and SC as -77.


     MAXNV    is the maximum number of values to return.  MAXNV
              is used to prevent SCLD01 from writing past the end
              of the supplied array DVAL.

Detailed_Output

     N        is the number of values actually returned.

     DVAL     is an array containing the requested double
              precision kernel data item.

Parameters

     MXCOEF   is the maximum number of coefficient sets in the
              array COEFFS that defines the mapping between
              encoded type 1 SCLK and a parallel time system.
              This array has dimension 3 x MXCOEF. The value of
              MXCOEF may be increased as required.

Exceptions

     1)  If item specified by NAME and SC is not found in the kernel
         pool, the error SPICE(KERNELVARNOTFOUND) is signaled. The
         output arguments are not modified.

     2)  If the item specified by NAME and SC is found but does not
         have numeric type, the error SPICE(BADKERNELVARTYPE) is
         signaled.

     3)  This routine can check certain data for validity. If any of
         these items have invalid values, the error
         SPICE(VALUEOUTOFRANGE) is signaled. The output arguments are
         not modified. The values in question are:

            - The number of coefficients.
            - The number of partition start values.
            - The number of partition end values.
            - The number of moduli.
            - The values of the moduli (lower bounds)
            - The number of offsets.
            - The number of kernel identifiers.

     4)  If the partition times or SCLK coefficients themselves
         are invalid, this routine does nothing about it. It is
         simply not possible to detect all of the possible errors
         that these data may be subject to.

     5)  If the dimension of the requested item exceeds MAXNV, the
         error SPICE(ARRAYTOOSMALL) is signaled.

     6)  If the dimension of the requested item is outside of the
         limits for that item, the error SPICE(INVALIDSIZE) is
         signaled.

     7)  If the dimension of the coefficient kernel variable is
         not a multiple of 3, the error SPICE(INVALIDSIZE) is
         signaled.

Files

     None.

Particulars

     The purpose of this routine is to localize error checking for
     lookups of type 1 SCLK kernel pool data. This routine handles
     lookups of double precision data.

Examples

     1)  Check a NAIF SCLK kernel for accuracy by converting the
         encoded SCLK coefficients to strings with partition numbers
         and converting the parallel times to UTC strings. Print out
         the results in tabular form. In this example, the spacecraft
         is Mars Observer, which has NAIF ID code -94. We could
         make the program work for Galileo by using the NAIF ID code
         -77 instead of -94.

            C
            C     Load the SCLK kernel in question, and also load
            C     a leapseconds kernel. We use made-up names for the
            C     kernel file; you would use the actual names of your
            C     kernel files instead if you were to carry out this
            C     procedure.
            C
                  CALL FURNSH ( 'SAMPLE_MO_SCLK.KER' )
                  CALL FURNSH ( 'LEAPSECONDS.KER'    )

                  CONAME =  SCLK01_COEFFICIENTS
                  SC     =  -94

            C
            C     Grab the coefficients.
            C
                  CALL SCLD01 ( CONAME, SC, 3*MXCOEF, NCOEFF, COEFFS )

            C
            C     The SCLK coefficients are in the first row of the
            C     coefficients array; the parallel times are in the
            C     second. Since the parallel time system used for MO
            C     is terrestrial dynamical time (TDT), we will convert
            C     the parallel time values to ET (TDB) first and then
            C     convert the resulting times to UTC.
            C
            C     In a more robust algorithm, we'd look up the parallel
            C     time system code used in the SCLK kernel rather than
            C     assume that it is a particular system. We omit this
            C     check for simplicity.
            C
            C     We decode the SCLK coefficients using SCDECD. Write
            C     out the results to a file we'll call COMPARE.DAT.
            C
                  OUTFIL = 'COMPARE.DAT'

                  CALL WRLINE ( OUTFIL, '    SCLK               UTC' )
                  CALL WRLINE ( OUTFIL, ' '                          )

                  DO I = 1, NCOEFF / 3

                     CALL SCDECD ( -94,  COEFF(1,I),  CLKSTR )
            C
            C        Convert the parallel time coefficients, which are
            C        given in TDT, to ET. UNITIM returns this value.
            C
                     CALL ET2UTC ( UNITIM ( COEFF(2,I), 'TDT', 'TDB' ),
                 .                 'D',
                 .                  3,
                 .                  UTC    )

                     LINE = ' SCLK        UTC '

                     CALL REPMC  ( LINE, 'SCLK', CLKSTR, LINE )
                     CALL REPMC  ( LINE, 'UTC',  UTC,    LINE )

                     CALL WRLINE ( OUTFIL, LINE )

                  END DO

Restrictions

     1)  SCLD01 assumes that a SCLK kernel appropriate to the
         spacecraft identified by SC has been loaded.

     2)  SCLD01 handles lookups of type 1 SCLK data only.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 3.0.0, 01-DEC-2021 (NJB) (JDR)

        New checks on item sizes have been added: sizes are now
        compared against upper bounds as well as lower bounds.
        Previously only lower bounds were used. A check has been
        added to verify that the coefficient count is a multiple
        of 3.

        Bug fix: corrected index error in modulus range check. Made
        cosmetic changes to code and comments.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 2.2.0, 20-NOV-2006 (NJB) (EDW)

        Routine was updated to use GDPOOL instead of RTPOOL. Header
        has been updated to remove warnings about memory corruption and
        to document exception handling for output buffer overflow
        errors.

        Header references to LDPOOL were replaced with references to
        FURNSH.

    SPICELIB Version 2.1.0, 19-OCT-1992 (NJB)

        This entry point was updated to fix a bug: if a kernel pool
        lookup fails, the number of elements returned N is now set to
        zero.

    SPICELIB Version 2.0.0, 17-APR-1992 (NJB) (WLT)

        One constant was changed in the code for clarity; no functional
        change results from this. Some corrections and other minor
        enhancements were made to the header. Comment section for
        permuted index source lines was added following the header.

    SPICELIB Version 1.0.0, 06-SEP-1990 (NJB)