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

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


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

I/O


   Given:

      handle   the scalar integer file handle referring to a DAF file opened
               with read access.

               help, handle
                  LONG = Scalar

               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'.

               help, bufsiz
                  LONG = Scalar

      buffln   a scalar integer defining the allowed length of each string
               element of the output `buffer'.

               help, buffln
                  LONG = Scalar

               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 `buffln' normally should be set to a
               "generous" value that is unlikely to be exceeded.

   the call:

      cspice_dafec, handle, bufsiz, buffln, 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'.

               help, n
                  LONG = Scalar

               `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'.

               help, buffer
                  STRING = Array[N]

               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.

               help, done
                  BOOLEAN = Scalar

               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.

Parameters


   None.

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.

   1) The following example will extract the entire comment area of a
      binary DAF, displaying the comments on the terminal screen.


      Use the SPK kernel below as input DAF file for the example.

         earthstns_itrf93_201023.bsp


      Example code begins here.


      PRO dafec_ex1

         ;;
         ;; Define the SPK file from which to extract the comment area.
         ;;
         SPK        = 'earthstns_itrf93_201023.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]
         print, ''

         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

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


         SPK for DSN Station Locations
         =====================================================================

         Original file name:                   earthstns_itrf93_201023.bsp
         Creation date:                        2020 October 28 12:30
         Created by:                           Nat Bachman  (NAIF/JPL)


         Introduction
         =====================================================================

         This file provides geocentric states---locations and velocities---f***
         set of DSN stations cited in the list below under "Position Data." ***
         position vectors point from the earth's barycenter to the stations.***

      Not all comments read from file.


      Warning: incomplete output. 3 lines extended past the right
      margin of the header and have been truncated. These lines are
      marked by "***" at the end of each line.


      Note that 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 139 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.

Exceptions


   1)  If the size of the output line buffer is is not positive, the
       error SPICE(INVALIDARGUMENT) is signaled by a routine in the
       call tree of this routine.

   2)  If a comment line in a DAF is longer than the length of a
       character string array element of `buffer', the error
       SPICE(COMMENTTOOLONG) is signaled by a routine in the call
       tree of this routine.

   3)  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) is signaled by a routine in the
       call tree of this routine.

   4)  If the number of comment characters scanned exceeds the number
       of comment characters computed, the error
       SPICE(BADCOMMENTAREA) is signaled by a routine in the call
       tree of this routine.

   5)  If the binary DAF attached to `handle' is not open for reading,
       an error is signaled by a routine in the call tree of this
       routine.

   6)  If any of the input arguments, `handle', `bufsiz' or `buffln',
       is undefined, an error is signaled by the IDL error handling
       system.

   7)  If any of the input arguments, `handle', `bufsiz' or `buffln',
       is not of the expected type, or it does not have the expected
       dimensions and size, an error is signaled by the Icy
       interface.

   8)  If any of the output arguments, `n', `buffer' or `done', is
       not a named variable, an error is signaled by the Icy
       interface.

Files


   See argument `handle' in -I/O.

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
       DAF. 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 1000 characters, as
       this can easily accommodate ``screen width'' lines as well as
       long lines which may contain some other form of information.

   3)  This routine is only used to read 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.

   4)  This routine is intended to be used on DAF files whose comment
       area does not change while this routine is called to extract
       comments, between the start and end of the extraction process.
       If the comment area does change (gets updated, reduced,
       extended, or deleted) between calls to this routine on the
       same DAF file, the routine's outputs are undefined and
       subsequent calls to it are likely to trigger an exception.

Required_Reading


   ICY.REQ
   DAF.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.1.0, 25-NOV-2021 (JDR)

       Changed the input argument name "lenout" to "buffln" for
       consistency with other routines.

       Edited the header to comply with NAIF standard. Added
       example's problem statement and modified input kernel.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

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

       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)

Index_Entries


    extract comments from a DAF



Fri Dec 31 18:43:02 2021