Table of contents
CSPICE_EKOPS creates and opens a scratch E-kernel file then
prepares the file for writing.
The call:
cspice_ekops, handle
returns:
handle the EK file handle of the file opened by this routine.
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) Suppose we want to create an E-kernel which contains a table
of items that have been ordered but we do not want to keep
the file. 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 example demonstrates how to open a scratch EK file;
create the segment described above, how to insert a new record
into it, and how to summarize its contents.
Example code begins here.
PRO ekops_ex1
;;
;; Local parameters
;;
TABLE = 'DATAITEMS'
DESCLN = 80L
;;
;; One value per row/column element.
;;
MAXVAL = 1L
NAMLEN = 40L
COLSLN = 5L
EKDTYP = [ 'CHR', 'DP', 'INT', 'TIME' ]
SPICEFALSE = 0B
SPICETRUE = 1B
;;
;; Define the EK data types.
;;
SPICE_CHR = 0
SPICE_DP = 1
SPICE_INT = 2
SPICE_TIME = 3
;;
;; Local variables
;;
cnames = strarr( COLSLN )
cdecls = strarr( COLSLN )
;;
;; Open a scratch EK file as we do not want to keep
;; the data.
;;
cspice_ekops, 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, COLSLN, cnames, cdecls, segno
;;
;; Append a new, empty record to the DATAITEMS
;; table. Recall that the DATAITEMS table
;; is in the first segment. The call will return
;; the number of the new, empty record.
;;
segno = 0L
cspice_ekappr, handle, segno, recno
;;
;; At this point, the new record is empty. 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 different 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 = 1L
;;
;; The following variables will contain the data for
;; the new record.
;;
ordid = [10011L]
itemid = [531L]
itemnm = ['Sample item']
descrp = ['This sample item is used only in tests.']
price = [1345.67d0]
;;
;; Note that the names of the routines called
;; correspond to the data types of the columns.
;;
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
;;
;; At this point, we could perform read operations
;; on the EK.
;;
;; Return the number of segments in the EK. Dump the
;; desired summary information for each one.
;;
nseg = cspice_eknseg( handle )
print, format='(A,I3)', 'Number of segments =', nseg
print
for segno=0L, nseg-1L do begin
cspice_ekssum, handle, segno, nrows, ncols, tabnam, cnames, $
cclass, dtypes, sizes, strlen, indexd, nullok
print, format='(2A)', 'Table containing segment: ', tabnam
print, format='(A,I2)', 'Number of rows : ', nrows
print, format='(A,I2)', 'Number of columns : ', ncols
print, format='(A)', 'Table data : '
for i=0L, ncols-1L do begin
print, format='(2A)', ' Column: ', cnames[i]
print, format='(2A)', ' Type : ', EKDTYP[ dtypes[i] ]
for recno=0L, nrows-1L do begin
if ( dtypes[i] eq SPICE_CHR ) then begin
cspice_ekrcec, handle, segno, recno, cnames[i], $
MAXVAL, NAMLEN, cvals, isnull
if ( isnull ) then begin
print, format='(A)', ' Data : <null>'
endif else begin
print, format='(2A)', ' Data : ', cvals
endelse
endif else if ( dtypes[i] eq SPICE_DP ) then begin
cspice_ekrced, handle, segno, recno, cnames[i], $
MAXVAL, dvals, isnull
if ( isnull ) then begin
print, format='(A)', ' Data : <null>'
endif else begin
print, format='(A,F9.2)', ' Data : ', dvals[0]
endelse
endif else if ( dtypes[i] eq SPICE_INT ) then begin
cspice_ekrcei, handle, segno, recno, cnames[i], $
MAXVAL, ivals, isnull
if ( isnull ) then begin
print, format='(A)', ' Data : <null>'
endif else begin
print, format='(A,I6)', ' Data : ', ivals[0]
endelse
endif
;;
;; There is no time data. Otherwise, we would need
;; to use a LSK and cspice_ekrced to read it
;; (internally, it is stored as double precision).
;;
print
endfor
endfor
print, '----------------------------------------'
endfor
;;
;; Close the file. This will delete the scratch file
;; and all the data will be lost.
;;
cspice_ekcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Number of segments = 1
Table containing segment: DATAITEMS
Number of rows : 1
Number of columns : 5
Table data :
Column: ITEM_ID
Type : INT
Data : 531
Column: ORDER_ID
Type : INT
Data : 10011
Column: ITEM_NAME
Type : CHR
Data : Sample item
Column: DESCRIPTION
Type : CHR
Data : This sample item is used only in tests.
Column: PRICE
Type : DP
Data : 1345.67
----------------------------------------
Note that after run completion, there is no EK file in the
output directory as scratch files are deleted when they are
closed or when the calling program terminates.
This routine operates by side effects: it opens and prepares
an EK for addition of data. "Scratch" files are automatically
deleted when closed using the Icy routine cspice_ekcls.
Note: An issue may exist when using EK scratch files from
IDL on Microsoft Windows. It seems the cspice_ekcls call may
fail to delete the scratch file created by the cspice_ekops
call. This file normally has a name format similar to
tmp.Fxxxxx. You can manually delete the file only after you
close the IDL application.
This problem does not affect use of the file or cause any
known instability to Icy.
1) 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.
2) 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.
3) If the output argument `handle' is not a named variable, an
error is signaled by the Icy interface.
This routine creates a temporary EK file; the file is deleted
when the calling program terminates or when the file is closed
using the Icy routine cspice_ekcls.
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
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.2, 17-APR-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.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added argument's type and size information in the -I/O section.
-Icy Version 1.0.1, 11-NOV-2005 (EDW)
Added mention of the scratch file retention issue on
Microsoft Windows.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
open scratch E-kernel
open scratch EK
|