Table of contents
CSPICE_DAFAC adds comments from a buffer of character strings to the
comment area of a binary DAF, appending them to any comments which
are already present in the file's comment area.
Given:
handle the scalar integer referring to a DAF opened with write access.
help, handle
LONG = Scalar
This handle refers to the DAF to which add the contents of
`buffer' as comments.
buflen the scalar integer defining the maximum length of the string
buffer rows.
help, buflen
LONG = Scalar
buffer a string vector containing comments which to write into the
comment area of the binary DAF attached to 'handle'.
help, buffer
STRING = Array[N]
Each element of `buffer' should contain one comment line.
the call:
cspice_dafac, handle, buflen, buffer
adds the contents of `buffer' to the DAF referred to by `handle'.
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) This example demonstrates how to append new comments to the
comment area of a DAF file.
Use the SPK kernel below as input DAF file for the program.
earthstns_itrf93_201023.bsp
Example code begins here.
PRO dafac_ex1
;;
;; Local parameters
;;
KERNEL = 'earthstns_itrf93_201023.bsp'
BUFFSZ = 25
CMTSIZ = 7
LINLEN = 1000
SPICEFALSE = 0
;;
;; Set the new comments to be added to the DAF file.
;;
newcmt = [ $
'================== NEW COMMENTS ==================', $
'', $
' New comments can be appended to the end of the', $
' comment area of a DAF file, with a single', $
' operation.', $
'', $
'================ END NEW COMMENTS ================' ]
;;
;; Open a DAF for write. Return a `handle' referring to the
;; file.
;;
cspice_dafopw, KERNEL, handle
;;
;; Print the end of comment area from the DAF file.
;; (Maximum 15 lines.)
;;
done = SPICEFALSE
while ( not done ) do begin
cspice_dafec, handle, 15, LINLEN, n, buffer, done
if ( done ) then begin
print, 'End of comment area of input DAF file (max. 15' + $
' lines):'
print, '-------------------------------' + $
'-------------------------------'
for i=0, n - 1L do begin
print, buffer[i]
endfor
print, '-------------------------------' + $
'-------------------------------'
endif
endwhile
;;
;; Append the new comments to the DAF file.
;;
cspice_dafac, handle, LINLEN, newcmt
;;
;; Safely close the DAF.
;;
cspice_dafcls, handle
;;
;; Check if the comments have indeed appended.
;;
;; Open a DAF for read.
;;
cspice_dafopr, KERNEL, handle
done = SPICEFALSE
while ( not done ) do begin
cspice_dafec, handle, BUFFSZ, LINLEN, n, buffer, done
if ( done ) then begin
print, 'End of comment area of input DAF file (max. 25' + $
' lines):'
print, '-------------------------------' + $
'-------------------------------'
for i=0, n - 1L do begin
print, buffer[i]
endfor
print, '-------------------------------' + $
'-------------------------------'
endif
endwhile
;;
;; Safely close the DAF.
;;
cspice_dafcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
End of comment area of input DAF file (max. 15 lines):
--------------------------------------------------------------
DSS-65_DXYZ = ( -0.0100 0.0242 0.0156***
DSS-65_TOPO_EPOCH = @2020-OCT-23/00:00
DSS-65_UP = 'Z'
DSS-65_NORTH = 'X'
\begintext
--------------------------------------------------------------
End of comment area of input DAF file (max. 25 lines):
--------------------------------------------------------------
DSS-65_DXYZ = ( -0.0100 0.0242 0.0156***
DSS-65_TOPO_EPOCH = @2020-OCT-23/00:00
DSS-65_UP = 'Z'
DSS-65_NORTH = 'X'
\begintext
================== NEW COMMENTS ==================
New comments can be appended to the end of the
comment area of a DAF file, with a single
operation.
================ END NEW COMMENTS ================
--------------------------------------------------------------
Warning: incomplete output. 2 lines extended past the right
margin of the header and have been truncated. These lines are
marked by "***" at the end of each line.
A binary DAF contains a data area which is reserved for storing
annotations or descriptive textual information about 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
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 take a buffer of text lines and add (append) them
to the comment area of a binary DAF. If there are no comments in the
comment area of the file, then space will be allocated and the text
lines in `buffer' will be placed into the comment area. The text lines
may contain only printable ASCII characters (decimal values 32 -
126).
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
reasonable, however, so that they may be easily extracted. A good
maximum 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.
1) If the number of comments to be added is not positive, the
error SPICE(INVALIDARGUMENT) is signaled by a routine in the
call tree of this routine.
2) If a non printing ASCII character is encountered in the
comments, the error SPICE(ILLEGALCHARACTER) is signaled by a
routine in the call tree of this routine.
3) If the binary DAF file attached to `handle' is not open with
write access, an error is signaled by a routine in the call
tree of this routine.
4) 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.
5) If any of the input arguments, `handle', `buflen' or `buffer',
is undefined, an error is signaled by the IDL error handling
system.
6) If any of the input arguments, `handle', `buflen' or `buffer',
is not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
See argument `handle' in -I/O.
1) This routine uses constants that are specific to the ASCII
character sequence. The results of using this routine with
a different character sequence are unpredictable.
2) This routine is only used to extract 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.
ICY.REQ
DAF.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.0, 25-NOV-2021 (JDR)
Edited the -Examples section to comply with NAIF standard.
Added complete code example.
Changed input argument name "length" to "buflen" for consistency
with other routines.
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)
Edits to -Examples text. Added -Particulars section text.
-Icy Version 1.0.0, 22-FEB-2008 (EDW)
add comments to a binary DAF
append comments to a DAF comment area
|