Table of contents
CSPICE_EKACEI adds data to an integer column in the specified
record of an EK file.
Given:
handle the scalar integer referring to an EK file open for write
access.
help, handle
LONG = Scalar
segno the scalar integer indicating EK segment number for the new
record.
help, segno
LONG = Scalar
recno the scalar integer indicating the index of the new record.
help, recno
LONG = Scalar
column the string scalar name of the column for the new record.
help, column
STRING = Scalar
nvals the integer number of entries from 'ivals' to add to the new
record.
help, nvals
LONG = Scalar
ivals an array of integer values containing the data values to add to
the new record in 'column'.
help, ivals
LONG = Array[N]
Note: 'nvals' specifies the number of 'ivals'
entries written to the new record.
isnull a scalar boolean flagging whether the entry is null, if equal to
TRUE, cspice_ekaced reserves space for record but does not add
the record to the EK.
help, isnull
BOOLEAN = Scalar
the call:
cspice_ekacei, handle, segno, recno, column, nvals, $
ivals, isnull
adds 'nvals' of 'ivals' to column 'column' in segment 'segno',
record 'recno', of the EK file referred to by 'handle'.
None.
Any numerical results shown for these examples may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) This example demonstrates how to fetch integer values
from a column in three different cases: single values,
variable-size arrays and static-size arrays.
Create an EK that contains a table TAB that has the following
columns:
Column name Data Type Size
----------- --------- ----
INT_COL_1 INT 1
INT_COL_2 INT VARIABLE
INT_COL_3 INT 3
Issue the following query
query = 'SELECT INT_COL_1, INT_COL2, INT_COL3 FROM TAB'
to fetch and dump column values from the rows that satisfy the
query.
Example code begins here.
PRO ekacei_ex1
;;
;; Local parameters
;;
EKNAME = 'ekacei_ex1.bdb'
TABLE = 'TAB'
COL3SZ = 3
MXC2SZ = 4
NCOLS = 3
NROWS = 4
SPICEFALSE = 0B
;;
;; Local variables
;;
cnames = strarr( NCOLS )
cdecls = strarr( NCOLS )
col2 = lonarr( MXC2SZ )
col3 = lonarr( COL3SZ )
ivals = lonarr( MXC2SZ )
;;
;; Open a new EK file. For simplicity, we will not
;; reserve any space for the comment area, so the
;; number of reserved comment characters is zero.
;; The variable `ifname' is the internal file name.
;;
nresvc = 0
ifname = 'Test EK/Created 13-JUN-2019'
cspice_ekopn, EKNAME, ifname, nresvc, handle
;;
;; Set up the column names and declarations
;; for the TAB segment. We'll index all of
;; the columns.
;;
cnames[0] = 'INT_COL_1'
cdecls[0] = 'DATATYPE = INTEGER, INDEXED = TRUE'
cnames[1] = 'INT_COL_2'
cdecls[1] = 'DATATYPE = INTEGER, SIZE = VARIABLE, NULLS_OK = TRUE'
cnames[2] = 'INT_COL_3'
cdecls[2] = 'DATATYPE = INTEGER, SIZE = 3'
;;
;; Start the segment.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
;;
;; At the records to the table.
;;
for i=1, NROWS do begin
;;
;; Append a new record to the EK.
;;
cspice_ekappr, handle, segno, recno
;;
;; Add INT_COL_1
;;
col1 = [i * 100]
cspice_ekacei, handle, segno, recno, cnames[0], $
1, col1, SPICEFALSE
;;
;; Add `i' items to INT_COL_2
;;
for j=0, i-1L do begin
col2[j] = j + 1 + i*200
endfor
isnull = ( i eq 2 )
cspice_ekacei, handle, segno, recno, cnames[1], $
i, col2, isnull
;;
;; Add 3 items to INT_COL_3
;;
for j=0, 2 do begin
col3[j] = i + (j+1)*100
endfor
cspice_ekacei, handle, segno, recno, cnames[2], $
3, col3, SPICEFALSE
endfor
;;
;; Close the file.
;;
cspice_ekcls, handle
;;
;; Open the created file. Perform the query and show the
;; results.
;;
cspice_furnsh, EKNAME
query = 'SELECT INT_COL_1, INT_COL_2, INT_COL_3 FROM TAB'
;;
;; Query the EK system for data rows matching the
;; SELECT constraints.
;;
cspice_ekfind, query, nmrows, error, errmsg
;;
;; Check whether an error occurred while processing the
;; SELECT clause. If so, output the error message.
;;
if ( error ) then begin
print, 'SELECT clause error: ', errmsg
endif else begin
for row=0, nmrows-1L do begin
print, ' '
print, format='(A,I3)', 'ROW = ', row
;;
;; Fetch values from column `int_col_1'. Since
;; `int_col_1' was the first column selected, the
;; selection index `selidx' is set to 0.
;;
selidx = 0
eltidx = 0
cspice_ekgi, selidx, row, eltidx, ival, isnull, found
ivals[0] = ival
print, format='(A,$)', ' COLUMN = INT_COL_1: '
if ( isnull ) then begin
print, '<Null>'
endif else begin
print, format='(I6)', ivals[0]
endelse
;;
;; Fetch values from column `int_col_2' in the current
;; row. Since `int_col_2' contains variable-size array
;; elements, we call cspice_eknelt to determine how many
;; elements to fetch.
;;
selidx = 1
nelt = cspice_eknelt( selidx, row )
eltidx = 0
isnull = SPICEFALSE
while ( ( eltidx lt nelt ) && ( ~isnull ) ) do begin
cspice_ekgi, selidx, row, eltidx, ival, isnull, found
ivals[eltidx] = ival
eltidx = eltidx + 1
;;
;; If the column entry is null, we'll be kicked
;; out of this loop after the first iteration.
;;
endwhile
print, format='(A,$)', ' COLUMN = INT_COL_2: '
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0, nelt-1L do begin
print, format='(I6,$)', ivals[i]
endfor
print, ' '
endelse
;;
;; Fetch values from column `int_col_3' in the current
;; row. We need not call cspice_eknelt since we know how
;; many elements are in each column entry.
;;
selidx = 2
eltidx = 0
isnull = SPICEFALSE
while ( ( eltidx lt COL3SZ ) && ( ~isnull ) ) do begin
cspice_ekgi, selidx, row, eltidx, ival, isnull, found
ivals[eltidx] = ival
eltidx = eltidx + 1
endwhile
print, format='(A,$)', ' COLUMN = INT_COL_3: '
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0, COL3SZ-1L do begin
print, format='(I6,$)', ivals[i]
endfor
print, ' '
endelse
endfor
;;
;; We either parsed the SELECT clause or had an error.
;;
endelse
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
ROW = 0
COLUMN = INT_COL_1: 100
COLUMN = INT_COL_2: 201
COLUMN = INT_COL_3: 101 201 301
ROW = 1
COLUMN = INT_COL_1: 200
COLUMN = INT_COL_2: <Null>
COLUMN = INT_COL_3: 102 202 302
ROW = 2
COLUMN = INT_COL_1: 300
COLUMN = INT_COL_2: 601 602 603
COLUMN = INT_COL_3: 103 203 303
ROW = 3
COLUMN = INT_COL_1: 400
COLUMN = INT_COL_2: 801 802 803 804
COLUMN = INT_COL_3: 104 204 304
Note that after run completion, a new EK file exists in the
output directory.
2) Suppose we want to create an E-kernel which contains 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
This EK file will have one segment containing the DATAITEMS
table.
This example demonstrates how to open a new EK file; create
the segment described above and how to insert a new record
into it.
Example code begins here.
PRO ekacei_ex2
;;
;; Local parameters
;;
EKNAME = 'ekacei_ex2.bdb'
TABLE = 'DATAITEMS'
DESCLN = 80
NAMLEN = 40
NCOLS = 5
SPICEFALSE = 0B
;;
;; Local variables
;;
cnames = strarr( NCOLS )
cdecls = strarr( NCOLS )
;;
;; Open a new EK file. For simplicity, we will not
;; reserve any space for the comment area, so the
;; number of reserved comment characters is zero.
;; The variable `ifname' is the internal file name.
;;
nresvc = 0
ifname = 'Test EK;Created 21-JUN-2019'
cspice_ekopn, EKNAME, ifname, nresvc, handle
;;
;; Set up the table and column names and declarations
;; for the DATAITEMS segment. We'll index all of
;; the columns. All columns are scalar, so we omit
;; the size declaration.
;;
cnames[0] = 'ITEM_ID'
cdecls[0] = 'DATATYPE = INTEGER, INDEXED = TRUE'
cnames[1] = 'ORDER_ID'
cdecls[1] = 'DATATYPE = INTEGER, INDEXED = TRUE'
cnames[2] = 'ITEM_NAME'
cdecls[2] = 'DATATYPE = CHARACTER*(*), INDEXED = TRUE'
cnames[3] = 'DESCRIPTION'
cdecls[3] = 'DATATYPE = CHARACTER*(*), INDEXED = TRUE'
cnames[4] = 'PRICE'
cdecls[4] = 'DATATYPE = DOUBLE PRECISION, INDEXED = TRUE'
;;
;; Start the segment. Since we have no data for this
;; segment, start the segment by just defining the new
;; segment's schema.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
;;
;; Append a new, empty record to the DATAITEMS
;; table. Recall that the DATAITEMS table
;; is in segment number 0. The call will return
;; the number of the new, empty record.
;;
segno = 0
cspice_ekappr, handle, segno, 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 cspice_ekaceX (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 0.
;;
isnull = SPICEFALSE
esize = 0
;;
;; The following variables will contain the data for
;; the new record.
;;
ordid = [ 10011 ]
itemid = [ 531 ]
itemnm = [ 'Sample item' ]
descrp = [ 'This sample item is used only in tests.' ]
price = [ 1345.678d ]
;;
;; 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.
;;
cspice_ekacei, handle, segno, recno, 'ORDER_ID', esize, ordid, isnull
cspice_ekacei, handle, segno, recno, 'ITEM_ID', esize, itemid, isnull
cspice_ekacec, handle, segno, recno, 'ITEM_NAME', $
esize, NAMLEN, itemnm, isnull
cspice_ekacec, handle, segno, recno, 'DESCRIPTION', $
esize, DESCLN, descrp, isnull
cspice_ekaced, handle, segno, recno, 'PRICE', esize, price, isnull
;;
;; Close the file to make the update permanent.
;;
cspice_ekcls, handle
END
When this program is executed, no output is presented on
screen. After run completion, a new EK file exists in the
output directory.
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) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine.
2) If `segno' is out of range, an error is signaled by a routine in
the call tree of this routine.
3) If `column' is not the name of a declared column, an error
is signaled by a routine in the call tree of this routine.
4) If `column' specifies a column of whose data type is not
integer, the error SPICE(WRONGDATATYPE) is signaled by a
routine in the call tree of this routine.
5) If `recno' is out of range, an error is signaled by a routine in
the call tree of this routine.
6) If the specified column has fixed-size entries and `nvals' does
not match this size, an error is signaled by a routine in the
call tree of this routine.
7) If the specified column has variable-size entries and `nvals' is
non-positive, an error is signaled by a routine in the call
tree of this routine.
8) If an attempt is made to add a null value to a column that
doesn't take null values, an error is signaled by a routine in
the call tree of this routine.
9) If `column' specifies a column of whose class is not a
character class known to this routine, the error
SPICE(NOCLASS) is signaled by a routine in the call tree of
this routine.
10) If an i/o error occurs while reading or writing the indicated
file, the error is signaled by a routine in the call tree of
this routine.
11) If any of the input arguments, `handle', `segno', `recno',
`column', `nvals', `ivals' or `isnull', is undefined, an error
is signaled by the IDL error handling system.
12) If any of the input arguments, `handle', `segno', `recno',
`column', `nvals', `ivals' or `isnull', is not of the expected
type, or it does not have the expected dimensions and size, an
error is signaled by the Icy interface.
See the EK Required Reading ek.req for a discussion of the EK file
format.
None.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.2, 24-NOV-2021 (JDR)
Edited the -Examples section to comply with NAIF standard. Added
example's problem statement, a note after the example's
output and a second example.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.1, 23-FEB-2010 (EDW)
Correction to example code; corrected "cspice_ekrcei" argument
list.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
add integer data to EK column
add data to EK
write integer data to EK column
|