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 
 
Wed Apr  5 17:54:34 2017