void dafec_c ( SpiceInt handle,
SpiceInt bufsiz,
SpiceInt lenout,
SpiceInt * n,
void * buffer,
SpiceBoolean * done )
Extract comments from the comment area of a binary DAF.
DAF
FILES
UTILITY
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of binary DAF opened with read access.
bufsiz I Maximum size, in lines, of buffer.
lenout I Length of strings in output buffer.
n O Number of extracted comment lines.
buffer O Buffer where extracted comment lines are placed.
done O Indicates whether all comments have been extracted.
handle is the file handle of a binary DAF which has been opened with
read access.
bufsiz is the maximum number of comments that may be placed into
buffer. This would typically be the declared array size for
the Fortran character string array passed into this
routine.
lenout is the allowed length of each string element of the output
buffer. This length must large enough to hold the longest
output string plus the null terminator. 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.
n is the number of comment lines extracted from the comment area
of the binary DAF associated with `handle'. `n' will be
less than or equal to `bufsiz' on output.
buffer is an array containing comment lines read from the DAF
associated with `handle'. `buffer' should be declared
SpiceChar buffer[bufsiz][lenout];
On output, the first `n' strings of `buffer' will contain
comment text, with one comment line per string.
done is a logical flag indicating whether or not all of the
comment lines from the comment area of the DAF 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.
None.
1) If the size of the output line buffer is is not positive,
the error SPICE(INVALIDARGUMENT) will be signaled.
3) If a comment line in a DAF is longer than the length
of a character string array element of BUFFER, the error
SPICE(COMMENTTOOLONG) will be signaled.
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) will be signaled.
4) If the number of comment characters scanned exceeds the
number of comment characters computed, the error
SPICE(BADCOMMENTAREA) will be signaled.
5) If the binary DAF attached to HANDLE is not open for
reading,an error will be signaled by a routine called by
this routine.
6) If the output buffer pointer is null the error SPICE(NULLPOINTER)
will be signaled.
7) If the output buffer string length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
See argument `handle' in $ Detailed_Input.
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 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 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 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.
This routine can be used to ``simultaneously'' extract comments
from the comment areas of multiple binary DAFs. See Example
2 in the $ Examples section.
1) The following example will extract the entire comment area of a
binary DAF, displaying the comments on the terminal screen.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
#define FILSIZ 256
#define LINLEN 1001
#define BUFFSZ 25
SpiceBoolean done = SPICEFALSE;
SpiceChar daf [FILSIZ];
SpiceChar buffer [BUFFSZ][LINLEN];
SpiceInt handle;
SpiceInt i;
SpiceInt n;
prompt_c ( "Enter name of DAF > ", FILSIZ, daf );
dafopr_c ( daf, &handle );
while ( !done )
{
dafec_c ( handle, BUFFSZ, LINLEN, &n, buffer, &done );
for ( i = 0; i < n; i++ )
{
printf ( "%s\n", buffer[i] );
}
}
return ( 0 );
}
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 might 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.
None.
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-CSPICE Version 1.0.0, 16-NOV-2006 (NJB) (KRG)
extract comments from a DAF
Link to routine dafec_c source file dafec_c.c
|