Procedure

     CKSNS ( C-kernel, Select next segment )

     ENTRY CKSNS ( HANDLE, DESCR, SEGID, FOUND )

Abstract

     Search through loaded files to find a segment matching the
     requested instrument, time, and need for angular velocity,
     buffering segment descriptors, identifiers, and handles in the
     process to minimize file reads.

Required_Reading

     CK
     DAF

Keywords

     POINTING

Declarations

    INTEGER               HANDLE
    DOUBLE PRECISION      DESCR  ( * )
    CHARACTER*(*)         SEGID
    LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     O   Handle of file containing the applicable segment.
     DESCR      O   Descriptor of the applicable segment.
     SEGID      O   Identifier of the applicable segment.
     FOUND      O   .TRUE. if a segment was found.

Detailed_Input

     None.

Detailed_Output

     HANDLE   is an integer handle of the file containing the
              segment matching the instrument and time
              specifications made in the last call to CKBSS.

     DESCR,
     SEGID    are the descriptor and identifier of the segment found
              which matches the instrument and time specifications
              made in the last call to CKBSS.

     FOUND    is .TRUE. if an applicable segment was found, .FALSE.
              otherwise. If FOUND is .FALSE., the values of the
              other arguments are meaningless.

Parameters

     None.

Exceptions

     1)  If CKSNS is called without CKBSS ever having been called,
         the error SPICE(CALLCKBSSFIRST) is signaled.

     2)  If no segment is found that matches the search criteria,
         FOUND is set to .FALSE., but the values of HANDLE, DESCR,
         and SEGID will be meaningless.

Files

     All files loaded by CKLPF are potential search targets for
     CKSNS. The files are all referred to by their integer handles.

Particulars

     CKSNS is used to locate segments based on the search criteria
     established by the most recent call to CKBSS. When a segment
     is found it will have the following characteristics:

        1) Its instrument will match the instrument specified in the
           call to CKBSS.

        2) Its time interval will intersect the time interval

              [SCLKDP - TOL, SCLKDP + TOL],

           where SCLKDP and TOL were specified in the call to CKBSS.

        3) If there is a need for angular velocity data, as specified
           by NEEDAV in the call to CKBSS, a returned segment
           will contain angular velocity data. If there is no need
           for such data, the returned segment may or may not contain
           angular velocity data.

     The first call to CKSNS following a call to CKBSS starts a search
     through loaded files and either returns the first applicable
     segment, or indicates that no segment was found.

     CKSNS searches through last-loaded files first. Individual
     files are searched backwards, so that segments that were inserted
     last into the file get checked first.

     Subsequent calls to CKSNS pick up the search exactly where the
     previous calls left off. If a segment is not found, future calls
     will also indicate that no segment could be found, until a new
     search is begun.

     CKSNS also buffers segment descriptors and identifiers, to
     attempt to minimize file reads.

Examples

     See $Examples in CKBSR.

Restrictions

     1)  This subroutine assumes that a search has been initiated by
         a call to CKBSS.

     2)  When a CK file is loaded or unloaded, a new search must
         be started via a call to CKBSS before this routine may
         be called.

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)

Version

    SPICELIB Version 4.6.0, 13-OCT-2021 (JDR) (NJB)

        Edited the header to comply with NAIF standard.

        Relocated initialization of FOUND so it is always
        executed, even if an error state is indicated by RETURN().

    SPICELIB Version 4.5.1, 30-JAN-2017 (NJB)

        Corrected various spelling errors within comments.

    SPICELIB Version 4.5.0, 24-FEB-2011 (NJB)

        Bug fix: in the 'MAKE ROOM' state, when the suspended activity
        is 'ADD TO FRONT' and no segment table room is available, the
        instrument table's pointer to the current segment list is now
        set to null. Previously the pointer was allowed to go stale.

    SPICELIB Version 4.2.0, 08-SEP-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in MOVED call.

    SPICELIB Version 4.1.0, 20-NOV-2001 (NJB)

        Bug fixes:

           1) When a segment list is freed because the entire list
              is contributed by a single CK file, and the list is
              too large to be buffered, the corresponding instrument
              table pointer is now set to null.

           2) An algorithm change has eliminated a bug caused by not
              updating the current instrument index when instrument
              table entries  having empty segment lists were compressed
              out of the instrument table. Previously the instrument
              table pointer IINDEX could go stale after the
              compression.

           3) DAF calls are now followed by tests of FAILED()
              in order to ensure that the main state loop terminates.

        The "re-use interval" feature was introduced to improve speed
        in the case where repeated, consecutive requests are satisfied
        by the same segment.

        The segment list cost algorithm was modified slightly:
        the contribution of a file search to the cost of a list
        is included only when the file search is completed. The
        cost of finding the re-use interval is accounted for when
        unbuffered searches are required.

        The file table size has been increased to 1000, in order
        to take advantage of the DAF system's new ability to load
        1000 files.

        The instrument table size has been increased to 100 in order to
        decrease the chance of thrashing due to swapping segment
        lists for different bodies.

        Various small updates and corrections were made to the
        comments throughout the file.

    SPICELIB Version 4.0.0, 17-FEB-2000 (WLT)

        Added the Entry point CKHAVE.

    SPICELIB Version 3.0.0, 03-MAR-1999 (WLT)

        The parameter STSIZE was increased from 1000 to 4000 to
        avoid the buffering error that exists in the CKBSR.

    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, 01-NOV-1990 (JML)

        A check on the initial value of the variable STATUS
        was added in order to detect the situation in which
        CKBSS was never called to initiate a search.


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