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 ekappr_c

Table of contents

Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

       ekappr_c ( EK, append record onto segment )

       void ekappr_c ( SpiceInt     handle,
                       SpiceInt     segno,
                       SpiceInt   * recno  )

#### Abstract

       Append a new, empty record at the end of a specified E-kernel
       segment.

#### Required_Reading

       EK

#### Keywords

       PRIVATE
       UTILITY

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       handle     I   File handle.
       segno      I   Segment number.
       recno      O   Number of appended record.

#### Detailed_Input

       handle      is a file handle of an EK open for write access.

       segno       is the number of the segment to which the record
                   is to be added. EK segment numbers range from
                   zero to N-1, where N is the number of segments
                   in the kernel.

#### Detailed_Output

       recno       is the number of the record appended by this
                   routine. recno is used to identify the record
                   when writing column entries to it. EK record
                   numbers range from 0 to N-1, where N is the
                   number of records in the segment containing
                   the record.

#### Parameters

       None.

#### Exceptions

       1)  If `handle' is invalid, an error is signaled by a routine in the
           call tree of this routine. The file will not be modified.

       2)  If `segno' is out of range, the error SPICE(INVALIDINDEX) is
           signaled by a routine in the call tree of this routine. The
           file will not be modified.

       3)  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. The file may be corrupted.

#### Files

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

#### Particulars

       This routine operates by side effects: It appends a new, empty
       record structure to an EK segment. The ordinal position of the
       new record is one greater than the previous number of records in
       in the segment.

       After a new record has been appended to a segment by this routine,
       the record must be populated with data using the ekaceX_c
       routines.  EKs are valid only when all of their column entries
       are initialized.

       To insert a record into a segment at a specified ordinal position,
       use the routine ekappr_c.

       This routine cannot be used with the "fast write" suite of
       routines. See the EK Required Reading for a discussion of the
       fast writers.

#### Examples

       The numerical results shown for this example may differ across
       platforms. The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       1)  Append a record to a specified segment.

          Suppose we have an E-kernel which contains records of orders
          for data products. The E-kernel has a table called DATAORDERS
          that consists of the set of columns listed below:

             DATAORDERS

                Column Name     Data Type
                -----------     ---------
                ORDER_ID        INTEGER
                CUSTOMER_ID     INTEGER
                LAST_NAME       CHARACTER*(*)
                FIRST_NAME      CHARACTER*(*)
                ORDER_DATE      TIME
                COST            DOUBLE PRECISION

          The order database also has a table of items that have been
          ordered. 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

          We'll suppose that the EK file contains two segments, the
          first containing the DATAORDERS table and the second
          containing the DATAITEMS table.

          This examples creates such EK, with no records in either
          table, and after re-opening the file, inserts a new record
          into the DATAITEMS table.

          Example code begins here.

          /.
             Program ekappr_ex1
          ./
          #include <string.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local parameters
             ./
             #define EKNAME       "ekappr_ex1.bdb"
             #define DECLEN       201
             #define DESCLN       81
             #define NAMLEN       41
             #define NCOLS        6

             /.
             Local variables
             ./
             SpiceChar            cdecls [NCOLS] [DECLEN];
             SpiceChar            cnames [NCOLS] [SPICE_EK_CSTRLN];
             SpiceChar          * descrp;
             SpiceChar          * ifname;
             SpiceChar          * itemnm;

             SpiceDouble          price;

             SpiceInt             esize;
             SpiceInt             handle;
             SpiceInt             itemid;
             SpiceInt             nresvc;
             SpiceInt             ordid;
             SpiceInt             recno;
             SpiceInt             segno;

             SpiceBoolean         isnull;

             /.
             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 01-JUN-2019";

             ekopn_c ( EKNAME, ifname, nresvc, &handle );

             /.
             Set up the table and column names and declarations
             for the DATAORDERS segment.  We'll index all of
             the columns.  All columns are scalar, so we omit
             the size declaration.  Only the COST column may take
             null values.
             ./
             strcpy( cnames[0], "ORDER_ID" );
             strcpy( cdecls[0], "DATATYPE = INTEGER, INDEXED = TRUE" );

             strcpy( cnames[1], "CUSTOMER_ID" );
             strcpy( cdecls[1], "DATATYPE = INTEGER, INDEXED = TRUE" );

             strcpy( cnames[2], "LAST_NAME" );
             strcpy( cdecls[2], "DATATYPE = CHARACTER*(*), INDEXED  = TRUE" );

             strcpy( cnames[3], "FIRST_NAME" );
             strcpy( cdecls[3], "DATATYPE = CHARACTER*(*), INDEXED  = TRUE" );

             strcpy( cnames[4], "ORDER_DATE" );
             strcpy( cdecls[4], "DATATYPE = TIME, INDEXED  = TRUE" );

             strcpy( cnames[5], "COST" );
             strcpy( cdecls[5], "DATATYPE = DOUBLE PRECISION, "
                                "INDEXED  = TRUE, NULLS_OK = TRUE" );

             /.
             Start the first segment. Since we have no data for this
             segment, start the segment by just defining the new
             segment's schema.
             ./
             ekbseg_c ( handle, "DATAORDERS", NCOLS,   SPICE_EK_CSTRLN,
                        cnames,  DECLEN,      cdecls, &segno           );

             /.
             At this point, the second segment could be
             created by an analogous process.  In fact, the
             second segment could be created at any time; it is
             not necessary to populate the first segment with
             data before starting the second segment.

             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.
             ./
             strcpy( cnames[0], "ITEM_ID" );
             strcpy( cdecls[0], "DATATYPE = INTEGER, INDEXED = TRUE" );

             strcpy( cnames[1], "ORDER_ID" );
             strcpy( cdecls[1], "DATATYPE = INTEGER, INDEXED = TRUE" );

             strcpy( cnames[2], "ITEM_NAME" );
             strcpy( cdecls[2], "DATATYPE = CHARACTER*(*), INDEXED  = TRUE" );

             strcpy( cnames[3], "DESCRIPTION" );
             strcpy( cdecls[3], "DATATYPE = CHARACTER*(*), INDEXED  = TRUE" );

             strcpy( cnames[4], "PRICE" );
             strcpy( cdecls[4], "DATATYPE = DOUBLE PRECISION, INDEXED  = TRUE" );

             /.
             Start the new segment. Since we have no data for this
             segment, start the segment by just defining the new
             segment's schema.
             ./
             ekbseg_c ( handle, "DATAITEMS", 5,       SPICE_EK_CSTRLN,
                        cnames,  DECLEN,     cdecls, &segno           );

             /.
             End the file by a call to ekcls_c.
             ./
             ekcls_c ( handle );

             /.
             Now, we want to insert a new record into the DATAITEMS
             table.

             Open the database for write access.  This call is
             made when the file already exists.
             ./
             ekopw_c ( EKNAME, &handle );

             /.
             Append a new, empty record to the DATAITEMS
             table. Recall that the DATAITEMS table
             is in segment number 1.  The call will return
             the number of the new, empty record.
             ./
             segno = 1;
             ekappr_c ( handle, segno, &recno );

             /.
             At this point, the new record is empty.  A valid EK
             cannot contain empty records.  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 ekaceX_c (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    =  1;

             /.
             The following variables will contain the data for
             the new record.
             ./
             ordid    =   10011;
             itemid   =   531;
             itemnm   =  "Sample item";
             descrp   =  "This sample item is used only in tests.";
             price    =   1345.678;

             /.
             Note that the names of the routines called
             correspond to the data types of the columns:  the
             last letter of the routine name is C, `i', or D,
             depending on the data type.
             ./
             ekacei_c ( handle,  segno, recno, "ORDER_ID",
                        esize,  &ordid, isnull            );

             ekacei_c ( handle,  segno,  recno, "ITEM_ID",
                        esize,  &itemid, isnull           );

             ekacec_c ( handle, segno,  recno,  "ITEM_NAME",
                        esize,  NAMLEN, itemnm,  isnull     );

             ekacec_c ( handle, segno,  recno,  "DESCRIPTION",
                        esize,  DESCLN, descrp,  isnull       );

             ekaced_c ( handle, segno, recno, "PRICE", esize, &price, isnull );

             /.
             Close the file to make the update permanent.
             ./
             ekcls_c ( handle );

             return ( 0 );
          }

          When this program is executed, no output is presented on
          screen. After run completion, a new EK file exists in the
          output directory.

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)

#### Version

       -CSPICE Version 1.0.1, 24-NOV-2021 (JDR)

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

       -CSPICE Version 1.0.0, 09-JAN-2002 (NJB)

#### Index_Entries

       append record to EK segment

#### Link to routine ekappr_c source file ekappr_c.c

    Fri Dec 31 18:41:05 2021