Table of contents
CSPICE_DASADC adds character data to a DAS file.
Given:
handle a file handle of a DAS file opened for writing.
help, handle
LONG = Scalar
n the total number of characters to add to the specified DAS
file.
help, n
LONG = Scalar
bpos,
epos the begin and end character positions that define the
substrings in each of the elements of the input array.
help, bpos
LONG = Scalar
help, epos
LONG = Scalar
This routine writes the first `n' characters from the
specified set of substrings to the specified DAS file.
data a two-dimensional or one-dimensional array of bytes,
representing characters, some portion of whose contents are to
be added to the specified DAS file.
help, data
BYTE = Array[N,M] or BYTE = Array[N]
Note that, due to its internal implementation, IDL represents a
two-dimensional array where M=1 (single row) as a
one-dimensional array. Therefore, this routine makes no
difference between two- and one-dimensional arrays.
Specifically, the first `n' characters of the substrings
data[bpos:epos, i], i = 0, ...
are appended to the character data in the file.
`data' must be declared at least as
data = bytarr( epos, r )
with the dimension `r' being at least
r = LONG( ( n + sublen - 1 ) / sublen )
and `sublen', the length of each of the substrings in
the array to be added to the DAS file, being
sublen = epos - bpos + 1
The order of characters in the input substrings is
considered to increase from left to right within each
element of `data', and to increase with the indices of the
elements of `data'.
the call:
cspice_dasadc, handle, n, bpos, epos, data
returns:
None.
See -Particulars for a description of the effect of this routine.
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 demonstrates the capabilities of the
DAS character data routines. The reader should notice that
in these interfaces, the character data are treated not as
strings (or arrays of strings) but as a stream of single
characters: DAS character data are not limited to
human-readable text. For example, one can store images or
DEM data as DAS character data.
The example shows how to add a variable amount of character
data to a new DAS file, how to update some of the character
logical addresses within that file, and how to read that
data out to a different array.
Example code begins here.
PRO dasadc_ex1
;;
;; Local parameters.
;;
FNAME = 'dasadc_ex1.das'
TYPE = 'TEST'
cdatou = BYTE( [ '..............................', $
'..............................', $
'..............................', $
'..............................', $
'..............................', $
'..............................', $
'..............................', $
'..............................', $
' 1 2 3', $
'123456789012345678901234567890' ] )
;;
;; Open a new DAS file. Use the file name as the internal
;; file name, and reserve no records for comments.
;;
cspice_dasonw, FNAME, TYPE, FNAME, 0L, handle
;;
;; Set the input data. Note that these data will be
;; considered as a binary data stream: DAS character data
;; are not limited to human-readable text. For example,
;; one can store images or DEM data as DAS character data.
;;
cdatin = BYTE( [ '--F-345678901234567890', $
'--S-345678901234567890', $
'--T-IRDxxxxxxxxxxxxxxx' ] )
;;
;; Add the last 20 characters of the first two elements
;; of `cdatin', and the 3rd character from the third one.
;;
cspice_dasadc, handle, 41, 2, 21, cdatin
;;
;; Update the 10th, 20th and 30th character in the DAS
;; file with a vertical bar.
;;
for i=1L, 3L do begin
cspice_dasudc, handle, i*10L, i*10L, 0, 0, BYTE( '|' )
endfor
;;
;; Close the file.
;;
cspice_dascls, handle
;;
;; Now verify the addition of data by opening the
;; file for read access and retrieving the data.
;;
cspice_dasopr, FNAME, handle
;;
;; Read the 41 characters that we stored on the DAS
;; file. Update the data on the `cdatou' array, placing
;; 6 characters on each element, starting from the
;; 10th position.
;;
cspice_dasrdc, handle, 1L, 41L, 9L, 14L, cdatou
;;
;; Dump the data to the screen. Note that the last
;; three lines should remain unmodified, and that
;; only 5 characters will be written on the 7th line.
;;
print
print, 'Data from "', FNAME, '":'
print
for i=0L, 9L do begin
print, STRING(cdatou[*,i])
endfor
;;
;; Close the file.
;;
cspice_dascls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Data from "dasadc_ex1.das":
.........F-3456...............
.........789|12...............
.........345678...............
.........9|S-34...............
.........56789|...............
.........123456...............
.........7890T................
..............................
1 2 3
123456789012345678901234567890
Note that after run completion, a new DAS file exists in the
output directory.
DAS is a low-level format meant to store and transmit data. As
such, character data in DAS files are not interpreted by Icy
DAS input or output routines. There are no limits on which
character values may be placed in the virtual character array of a
DAS file.
This routine adds character data to a DAS file by "appending" them
after any character data already in the file. The sense in which
the data are "appended" is that the data will occupy a range of
logical addresses for character data that immediately follow the
last logical address of a character that is occupied at the time
this routine is called. The diagram below illustrates this
addition:
+-------------------------+
| (already in use) | Character logical address 1
+-------------------------+
.
.
.
+-------------------------+ last character logical address
| (already in use) | in use before call to cspice_dasadc
+-------------------------+
| data[0][bpos] | First added character
+-------------------------+
| data[0][bpos+1] |
+-------------------------+
.
.
.
+-------------------------+
| data[0][epos] |
+-------------------------+
| data[1][bpos] |
+-------------------------+
.
.
.
+-------------------------+
| data[r-1][c] | n'th added character---here `r' is
+-------------------------+
int( (n+l-1)/l )
where l = epos - bpos + 1, and
`c' is
bpos + ( n - (r-1)*l ) - 1
The logical organization of the characters in the DAS file is
independent of the order of addition to the file or physical
location of any data of integer or double precision type.
The actual physical write operations that add the input array
`data' to the indicated DAS file may not take place before this
routine returns, since the DAS system buffers data that are
written as well as data that are read. In any case, the data
will be flushed to the file at the time the file is closed, if
not earlier. A physical write of all buffered records can be
forced by calling the ICY routine cspice_daswbr (DAS, write
buffered records).
In order to update character logical addresses that already
contain data, the Icy routine cspice_dasudc (DAS, update data,
character) should be used.
1) If the input file handle is invalid, an error is signaled
by a routine in the call tree of this routine.
2) If `epos' or `bpos' are outside of the range
[ 0, n_elements(data[*,0]) - 1 ]
or if epos < bpos, the error SPICE(BADSUBSTRINGBOUNDS) is
signaled by a routine in the call tree of this routine.
3) If the input count `n' is less than 1, no data will be
added to the specified DAS file.
4) If an I/O error occurs during the data addition attempted
by this routine, the error is signaled by a routine in the
call tree of this routine.
5) If `n' is greater than the number of characters in the
specified set of input substrings, the results of calling
this routine are unpredictable. This routine cannot
detect this error.
6) If any of the input arguments, `handle', `n', `bpos', `epos'
or `data', is undefined, an error is signaled by the IDL error
handling system.
7) If any of the input arguments, `handle', `n', `bpos', `epos'
or `data', 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 the data provided in `data' is insufficient to add `n' characters
(of type byte) to the DAS file, an error is signaled by the Icy
interface.
See the description of the argument `handle' in -I/O.
None.
DAS.REQ
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
-Icy Version 1.0.0, 19-JUL-2021 (JDR)
add character data to a DAS file
|