Table of contents
CSPICE_EKRCEC reads data from a character 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,
cvalen respectively, the number of allowed elements in the output
`cvals' array and the maximum length expected for any string
element in the array.
help, nvals
LONG = Scalar
help, cvalen
LONG = Scalar
Note, `nvals' and `cvalen' define the amount of memory for
`cvals' in the same manner as the C declaration:
cvals[nvals][cvalen]
the call:
cspice_ekrcec, handle, segno, recno, column, $
nvals, cvalen, cvals, isnull
returns:
cvals the set of string values found in the specified column entry.
help, cvals
STRING = 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 character column in a given record within the
file, and how to read the data from it.
Example code begins here.
PRO ekrcec_ex1
;;
;; Constants
;;
EKNAME = "ekrcec_ex1.bdb"
IFNAME = "Test EK/Enjoy"
NCOLS = 2
NROWS = 5
NRESVC = 0
TABLE = "CHR_DATA"
CVLEN = 10
MAXVAL = 10
cvals = strarr( 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 holds 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 CHR_DATA segment.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
;;
;; Define the column names and formats.
;;
cnames[0] = "CHR_COL_1"
cdecls[0] = "DATATYPE = CHARACTER*(*), " +$
"INDEXED = TRUE, NULLS_OK = TRUE"
cnames[1] = "CHR_COL_2"
cdecls[1] = "DATATYPE = CHARACTER*(9), " +$
"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.
;;
cvals[0] = string(i + 350)
;;
;; Add the data to the EK in column 1.
;;
cspice_ekacec, handle, segno, recno, cnames[0], 1, $
CVLEN, cvals, isnull
;;
;; Array-valued columns follow.
;;
cvals[0] = string( 10*i )
cvals[1] = string((10*i) + 1)
cvals[2] = string((10*i) + 2)
cvals[3] = string((10*i) + 3)
;;
;; Add the data to column 2.
;;
cspice_ekacec, handle, segno, recno, cnames[1], 4, $
CVLEN, cvals, isnull
endfor
;;
;; Close the file.
;;
cspice_ekcls, handle
;;
;; Open the created file. Show the values added.
;;
cspice_ekopr, EKNAME, handle
for i = 0, (NROWS-1) do begin
cspice_ekrcec, handle, segno, i, cnames[0], MAXVAL, $
CVLEN, cvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ',i
print, cvals
print
endif
;;
;; Array-valued columns follow.
;;
cspice_ekrcec, handle, segno, i, cnames[1], MAXVAL, $
CVLEN, cvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ',i
print, cvals
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: CHR_COL_1 record number: 0
350
Data from column: CHR_COL_2 record number: 0
0 1 2 3
Data from column: CHR_COL_1 record number: 2
352
Data from column: CHR_COL_2 record number: 2
20 21 22 23
Data from column: CHR_COL_1 record number: 3
353
Data from column: CHR_COL_2 record number: 3
30 31 32 33
Data from column: CHR_COL_1 record number: 4
354
Data from column: CHR_COL_2 record number: 4
40 41 42 43
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
character, 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 character
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 element of the column entry would be truncated when
assigned to an element of `cvals', an error is signaled by a
routine in the call tree of this routine.
10) If any of the input arguments, `handle', `segno', `recno',
`column', `nvals' or `cvalen', is undefined, an error is
signaled by the IDL error handling system.
11) If any of the input arguments, `handle', `segno', `recno',
`column', `nvals' or `cvalen', is not of the expected type, or
it does not have the expected dimensions and size, an error is
signaled by the Icy interface.
12) If any of the output arguments, `cvals' 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, 31-MAY-2021 (JDR)
Changed the input argument names "nelts" and "cvals_len" to
"nvals" and "cvalen" 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.0, 16-JUN-2003 (EDW)
read character data from EK column
|