Procedure

     DAFSIH ( DAF, signal invalid handles )

     ENTRY DAFSIH ( HANDLE, ACCESS )

Abstract

     Signal an error if a DAF file handle does not designate a DAF
     that is open for a specified type of access.

Required_Reading

     DAF
     ERROR
     SETS

Keywords

     DAF
     FILES

Declarations

    INTEGER               HANDLE
    CHARACTER*(*)         ACCESS

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   HANDLE to be validated.
     ACCESS     I   String indicating access type.

Detailed_Input

     HANDLE   is a DAF handle to validate. For HANDLE to be
              considered valid, it must specify a DAF that is
              open for the type of access specified by the input
              argument ACCESS.


     ACCESS   is a string indicating the type of access that
              the DAF specified by the input argument HANDLE
              must be open for. The values of ACCESS may be


                 'READ'      File must be open for read access
                             by DAF routines. All open DAFs
                             may be read.

                 'WRITE'     File must be open for write access
                             by DAF routines.

                             Note that files open for write
                             access may be read as well as
                             written.


              Leading and trailing blanks in ACCESS are ignored,
              and case is not significant.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If the input argument ACCESS has an unrecognized value,
         the error SPICE(INVALIDOPTION) is signaled.

Files

     None.

Particulars

     This routine signals the error SPICE(DAFINVALIDACCESS) if the
     DAF designated by the input argument HANDLE is not open
     for the specified type of access. If HANDLE does not designate
     an open DAF, the error SPICE(DAFNOSUCHHANDLE) is signaled.

     This routine allows subroutines to test file handles for
     validity before performing operations on them, such as
     finding the name of the file designated by a handle. Many
     DAF operations on handles may cause unpredictable program
     behavior if the handles are invalid. This routine should
     be used in situations where the appropriate action to take upon
     determining that a handle is invalid is to signal an error.
     DAFSIH centralizes the error response for this type of error in a
     single routine.

     In cases where it is necessary to determine the validity of a
     file handle, but it is not an error for the handle to refer
     to a closed file, the entry point DAFHOF should be used instead
     of DAFSIH.

Examples

     1)  Add data to a DAF specified by a file handle. Signal an
         error if the file is not open for writing. Check the
         SPICELIB error status function FAILED after calling
         DAFSIH, so that the routine will return if DAFSIH
         signaled an error (we're presuming that this code
         fragment would be used in a subroutine).

            C
            C     Check that HANDLE is valid, then add data to the
            C     file specified by HANDLE.
            C
                  CALL DAFSIH  (  HANDLE, 'WRITE' )

                  IF ( FAILED() ) THEN
                     RETURN
                  END IF

                  CALL DAFBNA (  HANDLE,  SUM,    NAME )
                  CALL DAFADA (  DATA,    N            )
                  CALL DAFENA

     2)  Find the size of an array in a DAF specified by a file
         handle. Signal an error if the file is not open for reading.

            C
            C     Check that HANDLE is valid, then obtain the
            C     current array summary and compute the size of
            C     the current array.
            C
                  CALL DAFSIH  ( HANDLE, 'READ' )

                  IF ( FAILED() ) THEN
                     RETURN
                  END IF

            C
            C     Obtain the summary format, then the integer and d.p.
            C     components of the summary. Finally, compute the
            C     array length.
            C
                  CALL DAFHSF (  HANDLE, ND, NI          )
                  CALL DAFGS  (  SUMMRY                  )
                  CALL DAFUS  (  SUMMRY, ND, NI, DC, IC  )

                  IA      =  IC( NI - 1 )
                  FA      =  IC( NI     )
                  LENGTH  =  FA  -  IA  +  1

     3)  Make sure that a file handle designates an open DAF. Signal
         an error if it does not.

         Note that if a DAF is open at all, read access is allowed.

                  CALL DAFSIH ( HANDLE, 'READ' )

                  IF ( FAILED() ) THEN
                     RETURN
                  END IF

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     J.M. Lynch         (JPL)
     W.L. Taber         (JPL)
     F.S. Turner        (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.

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

        IOSTAT is now checked after the INQUIRE statement.

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

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

    SPICELIB Version 1.0.0, 03-SEP-1991 (NJB) (WLT)