1 /* 2 3 -Procedure dafgn_c ( DAF, get array name ) 4 5 -Abstract 6 7 Return (get) the name for the current 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 "SpiceZmc.h" 47 #include "SpiceZst.h" 48 49 dafgn_c(SpiceInt lenout,SpiceChar * name)50 void dafgn_c ( SpiceInt lenout, 51 SpiceChar * name ) 52 53 /* 54 55 -Brief_I/O 56 57 Variable I/O Description 58 -------- --- -------------------------------------------------- 59 lenout I Length of array name string. 60 name O Name of current array. 61 62 -Detailed_Input 63 64 lenout is the length of the name string, including room for 65 the null terminator. For a DAF with summary 66 parameters ND and NI, the maximum length of an array 67 name is 68 69 (NI + 1) 70 NC = 8 * ( ND + -------- ) (Note that this is 71 2 integer division.) 72 73 Given NC, lenout should be set equal to NC+1. 74 75 -Detailed_Output 76 77 name is the name for the current array (the array found by 78 the latest call to daffna_c or daffpa_c). 79 80 -Parameters 81 82 None. 83 84 -Files 85 86 None. 87 88 -Exceptions 89 90 1) If this routine is called when no search is in progress in the 91 the current DAF, the error SPICE(DAFNOSEARCH) is signalled. 92 93 2) If the DAF for which the "current" array's name is to be 94 returned has actually been closed, the error will be diagnosed 95 by routines called by this routine. 96 97 3) If no array is current in the current DAF, the error 98 SPICE(NOCURRENTARRAY) is signalled. There is no current 99 array when a search is started by dafbfs_c or dafbbs_c, but no 100 calls to daffna_c or dafbna_c have been made yet, or whenever 101 daffna_c or daffpa_c return the value SPICEFALSE in the found 102 argument. 103 104 4) The error SPICE(NULLPOINTER) is signaled if the input string 105 pointer is null. 106 107 5) The caller must pass a value indicating the length of the output 108 string. If this value is not at least 2, the error 109 SPICE(STRINGTOOSHORT) is signaled. 110 111 -Particulars 112 113 The DAF search routines are: 114 115 dafbfs_c Begin forward search. 116 daffna Find next array. 117 118 dafbbs_c Begin backward search. 119 daffpa_c Find previous array. 120 121 dafgs_c Get summary. 122 dafgn_c Get name. 123 dafgh_c Get handle. 124 125 dafcs_c Continue search. 126 127 The main function of these entry points is to allow the 128 contents of any DAF to be examined on an array-by-array 129 basis. 130 131 Conceptually, the arrays in a DAF form a doubly linked list, 132 which can be searched in either of two directions: forward or 133 backward. It is possible to search multiple DAFs simultaneously. 134 135 dafbfs_c (begin forward search) and daffna are used to search the 136 arrays in a DAF in forward order. In applications that search a 137 single DAF at a time, the normal usage is 138 139 dafbfs_c ( handle ); 140 daffna_c ( &found ); 141 142 while ( found ) 143 { 144 dafgs_c ( sum ); 145 dafgn_c ( name ); 146 . 147 . 148 149 daffna_c ( &found ); 150 } 151 152 153 dafbbs_c (begin backward search) and daffpa_c are used to search the 154 arrays in a DAF in backward order. In applications that search 155 a single DAF at a time, the normal usage is 156 157 dafbbs_c ( handle ); 158 daffpa_c ( &found ); 159 160 while ( found ) 161 { 162 dafgs_c ( sum ); 163 dafgn_c ( name ); 164 . 165 . 166 167 daffpa_c ( &found ); 168 } 169 170 171 In applications that conduct multiple searches simultaneously, 172 the above usage must be modified to specify the handle of the 173 file to operate on, in any case where the file may not be the 174 last one specified by dafbfs_c or dafbbs_c. The routine dafcs_c 175 (DAF, continue search) is used for this purpose. Below, we 176 give an example of an interleaved search of two files specified 177 by the handles handl1 and handl2. The directions of searches 178 in different DAFs are independent; here we conduct a forward 179 search on one file and a backward search on the other. 180 Throughout, we use dafcs to specify which file to operate on, 181 before calling daffna_c, daffpa_c, dafgs_c, or dafgn_c. 182 183 184 dafbfs_c ( handl1 ); 185 dafbbs_c ( handl2 ); 186 187 dafcs_c ( handl1 ); 188 daffna_c ( &found1 ); 189 190 dafcs_c ( handl2 ); 191 daffpa_c ( &found2 ); 192 193 while ( found1 || found2 ) 194 { 195 if ( found1 ) 196 { 197 dafcs_c ( handl1 ); 198 dafgs_c ( sum ); 199 dafgn_c ( name ); 200 . 201 . 202 dafcs_c ( &handl1 ); 203 daffna_c ( &found1 ); 204 } 205 206 if ( found2 ) 207 { 208 dafcs_c ( handl2 ); 209 dafgs_c ( sum ); 210 dafgn_c ( name ); 211 . 212 . 213 dafcs_c ( handl2 ); 214 daffpa_c ( &found2 ); 215 } 216 } 217 218 219 At any time, the latest array found (whether by daffna_c or daffpa_c) 220 is regarded as the "current" array for the file in which the 221 array was found. The last DAF in which a search was started, 222 executed, or continued by any of dafbfs_c, dafbbs_c, daffna_c, 223 daffpa_c or dafcs_c is regarded as the "current" DAF. The summary 224 and name for the current array in the current DAF can be obtained 225 separately, as shown above, by calls to DAFGS (get summary) and 226 dafgn_c (get name). The handle of the current DAF can also be 227 obtained by calling dafgh_c (get handle). 228 229 Once a search has been begun, it may be continued in either 230 direction. That is, daffpa_c may be used to back up during a 231 forward search, and daffna_c may be used to advance during a 232 backward search. 233 234 -Examples 235 236 1) See Particulars. 237 238 -Restrictions 239 240 None. 241 242 -Literature_References 243 244 NAIF Document 167.0, "Double Precision Array Files (DAF) 245 Specification and User's Guide" 246 247 -Author_and_Institution 248 249 N.J. Bachman (JPL) 250 W.L. Taber (JPL) 251 I.M. Underwood (JPL) 252 253 -Version 254 255 -CSPICE Version 1.0.0, 01-AUG-1999 (NJB) (WLT) (IMU) 256 257 -Index_Entries 258 259 get daf array name 260 261 -& 262 */ 263 264 { /* Begin dafgn_c */ 265 266 267 /* 268 Participate in error tracing. 269 */ 270 chkin_c ( "dafgn_c" ); 271 272 /* 273 Make sure the output string has at least enough room for one output 274 character and a null terminator. Also check for a null pointer. 275 */ 276 CHKOSTR ( CHK_STANDARD, "dafgn_c", name, lenout ); 277 278 279 dafgn_ ( ( char * ) name, 280 ( ftnlen ) lenout-1 ); 281 282 /* 283 Convert the output string to C style. 284 */ 285 F2C_ConvertStr ( lenout, name ); 286 287 288 chkout_c ( "dafgn_c" ); 289 290 } /* End dafgn_c */ 291