Table of contents
CSPICE_EKAPPR appends a new, empty record at the end of a specified
EK segment.
Given:
handle a file handle of an EK open for write access.
help, handle
LONG = Scalar
segno the number of the segment to which the record is to be added.
help, segno
LONG = Scalar
the call:
cspice_ekappr, handle, segno, recno
returns:
recno the number of the record appended by this routine.
help, recno
LONG = Scalar
`recno' is used to identify the record when writing column
entries to it.
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) Append a record to a specified segment.
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 creates such EK, with no records in either
table, and after re-opening the file, inserts a new record
into the DATAITEMS table.
Example code begins here.
PRO ekappr_ex1
;;
;; Local parameters
;;
EKNAME = 'ekappr_ex1.bdb'
DESCLN = 81
NAMLEN = 41
NCOLS = 6
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 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 first segment. Since we have no data for this
;; segment, start the segment by just defining the new
;; segment's schema.
;;
cspice_ekbseg, handle, 'DATAORDERS', NCOLS, cnames, cdecls, segno
;;
;; 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
;;
;; End 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
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 appends a new, empty
record structure to an EK segment. The ordinal position of the
new record is one greater than the previous number of records in
in the segment.
After a new record has been appended to a segment by this routine,
the record must be populated with data using the cspice_ekaceX
routines. EKs are valid only when all of their column entries
are initialized.
To insert a record into a segment at a specified ordinal position,
use the routine cspice_ekappr.
This routine cannot be used with the "fast write" suite of
routines. See the EK Required Reading for a discussion of the
fast writers.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine. The file will not be modified.
2) If `segno' is out of range, the error SPICE(INVALIDINDEX) is
signaled by a routine in the call tree of this routine. The
file will not be modified.
3) 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. The file may be corrupted.
4) If any of the input arguments, `handle' or `segno', is
undefined, an error is signaled by the IDL error handling
system.
5) If any of the input arguments, `handle' or `segno', is not of
the expected type, or it does not have the expected dimensions
and size, an error is signaled by the Icy interface.
6) If the output argument `recno' 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 header 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)
append record to EK segment
|