1 /* 2 3 -Procedure ekgi_c ( EK, get event data, integer ) 4 5 -Abstract 6 7 Return an element of an entry in a column of integer 8 type in a specified row. 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 EK 38 39 -Keywords 40 41 ASSIGNMENT 42 EK 43 44 */ 45 46 #include "SpiceUsr.h" 47 #include "SpiceZfc.h" 48 ekgi_c(SpiceInt selidx,SpiceInt row,SpiceInt elment,SpiceInt * idata,SpiceBoolean * null,SpiceBoolean * found)49 void ekgi_c ( SpiceInt selidx, 50 SpiceInt row, 51 SpiceInt elment, 52 SpiceInt * idata, 53 SpiceBoolean * null, 54 SpiceBoolean * found ) 55 /* 56 57 -Brief_I/O 58 59 Variable I/O Description 60 -------- --- -------------------------------------------------- 61 selidx I Index of parent column in SELECT clause. 62 row I Row to fetch from. 63 elment I Index of element, within column entry, to fetch. 64 idata O Integer element of column entry. 65 null O Flag indicating whether column entry was null. 66 found O Flag indicating whether column was present in row. 67 68 -Detailed_Input 69 70 selidx is the SELECT clause index of the column to fetch 71 from. The range of selidx is from 0 to one less than 72 the number of columns in the SELECT clause. 73 74 row is the output row containing the entry to fetch 75 from. The range of row is from 0 to one less than 76 the number of rows satisfying the previous query. 77 78 elment is the index of the element of the column entry 79 to fetch. The normal range of elment is from 0 to 80 one less than the size of the column's entry, but 81 elment is allowed to exceed the number of elements in 82 the column entry; if it does, found is returned 83 as SPICEFALSE. This allows the caller to read data 84 from the column entry in a loop without checking the 85 number of available elements first. 86 87 Null values in variable-sized columns are 88 considered to have size 1. 89 90 -Detailed_Output 91 92 idata is the requested element of the specified column 93 entry. If the entry is null, idata is undefined. 94 95 If idata is too short to accommodate the requested 96 column entry element, the element is truncated on 97 the right to fit idata. 98 99 null is a logical flag indicating whether the entry 100 belonging to the specified column in the specified 101 row is null. 102 103 found is a logical flag indicating whether the specified 104 element was found. If the element does not exist, 105 found is returned as SPICEFALSE. 106 107 -Parameters 108 109 None. 110 111 -Exceptions 112 113 1) If the input argument elment is less than 0, found is returned as 114 SPICEFALSE, and the error SPICE(INVALIDINDEX) is signalled. 115 However, elment is allowed to be greater than or equal to 116 the number of elements in the specified column entry; this allows 117 the caller to read data from the column entry in a loop without 118 checking the number of available elements first. If elment is 119 greater than or equal to the number of available elements, found 120 is returned as SPICEFALSE. 121 122 2) If selidx is outside of the range established by the 123 last query passed to eksrch_, the error SPICE(INVALIDINDEX) 124 will be signalled. 125 126 3) If the input argument row is less than 0 or greater than or 127 equal to the number of rows matching the query, found is returned 128 as SPICEFALSE, and the error SPICE(INVALIDINDEX) is signalled. 129 130 4) If the specified column does not have integer type, the 131 error SPICE(INVALIDTYPE) is signalled. 132 133 5) If this routine is called when no E-kernels have been loaded, 134 the error SPICE(NOLOADEDFILES) is signalled. 135 136 -Files 137 138 The EK "query and fetch" suite of functions reads binary `sequence 139 component' EK files. In order for a binary EK file to be 140 accessible to this routine, the file must be `loaded' via a call 141 to the function eklef_c. 142 143 Text format EK files cannot be used by this routine; they must 144 first be converted by binary format by the NAIF Toolkit utility 145 SPACIT. 146 147 -Particulars 148 149 This routine allows retrieval of data from integer columns. 150 151 This routine returns one element at a time in order to save the 152 caller from imposing a limit on the size of the column entries 153 that can be handled. 154 155 -Examples 156 157 1) Suppose the EK table TAB contains the following columns: 158 159 Column name Data Type Size 160 ----------- --------- ---- 161 INT_COL_1 INT 1 162 INT_COL_2 INT VARIABLE 163 INT_COL_3 INT 10 164 165 166 Suppose the query 167 168 query = "SELECT INT_COL_1 FROM TAB" 169 170 is issued to ekfind_c via the call 171 172 ekfind_c ( query, lenout, nmrows, error, errmsg ); 173 174 To fetch and dump column values from the rows that satisfy the 175 query, the loop below could be used. Note that we don't check 176 the found flags returned by ekgi_c since we know that every 177 entry in column INT_COL_1 contains one element. 178 179 /. 180 Since INT_COL_1 was the first column selected, 181 the selection index selidx is set to 0. 182 The column is scalar, so the element index eltidx 183 is set to 0. The variable nmrows is the number of 184 matching rows returned by ekfind_c. 185 ./ 186 187 selidx = 0; 188 eltidx = 0; 189 190 for ( row = 0; row < nmrows; row++ ) 191 { 192 printf ( "\nRow = %d\n\n", row ); 193 194 /. 195 Fetch values from column INT_COL_1. 196 ./ 197 ekgi_c ( selidx, row, eltidx, 198 ival, &isnull, &found ); 199 200 if ( isnull ) 201 { 202 printf ( "%s\n", "<null>" ); 203 } 204 else 205 { 206 printf ( "%d\n", ival ); 207 } 208 } 209 210 211 2) Suppose the EK table TAB is as in example 1, and we issue 212 the query 213 214 query = "SELECT INT_COL_1, INT_COL_2, INT_COL_3 FROM TAB" 215 216 to ekfind_c via the call 217 218 ekfind_c ( query, lenout, &nmrows, &error, errmsg ); 219 220 To fetch and dump column values from the rows that satisfy the 221 query, the loop below could be used. Note that we don't check 222 the found flags returned by ekgi_c since we know in advance how 223 many elements are contained in each column entry we fetch. 224 225 226 for ( row = 0; row < nmrows; row++ ) 227 { 228 printf ( "\nRow = %d\n\n", row ); 229 230 /. 231 Fetch values from column INT_COL_1. Since 232 INT_COL_1 was the first column selected, the 233 selection index selidx is set to 0. 234 ./ 235 236 selidx = 0; 237 eltidx = 0; 238 239 ekgi_c ( selidx, row, eltidx, 240 ivals[0], &isnull, &found ) 241 242 printf ( "\nColumn = INT_COL_1\n\n" ); 243 244 if ( isnull ) 245 { 246 printf ( "%s\n", "<null>" ); 247 } 248 else 249 { 250 printf ( "%d\n", ivals[0] ); 251 } 252 253 254 /. 255 Fetch values from column INT_COL_2 in the current 256 row. Since INT_COL_2 contains variable-size array 257 entries, we call eknelt_c to determine how many 258 elements to fetch. 259 ./ 260 selidx = 1; 261 262 eknelt_c ( selidx, row, &nelt ); 263 264 eltidx = 0; 265 isnull = SPICEFALSE; 266 267 while ( ( eltidx < nelt ) && ( !isnull ) ) 268 { 269 270 ekgi_c ( selidx, row, eltidx, 271 ivals[eltidx], &isnull, &found ); 272 273 eltidx++; 274 275 /. 276 If the column entry is null, we'll be kicked 277 out of this loop after the first iteration. 278 ./ 279 } 280 281 printf ( "\nColumn = INT_COL_2\n\n" ); 282 283 if ( isnull ) 284 { 285 printf ( "%s\n", "<null>" ); 286 } 287 else 288 { 289 for ( i = 0; i < nelt; i++ ) 290 { 291 printf ( "%d\n", ivals[i] ); 292 } 293 } 294 295 296 /. 297 Fetch values from column INT_COL_3 in the current 298 row. We need not call eknelt_c since we know how 299 many elements are in each column entry. 300 ./ 301 selidx = 2; 302 eltidx = 0; 303 isnull = SPICEFALSE; 304 305 306 while ( ( eltidx < 10 ) && ( !isnull ) ) 307 { 308 309 ekgi_c ( selidx, row, eltidx, 310 ivals[eltidx], &isnull, &found ); 311 312 eltidx++; 313 } 314 315 316 printf ( "\nColumn = INT_COL_3\n\n" ); 317 318 if ( isnull ) 319 { 320 printf ( "%s\n", "<null>" ); 321 } 322 else 323 { 324 for ( i = 0; i < 10; i++ ) 325 { 326 printf ( "%d\n", ivals[i] ); 327 } 328 } 329 330 } 331 332 3) See the Examples section of the query routine ekfind_c 333 for an example in which the names and data types of the 334 columns from which to fetch data are not known in advance. 335 336 -Restrictions 337 338 None. 339 340 -Literature_References 341 342 None. 343 344 -Author_and_Institution 345 346 N.J. Bachman (JPL) 347 348 -Version 349 350 -CSPICE Version 1.1.1, 09-FEB-2003 (EDW) 351 352 Minor edit to correct typo in header. 353 354 -CSPICE Version 1.1.0, 09-JUL-1998 (NJB) 355 356 Bug fix: now uses local logical variable to capture the 357 error flag value returned by the underlying f2c'd routine. 358 359 -CSPICE Version 1.0.0, 27-MAR-1998 360 361 Based on SPICELIB Version 1.1.0, 07-JUL-1996 (NJB) 362 363 -Index_Entries 364 365 fetch element from integer column entry 366 367 -& 368 */ 369 370 { /* Begin ekgi_c */ 371 372 /* 373 Local variables 374 */ 375 logical fnd; 376 377 378 /* 379 Participate in error tracing. 380 */ 381 chkin_c ( "ekgi_c" ); 382 383 384 /* 385 Convert indices to Fortran-style; increment each index. 386 */ 387 selidx ++; 388 row ++; 389 elment ++; 390 391 392 /* 393 Call the f2c'd routine. 394 */ 395 ekgi_ ( ( integer * ) &selidx, 396 ( integer * ) &row, 397 ( integer * ) &elment, 398 ( integer * ) idata, 399 ( logical * ) null, 400 ( logical * ) &fnd ); 401 402 /* 403 Set the SpiceBoolean output found flag. 404 */ 405 406 *found = fnd; 407 408 409 chkout_c ( "ekgi_c" ); 410 411 } /* End ekgi_c */ 412