Table of contents
CSPICE_EKRCEI reads data from an integer column in a specified
segment of an EK file.
Given:
handle an EK file handle.
help, handle
LONG = Scalar
The file may be open for read or write access.
segno the index of the segment from which data is to be read.
help, segno
LONG = Scalar
recno the index of the record from which data is to be read.
help, recno
LONG = Scalar
This record number is relative to the start of the segment
indicated by `segno'; the first record in the segment has index
1.
column the name of the column from which data is to be read.
help, column
STRING = Scalar
nvals the number of allowed elements in the output `ivals' array.
help, nvals
LONG = Scalar
`ivals' returns with `nvals' elements or less.
the call:
cspice_ekrcei, handle, segno, recno, column, nvals, ivals, isnull
returns:
ivals the set of integer values found in the specified column entry.
help, ivals
LONG = Array[N]
isnull a logical flag indicating whether the returned column entry is
null.
help, isnull
BOOLEAN = 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) The following program demonstrates how to create a new EK and
add data to an integer column in a given record within the
file.
Example code begins here.
PRO ekrcei_ex1
;;
;; Constants
;;
EKNAME = 'ekrcei_ex1.bdb'
IFNAME = 'Test EK/Enjoy'
NCOLS = 2
NROWS = 5
NRESVC = 0
TABLE = 'SCALAR_DATA'
MAXVAL = 10
ivals = lonarr( MAXVAL )
;;
;; 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 constant IFNAME is the internal file name.
;;
if ( cspice_exists (EKNAME) ) then begin
file_delete, EKNAME
endif
;;
;; Create and open a new EK file.
;;
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.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
;;
;; Define the column names and formats.
;;
cnames[0] = 'INT_COL_1'
cdecls[0] = 'DATATYPE = INTEGER, INDEXED = TRUE, ' +$
'NULLS_OK = TRUE'
cnames[1] = 'INT_COL_2'
cdecls[1] = 'DATATYPE = INTEGER, SIZE = VARIABLE, '+$
'NULLS_OK = TRUE'
;;
;; Start the segment.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
;;
;; Loop over the number of rows, writing data to each column.
;;
for i = 0, (NROWS-1) do begin
;;
;; Set the null flag for i == 1.
;;
isnull = ( i EQ 1 );
;;
;; Append a new record to the EK.
;;
cspice_ekappr, handle, segno, recno
;;
;; Define the scalar.
;;
ivals[0] = long(i + 350)
;;
;; Add the data to the EK.
;;
cspice_ekacei, handle, segno, recno, cnames[0], $
1, ivals, isnull
;;
;; Array-valued columns follow.
;;
ivals[0] = long( 10*i)
ivals[1] = long((10*i)+1 )
ivals[2] = long((10*i)+2 )
;;
;; Add the data.
;;
cspice_ekacei, handle, segno, recno, cnames[1], $
3, ivals, isnull
endfor
;;
;; Close the file.
;;
cspice_ekcls, handle
;;
;; Open the created file. Show the values added.
;;
cspice_ekopr, EKNAME, handle
;;
;; Provide a maximum size for the return array 'dvals'.
;;
nvals = 20l
for i = 0, (NROWS-1) do begin
cspice_ekrcei, handle, segno, i, cnames[0], nvals, $
ivals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ',i
print, ivals
print
endif
;;
;; Array-valued columns follow.
;;
cspice_ekrcei, handle, segno, i, cnames[1], nvals, $
ivals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ',i
print, ivals
print
endif
endfor
;;
;; End the file.
;;
cspice_ekcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Data from column: INT_COL_1 record number: 0
350
Data from column: INT_COL_2 record number: 0
0 1 2
Data from column: INT_COL_1 record number: 2
352
Data from column: INT_COL_2 record number: 2
20 21 22
Data from column: INT_COL_1 record number: 3
353
Data from column: INT_COL_2 record number: 3
30 31 32
Data from column: INT_COL_1 record number: 4
354
Data from column: INT_COL_2 record number: 4
40 41 42
Note that the record 1 does not appear due to setting the
'isnull' flag to true for that record.
After run completion, a new EK exists in the output directory.
This routine is a utility that allows an EK file to be read
directly without using the high-level query interface.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine.
2) If `segno' is out of range, an error is signaled by a routine in
the call tree of this routine.
3) If `recno' is out of range, an error is signaled by a routine in
the call tree of this routine.
4) If `column' is not the name of a declared column, an error
is signaled by a routine in the call tree of this routine.
5) If `column' specifies a column of whose data type is not
integer, the error SPICE(WRONGDATATYPE) is signaled by a
routine in the call tree of this routine.
6) If `column' specifies a column of whose class is not an integer
class known to this routine, the error SPICE(NOCLASS) is
signaled by a routine in the call tree of this routine.
7) If an attempt is made to read an uninitialized column entry,
an error is signaled by a routine in the call tree of this
routine. A null entry is considered to be initialized, but
entries do not contain null values by default.
8) If an i/o error occurs while reading the indicated file, the
error is signaled by a routine in the call tree of this
routine.
9) If any of the input arguments, `handle', `segno', `recno',
`column' or `nvals', is undefined, an error is signaled by the
IDL error handling system.
10) If any of the input arguments, `handle', `segno', `recno',
`column' or `nvals', is not of the expected type, or it does
not have the expected dimensions and size, an error is
signaled by the Icy interface.
11) If any of the output arguments, `ivals' or `isnull', 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) EK files open for write access are not necessarily readable.
In particular, a column entry can be read only if it has been
initialized. The caller is responsible for determining
when it is safe to read from files open for write access.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.0, 10-AUG-2021 (JDR)
Changed output argument name "nelts" to "nvals" for consistency
with other routines.
Edited the header to comply with NAIF standard. Added example's
problem statement, and a note after the example's output.
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.1, 23-FEB-2010 (EDW)
Correction to -I/O section to document use of 'elts' argument.
Correction to example code; corrected "cspice_ekrcei" argument
list.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
read integer data from EK column
|