Table of contents
CSPICE_DAFEC reads comment text from the comment area of a DAF.
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.
None.
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.
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.
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.
See argument `handle' in -I/O.
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.
ICY.REQ
DAF.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-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)
extract comments from a DAF
|