1 /* 2 3 -Procedure pckcov_c ( PCK coverage ) 4 5 -Abstract 6 7 Find the coverage window for a specified reference frame in a 8 specified binary PCK file. 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 CELLS 38 DAF 39 PCK 40 TIME 41 WINDOWS 42 43 -Keywords 44 45 ORIENTATION 46 TIME 47 UTILITY 48 49 */ 50 51 #include "SpiceUsr.h" 52 #include "SpiceZfc.h" 53 #include "SpiceZmc.h" 54 55 pckcov_c(ConstSpiceChar * pck,SpiceInt idcode,SpiceCell * cover)56 void pckcov_c ( ConstSpiceChar * pck, 57 SpiceInt idcode, 58 SpiceCell * cover ) 59 /* 60 61 -Brief_I/O 62 63 Variable I/O Description 64 -------- --- -------------------------------------------------- 65 pck I Name of PCK file. 66 idcode I Class ID code of PCK reference frame. 67 cover I/O Window giving coverage in `pck' for `idcode'. 68 69 -Detailed_Input 70 71 pck is the name of a binary PCK file. 72 73 idcode is the integer frame class ID code of a PCK reference 74 frame for which data are expected to exist in the 75 specified PCK file. 76 77 cover is an initialized CSPICE window data structure. 78 `cover' optionally may contain coverage data on 79 input; on output, the data already present in `cover' 80 will be combined with coverage found for the 81 reference frame designated by `idcode' in the file 82 `pck'. 83 84 If `cover' contains no data on input, its size and 85 cardinality still must be initialized. 86 87 -Detailed_Output 88 89 cover is a CSPICE window data structure which represents 90 the merged coverage for the reference frame having 91 frame class ID `idcode'. This is the set of time 92 intervals for which data for `idcode' are present in 93 the file `pck', merged with the set of time intervals 94 present in `cover' on input. The merged coverage is 95 represented as the union of one or more disjoint time 96 intervals. The window `cover' contains the pairs of 97 endpoints of these intervals. 98 99 The interval endpoints contained in `cover' are 100 ephemeris times, expressed as seconds past J2000 101 TDB. 102 103 See the Examples section below for a complete 104 example program showing how to retrieve the 105 endpoints from `cover'. 106 107 -Parameters 108 109 None. 110 111 -Exceptions 112 113 1) If the input file has transfer format, the error 114 SPICE(INVALIDFORMAT) is signaled. 115 116 2) If the input file is not a transfer file but has architecture 117 other than DAF, the error SPICE(BADARCHTYPE) is signaled. 118 119 3) If the input file is a binary DAF file of type other than 120 PCK, the error SPICE(BADFILETYPE) is signaled. 121 122 4) If the PCK file cannot be opened or read, the error will 123 be diagnosed by routines called by this routine. The output 124 window will not be modified. 125 126 5) If the size of the output window argument COVER is 127 insufficient to contain the actual number of intervals in the 128 coverage window for IDCODE, the error will be diagnosed by 129 routines called by this routine. 130 131 6) The error SPICE(EMPTYSTRING) is signaled if the input 132 string `pck' does not contain at least one character, since the 133 input string cannot be converted to a Fortran-style string in 134 this case. 135 136 7) The error SPICE(NULLPOINTER) is signaled if the input string 137 pointer `pck' is null. 138 139 -Files 140 141 This routine reads a PCK file. 142 143 -Particulars 144 145 This routine provides an API via which applications can determine 146 the coverage a specified PCK file provides for a specified 147 PCK class reference frame. 148 149 -Examples 150 151 1) This example demonstrates combined usage of pckcov_c and the 152 related PCK utility pckfrm_c. 153 154 Display the coverage for each object in a specified PCK file. 155 Find the set of objects in the file; for each object, find 156 and display the coverage. 157 158 159 #include <stdio.h> 160 #include "SpiceUsr.h" 161 162 int main() 163 { 164 /. 165 Local parameters 166 ./ 167 #define FILSIZ 256 168 #define MAXIV 1000 169 #define WINSIZ ( 2 * MAXIV ) 170 #define TIMLEN 51 171 #define MAXOBJ 1000 172 173 /. 174 Local variables 175 ./ 176 SPICEDOUBLE_CELL ( cover, WINSIZ ); 177 SPICEINT_CELL ( ids, MAXOBJ ); 178 179 SpiceChar lsk [ FILSIZ ]; 180 SpiceChar pck [ FILSIZ ]; 181 SpiceChar timstr [ TIMLEN ]; 182 183 SpiceDouble b; 184 SpiceDouble e; 185 186 SpiceInt i; 187 SpiceInt j; 188 SpiceInt niv; 189 SpiceInt obj; 190 191 192 /. 193 Load a leapseconds kernel for output time conversion. 194 PCKCOV itself does not require a leapseconds kernel. 195 ./ 196 prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk ); 197 furnsh_c ( lsk ); 198 199 /. 200 Get name of PCK file. 201 ./ 202 prompt_c ( "Name of PCK file > ", FILSIZ, pck ); 203 204 /. 205 Find the set of frames in the PCK file. 206 ./ 207 pckfrm_c ( pck, &ids ); 208 209 /. 210 We want to display the coverage for each frame. Loop over 211 the contents of the ID code set, find the coverage for 212 each item in the set, and display the coverage. 213 ./ 214 for ( i = 0; i < card_c( &ids ); i++ ) 215 { 216 /. 217 Find the coverage window for the current frame. 218 Empty the coverage window each time so we don't 219 include data for the previous frame. 220 ./ 221 obj = SPICE_CELL_ELEM_I( &ids, i ); 222 223 scard_c ( 0, &cover ); 224 pckcov_c ( pck, obj, &cover ); 225 226 /. 227 Get the number of intervals in the coverage window. 228 ./ 229 niv = wncard_c ( &cover ); 230 231 /. 232 Display a simple banner. 233 ./ 234 printf ( "%s\n", "========================================" ); 235 236 printf ( "Coverage for frame %d\n", (int)obj ); 237 238 /. 239 Convert the coverage interval start and stop times to TDB 240 calendar strings. 241 ./ 242 for ( j = 0; j < niv; j++ ) 243 { 244 /. 245 Get the endpoints of the jth interval. 246 ./ 247 wnfetd_c ( &cover, j, &b, &e ); 248 249 /. 250 Convert the endpoints to TDB calendar 251 format time strings and display them. 252 ./ 253 timout_c ( b, 254 "YYYY MON DD HR:MN:SC.### (TDB) ::TDB", 255 TIMLEN, 256 timstr ); 257 258 printf ( "\n" 259 "Interval: %d\n" 260 "Start: %s\n", 261 (int)j, 262 timstr ); 263 264 timout_c ( e, 265 "YYYY MON DD HR:MN:SC.### (TDB) ::TDB", 266 TIMLEN, 267 timstr ); 268 printf ( "Stop: %s\n", timstr ); 269 270 } 271 272 } 273 return ( 0 ); 274 } 275 276 277 2) Find the coverage for the frame designated by `idcode' 278 provided by the set of PCK files loaded via a metakernel. 279 (The metakernel must also specify a leapseconds kernel.) 280 281 #include <stdio.h> 282 #include "SpiceUsr.h" 283 284 int main() 285 { 286 287 /. 288 Local parameters 289 ./ 290 #define FILSIZ 256 291 #define LNSIZE 81 292 #define MAXCOV 100000 293 #define WINSIZ ( 2 * MAXCOV ) 294 #define TIMLEN 51 295 296 /. 297 Local variables 298 ./ 299 SPICEDOUBLE_CELL ( cover, WINSIZ ); 300 301 SpiceBoolean found; 302 303 SpiceChar file [ FILSIZ ]; 304 SpiceChar idch [ LNSIZE ]; 305 SpiceChar meta [ FILSIZ ]; 306 SpiceChar source [ FILSIZ ]; 307 SpiceChar timstr [ TIMLEN ]; 308 SpiceChar type [ LNSIZE ]; 309 310 SpiceDouble b; 311 SpiceDouble e; 312 313 SpiceInt count; 314 SpiceInt handle; 315 SpiceInt i; 316 SpiceInt idcode; 317 SpiceInt niv; 318 319 320 /. 321 Prompt for the metakernel name; load the metakernel. 322 The metakernel lists the PCK files whose coverage 323 for `idcode' we'd like to determine. The metakernel 324 must also specify a leapseconds kernel. 325 ./ 326 prompt_c ( "Name of metakernel > ", FILSIZ, meta ); 327 furnsh_c ( meta ); 328 329 /. 330 Get the ID code of interest. 331 ./ 332 prompt_c ( "Enter ID code > ", LNSIZE, idch ); 333 prsint_c ( idch, &idcode ); 334 335 /. 336 Find out how many kernels are loaded. Loop over the 337 kernels: for each loaded PCK file, add its coverage 338 for `idcode', if any, to the coverage window. 339 ./ 340 ktotal_c ( "PCK", &count ); 341 342 for ( i = 0; i < count; i++ ) 343 { 344 kdata_c ( i, "PCK", FILSIZ, LNSIZE, FILSIZ, 345 file, type, source, &handle, &found ); 346 347 pckcov_c ( file, idcode, &cover ); 348 } 349 350 /. 351 Display results. 352 353 Get the number of intervals in the coverage window. 354 ./ 355 niv = wncard_c ( &cover ); 356 357 /. 358 Display a simple banner. 359 ./ 360 printf ( "\nCoverage for frame %d\n", (int)idcode ); 361 362 /. 363 Convert the coverage interval start and stop times to TDB 364 calendar strings. 365 ./ 366 for ( i = 0; i < niv; i++ ) 367 { 368 /. 369 Get the endpoints of the ith interval. 370 ./ 371 wnfetd_c ( &cover, i, &b, &e ); 372 373 /. 374 Convert the endpoints to TDB calendar 375 format time strings and display them. 376 ./ 377 timout_c ( b, 378 "YYYY MON DD HR:MN:SC.### (TDB) ::TDB", 379 TIMLEN, 380 timstr ); 381 382 printf ( "\n" 383 "Interval: %d\n" 384 "Start: %s\n", 385 (int)i, 386 timstr ); 387 388 timout_c ( e, 389 "YYYY MON DD HR:MN:SC.### (TDB) ::TDB", 390 TIMLEN, 391 timstr ); 392 printf ( "Stop: %s\n", timstr ); 393 394 } 395 return ( 0 ); 396 } 397 398 399 400 -Restrictions 401 402 1) If an error occurs while this routine is updating the window 403 `cover', the window may be corrupted. 404 405 -Literature_References 406 407 None. 408 409 -Author_and_Institution 410 411 N.J. Bachman (JPL) 412 413 -Version 414 415 -CSPICE Version 1.0.2, 12-JUL-2016 (EDW) 416 417 Edit to example program to use "%d" with explicit casts 418 to int for printing SpiceInts with printf. 419 420 -CSPICE Version 1.0.1, 01-JUL-2014 (NJB) 421 422 Updated index entries. 423 424 -CSPICE Version 1.0.0, 30-NOV-2007 (NJB) 425 426 -Index_Entries 427 428 get coverage window for binary pck reference frame 429 get coverage start and stop time for binary pck frame 430 431 -& 432 */ 433 434 { /* Begin pckcov_c */ 435 436 437 /* 438 Participate in error tracing. 439 */ 440 if ( return_c() ) 441 { 442 return; 443 } 444 chkin_c ( "pckcov_c" ); 445 446 447 /* 448 Check the input string `pck' to make sure the pointer is non-null 449 and the string length is non-zero. 450 */ 451 CHKFSTR ( CHK_STANDARD, "pckcov_c", pck ); 452 453 /* 454 Make sure cell data type is d.p. 455 */ 456 CELLTYPECHK ( CHK_STANDARD, "pckcov_c", SPICE_DP, cover ); 457 458 /* 459 Initialize the cell if necessary. 460 */ 461 CELLINIT ( cover ); 462 463 /* 464 Call the f2c'd Fortran routine. 465 */ 466 pckcov_ ( ( char * ) pck, 467 ( integer * ) &idcode, 468 ( doublereal * ) (cover->base), 469 ( ftnlen ) strlen(pck) ); 470 471 /* 472 Sync the output cell. 473 */ 474 if ( !failed_c() ) 475 { 476 zzsynccl_c ( F2C, cover ); 477 } 478 479 480 chkout_c ( "pckcov_c" ); 481 482 } /* End pckcov_c */ 483 484