Index Page
cspice_ekgc
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_EKGC returns an element of string (character) data from a
   specified row in a specified column of the set of rows matching 
   the previous cspice_ekfind SELECT query.

   For important details concerning this module's function, please refer to
   the CSPICE routine ekgc_c.

I/O

   
   Given:
   
      selidx   the scalar integer index for a column of interest
               satisfying the SELECT clause, the column indices
               range from 0 to N-1 where N equals the total number
               of columns satisfying the SELECT clause.
               
      row      the scalar integer index for a row in the column
               identified by 'selidx', the column indices
               range from 0 to M-1 where M equals the total number
               of rows satisfying the SELECT clause.
               
      elment   the scalar integer index for a element of 
               the data at the 'selidx','row' position; a scalar
               value at 'selidx','row' has 'elment' value zero.
   
      lenout   the scalar integer defining the maximum length of the
               'cdata' output string.
   
   the call:
   
      cspice_ekgc, selidx, row, elment, lenout, cdata, null, found
   
   returns:
   
      cdata    the string value of the requested element at
               data location 'selidx', 'row', 'elment'.
   
      null     a scalar boolean indicating if the 'idata' has a null value.
      
      found    a scalar boolean indicating whether the specified 
               value at 'selidx', 'row', 'elment' was found.
   

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.

      ;;
      ;; Assign an EK file to load and a max string size
      ;; for the cspice_ekgc return string.
      ;;
      EK     = 'test_file.ek'
      MAXSTR = 1025
   
      ;;
      ;; Load the EK.
      ;;
      cspice_furnsh, EK
   
      ;;
      ;; Assume the file test_file.ek contains the table 'scalar_2',
      ;; and that "scalar_2' has the column named 'c_col_1' of scalar
      ;; strings.
      ;;
      ;; Define a set of constraints to perform a query on all
      ;; loaded EK file (the SELECT clause). In this case select 
      ;; the column "c_col_1" from table "scalar_2."
      ;;
      query = "Select c_col_1 from scalar_2 order by row_no"
   
      ;;
      ;; Query the EK system for data rows matching the
      ;; SELECT restraints.
      ;;
      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
   
      ;;
      ;; Loop over each row found to match the query.
      ;;
      for rowno = 0, (nmrows-1) do begin
   
         ;;
         ;; Fetch the character data. We know the query returned
         ;; one column and the column contains only scalar data, 
         ;; so the index of all elements is 0.
         ;;
         selidx = 0
         eltidx = 0
   
         ;;
         ;; Use cspice_ekgc to retrieve the string from 
         ;; row/column position.
         ;;
         cspice_ekgc, selidx, rowno, eltidx, MAXSTR, cdata, isnull, found
   
         ;;
         ;; Output the value, if non-null data exists at the 
         ;; requested position.
         ;;
         if ( NOT isnull ) then begin
            print, 'Character data: ', cdata
         endif
   
      endfor
   
      ;;
      ;; Unload the EK. Note, you don't normally unload an EK
      ;; after a query, rather at the end of a program.
      ;;
      cspice_unload, EK
   
   IDL outputs:
   
      Character data: SEG_2_C_COL_1_ROW_1
      Character data: SEG_2_C_COL_1_ROW_2
      Character data: SEG_2_C_COL_1_ROW_3
      Character data: SEG_2_C_COL_1_ROW_4
      Character data: SEG_2_C_COL_1_ROW_5
      Character data: SEG_2_C_COL_1_ROW_6
      Character data: SEG_2_C_COL_1_ROW_7
      Character data: SEG_2_C_COL_1_ROW_8
      Character data: SEG_2_C_COL_1_ROW_9
      Character data: SEG_2_C_COL_1_ROW_10
      Character data: SEG_2_C_COL_1_ROW_11
      Character data: SEG_2_C_COL_1_ROW_12
      Character data: SEG_2_C_COL_1_ROW_13
      Character data: SEG_2_C_COL_1_ROW_14
      Character data: SEG_2_C_COL_1_ROW_15
      Character data: SEG_2_C_COL_1_ROW_16
      Character data: SEG_2_C_COL_1_ROW_17
      Character data: SEG_2_C_COL_1_ROW_18
      Character data: SEG_2_C_COL_1_ROW_19
      Character data: SEG_2_C_COL_1_ROW_20

Particulars


   If a SELECT clause returns data consisting of three 
   columns (N=3) and four rows (M=4),
               
              col 0    col 1    col 2
               
      row 0   val_00   val_01   val_02 
      row 1   val_10   val_11   val_12
      row 2   val_20   val_21   val_22
      row 3   val_30   val_31   val_32
   
   with "col 1" and "col 2" containing scalar string data
   and the "val_31" a vector of K strings, the data position
   relates to the data:
              
   fetch scalar "val_21"
   
      'selidx' = 1, 'row' = 2, 'elment' = 0
   
   fetch scalar "val_32"
              
      'selidx' = 2, 'row' = 3, 'elment' = 0
   
   fetch the final element of vector "val_31"
              
      'selidx' = 1, 'row' = 3, 'elment' = K-1
   
   'elment' is allowed to exceed the number of elements in 
   the column entry; if it does, 'found' returns
   as SPICEFALSE.  This allows the caller to read data 
   from the column entry in a loop without checking the 
   number of available elements first.

Required Reading


   ICY.REQ
   EK.REQ

Version


   -Icy Version 1.0.1, 24-JAN-2010, EDW (JPL)

      Corrected errors in the description of the indices behavior
      as given in 'elment' argument. That description is now
      in the "Particulars" section.

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

Index_Entries

 
   fetch element from character column entry 
 



Wed Apr  5 17:58:00 2017