Table of contents
CSPICE_EKIFLD initializes a new EK segment so as to allow
fast writing.
Given:
handle the handle of an EK file open for write access.
help, handle
LONG = Scalar
A new segment is to be created in this file.
tabnam the name of the EK table to which the current segment belongs.
help, tabnam
STRING = Scalar
All segments in the EK file designated by `handle' must have
identical column attributes. `tabnam' must not exceed
SPICE_EK_TNAMSZ (64) characters in length. Case is not
significant. Table names must start with a letter and contain
only characters from the set {A-Z,a-z,0-9,$,_}.
ncols the number of columns in a new segment.
help, ncols
LONG = Scalar
nrows the number of rows in a new segment.
help, nrows
LONG = Scalar
Each column to be added to the segment must contain the number
of entries indicated by `nrows'.
cnames,
decls respectively, an array of column names and their corresponding
declarations: the ith element of `cnames' and the ith element of
`decls' apply to the ith column in the segment.
help, cnames
STRING = Array[ncols]
help, decls
STRING = Array[ncols]
Column names must not exceed SPICE_EK_CNAMSZ (32) characters in
length. Case is not significant. Column names must start
with a letter and contain only characters from the set
{A-Z,a-z,0-9,$,_}.
The declarations are strings that contain "keyword=value"
assignments that define the attributes of the columns to
which they apply. The column attributes that are defined
by a column declaration are:
DATATYPE
SIZE
<is the column indexed?>
<does the column allow null values?>
The form of a declaration is
'DATATYPE = <type>,
size = <size>,
indexed = <boolean>,
NULLS_OK = <boolean>'
For example, an indexed, scalar, integer column that
allows null values would have the declaration
'DATATYPE = LONG,
SIZE = 1,
INDEXED = TRUE,
NULLS_OK = TRUE'
Commas are required to separate the assignments within
declarations; white space is optional; case is not
significant.
The order in which the attribute keywords are listed in
declaration is not significant.
Every column in a segment must be declared.
Each column entry is effectively an array, each element
of which has the declared data type. The `size' keyword
indicates how many elements are in each entry of the
column in whose declaration the keyword appears. Note
that only scalar-valued columns (those for which `size' =
1) may be referenced in query constraints. A size
assignment has the syntax
'SIZE = <integer>'
or
'SIZE = VARIABLE'
The size value defaults to 1 if omitted.
The DATATYPE keyword defines the data type of column
entries. The DATATYPE assignment syntax has any of the
forms
'DATATYPE = CHARACTER*(<length>)'
'DATATYPE = CHARACTER*(*)'
'DATATYPE = DOUBLE'
'DATATYPE = LONG'
'DATATYPE = TIME'
As the datatype declaration syntax suggests, character
strings may have fixed or variable length.
Variable-length strings are allowed only in columns of
size 1.
Optionally, scalar-valued columns may be indexed. To
create an index for a column, use the assignment
'INDEXED = TRUE'
By default, columns are not indexed.
Optionally, any column can allow null values. To indicate
that a column may allow null values, use the assignment
'NULLS_OK = TRUE'
in the column declaration. By default, null values are
not allowed in column entries.
the call:
cspice_ekifld, handle, tabnam, ncols, nrows, $
cnames, decls, segno, rcptrs
returns:
segno the number of the segment created by this routine.
help, segno
LONG = Scalar
Segment numbers are used as unique identifiers by other EK
access routines.
rcptrs an array of record pointers for the input segment.
help, rcptrs
LONG = Array[nrows]
This array must not be modified by the caller.
The array `rcptrs' must be passed as an input to each
column addition routine called while writing the
specified segment.
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 'ekifld_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 'ekifld_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 ekifld_ex1
;;
;; Initialize needed parameters.
;;
SPICEFALSE = 0B
SPICETRUE = 1B
EKNAME = 'ekifld_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 = lonarr( 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 prepares an EK for the creation of a new segment via
the fast column writer routines. After this routine is called,
the columns of the segment are filled in by calls to the fast
column writer routines of the appropriate data types. The fast
column writer routines are:
cspice_ekaclc {EK, add column, character}
cspice_ekacld {EK, add column, double precision}
cspice_ekacli {EK, add column, integer}
When all of the columns have been added, the write operation is
completed by a call to cspice_ekffld {EK, finish fast write},
therefore, an EK initialized with cspice_ekifld must end the segment
write with cspice_ekffld before closing the EK with a
cspice_ekcls call.
The segment is not valid until cspice_ekffld has been called.
The EK system supports only one fast write at a time. It is
not possible use the fast write routines to simultaneously write
multiple segments, either in the same EK file or in different
files.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine.
2) If `tabnam' is more than SPICE_EK_TNAMSZ characters long, an error
is signaled by a routine in the call tree of this routine.
3) If `tabnam' contains any nonprintable characters, an error
is signaled by a routine in the call tree of this routine.
4) If `ncols' is non-positive or greater than the maximum allowed
number SPICE_EK_MXCLSG, an error is signaled by a routine in the call
tree of this routine.
5) If `nrows' is non-positive, the error SPICE(INVALIDCOUNT)
is signaled by a routine in the call tree of this routine.
6) If any column name exceeds SPICE_EK_CNAMSZ characters in length, an
error is signaled by a routine in the call tree of this
routine.
7) If any column name contains non-printable characters, an error
is signaled by a routine in the call tree of this routine.
8) If a declaration cannot be understood by this routine, an
error is signaled by a routine in the call tree of this
routine.
9) If an non-positive string length or element size is specified,
an error 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', `tabnam', `ncols',
`nrows', `cnames' or `decls', is undefined, an error is
signaled by the IDL error handling system.
12) If any of the input arguments, `handle', `tabnam', `ncols',
`nrows', `cnames' or `decls', is not of the expected type, or
it does not have the expected dimensions and size, an error is
signaled by the Icy interface.
13) If any of the output arguments, `segno' or `rcptrs', is not a
named variable, 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.1, 17-JUN-2021 (JDR)
Edited header to comply with NAIF standard.
Added -Parameters, -Particulars, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
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)
start new E-kernel segment for fast writing
start new EK segment for fast writing
|