Index Page dafac_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void dafac_c ( SpiceInt      handle,
                      SpiceInt      n,
                      SpiceInt      lenvals,
                      const void  * buffer  )
#### Abstract
       Add comments from a buffer of character strings to the comment
       area of a binary DAF file, appending them to any comments which
       are already present in the file's comment area.
#### Required_Reading
       DAF
#### Keywords
       FILES
       UTILITY
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       handle     I    handle of a DAF opened with write access.
       n          I    Number of comments to put into the comment area.
       lenvals    I    Length of elements
       buffer     I    Buffer of comments to put into the comment area.
#### Detailed_Input
       handle   is the file handle of a binary DAF which has been opened
                with write access.

       n        is the number of rows in the array `buffer'.  This is
                also the number of comment lines in `buffer' that are to be
                added to the comment area of the binary DAF attached to
                `handle'.

       buffer   A string buffer containing comments which are to be added
                to the comment area of the binary DAF attached to `handle'.
                buffer should be declared by the caller has follows:

                   SpiceChar    buffer[n][lenvals];

                Each row of the buffer should contain one comment line.
#### Detailed_Output
       None.
#### Parameters
       None.
#### Exceptions
       1) If the number of comments to be added is not positive, the
          error SPICE(INVALIDARGUMENT) will be signaled.

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

       3) If the binary DAF file attached to HANDLE is not open with
          write access an error will be signalled by a routine called by
          this routine.

       4) If the end of the comments cannot be found, i.e., the end of
          comments marker is missing on the last comment record, the error
          SPICE(BADCOMMENTAREA) will be signaled.

       5) If the input pointer `buffer' is null, the error
          SPICE(NULLPOINTER) will be signaled.

       6) If the input buffer string length indicated by `lenvals'
          is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled.
#### Files
       See argument `handle' in $ Detailed_Input.
#### Particulars
       A binary DAF contains 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 DAF is a line oriented
       medium for storing textual information. The comment area preserves
       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 DAF. If there are no comments in the
       comment area of the file, then space will be allocated and the text
       lines in `buffer' will be 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 DAF. The
       maximum length of a line stored in the comment area should be
       reasonable, however, so that they may be easily extracted. A good
       maximum 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
       1) Let

             handle   be the handle for a DAF 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 DAF attached to handle.

             lenvals  be the length of the rows of a string buffer.

             buffer   is an array of text lines to be added to the comment
                      area of the binary DAF attached to handle. `buffer'
                      normally is declared

                         SpiceChar buffer [n][lenvals];

          The call

             dafac_c ( handle, n, lenvals, buffer );

          will append the first n line(s) in `buffer' to the comment area
          of the binary DAF 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.

       2) This routine is only used to extract records on environments
          whose characters are a single byte in size.  Updates to this
          routine and routines in its call tree may be required to
          properly handle other cases.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       K.R. Gehringer (JPL)
#### Version
       -CSPICE Version 1.0.0, 16-NOV-2006 (NJB) (KRG)
#### Index_Entries
       add comments to a binary daf file
       append comments to a daf file comment area
#### Link to routine dafac_c source file dafac_c.c

    Wed Jun  9 13:05:20 2010