Table of contents
CSPICE_EKNELT returns an integer value of the number of elements
in the specified row in a specified column.
Given:
selidx the SELECT clause index of the column to fetch from.
help, selidx
LONG = Scalar
row the index of the row containing the element.
help, row
LONG = Scalar
This number refers to a member of the set of rows matching a
query. `row' must be in the range
0:nmrows-1
where `nmrows' is the matching row count returned
by cspice_ekfind.
the call:
eknelt = cspice_eknelt( selidx, row )
returns:
eknelt the number of elements in the column entry belonging to the
specified column in the current row.
help, eknelt
LONG = Scalar
Null entries in variable-size columns are considered to have
size 1.
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) This example demonstrates how to fetch integer, double
precision and character string values from a column when such
column corresponds to either a variable-size array or to a
static-size array.
Create an EK that contains a table TAB that has the following
columns:
Column name Data Type Size
----------- --------- ----
IARRAY INT 3
DARRAY DP VARIABLE
CARRAY CHR VARIABLE
Issue the following query
query = 'SELECT IARRAY, DARRAY, CARRAY FROM TAB'
to fetch and dump column values from the rows that satisfy the
query.
Example code begins here.
PRO eknelt_ex1
;;
;; Local parameters
;;
EKNAME = 'eknelt_ex1.bdb'
TABLE = 'TAB'
CHRSLN = 6
COL1SZ = 3
MXC2SZ = 4
MXC3SZ = 7
NCOLS = 3
NROWS = 4
STRSIZ = 31
SPICEFALSE = 0L
;;
;; Local variables
;;
cnames = strarr( NCOLS )
cdecls = strarr( NCOLS )
col3 = strarr( MXC3SZ )
cvals = strarr( MXC3SZ )
col1 = lonarr( COL1SZ )
ivals = lonarr( COL1SZ )
col2 = dblarr( MXC2SZ )
dvals = dblarr( MXC2SZ )
;;
;; 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 13-JUN-2019'
cspice_ekopn, EKNAME, ifname, nresvc, handle
;;
;; Set up the column names and declarations
;; for the TAB segment. We'll index all of
;; the columns.
;;
cnames[0] = 'IARRAY'
cdecls[0] = 'DATATYPE = INTEGER, SIZE = 3'
cnames[1] = 'DARRAY'
cdecls[1] = 'DATATYPE = DOUBLE PRECISION, SIZE = VARIABLE'
cnames[2] = 'CARRAY'
cdecls[2] = 'DATATYPE = CHARACTER*(5), SIZE = VARIABLE'
;;
;; Start the segment.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
;;
;; At the records to the table.
;;
for i=0, NROWS-1L do begin
;;
;; Append a new record to the EK.
;;
cspice_ekappr, handle, segno, recno
;;
;; Add 3 items to IARRAY
;;
for j=0, COL1SZ - 1L do begin
col1[j] = i+1 + (j+1)*100
endfor
cspice_ekacei, handle, segno, recno, cnames[0], $
COL1SZ, col1, SPICEFALSE
;;
;; Add i+1 items to DARRAY
;;
for j=0, i do begin
col2[j] = j+1 + (i+1)*200.0d
endfor
cspice_ekaced, handle, segno, recno, cnames[1], $
i+1, col2, SPICEFALSE
;;
;; Add 4+i items to CARRAY
;;
for j=0, 3+i do begin
col3[j] = STRING( format='(%"ST%d")', j+1 + (i+1)*100 )
endfor
cspice_ekacec, handle, segno, recno, cnames[2], $
i+4, CHRSLN, col3, SPICEFALSE
endfor
;;
;; Close the file.
;;
cspice_ekcls, handle
;;
;; Open the created file. Perform the query and show the
;; results.
;;
cspice_furnsh, EKNAME
query = 'SELECT IARRAY, DARRAY, CARRAY FROM TAB'
;;
;; Query the EK system for data rows matching the
;; SELECT constraints.
;;
cspice_ekfind, query, nmrows, error, errmsg
;;
;; Check whether an error occurred while processing the
;; SELECT clause. If so, output the error message.
;;
if ( error ) then begin
print, 'SELECT clause error: ', errmsg
endif else begin
for row=0, nmrows-1L do begin
print, ' '
print, format='(A,I3)', 'ROW = ', row
;;
;; Fetch values from column IARRAY in the current
;; row. Since IARRAY was the first column selected,
;; the selection index `selidx' is set to 0.
;;
selidx = 0
eltidx = 0
isnull = SPICEFALSE
while ( ( eltidx lt COL1SZ ) && ( ~isnull ) ) do begin
;;
;; If the column entry is null, we'll be kicked
;; out of this loop after the first iteration.
;;
cspice_ekgi, selidx, row, eltidx, $
ival, isnull, found
ivals[eltidx] = ival
eltidx = eltidx + 1
endwhile
print, format='(A,$)', ' COLUMN = IARRAY:'
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0,COL1SZ-1L do begin
print, format='(I6,$)', ivals[i]
endfor
print, ' '
endelse
;;
;; Fetch values from column DARRAY in the current
;; row. Since DARRAY contains variable-size array
;; elements, we call cspice_eknelt to determine how many
;; elements to fetch.
;;
selidx = 1
nelt = cspice_eknelt( selidx, row )
eltidx = 0
isnull = SPICEFALSE
while ( ( eltidx lt nelt ) && ( ~isnull ) ) do begin
cspice_ekgd, selidx, row, eltidx, $
dval, isnull, found
dvals[eltidx] = dval
eltidx = eltidx + 1
endwhile
print, format='(A,$)', ' COLUMN = DARRAY:'
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0,nelt-1L do begin
print, format='(F6.1,$)', dvals[i]
endfor
print, ' '
endelse
;;
;; Fetch values from column CARRAY in the current
;; row.
;;
selidx = 2
nelt = cspice_eknelt( selidx, row )
eltidx = 0
isnull = SPICEFALSE
while ( ( eltidx lt nelt ) && ( ~isnull ) ) do begin
cspice_ekgc, selidx, row, eltidx, STRSIZ, $
cval, isnull, found
cvals[eltidx] = cval
eltidx = eltidx + 1
endwhile
print, format='(A,$)', ' COLUMN = CARRAY:'
if ( isnull ) then begin
print, '<Null>'
endif else begin
for i=0,nelt-1L do begin
print, format='(X,A,$)', cvals[i]
endfor
print, ' '
endelse
endfor
;;
;; We either parsed the SELECT clause or had an error.
;;
endelse
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
ROW = 0
COLUMN = IARRAY: 101 201 301
COLUMN = DARRAY: 201.0
COLUMN = CARRAY: ST101 ST102 ST103 ST104
ROW = 1
COLUMN = IARRAY: 102 202 302
COLUMN = DARRAY: 401.0 402.0
COLUMN = CARRAY: ST201 ST202 ST203 ST204 ST205
ROW = 2
COLUMN = IARRAY: 103 203 303
COLUMN = DARRAY: 601.0 602.0 603.0
COLUMN = CARRAY: ST301 ST302 ST303 ST304 ST305 ST306
ROW = 3
COLUMN = IARRAY: 104 204 304
COLUMN = DARRAY: 801.0 802.0 803.0 804.0
COLUMN = CARRAY: ST401 ST402 ST403 ST404 ST405 ST406 ST407
Note that after run completion, a new EK file exists in the
output directory.
This routine is meant to be used in conjunction with the EK
fetch entry points cspice_ekgc, cspice_ekgd, and cspice_ekgi
allowing the caller of those routines to determine appropriate
loop bounds to use to fetch each column entry in the current row.
1) If this routine is called when no E-kernels have been loaded,
the error SPICE(NOLOADEDFILES) is signaled by a routine in the
call tree of this routine.
2) If `selidx' is outside of the range established by the last query
passed to the EK search engine, the error SPICE(INVALIDINDEX) is
signaled by a routine in the call tree of this routine.
3) If `row' is outside of the range established by the last query passed
to the EK search engine, the error SPICE(INVALIDINDEX) is signaled by
a routine in the call tree of this routine.
4) If any of the input arguments, `selidx' or `row', is
undefined, an error is signaled by the IDL error handling
system.
5) If any of the input arguments, `selidx' or `row', is not of
the expected type, or it does not have the expected dimensions
and size, an error is signaled by the Icy interface.
This routine reads binary "sequence component" EK files.
In order for a binary EK file to be accessible to this routine,
the file must be "loaded" via a call to the routine cspice_eklef.
Text format EK files cannot be used by this routine; they must
first be converted by binary format by the NAIF Toolkit utility
SPACIT.
None.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.4, 10-AUG-2021 (JDR)
Edited the header to comply with NAIF standard. Updated code example to
not require any existing EK.
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 arguments' type and size information in the -I/O section.
-Icy Version 1.0.3, 24-APR-2010 (EDW)
Minor edit to code comments eliminating typo.
Implemented a complete code example.
-Icy Version 1.0.2, 03-FEB-2008 (EDW)
Completed the previously empty -I/O section. Edited the header
for clarity.
-Icy Version 1.0.1, 09-DEC-2005 (EDW)
Added -Examples section.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
return the number of elements in a column entry
|