Table of contents
CSPICE_DAFBFS initiates a forward search for arrays in a DAF
file.
Given:
handle the scalar integer file handle referring to a DAF.
help, handle
LONG = Scalar
the call:
cspice_dafbfs, handle
starts a forwards search, i.e. start of file to end of file,
on a DAF.
returns:
None.
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) Create a simple program to output the double precision and integer
values stored in an SPK's segments' descriptors. This program opens
a DAF for read, performs a forward search for the DAF arrays,
prints the segment descriptor for each array found, then closes
the DAF.
Use the SPK kernel below as input DAF file for the program.
de421.bsp
Example code begins here.
PRO dafbfs_ex1
;;
;; Local constants
;;
kernel = 'de421.bsp'
;;
;; Open a DAF file for read. Return a 'handle' referring
;; to the file.
;;
cspice_dafopr, kernel, handle
;;
;; Define the summary parameters appropriate
;; for an SPK file.
;;
ND = 2L
NI = 6L
;;
;; Begin a forward search on the file.
;;
cspice_dafbfs, handle
;;
;; Search until a DAF array is found.
;;
cspice_daffna, found
;;
;; Loop while the search finds subsequent DAF arrays.
;;
while found do begin
cspice_dafgs, ND, NI, dc, ic
print, 'Doubles: ', dc
print, FORMAT='(A,6I8)', 'Integers: ', ic
print, ' '
;;
;; Check for another segment.
;;
cspice_daffna, found
endwhile
;;
;; Safely close the DAF file.
;;
cspice_dafcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 1 0 1 2 641 310404
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 2 0 1 2 310405 423048
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 3 0 1 2 423049 567372
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 4 0 1 2 567373 628976
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 5 0 1 2 628977 674740
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 6 0 1 2 674741 715224
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 7 0 1 2 715225 750428
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 8 0 1 2 750429 785632
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 9 0 1 2 785633 820836
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 10 0 1 2 820837 944040
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 301 3 1 2 944041 1521324
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 399 3 1 2 1521325 2098608
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 199 1 1 2 2098609 2098620
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 299 2 1 2 2098621 2098632
Doubles: -3.1691952e+09 1.6968528e+09
Integers: 499 4 1 2 2098633 2098644
Note, the specific contents of `ic' and `dc' depend on the
type of DAF.
Note, the final entries in the integer array contain the segment
start/end indexes. The output indicates the search proceeded
from the start of the file (low value index) towards the end
(high value index).
The DAF search routines are:
cspice_dafbfs Begin forward search.
cspice_daffna Find next array.
cspice_dafbbs Begin backward search.
cspice_daffpa Find previous array.
cspice_dafgs Get summary.
cspice_dafgn Get name.
cspice_dafcs Continue search.
The main procedure of these entry points is to allow the
contents of any DAF to be examined on an array-by-array
basis.
Conceptually, the arrays in a DAF form a doubly linked list,
which can be searched in either of two directions: forward or
backward. It is possible to search multiple DAFs simultaneously.
cspice_dafbfs (begin forward search) and daffna are used to search the
arrays in a DAF in forward order. In applications that search a
single DAF at a time, the normal usage is
cspice_dafbfs, handle
cspice_daffna, found
while found do begin
cspice_dafgs, ND, NI, dc, ic
cspice_dafps, dc, ic, sum
cspice_dafgn, name
.
.
cspice_daffna, found
endwhile
cspice_dafbbs (begin backward search) and cspice_daffpa are used to
search the arrays in a DAF in backward order. In applications that search
a single DAF at a time, the normal usage is
cspice_dafbbs, handle
cspice_daffpa, found
while found do begin
cspice_dafgs, ND, NI, dc, ic
cspice_dafps, dc, ic, sum
cspice_dafgn, name
.
.
cspice_daffpa, found
endwhile
In applications that conduct multiple searches simultaneously, the above
usage must be modified to specify the handle of the file to operate on,
in any case where the file may not be the last one specified by
cspice_dafbfs or cspice_dafbbs. The routine cspice_dafcs (DAF, continue
search) is used for this purpose. Below, we give an example of an
interleaved search of two files specified by the handles handl1 and
handl2. The directions of searches in different DAFs are independent;
here we conduct a forward search on one file and a backward search on the
other. Throughout, we use dafcs to specify which file to operate on,
before calling cspice_daffna, cspice_daffpa, cspice_dafgs, or
cspice_dafgn.
cspice_dafbfs, handl1
cspice_dafbbs, handl2
cspice_dafcs, handl1
cspice_daffna, found1
cspice_dafcs, handl2
cspice_daffpa, found2
while ( found1 || found2 ) do begin
if ( found1 ) then begin
cspice_dafcs, handl1
cspice_dafgs, ND, NI, dc, ic
cspice_dafps, dc, ic, sum
cspice_dafgn, name
.
.
cspice_dafcs, handl1
cspice_daffna, found1
endif
if ( found2 ) then begin
cspice_dafcs, handl2
cspice_dafgs, ND, NI, dc, ic
cspice_dafps, dc, ic, sum
cspice_dafgn, name
.
.
cspice_dafcs, handl2
cspice_daffpa, found2
endif
endwhile
At any time, the latest array found (whether by cspice_daffna or
cspice_daffpa) is regarded as the 'current' array for the file in which
the array was found. The last DAF in which a search was started,
executed, or continued by any of cspice_dafbfs, cspice_dafbbs,
cspice_daffna, cspice_daffpa or cspice_dafcs is regarded as the 'current'
DAF. The summary and name for the current array in the current DAF can be
obtained separately, as shown above, by calls to cspice_dafgs (get
summary) and cspice_dafgn (get name).
Once a search has been begun, it may be continued in either
direction. That is, cspice_daffpa may be used to back up during a
forward search, and cspice_daffna may be used to advance during a
backward search.
1) If the input handle is invalid, an error is signaled by a
routine in the call tree of this routine.
2) If the summary record of the first record in the DAF file
cannot be read, the error SPICE(RECORDNOTFOUND) is signaled by
a routine in the call tree of this routine.
3) If the input argument `handle' is undefined, an error is
signaled by the IDL error handling system.
4) If the input argument `handle' 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'.
None.
ICY.REQ
DAF.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.3, 25-AUG-2021 (JDR)
Edited the -Examples section to comply with NAIF standard.
Modified code example to hardcode the input DAF file.
Added -Parameters, -Particulars, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added argument's type and size information in the -I/O section.
-Icy Version 1.0.2, 06-NOV-2013 (EDW)
Minor edits and clean up to header text.
-Icy Version 1.0.1, 08-AUG-2008 (EDW)
Minor edits to header text.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
begin DAF forward search
|