Table of contents
CSPICE_EKRCED reads data from a double precision 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
0.
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 `dvals' array.
help, nvals
LONG = Scalar
`dvals' returns with `nvals' elements or less.
the call:
cspice_ekrced, handle, segno, recno, column, nvals, dvals, isnull
returns:
dvals the set of double precision values found in the specified column
entry.
help, dvals
DOUBLE = 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 a double precision column in a given record within
the file, and how to read the data from it.
Example code begins here.
PRO ekrced_ex1
;;
;; Constants
;;
EKNAME = 'ekrced_ex1.bdb'
IFNAME = 'Test EK/Enjoy'
NCOLS = 2
NROWS = 5
NRESVC = 0
TABLE = 'DP_DATA'
CVLEN = 81
MAXVAL = 10
dvals = dblarr( MAXVAL )
;;
;; Open a new EK file. For simplicity, we won't
;; reserve space for the comment area, so the
;; number of reserved comment characters is zero.
;; The constant IFNAME stores 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 DP_DATA segment. We'll index all of
;; the columns.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
;;
;; Define the column names and formats.
;;
cnames[0] = 'DP_COL_1'
cdecls[0] = 'DATATYPE = DOUBLE PRECISION, INDEXED = TRUE, ' +$
'NULLS_OK = TRUE'
cnames[1] = 'DP_COL_2'
cdecls[1] = 'DATATYPE = DOUBLE PRECISION, 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.
;;
dvals[0] = double(i + 350.d)
;;
;; Add the data to the EK in column 1.
;;
cspice_ekaced, handle, segno, recno, cnames[0], $
1, dvals, isnull
;;
;; Array-valued columns follow.
;;
dvals[0] = double( 10*i)
dvals[1] = double((10*i)+1 )
dvals[2] = double((10*i)+2 )
;;
;; Add the data to column 2.
;;
cspice_ekaced, handle, segno, recno, cnames[1], $
3, dvals, 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_ekrced, handle, segno, i, cnames[0], nvals, $
dvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ',i
print, dvals
print
endif
;;
;; Array-valued columns follow.
;;
cspice_ekrced, handle, segno, i, cnames[1], nvals, $
dvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ',i
print, dvals
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: DP_COL_1 record number: 0
350.00000
Data from column: DP_COL_2 record number: 0
0.0000000 1.0000000 2.0000000
Data from column: DP_COL_1 record number: 2
352.00000
Data from column: DP_COL_2 record number: 2
20.000000 21.000000 22.000000
Data from column: DP_COL_1 record number: 3
353.00000
Data from column: DP_COL_2 record number: 3
30.000000 31.000000 32.000000
Data from column: DP_COL_1 record number: 4
354.00000
Data from column: DP_COL_2 record number: 4
40.000000 41.000000 42.000000
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 double
precision, 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 a double
precision 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 or writing 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, `dvals' 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)
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 "nvals" argument.
Correction to example code; corrected "cspice_ekrced" argument
list.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
read double precision data from EK column
|