Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page ekpsel_c
Table of contents
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### 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  )
#### Abstract
       Parse the SELECT clause of an EK query, returning full particulars
       concerning each selected item.
#### Required_Reading
       None.
#### Keywords
       PRIVATE
#### Brief_I/O
       VARIABLE  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.
#### Parameters
       None.
#### 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.
#### Files
       None.
#### Particulars
       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.
#### 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
#### Restrictions
       1)  Currently, column names are the only supported expressions.
#### Literature_References
       None.
#### Author_and_Institution
       N.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_Entries
       parse select clause of EK query
#### Link to routine ekpsel_c source file ekpsel_c.c

    Fri Dec 31 18:41:06 2021