Procedure

     CKR06 ( C-kernel, read record from segment, type 6 )

     SUBROUTINE CKR06 ( HANDLE, DESCR, SCLKDP, TOL, NEEDAV,
    .                   RECORD, FOUND                       )

Abstract

     Read a single CK data record from a segment of type 6
     (ESOC/DDID Piecewise Interpolation).

Required_Reading

     CK

Keywords

     POINTING

Declarations

     IMPLICIT NONE

     INCLUDE 'ckparam.inc'
     INCLUDE 'ck06.inc'

     INTEGER               HANDLE
     DOUBLE PRECISION      DESCR    ( 5 )
     DOUBLE PRECISION      SCLKDP
     DOUBLE PRECISION      TOL
     LOGICAL               NEEDAV
     DOUBLE PRECISION      RECORD   ( * )
     LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   File handle.
     DESCR      I   Segment descriptor.
     SCLKDP     I   Pointing request time.
     TOL        I   Lookup tolerance.
     NEEDAV     I   Angular velocity flag.
     RECORD     O   Data record.
     FOUND      O   Flag indicating whether record was found.

Detailed_Input

     HANDLE,
     DESCR    are the file handle and segment descriptor for a CK
              segment of type 6.

     SCLKDP   is an encoded spacecraft clock time indicating the
              epoch for which pointing is desired.

     TOL      is a time tolerance, measured in the same units as
              encoded spacecraft clock.

              When SCLKDP falls between the start time of one of
              the mini-segment intervals and the last time tag of
              that interval, the tolerance has no effect because
              pointing will be returned at the request time.

              However, if the request time falls within a coverage
              gap in one of the intervals, or outside of any
              interval, then the tolerance is used to determine if
              pointing should be returned at the closest epoch for
              which pointing is available. This epoch is either an
              interval's start time or the smaller of an interval's
              end time and its last time tag.


     NEEDAV   is .TRUE. if angular velocity is requested. If the
              input segment descriptor indicates angular velocity
              is absent, the error SPICE(NOAVDATA) is signaled.

              Note: although all subtypes of type 6 records either
              contain or compute angular velocity, a CK creator may
              choose to indicate that the provided angular velocity
              data are not valid; this can be done by setting the
              segment descriptor angular velocity flag to .FALSE.

Detailed_Output

     RECORD   is a set of data from the specified segment which,
              when evaluated at epoch SCLKDP, will give the
              attitude and angular velocity of some body, relative
              to the reference frame indicated by DESCR.

              The structure of the record is as follows:

                 +----------------------+
                 | evaluation epoch     |
                 +----------------------+
                 | subtype code         |
                 +----------------------+
                 | number of packets (n)|
                 +----------------------+
                 | nominal SCLK rate    |
                 +----------------------+
                 | packet 1             |
                 +----------------------+
                 | packet 2             |
                 +----------------------+
                             .
                             .
                             .
                 +----------------------+
                 | packet n             |
                 +----------------------+
                 | epochs 1--n          |
                 +----------------------+

              The packet size is a function of the subtype code.
              All packets in a record have the same size.


     FOUND    is a logical flag indicating whether data were found.
              If NEEDAV is .FALSE., data will be found if the
              request time is within TOL ticks of a time for which
              the segment provides data. If NEEDAV is .TRUE., the
              segment's angular velocity flag must also be set in
              order for data to be found.

              A type 6 segment provides data for times that are
              between its descriptor time bounds and that are
              within the coverage region of a mini-segment
              interval. The coverage region of a mini-segment
              interval extends from its start time to the lesser of
              its stop time and its last time tag.

Parameters

     None.

Exceptions

     This routine roughly follows the pattern established in the
     lower-numbered CK data type readers of not explicitly performing
     error diagnoses. In particular, the C-kernel from which data are
     read is assumed to be valid in most respects. The few exceptions
     that are handled here are listed below.

     1)  If the input HANDLE does not designate a loaded CK file, an
         error is signaled by a routine in the call tree of this
         routine.

     2)  If the segment specified by DESCR is not of data type 6, the
         error SPICE(WRONGCKTYPE) is signaled.

     3)  If the input SCLK value is not within TOL ticks of a time
         for which the segment provides data, FOUND is set to .FALSE.
         and the output record is undefined.

     4)  If the window size is non-positive or greater than the
         maximum allowed value, the error SPICE(INVALIDVALUE) is
         signaled.

     5)  If the window size is not compatible with the segment
         subtype, the error SPICE(INVALIDVALUE) is signaled.

     6)  If the segment subtype is not recognized, the error
         SPICE(INVALIDSUBTYPE) is signaled.

     7)  If the tolerance is negative, the error SPICE(NEGATIVETOL) is
         signaled.

     8)  If an error occurs while trying to read data from a C-kernel,
         the error is signaled by a routine in the call tree of this
         routine.

     9)  If the input segment descriptor indicates that angular
         velocity data are not present, and if the input flag NEEDAV
         is set to .TRUE., the error SPICE(NOAVDATA) is signaled.

Files

     See argument HANDLE.

Particulars

     See the CK Required Reading file for a description of the
     structure of a data type 6 segment.

Examples

     The data returned by the CKRnn routine is in its rawest form,
     taken directly from the segment. As such, it will be meaningless
     to a user unless he/she understands the structure of the data type
     completely. Given that understanding, however, the CKRxx
     routines might be used to "dump" and check segment data for a
     particular epoch.

     The search performed here does not mimic the behavior of the CK
     reader APIs CKGP and CKGPAV, which continue searching when an
     applicable segment doesn't satisfy a pointing request. See the CK
     Required reading for details.

     C
     C     Get a segment applicable to a specified body and epoch.
     C
           CALL CKBSS ( INST,   SCLKDP, TOL,   NEEDAV )
           CALL CKSNS ( HANDLE, DESCR,  SEGID, SFND   )

           IF ( .NOT. SFND ) THEN
              [Handle case of pointing not being found]
           END IF

     C
     C     Look at parts of the descriptor.
     C
           CALL DAFUS ( DESCR, 2, 6, DCD, ICD )
           CENTER = ICD( 2 )
           REF    = ICD( 3 )
           TYPE   = ICD( 4 )

           IF ( TYPE .EQ. 6 ) THEN

              CALL CKR06 ( HANDLE, DESCR, SCLKDP, TOL, NEEDAV,
          .                RECORD, FOUND                       )

              IF ( .NOT. FOUND ) THEN
                 [Handle case of pointing not being found]
              END IF

              [Look at the RECORD data]
                  .
                  .
                  .
           END IF

Restrictions

     1)  Correctness of the C-kernel read by this routine is
         assumed.

     2)  Correctness of inputs must be ensured by the caller of
         this routine.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)

Version

    SPICELIB Version 1.0.1, 06-JUL-2021 (NJB) (JDR)

        Corrected code example: removed comment character preceding
        CKBSS call. Added note regarding difference between this
        search and those performed by the CK reader APIs CKGP and
        CKGPAV.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.0.0, 14-MAR-2014 (NJB) (BVS)