Table of contents
CSPICE_EKACLC adds a column of character data to an EK
segment.
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
column the scalar string naming the target column for the data stored
in `cvals'.
help, column
STRING = Scalar
vallen a scalar integer describing the maximum size for the individual
`cvals' elements.
help, vallen
LONG = Scalar
cvals an array of strings, listed in row order, containing the data to
add to the EK referred to by `handle'.
help, cvals
STRING = Array[N]
entszs an array of integers containing the sizes of column entries -
used only for columns possessing variable size entries; the ith
element of `entszs' corresponds to the size of the ith entry of
`cvals'.
help, entszs
LONG = Array[N]
nlflgs an array of booleans indicating whether the corresponding
`cvals' has a null value, with the ith entry of `nlflgs'
corresponding to the ith entry of `cvals'.
help, nlflgs
BOOLEAN = Array[N]
rcptrs an integer array of record pointers, returned from
cspice_ekifld, for the input segment.
help, rcptrs
LONG = Array[N]
wkindx a read/write array of integers, used as a workspace when
building an column index.
help, wkindx
LONG = Array[N]
As this array functions as read/write, the calling routine must
declare an appropriate size of NROWS (the number of rows in the
column).
the call:
cspice_ekaclc, handle, segno, column, vallen, $
cvals, entszs, nlflgs, rcptrs, wkindx
writes the `cvals' data to `column' in segment `segno' of the
EK referred to by `handle'.
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Suppose we want to create an Sequence Component E-kernel
named 'ekaclc_ex1.bdb' 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
The file 'ekaclc_ex1.bdb' will contain 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 and create
the first of the segments described above.
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
PRO ekaclc_ex1
;;
;; Initialize needed parameters.
;;
SPICEFALSE = 0B
SPICETRUE = 1B
EKNAME = 'ekaclc_ex1.bdb'
FNMLEN = 50
IFNAME = 'Test EK'
LNMLEN = 50
LSK = 'naif0012.tls'
NCOLS = 6
NRESVC = 0
NROWS = 9
TABLE = 'DATAORDERS'
;;
;; Load a leapseconds kernel for UTC/ET conversion.
;;
cspice_furnsh, LSK
;;
;; 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 is the internal file name.
;;
cspice_ekopn, EKNAME, IFNAME, NRESVC, handle
cnames = strarr( NCOLS )
cdecls = strarr( NCOLS )
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
;;
;;
;; The null flags 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.
;;
;; Fill in data arrays and null flag arrays here. This code
;; section would normally be replaced by calls to user functions
;; returning column values.
;;
ordids = lonarr( NROWS)
cstids = lonarr( NROWS)
costs = dblarr( NROWS)
ets = dblarr( NROWS)
fnames = strarr( NROWS)
lnames = strarr( NROWS)
nlflgs = bytarr( NROWS)
wkindx = lonarr( NROWS)
sizes = lonarr( NROWS)
for i = 0, (NROWS-1) do begin
ordids[i] = i
cstids[i] = i*100
costs [i] = double(100*i)
fnames[i] = 'Order ' + string(i) + ' Customer first name'
lnames[i] = 'Order ' + string(i) + ' Customer last name'
date_string = '2001 Mar ' + string(i)
cspice_utc2et, date_string, 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.
;;
;; 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 ekifld_c.
;;
cspice_ekffld, handle, segno, rcptrs
;;
;; The file must be closed by a call to cspice_ekcls
;;
cspice_ekcls, handle
cspice_unload, LSK
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 column. This routine
writes the entire contents of the specified column in one shot.
This routine creates columns much more efficiently than can be
done by sequential calls to cspice_ekacec, but has the drawback that
the caller must use more memory for the routine's inputs. This
routine cannot be used to add data to a partially completed
column.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine.
2) If `column' is not the name of a declared column, an error is
signaled by a routine in the call tree of this routine.
3) 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.
4) If the specified column already contains ANY entries, an error
is signaled by a routine in the call tree of this routine.
5) 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.
6) If any of the input arguments, `handle', `segno', `column',
`vallen', `cvals', `entszs', `nlflgs', `rcptrs' or `wkindx',
is undefined, an error is signaled by the IDL error handling
system.
7) If any of the input arguments, `handle', `segno', `column',
`vallen', `cvals', `entszs', `nlflgs', `rcptrs' or `wkindx',
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.
1) Only one segment can be created at a time using the fast
write routines.
2) No other EK operation may interrupt a fast write. For
example, it is not valid to issue a query while a fast write
is in progress.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.2, 27-AUG-2021 (JDR)
Edited the header to comply with NAIF standard.
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, 27-FEB-2007 (EDW)
Removed unneeded variable assignment and unneeded cspice_unload call
in example section.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
write entire character column to EK segment
|