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 ekssum_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

       ekssum_c ( EK, return segment summary )

       void ekssum_c ( SpiceInt           handle,
                       SpiceInt           segno,
                       SpiceEKSegSum    * segsum )

#### Abstract

       Return summary information for a specified segment in a
       specified EK.

#### Required_Reading

       EK

#### Keywords

       EK
       UTILITY

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       handle     I   Handle of EK.
       segno      I   Number of segment to be summarized.
       segsum     O   EK segment summary.

#### Detailed_Input

       handle      is an EK file handle specifying the EK containing
                   the segment to be summarized.

       segno       is the number of the segment whose summary is
                   desired. Segments are numbered from 0 to nseg-1,
                   where nseg is the count of segments in the file.

#### Detailed_Output

       segsum      is a pointer to an EK segment summary. The summary is
                   of type EKSegSum. The structure contains the
                   following members:

                      tabnam      The name of the table to which the
                                  segment belongs.

                      nrows       The number of rows in the segment.

                      ncols       The number of columns in the segment.

                      cnames      An array of names of columns in the
                                  segment. Column names may contain
                                  as many as SPICE_EK_CNAMSZ characters.
                                  The array contains room for
                                  SPICE_EK_MXCLSG column names.

                      cdescrs     An array of column attribute
                                  descriptors of type SpiceEKAttDsc.
                                  The array contains room for
                                  SPICE_EK_MXCLSG descriptors. The Ith
                                  descriptor corresponds to the column
                                  whose name is the Ith element of the
                                  array cnames.

                   The column attribute descriptors have the following
                   members:

                      cclass: Column class code.

                      dtype: Data type code: has type
                                  SpiceEKDataType.

                      strlen: String length. Applies to SPICE_CHR
                                  type. Value is SPICE_EK_VARSIZ for
                                  variable-length strings.

                      size: Column entry size; this is the number
                                  of array elements in a column entry.
                                  The value is SPICE_EK_VARSIZ for
                                  variable-size columns.

                      indexd: Index flag; value is SPICETRUE if the
                                  column is indexed, SPICEFALSE
                                  otherwise.

                      nullok: Null flag; value is SPICETRUE if the
                                  column may contain null values,
                                  SPICEFALSE otherwise.

#### Parameters

       See the -Restrictions section.

#### Exceptions

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

       2)  If `segno' is not the index of an existing segment in the
           specified file, the error SPICE(INDEXOUTOFRANGE) is signaled by
           a routine in the call tree of this routine. The output arguments
           will not be modified.

       3)  If an I/O error occurs while attempting to obtain summary
           information for the specified segment, the error is signaled
           by a routine in the call tree of this routine. The output
           arguments may be modified in this case.

#### Files

       This routine provides summary information for segments belonging
       to a binary EK file.

#### Particulars

       This routine supports the function of summarizing a binary
       EK file, allowing NAIF Toolkit users to determine whether it
       contains data of interest.

#### 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) Dump the attributes of the segments in a specified EK.

          Example code begins here.

          /.
             ekssum_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Constants
             ./
             #define FILSIZ          256

             SpiceChar               ek       [FILSIZ];
             static SpiceChar        chrTypes [4][5] = { "CHR",
                                                         "DP",
                                                         "INT",
                                                         "TIME" };
             SpiceEKSegSum           segsum;

             SpiceInt                handle;
             SpiceInt                i;
             SpiceInt                nseg;
             SpiceInt                segno;

             prompt_c ( "Enter name of EK file > ", FILSIZ, ek );

             /.
             Open the EK for read access and get the number of
             segments it contains.
             ./
             ekopr_c ( ek, &handle );

             nseg = eknseg_c ( handle );

             /.
             Loop through the segments, dumping the desired
             summary information for each one.
             ./
             printf ( "\n"
                      "Segment summary for file %s\n\n",
                      ek                                );

             for ( segno = 0;  segno < nseg;  segno++ )
             {

                ekssum_c (  handle,  segno,  &segsum );

                printf ( "=============================="
                         "=============================="
                         "\n"
                         "Table containing segment:  %s\n"
                         "\n"
                         "Number of rows:     %d\n"
                         "Number of columns:  %d\n"
                         "\n"
                         "Column names and attributes: \n"
                         "\n",
                         segsum.tabnam,
                         segsum.nrows,
                         segsum.ncols                            );

                for ( i = 0;  i < segsum.ncols;  i++ )
                {

                   printf ( "\n"
                            "Column:   %s\n"
                            "\n"
                            "Data type:      %s\n",
                            segsum.cnames[i],
                            chrTypes[ segsum.cdescrs[i].dtype ]     );

                   if ( segsum.cdescrs[i].size >= 0 )
                   {
                      printf ( "Dimension:      %d\n",
                                segsum.cdescrs[i].size );
                   }
                   else
                   {
                      printf ( "Dimension:      Variable\n" );
                   }

                   if ( segsum.cdescrs[i].dtype == SPICE_CHR )
                   {
                      if ( segsum.cdescrs[i].strlen >= 0 )
                      {
                         printf ( "String length:  %d\n",
                                   segsum.cdescrs[i].strlen         );
                      }
                      else
                      {
                         printf ( "String length:  Variable\n" );
                      }
                   }

                   if ( segsum.cdescrs[i].indexd )
                   {
                       printf ( "Indexed\n" );
                   }

                   if ( segsum.cdescrs[i].nullok )
                   {
                       printf ( "Nulls allowed\n" );
                   }

                   printf ( "\n" );

                }

                printf ( "\n"
                         "=============================="
                         "=============================="
                         "\n"                            );
             }

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, using the EK file named dif_cmdict_128_20050620.bdb
          to load the Deep Impact spacecraft subsystem commands dictionary,
          the output was:

          Enter name of EK file > dif_cmdict_128_20050620.bdb

          Segment summary for file dif_cmdict_128_20050620.bdb

          ============================================================
          Table containing segment:  DIF_COMMANDS

          Number of rows:     5798
          Number of columns:  7

          Column names and attributes:

          Column:   SUBSYSTEM

          Data type:      CHR
          Dimension:      1
          String length:  32
          Indexed

          Column:   COMMAND

          Data type:      CHR
          Dimension:      1
          String length:  32
          Indexed

          Column:   PARAMETER_NAME

          Data type:      CHR
          Dimension:      1
          String length:  32
          Indexed

          Column:   PARAMETER_INDEX

          Data type:      INT
          Dimension:      1
          Indexed

          Column:   PARAMETER_TYPE

          Data type:      CHR
          Dimension:      1
          String length:  32
          Nulls allowed

          Column:   PARAMETER_RANGE

          Data type:      CHR
          Dimension:      Variable
          String length:  80
          Nulls allowed

          Column:   DESCRIPTION

          Data type:      CHR
          Dimension:      Variable
          String length:  80

          ============================================================

#### Restrictions

       1)  Many parameters used internally in this routine are from the
           Fortran SPICELIB include files ekcoldsc.inc and eksegdsc.inc.
           The parameters used in this routine must be kept in sync with
           those used in SPICELIB.

#### Literature_References

       None.

#### Author_and_Institution

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

#### Version

       -CSPICE Version 1.1.1, 10-AUG-2021 (JDR)

           Edited the header to comply with NAIF standard.

           Added the solution to the example when using a Deep Impact EK kernel.
           Reformatted example's output.

       -CSPICE Version 1.1.0, 12-JUL-1999 (NJB)

           Now calls zzeksinf_ instead of ekssum_ to get summary
           information. This enables retrieval of column classes and
           simplifies the code as well.

           Changed arrays of SpiceBoolean flags passed to ekssum_ to
           data type logical. Changed name of "class" member of structure
           SpiceEKSegSum to "cclass." The name "class" is a C++ keyword
           and prevented clean integration into C++ code.

       -CSPICE Version 1.0.0, 17-FEB-1999 (NJB)

#### Index_Entries

       return EK segment summary

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

    Fri Dec 31 18:41:06 2021