Add data to an integer column in a specified EK record.
Variable I/O Description -------- --- -------------------------------------------------- handle I EK file handle. segno I Index of segment containing record. recno I Record to which data is to be added. column I Column name. nvals I Number of values to add to column. ivals I Integer values to add to column. isnull I Flag indicating whether column entry is null.
handle is the handle of an EK file open for write access. segno is the number of the segment to which the record is to be added. EK segment numbers range from 0 to N-1, where N is the number of segments in the kernel. recno is the index of the record to which data is to be added. This record number is relative to the start of the segment indicated by segno; the first record in the segment has index 0. column is the name of the column to which data is to be added. nvals, ivals are, respectively, the number of values to add to the specified column and the set of values themselves. The data values are written into the specified column and record. If the column has fixed-size entries, then NVALS must equal the entry size for the specified column. isnull is a logical flag indicating whether the entry is null. If isnull is SPICEFALSE, the column entry defined by nvals and ivals is added to the specified kernel file. If isnull is SPICETRUE, nvals and cvals are ignored: no data are written into the specified column entry. The column entry is marked as a null value. If the column has fixed-length, variable-size entries, the number of entries is considered to be 1.
None. See $Particulars for a description of the effect of this routine.
This routine operates by side effects: it modifies the named EK file by adding data to the specified record in the specified column. Data may be added to a segment in random order; it is not necessary to fill in columns or rows sequentially. Data may only be added one column entry at a time.
1) Add the value 999 to the third record of the column ICOL in the fifth segment of an EK file designated by handle. ekacei_c ( handle, 4, 2, "ICOL", 1, 999, SPICEFALSE ); 2) Same as (1), but this time add a null value. The argument 999 is ignored because the null flag is set to SPICETRUE. ekacei_c ( handle, 4, 2, "ICOL", 1, 999, SPICETRUE ) 3) Add an array IBUFF of 10 values to the third record of the column IARRAY in the fifth segment of an EK file designated by HANDLE. ekacei_c ( handle, 4, 2, "IARRAY", 10, ibuff, SPICEFALSE ); 4) A more detailed example: append a record to a specified segment. Suppose we have an E-kernel named order_db.ek which contains records of orders for data products. The E-kernel has a table called DATAORDERS that consists of the set of columns listed below: DATAORDERS Column Name Data Type ----------- --------- ORDER_ID INTEGER CUSTOMER_ID INTEGER LAST_NAME CHARACTER*(*) FIRST_NAME CHARACTER*(*) ORDER_DATE TIME COST DOUBLE PRECISION The order database also has a table of items that have been ordered. The columns of this table are shown below: DATAITEMS Column Name Data Type ----------- --------- ITEM_ID INTEGER ORDER_ID INTEGER ITEM_NAME CHARACTER*(*) DESCRIPTION CHARACTER*(*) PRICE DOUBLE PRECISION We'll suppose that the file order_db.ek contains two segments, the first containing the DATAORDERS table and the second containing the DATAITEMS table. If we wanted to insert a new record into the DATAORDERS table in position 0, we'd make the following calls: #include "SpiceUsr.h" . . . /. Open the database for write access. This call is made when the file already exists. See ekopn_c for an example of creating a new file. ./ ekopw_c ( "order_db.ek", &handle ); /. Append a new, empty record to the DATAORDERS table. Recall that the DATAORDERS table is in segment number 0. The call will return the number of the new, empty record. ./ ekappr_c ( handle, 0, &recno ); /. At this point, the new record is empty. A valid EK cannot contain empty records. We fill in the data here. Data items are filled in one column at a time. The order in which the columns are filled in is not important. We use the ekace*_c (add column entry) routines to fill in column entries. We'll assume that no entries are null. All entries are scalar, so the entry size is 1. ./ isnull = SPICEFALSE; size = 1; /. The following variables will contain the data for the new record. ./ ordid = 10011; custid = 531; lname = "scientist"; fname = "joe"; odate = "1995-sep-20"; cost = 5000.; /. Note that the names of the routines called correspond to the data types of the columns: the last letter of the routine name is C, I, or D, depending on the data type. Time values are converted to ET for storage. ./ ekacei_c ( handle, segno, recno, "order_id", size, ordid, isnull ); ekacei_c ( handle, segno, recno, "customer_id", size, custid, isnull ); ekacec_c ( handle, segno, recno, "last_name", size, vallen, lname, isnull ); ekacec_c ( handle, segno, recno, "first_name", size, vallen, fname, isnull ); utc2et_c ( odate, &et ); ekaced_c ( handle, segno, recno, "order_date", size, et, isnull ); ekaced_c ( handle, segno, recno, "cost", size, cost, isnull ); /. Close the file to make the update permanent. ./ ekcls_c ( handle );
1) If handle is invalid, the error will be diagnosed by routines called by this routine. 2) If segno is out of range, the error will be diagnosed by routines called by this routine. 3) If column is not the name of a declared column, the error will be diagnosed by routines called by this routine. 4) If column specifies a column of whose data type is not integer, the error SPICE(WRONGDATATYPE) will be signaled. 5) If recno is out of range, the error will be diagnosed by routines called by this routine. 6) If the specified column has fixed-size entries and nvals does not match this size, the error will be diagnosed by routines called by this routine. 7) If the specified column has variable-size entries and nvals is non-positive, the error will be diagnosed by routines called by this routine. 8) If an attempt is made to add a null value to a column that doesn't take null values, the error will be diagnosed by routines called by this routine. 9) If column specifies a column of whose class is not an integer class known to this routine, the error SPICE(NOCLASS) will be signaled. 10) If an I/O error occurs while reading or writing the indicated file, the error will be diagnosed by routines called by this routine. 11) If the input string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 12) If the input string has length zero, the error SPICE(EMPTYSTRING) will be signaled.
See the EK Required Reading for a discussion of the EK file format.
N.J. Bachman (JPL)
-CSPICE Version 1.0.0, 28-AUG-2001 (NJB)
add integer data to EK column add data to EK write integer data to EK column