Table of contents
CSPICE_DASEC extracts comments from the comment area of a binary
DAS file.
Given:
handle the file handle of a binary DAS file which has been opened with
read access.
help, handle
LONG = Scalar
This handle refers to the DAS file from which to read the
comment section.
bufsiz a scalar integer defining the maximum number of comments that
may be placed into `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_dasec, handle, bufsiz, buffln, n, buffer, done
returns:
n the scalar integer number of comment lines read from the comment
area of the binary DAS 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 which have been
extracted from the comment area of the binary DAS file attached
to handle.
help, buffer
STRING = Array[N]
On output, `buffer' contains `bufsiz' or less strings of comment
text, with one comment line per string ( bufsiz >= n).
done a scalar logical indicating whether or not all of the comment
lines from the comment area of the DAS file have been read.
help, done
BOOLEAN = Scalar
This variable has the value true after the last comment line
has been read. It will have the value false 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 DAS file attached to `handle', displaying the comments on
the terminal screen.
Use the DSK kernel below as input DAS file for the example.
phobos512.bds
Example code begins here.
PRO dasec_ex1
;;
;; Local constants
;;
SPICEFALSE = 0L
BUFSIZE = 40L
LINLEN = 115L
filename = 'phobos512.bds'
;;
;; Open for reading the DAS, return the corresponding
;; file handle to 'handle'.
;;
cspice_dasopr, filename, handle
done = SPICEFALSE
cspice_dasec, 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_dascls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
************************************************************************
MKDSK RUN DATE/TIME: 2010-06-30T16:52:12
MKDSK SETUP FILE: phobos512.cmd
MKDSK INPUT FILE: phobos_q512.txt
MKDSK OUTPUT FILE: phobos512.bds
OUTPUT FILE STATUS: NEW FILE
************************************************************************
\begindata
INPUT_SHAPE_FILE = 'phobos_q512.txt'
OUTPUT_DSK_FILE = 'phobos512.bds'
COMMENT_FILE = ' '
LEAPSECONDS_FILE = 'naif0009.tls'
SURFACE_NAME = 'phobos'
CENTER_NAME = 'phobos'
REF_FRAME_NAME = 'IAU_PHOBOS'
START_TIME = '1950-JAN-1/00:00:00'
STOP_TIME = '2050-JAN-1/00:00:00'
DATA_CLASS = 1
INPUT_DATA_UNITS = ( 'ANGLES = DEGREES'
'DISTANCES = KILOMETERS' )
COORDINATE_SYSTEM = 'LATITUDINAL'
MINIMUM_LATITUDE = -90
MAXIMUM_LATITUDE = 90
MINIMUM_LONGITUDE = -180
MAXIMUM_LONGITUDE = 180
DATA_TYPE = 2
PLATE_TYPE = 2
FINE_VOXEL_SCALE = 4.0
COARSE_VOXEL_SCALE = 5
\begintext
************************************************************************
All comments read from file.
Note, that the program outputs BUFSIZE or less lines from the
DAS comment area.
Reading all comment lines from a DAS may require a large value
for BUFSIZE. In this case, a BUFSIZ value of 50 will read all
comment lines from a DAS in a single cspice_dasec call. Otherwise,
additional calls to cspice_dasec will read more comment lines
from the DAS in slices of BUFSIZE.
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
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.
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 DAS file 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 there is a mismatch between the number of comment
characters found and the number of comment characters
expected, the error SPICE(BADDASCOMMENTAREA) is signaled by a
routine in the call tree of this routine.
4) If the binary DAS file attached to `handle' is not open for
reading, an error is signaled by a routine in the call tree of
this routine.
5) If any of the input arguments, `handle', `bufsiz' or `buffln',
is undefined, an error is signaled by the IDL error handling
system.
6) 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.
7) 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
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.
ICY.REQ
DAS.REQ
None.
J. Diaz del Rio (ODC Space)
M. Liukis (JPL)
E.D. Wright (JPL)
-Icy Version 1.1.0, 10-AUG-2021 (JDR)
Changed the input argument name "lenout" to "buffln" for
consistency with other routines.
Edited the -Examples section to comply with NAIF standard. Added
example's problem statement. Updated code example to hardcode
the input DAS file.
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.0, 05-JAN-2017 (ML) (EDW)
extract comments from a DAS file
|