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
cspice_ekfind

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_EKFIND finds E-kernel data that satisfy a set of constraints.

I/O


   Given:

      query   a string scalar specifying the data to locate from data available
               in all loaded EK files.

               help, query
                  STRING = Scalar

               The general form of a query general form:

                 SELECT   <column list>
                 FROM     <table list>
                [WHERE    <constraint list>]
                [ORDER BY <ORDER BY column list>]

              (WHERE and ORDER BY are optional parameters)

   the call:

      cspice_ekfind, query, nmrows, error, errmsg

   returns:

      nmrows   a scalar integer containing the number of rows matching the
               query.

               help, nmrows
                  LONG = Scalar

      error    a scalar boolean indicating whether the query parsed correctly
               (TRUE) or not (FALSE).

               help, error
                  BOOLEAN = Scalar

      errmsg   a string scalar containing a description of the parse error
               should one occur, otherwise the string returns as blank.

               help, errmsg
                  STRING = Scalar

Parameters


   None.

Examples


   Any numerical results shown for these examples may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Perform a query on an EK file that contains a database with
      the different commands of the Deep Impact spacecraft subsystem,
      and a table with the subsystem id, the parameter name, and the
      description of that parameters, ordered by subsystem name. Print
      the number of records of that table.

      Use the EK kernel below to load the Deep Impact spacecraft
      subsystem commands dictionary.

         dif_cmdict_128_20050620.bdb


      Example code begins here.


      PRO ekfind_ex1

         ;;
         ;; Assign an EK file to load.
         ;;
         EK = 'dif_cmdict_128_20050620.bdb'

         ;;
         ;; Load the EK.
         ;;
         cspice_furnsh, EK

         ;;
         ;; The EK file contains the table 'DIF_COMMANDS',
         ;; and that 'DIF_COMMANDS' contains columns named:
         ;;
         ;;   SUBSYSTEM, COMMAND, PARAMETER_NAME, DESCRIPTION
         ;;
         ;; Define a set of constraints to perform a query on all
         ;; loaded EK files (the SELECT clause).
         ;;
         query = 'Select SUBSYSTEM, COMMAND, PARAMETER_NAME, ' + $
                 'DESCRIPTION from DIF_COMMANDS order by SUBSYSTEM'

         ;;
         ;; Query the EK system for data rows matching the
         ;; SELECT constraints.
         ;;
         cspice_ekfind, query, nmrows, error, errmsg

         ;;
         ;; Check if an error occurred during parsing of the query string.
         ;; If so, the errmsg string contains the error message.
         ;;
         if ( error ) then begin

            print, 'Error message: ', errmsg

         endif else begin

            ;;
            ;; If no error, `nmrows' contains the number of rows matching
            ;; the constraints specified in the query string
            ;;
            print, 'Number of matching rows: ', nmrows

         endelse

         ;;
         ;; Clear the kernel pool and database. Note, you don't normally
         ;; unload an EK after a query, rather at the end of a program.
         ;;
         cspice_kclear

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Number of matching rows:         5798


   2) Examples of strings containing syntactically valid queries:

          SELECT COL1 FROM TAB1

          select col1 from tab1 where col1 gt 5

          SELECT COL2 FROM TAB1 WHERE COL2 > 5.7D0 ORDER BY COL2

          SELECT COL2 FROM TAB1 WHERE COL1 != 5

          SELECT COL2 FROM TAB1 WHERE COL1 GE COL2

          SELECT COL1, COL2, COL3 FROM TAB1 ORDER BY COL1

          SELECT COL3 FROM TAB1 WHERE COL5 EQ "ABC"

          SELECT COL3 FROM TAB1 WHERE COL5 = 'ABC'

          SELECT COL3 FROM TAB1 WHERE COL5 LIKE 'A*'

          SELECT COL3 FROM TAB1 WHERE COL5 LIKE 'A%%'

          SELECT COL4 FROM TAB1 WHERE COL4 = '1995 JAN 1 12:38:09.7'

          SELECT COL4 FROM TAB1 WHERE COL4 = "1995 JAN 1 12:38:09.7"

          SELECT COL4 FROM TAB1 WHERE
          COL4 NE 'GLL SCLK 02724646:67:7:2'

          SELECT COL1 FROM TAB1 WHERE COL1 != NULL

          SELECT COL1 FROM TAB1 WHERE COL1 IS NULL

          SELECT COL1 FROM TAB1 WHERE COL1 IS NOT NULL

          SELECT COL1, COL2, COL3 FROM TAB1
          WHERE (COL1 BETWEEN 4 AND 6) AND (COL3 NOT LIKE "A%%")
          ORDER BY COL1, COL3

          SELECT COL4 FROM TAB1
          WHERE COL4 BETWEEN "1995 JAN 1 12:38" AND
          "October 23, 1995"

          SELECT COL1, COL2 FROM TAB1 WHERE
          NOT (    ( ( COL1 <  COL2 ) AND ( COL1 > 5   ) )  OR
                   ( ( COL1 >= COL2 ) AND ( COL2 <= 10 ) )      )


          SELECT T1.COL1, T1.COL2, T2.COL2, T2.COL3
          FROM TABLE1 T1, TABLE2 T2
          WHERE T1.COL1 = T2.COL1
          AND T1.COL2 > 5
          ORDER BY T1.COL1, T2.COL2


   3) Examples of syntactically invalid queries:

          SELECT TIME WHERE TIME
          LT 1991 JAN 1                      {FROM clause is absent}

          select time from table1 where
          time lt 1991 jan 1                 {time string is not
                                              quoted}

          select time from table1
          where time .lt. '1991 jan 1'       {operator should be lt}

          select cmd from table1
          where "cmd,6tmchg" != cmd          {value is on left side
                                              of operator}

          select event_type from table1
          where event_type eq ""             {quoted string is empty
                                              ---use " " to indicate
                                              a blank string}

          select event_type from table1
          where event_type = "COMMENT"
          order TIME                         {ORDER BY phrase is
                                              lacking BY keyword}

          select COL1 from table where
          where COL1 eq MOC_EVENT            {literal string on
                                              right-hand-side of
                                              operator is not quoted}



       In the following examples, we'll assume that the program
       calling cspice_ekfind has loaded an EK containing two segments
       having columns having the following names and attributes:


        TABLE1:
        ==========

          Column name        Data type         Size       Indexed?
          -----------        ---------         ----       --------
          EVENT_TYPE         CHARACTER*32      1          YES
          EVENT_PARAMETERS   CHARACTER*(*)     1          NO
          COMMENT            CHARACTER*80      VARIABLE   NO


        TABLE2:
        ==========

          Column name        Data type         Size       Indexed?
          -----------        ---------         ----       --------
          EVENT_TYPE         CHARACTER*32      1          YES
          EVENT_PARAMETERS   CHARACTER*80      1          NO
          COMMENT            CHARACTER*80      VARIABLE   NO
          COMMAND            CHARACTER*80      1          YES


       Then the following queries are semantically invalid:

          SELECT EVENT_PARAMETERS
          FROM TABLE1
          WHERE EVENT_DURATION = 7.0         {No column called
                                              EVENT_DURATION
                                              is present in a loaded
                                              EK}

          SELECT COMMENT FROM TABLE2
          WHERE COMMENT EQ "N/A"             {The COMMENT column does
                                              not have size 1 and
                                              therefore cannot be
                                              referenced in a query}

Particulars


   This routine operates almost entirely by side effects: it
   prepares the EK fetch routines to return event data that
   satisfy the input query. See the EK Required Reading for examples
   of use of this routine in conjunction with the EK fetch routines.

Exceptions


   1)  Most of the exceptions that can occur on a call to
       cspice_ekfind are caused by errors in the input query. cspice_ekfind
       attempts to diagnose these via the output error flag and
       error message, instead of signaling errors. The following
       classes of errors are detected:

          Scanning errors---these result from badly formed query
          in which cspice_ekfind could not identify all of the tokens.
          When these errors occur, cspice_ekfind may be too confused to
          give a helpful diagnostic message.

          Parsing errors---these result from a badly formed
          query that cspice_ekfind was able to separate into tokens
          but that cspice_ekfind determined to be syntactically invalid:

          Name resolution errors---these result from referencing
          invalid or ambiguous column or table names in a query.

          Time resolution errors---these result from use of time
          strings that cannot be parsed.

          Semantic errors---these result from a syntactically
          valid query that violates a limit or a restriction on
          values used in a query.


   Some problems with queries are not trapped by cspice_ekfind but
   instead cause errors to be signaled. These are listed below.

   2)  If no E-kernels are loaded at the time this routine is called,
       an error is signaled by a routine in the call tree of this
       routine.

   3)  If a leapseconds kernel is is not loaded before this routine
       is called, UTC time values may not be used in queries. If they
       are, an error is signaled by a routine in the call tree of
       this routine.

   4)  If an SCLK kernel for the appropriate spacecraft clock has not
       been loaded before this routine is called, SCLK values for
       that clock may not be used in queries. If they are, an error
       is signaled by a routine in the call tree of this routine.

   5)  If the input argument `query' is undefined, an error is
       signaled by the IDL error handling system.

   6)  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.

   7)  If any of the output arguments, `nmrows', `error' or `errmsg',
       is not a named variable, an error is signaled by the Icy
       interface.

Files


   None.

Restrictions


   1)  A leapseconds kernel must be loaded before this routine may
       be called, if UTC time values are used in input queries.

   2)  An appropriate SCLK kernel must be loaded before this routine
       may be called, if SCLK values are used in input queries.

   3)  Data found in response to a query become unavailable
       when a fast load is initiated via cspice_ekifld. Any desired
       fetches of the data must be performed before a fast
       load or any other operation that modifies the EK scratch
       area is initiated.

Required_Reading


   ICY.REQ
   EK.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.1, 13-AUG-2021 (JDR)

       Edited the -Examples section to comply with NAIF standard. Added
       example's problem statement and example's EK. Updated code
       example to work with provided EK. Added examples of syntactically
       valid and invalid queries.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections, and
       completed -Particulars section.

       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.0, 16-JUN-2003 (EDW)

Index_Entries


   find EK data
   issue EK query



Fri Dec 31 18:43:04 2021