1 /* 2 3 -Procedure ekaced_c ( EK, add d.p. data to column ) 4 5 -Abstract 6 7 Add data to an double precision column in a specified EK record. 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 EK 37 38 -Keywords 39 40 EK 41 FILES 42 UTILITY 43 44 */ 45 46 #include "SpiceUsr.h" 47 #include "SpiceZfc.h" 48 #include "SpiceZmc.h" 49 #include "SpiceZim.h" 50 #undef ekaced_c 51 52 ekaced_c(SpiceInt handle,SpiceInt segno,SpiceInt recno,ConstSpiceChar * column,SpiceInt nvals,ConstSpiceDouble * dvals,SpiceBoolean isnull)53 void ekaced_c ( SpiceInt handle, 54 SpiceInt segno, 55 SpiceInt recno, 56 ConstSpiceChar * column, 57 SpiceInt nvals, 58 ConstSpiceDouble * dvals, 59 SpiceBoolean isnull ) 60 /* 61 62 -Brief_I/O 63 64 Variable I/O Description 65 -------- --- -------------------------------------------------- 66 handle I EK file handle. 67 segno I Index of segment containing record. 68 recno I Record to which data is to be added. 69 column I Column name. 70 nvals I Number of values to add to column. 71 dvals I Double precision values to add to column. 72 isnull I Flag indicating whether column entry is null. 73 74 -Detailed_Input 75 76 handle is the handle of an EK file open for write access. 77 78 segno is the number of the segment to which the record 79 is to be added. EK segment numbers range from 80 zero to N-1, where N is the number of segments 81 in the kernel. 82 83 recno is the index of the record to which data is to be 84 added. This record number is relative to the start 85 of the segment indicated by segno; the first 86 record in the segment has index 0. 87 88 column is the name of the column to which data is to be 89 added. 90 nvals, 91 dvals are, respectively, the number of values to add to 92 the specified column and the set of values 93 themselves. The data values are written into the 94 specified column and record. 95 96 If the column has fixed-size entries, then nvals 97 must equal the entry size for the specified column. 98 99 100 isnull is a logical flag indicating whether the entry is 101 null. If isnull is SPICEFALSE, the column entry 102 defined by nvals and dvals is added to the 103 specified kernel file. 104 105 If isnull is SPICETRUE, nvals and cvals are ignored: 106 no data are written into the specified column entry. 107 The column entry is marked as a null value. 108 109 If the column has fixed-length, variable-size 110 entries, the number of entries is considered to 111 be 1. 112 113 -Detailed_Output 114 115 None. See $Particulars for a description of the effect of this 116 routine. 117 118 -Parameters 119 120 None. 121 122 -Exceptions 123 124 1) If handle is invalid, the error will be diagnosed by routines 125 called by this routine. 126 127 2) If segno is out of range, the error will be diagnosed by 128 routines called by this routine. 129 130 3) If column is not the name of a declared column, the error 131 will be diagnosed by routines called by this routine. 132 133 4) If column specifies a column of whose data type is not 134 double precision, the error SPICE(WRONGDATATYPE) will be 135 signaled. 136 137 5) If recno is out of range, the error will be diagnosed by 138 routines called by this routine. 139 140 6) If the specified column has fixed-size entries and nvals 141 does not match this size, the error will be diagnosed by 142 routines called by this routine. 143 144 7) If the specified column has variable-size entries and nvals 145 is non-positive, the error will be diagnosed by routines 146 called by this routine. 147 148 8) If an attempt is made to add a null value to a column that 149 doesn't take null values, the error will be diagnosed by 150 routines called by this routine. 151 152 9) If column specifies a column of whose class is not 153 a double precision class known to this routine, the error 154 SPICE(NOCLASS) will be signaled. 155 156 10) If an I/O error occurs while reading or writing the indicated 157 file, the error will be diagnosed by routines called by this 158 routine. 159 160 11) If the input string pointer is null, the error 161 SPICE(NULLPOINTER) will be signaled. 162 163 12) If the input string has length zero, the error 164 SPICE(EMPTYSTRING) will be signaled. 165 166 167 -Files 168 169 See the EK Required Reading for a discussion of the EK file 170 format. 171 172 -Particulars 173 174 This routine operates by side effects: it modifies the named 175 EK file by adding data to the specified record in the specified 176 column. Data may be added to a segment in random order; it is not 177 necessary to fill in columns or rows sequentially. Data may only 178 be added one column entry at a time. 179 180 -Examples 181 182 1) Add the value 999. to the third record of the column DCOL in 183 the fifth segment of an EK file designated by handle. 184 185 ekaced_c ( handle, 4, 2, "DCOL", 1, 999., SPICEFALSE ); 186 187 188 2) Same as (1), but this time add a null value. The argument 189 999. is ignored because the null flag is set to SPICETRUE. 190 191 ekaced_c ( handle, 4, 2, "DCOL", 1, 999., SPICETRUE ); 192 193 194 3) Add an array dbuff of 10 values to the third record of the 195 column darray in the fifth segment of an EK file designated by 196 handle. 197 198 ekaced_c ( handle, 4, 2, "DARRAY", 10, dbuff, SPICEFALSE ); 199 200 201 4) A more detailed example: append a record to a specified 202 segment. 203 204 Suppose we have an E-kernel named order_db.ek which contains 205 records of orders for data products. The E-kernel has a 206 table called DATAORDERS that consists of the set of columns 207 listed below: 208 209 DATAORDERS 210 211 Column Name Data Type 212 ----------- --------- 213 ORDER_ID INTEGER 214 CUSTOMER_ID INTEGER 215 LAST_NAME CHARACTER*(*) 216 FIRST_NAME CHARACTER*(*) 217 ORDER_DATE TIME 218 COST DOUBLE PRECISION 219 220 The order database also has a table of items that have been 221 ordered. The columns of this table are shown below: 222 223 DATAITEMS 224 225 Column Name Data Type 226 ----------- --------- 227 ITEM_ID INTEGER 228 ORDER_ID INTEGER 229 ITEM_NAME CHARACTER*(*) 230 DESCRIPTION CHARACTER*(*) 231 PRICE DOUBLE PRECISION 232 233 234 We'll suppose that the file order_db.ek contains two segments, 235 the first containing the DATAORDERS table and the second 236 containing the DATAITEMS table. 237 238 If we wanted to insert a new record into the DATAORDERS 239 table in position 0, we'd make the following calls: 240 241 242 #include "SpiceUsr.h" 243 . 244 . 245 . 246 /. 247 Open the database for write access. This call is 248 made when the file already exists. See ekopn_c for 249 an example of creating a new file. 250 ./ 251 ekopw_c ( "order_db.ek", &handle ); 252 253 /. 254 Append a new, empty record to the DATAORDERS 255 table. Recall that the DATAORDERS table 256 is in segment number 0. The call will return 257 the number of the new, empty record. 258 ./ 259 ekappr_c ( handle, 0, &recno ); 260 261 /. 262 At this point, the new record is empty. A valid EK 263 cannot contain empty records. We fill in the data 264 here. Data items are filled in one column at a time. 265 The order in which the columns are filled in is not 266 important. We use the ekace*_c (add column entry) 267 routines to fill in column entries. We'll assume 268 that no entries are null. All entries are scalar, 269 so the entry size is 1. 270 ./ 271 isnull = SPICEFALSE; 272 size = 1; 273 274 /. 275 The following variables will contain the data for 276 the new record. 277 ./ 278 ordid = 10011; 279 custid = 531; 280 lname = "scientist"; 281 fname = "joe"; 282 odate = "1995-sep-20"; 283 cost = 5000.; 284 285 /. 286 Note that the names of the routines called 287 correspond to the data types of the columns: the 288 last letter of the routine name is C, I, or D, 289 depending on the data type. Time values are 290 converted to ET for storage. 291 ./ 292 293 ekacei_c ( handle, segno, recno, "order_id", 294 size, ordid, isnull ); 295 296 ekacei_c ( handle, segno, recno, "customer_id", 297 size, custid, isnull ); 298 299 ekacec_c ( handle, segno, recno, "last_name", 300 size, vallen, lname, isnull ); 301 302 ekacec_c ( handle, segno, recno, "first_name", 303 size, vallen, fname, isnull ); 304 305 utc2et_c ( odate, &et ); 306 307 308 ekaced_c ( handle, segno, recno, "order_date", 309 size, et, isnull ); 310 311 ekaced_c ( handle, segno, recno, "cost", 312 size, cost, isnull ); 313 314 315 /. 316 Close the file to make the update permanent. 317 ./ 318 ekcls_c ( handle ); 319 320 321 -Restrictions 322 323 None. 324 325 -Literature_References 326 327 None. 328 329 -Author_and_Institution 330 331 N.J. Bachman (JPL) 332 333 -Version 334 335 -CSPICE Version 1.0.0, 28-AUG-2001 (NJB) 336 337 -Index_Entries 338 339 add double precision data to EK column 340 add data to EK 341 write double precision data to EK column 342 343 -& 344 */ 345 346 { /* Begin ekaced_c */ 347 348 349 /* 350 Local variables 351 */ 352 logical null; 353 354 /* 355 Participate in error tracing. 356 */ 357 chkin_c ( "ekaced_c" ); 358 359 /* 360 Check the column name to make sure the pointer is non-null 361 and the string length is non-zero. 362 */ 363 CHKFSTR ( CHK_STANDARD, "ekaced_c", column ); 364 365 /* 366 Convert the null flag to type logical before passing it to 367 ekaced_. Also map the segment and record numbers to their 368 Fortran-style counterparts. 369 */ 370 371 null = isnull; 372 373 segno++; 374 recno++; 375 376 ekaced_ ( ( integer * ) &handle, 377 ( integer * ) &segno, 378 ( integer * ) &recno, 379 ( char * ) column, 380 ( integer * ) &nvals, 381 ( doublereal * ) dvals, 382 ( logical * ) &null, 383 ( ftnlen ) strlen(column) ); 384 385 386 chkout_c ( "ekaced_c" ); 387 388 } /* End ekaced_c */ 389 390 391 392 393