Procedure

     DAFGH ( DAF, get handle )

     ENTRY DAFGH ( HANDLE )

Abstract

     Return (get) the handle of the DAF currently being searched.

Required_Reading

     DAF

Keywords

     FILES

Declarations

    INTEGER               HANDLE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     O   Handle for current DAF.

Detailed_Input

     None.

Detailed_Output

     HANDLE   is the handle for the current DAF (the handle connected
              to the DAF that is currently being actively searched).

Parameters

     None.

Exceptions

     1)  If this routine is called when no search is in progress in the
         the current DAF, the error SPICE(DAFNOSEARCH) is signaled.

     2)  If the DAF whose handle is to be returned has actually been
         closed, an error is signaled by a routine in the call tree of
         this routine.

Files

     This routine returns the handle of a DAF that is currently
     being searched.

Particulars

     Under rare circumstances, it may be necessary to identify the
     particular DAF that is being searched (such as when the search is
     begun by one module and continued by another).

Examples

     Consider a program like the following, which examines the
     individual arrays in a DAF and examines the contents of those
     meeting certain criteria.

        CALL DAFOPW ( FNAME, HANDLE )
        CALL DAFBFS ( HANDLE )
        CALL DAFFNA ( FOUND  )

        DO WHILE ( FOUND )

           CALL CHECK_DAF ( STATUS )

           IF ( STATUS .EQ. 'EXAMINE' ) THEN
              CALL EXAMINE_DAF
           END IF

           CALL DAFFNA ( FOUND )

        END DO

     The subroutine CHECK_DAF, which assumes that a search is in
     progress, gets the summary and name for the current array, and
     uses them to decide whether the data in the array merit further
     consideration.

        SUBROUTINE CHECK_DAF ( STATUS )

        CALL DAFGS ( SUM )
        CALL DAFGN ( NAME )
        CALL DAFUS ( SUM, ND, NI, DC, IC )
         .
         .

     The subroutine EXAMINE_DAF needs to examine the data in
     the array itself. In order to do do, it needs to have access
     not only to the summary, but to the handle of the file
     containing the array. This is provided by DAFGH.

        SUBROUTINE EXAMINE_DAF

        CALL DAFGS ( SUM  )
        CALL DAFGH ( HANDLE )
        CALL DAFUS ( SUM, ND, NI, DC, IC )

        CALL DAFGDA ( HANDLE, BEGIN, END, DATA )
         .
         .

Restrictions

     1)  Calls that do or may change DAF addresses of DAF summaries,
         names, or data of a given DAF file should not be made during
         a search of that file initiated by either DAFBFS or DAFBBS.
         No such changes should be made between the start of a search
         and calls to any entry point that reads or writes to the
         summary of the "current array" found by that search, or
         that returns a "found" flag indicating whether the current
         array exists.

         Changing the size of the comment area while a search is in
         progress can invalidate record numbers stored in local data
         structures of this routine. This can cause corrupted array
         summaries and names to be returned upon read access and file
         corruption to occur upon write access.

         Adding arrays (aka "segments") while either a forward or
         backward search is in progress can cause the search to miss
         the new segments.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     H.A. Neilan        (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 2.0.4, 26-OCT-2021 (JDR) (NJB)

        Edited the header to comply with NAIF standard. Extended $Files
        section.

        Updated $Restrictions section.

    SPICELIB Version 2.0.3, 14-MAR-2017 (NJB)

        Updated header example: changed DAFRDA call to DAFGDA call.

    SPICELIB Version 2.0.2, 18-AUG-2011 (EDW)

        Eliminated unneeded $Revisions section.

        Removed the obsolete Reference citation to "NAIF
        Document 167.0."

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

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

    SPICELIB Version 2.0.0, 04-SEP-1991 (NJB) (WLT)

        Updated to support simultaneous searches of multiple DAFs.

        This routine now operates on the current DAF---the one at
        the head of the active list. All saved state variables
        used by this routine are now part of the state table, or
        its associated set of pointers.

    SPICELIB Version 1.0.1, 22-MAR-1990 (HAN)

        Literature references added to the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (IMU)