Index Page ekpsel_c
A B C D E F G H I J K L M N O P Q R S T U V W X
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
       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         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         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 SpiceUsr.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 SpiceUsr.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
           QUERIES.

       2)  Queries cannot be parsed correctly unless at least one EK
           is loaded.
#### 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
       1)  Use of ekpsel_c to assist in fetching rows matching queries
           supplied at run time.

           The code fragment 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 columns are scalar-
           valued.

              #include "SpiceUsr.h"
              #include <stdio.h>
              #include <string.h>

              void main()
           {
              /.
              The kernel names that appear here are examples; to use this
              program, you would have to replace these names with those of
              kernels available on your own system.
              ./
              #define EK              "/kernels/galileo/ek/EK97148A.BSE"
              #define LSK             "/kernels/gen/lsk/leapseconds.ker"
              #define MSGLEN          320
              #define LNSIZE          80
              #define TIMELEN         25

              SpiceBoolean            error;
              SpiceBoolean            found;
              SpiceBoolean            null;

              SpiceChar               cdata  [LNSIZE];
              SpiceChar               cols   [SPICE_EK_MAXQSEL]
                                             [SPICE_EK_CSTRLN];
              SpiceChar               errmsg [MSGLEN];
              SpiceChar               outstr [LNSIZE];
              SpiceChar             * query;
              SpiceChar               tabs   [SPICE_EK_MAXQSEL]
                                             [SPICE_EK_TSTRLN];
              SpiceChar               utc    [TIMELEN];

              SpiceDouble             ddata;
              SpiceDouble             tdata;

              SpiceEKDataType         xtypes [SPICE_EK_MAXQSEL];
              SpiceEKExprClass        xclass [SPICE_EK_MAXQSEL];

              SpiceInt                col;
              SpiceInt                exprlen;
              SpiceInt                handle;
              SpiceInt                idata;
              SpiceInt                n;
              SpiceInt                nmrows;
              SpiceInt                row;

              SpiceInt                xbegs  [SPICE_EK_MAXQSEL];
              SpiceInt                xends  [SPICE_EK_MAXQSEL];

              /.
              Load leapseconds and E-kernels.
              ./
              furnsh_c ( LSK );
              eklef_c  ( EK, &handle );

              while ( SPICETRUE )
              {

                 /.
                 Prompt for query.  Parse the SELECT clause using ekpsel_c.
                 ./
                 query = prompt_c ( "Enter query > " );

                 ekpsel_c ( query,
                            MSGLEN,
                            &n,
                            xbegs,
                            xends,
                            xtypes,
                            xclass,
                            tabs,
                            cols,
                            &error,
                            errmsg );

                 if ( error )
                 {
                    printf ( "Error: <%s>\n", errmsg );
                 }

                 else
                 {
                    /.
                    Submit query to the EK query system.
                    ./

                    ekfind_c ( query, MSGLEN, &nmrows, &error, errmsg );

                    if ( error )
                    {
                       printf ( "Error found: %s\n", errmsg );
                    }

                    else
                    {
                       printf ( "Number of matching rows = %d\n", nmrows );

                       /.
                       Fetch the rows that matched the query.
                       ./

                       for ( row = 0;  row < nmrows;  row++ )
                       {
                          /.
                          Fetch data from the current row.
                          ./

                          printf ( "\nROW = %d\n", row );

                          for ( col = 0;  col < n;  col++ )
                          {
                             /.
                             Fetch data from the current selected column.
                             ./

                             if ( xclass[col] == SPICE_EK_EXP_COL )
                             {
                                 printf ( "COLUMN = %s.%s\n",
                                           tabs[col],
                                           cols[col] );
                             }
                             else
                             {
                                exprlen = xends[col] - xbegs[col] + 1;

                                strncpy ( outstr, query+xbegs[col],
                                          exprlen                    );

                                outstr[exprlen] = (char)0;

                                printf ( "%s\n", outstr );
                             }

                             /.
                             Write out the data.
                             ./

                             switch ( xtypes[col] )
                             {
                                case SPICE_CHR:

                                   ekgc_c ( col,   row,   0,     LNSIZE,
                                            cdata, &null, &found         );

                                   if ( !null )
                                   {
                                      printf ( "%s\n", cdata );
                                   }

                                   break;

                                case SPICE_DP:

                                   ekgd_c ( col,    row,   0,
                                            &ddata, &null, &found );

                                   if ( !null )
                                   {
                                      printf ( "%f\n", ddata );
                                   }

                                   break;

                                case SPICE_INT:

                                   ekgi_c ( col,    row,   0,
                                            &idata, &null, &found );

                                   if ( !null )
                                   {
                                      printf ( "%d\n", cdata );
                                   }

                                   break;

                                case SPICE_TIME:

                                   /.
                                   The item is a time value.  Convert it
                                   to UTC for output.
                                   ./

                                   ekgd_c ( col,    row,   0,
                                            &tdata, &null, &found );

                                   if ( !null )
                                   {
                                      et2utc_c ( tdata,   "C", 3,
                                                 TIMELEN, utc    );

                                      printf ( "%s\n", utc );
                                   }

                                   break;

                                default:

                                   ;
                             }

                             /.
                             Handle null values here.
                             ./

                             if ( null )
                             {
                                printf ( "%s\n", "<Null>" );
                             }

                             /.
                             End of data type switch.
                             ./

                          }
                          /.
                          We're done with the column having index col.
                          ./
                       }
                       /.
                       We're done with the row having index row.
                       ./
                    }
                    /.
                    We either processed the query or ekfind_c detected an
                    error.
                    ./
                 }
                 /.
                 We either parsed the SELECT clause or ekpsel_c detected an
                 error.
                 ./

              }

           }
#### Restrictions
       1)  Currently, column names are the only supported expressions.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman       (JPL)
#### Version
       -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

    Wed Apr  5 17:54:34 2017