Procedure

     PCKSFS ( PCK, select file and segment )

     ENTRY PCKSFS ( BODY, ET, HANDLE, DESCR, IDENT, FOUND )

Abstract

     Search through loaded files to find the first segment applicable
     to the body and time specified. Buffer searched segments in the
     process, to attempt to avoid re-reading files.

Required_Reading

     PCK

Keywords

     FILES
     PCK

Declarations

    INTEGER               BODY
    DOUBLE PRECISION      ET
    INTEGER               HANDLE
    DOUBLE PRECISION      DESCR  ( * )
    CHARACTER*(*)         IDENT
    LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     BODY       I   Body ID.
     ET         I   Ephemeris time.
     HANDLE     O   Handle of file containing the applicable segment.
     DESCR      O   Descriptor of the applicable segment.
     IDENT      O   Identifier of the applicable segment.
     FOUND      O   Indicates whether or not a segment was found.

Detailed_Input

     BODY     is the NAIF integer code of an ephemeris object,
              typically a solar system body.

     ET       is a time, in seconds past the epoch J2000 TDB.

Detailed_Output

     HANDLE   is the handle of the binary PCK file containing a
              located segment.

     DESCR    is the descriptor of a located segment.

     IDENT    is the identifier of a located segment.

     FOUND    is a logical flag indicating whether a requested segment
              was found or not.

Parameters

     None.

Exceptions

     1)  If an attempt is made to call PCKSFS when there aren't any
         files loaded, the error SPICE(NOLOADEDFILES) is signaled.

Files

     All files loaded by PCKLOF are potential search targets for
     PCKSFS.

Particulars

     This routine finds the highest-priority segment, in any loaded
     PCK file, such that the segment provides data for the specified
     body and epoch.

Examples

     See $Examples in PCKBSR.

Restrictions

     1)  If Fortran I/O errors occur while searching a loaded PCK
         file, the internal state of this suite of routines may
         be corrupted. It may be possible to correct the state
         by unloading the pertinent PCK files and then re-loading
         them.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     E.D. Wright        (JPL)
     K.S. Zukor         (JPL)

Version

    SPICELIB Version 4.3.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.2.2, 30-JAN-2017 (NJB)

        Corrected various spelling errors within comments.

    SPICELIB Version 4.2.1, 03-JAN-2014 (EDW)

        Minor edits to $Procedure; clean trailing whitespace.
        Removed unneeded $Revisions section.

    SPICELIB Version 4.2.0, 01-MAR-2011 (NJB)

        Bug fix:

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

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

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

    SPICELIB Version 1.1.0, 08-NOV-2001 (NJB)

        Bug fixes:

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

           2) An algorithm change has eliminated a bug caused by not
              updating the current body index when body table entries
              having empty segment lists were compressed out of the
              body table. Previously the body table pointer BINDEX
              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.

           4) A subscript bound violation in a loop termination test
              was corrected. The loop is located in the
              'SEARCH W/O BUFFERING' block; it finds the start of a
              partial list that is to be freed.

        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 body table size has been increased to 200 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.

        In order to simplify the source code, the in-line singly
        linked list implementation of the segment table has been
        replaced by an implementation relying on the SPICELIB
        doubly linked list routines.

    SPICELIB Version 1.0.0, 16-MAR-1994 (KSZ)

        This differs only slightly from the SPKXXX code.
        The main difference is that the SFS subroutine returns
        FOUND = .FALSE. if no files are found, rather than returning
        an error.