Procedure

     DAFFNH ( DAF, file name to handle )

     ENTRY DAFFNH ( FNAME, HANDLE )

Abstract

     Return handle associated with a file name.

Required_Reading

     DAF

Keywords

     CONVERSION
     DAF
     FILES

Declarations

    CHARACTER*(*)         FNAME
    INTEGER               HANDLE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     FNAME      I   Name of a DAF file.
     HANDLE     O   Corresponding DAF file handle.

Detailed_Input

     FNAME    is the name of a previously opened DAF file.

Detailed_Output

     HANDLE   is the handle associated with the file.

Parameters

     None.

Exceptions

     1)  If the specified name does not specify any file currently
         known to be loaded as a DAF, the error SPICE(DAFNOSUCHFILE) is
         signaled. The value of HANDLE is undefined in this case.

     2)  If the file does not exist, an error is signaled by a routine
         in the call tree of this routine. The value of HANDLE is
         undefined in this case.

     3)  If an I/O error is generated in the process of connecting the
         specified name with a handle, the error is signaled by a
         routine in the call tree of this routine. The value of
         HANDLE is undefined in this case.

Files

     None.

Particulars

     It is sometimes easier to work with file names (which are
     meaningful, and often predictable) than with file handles
     (which are neither), especially in interactive situations.
     However, nearly every DAF routines requires that you use file
     handles to refer to files. DAFFNH is provided to bridge the gap
     between the two representations.

Examples

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

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

        CALL DAFFNH ( 'sample.DAF', HANDLE )

Restrictions

     1)  Only file names of DAFs loaded with interfaces present in
         this entry point umbrella should be passed into this routine.

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.1.2, 25-NOV-2021 (JDR)

        Edited the header to comply with NAIF standard.

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

        Eliminated unneeded $Revisions section.

        Corrected ordering of header section.

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

    SPICELIB Version 8.1.0, 02-APR-2002 (FST)

        Fixed a bug, where an error was signaled but the call to
        CHKOUT and the RETURN statement were omitted.

    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.

        In previous version of DAFAH, this module simply
        performed an INQUIRE on FNAME and looked in the
        file table for the logical unit returned.

        The integration of the new handle manager interfaces
        into this entry point has the possibility of increasing
        the complexity of this routine when more than UTSIZE
        files are loaded. Essentially, when given an arbitrary
        name, a total of FTSIZE INQUIRE statements may be executed
        to accurately connect FNAME with HANDLE. See ZZDDHFNH and
        ZZDDHF2H for details.

    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 2.0.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 2.0.0, 25-FEB-1993 (JML)

        The INQUIRE statement that checks if the file is open now also
        checks that the file exists. Two new exceptions were added as
        a result of this change.

        A RETURN statement was added after the error signaled when
        the file is not open.

        The file name is checked to see if it is blank.

        The file name string that is passed to the FORTRAN INQUIRE
        statement has been chopped at the last non-blank character.

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

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

    SPICELIB Version 1.1.1, 18-SEP-1991 (HAN)

        The $Revisions section was incorrectly named $Version. This has
        been fixed.

    SPICELIB Version 1.1.0, 05-NOV-1990 (HAN)

        Call to CHKIN was corrected. The module was checking in
        as 'DAFFHN'.

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

        Literature references added to the header.

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