| ekpsel_c |
|
Table of contents
Procedure
ekpsel_c ( EK, parse SELECT clause )
void ekpsel_c ( ConstSpiceChar * query,
SpiceInt msglen,
SpiceInt tablen,
SpiceInt collen,
SpiceInt * n,
SpiceInt * xbegs,
SpiceInt * xends,
SpiceEKDataType * xtypes,
SpiceEKExprClass * xclass,
void * tabs,
void * cols,
SpiceBoolean * error,
SpiceChar * errmsg )
AbstractParse the SELECT clause of an EK query, returning full particulars concerning each selected item. Required_ReadingNone. KeywordsPRIVATE Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- query I EK query. msglen I Available space in the output error message string. tablen I Length of strings in `tabs' output array. collen I Length of strings in `cols' output array. n O Number of items in SELECT clause of `query'. xbegs O Begin positions of expressions in SELECT clause. xends O End positions of expressions in SELECT clause. xtypes O Data types of expressions. xclass O Classes of expressions. tabs O Names of tables qualifying SELECT columns. cols O Names of columns in SELECT clause of `query'. error O Error flag. errmsg O Parse error message. Detailed_Input
query is a character string containing an EK query.
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 functions, such as
COUNT(*)
COUNT( <table name>.<column name> )
MAX ( <table name>.<column name> )
or expressions involving constants, such as
2 * <column name>
msglen is the allowed length for the output message string.
This length must large enough to hold the output
string plus the terminator. If the output string is
expected to have x characters, `msglen' needs to be
x + 1.
tablen is the length of the strings in the output table array.
This length must large enough to hold the output
strings plus the terminator. If the output strings
are expected to have x characters, `tablen' needs to be
x + 1. The parameter SPICE_EK_TSTRLN defines a string
length sufficient to hold any table name. This
parameter is defined by SpiceEK.h.
collen The length of the strings in the output column array.
This length must large enough to hold the output
strings plus the terminator. If the output strings
are expected to have x characters, `collen' needs to be
x + 1. The parameter SPICE_EK_CSTRLN defines a string
length sufficient to hold any table name. This
parameter is defined by SpiceEK.h.
Detailed_Output
n is the number of items specified in the
SELECT clause of the input query.
xbegs,
xends are, respectively, arrays of begin and end
positions of expressions designating items in the
SELECT clause of the input query. The ith
expression is located in the substring
query[ xbegs[i] ]...query[ xends[i] ]
xtypes is an array of values of type SpiceEKDataType giving
types of the expressions in the SELECT clause.
Values and meanings of `xtypes' are:
SPICE_CHR Character type
SPICE_DP Double precision type
SPICE_INT Integer type
SPICE_TIME Time type
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 ekgc_c
SPICE_DP ekgd_c
SPICE_INT ekgi_c
SPICE_TIME ekgd_c
Note that time values are stored as d.p. numbers.
xclass is an array of values of type SpiceEKExprClass giving
the classes of the expressions occurring in the SELECT
clause of the input query. Values and meanings of
`xclass' are:
SPICE_EK_EXP_COL Selected item was a column.
The column may qualified by a
table name.
SPICE_EK_EXP_FUNC Selected item was a simple
function invocation of the
form
F ( <column> )
or else was
COUNT(*)
SPICE_EK_EXP_EXPR Selected item was a more
general expression than those
shown above.
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.
tabs is an array of names of tables corresponding to
the columns in the SELECT clause. 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.
The contents of tabs[i] are defined if and only if
the returned value of xclass[i] is SPICE_EK_EXP_COL.
The caller should declare `tabs' as an array of strings
of length
SPICE_EK_TSTRLN
for example
SpiceChar tabs[SPICE_EK_MAXQSEL][SPICE_EK_TSTRLN];
cols is an array containing the columns of the SELECT
clause. The contents of cols[i] are defined if and
only if the returned value of xclass[i] is
SPICE_EK_EXP_COL.
The caller should declare `cols' as an array of strings
of length
SPICE_EK_CSTRLN
for example
SpiceChar tabs[SPICE_EK_MAXQSEL][SPICE_EK_CSTRLN];
error is a logical flag indicating whether the input
`query' parsed correctly. The other outputs of this
routine, except for `errmsg', are undefined if a
parse error occurred. `error' is returned SPICETRUE if
a parse error occurred, SPICEFALSE otherwise.
errmsg is a character string describing the cause of a
parse error, if such an error occurred. Otherwise,
`errmsg' is returned empty.
ParametersNone. Exceptions
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 `query' input string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
4) If the `query' input string has zero length, the error
SPICE(EMPTYSTRING) is signaled.
5) If the `errmsg' output string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
6) If the `errmsg' output string has length less than two
characters, the error SPICE(STRINGTOOSHORT) is signaled, since
the output string is too short to contain one character of
output data plus a null terminator.
FilesNone. ParticularsThis 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. Examples
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, 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
eknelt_c may be called to obtain the size of column entries to
be fetched. See eknelt_c 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.
/.
Program ekpsel_ex1
./
#include <stdio.h>
#include "SpiceUsr.h"
int main( )
{
/.
Local parameters
./
#define EKNAME "vo_sedr.bdb"
#define LSKNAM "naif0012.tls"
#define ERRLEN 1840
#define TIMLEN 27
#define TYPLEN 4
#define XCLSLN 4
/.
Local variables
./
SpiceChar cdata [SPICE_EK_MAXQSTR];
SpiceChar cols [SPICE_EK_MAXQSEL][SPICE_EK_MAXQRY];
SpiceChar errmsg [ERRLEN];
SpiceChar * query;
SpiceChar utcstr [TIMLEN];
SpiceChar tabs [SPICE_EK_MAXQTAB][SPICE_EK_MAXQRY];
SpiceEKExprClass xclass [SPICE_EK_MAXQSEL];
SpiceEKDataType xtypes [SPICE_EK_MAXQSEL];
SpiceDouble ddata;
SpiceDouble tdata;
SpiceInt b;
SpiceInt colno;
SpiceInt e;
SpiceInt handle;
SpiceInt idata;
SpiceInt n;
SpiceInt nmrows;
SpiceInt row;
SpiceInt xbegs [SPICE_EK_MAXQSEL];
SpiceInt xends [SPICE_EK_MAXQSEL];
SpiceBoolean error;
SpiceBoolean found;
SpiceBoolean null;
/.
Load leapseconds file for time conversion.
./
furnsh_c ( LSKNAM );
/.
Load EK.
./
eklef_c ( EKNAME, &handle );
/.
Setup the query. Parse the SELECT clause using
ekpsel_c.
./
query = "Select IMAGE_NUMBER, IMAGE_ID, PLATFORM_CLOCK, IMAGE_TIME "
"from VIKING_SEDR_DATA where IMAGE_NUMBER < 25850000 "
"order by IMAGE_NUMBER";
ekpsel_c ( query, ERRLEN, SPICE_EK_MAXQRY, SPICE_EK_MAXQRY,
&n, xbegs, xends, xtypes,
xclass, tabs, cols, &error, errmsg );
if ( error )
{
printf( "%s\n", errmsg );
}
else
{
/.
Submit query to the EK query system.
./
ekfind_c ( query, ERRLEN, &nmrows, &error, errmsg );
if ( error )
{
printf( "%s\n", errmsg );
}
else
{
/.
Fetch the rows that matched the query.
./
for ( row = 0; row < nmrows; row++ )
{
/.
Fetch data from the ith row.
./
printf( " \n" );
printf( "ROW = %d\n", (int)row );
for ( colno = 0; colno < n; colno++ )
{
/.
Fetch the data from the jth selected
column.
./
if ( xclass[colno] == SPICE_EK_EXP_COL )
{
printf( " %s.%-14s: ", tabs[colno], cols[colno] );
}
else
{
b = xbegs[colno];
e = xends[colno];
printf( "ITEM = (%.*s)", e-b, query+b );
}
if ( xtypes[colno] == SPICE_CHR )
{
ekgc_c ( colno, row, 1, SPICE_EK_MAXQSTR,
cdata, &null, &found );
if ( null )
{
printf( "<Null>\n" );
}
else
{
printf( "%s\n", cdata );
}
}
else if ( xtypes[colno] == SPICE_DP )
{
ekgd_c ( colno, row, 1, &ddata, &null, &found );
if ( null )
{
printf( "<Null>\n" );
}
else
{
printf( "%f\n", ddata );
}
}
else if ( xtypes[colno] == SPICE_INT )
{
ekgi_c ( colno, row, 1, &idata, &null, &found );
if ( null )
{
printf( "<Null>\n" );
}
else
{
printf( "%d\n", (int)idata );
}
}
else
{
/.
The item is a time value. Convert it
to UTC for output.
./
ekgd_c ( colno, row, 1, &tdata, &null, &found );
if ( null )
{
printf( "<Null>\n" );
}
else
{
et2utc_c ( tdata, "C", 3, TIMLEN, utcstr );
printf( "%s\n", utcstr );
}
}
/.
We're done with the column having index `colno'.
./
}
/.
We're done with the row having index `row'.
./
}
/.
We either processed the query or had an error.
./
}
/.
We either parsed the SELECT clause or had an error.
./
}
return ( 0 );
}
When this program was executed on a Mac/Intel/cc/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.880000
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.270000
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.880000
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.270000
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.880000
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.270000
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.140000
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.520000
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.140000
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.140000
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.140000
VIKING_SEDR_DATA.IMAGE_TIME : 1976 JUN 17 06:30:55.168
Restrictions1) Currently, column names are the only supported expressions. Literature_ReferencesNone. Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) E.D. Wright (JPL) Version
-CSPICE Version 2.1.3, 10-AUG-2021 (JDR)
Edited the header to comply with NAIF standard. Added complete
code example.
Extended the -Exceptions section to include the errors detected
by this wrapper.
-CSPICE Version 2.1.2, 22-MAR-2016 (NJB)
Updated brief I/O to describe inputs "tablen" and "collen".
Also added to -Detailed_Output descriptions of declarations
of the outputs "tabs" and "cols".
-CSPICE Version 2.1.1, 14-AUG-2006 (EDW)
Replace mention of ldpool_c with furnsh_c.
-CSPICE Version 2.1.0, 02-SEP-1999 (NJB)
Local type logical variable now used for error flag used in
interface of ekpsel_.
-CSPICE Version 2.0.0, 19-JUL-1999 (NJB)
The data types of the tabs and cols arguments were changed
to (void *), and associated string length arguments were added.
This style of interface for string arrays is now standard within
CSPICE.
Some corrections of the header comments were made.
-CSPICE Version 1.0.0, 21-FEB-1999 (NJB)
Index_Entriesparse select clause of EK query |
Fri Dec 31 18:41:06 2021