Index Page
cspice_dafec
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_DAFEC reads comment text from the comment area of a DAF.

   For important details concerning this module's function, please refer to
   the CSPICE routine dafec_c.

I/O


   Given:

      handle   the scalar integer file handle referring to a DAF file opened
               with read access. This handle refers to the DAF file from which
               to read the comment section.

      bufsiz   a scalar integer defining the maximum number of comment lines
               to copy to 'buffer'.

      lenout   a scalar integer defining the allowed length of each string
               element of the output 'buffer'. This length must be large enough
               to hold the longest output string. The SPICE system
               imposes no limit on the length of comment lines, so 'lenout'
               normally should be set to a "generous" value that is unlikely
               to be exceeded.

   the call:

      cspice_dafec, handle, bufsiz, lenout, n, buffer, done

   returns:

      n        the scalar integer number of comment lines read from the comment
               area of the binary DAF referred to by 'handle'. 'n' will be
               less than or equal to 'bufsiz' on output ( bufsiz >= n).

      buffer   a string vector containing comment lines read from the DAF
               associated with 'handle'.

               On output, 'buffer' contains 'bufsiz' or less strings of
               comment text, with one comment line per string.

      done     a scalar logical indicating whether or not all of the comment
               lines from the comment area of the DAF have been read. This
               variable has value true after the last comment line has been
               read. It will have a false value otherwise.

               If no comments exist in the comment area, this variable
               returns as true.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

      ;;
      ;; Define the SPK file from which to extract the comment area.
      ;;
      SPK        = 'de421.bsp'
      SPICEFALSE = 0L

      ;;
      ;; Define the size of the comment area to read from the SPK.
      ;; 15 lines, each with length 80 characters.
      ;;
      BUFSIZE    = 15L
      LINLEN     = 80L

      ;;
      ;; Open the 'SPK' for reading, return the corresponding
      ;; file handle to 'handle'.
      ;;
      cspice_dafopr, SPK, handle

      done = SPICEFALSE

      cspice_dafec, handle, BUFSIZE, LINLEN, n, buf, done
      for i=0,n-1 do print, buf[i]

      if ( done ) then begin
         print, 'All comments read from file.'
      endif else begin
         print, 'Not all comments read from file.'
      endelse

      ;;
      ;; SAFELY close the file.
      ;;
      cspice_dafcls, handle

   IDL outputs:

      ; de421.bsp LOG FILE
      ;
      ; Created 2008-02-12/11:33:34.00.
      ;
      ; BEGIN NIOSPK COMMANDS

      LEAPSECONDS_FILE    = naif0007.tls
      SPK_FILE            = de421.bsp
        SPK_LOG_FILE      = de421_spk_conversion.log
        NOTE              = NIOSPK 6.1.0 Conversion
        SOURCE_NIO_FILE   = de421.nio
          BEGIN_TIME      = CAL-ET 1899 JUL 29 00:00:00.000
          END_TIME        = CAL-ET 2053 OCT 09 00:00:00.000

      ; END NIOSPK COMMANDS

      Not all comments read from file.

   The program outputs BUFSIZ (15) lines from the 'SPK' comment area.
   Additional calls to cspice_dafec will read more comment lines
   from the SPK in slices of BUFSIZ.

   Reading all comment lines from 'SPK' requires a large value for BUFSIZ.
   In this case, a BUFSIZ value of 50 will read all comment lines from
   'SPK' in a single cspice_dafec.

Particulars


   A binary DAF contains 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 DAF 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 read the comments from the comment area of
   a binary DAF, 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 false. 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.

   This routine can be used to ``simultaneously'' extract comments
   from the comment areas of multiple binary DAFs.

Required Reading


   ICY.REQ
   DAF.REQ

Version


   -Icy Version 1.0.1, 11-NOV-2013, EDW (JPL)

      Corrected typo in description of 'buffer' array. The array will have size
      'bufsiz' or less, not 'n'. 'n' returns the number of string elements in
      'buffer'.

      Changed Example code to eliminate a logic error and properly demonstrate
      use of 'done'.

      Edits to Examples text. Added Particulars section text

   -Icy Version 1.0.0, 03-FEB-2008, EDW (JPL)

Index_Entries


    extract comments from a DAF




Wed Apr  5 17:57:59 2017