Table of contents
CSPICE_EKACED adds data to a double precision 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 'dvals' to add to the new
record.
help, nvals
LONG = Scalar
dvals an array of double precision values containing the
data values to add to the new record in 'column'/
Note: 'nvals' specifies the number of 'dvals'
entries written to the new record.
help, dvals
DOUBLE = Array[N]
isnull a scalar boolean flagging whether the entry is null, if equal to
SPICETRUE, cspice_ekaced reserves space for record but does not
add the record to the EK.
help, isnull
BOOLEAN = Scalar
the call:
cspice_ekaced, handle, segno, recno, column, nvals, $
dvals, isnull
adds 'nvals' of the 'dvals' array 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 add double precision values
to 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
----------- --------- ----
DP_COL_1 DP 1
DP_COL_2 DP VARIABLE
DP_COL_3 DP 3
Issue the following query
query = 'SELECT DP_COL_1, DP_COL_2, DP_COL_3 FROM TAB'
to fetch and dump column values from the rows that satisfy the
query.
Example code begins here.
PRO ekaced_ex1
;;
;; Local parameters
;;
EKNAME = 'ekaced_ex1.bdb'
TABLE = 'TAB'
COL3SZ = 3
MXC2SZ = 4
NCOLS = 3
NROWS = 4
SPICEFALSE = 0B
;;
;; Local variables
;;
cnames = strarr( NCOLS )
cdecls = strarr( NCOLS )
col2 = dblarr( MXC2SZ )
col3 = dblarr( COL3SZ )
dvals = dblarr( 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] = 'DP_COL_1'
cdecls[0] = 'DATATYPE = DOUBLE PRECISION, INDEXED = TRUE'
cnames[1] = 'DP_COL_2'
cdecls[1] = 'DATATYPE = DOUBLE PRECISION, SIZE = VARIABLE, ' + $
'NULLS_OK = TRUE'
cnames[2] = 'DP_COL_3'
cdecls[2] = 'DATATYPE = DOUBLE PRECISION, 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 DP_COL_1
;;
col1 = [i * 100.0d]
cspice_ekaced, handle, segno, recno, cnames[0], $
1, col1, SPICEFALSE
;;
;; Add `i' items to DP_COL_2
;;
for j=0, i-1L do begin
col2[j] = j + 1 + i*200.0d
endfor
isnull = ( i eq 2 )
cspice_ekaced, handle, segno, recno, cnames[1], $
i, col2, isnull
;;
;; Add 3 items to DP_COL_3
;;
for j=0, 2 do begin
col3[j] = i + (j+1)*100.0d
endfor
cspice_ekaced, 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 DP_COL_1, DP_COL_2, DP_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 `dp_col_1'. Since
;; `dp_col_1' was the first column selected, the
;; selection index `selidx' is set to 0.
;;
selidx = 0
eltidx = 0
cspice_ekgd, selidx, row, eltidx, ddata, isnull, found
dvals[0] = ddata
print, format='(A,$)', ' COLUMN = DP_COL_1: '
if ( isnull ) then begin
print, '<Null>'
endif else begin
print, dvals[0]
endelse
;;
;; Fetch values from column `dp_col_2' in the current
;; row. Since `dp_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_ekgd, selidx, row, eltidx, ddata, isnull, found
dvals[eltidx] = ddata
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 = DP_COL_2: '
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0, nelt-1L do begin
print, format='(F6.1,$)', dvals[i]
endfor
print, ' '
endelse
;;
;; Fetch values from column `dp_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_ekgd, selidx, row, eltidx, ddata, isnull, found
dvals[eltidx] = ddata
eltidx = eltidx + 1
endwhile
print, format='(A,$)', ' COLUMN = DP_COL_3: '
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0, COL3SZ-1L do begin
print, format='(F6.1,$)', dvals[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 = DP_COL_1: 100.00000
COLUMN = DP_COL_2: 201.0
COLUMN = DP_COL_3: 101.0 201.0 301.0
ROW = 1
COLUMN = DP_COL_1: 200.00000
COLUMN = DP_COL_2: <Null>
COLUMN = DP_COL_3: 102.0 202.0 302.0
ROW = 2
COLUMN = DP_COL_1: 300.00000
COLUMN = DP_COL_2: 601.0 602.0 603.0
COLUMN = DP_COL_3: 103.0 203.0 303.0
ROW = 3
COLUMN = DP_COL_1: 400.00000
COLUMN = DP_COL_2: 801.0 802.0 803.0 804.0
COLUMN = DP_COL_3: 104.0 204.0 304.0
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 ekaced_ex2
;;
;; Local parameters
;;
EKNAME = 'ekaced_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 double
precision, 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', `dvals' 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', `dvals' 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_ekrced" argument
list.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
add double precision data to EK column
add data to EK
write double precision data to EK column
|