Procedure

     DAFONW ( DAF, open new )

     ENTRY DAFONW ( FNAME, FTYPE, ND, NI, IFNAME, RESV, HANDLE )

Abstract

     Open a new DAF for subsequent write requests.

Required_Reading

     DAF

Keywords

     DAF
     FILES

Declarations

    CHARACTER*(*)         FNAME
    CHARACTER*(*)         FTYPE
    INTEGER               ND
    INTEGER               NI
    CHARACTER*(*)         IFNAME
    INTEGER               RESV
    INTEGER               HANDLE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     FNAME      I   Name of DAF to be opened.
     FTYPE      I   Mnemonic code for type of data in the DAF file.
     ND         I   Number of double precision components in summaries.
     NI         I   Number of integer components in summaries.
     IFNAME     I   Internal file name.
     RESV       I   Number of records to reserve.
     HANDLE     O   Handle assigned to DAF.

Detailed_Input

     FNAME    is the name of a new DAF to be created (and
              consequently opened for write access).

     FTYPE    is a code for type of data placed into a DAF file.
              The first nonblank character and the three (3)
              characters immediately following it, giving four (4)
              characters, are used to represent the type of the data
              placed in the DAF file. This is provided as a
              convenience for higher level software. It is an error
              if this string is blank. When written to the DAF file,
              the value for the type IS case sensitive; what you put
              in is what you get out, so be careful.

              NAIF has reserved for its own use file types
              consisting of the upper case letters (A-Z) and the
              digits 0-9. NAIF recommends lower case or mixed case
              file types be used by all others in order to avoid
              any conflicts with NAIF file types.

     ND       is the number of double precision components
              in each array summary of the new file.

     NI       is the number of integer components in each
              array summary in the new file.

     IFNAME   is the internal file name (containing as many as 60
              characters) for the new file. This should uniquely
              identify the file.

     RESV     is the number of records in the new file to be
              reserved; these records will not be used to store any
              data belonging to DAF arrays subsequently written to
              the file. The user may reserve records 2 through (2 +
              RESV - 1) in the file. SPICE kernels based on the DAF
              format use the reserved record area to store optional
              textual information; for these kernels, the reserved
              records contain the file's "comment area."

              When RESV is non-zero, this routine writes an
              end-of-comments character into the first byte of
              record 2, and fills the rest of the allocated records
              will null (ASCII code 0) characters.

Detailed_Output

     HANDLE   is the file handle associated with the file. This
              handle is used to identify the file in subsequent
              calls to other DAF routines.

Parameters

     INTEOC   is the ASCII decimal integer code of the character
              recognized by SPICE as representing the end of the
              comment data in the reserved record area.

Exceptions

     1)  If the specified file cannot be opened without exceeding
         the maximum number of files, the error SPICE(DAFFTFULL)
         is signaled.

     2)  If the input argument ND is out of the range [0, 124]
         or if NI is out of the range [2, 250], the error
         SPICE(DAFINVALIDPARAMS) is signaled.

     3)  If

            ND + ( NI + 1 ) / 2   >  125

         the error SPICE(DAFINVALIDPARAMS) is signaled.

     4)  If the number of records to be reserved is not zero or
         positive, the error SPICE(DAFNORESV) is signaled.

     5)  If an I/O error occurs in the process of opening the file,
         the error is signaled by a routine in the call tree of this
         routine.

     6)  If (for some reason) the initial records in the file cannot
         be written, the error SPICE(DAFWRITEFAIL) is signaled.

     7)  If no logical units are available, an error is
         signaled by a routine in the call tree of this routine.

     8)  If the file name is blank or otherwise inappropriate,
         an error is signaled by a routine in the call tree of this
         routine.

     9)  If the file type is blank, the error SPICE(BLANKFILETYPE)
         is signaled.

     10) If the file type contains nonprinting characters, decimal
         0-31 and 127-255, the error SPICE(ILLEGALCHARACTER) is
         signaled.

Files

     See argument FNAME.

Particulars

     This routine supersedes DAFOPN as the method for opening a new DAF
     file. It includes a data type identifier as part of the ID word of
     a DAF file it creates.

     The DAFs created by DAFONW have initialized file records but
     do not yet contain any arrays. See the DAF Required Reading
     for a discussion of file records.

Examples

     In the following code fragment, DAFONW is used to open a file,
     to which a new array is then added. This file will have the data
     type 'TEST' which may be used to distinguish production data from
     test data at a user subroutine level.

        FNAME = 'test.bin'
        FTYPE = 'TEST'

        CALL DAFONW   ( FNAME, FTYPE,  ND,  NI,  IFNAME, 0, HANDLE )

        CALL DAFBNA   ( HANDLE, SUM, NAME  )
        CALL GET_DATA ( DATA,   N,   FOUND )

        DO WHILE ( FOUND )

           CALL DAFADA   ( DATA, N        )
           CALL GET_DATA ( DATA, N, FOUND )

        END DO

        CALL DAFENA

Restrictions

     1)  Files opened using this routine must be closed with DAFCLS.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     W.L. Taber         (JPL)
     F.S. Turner        (JPL)
     E.D. Wright        (JPL)

Version

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

        Edited the header to comply with NAIF standard.

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

        Corrected ordering of header section.

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

    SPICELIB Version 9.0.0, 09-NOV-2006 (NJB)

        DAFONW now writes a EOC character to the first byte
        of the second record when NRESV > 0.

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

        This routine was updated to accommodate changes to the
        handle manager interface. See DAFAH's Revision section
        for details.

    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 2.0.0, 03-MAR-1999 (FST)

        The entry point was modified to insert the FTP validation
        string, as well as the binary file format into the file record.

    SPICELIB Version 1.1.0, 08-MAR-1996 (KRG)

        The modifications support the notion of a DAF comment area,
        and involve writing NULL filled reserved records when the
        number of reserved records is greater than zero (0).

        Some nested IF...THEN...ELSE IF...THEN...END IF constructs
        were expanded to be independent IF...THEN...END IF tests.
        The tests were for IOSTAT errors on cascading write statements
        nested in the IF...ELSE IF... statements, and this was
        confusing. These tests were restructured so that IOSTAT is
        tested after each write statement which is equivalent to the
        original intent and easier to read.

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

        This routine implements the notion of a file type for DAF
        files. It allows type information to be added to the file ID
        word.

        This routine is a modified version of DAFOPN. See the revision
        history of that entry point for details of changes before the
        creation of this entry point.