Table of contents
CSPICE_EKOPN creates, then opens a new E-kernel file and
prepares the file for writing.
Given:
fname the name of a new E-kernel file to be created.
help, fname
STRING = Scalar
ifname the internal file name of a new E-kernel.
help, ifname
STRING = Scalar
The internal file name may be up to 60 characters in length.
ncomch the amount of space, measured in characters, to be allocated in
the comment area when the new EK file is created.
help, ncomch
LONG = Scalar
It is not necessary to allocate space in advance in order to
add comments, but doing so may greatly increase the efficiency
with which comments may be added. Making room for comments after
data has already been added to the file involves moving the
data, and thus is slower.
`ncomch' must be greater than or equal to zero.
the call:
cspice_ekopn, fname, ifname, ncomch, handle
returns:
handle the EK handle of the file designated by `fname'.
help, handle
LONG = Scalar
This handle is used to identify the file to other EK routines.
SPICE_DAS_FTSIZE
is the maximum number of DAS files that a user can
have open simultaneously. This includes any files used
by the DAS system.
See the parameter definitions file IcyDAS.pro for the actual
value of this parameter.
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) This example demonstrates how to open a new EK file, creating
the two segments described below, without any records.
The EK file will contain two segments, the first containing
the DATAORDERS table and the second containing the DATAITEMS
table.
The E-kernel DATAORDERS table called 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 columns of the DATAITEMS table are shown below:
DATAITEMS
Column Name Data Type
----------- ---------
ITEM_ID INTEGER
ORDER_ID INTEGER
ITEM_NAME CHARACTER*(*)
DESCRIPTION CHARACTER*(*)
PRICE DOUBLE PRECISION
Note that it is not necessary to populate the first segment
with data before starting the second segment, or before
closing the EK.
Example code begins here.
PRO ekopn_ex1
;;
;; Local parameters
;;
EKNAME = 'ekopn_ex1.bdb'
NCOLS = 6
;;
;; 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
;;
;; Close the file by a call to cspice_ekcls.
;;
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 opens and prepares
an EK for addition of data.
1) If `ncomch' is less than zero, the error SPICE(INVALIDCOUNT) is
signaled by a routine in the call tree of this routine. No
file will be created.
2) If `ifname' is invalid, an error is signaled by a routine in the
call tree of this routine.
3) If the indicated file cannot be opened, an error is signaled
by a routine in the call tree of this routine. The new file
will be deleted.
4) 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.
5) If any of the input arguments, `fname', `ifname' or `ncomch',
is undefined, an error is signaled by the IDL error handling
system.
6) If any of the input arguments, `fname', `ifname' or `ncomch',
is not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
7) If the output argument `handle' 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) No more than SPICE_DAS_FTSIZE DAS files may be opened simultaneously.
See the parameter definitions file IcyDAS.pro for the value of
SPICE_DAS_FTSIZE.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.3, 31-MAY-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.2, 19-JAN-2009 (EDW)
Edits to header text and spelling correction.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
open new E-kernel
open new EK
|