Procedure

     SGFRVI ( Generic Segments: Fetch ref. value and index )

     SUBROUTINE SGFRVI ( HANDLE, DESCR, X, VALUE, INDX, FOUND )

Abstract

     Find the reference value associated with the value X and its 
     index in a generic segment. The segment is identified by a DAF 
     file handle and segment descriptor.

Required_Reading

     DAF

Keywords

     GENERIC SEGMENTS

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     DOUBLE PRECISION      DESCR ( * )
     DOUBLE PRECISION      X
     DOUBLE PRECISION      VALUE
     INTEGER               INDX
     LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   The handle of a DAF open for reading.
     DESCR      I   The descriptor for a DAF generic segment.
     X          I   The key value used to find a reference and index.
     VALUE      O   The reference value associated with X.
     INDX       O   The index of VALUE within the reference values.
     FOUND      O   A flag indicating whether values for X were found.

Detailed_Input

     HANDLE   is the handle of a DAF open for reading

     DESCR    is the descriptor of the generic segment that we are
              going to search for a reference value to associate with
              X.

     X        is a value for which the associated reference value
              and reference index is requested.

Detailed_Output

     VALUE    is the reference value associated with the input value
              X.

     INDX     is the index of VALUE within the set of reference
              values for the generic segment. This value may be used
              to obtain a particular packet of data from the generic
              segment.

     FOUND    is a logical flag indicating whether a reference value
              associated with X was found. If a reference value was
              found, FOUND will have a value of .TRUE.; otherwise it
              will have a value of .FALSE.

Parameters

     This subroutine makes use of parameters defined in the file
     'sgparam.inc'.

Exceptions

     1)  If the reference directory structure is unrecognized, the
         error SPICE(UNKNOWNREFDIR) is signaled. The most likely cause
         of this error is that an upgrade to your version of the SPICE
         toolkit is needed.

     2)  If a value computed for the index of an implicitly indexed
         generic segment is too large to be represented as an integer,
         the error SPICE(INDEXTOOLARGE) is signaled.

Files

     See the description of HANDLE above.

Particulars

     This routine allows you to easily find the index and value
     of the reference item that should be associated with a
     value X. Given this information you can then easily retrieve
     the packet that should be associated with X.

Examples

     Suppose that you have a generic segment that contains the
     following items.

         1)  Packets that model the motion of a body as a function
             of time over some interval of time.

         2)  Reference values that are the epochs corresponding
             to the beginning of the intervals for the packets.

     To retrieve the correct packet to use to compute the position
     and velocity of the body at a particular epoch,  ET, you could
     use the following code. (Note this block of code assumes that
     you aren't going to run into any exceptional cases such as ET
     falling outside the range of times for which the packets can
     provide ephemeris data.)

        Find out the index of the time that should be associated
        with the ET we've been given

        CALL SGFRVI ( HANDLE, DESCR, ET,  ETFND, INDX, FOUND )

        Fetch the INDX'th ephemeris packet from the segment.

        CALL SGFPKT ( HANDLE, DESCR, INDX, EPHEM )

Restrictions

     1)  The segment described by DESCR MUST be a generic segment,
         otherwise the results of this routine are not predictable.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     W.L. Taber         (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 1.2.1, 26-OCT-2021 (JDR)

        Edited the header to comply with NAIF standard.

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

        Replaced DAFRDA call with DAFGDA.

    SPICELIB Version 1.1.0, 08-MAY-1996 (WLT)

        A bug was found in the EXPCLS index case when the
        trying to retrieve the last value in a generic segment.
        This bug was discovered by the HP compiler complaining
        that an index used was not initialized.

        The offending line was

                 MYVALU = BUFFER(I)

        The corrected line is:

                 MYVALU = BUFFER(BFINDX)

    SPICELIB Version 1.0.0, 28-MAR-1994 (KRG) (WLT)