Table of contents
CSPICE_EKBSEG starts/initializes a new segment in an EK file.
Given:
handle the scalar integer handle of an EK file open for write access.
help, handle
LONG = Scalar
tabnam the scalar string holding the table name for the current
segment, with the string no longer than SPICE_EK_TNAMSZ (see
SpiceEK.h).
help, tabnam
STRING = Scalar
ncols the scalar integer holding the count of columns in the new
segment; 'cnames' and 'decls' must have ncols members.
help, ncols
LONG = Scalar
cnames an array of strings with dimension no larger than
cnames[SPICE_EK_MXCLSG][SPICE_EK_CSTRLN]
i.e. no more than SPICE_EK_MXCLSG elements for array cnames,
with each string no longer than SPICE_EK_CSTRLN (see SpiceEK.h);
the array elements contain the table column names.
help, cnames
STRING = Array[SPICE_EK_MXCLSG]
no more than SPICE_EK_MXCLSG elements for array cnames, with
each string no longer than SPICE_EK_CSTRLN (see SpiceEK.h); the
array elements contain the table column names
decls an array of strings with the number of array elements no larger
than SPICE_EK_MXCLSG (see SpiceEK.h); the array elements contain
the type declarations for each column with the Ith element of
cnames and the Ith element of decls apply to the Ith column in
the segment.
help, decls
STRING = Array[SPICE_EK_MXCLSG]
Column names must start with a letter and contain only
characters from the set {A-Z,a-z,0-9,$,_}. Case is not
significant.
The declarations are strings that contain `keyword=value'
assignments that define the attributes of the columns to
which they apply.
the call:
cspice_ekbseg, handle, tabnam, ncols, cnames, decls, segno
returns:
segno the scalar integer value for the data segment targeted by the
data write.
help, segno
LONG = Scalar
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 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 ekbseg_ex1
;;
;; Local parameters
;;
EKNAME = 'ekbseg_ex1.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 prepares an EK for
the addition of a new segment. It is not necessary to take
any special action to "complete" a segment; segments are readable
after the completion of any record insertion, deletion, write,
or update operation.
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 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 MXCLSG, the error SPICE(INVALIDCOUNT) is signaled by a
routine in the call tree of this routine.
5) If any column name exceeds CNAMSZ characters in length, an
error is signaled by a routine in the call tree of this
routine.
6) If any column name contains non-printable characters, an error
is signaled by a routine in the call tree of this routine.
7) If a declaration cannot be understood by this routine, an
error is signaled by a routine in the call tree of this
routine.
8) 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.
9) 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.
10) If any of the input arguments, `handle', `tabnam', `ncols',
`cnames' or `decls', is undefined, an error is signaled by the
IDL error handling system.
11) If any of the input arguments, `handle', `tabnam', `ncols',
`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.
12) If the output argument `segno' 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.
None.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.1, 24-NOV-2021 (JDR)
Edited the -Examples section to comply with NAIF standard. Added
complete code 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)
start new E-kernel segment
start new EK segment
|