Table of contents
CSPICE_EKACEC adds data to a character 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 `cvals' to add to the new
record.
help, nvals
LONG = Scalar
cvalen a scalar integer defining the length of the strings in the
`cvals' array.
help, cvalen
LONG = Scalar
cvals an array of strings containing the data values to add to the new
record in `column'.
help, cvals
STRING = Array[N]
Note: `nvals' specifies the number of `cvals'
entries written to the new record.
isnull a scalar boolean flagging whether the entry is null, if
equal to True, cspice_ekacec reserves space for
record but does not add the record to the EK
the call:
cspice_ekacec, handle, segno, recno, column, $
nvals, cvalen, cvals, isnull
adds `nvals' of the `cvals' array to column `column' in segment `segno',
record `recno', of the EK file referred to by `handle'.
help, isnull
BOOLEAN = Scalar
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) The following program demonstrates how to create a new EK and
add data to a character column in a given record within the
file, and how to read the data from it.
Example code begins here.
PRO ekacec_ex1
;;
;; Constants
;;
EKNAME = "ekacec_ex1.bdb"
IFNAME = "Test EK/Enjoy"
NCOLS = 2
NROWS = 5
NRESVC = 0
TABLE = "CHR_DATA"
CVLEN = 10
MAXVAL = 10
cvals = strarr( MAXVAL )
;;
;; Open a new EK file. For simplicity, we won't
;; reserve space for the comment area, so the
;; number of reserved comment characters is zero.
;; The constant IFNAME holds the internal file name.
;;
if ( cspice_exists (EKNAME) ) then begin
file_delete, EKNAME
endif
;;
;; Create and open a new EK file.
;;
cspice_ekopn, EKNAME, IFNAME, NRESVC, handle
;;
;; Set up the table and column names and declarations
;; for the CHR_DATA segment.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
;;
;; Define the column names and formats.
;;
cnames[0] = "CHR_COL_1"
cdecls[0] = "DATATYPE = CHARACTER*(*), " + $
"INDEXED = TRUE, NULLS_OK = TRUE"
cnames[1] = "CHR_COL_2"
cdecls[1] = "DATATYPE = CHARACTER*(9), " + $
"SIZE = VARIABLE, NULLS_OK = TRUE"
;;
;; Start the segment.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
;;
;; Loop over the number of rows, writing data to each column.
;;
for i = 0, (NROWS-1) do begin
;;
;; Set the null flag for i == 1.
;;
isnull = ( i EQ 1 );
;;
;; Append a new record to the EK.
;;
cspice_ekappr, handle, segno, recno
;;
;; Define the scalar.
;;
cvals[0] = string(i + 350)
;;
;; Add the data to the EK in column 1.
;;
cspice_ekacec, handle, segno, recno, cnames[0], 1, $
CVLEN, cvals, isnull
;;
;; Array-valued columns follow.
;;
cvals[0] = string( 10*i )
cvals[1] = string((10*i) + 1)
cvals[2] = string((10*i) + 2)
cvals[3] = string((10*i) + 3)
;;
;; Add the data to column 2.
;;
cspice_ekacec, handle, segno, recno, cnames[1], 4, $
CVLEN, cvals, isnull
endfor
;;
;; Close the file.
;;
cspice_ekcls, handle
;;
;; Open the created file. Show the values added.
;;
cspice_ekopr, EKNAME, handle
for i = 0, (NROWS-1) do begin
cspice_ekrcec, handle, segno, i, cnames[0], MAXVAL, $
CVLEN, cvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ', i
print, cvals
print
endif
;;
;; Array-valued columns follow.
;;
cspice_ekrcec, handle, segno, i, cnames[1], MAXVAL, $
CVLEN, cvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ', i
print, cvals
print
endif
endfor
;;
;; End the file.
;;
cspice_ekcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Data from column: CHR_COL_1 record number: 0
350
Data from column: CHR_COL_2 record number: 0
0 1 2 3
Data from column: CHR_COL_1 record number: 2
352
Data from column: CHR_COL_2 record number: 2
20 21 22 23
Data from column: CHR_COL_1 record number: 3
353
Data from column: CHR_COL_2 record number: 3
30 31 32 33
Data from column: CHR_COL_1 record number: 4
354
Data from column: CHR_COL_2 record number: 4
40 41 42 43
Note that the record 1 does not appear due to setting the
`isnull' flag to true for that record. After run completion, a
new EK exists in the output directory.
2) A more detailed example.
Suppose we have an E-kernel 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 EK file contains two segments, the
first containing the DATAORDERS table and the second
containing the DATAITEMS table.
This example demonstrates how to open a new EK file; create
the two segments described above, using fast writers; and
how to insert a new record into one of the tables.
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
PRO ekacec_ex2
;;
;; Local parameters
;;
EKNAME = 'ekacec_ex2.bdb'
TABLE = 'DATAORDERS'
DESCLN = 81
FNMLEN = 51
LNMLEN = 51
NAMLEN = 41
NCOLS = 6
NROWS = 9
SPICEFALSE = 0B
SPICETRUE = 1B
;;
;; Local variables
;;
cnames = strarr( NCOLS )
cdecls = strarr( NCOLS )
fnames = strarr( NROWS )
lnames = strarr( NROWS )
cstids = lonarr( NROWS )
nlflgs = lonarr( NROWS )
ordids = lonarr( NROWS )
sizes = lonarr( NROWS )
wkindx = lonarr( NROWS )
costs = dblarr( NROWS )
ets = dblarr( NROWS )
;;
;; Load a leapseconds kernel for UTC/ET conversion.
;;
cspice_furnsh, 'naif0012.tls'
;;
;; 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 01-JUN-2019'
cspice_ekopn, EKNAME, ifname, nresvc, handle
;;
;; Set up the table and column names and declarations
;; for the DATAORDERS segment. We'll index all of
;; the columns. All columns are scalar, so we omit
;; the size declaration. Only the COST column may take
;; null values.
;;
cnames[0] = 'ORDER_ID'
cdecls[0] = 'DATATYPE = INTEGER, INDEXED = TRUE'
cnames[1] = 'CUSTOMER_ID'
cdecls[1] = 'DATATYPE = INTEGER, INDEXED = TRUE'
cnames[2] = 'LAST_NAME'
cdecls[2] = 'DATATYPE = CHARACTER*(*), INDEXED = TRUE'
cnames[3] = 'FIRST_NAME'
cdecls[3] = 'DATATYPE = CHARACTER*(*), INDEXED = TRUE'
cnames[4] = 'ORDER_DATE'
cdecls[4] = 'DATATYPE = TIME, INDEXED = TRUE'
cnames[5] = 'COST'
cdecls[5] = 'DATATYPE = DOUBLE PRECISION, ' + $
'INDEXED = TRUE, NULLS_OK = TRUE'
;;
;; Start the segment. We presume the number of rows
;; of data is known in advance.
;;
cspice_ekifld, handle, TABLE, NCOLS, NROWS, $
cnames, cdecls, segno, rcptrs
;;
;; At this point, arrays containing data for the
;; segment's columns may be filled in. The names
;; of the data arrays are shown below.
;;
;; Column Data array
;;
;; 'ORDER_ID' ordids
;; 'CUSTOMER_ID' cstids
;; 'LAST_NAME' lnames
;; 'FIRST_NAME' fnames
;; 'ORDER_DATE' ets
;; 'COST' costs
;;
for i=0, NROWS - 1L do begin
id = i + 1
ordids[i] = id
cstids[i] = id * 100
costs[i] = id * 100.0d
fnames[i] = STRING( format='(%"Order %d Customer first name")', $
id )
lnames[i] = STRING( format='(%"Order %d Customer last name")', $
id )
odate = STRING( format='(%"1998 Mar %d")', id )
cspice_utc2et, odate, et
ets[i] = et
nlflgs[i] = SPICEFALSE
endfor
nlflgs[1] = SPICETRUE
;;
;; The `sizes' array shown below is ignored for scalar
;; and fixed-size array columns, so we need not
;; initialize it. For variable-size arrays, the
;; ith element of the `sizes' array must contain the size
;; of the ith column entry in the column being written.
;; Normally, the `sizes' array would be reset for each
;; variable-size column.
;;
;; The `nlflgs' array indicates which entries are null.
;; It is ignored for columns that don't allow null
;; values. In this case, only the COST column allows
;; nulls.
;;
;; Add the columns of data to the segment. All of the
;; data for each column is written in one shot.
;;
cspice_ekacli, handle, segno, 'ORDER_ID', ordids, $
sizes, nlflgs, rcptrs, wkindx
cspice_ekacli, handle, segno, 'CUSTOMER_ID', cstids, $
sizes, nlflgs, rcptrs, wkindx
cspice_ekaclc, handle, segno, 'LAST_NAME', LNMLEN, $
lnames, sizes, nlflgs, rcptrs, wkindx
cspice_ekaclc, handle, segno, 'FIRST_NAME', FNMLEN, $
fnames, sizes, nlflgs, rcptrs, wkindx
cspice_ekacld, handle, segno, 'ORDER_DATE', ets, $
sizes, nlflgs, rcptrs, wkindx
cspice_ekacld, handle, segno, 'COST', costs, $
sizes, nlflgs, rcptrs, wkindx
;;
;; Complete the segment. The `rcptrs' array is that
;; returned by cspice_ekifld.
;;
cspice_ekffld, handle, segno, rcptrs
;;
;; At this point, the second segment could be
;; created by an analogous process. In fact, the
;; second segment could be created at any time; it is
;; not necessary to populate the first segment with
;; data before starting the second segment.
;;
;; 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 new segment. Since we have no data for this
;; segment, start the segment by just defining the new
;; segment's schema.
;;
cspice_ekbseg, handle, 'DATAITEMS', 5, cnames, cdecls, segno
;;
;; Close the file by a call to cspice_ekcls.
;;
cspice_ekcls, handle
;;
;; Now, we want to insert a new record into the DATAITEMS
;; table.
;;
;; Open the database for write access. This call is
;; made when the file already exists.
;;
cspice_ekopw, EKNAME, handle
;;
;; Append a new, empty record to the DATAITEMS
;; table. Recall that the DATAITEMS table
;; is in segment number 1. The call will return
;; the number of the new, empty record.
;;
segno = 1
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 1.
;;
isnull = SPICEFALSE
esize = 1
;;
;; 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
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
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
character, 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', `cvalen', `cvals' 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', `cvalen', `cvals' 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.1.0, 10-AUG-2021 (JDR)
Changed the input argument name "cvals_len" to "cvalen" for
consistency with other routines.
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.0, 16-JUN-2003 (EDW)
add character data to EK column
add data to EK
write character data to EK column
|