Table of contents
CSPICE_EKPSEL parses the SELECT clause of an EK query, returning full
particulars concerning each selected item.
Given:
query a character string containing an EK query.
help, query
STRING = Scalar
EK queries have the general form
SELECT <select expr>, <select expr>, ...
FROM <table spec>, <table spec>, ...
[WHERE <constraint list>]
[ORDER BY <order-by column list>]
Here the symbol <select expr> indicates any
expression representing an entity that can be
selected. Commonly, the selected items are
columns, with or without qualifying table names,
having the form
<column name>
<table name>.<column name>
<table alias>.<column name>
but more general expressions may also be selected.
Examples are procedures, such as
COUNT(*)
COUNT( <table name>.<column name> )
MAX ( <table name>.<column name> )
or expressions involving constants, such as
2 * <column name>
the call:
cspice_ekpsel, query, n, xbegs, xends, xtypes, $
xclass, tabs, cols, error, errmsg
returns:
n a scalar integer indicating the number of items in SELECT clause
of query.
help, n
LONG = Scalar
xbegs,
xends respectively, arrays of begin and end positions of expressions
designating items in the SELECT clause of the input query.
help, xbegs
LONG = Array[N]
help, xends
LONG = Array[N]
The ith expression is located in the substring
query[ xbegs[i] : xends[i] ]
xtypes an array of integers containing the data type code of the
expressions.
help, xtypes
LONG = Array[N]
The possible return values:
0 indicates SPICE_CHR, for a character expression
1 indicates SPICE_DP, for a double precision expression
2 indicates SPICE_INT, for an integer expression
3 indicates SPICE_TIME, for a time (double precision)
expression
The ith element of `xtypes' refers to the ith
selected item.
The data type of an expression indicates which
fetch routine to use to obtain values of the
selected expression. The mapping of data types
to fetch routines is shown below:
SPICE_CHR cspice_ekgc
SPICE_DP cspice_ekgd
SPICE_INT cspice_ekgi
SPICE_TIME cspice_ekgd
Note that time values are stored as d.p. numbers.
xclass an array of integers giving the classes of the expressions
occurring in the SELECT clause of the input query.
help, xclass
LONG = Array[N]
The ith element of `xclass' refers to the ith
selected item.
When a selected item is a column, the values of
the arguments `tabs' and `cols' (discussed below) are
defined.
Note that currently, column names are the only supported
expressions.
tabs an array of names of tables corresponding to the columns in the
SELECT clause.
help, tabs
STRING = Array[N]
The ith element of `tabs' corresponds to the table containing
the ith SELECT column. Table names returned in `tabs' are the
actual names of tables in loaded EKs, not aliases supplied in
the input query. Table names are supplied even if the
corresponding column was unqualified in the input query, as long
as the column name was unambiguous.
cols a vector of strings containing the names of columns in SELECT
clause of query.
help, cols
STRING = Array[N]
error a logical flag indicating whether the input `query' parsed
correctly.
help, error
BOOLEAN = Scalar
The other outputs of this routine, except for `errmsg', are
undefined if a parse error occurred. `error' is returned True if
a parse error occurred, False otherwise.
errmsg a character string describing the cause of a parse error, if
such an error occurred.
help, errmsg
STRING = Scalar
Otherwise, `errmsg' is returned empty.
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) Query the EK system and fetch data matching that query.
The program shown here does not rely on advance
knowledge of the input query or the contents of any loaded EK
files.
To simplify the example, we assume that all data are scalar.
This assumption relieves us of the need to test the size of
column entries before fetching them. In the event that a
column contains variable-size array entries, the entry point
cspice_eknelt may be called to obtain the size of column entries to
be fetched. See cspice_eknelt for an example.
Use the EK kernel below to load the information from the
original Supplementary Engineering Data Record (SEDR) data
set generated by the Viking Project.
vo_sedr.bdb
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
PRO ekpsel_ex1
;;
;; Local parameters
;;
EKNAME = 'vo_sedr.bdb'
LSKNAM = 'naif0012.tls'
MAXSTR = 1024
;;
;; Define the types of expression that may appear
;; in the SELECT clause of EK queries.
;;
SPICE_EK_EXP_COL = 0
SPICE_EK_EXP_FUNC = 1
SPICE_EK_EXP_EXPR = 2
;;
;; Define the types of EK columns.
;;
SPICE_CHR = 0
SPICE_DP = 1
SPICE_INT = 2
SPICE_TIME = 3
;;
;; Load leapseconds file for time conversion.
;;
cspice_furnsh, LSKNAM
;;
;; Load EK.
;;
cspice_eklef, EKNAME, handle
;;
;; Setup the query. Parse the SELECT clause using
;; cspice_ekpsel.
;;
query = 'Select IMAGE_NUMBER, IMAGE_ID, ' + $
'PLATFORM_CLOCK, IMAGE_TIME ' + $
'from VIKING_SEDR_DATA where IMAGE_NUMBER < 25850000 ' + $
'order by IMAGE_NUMBER'
cspice_ekpsel, query, n, xbegs, xends, xtypes, $
xclass, tabs, cols, error, errmsg
if ( error ) then begin
print, errmsg
endif else begin
;;
;; Submit query to the EK query system.
;;
cspice_ekfind, query, nmrows, error, errmsg
if ( error ) then begin
print, errmsg
endif else begin
;;
;; Fetch the rows that matched the query.
;;
for row=0, nmrows-1L do begin
;;
;; Fetch data from the ith row.
;;
print, ' '
print, 'ROW = ', row
for colno=0, n-1L do begin
;;
;; Fetch the data from the jth selected
;; column.
;;
if ( xclass[colno] eq SPICE_EK_EXP_COL ) then begin
outstr = tabs[colno] + '.' + cols[colno]
print, format='(A-33,A,$)', ' ' + outstr, ': '
endif else begin
b = xbegs[colno]
e = xends[colno]
print, format='(2A,$)', 'ITEM = ', query(b:e)
endelse
if ( xtypes[colno] eq SPICE_CHR ) then begin
cspice_ekgc, colno, row, 0, MAXSTR, cdata, null, found
if ( null ) then begin
print, '<Null>'
endif else begin
print, cdata
endelse
endif else if ( xtypes[colno] eq SPICE_DP ) then begin
cspice_ekgd, colno, row, 0, ddata, null, found
if ( null ) then begin
print, '<Null>'
endif else begin
print, ddata
endelse
endif else if ( xtypes[colno] eq SPICE_INT ) then begin
cspice_ekgi, colno, row, 0, idata, null, found
if ( null ) then begin
print, '<Null>'
endif else begin
print, idata
endelse
endif else begin
;;
;; The item is a time value. Convert it
;; to UTC for output.
;;
cspice_ekgd, colno, row, 1, tdata, null, found
if ( null ) then begin
print, '<Null>'
endif else begin
cspice_et2utc, tdata, 'C', 3, utcstr
print, utcstr
endelse
endelse
;;
;; We're done with the column having index `colno'.
;;
endfor
;;
;; We're done with the row having index `row'.
;;
endfor
;;
;; We either processed the query or had an error.
;;
endelse
;;
;; 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
VIKING_SEDR_DATA.IMAGE_NUMBER : 25837050
VIKING_SEDR_DATA.IMAGE_ID : 168C09
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.88000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 16 16:50:55.925
ROW = 1
VIKING_SEDR_DATA.IMAGE_NUMBER : 25837051
VIKING_SEDR_DATA.IMAGE_ID : 168C10
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.27000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 16 16:51:00.269
ROW = 2
VIKING_SEDR_DATA.IMAGE_NUMBER : 25840344
VIKING_SEDR_DATA.IMAGE_ID : 168C11
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.88000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 16 20:56:53.051
ROW = 3
VIKING_SEDR_DATA.IMAGE_NUMBER : 25840345
VIKING_SEDR_DATA.IMAGE_ID : 168C12
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.27000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 16 20:56:57.395
ROW = 4
VIKING_SEDR_DATA.IMAGE_NUMBER : 25843638
VIKING_SEDR_DATA.IMAGE_ID : 169C01
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.88000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 01:02:50.177
ROW = 5
VIKING_SEDR_DATA.IMAGE_NUMBER : 25843639
VIKING_SEDR_DATA.IMAGE_ID : 169C02
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.27000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 01:02:54.521
ROW = 6
VIKING_SEDR_DATA.IMAGE_NUMBER : 25846934
VIKING_SEDR_DATA.IMAGE_ID : 169C03
VIKING_SEDR_DATA.PLATFORM_CLOCK: 120.14000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 05:08:56.263
ROW = 7
VIKING_SEDR_DATA.IMAGE_NUMBER : 25846935
VIKING_SEDR_DATA.IMAGE_ID : 169C04
VIKING_SEDR_DATA.PLATFORM_CLOCK: 119.52000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 05:09:00.607
ROW = 8
VIKING_SEDR_DATA.IMAGE_NUMBER : 25848026
VIKING_SEDR_DATA.IMAGE_ID : 169C05
VIKING_SEDR_DATA.PLATFORM_CLOCK: 120.14000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 06:30:28.424
ROW = 9
VIKING_SEDR_DATA.IMAGE_NUMBER : 25848030
VIKING_SEDR_DATA.IMAGE_ID : 169C09
VIKING_SEDR_DATA.PLATFORM_CLOCK: 120.14000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 06:30:46.174
ROW = 10
VIKING_SEDR_DATA.IMAGE_NUMBER : 25848032
VIKING_SEDR_DATA.IMAGE_ID : 169C11
VIKING_SEDR_DATA.PLATFORM_CLOCK: 120.14000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 06:30:55.168
This routine allows callers of the EK fetch routines to determine
at run time the attributes of the columns from which data is to be
fetched.
1) Parse failures do not cause this routine to signal errors;
instead, the `error' and `errmsg' outputs indicate invalid
`query'.
2) Queries cannot be parsed correctly unless at least one EK
is loaded.
3) If the input argument `query' is undefined, an error is
signaled by the IDL error handling system.
4) If the input argument `query' is not of the expected type, or
it does not have the expected dimensions and size, an error is
signaled by the Icy interface.
5) If any of the output arguments, `n', `xbegs', `xends',
`xtypes', `xclass', `tabs', `cols', `error' or `errmsg', is
not a named variable, an error is signaled by the Icy
interface.
None.
1) Currently, column names are the only supported expressions.
EK.REQ
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.2, 10-AUG-2021 (JDR)
Edited the header to comply with NAIF standard. Added complete
code example.
Added -Parameters and -Particulars sections and updated -I/O section
to provide further details on the input/output arguments.
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, 04-FEB-2008 (EDW)
Edited example code to replace
not isnull
with
~isnull
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
parse select clause of EK query
|