1 /* 2 3 -Procedure spksub_c ( S/P Kernel, subset ) 4 5 -Abstract 6 7 Extract a subset of the data in an SPK segment into a 8 separate segment. 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 SPK 38 DAF 39 40 -Keywords 41 42 EPHEMERIS 43 44 */ 45 46 #include "SpiceUsr.h" 47 #include "SpiceZfc.h" 48 #include "SpiceZmc.h" 49 spksub_c(SpiceInt handle,SpiceDouble descr[5],ConstSpiceChar * ident,SpiceDouble begin,SpiceDouble end,SpiceInt newh)50 void spksub_c ( SpiceInt handle, 51 SpiceDouble descr[5], 52 ConstSpiceChar * ident, 53 SpiceDouble begin, 54 SpiceDouble end, 55 SpiceInt newh ) 56 57 /* 58 59 -Brief_I/O 60 61 Variable I/O Description 62 -------- --- -------------------------------------------------- 63 handle I Handle of source segment. 64 descr I Descriptor of source segment. 65 ident I Identifier of source segment. 66 begin I Beginning (initial epoch) of subset. 67 end I End (final epoch) of subset. 68 newh I Handle of new segment. 69 70 -Detailed_Input 71 72 handle, 73 descr, 74 ident are the file handle assigned to a SPK file, the 75 descriptor for a segment within the file, and the 76 identifier for that segment. Together they determine 77 a complete set of ephemeris data, from which a 78 subset is to be extracted. 79 80 begin, 81 end are the initial and final epochs (ephemeris time) 82 of the subset. 83 84 newh is the file handle assigned to the file in which 85 the new segment is to be written. The file must 86 be open for write access. newh and handle may refer 87 to the same file. 88 89 -Detailed_Output 90 91 See $Files section. 92 93 -Parameters 94 95 None. 96 97 -Exceptions 98 99 1) If the condition 100 101 ALPHA < BEGIN < END < OMEGA 102 - - - 103 104 is not satisfied (where ALPHA and OMEGA are the initial 105 and final epochs of the segment respectively), the error 106 SPICE(SPKNOTASUBSET) is signaled. 107 108 2) If the segment type is not supported by the current 109 version of spksub_c, the error SPICE(SPKTYPENOTSUPP) 110 is signaled. 111 112 3) If the segment ID string pointer is null, the error 113 SPICE(NULLPOINTER) is signaled. 114 115 4) If the segment ID string is empty, the error 116 SPICE(EMPTYSTRING) is signaled. 117 118 -Files 119 120 A new segment, which contains a subset of the data in the 121 segment specified by DESCR and HANDLE, is written to the SPK 122 file attached to NEWH. 123 124 -Particulars 125 126 Sometimes, the segments in official source files---planetary 127 Developmental Ephemeris (DE) files, archival spacecraft 128 ephemeris files, and so on---contain more data than is needed 129 by a particular user. spksub_c allows a user to extract from a 130 segment the smallest amount of ephemeris data sufficient to 131 cover a specific interval. 132 133 The new segment is written with the same identifier as the 134 original segment, and with the same descriptor, with the 135 following components changed: 136 137 1) ALPHA and OMEGA (DCD(1) and DCD(2)) are assigned the values 138 specified by BEGIN and END. 139 140 2) The beginning and ending segment addresses (ICD(5) and ICD(6)) 141 are, of course, changed to reflect the location of the new 142 segment. 143 144 -Examples 145 146 In the following code fragment, the descriptor for each segment 147 in a source SPK file is examined. For each segment that covers 148 a target interval, the smallest possible subset is extracted into 149 a custom SPK file. 150 151 Assume that the source and custom files have been opened, for 152 read and write access, with handles srchan and custhan respectively. 153 154 #include "SpiceUsr.h" 155 . 156 . 157 . 158 dafbfs_c ( srchan ); 159 daffna_c ( &found ); 160 161 while ( found ) 162 { 163 dafgs_c ( descr ); 164 dafus_c ( descr, 2, 6, dc, ic ); 165 166 if ( ( dc[0] <= begin ) && ( end <= dc[1] ) ) 167 { 168 dafgn_c ( ident ); 169 spksub_c ( srchan, descr, ident, begin, end, custhan ); 170 } 171 172 daffna_c ( &found ); 173 } 174 175 176 -Restrictions 177 178 1) There is no way for spksub_c to verify that the descriptor and 179 identifier are the original ones for the segment. Changing 180 the descriptor can cause the data in the new segment to be 181 evaluated incorrectly; changing the identifier can destroy 182 the path from the data back to its original source. 183 184 -Literature_References 185 186 NAIF Document 168.0, "S- and P- Kernel (SPK) Specification and 187 User's Guide" 188 189 -Author_and_Institution 190 191 K.R. Gehringer (JPL) 192 W.L. Taber (JPL) 193 N.J. Bachman (JPL) 194 J.M. Lynch (JPL) 195 R.E. Thurman (JPL) 196 I.M. Underwood (JPL) 197 198 -Version 199 200 -CSPICE Version 1.0.0, 29-JUN-1999 (KRG)(WLT)(NJB)(JML)(RET)(IMU) 201 202 -Index_Entries 203 204 subset of spk file 205 206 -& 207 */ 208 209 { /* Begin spksub_c */ 210 211 212 213 /* 214 Participate in error tracing. 215 */ 216 chkin_c ( "spksub_c" ); 217 218 /* 219 Check the input strings to make sure the pointers 220 are non-null and the string lengths are non-zero. 221 */ 222 CHKFSTR ( CHK_STANDARD, "spksub_c", ident ); 223 224 225 spksub_ ( ( integer * ) &handle, 226 ( doublereal * ) descr, 227 ( char * ) ident, 228 ( doublereal * ) &begin, 229 ( doublereal * ) &end, 230 ( integer * ) &newh, 231 ( ftnlen ) strlen(ident) ); 232 233 234 chkout_c ( "spksub_c" ); 235 236 } /* End spksub_c */ 237