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_ekops

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


Abstract


   CSPICE_EKOPS creates and opens a scratch E-kernel file then
   prepares the file for writing.

I/O


   The call:

      cspice_ekops, handle

   returns:

      handle   the EK file handle of the file opened by this routine.

               help, handle
                  LONG = Scalar

               This handle is used to identify the file to other EK routines.

Parameters


   SPICE_DAS_FTSIZE

               is the maximum number of DAS files that a user can
               have open simultaneously. This includes any files used
               by the DAS system.

               See the parameter definitions file IcyDAS.pro for the actual
               value of this parameter.

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) Suppose we want to create an E-kernel which contains a table
      of items that have been ordered but we do not want to keep
      the file. The columns of this table are shown below:

         DATAITEMS

            Column Name     Data Type
            -----------     ---------
            ITEM_ID         INTEGER
            ORDER_ID        INTEGER
            ITEM_NAME       CHARACTER*(*)
            DESCRIPTION     CHARACTER*(*)
            PRICE           DOUBLE PRECISION


      This example demonstrates how to open a scratch EK file;
      create the segment described above, how to insert a new record
      into it, and how to summarize its contents.


      Example code begins here.


      PRO ekops_ex1

         ;;
         ;; Local parameters
         ;;
         TABLE     =   'DATAITEMS'
         DESCLN    =   80L

         ;;
         ;; One value per row/column element.
         ;;
         MAXVAL    =   1L
         NAMLEN    =   40L
         COLSLN    =   5L

         EKDTYP    = [ 'CHR', 'DP', 'INT', 'TIME' ]

         SPICEFALSE = 0B
         SPICETRUE  = 1B

         ;;
         ;; Define the EK data types.
         ;;
         SPICE_CHR  = 0
         SPICE_DP   = 1
         SPICE_INT  = 2
         SPICE_TIME = 3

         ;;
         ;; Local variables
         ;;
         cnames = strarr( COLSLN )
         cdecls = strarr( COLSLN )

         ;;
         ;; Open a scratch EK file as we do not want to keep
         ;; the data.
         ;;
         cspice_ekops, handle

         ;;
         ;; Set up the table and column names and declarations
         ;; for the DATAITEMS segment.  We'll index all of
         ;; the columns.  All columns are scalar, so we omit
         ;; the size declaration.
         ;;
         cnames[0] =  'ITEM_ID'
         cdecls[0] =  'DATATYPE = INTEGER, INDEXED = TRUE'

         cnames[1] =  'ORDER_ID'
         cdecls[1] =  'DATATYPE = INTEGER, INDEXED = TRUE'

         cnames[2] =  'ITEM_NAME'
         cdecls[2] =  'DATATYPE = CHARACTER*(*),INDEXED  = TRUE'

         cnames[3] =  'DESCRIPTION'
         cdecls[3] =  'DATATYPE = CHARACTER*(*),INDEXED  = TRUE'

         cnames[4] =  'PRICE'
         cdecls[4] =  'DATATYPE = DOUBLE PRECISION,INDEXED  = TRUE'

         ;;
         ;; Start the segment. Since we have no data for this
         ;; segment, start the segment by just defining the new
         ;; segment's schema.
         ;;
         cspice_ekbseg, handle, TABLE, COLSLN, cnames, cdecls, segno

         ;;
         ;; Append a new, empty record to the DATAITEMS
         ;; table. Recall that the DATAITEMS table
         ;; is in the first segment.  The call will return
         ;; the number of the new, empty record.
         ;;
         segno     = 0L
         cspice_ekappr, handle, segno, recno

         ;;
         ;; At this point, the new record is empty. We fill in the
         ;; data here.  Data items are filled in one column at a
         ;; time. The order in which the columns are filled in is
         ;; not important.  We use the different add column entry
         ;; routines to fill in column entries.  We'll assume
         ;; that no entries are null.  All entries are scalar,
         ;; so the entry size is 1.
         ;;
         isnull    =  SPICEFALSE
         esize     =  1L

         ;;
         ;; The following variables will contain the data for
         ;; the new record.
         ;;
         ordid     =  [10011L]
         itemid    =  [531L]
         itemnm    =  ['Sample item']
         descrp    =  ['This sample item is used only in tests.']
         price     =  [1345.67d0]

         ;;
         ;; Note that the names of the routines called
         ;; correspond to the data types of the columns.
         ;;
         cspice_ekacei, handle, segno, recno, 'ORDER_ID', esize, ordid, isnull

         cspice_ekacei, handle, segno, recno, 'ITEM_ID', esize, itemid, isnull

         cspice_ekacec, handle, segno,  recno,  'ITEM_NAME',                 $
                        esize,  NAMLEN, itemnm, isnull

         cspice_ekacec, handle, segno,  recno,  'DESCRIPTION',               $
                        esize,  DESCLN, descrp, isnull

         cspice_ekaced, handle, segno, recno, 'price', esize, price, isnull

         ;;
         ;; At this point, we could perform read operations
         ;; on the EK.
         ;;
         ;; Return the number of segments in the EK. Dump the
         ;; desired summary information for each one.
         ;;
         nseg = cspice_eknseg( handle )
         print, format='(A,I3)', 'Number of segments =', nseg
         print

         for segno=0L, nseg-1L do begin

            cspice_ekssum, handle, segno,  nrows, ncols,  tabnam, cnames,    $
                           cclass, dtypes, sizes, strlen, indexd, nullok

            print, format='(2A)',   'Table containing segment: ', tabnam
            print, format='(A,I2)', 'Number of rows          : ', nrows
            print, format='(A,I2)', 'Number of columns       : ', ncols
            print, format='(A)',    'Table data              : '

            for i=0L, ncols-1L do begin

               print, format='(2A)', '  Column: ', cnames[i]
               print, format='(2A)', '  Type  : ', EKDTYP[ dtypes[i] ]

               for recno=0L, nrows-1L do begin

                  if ( dtypes[i] eq SPICE_CHR ) then begin

                     cspice_ekrcec, handle, segno,  recno, cnames[i],        $
                                    MAXVAL, NAMLEN, cvals, isnull

                     if ( isnull ) then begin

                        print, format='(A)', '  Data  : <null>'

                     endif else begin

                        print, format='(2A)', '  Data  : ', cvals

                     endelse

                  endif else if ( dtypes[i] eq SPICE_DP ) then begin

                     cspice_ekrced, handle, segno, recno, cnames[i],         $
                                    MAXVAL, dvals, isnull

                     if ( isnull ) then begin

                        print, format='(A)', '  Data  : <null>'

                     endif else begin

                        print, format='(A,F9.2)', '  Data  : ', dvals[0]

                     endelse

                  endif else if ( dtypes[i] eq SPICE_INT ) then begin

                     cspice_ekrcei, handle, segno, recno, cnames[i],         $
                                    MAXVAL, ivals, isnull

                     if ( isnull ) then begin

                        print, format='(A)', '  Data  : <null>'

                     endif else begin

                        print, format='(A,I6)', '  Data  : ', ivals[0]

                    endelse

                  endif

                  ;;
                  ;; There is no time data. Otherwise, we would need
                  ;; to use a LSK and cspice_ekrced to read it
                  ;; (internally, it is stored as double precision).
                  ;;
                  print

               endfor

            endfor

            print, '----------------------------------------'

         endfor

         ;;
         ;; Close the file. This will delete the scratch file
         ;; and all the data will be lost.
         ;;
         cspice_ekcls, handle

      END


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


      Number of segments =  1

      Table containing segment: DATAITEMS
      Number of rows          :  1
      Number of columns       :  5
      Table data              :
        Column: ITEM_ID
        Type  : INT
        Data  :    531

        Column: ORDER_ID
        Type  : INT
        Data  :  10011

        Column: ITEM_NAME
        Type  : CHR
        Data  : Sample item

        Column: DESCRIPTION
        Type  : CHR
        Data  : This sample item is used only in tests.

        Column: PRICE
        Type  : DP
        Data  :   1345.67

      ----------------------------------------


      Note that after run completion, there is no EK file in the
      output directory as scratch files are deleted when they are
      closed or when the calling program terminates.

Particulars


   This routine operates by side effects: it opens and prepares
   an EK for addition of data. "Scratch" files are automatically
   deleted when closed using the Icy routine cspice_ekcls.

   Note: An issue may exist when using EK scratch files from
   IDL on Microsoft Windows. It seems the cspice_ekcls call may
   fail to delete the scratch file created by the cspice_ekops
   call. This file normally has a name format similar to
   tmp.Fxxxxx. You can manually delete the file only after you
   close the IDL application.

   This problem does not affect use of the file or cause any
   known instability to Icy.

Exceptions


   1)  If the indicated file cannot be opened, an error is signaled
       by a routine in the call tree of this routine. The new file
       will be deleted.

   2)  If an i/o error occurs while reading or writing the indicated
       file, the error is signaled by a routine in the call tree of
       this routine.

   3)  If the output argument `handle' is not a named variable, an
       error is signaled by the Icy interface.

Files


   This routine creates a temporary EK file; the file is deleted
   when the calling program terminates or when the file is closed
   using the Icy routine cspice_ekcls.

   See the EK Required Reading ek.req for a discussion of the EK file
   format.

Restrictions


   1)  No more than SPICE_DAS_FTSIZE DAS files may be opened simultaneously.
       See the parameter definitions file IcyDAS.pro for the value of
       SPICE_DAS_FTSIZE.

Required_Reading


   ICY.REQ
   EK.REQ
   ICY.REQ

Literature_References


   None.

Author_and_Institution


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

Version


   -Icy Version 1.0.2, 17-APR-2021 (JDR)

       Edited the header to comply with NAIF standard. Added complete
       code example.

       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 argument's type and size information in the -I/O section.

   -Icy Version 1.0.1, 11-NOV-2005 (EDW)

       Added mention of the scratch file retention issue on
       Microsoft Windows.

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

Index_Entries


   open scratch E-kernel
   open scratch EK



Fri Dec 31 18:43:04 2021