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_eknelt

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


Abstract


   CSPICE_EKNELT returns an integer value of the number of elements
   in the specified row in a specified column.

I/O


   Given:

      selidx   the SELECT clause index of the column to fetch from.

               help, selidx
                  LONG = Scalar

      row      the index of the row containing the element.

               help, row
                  LONG = Scalar

               This number refers to a member of the set of rows matching a
               query. `row' must be in the range

                  0:nmrows-1

               where `nmrows' is the matching row count returned
               by cspice_ekfind.

   the call:

      eknelt = cspice_eknelt( selidx, row )

   returns:

      eknelt   the number of elements in the column entry belonging to the
               specified column in the current row.

               help, eknelt
                  LONG = Scalar

               Null entries in variable-size columns are considered to have
               size 1.

Parameters


   None.

Examples


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

   1) This example demonstrates how to fetch integer, double
      precision and character string values from a column when such
      column corresponds to either a variable-size array or to a
      static-size array.

      Create an EK that contains a table TAB that has the following
      columns:

          Column name   Data Type   Size
          -----------   ---------   ----
          IARRAY        INT         3
          DARRAY        DP          VARIABLE
          CARRAY        CHR         VARIABLE

      Issue the following query

          query = 'SELECT IARRAY, DARRAY, CARRAY FROM TAB'

      to fetch and dump column values from the rows that satisfy the
      query.


      Example code begins here.


      PRO eknelt_ex1

         ;;
         ;; Local parameters
         ;;
         EKNAME     = 'eknelt_ex1.bdb'
         TABLE      = 'TAB'
         CHRSLN     = 6
         COL1SZ     = 3
         MXC2SZ     = 4
         MXC3SZ     = 7
         NCOLS      = 3
         NROWS      = 4
         STRSIZ     = 31
         SPICEFALSE = 0L

         ;;
         ;; Local variables
         ;;
         cnames = strarr( NCOLS  )
         cdecls = strarr( NCOLS  )
         col3   = strarr( MXC3SZ )
         cvals  = strarr( MXC3SZ )

         col1   = lonarr( COL1SZ )
         ivals  = lonarr( COL1SZ )

         col2   = dblarr( MXC2SZ )
         dvals  = dblarr( MXC2SZ )

         ;;
         ;; Open a new EK file.  For simplicity, we will not
         ;; reserve any space for the comment area, so the
         ;; number of reserved comment characters is zero.
         ;; The variable `ifname' is the internal file name.
         ;;
         nresvc  =  0
         ifname  =  'Test EK/Created 13-JUN-2019'

         cspice_ekopn, EKNAME, ifname, nresvc, handle

         ;;
         ;; Set up the column names and declarations
         ;; for the TAB segment.  We'll index all of
         ;; the columns.
         ;;
         cnames[0] = 'IARRAY'
         cdecls[0] = 'DATATYPE = INTEGER, SIZE = 3'

         cnames[1] = 'DARRAY'
         cdecls[1] = 'DATATYPE = DOUBLE PRECISION, SIZE = VARIABLE'

         cnames[2] = 'CARRAY'
         cdecls[2] = 'DATATYPE = CHARACTER*(5), SIZE = VARIABLE'

         ;;
         ;; Start the segment.
         ;;
         cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno

         ;;
         ;; At the records to the table.
         ;;
         for i=0, NROWS-1L do begin

            ;;
            ;; Append a new record to the EK.
            ;;
            cspice_ekappr, handle, segno, recno

            ;;
            ;; Add 3 items to IARRAY
            ;;
            for j=0, COL1SZ - 1L do begin

               col1[j] =  i+1 + (j+1)*100

            endfor

            cspice_ekacei, handle, segno, recno,     cnames[0],              $
                           COL1SZ, col1,  SPICEFALSE

            ;;
            ;; Add i+1 items to DARRAY
            ;;
            for j=0, i do begin

               col2[j] = j+1 + (i+1)*200.0d

            endfor

            cspice_ekaced, handle, segno, recno,     cnames[1],              $
                           i+1,    col2,  SPICEFALSE

            ;;
            ;; Add 4+i items to CARRAY
            ;;
            for j=0, 3+i do begin

               col3[j] = STRING( format='(%"ST%d")', j+1 + (i+1)*100 )

            endfor

            cspice_ekacec, handle, segno,  recno, cnames[2],                 $
                           i+4,    CHRSLN, col3,  SPICEFALSE

         endfor

         ;;
         ;; Close the file.
         ;;
         cspice_ekcls, handle

         ;;
         ;; Open the created file. Perform the query and show the
         ;; results.
         ;;
         cspice_furnsh, EKNAME

         query = 'SELECT IARRAY, DARRAY, CARRAY FROM TAB'

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

         ;;
         ;; Check whether an error occurred while processing the
         ;; SELECT clause. If so, output the error message.
         ;;
         if ( error ) then begin

            print, 'SELECT clause error: ', errmsg

         endif else begin

            for row=0, nmrows-1L do begin

               print, ' '
               print, format='(A,I3)', 'ROW  = ', row

               ;;
               ;; Fetch values from column IARRAY in the current
               ;; row.  Since IARRAY was the first column selected,
               ;; the selection index `selidx' is set to 0.
               ;;
               selidx = 0
               eltidx = 0
               isnull = SPICEFALSE

               while ( ( eltidx lt COL1SZ ) && ( ~isnull ) ) do begin

                  ;;
                  ;; If the column entry is null, we'll be kicked
                  ;; out of this loop after the first iteration.
                  ;;
                  cspice_ekgi, selidx, row,    eltidx,                       $
                               ival,   isnull, found
                  ivals[eltidx] = ival

                  eltidx = eltidx + 1

               endwhile

               print, format='(A,$)', '  COLUMN = IARRAY:'

               if ( isnull ) then begin

                  print, '<Null>'

               endif else begin

                  for i=0,COL1SZ-1L do begin

                     print, format='(I6,$)', ivals[i]

                  endfor

                  print, ' '

               endelse

               ;;
               ;; Fetch values from column DARRAY in the current
               ;; row.  Since DARRAY contains variable-size array
               ;; elements, we call cspice_eknelt to determine how many
               ;; elements to fetch.
               ;;
               selidx = 1
               nelt   = cspice_eknelt( selidx, row )

               eltidx = 0
               isnull = SPICEFALSE

               while ( ( eltidx lt nelt ) && ( ~isnull ) ) do begin

                  cspice_ekgd, selidx, row,    eltidx,                       $
                               dval,   isnull, found
                  dvals[eltidx] = dval

                  eltidx = eltidx + 1

               endwhile

               print, format='(A,$)', '  COLUMN = DARRAY:'

               if ( isnull ) then begin

                  print, '<Null>'

               endif else begin

                  for i=0,nelt-1L do begin

                     print, format='(F6.1,$)', dvals[i]

                  endfor

                  print, ' '

               endelse

               ;;
               ;; Fetch values from column CARRAY in the current
               ;; row.
               ;;
               selidx = 2
               nelt   = cspice_eknelt( selidx, row )

               eltidx = 0
               isnull = SPICEFALSE

               while ( ( eltidx lt nelt ) && ( ~isnull ) ) do begin

                  cspice_ekgc, selidx, row,    eltidx, STRSIZ,               $
                               cval,   isnull, found
                  cvals[eltidx] = cval

                  eltidx = eltidx + 1

               endwhile

               print, format='(A,$)', '  COLUMN = CARRAY:'

               if ( isnull ) then begin

                  print, '<Null>'

               endif else begin

                  for i=0,nelt-1L do begin

                     print, format='(X,A,$)', cvals[i]

                  endfor

                  print, ' '

               endelse

            endfor

            ;;
            ;; We either parsed the SELECT clause or had an error.
            ;;
         endelse

         ;;
         ;; It's always good form to unload kernels after use,
         ;; particularly in IDL due to data persistence.
         ;;
         cspice_kclear

      END


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


      ROW  =   0
        COLUMN = IARRAY:   101   201   301
        COLUMN = DARRAY: 201.0
        COLUMN = CARRAY: ST101 ST102 ST103 ST104

      ROW  =   1
        COLUMN = IARRAY:   102   202   302
        COLUMN = DARRAY: 401.0 402.0
        COLUMN = CARRAY: ST201 ST202 ST203 ST204 ST205

      ROW  =   2
        COLUMN = IARRAY:   103   203   303
        COLUMN = DARRAY: 601.0 602.0 603.0
        COLUMN = CARRAY: ST301 ST302 ST303 ST304 ST305 ST306

      ROW  =   3
        COLUMN = IARRAY:   104   204   304
        COLUMN = DARRAY: 801.0 802.0 803.0 804.0
        COLUMN = CARRAY: ST401 ST402 ST403 ST404 ST405 ST406 ST407


      Note that after run completion, a new EK file exists in the
      output directory.

Particulars


   This routine is meant to be used in conjunction with the EK
   fetch entry points cspice_ekgc, cspice_ekgd, and cspice_ekgi
   allowing the caller of those routines to determine appropriate
   loop bounds to use to fetch each column entry in the current row.

Exceptions


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

   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.

   3)  If `row' 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.

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

   5)  If any of the input arguments, `selidx' or `row', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy 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_eklef.

   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


   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.4, 10-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard. Updated code example to
       not require any existing EK.

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

       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.3, 24-APR-2010 (EDW)

       Minor edit to code comments eliminating typo.
       Implemented a complete code example.

   -Icy Version 1.0.2, 03-FEB-2008 (EDW)

       Completed the previously empty -I/O section. Edited the header
       for clarity.

   -Icy Version 1.0.1, 09-DEC-2005 (EDW)

       Added -Examples section.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries


   return the number of elements in a column entry



Fri Dec 31 18:43:04 2021