Procedure

     DAFHFN ( DAF, handle to file name )

     ENTRY DAFHFN ( HANDLE, FNAME )

Abstract

     Return the name of the file associated with a handle.

Required_Reading

     DAF

Keywords

     CONVERSION
     DAF
     FILES

Declarations

    INTEGER               HANDLE
    CHARACTER*(*)         FNAME

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle of a DAF file.
     FNAME      O   Corresponding file name.

Detailed_Input

     HANDLE   is the handle associated with a previously opened
              DAF file.

Detailed_Output

     FNAME    is the name of the file.

Parameters

     None.

Exceptions

     1)  If the specified handle does not belong to any file that is
         currently known to be loaded as a DAF, the error
         SPICE(DAFNOSUCHHANDLE) is signaled.

Files

     None.

Particulars

     It may be desirable to recover the names of one or more DAF
     files in a different part of the program from the one in which
     they were opened. Note that the names returned by DAFHFN may
     not be identical to the names used to open the files. Under
     most operating systems, a particular file can be accessed using
     many different names. DAFHFN returns one of them.

Examples

     In the following code fragment, the name of a DAF is
     recovered using the handle associated with the file.

        CALL DAFOPR ( 'sample.DAF', HANDLE )
         .
         .

        CALL DAFHFN ( HANDLE, FNAME )

     Depending on the circumstances (operating system, compiler,
     default directory) the value of FNAME might resemble any of
     the following:

        'USER$DISK:[WYATT.IMAGES]SAMPLE.DAF;4'

        '/wyatt/images/sample.DAF'

        'A:\IMAGES\SAMPLE.DAF'

     On the other hand, it might not.

Restrictions

     1)  This routine may only be used to retrieve the names of DAFs
         loaded or created using the interfaces available in this entry
         point umbrella. Using this entry point to retrieve names for
         files not loaded through these interfaces may result in
         unexpected behavior.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     J.M. Lynch         (JPL)
     H.A. Neilan        (JPL)
     W.L. Taber         (JPL)
     F.S. Turner        (JPL)
     I.M. Underwood     (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 8.0.2, 25-NOV-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 8.0.1, 10-OCT-2012 (EDW)

        Corrected ordering of header section.

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

    SPICELIB Version 8.0.0, 13-NOV-2001 (FST)

        This routine was updated to utilize the new handle manager
        software to manage binary file formats and consolidated
        I/O code.

    SPICELIB Version 7.0.4, 08-OCT-1999 (WLT)

        The environment lines were expanded so that the supported
        environments are now explicitly given. New
        environments are WIN-NT

    SPICELIB Version 7.0.3, 16-SEP-1999 (NJB)

        CSPICE environments were added. Some typos were corrected.

    SPICELIB Version 7.0.2, 28-JUL-1999 (WLT)

        The environment lines were expanded so that the supported
        environments are now explicitly given. New
        environments are PC-DIGITAL, SGI-O32 and SGI-N32.

    SPICELIB Version 7.0.1, 17-MAR-1999 (WLT)

        The environment lines were expanded so that the supported
        environments are now explicitly given. Previously,
        environments such as SUN-SUNOS and SUN-SOLARIS were implied
        by the environment label SUN.

    SPICELIB Version 1.1.1, 29-SEP-1993 (KRG)

        Removed references to specific DAF file open routines in the
        $Detailed_Input section of the header. This was done in order
        to minimize documentation changes if these open routines ever
        change.

    SPICELIB Version 1.1.0, 25-FEB-1993 (JML)

        IOSTAT is checked after the INQUIRE statement.

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

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

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

        Literature references added to the header.

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