dasec_c

Index Page dasec_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 dasec_c ( SpiceInt         handle,
                      SpiceInt         bufsiz,
                      SpiceInt         buflen,
                      SpiceInt       * n,
                      void           * buffer,
                      SpiceBoolean   * done   )
#### Abstract
       Extract comments from the comment area of a binary DAS file.
#### Required_Reading
       DAS
#### Keywords
       FILES
       UTILITY
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       handle     I   Handle of binary DAS file open with read access.
       bufsiz     I   Maximum size, in lines, of buffer.
       buflen     I   Line length associated with buffer.
       n          O   Number of comments extracted from the DAS file.
       buffer     O   Buffer in which extracted comments are placed.
       done       O   Indicates whether all comments have been extracted.
#### Detailed_Input
       handle   The file handle of a binary DAS file which has been
                opened with read access.

       bufsiz   The maximum number of comments that may be placed into
                buffer. This would typically be the declared array size
                for the C character string array passed into this
                routine.

       buflen   is the common length of the strings in buffer, including the
                terminating nulls.
#### Detailed_Output
       n        The number of comment lines extracted from the comment area
                of the binary DAS file attached to handle. This number will
                be <= bufsiz on output. If n == bufsiz and done !=
                SPICETRUE then there are more comments left to extract. If
                n == 0, then done == SPICETRUE, i.e., there were no
                comments in the comment area. If there are comments in the
                comment area, or comments remaining after the extraction
                process has begun, n > 0, always.

       buffer   A list of at most bufsiz comments which have been
                extracted from the comment area of the binary DAS
                file attached to handle.  buffer should be declared as
                follows:

                   ConstSpiceChar   buffer [bufsiz][buflen]

                Each string in buffer is null-terminated.

       done     A boolean flag indicating whether or not all of the
                comment lines from the comment area of the DAS file have
                been read. This variable has the value SPICETRUE after the
                last comment line has been read. It will have the value
                SPICEFALSE otherwise.

                If there are no comments in the comment area, this
                variable will have the value SPICETRUE, and n == 0.
#### Parameters
       None.
#### Exceptions
       1) If the size of the output line buffer is is not positive,
          the error SPICE(INVALIDARGUMENT) will be signaled.

       2) If a comment line in a DAS file is longer than the length
          of a character string array element of BUFFER, the error
          SPICE(COMMENTTOOLONG) will be signaled.

       3) If there is a mismatch between the number of comment
          characters found and the number of comment characters
          expected, the error SPICE(BADDASCOMMENTAREA) will be
          signaled.

       4) If the binary DAS file attached to HANDLE is not open for
          reading, an error will be signaled by a routine called by
          this routine.

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

       6) 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 an area which is reserved for storing
       annotations or descriptive textual information describing 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 of
       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 read the comments from the comment area of
       a binary DAS file, placing them into a line buffer. If the line
       buffer is not large enough to hold the entire comment area,
       the portion read will be returned to the caller, and the done
       flag will be set to SPICEFALSE. This allows the comment area to be
       read in "chunks," a buffer at a time. After all of the comment
       lines have been read, the done flag will be set to SPICETRUE.

       After all of the comments in DAS file have been read, the next
       call to this routine will start reading comments at the start
       of the comment area.

       This routine can be used to "simultaneously" extract comments
       from the comment areas of multiple binary DAS files.
#### Examples
       1) The following example will extract the entire comment area of a
          binary DAS file attached to HANDLE, displaying the comments on
          the terminal screen.

             #include <stdio.h>
             #include "SpiceUsr.h"

             int main( int argc, char ** argv )
             {

                #define LNSIZE          81
                #define MAXBUF          25

                SpiceBoolean            done;

                SpiceChar               buffer [MAXBUF][LNSIZE];
                SpiceChar             * filename;

                SpiceInt                handle;
                SpiceInt                i;
                SpiceInt                n;

                filename = argv[1];

                dasopr_ ( filename, &handle, (ftnlen)strlen(filename) );

                done = SPICEFALSE;

                while ( !done )
                {
                   dasec_c( handle, MAXBUF, LNSIZE, &n, buffer, &done );

                   for ( i = 0;  i < n;  i++ )
                   {
                      printf ( "%s\n", buffer[i] );
                   }
                }

                return ( 0 );
             }
#### Restrictions
       1) The comment area may consist only of printing ASCII characters,
          decimal values 32 - 126.

       2) 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 kept reasonable, 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.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       K.R. Gehringer (JPL)
#### Version
       -CSPICE Version 1.0.0, 24-FEB-2003 (NJB) (KRG)
#### Index_Entries
        extract comments from a das file
#### Link to routine dasec_c source file dasec_c.c

    Thu Apr 16 08:57:42 2009