1 /* 2 3 -Procedure daffpa_c ( DAF, find previous array ) 4 5 -Abstract 6 7 Find the previous (backward) array in the current DAF. 8 9 -Disclaimer 10 11 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 12 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 13 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 14 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 15 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 16 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 17 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 18 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 19 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 20 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 21 22 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 23 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 24 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 25 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 26 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 27 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 28 29 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 30 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 31 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 32 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 33 34 -Required_Reading 35 36 DAF 37 38 -Keywords 39 40 FILES 41 42 */ 43 44 #include "SpiceUsr.h" 45 #include "SpiceZfc.h" 46 #include "SpiceZst.h" 47 daffpa_c(SpiceBoolean * found)48 void daffpa_c ( SpiceBoolean * found ) 49 50 /* 51 52 -Brief_I/O 53 54 Variable I/O Description 55 -------- --- -------------------------------------------------- 56 found O SPICETRUE if an array was found. 57 58 -Detailed_Input 59 60 None. 61 62 -Detailed_Output 63 64 found is SPICETRUE if an array was found, and is SPICEFALSE 65 if, when this routine is called, the current array is 66 the head of the array list. (Recall that the arrays in 67 a DAF may be viewed as a doubly linked list, with the 68 head being the first array in the file.) 69 70 -Parameters 71 72 None. 73 74 -Exceptions 75 76 1) If this routine is called before a search is begun, the 77 error SPICE(DAFNOSEARCH) is signaled. 78 79 2) If the DAF to be searched has actually been closed, the error 80 will be diagnosed by routines called by this routine. 81 82 3) If the beginning of the array list has already been reached 83 when this routine is called, this routine will not change the 84 current array. found will be SPICEFALSE on output. 85 86 -Files 87 88 None. 89 90 -Particulars 91 92 The DAF search routines are: 93 94 95 dafbfs_c Begin forward search. 96 daffna Find next array. 97 98 dafbbs_c Begin backward search. 99 daffpa_c Find previous array. 100 101 dafgs_c Get summary. 102 dafgn_c Get name. 103 dafgh_c Get handle. 104 105 dafcs_c Continue search. 106 107 The main function of these entry points is to allow the 108 contents of any DAF to be examined on an array-by-array 109 basis. 110 111 Conceptually, the arrays in a DAF form a doubly linked list, 112 which can be searched in either of two directions: forward or 113 backward. It is possible to search multiple DAFs simultaneously. 114 115 dafbfs_c (begin forward search) and daffna are used to search the 116 arrays in a DAF in forward order. In applications that search a 117 single DAF at a time, the normal usage is 118 119 dafbfs_c ( handle ); 120 daffna_c ( &found ); 121 122 while ( found ) 123 { 124 dafgs_c ( sum ); 125 dafgn_c ( name ); 126 . 127 . 128 129 daffna_c ( &found ); 130 } 131 132 133 dafbbs_c (begin backward search) and daffpa_c are used to search the 134 arrays in a DAF in backward order. In applications that search 135 a single DAF at a time, the normal usage is 136 137 dafbbs_c ( handle ); 138 daffpa_c ( &found ); 139 140 while ( found ) 141 { 142 dafgs_c ( sum ); 143 dafgn_c ( name ); 144 . 145 . 146 147 daffpa_c ( &found ); 148 } 149 150 151 In applications that conduct multiple searches simultaneously, 152 the above usage must be modified to specify the handle of the 153 file to operate on, in any case where the file may not be the 154 last one specified by dafbfs_c or dafbbs_c. The routine dafcs_c 155 (DAF, continue search) is used for this purpose. Below, we 156 give an example of an interleaved search of two files specified 157 by the handles handl1 and handl2. The directions of searches 158 in different DAFs are independent; here we conduct a forward 159 search on one file and a backward search on the other. 160 Throughout, we use dafcs to specify which file to operate on, 161 before calling daffna_c, daffpa_c, dafgs_c, or dafgn_c. 162 163 164 dafbfs_c ( handl1 ); 165 dafbbs_c ( handl2 ); 166 167 dafcs_c ( handl1 ); 168 daffna_c ( &found1 ); 169 170 dafcs_c ( handl2 ); 171 daffpa_c ( &found2 ); 172 173 while ( found1 || found2 ) 174 { 175 if ( found1 ) 176 { 177 dafcs_c ( handl1 ); 178 dafgs_c ( sum ); 179 dafgn_c ( name ); 180 . 181 . 182 dafcs_c ( &handl1 ); 183 daffna_c ( &found1 ); 184 } 185 186 if ( found2 ) 187 { 188 dafcs_c ( handl2 ); 189 dafgs_c ( sum ); 190 dafgn_c ( name ); 191 . 192 . 193 dafcs_c ( handl2 ); 194 daffpa_c ( &found2 ); 195 } 196 } 197 198 199 At any time, the latest array found (whether by daffna_c or daffpa_c) 200 is regarded as the "current" array for the file in which the 201 array was found. The last DAF in which a search was started, 202 executed, or continued by any of dafbfs_c, dafbbs_c, daffna_c, 203 daffpa_c or dafcs_c is regarded as the "current" DAF. The summary 204 and name for the current array in the current DAF can be obtained 205 separately, as shown above, by calls to DAFGS (get summary) and 206 dafgn_c (get name). The handle of the current DAF can also be 207 obtained by calling dafgh_c (get handle). 208 209 Once a search has been begun, it may be continued in either 210 direction. That is, daffpa_c may be used to back up during a 211 forward search, and daffna_c may be used to advance during a 212 backward search. 213 214 -Examples 215 216 Example (1): 217 218 See Particulars. 219 220 Example (2): 221 222 Use a simple routine to output the double precision and integer 223 values stored in an SPK's segments descriptors. This function 224 opens a DAF for read, performs a backwards search for the DAF 225 arrays, prints segments description for each array found, then 226 closes the DAF. 227 228 #include <stdio.h> 229 #include "SpiceUsr.h" 230 231 int main() 232 { 233 234 /. 235 Local constants 236 ./ 237 238 /. 239 Define the summary parameters appropriate 240 for an SPK file. 241 ./ 242 243 #define ND 2 244 #define NI 6 245 #define MAXSUM 125 246 247 SpiceInt ic [ NI ]; 248 SpiceInt handle; 249 250 SpiceDouble dc [ ND ]; 251 SpiceDouble sum [ MAXSUM ]; 252 253 SpiceChar * kernel = "/kernels/gen/spk/de421.bsp"; 254 255 SpiceBoolean found; 256 257 258 /. 259 Open a DAF for read. Return a handle referring to the file. 260 ./ 261 dafopr_c ( kernel, &handle ); 262 263 /. 264 Begin a backward search on the file. 265 ./ 266 dafbbs_c ( handle ); 267 268 /. 269 Search until a DAF array is found. 270 ./ 271 daffpa_c ( &found ); 272 273 /. 274 Loop while the search finds subsequent DAF arrays. 275 ./ 276 while ( found ) 277 { 278 279 dafgs_c ( sum ); 280 dafus_c ( sum, ND, NI, dc, ic ); 281 282 printf( " Doubles: %f %f \n", dc[0], dc[1] ); 283 printf( "Integers: %d %d %d %d %d %d\n\n", 284 (int)ic[0], (int)ic[1], (int)ic[2], 285 (int)ic[3], (int)ic[4], (int)ic[5] ); 286 287 /. 288 Check for another segment. 289 ./ 290 daffpa_c ( &found ); 291 } 292 293 /. 294 Safely close the DAF. 295 ./ 296 dafcls_c ( handle ); 297 298 return ( 0 ); 299 } 300 301 The program outouts: 302 303 Doubles: -3169195200.000000 1696852800.000000 304 Integers: 499 4 1 2 2098633 2098644 305 306 Doubles: -3169195200.000000 1696852800.000000 307 Integers: 299 2 1 2 2098621 2098632 308 309 Doubles: -3169195200.000000 1696852800.000000 310 Integers: 199 1 1 2 2098609 2098620 311 312 Doubles: -3169195200.000000 1696852800.000000 313 Integers: 399 3 1 2 1521325 2098608 314 315 Doubles: -3169195200.000000 1696852800.000000 316 Integers: 301 3 1 2 944041 1521324 317 318 Doubles: -3169195200.000000 1696852800.000000 319 Integers: 10 0 1 2 820837 944040 320 321 Doubles: -3169195200.000000 1696852800.000000 322 Integers: 9 0 1 2 785633 820836 323 324 Doubles: -3169195200.000000 1696852800.000000 325 Integers: 8 0 1 2 750429 785632 326 327 Doubles: -3169195200.000000 1696852800.000000 328 Integers: 7 0 1 2 715225 750428 329 330 Doubles: -3169195200.000000 1696852800.000000 331 Integers: 6 0 1 2 674741 715224 332 333 Doubles: -3169195200.000000 1696852800.000000 334 Integers: 5 0 1 2 628977 674740 335 336 Doubles: -3169195200.000000 1696852800.000000 337 Integers: 4 0 1 2 567373 628976 338 339 Doubles: -3169195200.000000 1696852800.000000 340 Integers: 3 0 1 2 423049 567372 341 342 Doubles: -3169195200.000000 1696852800.000000 343 Integers: 2 0 1 2 310405 423048 344 345 Doubles: -3169195200.000000 1696852800.000000 346 Integers: 1 0 1 2 641 310404 347 348 Note, the final entries in the integer arrays record the segment 349 start/end indexes. The output indicates the search proceeded 350 from the end of the file (high value index) towards the beginning 351 (low value index). 352 353 -Restrictions 354 355 None. 356 357 -Literature_References 358 359 None. 360 361 -Author_and_Institution 362 363 N.J. Bachman (JPL) 364 W.L. Taber (JPL) 365 I.M. Underwood (JPL) 366 367 -Version 368 369 -CSPICE Version 1.0.2, 28-JUN-2016 (EDW) 370 371 Edit to Example code, SpiceInts output as ints using 372 explicit casting. 373 374 -CSPICE Version 1.0.1, 10-OCT-2012 (EDW) 375 376 Added a functional code example to the Examples section. 377 378 Removed the obsolete Reference citation to "NAIF 379 Document 167.0." 380 381 -CSPICE Version 1.0.0, 31-JUL-1999 (NJB) (WLT) (IMU) 382 383 -Index_Entries 384 385 find previous daf array 386 387 -& 388 */ 389 390 { /* Begin daffpa_c */ 391 392 /* 393 Local variables 394 */ 395 logical fnd; 396 397 398 /* 399 Participate in error tracing. 400 */ 401 chkin_c ( "daffpa_c" ); 402 403 404 daffpa_ ( ( logical * ) &fnd ); 405 406 *found = fnd; 407 408 409 chkout_c ( "daffpa_c" ); 410 411 } /* End daffpa_c */ 412