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_ekgd

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

Abstract


   CSPICE_EKGD returns an element of double precision data from a
   specified row in a specified column of the set of rows matching
   the previous cspice_ekfind SELECT query.

I/O


   Given:

      selidx   the index for a column of interest satisfying the SELECT
               clause, the column indices range from 1 to number of
               columns in the SELECT clause.

               [1,1] = size(selidx); int32 = class(selidx)

      row      the index for a row in the column identified by 'selidx',
               the column indices range from 1 to 'nmrows' where 'nmrows'
               equals the total number of rows satisfying the SELECT clause.

               [1,1] = size(row); int32 = class(row)

      elment   the index for an element of the data at the 'selidx','row'
               position; a scalar value at 'selidx', 'row' has 'elment'
               value one.

               [1,1] = size(elment); int32 = class(elment)

   the call:

      [ ddata, null, found] = cspice_ekgd( selidx, row, elment )

   returns:

      ddata    the value of the requested element at data location
               'selidx', 'row', 'elment'.

               [1,1] = size(ddata); double = class(ddata)

      null     a boolean indicating if 'ddata' has a null value.

               [1,1] = size(null); logical = class(null)

      found    a boolean indicating whether the specified value at
               'selidx', 'row', 'elment' was found.

               [1,1] = size(found); logical = class(found)

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 Supplementary Engineering Data Records of the Viking Project
      in order to retrieve the PLATFORM_CLOCK values (double precision)
      that correspond to the images with IMAGE_NUMBER smaller than
      a given value, ordered by IMAGE_NUMBER.


      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


      Example code begins here.


      function ekgd_ex1()

         %
         % Assign an EK file to load.
         %
         EK = 'vo_sedr.bdb';

         %
         % Load the EK.
         %
         cspice_furnsh( EK )

         %
         % The table 'VIKING_SEDR_DATA' has a column 'PLATFORM_CLOCK'
         % of double precision values.
         %
         % Define a set of constraints to perform a query on all
         % loaded EK files (the SELECT clause). In this case select
         % the column 'PLATFORM_CLOCK' from table 'VIKING_SEDR_DATA'
         % sorted by 'IMAGE_NUMBER'.
         %
         query = ['Select PLATFORM_CLOCK from VIKING_SEDR_DATA '          ...
                  'where IMAGE_NUMBER < 25860000  order by IMAGE_NUMBER'];

         %
         % Query the EK system for data rows matching the
         % SELECT constraints.
         %
         [nmrows, error, errmsg] = cspice_ekfind( query );

         %
         % Check whether an error occurred while processing the
         % SELECT clause. If so, output the error message.
         %
         if ( error )
            printf( 'SELECT clause error: %s\n', errmsg );
         end

         %
         % Loop over each row found matching the query.
         %
         for rowno = 1:nmrows

            %
            % Fetch the double precision data. We know the query returned
            % one column and the column contains only scalar data,
            % so the index of all elements is 1.
            %
            selidx = 1;
            eltidx = 1;

            %
            % Use cspice_ekgd to retrieve the value from
            % row/column position.
            %
            [ddata, isnull, found] = cspice_ekgd( selidx, rowno, eltidx );

            %
            % Output the value, if non-null data exist at the
            % requested position.
            %
            if  ~isnull
               fprintf( 'Row %3d: Double precision data: %f\n', rowno,    ...
                                                                ddata );
            end

         end

         %
         % 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


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


      Row   1: Double precision data: 119.880000
      Row   2: Double precision data: 119.270000
      Row   3: Double precision data: 119.880000
      Row   4: Double precision data: 119.270000
      Row   5: Double precision data: 119.880000
      Row   6: Double precision data: 119.270000
      Row   7: Double precision data: 120.140000
      Row   8: Double precision data: 119.520000
      Row   9: Double precision data: 120.140000
      Row  10: Double precision data: 120.140000
      Row  11: Double precision data: 120.140000
      Row  12: Double precision data: 221.920000
      Row  13: Double precision data: 221.920000
      Row  14: Double precision data: 221.920000
      Row  15: Double precision data: 120.140000
      Row  16: Double precision data: 120.140000
      Row  17: Double precision data: 120.140000
      Row  18: Double precision data: 120.220000
      Row  19: Double precision data: 120.220000
      Row  20: Double precision data: 120.220000
      Row  21: Double precision data: 120.370000
      Row  22: Double precision data: 120.370000
      Row  23: Double precision data: 120.370000
      Row  24: Double precision data: 120.290000
      Row  25: Double precision data: 120.290000
      Row  26: Double precision data: 120.290000


   2) Perform a query on an EK file that contains a database with
      the Supplementary Engineering Data Records of the Viking
      Project in order to retrieve the IMAGE_TIME values (double
      precision time) that correspond to the images with
      IMAGE_NUMBER smaller than a given value, ordered by
      IMAGE_NUMBER.


      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.


      function ekgd_ex2()

         %
         % Assign an EK file to load.
         %
         EK     = 'vo_sedr.bdb';
         LSKNAM = 'naif0012.tls';

         %
         %  Load leapseconds file for time conversion.
         %
         cspice_furnsh( LSKNAM );

         %
         % Load the EK.
         %
         cspice_furnsh( EK )

         %
         % The table 'VIKING_SEDR_DATA' has a column 'IMAGE_TIME'
         % of double precision values.
         %
         % Define a set of constraints to perform a query on all
         % loaded EK files (the SELECT clause). In this case select
         % the column 'IMAGE_TIME' from table 'VIKING_SEDR_DATA'
         % sorted by 'IMAGE_NUMBER'.
         %
         query = ['Select IMAGE_TIME from VIKING_SEDR_DATA '          ...
                  'where IMAGE_NUMBER < 25860000  order by IMAGE_NUMBER'];

         %
         % Query the EK system for data rows matching the
         % SELECT constraints.
         %
         [nmrows, error, errmsg] = cspice_ekfind( query );

         %
         % Check whether an error occurred while processing the
         % SELECT clause. If so, output the error message.
         %
         if ( error )
            printf( 'SELECT clause error: %s\n', errmsg );
         end

         %
         % Loop over each row found matching the query.
         %
         for rowno = 1:nmrows

            %
            % Fetch the double precision data. We know the query returned
            % one column and the column contains only scalar data,
            % so the index of all elements is 1.
            %
            selidx = 1;
            eltidx = 1;

            %
            % Use cspice_ekgd to retrieve the value from
            % row/column position.
            %
            [ddata, isnull, found] = cspice_ekgd( selidx, rowno, eltidx );

            %
            % Output the value, if non-null data exist at the
            % requested position.
            %
            if  ~isnull

               [utcstr] = cspice_et2utc( ddata, 'C', 3 );
               fprintf( 'Row %3d: Time data:  %s\n', rowno, utcstr );
            end

         end

         %
         % 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


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


      Row   1: Time data:  1976 JUN 16 16:50:55.925
      Row   2: Time data:  1976 JUN 16 16:51:00.269
      Row   3: Time data:  1976 JUN 16 20:56:53.051
      Row   4: Time data:  1976 JUN 16 20:56:57.395
      Row   5: Time data:  1976 JUN 17 01:02:50.177
      Row   6: Time data:  1976 JUN 17 01:02:54.521
      Row   7: Time data:  1976 JUN 17 05:08:56.263
      Row   8: Time data:  1976 JUN 17 05:09:00.607
      Row   9: Time data:  1976 JUN 17 06:30:28.424
      Row  10: Time data:  1976 JUN 17 06:30:46.174
      Row  11: Time data:  1976 JUN 17 06:30:55.168
      Row  12: Time data:  1976 JUN 17 11:17:47.471
      Row  13: Time data:  1976 JUN 17 11:18:05.221
      Row  14: Time data:  1976 JUN 17 11:18:14.215
      Row  15: Time data:  1976 JUN 17 13:20:23.634
      Row  16: Time data:  1976 JUN 17 13:20:41.384
      Row  17: Time data:  1976 JUN 17 13:20:50.378
      Row  18: Time data:  1976 JUN 17 15:23:17.717
      Row  19: Time data:  1976 JUN 17 15:23:35.467
      Row  20: Time data:  1976 JUN 17 15:23:44.461
      Row  21: Time data:  1976 JUN 17 17:26:20.760
      Row  22: Time data:  1976 JUN 17 17:26:38.510
      Row  23: Time data:  1976 JUN 17 17:26:47.504
      Row  24: Time data:  1976 JUN 17 19:29:23.803
      Row  25: Time data:  1976 JUN 17 19:29:41.553
      Row  26: Time data:  1976 JUN 17 19:29:50.547


Particulars


   Suppose a SELECT clause return data consisting of three columns (N=3)
   and four rows (M=4):

              col 1    col 2    col 3

      row 1   val_11   val_12   val_13
      row 2   val_21   val_22   val_23
      row 3   val_31   val_32   val_33
      row 4   val_41   val_42   val_43

   with "col 2" and "col 3" containing scalar double precision data
   and "val_42" containing a vector of K doubles.

   Retrieving the data elements depends on the values for the index set
   "selidx," "row," and "elment."

   Use the set

      'selidx' = 2, 'row' = 3, 'elment' = 1

   to fetch scalar "val_32."

   Use the set

      'selidx' = 3, 'row' = 4, 'elment' = 1

   to fetch scalar "val_43."

   Use the set

      'selidx' = 2, 'row' = 4, 'elment' = K

   to fetch the final element of vector "val_42"

   `elment' is allowed to exceed the number of elements in the column
   entry; if it does, `found' returns as false. This allows the caller
   to read data from the column entry in a loop without checking the
   number of available elements first.

Exceptions


   1)  If the input argument `elment' is less than 1, the error
       SPICE(INVALIDINDEX) is signaled by a routine in the call tree
       of this routine and `found' is returned false. However, `elment'
       is allowed to be greater than the number of elements in the
       specified column entry; this allows the caller to read data
       from the column entry in a loop without checking the number of
       available elements first. If `elment' is greater than the number
       of available elements, `found' is returned false.

   2)  If `selidx' is outside of the range established by the last query
       passed to the EK search engine, the error SPICE(INVALIDINDEX) is
       signaled by a routine in the call tree of this routine and `found' is
       returned false.

   3)  If the input argument `row' is less than 1 or greater than the
       number of rows matching the query, the error
       SPICE(INVALIDINDEX) is signaled by a routine in the call tree
       of this routine and `found' is returned false.

   4)  If the specified column does not have DP or TIME type, the
       error SPICE(INVALIDTYPE) is signaled by a routine in the call
       tree of this routine.

   5)  If this routine is called when no E-kernels have been loaded,
       the error SPICE(NOLOADEDFILES) is signaled by a routine in the
       call tree of this routine.

   6)  If any of the input arguments, `selidx', `row' or `elment', is
       undefined, an error is signaled by the Matlab error handling
       system.

   7)  If any of the input arguments, `selidx', `row' or `elment', is
       not of the expected type, or it does not have the expected
       dimensions and size, an error is signaled by the Mice
       interface.

Files


   This routine reads binary "sequence component" EK files.
   In order for a binary EK file to be accessible to this routine,
   the file must be "loaded" via a call to the routine cspice_furnsh.

   Text format EK files cannot be used by this routine; they must
   first be converted by binary format by the NAIF Toolkit utility
   SPACIT.

Restrictions


   None.

Required_Reading


   MICE.REQ
   EK.REQ

Literature_References


   None.

Author_and_Institution


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

Version


   -Mice Version 1.3.0, 10-AUG-2021 (EDW) (JDR)

       Edited the -Examples section to comply with NAIF standard. Added
       example's problem statement and example's EK. Updated example
       code to work with provided EK, and added additional examples.

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

       Eliminated use of "lasterror" in rethrow.

       Removed reference to the function's corresponding CSPICE header from
       -Required_Reading section.

   -Mice Version 1.2.1, 03-NOV-2014 (EDW)

       Edited -I/O section to conform to NAIF standard for Mice
       documentation.

   -Mice Version 1.2.0, 10-MAY-2011 (EDW)

       "logical" call replaced with "zzmice_logical."

   -Mice Version 1.0.0, 10-APR-2010 (EDW)

Index_Entries


   fetch element from double precision column entry


Fri Dec 31 18:44:24 2021