Procedure

     DASAC ( DAS add comments )

     SUBROUTINE DASAC ( HANDLE, N, BUFFER )

Abstract

     Add comments from a buffer of character strings to the comment
     area of a binary DAS file, appending them to any comments which
     are already present in the file's comment area.

Required_Reading

     DAS

Keywords

     FILES
     UTILITY

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     INTEGER               N
     CHARACTER*(*)         BUFFER(*)

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE    I    DAS handle of a file opened with write access.
     N         I    Number of comments to put into the comment area.
     BUFFER    I    Buffer of lines to be put into the comment area.

Detailed_Input

     HANDLE   is the file handle of a binary DAS file which has been
              opened with write access.

     N        is the number of comments in BUFFER that are to be
              added to the comment area of the binary DAS file
              attached to HANDLE.

     BUFFER   is a buffer containing comments which are to be added
              to the comment area of the binary DAS file attached
              to HANDLE.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If the number of comments to be added is not positive, the
         error SPICE(INVALIDARGUMENT) is signaled.

     2)  If a non printing ASCII character is encountered in the
         comments, the error SPICE(ILLEGALCHARACTER) is signaled.

     3)  If the binary DAS file attached to HANDLE is not open with
         write access, an error is signaled by a routine in the call
         tree of this routine.

Files

     See argument HANDLE in $Detailed_Input.

Particulars

     Binary DAS files contain a data area which is reserved for storing
     annotations or descriptive textual information about the data
     contained in a file. This area is referred to as the ``comment
     area'' of the file. The comment area of a DAS file is a line
     oriented medium for storing textual information. The comment
     area preserves any leading or embedded white space in the line(s)
     of text which are stored so that the appearance of the
     information will be unchanged when it is retrieved (extracted) at
     some other time. Trailing blanks, however, are NOT preserved,
     due to the way that character strings are represented in
     standard Fortran 77.

     This routine will take a buffer of text lines and add (append)
     them to the comment area of a binary DAS file. If there are no
     comments in the comment area of the file, then space will be
     allocated and the text lines in BUFFER will then placed into the
     comment area. The text lines may contain only printable ASCII
     characters (decimal values 32 - 126).

     There is NO maximum length imposed on the significant portion
     of a text line that may be placed into the comment area of a
     DAS file. The maximum length of a line stored in the comment
     area should be reasonable, however, so that they may be easily
     extracted. A good value for this would be 255 characters, as
     this can easily accommodate ``screen width'' lines as well as
     long lines which may contain some other form of information.

Examples

     Let

           HANDLE   be the handle for a DAS file which has been opened
                    with write access.

           N        be the number of lines of text to be added to the
                    comment area of the binary DAS file attached to
                    HANDLE.

           BUFFER   is a list of text lines to be added to the comment
                    area of the binary DAS file attached to HANDLE.

     The call

           CALL DASAC ( HANDLE, N, BUFFER )

     will append the first N line(s) in BUFFER to the comment area
     of the binary DAS file attached to HANDLE.

Restrictions

     1)  This routine uses constants that are specific to the ASCII
         character sequence. The results of using this routine with
         a different character sequence are unpredictable.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)

Version

    SPICELIB Version 1.2.0, 13-AUG-2021 (JDR)

        Added IMPLICIT NONE standard.

        Edited the header to comply with NAIF standard. Removed
        unnecessary $Revisions section and fixed the first two entry
        version lines (Beta -> SPICELIB).

    SPICELIB Version 1.1.0, 05-FEB-2015 (NJB) (KRG)

        Updated to use ZZDDHHLU.

    SPICELIB Version 1.0.1, 12-MAY-1994 (KRG)

        Fixed a typo in the $Particulars section.

    SPICELIB Version 1.0.0, 23-NOV-1992 (KRG)