Procedure

     CKR01 ( C-kernel, read pointing record, data type 1 )

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

Abstract

     Read a pointing record from a CK segment, data type 1.

Required_Reading

     CK
     DAF

Keywords

     POINTING

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     DOUBLE PRECISION      DESCR  ( * )
     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   Spacecraft clock time.
     TOL        I   Time tolerance.
     NEEDAV     I   .TRUE. when angular velocity data is requested.
     RECORD     O   Pointing data record.
     FOUND      O   .TRUE. when data is found.

Detailed_Input

     HANDLE   is the integer handle of the CK file containing the
              segment.

     DESCR    is the descriptor of the segment.

     SCLKDP   is an encoded spacecraft clock time for which
              pointing is being requested. The SPICELIB routines
              SCENCD and SCDECD are used to encode and decode SCLK
              times.

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

              The record returned by CKR01 is the one whose time is
              closest to SCLKDP and within TOL units of SCLKDP.

     NEEDAV   is .TRUE. when angular velocity data is requested.

Detailed_Output

     RECORD   is the pointing record. Contents are as follows:

                 RECORD( 1 ) = CLKOUT

                 RECORD( 2 ) = q0
                 RECORD( 3 ) = q1
                 RECORD( 4 ) = q2
                 RECORD( 5 ) = q3

                 RECORD( 6 ) = Av1  ]
                 RECORD( 7 ) = Av2  |-- Returned optionally
                 RECORD( 8 ) = Av3  ]

              CLKOUT is the encoded spacecraft clock time for the
              returned pointing values. CLKOUT will be the closest
              time in the segment to the input time as long as it is
              within the input tolerance (see FOUND below). If SCLKDP
              falls at the exact midpoint of two times, the record
              for the greater of the two will be returned.

              The quantities q0 - q3 represent a quaternion.
              The quantities Av1, Av2, and Av3 represent the angular
              velocity vector, and are returned if the segment
              contains angular velocity data and NEEDAV is .TRUE.
              The components of the angular velocity vector are
              specified relative to the inertial reference frame
              for the segment.

     FOUND    is .TRUE. if a record was found to satisfy the pointing
              request. FOUND will be .FALSE. when there is no pointing
              instance within the segment whose time falls within
              the requested time tolerance on either side of the
              input time.

Parameters

     None.

Exceptions

     1)  If the specified handle does not belong to any file that is
         currently known to be open, an error is signaled by a routine
         in the call tree of this routine.

     2)  If DESCR is not a valid, packed descriptor of a segment in
         the CK file specified by HANDLE, the results of this routine
         are unpredictable.

     3)  If the segment is not of data type 1, as specified in the
         third integer component of the segment descriptor,
         the error SPICE(WRONGDATATYPE) is signaled.

     4)  If there is a need for angular velocity data and the segment
         contains no such data, the error SPICE(NOAVDATA) is signaled.

Files

     The file containing the segment is specified by its handle, and
     should be opened for read, either by CKLPF or DAFOPR.

Particulars

     See the CK Required Reading file for a detailed description of
     the structure of a type 1 pointing segment.

     This routine searches a type 1 segment for the pointing instance
     whose associated time is closest to the time that pointing was
     requested for. If this time is within the tolerance specified by
     the user, it sets FOUND equal to true and returns information in
     the array RECORD that CKE01 uses to evaluate the pointing at the
     time CLKOUT.

Examples

     The CKRnn routines are usually used in tandem with the CKEnn
     routines, which evaluate the record returned by CKRnn to give
     the pointing information and output time.

     The following code fragment searches backwards through a file
     (represented by HANDLE) for all segments applicable to the
     Voyager 2 wide angle camera, for a particular spacecraft clock
     time, which have data type 1. It then evaluates the pointing for
     that epoch and prints the result.

     The search performed here does not mimic the behavior of the CK
     reader APIs CKGP and CKGPAV, which consider data from multiple CK
     files, when available. See the CK Required reading for details.

     C
     C     - Get the spacecraft clock time. Must encode it for use
     C       in the C-kernel.
     C
     C     - Set the time tolerance high to catch anything close to
     C       the input time.
     C
     C     - We don't need angular velocity data.
     C
           SC     = -32
           INST   = -32002
           TOL    =  1000.D0
           NEEDAV = .FALSE.
           DTYPE  =  1
     C
     C     Load the Voyager 2 spacecraft clock kernel and the C-kernel.
     C
           CALL FURNSH ( 'VGR_SCLK.TSC'        )
           CALL DAFOPR ( 'VGR2_CK.BC',  HANDLE )
     C
     C     Convert the input request time to ticks.
     C
           WRITE (*,*) 'Enter spacecraft clock time string:'
           READ (*,FMT='(A)') SCLKCH
           CALL SCENCD ( SC, SCLKCH, SCLKDP )

     C
     C     Search backwards from the end of the CK file through all
     C     of the segments.
     C
           CALL DAFBBS ( HANDLE )
           CALL DAFFPA ( SFND   )

           DO WHILE ( SFND )

              CALL DAFGN ( IDENT                 )
              CALL DAFGS ( DESCR                 )
              CALL DAFUS ( DESCR, 2, 6, DCD, ICD )

              IF ( INST          .EQ. ICD( 1 )  .AND.
          .        DTYPE         .EQ. ICD( 3 )  .AND.
          .        SCLKDP + TOL  .GE. DCD( 1 )  .AND.
          .        SCLKDP - TOL  .LE. DCD( 2 ) ) THEN

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

                 IF ( FOUND ) THEN

                    CALL CKE01 ( NEEDAV, RECORD, CMAT, AV, CLKOUT )

                    WRITE (*,*) 'Segment descriptor and identifier:'
                    WRITE (*,*) DCD, ICD
                    WRITE (*,*) IDENT

                    WRITE (*,*) 'C-matrix:'
                    WRITE (*,*) CMAT

                 END IF

              END IF

              CALL DAFFPA ( SFND )

           END DO

Restrictions

     1)  The file containing the segment should be opened for read,
         either by CKLPF or DAFOPR.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     J.M. Lynch         (JPL)
     W.L. Taber         (JPL)
     R.E. Thurman       (JPL)
     I.M. Underwood     (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 1.2.2, 12-AUG-2021 (NJB) (JDR)

        Updated code example to use backwards search. 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.2.1, 22-AUG-2006 (EDW)

        Replaced references to LDPOOL with references
        to FURNSH.

    SPICELIB Version 1.2.0, 07-SEP-2001 (EDW)

        Replaced DAFRDA call with DAFGDA.
        Added IMPLICIT NONE.

    SPICELIB Version 1.1.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.1.0, 30-AUG-1991 (JML)

        This routine now checks the segment descriptor to
        determine if it has been given a type 1 segment.

        The FOUND flag is set to .FALSE. at the beginning of
        the routine.

        The $Particulars section was changed to provide a more
        general description of the function of this routine. The
        information that was originally in $Particulars was moved
        to the body of the code.

        The example program was changed so that the tolerance
        and data type are used in selecting which segments to read.

    SPICELIB Version 1.0.1, 02-NOV-1990 (JML)

        The example program was corrected so that the input
        instrument code was tested against ICD(1) instead of
        ICD(3).

    SPICELIB Version 1.0.0, 07-SEP-1990 (RET) (IMU)