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 ekrcec_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
       ekrcec_c ( EK, read column entry element, character )

       void ekrcec_c ( SpiceInt           handle,
                       SpiceInt           segno,
                       SpiceInt           recno,
                       ConstSpiceChar   * column,
                       SpiceInt           cvalen,
                       SpiceInt         * nvals,
                       void             * cvals,
                       SpiceBoolean     * isnull )
#### Abstract
       Read data from a character column in a specified EK record.
#### Required_Reading
       EK
#### Keywords
       EK
       FILES
       UTILITY
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       handle     I   Handle attached to EK file.
       segno      I   Index of segment containing record.
       recno      I   Record from which data is to be read.
       column     I   Column name.
       cvalen     I   Maximum length of output strings.
       nvals      O   Number of values in column entry.
       cvals      O   Character values in column entry.
       isnull     O   Flag indicating whether column entry is null.
#### Detailed_Input
       handle      is an EK file handle. The file may be open for
                   read or write access.

       segno       is the index of the segment from which data is to
                   be read. The first segment in the file has index 0.

       recno       is the index of the record from which data is to be
                   read. This record number is relative to the start
                   of the segment indicated by segno; the first
                   record in the segment has index 0.

       column      is the name of the column from which data is to be
                   read.

       cvalen      is the maximum string length that can be accommodated in
                   the output array cvals. This length must large enough to
                   hold the longest element of the specified column entry,
                   including a null terminator. If the column element contains
                   strings of length up to n characters, `cvalen' should be set
                   to n + 1.
#### Detailed_Output
       nvals,
       cvals       are, respectively, the number of values found in
                   the specified column entry and the set of values
                   themselves. The array cvals must have sufficient
                   string length to accommodate the longest string
                   in the returned column entry. The calling application
                   should declare `cvals' with dimension

                      [nelts][cvalen]

                   where `nelts' is the maximum number of elements that
                   occur in any entry of the specified column.

                   For columns having fixed-size entries, when a
                   a column entry is null, `nvals' is still set to the
                   column entry size. For columns having variable-
                   size entries, `nvals' is set to 1 for null entries.

       isnull      is a logical flag indicating whether the returned
                   column entry is null.
#### Parameters
       None.
#### Exceptions
       1)  If `handle' is invalid, an error is signaled by a routine in the
           call tree of this routine.

       2)  If `segno' is out of range, an error is signaled by a routine in
           the call tree of this routine.

       3)  If `recno' is out of range, an error is signaled by a routine in
           the call tree of this routine.

       4)  If `column' is not the name of a declared column, an error
           is signaled by a routine in the call tree of this routine.

       5)  If `column' specifies a column of whose data type is not
           character, the error SPICE(WRONGDATATYPE) is signaled by a
           routine in the call tree of this routine.

       6)  If `column' specifies a column of whose class is not a character
           class known to this routine, the error SPICE(NOCLASS) is
           signaled by a routine in the call tree of this routine.

       7)  If an attempt is made to read an uninitialized column entry,
           an error is signaled by a routine in the call tree of this
           routine. A null entry is considered to be initialized, but
           entries do not contain null values by default.

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

       9)  If any element of the column entry would be truncated when
           assigned to an element of `cvals', an error is signaled by a
           routine in the call tree of this routine.

       10) If the `column' input string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       11) If the `column' input string has zero length, the error
           SPICE(EMPTYSTRING) is signaled.

       12) If the `cvals' output string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       13) If the `cvals' output string has length less than two
           characters, the error SPICE(STRINGTOOSHORT) is signaled, since
           the output string is too short to contain one character of
           output data plus a null terminator.
#### Files
       See the EK Required Reading for a discussion of the EK file
       format.
#### Particulars
       This routine is a utility that allows an EK file to be read
       directly without using the high-level query interface.
#### 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) The following program demonstrates how to create a new EK and
          add data to a character column in a given record within the
          file, and how to read the data from it.

          Example code begins here.

          /.
             Program ekrcec_ex1
          ./
          #include <stdio.h>
          #include <string.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local constants.
             ./
             #define EKNAME       "ekrcec_ex1.bdb"
             #define IFNAME       "Test EK"
             #define TABLE        "CHR_DATA"
             #define CVLEN        10
             #define DECLEN       201
             #define MAXVAL       4
             #define NCOLS        2
             #define NROWS        6
             #define NRESVC       0

             /.
             Local variables
             ./
             SpiceChar            cdecls [NCOLS] [DECLEN];
             SpiceChar            cnames [NCOLS] [SPICE_EK_CSTRLN];
             SpiceChar            cvals  [MAXVAL][CVLEN];

             SpiceInt             handle;
             SpiceInt             i;
             SpiceInt             nvals;
             SpiceInt             recno;
             SpiceInt             segno;

             SpiceBoolean         isnull;

             /.
             Open a new EK file.  For simplicity, we won't
             reserve space for the comment area, so the
             number of reserved comment characters is zero.
             The constant IFNAME is the internal file name.
             ./
             ekopn_c ( EKNAME, IFNAME, NRESVC, &handle );

             /.
             Set up the table and column names and declarations
             for the CHR_DATA segment.  We'll index all of
             the columns.
             ./
             strcpy( cnames[0], "CHR_COL_1" );
             strcpy( cdecls[0], "DATATYPE = CHARACTER*(*), "
                                "INDEXED = TRUE, NULLS_OK = TRUE" );

             strcpy( cnames[1], "CHR_COL_2" );
             strcpy( cdecls[1], "DATATYPE = CHARACTER*(9), "
                                "SIZE = VARIABLE, NULLS_OK = TRUE" );

             /.
             Start the segment.
             ./
             ekbseg_c ( handle, TABLE,  NCOLS,   SPICE_EK_CSTRLN,
                        cnames, DECLEN, cdecls, &segno           );

             for ( i = 0; i < NROWS; i++ )
             {

                ekappr_c ( handle, segno, &recno );

                isnull = ( i == 1 );

                sprintf  ( cvals[0], "%d", i );
                ekacec_c ( handle, segno, recno, cnames[0],
                           1,      CVLEN, cvals, isnull    );

                /.
                Array-valued columns follow.
                ./
                sprintf  ( cvals[0], "%d", 10*i     );
                sprintf  ( cvals[1], "%d", 10*i + 1 );
                sprintf  ( cvals[2], "%d", 10*i + 2 );
                sprintf  ( cvals[3], "%d", 10*i + 3 );
                ekacec_c ( handle, segno, recno, cnames[1],
                           4,      CVLEN, cvals, isnull    );

             }

             /.
             End the file.
             ./
             ekcls_c ( handle );

             /.
             Open the created file. Show the values added.
             ./
             ekopr_c ( EKNAME, &handle );

             for ( i = 0; i < NROWS; i++ )
             {

                ekrcec_c ( handle, segno, i,      cnames[0],
                           CVLEN, &nvals, cvals, &isnull    );

                if ( ! isnull )
                {

                   printf( "Data from column:  %s\n", cnames[0] );
                   printf( "   record number:  %d\n", i );
                   printf( "   values       :  %s\n", cvals[0] );
                   printf( " \n" );

                }
                else
                {

                   printf( "Record  %d flag is NULL.\n", i );
                   printf( " \n" );

                }

                /.
                Array-valued columns follow.
                ./
                ekrcec_c ( handle, segno, i,      cnames[1],
                           CVLEN, &nvals, cvals, &isnull    );

                if ( ! isnull )
                {

                   printf( "Data from column:  %s\n", cnames[1] );
                   printf( "   record number:  %d\n", i );
                   printf( "   values       :  %s  %s  %s  %s\n",
                                         cvals[0], cvals[1], cvals[2], cvals[3] );
                   printf( " \n" );

                }

             }

             return ( 0 );
          }

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

          Data from column:  CHR_COL_1
             record number:  0
             values       :  0

          Data from column:  CHR_COL_2
             record number:  0
             values       :  0          1          2          3

          Record  1 flag is NULL.

          Data from column:  CHR_COL_1
             record number:  2
             values       :  2

          Data from column:  CHR_COL_2
             record number:  2
             values       :  20         21         22         23

          Data from column:  CHR_COL_1
             record number:  3
             values       :  3

          Data from column:  CHR_COL_2
             record number:  3
             values       :  30         31         32         33

          Data from column:  CHR_COL_1
             record number:  4
             values       :  4

          Data from column:  CHR_COL_2
             record number:  4
             values       :  40         41         42         43

          Data from column:  CHR_COL_1
             record number:  5
             values       :  5

          Data from column:  CHR_COL_2
             record number:  5
             values       :  50         51         52         53

          Note that the second record does not appear due to setting the
          `isnull' flag to true for that record.

          After run completion, a new EK exists in the output directory.
#### Restrictions
       1)  EK files open for write access are not necessarily readable.
           In particular, a column entry can be read only if it has been
           initialized. The caller is responsible for determining
           when it is safe to read from files open for write access.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       W.L. Taber          (JPL)
#### Version
       -CSPICE Version 1.2.0, 02-AUG-2021 (JDR)

           Changed input argument name "lenout" to "cvalen" for consistency
           with other routines.

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

       -CSPICE Version 1.1.0, 21-MAY-2001 (WLT)

           Added a cast to (char *) in the call to  F2C_ConvertStrArr to
           support compilation under C++.

       -CSPICE Version 1.0.0, 04-JUL-2000 (NJB)
#### Index_Entries
       read character data from EK column
#### Link to routine ekrcec_c source file ekrcec_c.c

    Fri Dec 31 18:41:06 2021