1 /* 2 3 -Procedure dafcs_c ( DAF, continue search ) 4 5 -Abstract 6 7 Select a DAF that already has a search in progress as the 8 one to continue searching. 9 10 -Disclaimer 11 12 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 13 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 14 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 15 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 16 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 17 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 18 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 19 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 20 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 21 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 22 23 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 24 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 25 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 26 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 27 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 28 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 29 30 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 31 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 32 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 33 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 34 35 -Required_Reading 36 37 DAF 38 39 -Keywords 40 41 FILES 42 43 */ 44 45 #include "SpiceUsr.h" 46 #include "SpiceZfc.h" 47 48 dafcs_c(SpiceInt handle)49 void dafcs_c ( SpiceInt handle ) 50 51 /* 52 53 -Brief_I/O 54 55 Variable I/O Description 56 -------- --- -------------------------------------------------- 57 handle I Handle of DAF to continue searching. 58 59 -Detailed_Input 60 61 handle is the handle of a DAF in which either a forward 62 or backward search has already been started by 63 dafbfs_c or dafbbs_c. The DAF may be open for read 64 or write access. 65 66 -Detailed_Output 67 68 None. 69 70 -Parameters 71 72 None. 73 74 -Exceptions 75 76 1) If the input handle is invalid, the error will be diagnosed 77 by routines called by this routine. 78 79 2) If this routine is called when no search is in progress in the 80 the current DAF, the error SPICE(DAFNOSEARCH) is signalled. 81 82 -Files 83 84 None. 85 86 -Particulars 87 88 dafcs_c supports simultaneous searching of multiple DAFs. In 89 applications that use this capability, dafcs_c should be called 90 prior to each call to daffna_c, daffpa_c, dafgn_c, or dafgs_c to 91 specify which DAF is to be acted upon. 92 93 The DAF search routines are: 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 1) See Particulars. 217 218 -Restrictions 219 220 None. 221 222 -Literature_References 223 224 None. 225 226 -Author_and_Institution 227 228 N.J. Bachman (JPL) 229 W.L. Taber (JPL) 230 231 -Version 232 233 -CSPICE Version 1.0.0, 31-JUL-1999 (NJB) (WLT) 234 235 -Index_Entries 236 237 select a daf to continue searching 238 239 -& 240 */ 241 242 { /* Begin dafcs_c */ 243 244 245 /* 246 Participate in error tracing. 247 */ 248 chkin_c ( "dafcs_c" ); 249 250 251 dafcs_ ( ( integer * ) &handle ); 252 253 254 chkout_c ( "dafcs_c" ); 255 256 } /* End dafcs_c */ 257