dasac_c

Index Page dasac_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 dasac_c ( SpiceInt       handle,
                      SpiceInt       n,
                      SpiceInt       buflen,
                      const void   * 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
#### 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.
       buflen     I   Line length associated with buffer.
       buffer     I   Buffer of lines to be put into the comment area.
#### Detailed_Input
       handle   The file handle of a binary DAS file which has been
                opened with write access.

       n        The number of strings in buffer that are to be
                appended to the comment area of the binary DAS file
                attached to handle.

       buflen   is the common length of the strings in buffer, including the
                terminating nulls.

       buffer   A buffer containing comments which are to be added
                to the comment area of the binary DAS file attached
                to handle.  buffer should be declared as follows:

                   ConstSpiceChar   buffer [n][buflen]

                Each string in buffer is null-terminated.
#### 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-null, non printing ASCII character is encountered in the
          comments, the error SPICE(ILLEGALCHARACTER) will be
          signaled.

       3) If the binary DAS file attached to handle is not open for
          write access, an error will be signaled by a routine called
          by this routine.

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

       5) If the input buffer string length buflen is not at least 2,
          the error SPICE(STRINGTOOSHORT) will be signaled.
#### 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.

          BUFLEN   be the declared line length of the buffer.

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

       The call

          dasac_c ( handle, n, BUFLEN, 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)
       K.R. Gehringer (JPL)
#### Version
       -CSPICE Version 1.1.0, 02-MAR-2003 (NJB)

           Added error check in wrapper for non-positive
           buffer line count.

       -CSPICE Version 1.0.0, 25-FEB-2003 (NJB) (KRG)
#### Index_Entries
        add comments to a binary das file
        append comments to a das file comment area
#### Link to routine dasac_c source file dasac_c.c

    Thu Apr 16 08:57:41 2009