ekssum_c

Index Page ekssum_c
A B C D E F G H I J K L M N O P Q R S T U V W X
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
       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, the error will be diagnosed by routines
           called by 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) will be
           signalled.  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 will be
           diagnosed by routines called by 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
       1)  Dump the attributes of the segments in a specified EK.

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

              void main()
              {

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

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

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

                 /.
                 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"
                          "\n"
                          "Segment summary for file %s\n"
                          "\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"                                       );
                 }
              }
#### Restrictions
       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)
#### Version
       -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

    Thu Apr 16 08:57:59 2009