Exemple #1
0
   void tpictr_c ( ConstSpiceChar * sample,
                   SpiceInt         lenout,
                   SpiceInt         lenerr,
                   SpiceChar      * pictur,
                   SpiceBoolean   * ok,
                   SpiceChar      * errmsg )
/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   sample     I   A sample time string.
   lenout     I   The length for the output picture string.
   lenerr     I   The length for the output error string.
   pictur     O   A format picture that describes sample.
   ok         O   Flag indicating whether sample parsed successfully.
   errmsg     O   Diagnostic returned if sample cannot be parsed.

-Detailed_Input


   sample     is a representative time string to use as a model to
              format time strings.

   lenout     is the allowed length for the output picture.  This length
              must large enough to hold the output string plus the null
              terminator.  If the output string is expected to have x
              characters, lenout needs to be x + 1.  80 is a reasonable
              value for lenout (79 characters plus the null
              terminator).  

   lenerr     is the allowed length for the output error string.    
   
   
-Detailed_Output


   pictur     is a format picture suitable for use with the SPICE
              routine timout_c.  This picture, when used to format an
              epoch via timout_c, will yield the same time components in
              the same order as the components in sample.

   ok         is a logical flag indicating whether the input format
              sample could be parsed. If all of the components of
              sample are recognizable, ok will be returned with the
              value SPICEFALSE.  If some part of pictur cannot be
              parsed, ok will be returned with the value SPICEFALSE.

   errmsg     is a diagnostic message that indicates what part of
              sample was not recognizable.  If sample was successfully
              parsed, ok will be SPICEFALSE and errmsg will be
              returned as an empty string.

-Parameters

   None.

-Files

   None.

-Exceptions

   Error free.

   1) All problems with the inputs are diagnosed via ok and errmsg.

   2) If a format picture can not be created from the sample
      time string, pictur is returned as a blank string.

-Particulars

   Although the routine timout_c provides CSPICE users with a great
   deal of flexibility in formatting time strings, users must
   master the means by which a time picture is constructed
   suitable for use by timout_c.

   This routine allows CSPICE users to supply a sample time string
   from which a corresponding time format picture can be created,
   freeing users from the task of mastering the intricacies of
   the routine timout_c.

   Note that timout_c can produce many time strings whose patterns
   can not be discerned by this routine.  When such outputs are
   called for, the user must consult timout_c and construct the
   appropriate format picture "by hand."  However, these exceptional
   formats are not widely used and are not generally recognizable
   to an uninitiated reader.

-Examples

   Suppose you need to print epochs corresponding to some events and
   you wish the epochs to have the same arrangement of components as in
   the string "10:23 P.M. PDT January 3, 1993".

   The following subroutine call will construct the appropriate format
   picture for use with timout_c.

   tpictr_c ( "10:23 P.M. PDT January 3, 1993",
               lenout, lenerr, pictur, &ok, errmsg );

   The resulting picture is:

      "AP:MN AMPM PDT Month DD, YYYY ::UTC-7"

   This picture can be used with timout_c to format a sequence
   of epochs, et[0],...,et[n-1] (given as ephemeris seconds past J2000)
   as shown in the loop below:

      #include "SpiceUsr.h"
          .
          .
          .
      for ( i = 0; i < n; i++ )
      {
         timout_c ( et[i], pictur, string );
         printf ( "Epoch: %d --- %s\n", i, string );
      }

-Restrictions

   None.

-Author_and_Institution
   
   W.L. Taber      (JPL)
   E.D. Wright     (JPL)

-Literature_References

   None.

-Version

   -CSPICE Version 1.0.0, 23-JUL-1999   (EDW) (WLT)

-Index_Entries

   Use a sample time string to produce a time format picture

-&
*/

{ /* Begin tpictr_c */

   /*
   Local variables
   */
   logical                 okeydoke;

   /*
   Participate in error tracing.
   */
   chkin_c ( "tpictr_c" );


   /*
   Check the input string sample to make sure the pointer is non-null
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "tpictr_c", sample );


   /*
   Make sure the output strings have at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "tpictr_c",  pictur, lenout );
   CHKOSTR ( CHK_STANDARD, "tpictr_c",  errmsg, lenerr );


   /* 
   Call the f2c'd routine. 
   */
   tpictr_( ( char    * ) sample,
            ( char    * ) pictur,
            ( logical * ) &okeydoke,
            ( char    * ) errmsg,
            ( ftnlen    ) strlen( sample ),
            ( ftnlen    ) lenout - 1,
            ( ftnlen    ) lenerr - 1       );
            
   
   /* 
   Convert the output strings to C style.
   */
   F2C_ConvertStr( lenout, pictur );
   F2C_ConvertStr( lenerr, errmsg );


   /*
   Convert the status flag from logical to SpiceBoolean.
   */
   
   *ok = okeydoke;


   chkout_c ( "tpictr_c" );


} /* End tpictr_c */
Exemple #2
0
   void gcpool_c ( ConstSpiceChar * name,
                   SpiceInt         start,
                   SpiceInt         room,
                   SpiceInt         lenout,
                   SpiceInt       * n,
                   void           * cvals,
                   SpiceBoolean   * found )
 
/*
 
-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   name       I   Name of the variable whose value is to be returned.
   start      I   Which component to start retrieving for name
   room       I   The largest number of values to return.
   lenout     I   The length of the output string.
   n          O   Number of values returned for name.
   cvals      O   Values associated with name.
   found      O   True if variable is in pool.
 
-Detailed_Input
 
   name       is the name of the variable whose values are to be
              returned. If the variable is not in the pool with
              character type, found will be SPICEFALSE.
 
   start      is the index of the first component of name to return.
              The index follows the C convention of being 0 based.
              If start is less than 0, it will be treated as 0.  If
              start is greater than the total number of components
              available for name, no values will be returned (n will
              be set to zero).  However, found will still be set to
              SPICETRUE
 
   room       is the maximum number of components that should be
              returned for this variable.  (Usually it is the amount
              of room available in the array cvals). If room is
              less than 1 the error SPICE(BADARRAYSIZE) will be
              signaled.
 
   lenout     The allowed length of the output string.  This length
              must large enough to hold the output string plus the
              terminator.  If the output string is expected to have x
              characters, lenout needs to be x + 1. 
 
-Detailed_Output
 
   n          is the number of values associated with name that
              are returned.  It will always be less than or equal
              to room.
 
              If name is not in the pool with character type, no
              value is given to n.
 
   cvals      is the array of values associated with name.
              If name is not in the pool with character type, no
              values are given to the elements of cvals.
 
              If the length of cvals is less than the length of
              strings stored in the kernel pool (see MAXCHR) the
              values returned will be truncated on the right.
 
   found      is SPICETRUE if the variable is in the pool and has
              character type, SPICEFALSE if it is not.
 
-Parameters
 
   None.
 
-Exceptions
 
   1) If the value of room is less than one the error
      SPICE(BADARRAYSIZE) is signaled.
 
   2) If cvals has declared length less than the size of a
      string to be returned, the value will be truncated on
      the right.  See MAXCHR in pool.c for the maximum stored size of
      string variables.
 
   3) If the input string pointer is null, the error SPICE(NULLPOINTER)
      will be signaled.
 
   4) If the input string has length zero, the error SPICE(EMPTYSTRING)
      will be signaled.
 
   5) If the output string has length less than two characters, it
      is too short to contain one character of output data plus a null
      terminator, so it cannot be passed to the underlying Fortran
      routine.  In this event, the error SPICE(STRINGTOOSHORT) is
      signaled.
 
-Files
 
   None.
 
-Particulars
 
   This routine provides the user interface to retrieving
   character data stored in the kernel pool.  This interface
   allows you to retrieve the data associated with a variable
   in multiple accesses.  Under some circumstances this alleviates
   the problem of having to know in advance the maximum amount
   of space needed to accommodate all kernel variables.
 
   However, this method of access does come with a price. It is
   always more efficient to retrieve all of the data associated
   with a kernel pool data in one call than it is to retrieve
   it in sections.
 
   C requires the length of the output character array to be defined
   prior to calling the converted gcpool_c routine.  The size of the
   cvals output array is user defined and passed as the variable
   lenout.
 
   Also see the entry points gdpool_c and gipool_c.
 
-Examples
 
   The following code fragment demonstrates how the data stored
   in a kernel pool variable can be retrieved in pieces.  Using the
   kernel "test.ker" which contains
 
   \begindata
 
   CTEST_VAL = ('LARRY', 'MOE', 'CURLY' )
 
   ITEST_VAL = ( 3141, 186, 282 )
 
   DTEST_VAL = ( 3.1415, 186. , 282.397 )
 
 
   The program...
 
   #include <stdio.h>
   #include <string.h>
 
   #include "SpiceUsr.h"
   #include "SpiceZmc.h"
 
   #define LENOUT 20
   #define NUMVALS 2
   #define START   1
 
   void main()
      {
 
      SpiceInt          n;
      SpiceChar         cvals[NUMVALS][LENOUT];
      SpiceBoolean      found;
      SpiceInt          i;
 
 
       ldpool_c ( "test.ker" );
 
 
       /.
       Get 2 values (NUMVALs) starting at the second value
       in the list (START).  Each value will be of length LENOUT.
       ./
 
       gcpool_c ( "CTEST_VAL", START, NUMVALS, LENOUT, &n, cvals,
                  &found );
 
       for ( i = 0; i < NUMVALS; i++ )
          {
          printf("%s\n", cvals[i] );
          }
 
       exit(0);
      }
 
 
   Will give output of
   MOE
   CURLY
 
 
-Restrictions
 
   None.
 
-Literature_References
 
   None.
 
-Author_and_Institution
 
   W.L. Taber  (JPL)
 
-Version

   -CSPICE Version 2.2.1 07-SEP-2007   (EDW)

      Edited the 'lenout' description in the Detailed_Input to
      remove the recommendation of 32 as a general use value
      for 'lenout'.

   -CSPICE Version 2.2.0 18-MAY-2001   (WLT)

      Added a cast to (char *) in the call to F2C_ConvertStrArr.
 
   -CSPICE Version 2.1.0 22-JUN-1999   (EDW)
 
      Added local variable to return boolean/logical values.  This
      fix allows the routine to function if int and long are different
      sizes.
 
   -CSPICE Version 2.0.3 09-FEB-1998   (EDW)
 
      Removed the output dynamically allocated string.  Conversion
      of cval from string to array now accomplished via the
      F2C_ConvertStrArray call.
 
   -CSPICE Version 2.0.2 01-FEB-1998   (EDW)
 
      Removed the input and work dynamically allocated strings.
 
   -CSPICE Version 2.0.1 28-JAN-1998   (EDW)
 
      The start parameter is now zero based as per C convention.
      Adjusted the amount of memory for the strings to lenout-1.
 
   -CSPICE Version 2.0.0 07-JAN-1998   (EDW)
 
     The routine now function properly for room > 1.  Previously
     only a single value could be returned.
 
   -CSPICE Version 1.0.0 23-OCT-1997   (EDW)
 
 
-Index_Entries
 
   RETURN the character value of a pooled kernel variable
   RETURN the string value of a pooled kernel variable
 
-&
*/
 
{ /* Begin gcpool_c */
 
 
   /*
   Local variables.
   */
   logical            yes;
 
 
   /* The index is zero based here but not in gcpool_. */
   start = start + 1;
 
 
   /*
   Participate in error tracing.
   */
   chkin_c ( "gcpool_c");
 
 
   /*
   Check the input string utcstr to make sure the pointer is non-null
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "gcpool_c", name );
 
 
   /*
   Make sure the output string has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "gcpool_c", cvals, lenout );
 
 
 
   /*
   Call the f2c'd routine
   */
 
   gcpool_( ( char    * ) name,
            ( integer * ) &start,
            ( integer * ) &room,
            ( integer * ) n,
            ( char    * ) cvals,
            ( logical * ) &yes,
            ( ftnlen    ) strlen(name),
            ( ftnlen    ) lenout - 1 );
 
  
   /* Cast back to a SpiceBoolean. */
   *found = yes;

   if ( *found )
   {
      /*
      cvals now contains the requested data in a single string
      lenout * n long.  We need to reform cvals into an array
      of n strings each lenout long.
      */
      F2C_ConvertTrStrArr ( *n, lenout, (char *)cvals );
   }
 
 
   /* Done.  Checkout. */
   chkout_c ( "gcpool_c");
 
} /* End gcpool_c */
Exemple #3
0
   void dafac_c ( SpiceInt      handle,
                  SpiceInt      n,
                  SpiceInt      lenvals,
                  const void  * buffer  ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I    handle of a DAF opened with write access. 
   n          I    Number of comments to put into the comment area. 
   lenvals    I    Length of elements
   buffer     I    Buffer of comments to put into the comment area. 
 
-Detailed_Input
 
   handle   is the file handle of a binary DAF which has been opened 
            with write access. 
 
   n        is the number of rows in the array `buffer'.  This is
            also the number of comment lines in `buffer' that are to be
            added to the comment area of the binary DAF attached to
            `handle'.
 
   buffer   A string buffer containing comments which are to be added 
            to the comment area of the binary DAF attached to `handle'. 
            buffer should be declared by the caller has follows:

               SpiceChar    buffer[n][lenvals];
            
            Each row of the buffer should contain one comment line.

-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the number of comments to be added is not positive, the 
      error SPICE(INVALIDARGUMENT) will be signaled. 
 
   2) If a non printing ASCII character is encountered in the 
      comments, the error SPICE(ILLEGALCHARACTER) will be signaled.
 
   3) If the binary DAF file attached to HANDLE is not open with 
      write access an error will be signalled by a routine called by
      this routine.
 
   4) If the end of the comments cannot be found, i.e., the end of 
      comments marker is missing on the last comment record, the error
      SPICE(BADCOMMENTAREA) will be signaled.
 
   5) If the input pointer `buffer' is null, the error
      SPICE(NULLPOINTER) will be signaled.
  
   6) If the input buffer string length indicated by `lenvals' 
      is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. 

-Files
 
   See argument `handle' in $ Detailed_Input. 
 
-Particulars
 
   A binary DAF contains a data area which is reserved for storing
   annotations or descriptive textual information about the data
   contained in a file. This area is referred to as the ``comment
   area'' of the file. The comment area of a DAF is a line oriented
   medium for storing textual information. The comment area preserves
   leading or embedded white space in the line(s) of text which are
   stored so that the appearance of the information will be unchanged
   when it is retrieved (extracted) at some other time. Trailing
   blanks, however, are NOT preserved, due to the way that character
   strings are represented in standard Fortran 77.
 
   This routine will take a buffer of text lines and add (append) them
   to the comment area of a binary DAF. If there are no comments in the
   comment area of the file, then space will be allocated and the text
   lines in `buffer' will be placed into the comment area. The text lines
   may contain only printable ASCII characters (decimal values 32 -
   126).
 
   There is NO maximum length imposed on the significant portion of a
   text line that may be placed into the comment area of a DAF. The
   maximum length of a line stored in the comment area should be
   reasonable, however, so that they may be easily extracted. A good
   maximum value for this would be 255 characters, as this can easily
   accommodate ``screen width'' lines as well as long lines which may
   contain some other form of information.
 
-Examples
 
   1) Let 
 
         handle   be the handle for a DAF which has been opened with 
                  write access. 
 
         n        be the number of lines of text to be added to the 
                  comment area of the binary DAF attached to handle. 
 
         lenvals  be the length of the rows of a string buffer.

         buffer   is an array of text lines to be added to the comment 
                  area of the binary DAF attached to handle. `buffer'
                  normally is declared

                     SpiceChar buffer [n][lenvals];
                  
      The call 
 
         dafac_c ( handle, n, lenvals, buffer );
 
      will append the first n line(s) in `buffer' to the comment area 
      of the binary DAF attached to `handle'. 
 
-Restrictions
 
   1) This routine uses constants that are specific to the ASCII 
      character sequence. The results of using this routine with 
      a different character sequence are unpredictable. 
 
   2) This routine is only used to extract records on environments 
      whose characters are a single byte in size.  Updates to this 
      routine and routines in its call tree may be required to 
      properly handle other cases. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL)
   K.R. Gehringer (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 16-NOV-2006 (NJB) (KRG)

-Index_Entries
 
   add comments to a binary daf file 
   append comments to a daf file comment area 
 
-&
*/

{ /* Begin dafac_c */


   /*
   Local variables
   */
   SpiceChar             * fCvalsArr;
   
   SpiceInt                fCvalsLen;


   /*
   Participate in error tracing.
   */
   chkin_c ( "dafac_c" );


   /*
   Make sure the input string pointer for the `buffer' array is non-null 
   and that the length lenvals is sufficient.  
   */
   CHKOSTR ( CHK_STANDARD, "dafac_c", buffer, lenvals );
   
   /*
   The input buffer contains C-style strings; we must pass a 
   Fortran-style buffer to dafac_.
   */
   C2F_MapStrArr ( "dafac_c", 
                   n, lenvals, buffer, &fCvalsLen, &fCvalsArr );

   if ( failed_c() )
   {
      chkout_c ( "dafac_c" );
      return;
   }


   /*
   Call the f2c'd routine.
   */
   dafac_ ( ( integer * ) &handle,
            ( integer * ) &n,
            ( char    * ) fCvalsArr,
            ( ftnlen    ) fCvalsLen );

   /*
   Free the dynamically allocated array.
   */
   free ( fCvalsArr );


   chkout_c ( "dafac_c" );

} /* End dafac_c */
Exemple #4
0
   void ekrcec_c ( SpiceInt           handle,
                   SpiceInt           segno,
                   SpiceInt           recno,
                   ConstSpiceChar   * column,
                   SpiceInt           lenout,
                   SpiceInt         * nvals,
                   void             * cvals,
                   SpiceBoolean     * isnull )

/*

-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. 
   lenout     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. 
 
   lenout         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, lenout 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][lenout]
                  
                  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, the error will be diagnosed by routines 
       called by this routine. 
 
   2)  If segno is out of range, the error will diagnosed by routines 
       called by this routine. 
 
   3)  If recno is out of range, the error will diagnosed by routines 
       called by this routine. 
 
   4)  If column is not the name of a declared column, the error 
       will be diagnosed by routines called by this routine. 
 
   5)  If column specifies a column of whose data type is not 
       character, the error SPICE(WRONGDATATYPE) will be 
       signaled. 
 
   6)  If column specifies a column of whose class is not 
       a character class known to this routine, the error 
       SPICE(NOCLASS) will be signaled. 
 
   7)  If an attempt is made to read an uninitialized column entry, 
       the error will be diagnosed by routines called by 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 will be diagnosed by routines called by this 
       routine. 
 
   9)  If any element of the column entry would be truncated when 
       assigned to an element of cvals, the error will be diagnosed 
       by routines called by this routine. 

   10) If the input column name string pointer is null, the error
       SPICE(NULLPOINTER) will be signaled.

   11) If the input column name string has length zero, the error 
       SPICE(EMPTYSTRING) will be signaled.

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

   13) If the output string length indicated by lenout is less than two 
       characters, it is too short to contain one character of output data
       plus a null terminator, so it cannot be passed to the underlying Fortran
       routine.  In this event, the error SPICE(STRINGTOOSHORT) is
       signaled.
 
-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
 
   1)  Read the value in the third record of the column ccol in 
       the fifth segment of an EK file designated by handle. 
 
          #include "SpiceUsr.h"
             .
             .
             .
          ekrcec_c ( handle, 4, 2, "CCOL", lenout, &nvals, &cval, &isnull );
 
-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) 
 
-Version

   -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 
 
-&
*/

{ /* Begin ekrcec_c */


   /*
   Local variables
   */
   logical                 null;


   /*
   Participate in error tracing.
   */
   chkin_c ( "ekrcec_c" );


   /*
   Check the column name to make sure the pointer is non-null
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ekrcec_c", column );


   /*
   Make sure the output array has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "ekrcec_c", cvals, lenout );

   /*
   Map the segment and record numbers to their Fortran-style
   values.  Pass a flag of type logical to ekrced_.
   */
    
   segno++;
   recno++;


   ekrcec_ ( ( integer * ) &handle,
             ( integer * ) &segno,
             ( integer * ) &recno,
             ( char    * ) column,
             ( integer * ) nvals,
             ( char    * ) cvals,
             ( logical * ) &null,
             ( ftnlen    ) strlen(column),
             ( ftnlen    ) lenout-1        );

   /*
   Convert the output array from Fortran to C style. 
   */
   F2C_ConvertStrArr ( *nvals, lenout, (char *) cvals );


   /*
   Cast the null flag back to a SpiceBoolean. 
   */
   *isnull = null;


   chkout_c ( "ekrcec_c" );

} /* End ekrcec_c */
Exemple #5
0
   void getelm_c ( SpiceInt         frstyr,
                   SpiceInt         lineln,
                   const void     * lines,
                   SpiceDouble    * epoch,
                   SpiceDouble    * elems   ) 
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   frstyr     I   Year of earliest representable two-line elements.
   lineln     I   Length of strings in lines array.
   lines      I   A pair of "lines" containing two-line elements.
   epoch      O   The epoch of the elements in seconds past J2000. 
   elems      O   The elements converted to SPICE units. 
 
-Detailed_Input
 
   frstyr    is the first year possible for two line elements. Since
             two line elements allow only two digits for the year, some
             conventions must be followed concerning which century the
             two digits refer to.  frstyr is the year of the earliest
             representable elements. The two-digit year is mapped to
             the year in the interval from frstyr to frstyr + 99 that
             has the same last two digits as the two digit year in the
             element set.  For example if frstyr is set to 1960  then
             the two digit years are mapped as shown in the table
             below:
 
             Two-line         Maps to 
             element year 
             
                00            2000 
                01            2001 
                02            2002 
                 .              . 
                 .              . 
                 .              . 
                58            2058 
                59            2059 
               -------------------- 
                60            1960 
                61            1961 
                62            1962 
                 .              . 
                 .              . 
                 .              . 
                99            1999 
 
              Note that if Space Command should decide to represent
              years in 21st century as 100 + the last two digits of the
              year (for example: 2015 is represented as 115) instead of
              simply dropping the first two digits of the year, this
              routine will correctly map the year as long as you set
              frstyr to some value between 1900 and 1999.
 
   lines      is a pair of lines of text that comprise a Space command
              ``two-line element'' set.  lines should be declared
              
                 SpiceChar lines[2][lineln];

              These text lines should be the same as they are presented
              in the two-line element files available from Space
              Command (formerly NORAD). Below is an example of a
              two-line set for TOPEX.
 
   TOPEX 
   1 22076U 92052A   97173.53461370 -.00000038  00000-0  10000-3 0   594 
   2 22076  66.0378 163.4372 0008359 278.7732  81.2337 12.80930736227550 
 
 
                 
 
-Detailed_Output
 
   epoch      is the epoch of the two line elements supplied via 
              the input array lines.  Epoch is returned in TDB 
              seconds past J2000. 
 
   elems      is an array containing the elements from the two line 
              set supplied via the array lines.  The elements are 
              in units suitable for use by the CSPICE routine 
              ev2lin_. 
 
              Also note that the elements XNDD6O and BSTAR 
              incorporate the exponential factor present in the 
              input two line elements in LINES.  (See particulars 
              below. 
 
                  ELEMS [ 0 ] = XNDT2O in radians/minute**2 
                  ELEMS [ 1 ] = XNDD6O in radians/minute**3 
                  ELEMS [ 2 ] = BSTAR 
                  ELEMS [ 3 ] = XINCL  in radians 
                  ELEMS [ 4 ] = XNODEO in radians 
                  ELEMS [ 5 ] = EO 
                  ELEMS [ 6 ] = OMEGAO in radians 
                  ELEMS [ 7 ] = XMO    in radians 
                  ELEMS [ 8 ] = XNO    in radians/minute 
                  ELEMS [ 9 ] = EPOCH of the elements in seconds 
                                past ephemeris epoch J2000. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   No checking of the inputs is performed in this routine. However, this
   routine does call other CSPICE routines. If one of these routines
   detects an error it will diagnose it and signal an error.
 
-Files
 
   You must have loaded a SPICE leapseconds kernel into the 
   kernel pool prior to caling this routine. 
 
-Particulars
 
   This routine parses a Space Command Two-line element set and returns
   the orbital elements properly scaled and in units suitable for use
   by other SPICE software.  Input elements look like the following
 
--------------------------------------------------------------------- 
1 22076U 92052A   97173.53461370 -.00000038  00000-0  10000-3 0   594 
2 22076  66.0378 163.4372 0008359 278.7732  81.2337 12.80930736227550 
--------------------------------------------------------------------- 
^ 
123456789012345678901234567890123456789012345678901234567890123456789 
         1         2         3         4         5         6 
 
   The ``raw'' elements in the first and second lines are marked below.
   Note that in several instances exponents and decimal points are
   implied.  Also note that input units are degrees, degrees/day**n and
   revolutions/day.
 
 
                    DAY OF YEAR             NDD60    BSTAR 
                    vvvvvvvvvvvv            vvvvvv   vvvvvv 
--------------------------------------------------------------------- 
1 22076U 92052A   97173.53461370 -.00000038  00000-0  10000-3 0   594 
--------------------------------------------------------------------- 
                  ^^             ^^^^^^^^^^       ^^       ^^ 
                  YEAR             NDT20          IEXP     IBEXP 
 
 
 
   The ``raw'' elements in the second line are marked below 
                 NODE0            OMEGA             N0 
                 vvvvvvvv         vvvvvvvv          vvvvvvvvvvv 
--------------------------------------------------------------------- 
2 22076  66.0378 163.4372 0008359 278.7732  81.2337 12.80930736227550 
--------------------------------------------------------------------- 
        ^^^^^^^^          ^^^^^^^          ^^^^^^^^ 
        Inclination       Eccentricity     M0 
 
   This routine extracts these values ``inserts'' the implied 
   decimal points and exponents and then converts the inputs 
   to units of radians, radians/minute, radians/minute**2, and 
   radians/minute**3 
 
-Examples
 
   Suppose you have a set of two-line elements and an array containing
   the related geophysical constants necessary to evaluate a state.
   The example below shows how you can use this routine together with
   the routine EV2LIN to propagate a state to an epoch of interest.
 
      #include <string.h>
      #include <stdio.h>
      #include "SpiceUsr.h"
      
      SpiceDouble         et;
      SpiceDouble         epoch;
      SpiceInt            frstyr;
          .
          .
          .
      /.
      The parameters below will make it easier to make assignments 
      to the array GEOPHS required by EV2LIN. 
 
         J2  --- location of J2 
         J3  --- location of J3 
         J4  --- location if J4 
         KE  --- location of KE = sqrt(GM) in eart-radii**1.5/MIN 
         QO  --- location of upper bound of atmospheric model in KM 
         SO  --- location of lower bound of atmospheric model in KM 
         ER  --- location of earth equatorial radius in KM. 
         AE  --- location of distance units/earth radius 
      ./
      
      #define  J2 0   
      #define  J3 1   
      #define  J4 2    
      #define  KE 3   
      #define  QO 4   
      #define  SO 5   
      #define  ER 6   
      #define  AE 7  
 
      /.
      We set the lower bound for the years to be the beginning 
      of the space age. 
      ./
      frstyr  =  1957;
 
      /.
      Read in the next two lines from the text file that contains 
      the two-line elements.  We assume that file has been opened 
      properly and that we have set the ``file pointer'' to the 
      correct location for reading the next set of elements. 
      ./
      
      for ( i = 0; i < 2; i++ )
      {
         fgets ( line[i], lineln, textfile );
         line[i][ strlen(line[i]) ] = '\0';
      }

      getelm_c ( frstyr, lineln, line, &epoch, elems ); 
 
 
      /.
      Set up the geophysical quantities.  At last check these 
      were the values used by Space Command. 
      ./
      
      geophs[ J2 ] =    1.082616e-3; 
      geophs[ J3 ] =   -2.53881e-6; 
      geophs[ J4 ] =   -1.65597e-6; 
      geophs[ KE ] =    7.43669161e-2; 
      geophs[ QO ] =  120.0; 
      geophs[ SO ] =   78.0; 
      geophs[ ER ] = 6378.135; 
      geophs[ AE ] =    1.0; 
      
      
      /.
      Now propagate the state using ev2lin_ to the epoch of 
      interest. 
      ./
      ev2lin_ ( &et, geophs, elems, state ); 
 
 
-Restrictions
 
  The format of the two-line elements suffer from a "millenium"
  problem---only two digits are used for the year of the elements. It
  is not clear how Space Command will deal with this problem as the
  year 2000 comes and goes.  We hope that by adjusting the input frstyr
  you should be able to use this routine well into the 21st century.
  However, since we can't predict how others will resolve the millenium
  problem we can't be sure that our approach will be addequate to deal
  with the problem.
 
  The approach taken to mapping the two-digit year to the full year is
  given by the code below. Here, yr is the integer obtained by parsing
  the two-digit year from the first line of the elements.
 
      begyr = (frstyr/100)*100; 
      year  = begyr + yr;
 
      if ( year < frstyr )  
      {
         year += 100;
      }
 
   This mapping will be changed if future two-line element
   representations make this method of computing the full year
   inaccurate.
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 
-Version

   -CSPICE Version 1.0.1, 15-NOV-2007 (EDW)
   
      Minor edits to example section; the getelm_c call lacked
      the 'lineln' argument, the use of 'et' implied a pointer
      rather than a value.

   -CSPICE Version 1.0.0, 06-AUG-1999 (NJB) (WLT)

-Index_Entries
 
   Parse two-line elements 
 
-&
*/

{ /* Begin getelm_c */


   /*
   Local constants
   */
   #define NELTS           2
   
   
   /*
   Local variables
   */
   SpiceChar            ** cvalsPtr;
   SpiceChar             * fCvalsArr;

   SpiceInt                i;
   SpiceInt                fCvalsLen;

   SpiceStatus             status;

   /*
   Participate in error tracing.
   */
   chkin_c ( "getelm_c" );


   /*
   Check the input line array for null pointer of insufficient string
   length.
   */
   CHKOSTR ( CHK_STANDARD, "getelm_c", lines, lineln );


   /*
   Convert the input string array to a Fortran-style string array.

   We'll first allocate an array of character pointers to index
   the values, initialize this array, and use it to produce
   a dynamically allocated array of Fortran-style strings.
   */

   cvalsPtr = ( SpiceChar ** ) malloc ( NELTS * sizeof(SpiceChar *) );

   if ( cvalsPtr == 0 )
   {
      setmsg_c ( "Failure on malloc call to create pointer array "
                 "for line values."                              );
      sigerr_c ( "SPICE(MALLOCFAILED)"                           );
      chkout_c ( "getelm_c"                                      );
      return;
   }
   
   for ( i = 0;  i < NELTS;  i++  )
   {
      cvalsPtr[i] =  (SpiceChar *)lines  +  ( i * lineln );
   }
   
   status = C2F_CreateStrArr (  NELTS, 
                                ( ConstSpiceChar ** ) cvalsPtr, 
                                &fCvalsLen, 
                                &fCvalsArr                      );
  /* fCvalsArr[2*fCvalsLen] = '\0'; */
   
   if ( status == SPICEFAILURE )
   {
      free ( cvalsPtr );
      
      setmsg_c ( "C to Fortran string array conversion for `lines' "
                 "failed."                                           );
      sigerr_c ( "SPICE(STRINGCONVERROR)"                            );
      chkout_c ( "getelm_c"                                          );
      return;
   }
   
   /*
   Call the f2c'd routine.
   */
   getelm_ (  ( integer    * ) &frstyr,
              ( char       * ) fCvalsArr,
              ( doublereal * ) epoch,
              ( doublereal * ) elems,
              ( ftnlen       ) fCvalsLen  );
   
   /*
   Clean up all of our dynamically allocated arrays.
   */
   free ( cvalsPtr  );
   free ( fCvalsArr );


   chkout_c ( "getelm_c" );

} /* End getelm_c */
Exemple #6
0
   void timdef_c ( ConstSpiceChar * action,
                   ConstSpiceChar * item,
                   SpiceInt         lenout,
                   SpiceChar      * value )

/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   action     I   is the kind of action to take "SET" or "GET".
   item       I   is the default item of interest.
   lenout     I   Length of list for output.
   value     I/O  is the value associated with the default item.

-Detailed_Input

   action     is a word that specifies whether timdef_c sets the
              value associated with item or retrieves the value
              associated with item.  The allowed values for
              action are "SET" and "GET".  The routine is not
              sensitive to the case of the letters in action.

   item       is the default items whose value should be set or
              retrieved.  The items that may be requested are:

              item        Allowed Values
              ---------   --------------
              CALENDAR    GREGORIAN
                          JULIAN
                          MIXED

              SYSTEM      TDB
                          TDT
                          UTC

              ZONE        EST, EDT, CST, CDT, MST, MDT, PST, PDT
                          UTC+HR
                          UTC-HR       ( 0 <= HR < 13 )
                          UTC+HR:MN    ( 0 <= MN < 60 )
                          UTC-HR:MN

              The case of item is not significant.

   lenout     is the allowed length of the string when returning a
              value via a "GET".  The size described by lenout should
              be large enough to hold any possible output plus 1.

   value      if the action is "SET" then value is an input and
              is the value to be associated with item.  Note that
              value is checked to ensure it is within the range
              of allowed values for item.  If it is not within
              the expected range and appropriate error message
              is signalled.  The case of value is not significant.

-Detailed_Output

   value      if the action is "GET" then value will be the
              value associated with the requested item.  Note that
              when time zones are set, they are translated to the
              UTC offset form ( UTC(+/-)HR[:MN] ).  When value is
              an output it will be in upper case.

-Parameters

   None.

-Files

   None.

-Exceptions

   1) If the action specified is not SET or GET the error
      SPICE(BADACTION) is signalled.

   2) If the item specified is not one the recognized items
      the error SPICE(BADTIMEITEM) is signalled.

   3) If the value associated with a "SET", item input
      is not one of the recognized items, the error
      SPICE(BADDEFAULTVALUE) is signalled.

-Particulars

   This routine exists to allow SPICE toolkit users to alter
   the default interpretation of time strings made by the
   routine str2et_c.

   Normally, unlabelled time strings are assumed to belong to
   the Gregorian Calendar and are UTC times.  However, you
   may alter the default behavior by calling timdef_c.

   Calendar
   --------

   You may set the calendar to be one of the following

   Gregorian   --- This is the calendar used daily the
                   Western Hemisphere.  Leap years occur in this
                   calendar every 4 years except on centuries
                   such as 1900 that are not divisible by 400.

   Julian      --- This is the calendar that was in use prior
                   to October 15, 1582.  Leap years occur every
                   4 years on the Julian Calendar (including all
                   centuries.)  October 5, 1582 on the Julian
                   calendar corresponds to October 15, 1582 of the
                   Gregorian Calendar.

   Mixed       --- This calendar uses the Julian calendar
                   for days prior to October 15, 1582 and
                   the Gregorian calendar for days on or after
                   October 15, 1582.

   To set the default calendar, select on of the above for value
   and make the following call.

      timdef_c ( "SET", "CALENDAR", lenout, value );


   System
   -------

   You may set the system used for keeping time to be UTC (default)
   TDB (barycentric dynamical time) or TDT (terrestrial dynamical
   time).  Both TDB and TDT have no leapseconds.  As such the time
   elapsed between any two epochs on these calendars does not depend
   upon when leapseconds occur.

   To set the default time system, select TDT, TDB or UTC for value
   and make the following call.

      timdef_c ( "SET", "SYSTEM", lenout, value );

   Note that such a call has the side effect of setting the value
   associated with ZONE to a blank.

   Zone
   -----

   You may alter the UTC system by specifying a time zone (UTC
   offset).  For example you may specify that epochs are referred
   to Pacific Standard Time (PST --- UTC-7).  The standard
   abbreviations for U.S. time zones are recognized:

      EST   UTC-5
      EDT   UTC-4
      CST   UTC-6
      CDT   UTC-5
      MST   UTC-7
      MDT   UTC-6
      PST   UTC-8
      PDT   UTC-7

   In addition you may specify any commercial time zone by using
   "offset" notation.  This notation starts with the letters "UTC"
   followed by a + for time zones east of Greenwich and - for
   time zones west of Greenwich.  This is followed by the number
   of hours to add or subtract from UTC.  This is optionally followed
   by a colon ':' and the number of minutes to add or subtract (based
   on the sign that follows "UTC") to get the
   local time zone.  Thus to specify the time zone of Calcutta you
   would specify the time zone to be UTC+5:30.  To specify the
   time zone of Newfoundland use the time zone UTC-3:30.

   To set a default time zone, select one of the "built-in" U.S.
   zones or construct an offset as discussed above.  Then make the
   call

      timdef_c ( "SET", "ZONE", lenout, value );

   If you "GET" a "ZONE" it will either be blank, or have the
   form "UTC+/-HR[:MN]"

   Note that such a call has the side effect of setting the value
   associated with SYSTEM to a blank.

-Examples

   Suppose you wish to modify the behavior of str2et_c so that
   it interprets unlabeled time strings as being times in
   Pacific Daylight Time and that you want the calendar to use
   to be the "Mixed" calendar.  The following two calls will
   make the desired changes to the behavior of str2et_c

       timdef_c ( "SET", "CALENDAR", lenout, "MIXED" );
       timdef_c ( "SET", "ZONE"    , lenout, "PDT"   );

-Restrictions

   None.

-Author_and_Institution

   W.L. Taber      (JPL)
   E.D. Wright     (JPL)

-Literature_References

   None.

-Version

   -CSPICE Version 1.0.1, 13-APR-2000 (NJB) 
   
      Made some minor updates and corrections in the header comments.
      
   -CSPICE Version 1.0.0, 4-FEB-1998   (EDW)

-Index_Entries

   Change time software defaults.
   Time Zones
   Gregorian and Julian Calendars

-&
*/

{ /* Begin timdef_c */


   /*
   Participate in error tracing.
   */

   chkin_c ( "timdef_c" );


   /*
   Check the input strings to make sure the pointers are non-null
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "timdef_c", action );

   CHKFSTR ( CHK_STANDARD, "timdef_c", item   );



   /*  Select a task based on the value of the action string. */

   if ( eqstr_c ( action, "SET") )
      {

      /*
      Operation is SET. "value" will be an input string.  Check
      value as well.
      */

      CHKFSTR ( CHK_STANDARD, "timdef_c", value );


      /*
      Call the f2c'd Fortran routine.
      */

      timdef_( ( char * ) action,
               ( char * ) item,
               ( char * ) value,
               ( ftnlen ) strlen(action),
               ( ftnlen ) strlen(item),
               ( ftnlen ) strlen(value)  );


      }

   else if ( eqstr_c (action, "GET" ) )
      {

      /*
      Operation is GET.  "action" will be an output string.  Make sure
      the output string has at least enough room for one output
      character and a null terminator.  Also check for a null pointer.
      */
      CHKOSTR ( CHK_STANDARD, "timdef_c", value, lenout );


      /*
      Call the f2c'd Fortran routine.
      */

      timdef_( ( char * ) action,
               ( char * ) item,
               ( char * ) value,
               ( ftnlen ) strlen(action),
               ( ftnlen ) strlen(item),
               ( ftnlen ) lenout - 1  );


      /* Convert our Fortran string to C. */

      F2C_ConvertStr( lenout, value );

      }



   chkout_c ( "timdef_c" );


} /* End timdef_c */
Exemple #7
0
   void errprt_c ( ConstSpiceChar * op,
                   SpiceInt         lenout,
                   SpiceChar      * list  )

/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   op         I   The operation:  "GET" or "SET".
   lenout     I   Length of list for output.
   list      I/O  Specification of error messages to be output.

-Detailed_Input

   op      indicates the operation to be performed.  Possible
           values are "GET" and "SET".

           "SET" means, "the following list specifies the default
           selection of error messages to be output."  These are
           the messages that will be output to the default error
           output device (selected by errdev_c) when an error is
           detected.

           "GET" means, "return the current list of error output
           items."  This is the exact list that was set by the
           last call to this routine with the "SET" option.

           The option can be specified in mixed case.  For example,
           the following call will work:

           errprt_c ( "SeT", lenout, "ALL" )


   lenout  is the allowed length of list when list is returning a
           the error message list.  The size described by lenout
           should be large enough to hold any possible output plus 1.


   list    is a list of error message items.  The items
           are delimited by commas.  The items that can be
           in the list are the words:

           1.  SHORT        ...indicates the short error message
           2.  EXPLAIN      ...the explanation of the short message
           3.  LONG         ...the long error message
           4.  TRACEBACK    ...the traceback
           5.  ALL          ...indicates "output all messages"
           6.  NONE         ...indicates "don't output any messages"
           7.  DEFAULT      ...same as ALL, but includes default
                                message

           A "list" is a character string containing some or
           all of the above words, delimited by commas.  Examples
           are:

           1.  "SHORT, EXPLAIN"
           2.  "SHORT, LONG"
           3.  "ALL"
           4.  "NONE"
           5.  "ALL, NONE, ALL, SHORT, NONE"

           Each word in the list can be thought of as
           "flipping a switch" to enable or disable the output
           of the message(s) indicated by the word.  The
           words are acted on in the order they occur in the
           list, starting with the leftmost word.  As examples,
           consider the sample lists above.

           The effect of the first list above, "SHORT, EXPLAIN",
           is to enable the output of the short error message
           and the explanatory text corresponding to it.

           The effect of the second list is to enable the output
           of the short and long messages.

           The effect of the third list is to enable the output of
           all of the error messages (short, long, explanation
           of the short message, and traceback).

           The effect of the fourth list is to disable output of
           all of the messages.

           The effect of the fifth list is to disable output of
           all of the messages.  The reason for this is that
           the words in the list are responded to in order,
           from left to right, and "NONE" is the last word.

           If any words other than SHORT, LONG, EXPLAIN, ALL,
           DEFAULT, TRACEBACK or NONE appear in list, those words
           that are recognized are responded to.  The words
           that are not recognized are diagnosed as
           erroneous, and error messages are generated
           for each such unrecognized word.

           The length of list is caller-defined, but only
           the first 100 characters of list will be saved
           for later retrieval.

           Only the first 10 items in the list are used;
           the rest are ignored.

-Detailed_Output

   list    is a list of error message items.  The value of
           list is that set by the last call to this routine
           using the "SET" option.  See "Detailed Input"
           for a description of the possible values and
           meanings of list.

           The initial value returned is "DEFAULT".

           Only the first 100 characters of list are saved
           when the list is set; any additional characters
           are truncated.  Therefore, the first 100
           characters, at most, of the saved value of list
           will be returned.

-Parameters

   None.

-Exceptions

   1) If the input argument op does not indicate a valid operation,
      the error SPICE(INVALIDOPERATION) will be signaled.
      
   2) If the input argument list does not indicate a valid list of
      error message types, the error SPICE(INVALIDLISTITEM) will be
      signaled.
      
   3) The error SPICE(EMPTYSTRING) is signalled if the input
      string does not contain at least one character, since the
      input string cannot be converted to a Fortran-style string
      in this case.
      
   4) The error SPICE(NULLPOINTER) is signalled if the input string
      pointer is null.
 
   5) The user must pass a value indicating the length of the output
      string, when list is an output.  If this value is not at least 2, 
      the error SPICE(STRINGTOOSHORT) is signaled.

   Also, this routine is part of the CSPICE error
   handling mechanism.

-Files

   None.

-Particulars

   Please read the "required reading"!

   This routine is intended to be used in conjunction with
   errdev_c, which selects the default output device to which
   the error messages selected by this routine will be
   output.

   Additionally, the error response action must be
   something other than "IGNORE" if the error messages
   are to be output.  Possible choices of the error
   response action are "RETURN", "REPORT", "ABORT", "DEFAULT", and
   "IGNORE".  Use erract_c to set the error response action.


   Only the first 100 characters of list are saved.

   The default set of error messages that are output is the
   set specified by "DEFAULT"; i.e., all of them, including
   the "default" message.


-Examples

   1.  In this example, we select as the output device
       the file, SPUD.DAT, and then select the error
       messages to be output.  We choose the short
       error message and the traceback.  Since a
       different set of messages may have been selected
       previously, we clear the old setting by putting
       the word, "NONE", at the beginning of the list.

          /.
          Set the error output device to SPUD.DAT:
          ./
          errdev_c (  "SET", lenout, "SPUD.DAT" );

          /.
          Choose error messages:
          ./
          errprt_c (  "SET", lenout, "NONE, SHORT, TRACEBACK" );


   2.  In this example we are retrieving the error message list.

          /.
          Declare the output string and its size.
          ./

         #define     LENOUT  50

         SpiceChar   list[ LENOUT ];

         errdev_c ( "GET", LENOUT, list );


-Restrictions

   The device to which the selected error messages will
   be written must be selected via errdev_c; otherwise,
   messages will be written to the initial default device.

   Only the first 100 characters of list are saved.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman    (JPL)

-Version

   -CSPICE Version 1.3.0, 24-JUN-2003 (NJB)

      Bug fix:  case of invalid operation keyword is now 
      diagnosed, as per the Exceptions section of the header.

   -CSPICE Version 2.0.0, 09-FEB-1998 (NJB) (EDW)

      Input argument op was changed to type ConstSpiceChar *.

      Re-implemented routine without dynamically allocated, temporary 
      strings. 
      
      Corrected errors in examples in which the call sequence
      was incorrect.

   -CSPICE Version 1.0.0, 25-OCT-1997   (EDW)

-Index_Entries

   get/set error output items

-&
*/

{ /* Begin errprt_c */


   /*
   Participate in error tracing.
   */
   if ( return_c() ) 
   {
      return;
   }

   chkin_c ( "errprt_c" );


   /*
   Check the input string op to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "errprt_c", op );
   

   if ( eqstr_c ( op, "SET") )
   {

      /*
      Operation is SET. The argument "list" will be an input string.
      Check "list" as well.
      */
      CHKFSTR ( CHK_STANDARD, "errprt_c", list );


      errprt_( ( char * ) op,
               ( char * ) list,
               ( ftnlen ) strlen(op),
               ( ftnlen ) strlen(list) );
   }

   else if ( eqstr_c (op, "GET" ) )
   {

      /*
      Operation is GET.  "list" will be an output string. 
      
      Make sure the output string has at least enough room for one 
      output character and a null terminator.  Also check for a null 
      pointer.
      */
      CHKOSTR ( CHK_STANDARD, "errprt_c", list, lenout );
        
      /*
      After the routine call, create a C string from the
      Fortran output string.
      */
      errprt_( ( char * ) op,
               ( char * ) list,
               ( ftnlen ) strlen(op),
               ( ftnlen ) lenout-1     );


      F2C_ConvertStr( lenout, list );
   }

   else
   {
      setmsg_c ( "Input argument op had value: # "
                 "Valid choices are GET or SET."   );   
      errch_c  ( "#",  op                          );
      sigerr_c ( "SPICE(INVALIDOPERATION)"         );
      chkout_c ( "errprt_c"                        );
      return;
   }


   chkout_c ( "errprt_c" );
   

} /* End errprt_c */
Exemple #8
0
void kdata_c ( SpiceInt          which,
               ConstSpiceChar  * kind,
               SpiceInt          fillen,
               SpiceInt          typlen,
               SpiceInt          srclen,
               SpiceChar       * file,
               SpiceChar       * filtyp,
               SpiceChar       * source,
               SpiceInt        * handle,
               SpiceBoolean    * found  )
/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   which      I   Index of kernel to fetch from the list of kernels.
   kind       I   The kind of kernel to which fetches are limited.
   fillen     I   Available space in output file string.
   typlen     I   Available space in output kernel type string.
   srclen     I   Available space in output source string.
   file       O   The name of the kernel file.
   filtyp     O   The type of the kernel.
   source     O   Name of the source file used to load file.
   handle     O   The handle attached to file.
   found      O   SPICETRUE if the specified file could be located.

-Detailed_Input

   which      is the number of the kernel to fetch (matching the
              type specified by kind) from the list of kernels that
              have been loaded through the entry point furnsh_c but
              that have not been unloaded through the entry point
              unload_c.

              The range of which is 0 to count-1, where count is
              the number of kernels loaded via furnsh_c.  This
              count may be obtained by calling ktotal_c.  See the
              Examples section for an illustrative code fragment.


   kind       is a list of types of kernels to be considered when
              fetching kernels from the list of loaded kernels. KIND
              should consist of a list of words of kernels to
              examine.  Recognized types are

                 SPK  --- All SPK files are counted in the total.
                 CK   --- All CK files are counted in the total.
                 PCK  --- All binary PCK files are counted in the
                          total.
                 EK   --- All EK files are counted in the total.
                 TEXT --- All text kernels that are not meta-text
                          kernels are included in the total.
                 META --- All meta-text kernels are counted in the
                          total.
                 ALL  --- Every type of kernel is counted in the
                          total.

               kind is case insensitive.  If a word appears in kind
               that is not one of those listed above it is ignored.

               See the entry point ktotal_c for examples of the use
               of kind.

   fillen      is the amount of available space in the output file
               string, including room for the terminating null.
               Normally, this is the declared length of the output
               string.

   typlen      is the amount of available space in the output kernel
               type string.

   srclen      is the amount of available space in the output kernel
               source string.


-Detailed_Output


   file        is the name of the file having index which in the
               sequence of files of type kind currently loaded via
               furnsh_c.  file will be blank if there is no such kernel
               is loaded.

   filtyp      is the type of the kernel specified by file.  filtyp
               will be empty if there is no file matching the
               specification of which and kind.

   source      is the name of the source file that was used to
               specify file as one to load.  If file was loaded
               directly via a call to furnsh_c, source will be empty.
               If there is no file matching the specification of
               which and kind, source will be empty.

   handle      is the handle attached to file if it is a binary
               kernel.  If file is a text kernel or meta-text kernel
               handle will be zero.  If there is no file matching
               the specification of which and kind, handle will be
               set to zero.

   found       is returned SPICETRUE if a file matching the
               specification of which and kind exists.  If there is no
               such file, found will be set to SPICEFALSE.

-Parameters

   None.

-Exceptions

   1) If a file is not loaded matching the specification of which
      and kind, found will be SPICEFALSE; file, filtyp, and source
      will be empty and handle will be set to zero.

   2) If any input or output character argument pointer is null, the
      error SPICE(NULLPOINTER) will be signaled.

   3) If any of the output string length arguments are less than 1, the
      error SPICE(STRINGTOOSHORT) will be signaled.

   4) If any output string has length at least 1 but is too short to
      contain the output string, the corresponding is truncated on the
      right.  The output string is still null-terminated.

-Files

   None.

-Particulars

   This entry point allows you to determine which kernels have
   been loaded via furnsh_c and to obtain information sufficient
   to directly query those files.

-Examples

   The following example shows how you could print a summary
   of SPK files that have been loaded through the interface
   furnsh_c.

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

      #define  FILLEN   128
      #define  TYPLEN   32
      #define  SRCLEN   128

      SpiceInt        which;
      SpiceInt        count;
      SpiceInt        handle;

      SpiceChar       file  [FILLEN];
      SpiceChar       filtyp[TYPLEN];
      SpiceChar       source[SRCLEN];

      SpiceBoolean    found;

      int main()
         {
         furnsh_c( "/kernels/standard.tm" );

         ktotal_c ( "spk", &count );

         if ( count == 0 )
            {
            printf ( "No SPK files loaded at this time.\n" );
            }
         else
            {
            printf ( "The loaded SPK files are: \n\n" );
            }

         for ( which = 0;  which < count;  which++ )
            {
            kdata_c ( which,  "spk",    FILLEN,   TYPLEN, SRCLEN,
                      file,   filtyp,  source,  &handle,  &found );
            printf ( "%s\n",  file   );
            }

         }

-Restrictions

   None.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman    (JPL)
   W.L. Taber      (JPL)

-Version

   -CSPICE Version 1.1.3, 02-MAY-2008 (EDW)

      standard.ker renamed standard.tm

   -CSPICE Version 1.1.2, 05-SEP-2007 (EDW)

      Expanded Examples section to a full, compilable program.

   -CSPICE Version 1.1.1, 29-DEC-2004 (LSE)

      Corrected example code to match routine's argument list.
      (2 arguments reversed)

   -CSPICE Version 1.1.0, 02-FEB-2003 (EDW)

      Corrected example code to match routine's argument list.

   -CSPICE Version 1.0.0, 12-SEP-1999 (NJB) (WLT)

-Index_Entries

   Retrieve information on loaded SPICE kernels

-&
*/

{   /* Begin kdata_c */


    /*
    Local variables
    */
    logical                 fnd;


    /*
    Participate in error tracing.
    */
    chkin_c ( "kdata_c" );


    /*
    Check the input string kind to make sure the pointer is non-null
    and the string length is non-zero.
    */
    CHKFSTR ( CHK_STANDARD, "kdata_c", kind );


    /*
    Make sure the output string file has at least enough room for one
    output character and a null terminator.  Also check for a null
    pointer.
    */
    CHKOSTR ( CHK_STANDARD, "kdata_c", file, fillen );


    /*
    Make sure the output string filtyp has at least enough room for one
    output character and a null terminator.  Also check for a null
    pointer.
    */
    CHKOSTR ( CHK_STANDARD, "kdata_c", filtyp, typlen );


    /*
    Make sure the output string source has at least enough room for one
    output character and a null terminator.  Also check for a null
    pointer.
    */
    CHKOSTR ( CHK_STANDARD, "kdata_c", source, srclen );


    /*
    Map the input index from C to Fortran style.
    */

    which++;


    /*
    Call the f2c'd routine.
    */
    kdata_ (  ( integer   * ) &which,
              ( char      * ) kind,
              ( char      * ) file,
              ( char      * ) filtyp,
              ( char      * ) source,
              ( integer   * ) handle,
              ( logical   * ) &fnd,
              ( ftnlen      ) strlen(kind),
              ( ftnlen      ) fillen-1,
              ( ftnlen      ) typlen-1,
              ( ftnlen      ) srclen-1     );


    /*
    Convert the output strings from Fortran style to C style.  Set
    the SpiceBoolean output found flag.
    */
    F2C_ConvertStr( fillen, file   );
    F2C_ConvertStr( typlen, filtyp );
    F2C_ConvertStr( srclen, source );

    *found = fnd;


    chkout_c ( "kdata_c" );

} /* End kdata_c */
Exemple #9
0
   void spksfs_c ( SpiceInt        body,
                   SpiceDouble     et,
                   SpiceInt        idlen,
                   SpiceInt      * handle,
                   SpiceDouble     descr [5],
                   SpiceChar     * ident,
                   SpiceBoolean  * found     ) 
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   body       I   Body ID. 
   et         I   Ephemeris time. 
   idlen      I   Length of output segment ID string.
   handle     O   Handle of file containing the applicable segment. 
   descr      O   Descriptor of the applicable segment. 
   ident      O   Identifier of the applicable segment. 
   found      O   Indicates whether or not a segment was found. 
   SIDLEN     P   Maximum length of segment ID.

-Detailed_Input
 
   body       is the NAIF integer code of an ephemeris object, 
              typically a solar system body. 
 
   et         is a time, in seconds past the epoch J2000 TDB. 
 
   idlen      is the allowed length of the output string.  This length
              must large enough to hold the output segment ID plus the
              null terminator. SPK segment identifiers may contain up
              to SIDLEN characters, excluding the null terminator.

-Detailed_Output
 
   handle     is the handle of the SPK file containing a located
              segment.
 
   descr      is the descriptor of a located SPK segment. `descr'
              has length 5.
 
   ident      is the SPK segment identifier of a located SPK segment.
 
   found      indicates whether a requested segment was found or not.
              The other output arguments are valid only if `found'
              is set to SPICETRUE.
 
-Parameters
 
   SIDLEN     is the maximum number of characters in an SPK segment
              identifier, excluding the null terminator.

              SIDLEN is set to 40.
 
-Exceptions
 
   1) If an attempt is made to call spksfs_c when there aren't any 
      SPK files loaded, the error SPICE(NOLOADEDFILES) is signaled.

   2) With the exception of Fortran READ errors, any errors
      that occur while this routine attempts to extract segment
      descriptors from loaded SPK files will be diagnosed and signaled
      by routines in the call tree of this routine.

      Note however that I/O errors occurring during reads of DAF
      double precision records are NOT treated as SPICE errors
      and are not signaled.
 
-Files
 
   All SPK files loaded by furnsh_c or spklef_c are potential search
   targets for spksfs_c.
 
-Particulars
    
   This routine finds the highest-priority segment, in any loaded 
   SPK file, such that the segment provides data for the specified 
   body and epoch. 
 
-Examples
 
 
   1) Find a segment for the Pluto barycenter, with coverage for
      a specified epoch, in a JPL planetary SPK file.

      This example uses the following meta-kernel:


         KPL/MK

         This meta-kernel is intended to support operation of SPICE
         example programs. The kernels shown here should not be
         assumed to contain adequate or correct versions of data
         required by SPICE-based user applications.

         In order for an application to use this meta-kernel, the
         kernels referenced here must be present in the user's
         current working directory.

         The names and contents of the kernels referenced
         by this meta-kernel are as follows:

            File name                     Contents
            ---------                     --------
            de421.bsp                     Planetary ephemeris
            naif0010.tls                  Leapseconds


         \begindata

            KERNELS_TO_LOAD = ( 'de421.bsp'
                                'naif0010.tls'  )

         \begintext

         End of meta-kernel



      Example code starts here.

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

         int main()
         {
            /.
            Local parameters 
            ./
            #define ND                       2
            #define NI                       6
            #define DSCSIZ                   5
            #define SIDLEN1                 41

            /.
            Local variables 
            ./
            SpiceBoolean            found;

            SpiceChar               segid   [ SIDLEN1 ];
            SpiceChar             * reqtim;

            SpiceDouble             dc      [ ND ];
            SpiceDouble             descr   [ DSCSIZ ];
            SpiceDouble             et;

            SpiceInt                handle;
            SpiceInt                ic      [ NI ];
            SpiceInt                idcode;

            /.
            Load a meta-kernel that specifies a planetary SPK file
            and leapseconds kernel. The contents of this meta-kernel
            are displayed above.
            ./
            furnsh_c ( "spksfs.tm" );

            /.
            Get the NAIF ID code for the Pluto system barycenter.
            This is a built-in ID code, so something's seriously
            wrong if we can't find the code.
            ./
            bodn2c_c ( "PLUTO BARYCENTER", &idcode, &found );

            if ( !found )
            {
               sigerr_c( "SPICE(BUG)" );
            }

            /.
            Pick a request time; convert to seconds past J2000 TDB.
            ./
            reqtim = "2011 FEB 18 UTC";

            str2et_c ( reqtim, &et );

            /.
            Find a loaded segment for the specified body and time. 
            ./
            spksfs_c ( idcode, et, SIDLEN1, &handle, descr, segid, &found );

            if ( !found )
            {
               printf ( "No descriptor was found for ID %ld at "
                        "TDB %24.17e\n", 
                        (long) idcode,
                        et                                       );
            }
            else
            {
               /.
               Display the DAF file handle.
               ./
               printf ( "\n"
                        "DAF handle: %ld\n"
                        "\n",
                        (long)handle        );

               /.
               Display the segment ID.

               Unpack the descriptor. Display the contents.
               ./
               dafus_c ( descr, ND, NI, dc, ic );

               printf ( "Segment found.\n"
                        "   Segment ID:        %s\n"
                        "   Body ID code:      %ld\n"
                        "   Center ID code:    %ld\n"
                        "   Frame ID code:     %ld\n"
                        "   SPK data type:     %ld\n"
                        "   Start time (TDB):  %24.17e\n"
                        "   Stop time  (TDB):  %24.17e\n",
                        segid,
                        (long) ic[0],
                        (long) ic[1],
                        (long) ic[2],
                        (long) ic[3],
                        dc[0],
                        dc[1]                             );
            }

            return ( 0 );
         }

 
      When executed on a PC/Linux/gcc platform, this program 
      produced the following output:
      

         DAF handle: 1

         Segment found.
            Segment ID:        DE-0421LE-0421
            Body ID code:      9
            Center ID code:    0
            Frame ID code:     1
            SPK data type:     2
            Start time (TDB):  -3.16919520000000000e+09
            Stop time  (TDB):   1.69685280000000000e+09
 


-Restrictions

   1) If a Fortran I/O error occurs while this routine searches a
      loaded SPK file, the internal state of SPK segment and file
      selection routines, which are all entry points in the f2c'd
      version for the Fortran routine SPKBSR, may be corrupted.

-Literature_References
 
   SPK Required Reading. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL) 
   R.E. Thurman    (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 05-OCT-2012 (NJB) (RET)

-Index_Entries
 
   select spk file and segment 
 
-&
*/

{  /* Begin spksfs_c */


   /*
   Local variables
   */
   logical                 fnd;


   /*
   Participate in error tracing.
   */
   chkin_c ( "spksfs_c" );


   /*
   Make sure the output segment ID string has at least enough room for
   one output character and a null terminator.  Also check for a null
   pointer.
   */
   CHKOSTR ( CHK_STANDARD, "spksfs_c", ident, idlen );


   /*
   Call the f2c'd routine. 
   */
   spksfs_ ( (integer    *) &body,
             (doublereal *) &et,
             (integer    *) handle,
             (doublereal *) descr,
             (char       *) ident,
             (logical    *) &fnd,
             (ftnlen      ) idlen-1  );

   /*
   Set the output found flag based on the local one of
   type logical. 
   */

   *found = (SpiceBoolean) fnd;


   /*
   Convert the output segment ID string from Fortran to C style. 

   Note that this is necessary even if the found flag is false
   or if a SPICE error was signaled, since it's unsafe to return
   a string without a null terminator.
   */
   F2C_ConvertStr ( idlen, ident );


   chkout_c ( "spksfs_c" );

} /* End spksfs_c */
Exemple #10
0
   void dasac_c ( SpiceInt       handle,
                  SpiceInt       n,
                  SpiceInt       buflen,
                  const void   * buffer  ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   DAS handle of a file opened with write access. 
   n          I   Number of comments to put into the comment area. 
   buflen     I   Line length associated with buffer.
   buffer     I   Buffer of lines to be put into the comment area. 
 
-Detailed_Input
 
   handle   The file handle of a binary DAS file which has been 
            opened with write access. 
 
   n        The number of strings in buffer that are to be 
            appended to the comment area of the binary DAS file 
            attached to handle. 

   buflen   is the common length of the strings in buffer, including the 
            terminating nulls.
 
   buffer   A buffer containing comments which are to be added 
            to the comment area of the binary DAS file attached 
            to handle.  buffer should be declared as follows:
              
               ConstSpiceChar   buffer [n][buflen]
              
            Each string in buffer is null-terminated.
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the number of comments to be added is not positive, the 
      error SPICE(INVALIDARGUMENT) will be signaled. 
 
   2) If a non-null, non printing ASCII character is encountered in the 
      comments, the error SPICE(ILLEGALCHARACTER) will be 
      signaled. 
 
   3) If the binary DAS file attached to handle is not open for 
      write access, an error will be signaled by a routine called 
      by this routine. 
 
   4) If the input buffer pointer is null, the error SPICE(NULLPOINTER) 
      will be signaled.

   5) If the input buffer string length buflen is not at least 2, 
      the error SPICE(STRINGTOOSHORT) will be signaled.

-Files
 
   See argument handle in Detailed_Input. 
 
-Particulars
 
   Binary DAS files contain a data area which is reserved for storing 
   annotations or descriptive textual information about the data 
   contained in a file. This area is referred to as the "comment 
   area" of the file. The comment area of a DAS file is a line 
   oriented medium for storing textual information. The comment 
   area preserves any leading or embedded white space in the line(s) 
   of text which are stored so that the appearance of the 
   information will be unchanged when it is retrieved (extracted) at 
   some other time. Trailing blanks, however, are NOT preserved, 
   due to the way that character strings are represented in 
   standard Fortran 77. 
 
   This routine will take a buffer of text lines and add (append) 
   them to the comment area of a binary DAS file. If there are no 
   comments in the comment area of the file, then space will be 
   allocated and the text lines in buffer will then placed into the 
   comment area. The text lines may contain only printable ASCII 
   characters (decimal values 32 - 126). 
 
   There is no maximum length imposed on the significant portion 
   of a text line that may be placed into the comment area of a 
   DAS file. The maximum length of a line stored in the comment 
   area should be reasonable, however, so that they may be easily 
   extracted. A good value for this would be 255 characters, as 
   this can easily accommodate "screen width" lines as well as 
   long lines which may contain some other form of information. 
 
-Examples
 
   Let 
 
      handle   be the handle for a DAS file which has been opened 
               with write access. 

      n        be the number of lines of text to be added to the 
               comment area of the binary DAS file attached to 
               handle. 

      BUFLEN   be the declared line length of the buffer.

      buffer   is a list of text lines to be added to the comment 
               area of the binary DAS file attached to handle. 
 
   The call 
 
      dasac_c ( handle, n, BUFLEN, buffer );
 
   will append the first n line(s) in buffer to the comment area 
   of the binary DAS file attached to handle. 
 
-Restrictions
 
   1) This routine uses constants that are specific to the ASCII 
      character sequence. The results of using this routine with 
      a different character sequence are unpredictable. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
   K.R. Gehringer (JPL) 
 
-Version
 
   -CSPICE Version 1.1.0, 02-MAR-2003 (NJB) 

       Added error check in wrapper for non-positive
       buffer line count.

   -CSPICE Version 1.0.0, 25-FEB-2003 (NJB) (KRG)

-Index_Entries
 
    add comments to a binary das file 
    append comments to a das file comment area 
 
-&
*/

{ /* Begin dasac_c */


   /*
   Local variables
   */

   SpiceChar             * fCvalsArr;

   SpiceInt                fCvalsLen;


   /*
   Participate in error tracing.
   */
   if ( return_c() )
   {
      return;
   }
   chkin_c ( "dasac_c" );

   /*
   Check the line count of the input buffer. 
   */
   if ( n < 1 ) 
   {
      setmsg_c ( "Comment buffer line count n = #; must be positive." );
      errint_c ( "#", n                                               );
      sigerr_c ( "SPICE(INVALIDARGUMENT)"                             );
      chkout_c ( "dasac_c"                                            );
      return;
   }

   /*
   Check the input buffer for null pointer or short lines. 
   */
   CHKOSTR ( CHK_STANDARD, "dasac_c", buffer, buflen );


   /*
   Map the input buffer to a Fortran-style buffer. 
   */
   C2F_MapStrArr ( "dasac_c", n, buflen, buffer, &fCvalsLen, &fCvalsArr );

   if ( failed_c() )
   {
      chkout_c ( "dasac_c" );
      return;
   }


   /*
   Call the f2c'd routine.
   */
   dasac_ (  ( integer    * ) &handle,
             ( integer    * ) &n,
             ( char       * ) fCvalsArr,
             ( ftnlen       ) fCvalsLen );


   /*
   Free the dynamically allocated array.
   */
   free ( fCvalsArr );


   chkout_c ( "dasac_c" );

} /* End dasac_c */
Exemple #11
0
   void ekcii_c ( ConstSpiceChar   * table,
                  SpiceInt           cindex,
                  SpiceInt           lenout,
                  SpiceChar        * column,
                  SpiceEKAttDsc    * attdsc  ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   table      I   Name of table containing column. 
   cindex     I   Index of column whose attributes are to be found. 
   lenout     I   Maximum allowed length of column name.
   column     O   Name of column. 
   attdsc     O   Column attribute descriptor. 
 
-Detailed_Input
 
   table          is the name of a loaded EK table.  Case is not 
                  significant. 
 
   cindex         is the index, within TABLE's column attribute 
                  table, of the column whose attributes are to be 
                  found.  The indices of the column table entries 
                  range from 0 to ccount-1, where ccount is the value 
                  returned by the entry point ekccnt_c. 
 
   lenout         is the maximum allowed length of the output column
                  name, including the terminating null.  Column names
                  can be accommodated by a character array of length
                  SPICE_EK_CSTRLN.  This constant is declared in the
                  header file SpiceEK.h.

-Detailed_Output
 
   column         is the name of the specified column. 
 
   attdsc         is an EK column attribute descriptor.  See the header
                  file SpiceEK.h for details.
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If the specified table is not loaded, the error 
       SPICE(TABLENOTLOADED) is signaled. 
 
   2)  If the input argument cindex is less than 0 or greater 
       than or equal to the number of columns in table, the error 
       SPICE(INVALIDINDEX) is signaled. 
    
   3) If the output string pointer is null, the error SPICE(NULLPOINTER)
      is signaled.
      
   4) If the output string has length less than two characters, it 
      is too short to contain one character of output data plus a null  
      terminator, so it cannot be passed to the underlying Fortran 
      routine.  In this event, the error SPICE(STRINGTOOSHORT) is
      signaled.
      
   5) If the length of column (indicated by lenout) is at least two
      characters but not large enough to contain the output string,
      the output string will be truncated on the right. 

-Files
 
   The returned column name and descriptor are based on the currently 
   loaded EK files. 
 
-Particulars
 
   This routine is a utility that allows a calling routine to 
   determine the attributes of the currently loaded columns. 
 
-Examples
 
   1)  Dump the names and attributes of the columns in each loaded 
       table.  ekcii_c is used to obtain column names and attributes.


          #include "SpiceUsr.h"
          #include "SpiceEK.h"

          #define FILEN           256

          SpiceChar               colnam  [ SPICE_EK_CSTRLN ];
          SpiceChar               ek      [ FILEN ];
          SpiceChar               tabnam  [ SPICE_EK_TSTRLN ];

          SpiceChar             * typstrs [ 4 ] =
                                  {
                                     "CHR", "DP", "INT", "TIME" 
                                  };

          SpiceEKAttDsc           attdsc;

          SpiceInt                i;
          SpiceInt                ncols;
          SpiceInt                ntab;
          SpiceInt                tab;

          prompt_c ( "Enter name of EK to examine > ", FILEN, ek );

          furnsh_c ( ek );

          /. 
          Get the number of loaded tables. 
          ./
          ekntab_c ( &ntab );

          for ( tab = 0;  tab < ntab;  tab++ )
          {
             /.
             Get the name of the current table, and look up 
             the column count for this table. 
             ./
             ektnam_c ( tab, SPICE_EK_TSTRLN, tabnam );

             ekccnt_c ( tabnam, &ncols );

             printf ( "Table = %s\n\n", tabnam );
  

             /.
             For each column in the current table, look up the 
             column's attributes.  The attribute block 
             index parameters are defined in the include file 
             ekattdsc.inc. 
             ./

             for ( i = 0;  i < ncols;  i++ )
             {
                ekcii_c ( tabnam, i, SPICE_EK_CSTRLN, colnam, &attdsc );
 
                printf ( "Column = %s\n", colnam );

 
                /.
                Write out the current column's data type. 
                ./

                printf ( "Type = %s\n", typstrs[(int)attdsc.dtype] );

                if ( attdsc.dtype == SPICE_CHR )
                {
                   if ( attdsc.strlen == SPICE_EK_VARSIZ )
                   {
                      printf ( "String length = VARIABLE\n" );
                   }
                   else
                   {
                       printf ( "String length = %ld\n", 
                               (SpiceInt) attdsc.strlen );
                   }
                }

                /.
                Write out the current column's entry size. 
                ./                
                printf ( "Size = %ld\n", attdsc.size );
 

                /.
                Indicate whether the current column is indexed. 
                ./
                if ( attdsc.indexd == SPICETRUE )
                {
                   printf ( "Indexed.\n" );
                }
                else
                {
                   printf ( "Not indexed.\n" );
                }
 
                /.
                Indicate whether the current column allows 
                null values. 
                ./
                if ( attdsc.nullok == SPICETRUE )
                {
                   printf ( "Null values allowed.\n" );
                }
                else
                {
                   printf ( "Null values not allowed.\n" );
                }
             }
             /.
             We're done with the current column.
             ./
          }
          /.
          We're done with the current table.
          ./
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.0.1, 26-MAR-2003 (NJB) 

       Fixed description of exception (5):  replaced "lenout-1"
       with "lenout."  Removed spurious word "clock" from string
       description.

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

-Index_Entries
 
   return information on loaded EK column specified by index 
 
-&
*/

{ /* Begin ekcii_c */

   /*
   Local constants
   */
   #define   CLSIDX        0
   #define   TYPIDX        ( CLSIDX + 1 )
   #define   LENIDX        ( TYPIDX + 1 )
   #define   SIZIDX        ( LENIDX + 1 )
   #define   IXTIDX        ( SIZIDX + 1 )
   #define   NULIDX        ( IXTIDX + 1 )
   #define   DSCSIZ        ( NULIDX + 1 )

   /*
   Local variables
   */
   integer                 fAttDsc [ DSCSIZ ];


   /*
   Participate in error tracing.
   */
   chkin_c ( "ekcii_c" );

   /*
   Make sure the output column has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "ekcii_c", column, lenout );

   /*
   Map the column index to a Fortran-style index. 
   */   
   cindex++;

   /*
   Call the underlying f2c'd routine.  We'll get back individual 
   attributes which we'll use to populate the output attribute
   descriptor. 
   */
   ekcii_ (  ( char    * ) table, 
             ( integer * ) &cindex, 
             ( char    * ) column,
             ( integer * ) fAttDsc,
             ( ftnlen    ) strlen(table),
             ( ftnlen    ) lenout-1       );  

   /*
   Convert the output column name to a C-style string. 
   */
   F2C_ConvertStr ( lenout, column );


   /*
   Fill in the output attribute descriptor. 

   Note that the CSPICE integer codes for data types are one less
   than their corresponding codes in SPICELIB.

   The integer code indicating "variable array size" is the same
   in CSPICE and SPICELIB, so the size attribute may be copied directly
   from the integer array fAttDsc.
   */
   attdsc->cclass  = ( SpiceInt        )   fAttDsc[CLSIDX];
   attdsc->dtype   = ( SpiceEKDataType ) ( fAttDsc[TYPIDX] - 1  );
   attdsc->strlen  = ( SpiceInt        )   fAttDsc[LENIDX];
   attdsc->size    = ( SpiceInt        )   fAttDsc[SIZIDX];
   attdsc->indexd  = ( SpiceBoolean    ) ( fAttDsc[IXTIDX] >= 0 );
   attdsc->nullok  = ( SpiceBoolean    ) ( fAttDsc[NULIDX] >= 0 );


   chkout_c ( "ekcii_c" );

} /* End ekcii_c */
Exemple #12
0
   void lmpool_c ( const void  * cvals,
                   SpiceInt      lenvals,
                   SpiceInt      n       ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   cvals      I   An array that contains a SPICE text kernel.
   lenvals    I   Length of strings in cvals.
   n          I   The number of entries in cvals. 
 
-Detailed_Input
 
   cvals          is an array of strings that contains lines of text 
                  that could serve as a SPICE text kernel.  cvals is 
                  declared as follows:
              
                     ConstSpiceChar   cvals [n][lenvals]
              
                  Each string in cvals is null-terminated.
              
   lenvals        is the common length of the strings in cvals,
                  including the terminating nulls.
              
   n              is the number of strings in cvals. 
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the input string pointer is null, the error SPICE(NULLPOINTER) 
      will be signaled.

   2) If the input string length lenvals is not at least 2, the error
      SPICE(STRINGTOOLSHORT) will be signaled.

   3) The error 'SPICE(BADVARNAME)' signals if a kernel pool
      variable name length exceeds 32.

   4) Other exceptions are diagnosed by routines in the call tree of 
      this routine.
-Files
 
   None. 
 
-Particulars
 
   This routine allows you to store a text kernel in an internal 
   array of your program and load this array into the kernel pool 
   without first storing its contents as a text kernel. 

   Kernel pool variable names are restricted to a length of 32
   characters or less.
 
-Examples
 
   Suppose that your application is not particularly sensitive 
   to the current number of leapseconds but that you would 
   still like to use a relatively recent leapseconds kernel 
   without requiring users to load a leapseconds kernel into 
   the program.  The example below shows how you might set up 
   the initialization portion of your program. 
 
      #include "SpiceUsr.h"
      
      #define LNSIZE          81
      #define NLINES          27
      
      SpiceChar               textbuf[NLINES][LNSIZE] = 
                     {
                        "DELTET/DELTA_T_A = 32.184",
                        "DELTET/K         = 1.657D-3",
                        "DELTET/EB        = 1.671D-2",
                        "DELTET/M         = ( 6.239996 1.99096871D-7 )",
                        "DELTET/DELTA_AT  = ( 10, @1972-JAN-1",
                        "                     11, @1972-JUL-1",
                        "                     12, @1973-JAN-1",
                        "                     13, @1974-JAN-1",
                        "                     14, @1975-JAN-1",
                        "                     15, @1976-JAN-1",
                        "                     16, @1977-JAN-1",
                        "                     17, @1978-JAN-1",
                        "                     18, @1979-JAN-1",
                        "                     19, @1980-JAN-1",
                        "                     20, @1981-JUL-1",
                        "                     21, @1982-JUL-1",
                        "                     22, @1983-JUL-1",
                        "                     23, @1985-JUL-1",
                        "                     24, @1988-JAN-1",
                        "                     25, @1990-JAN-1",
                        "                     26, @1991-JAN-1",
                        "                     27, @1992-JUL-1",
                        "                     28, @1993-JUL-1",
                        "                     29, @1994-JUL-1",
                        "                     30, @1996-JAN-1",
                        "                     31, @1997-JUL-1",
                        "                     32, @1999-JAN-1 )"
                     };
                      
      lmpool_c ( textbuf, LNSIZE, NLINES );
 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 
-Version

   -CSPICE Version 1.3.1,  10-FEB-2010 (EDW)

      Added mention of the restriction on kernel pool variable 
      names to 32 characters or less.

   -CSPICE Version 1.3.0, 12-JUL-2002 (NJB)

      Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.

   -CSPICE Version 1.2.0, 28-AUG-2001 (NJB)

      Const-qualified input array.

   -CSPICE Version 1.1.0, 14-FEB-2000 (NJB)

       Calls to C2F_CreateStrArr replaced with calls to error-signaling 
       version of this routine:  C2F_CreateStrArr_Sig.
      
   -CSPICE Version 1.0.0, 08-JUN-1999 (NJB) (WLT) 

-Index_Entries
 
   Load the kernel pool from an internal text buffer 
 
-&
*/

{ /* Begin lmpool_c */



   /*
   Local variables
   */

   SpiceChar             * fCvalsArr;

   SpiceInt                fCvalsLen;


   /*
   Participate in error tracing.
   */
   chkin_c ( "lmpool_c" );

   /*
   Make sure the input string pointer is non-null and that the
   length lenvals is sufficient.  
   */
   CHKOSTR ( CHK_STANDARD, "lmpool_c", cvals, lenvals );


   /*
   Create a Fortran-style string array.
   */
   C2F_MapStrArr ( "lmpool_c", n, lenvals, cvals, &fCvalsLen, &fCvalsArr );

   if ( failed_c() )
   {
      chkout_c ( "lmpool_c" );
      return;
   }


   /*
   Call the f2c'd routine.
   */
   lmpool_ (  ( char       * ) fCvalsArr,
              ( integer    * ) &n,
              ( ftnlen       ) fCvalsLen );


   /*
   Free the dynamically allocated array.
   */
   free ( fCvalsArr );
   
   chkout_c ( "lmpool_c" );

} /* End lmpool_c */
Exemple #13
0
void ccifrm_c ( SpiceInt          frclss,
                SpiceInt          clssid,
                SpiceInt          lenout,
                SpiceInt        * frcode,
                SpiceChar       * frname,
                SpiceInt        * center,
                SpiceBoolean    * found   )


/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   frclss     I   Class of frame.
   clssid     I   Class ID of frame.
   lenout     I   Maximum length of output string.
   frcode     O   ID code of the frame.
   frname     O   Name of the frame.
   center     O   ID code of the center of the frame.
   found      O   SPICETRUE if the requested information is available.

-Detailed_Input

   frclss     is the class or type of the frame. This identifies which
              subsystem will be used to perform frame transformations.

   clssid     is the ID code used for the frame within its class. This
              may be different from the frame ID code.

   lenout     The allowed length of the output frame name. This length
              must large enough to hold the output string plus the
              null terminator.  If the output string is expected to have
              n characters, `lenout' should be n + 1.

-Detailed_Output

   frcode      is the frame ID code for the reference frame
               identified by `frclss' and `clssid'.

   frname      is the name of the frame identified by
               `frclss' and `clssid'.

               `frname' should be declared

                   SpiceChar frname [33]

               to ensure that it can contain the full name of the
               frame.  If `frname' does not have enough room to hold
               the full name of the frame, the name will be truncated
               on the right.

   center      is the body ID code for the center of the reference
               frame identified  by `frclss' and `clssid'.

   found       is SPICETRUE if a valid frame specification
               corresponding to the input frame class and frame class
               ID is available, in which case the other outputs are
               valid. Otherwise, `found' is returned with the value
               SPICEFALSE.

-Parameters

   None.

-Exceptions

   1) This routine assumes that the first frame found with matching
      class and class ID is the correct one. SPICE's frame system
      does not diagnose the situation where there are multiple,
      distinct frames with matching classes and class ID codes, but
      this situation could occur if such conflicting frame
      specifications are loaded via one or more frame kernels. The
      user is responsible for avoiding such frame specification
      conflicts.

   2) If `frname' does not have room to contain the frame name, the
      name will be truncated on the right. (Declaring `frname' to have
      a length of 33 characters will ensure that the name will not be
      truncated.

   3) If a frame class assignment is found that associates a
      string (as opposed to numeric) value with a frame class
      keyword, the error SPICE(INVALIDFRAMEDEF) will be signaled.

   4) If a frame class assignment is found that matches the input
      class, but a corresponding class ID assignment is not
      found in the kernel pool, the error SPICE(INVALIDFRAMEDEF)
      will be signaled.

   5) If a frame specification is found in the kernel pool with
      matching frame class and class ID, but either the frame name
      or frame ID code are not found, the error
      SPICE(INVALIDFRAMEDEF) will be signaled.

   6) If a frame specification is found in the kernel pool with
      matching frame class and class ID, but the frame center
      is not found, the error will be diagnosed by routines
      in the call tree of this routine.

   7) The error SPICE(NULLPOINTER) is signaled if the output string
      pointer is null.

   8) The caller must pass a value indicating the length of the output
      string. If this value is not at least 2, the error
      SPICE(STRINGTOOSHORT) is signaled.


-Files

   The frame specifications sought by this routine may be provided
   by loaded frames kernels. Such kernels will always be required if
   the frame class is CK, TK, or dynamic, and will be required if
   the frame class is PCK but the frame of interest is not built-in.

-Particulars

   This routine allows the user to determine the frame associated
   with a given frame class and class ID code. The kernel pool is
   searched first for a matching frame; if no match is found, then
   the set of built-in frames is searched.

   Since the neither the frame class nor the class ID are primary
   keys, searching for matching frames is a linear (and therefore
   typically slow) process.

-Examples

   Suppose that you want to find the frame information of a named frame,
   "ITRF93" for this example. One could use the following code fragment:

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

      #define FRNAMLEN       33

      SpiceChar              frname[FRNAMLEN];
      SpiceInt               clss;
      SpiceInt               clss_ID;

      SpiceInt               frcode1;
      SpiceInt               frcode2;

      SpiceInt               center1;
      SpiceInt               center2;

      SpiceBoolean           found;

      int main()
         {

         namfrm_ ( "ITRF93", &frcode1, 6 );

         frinfo_c ( frcode1,
                    &center1, &clss, &clss_ID, &found );

         ccifrm_c ( clss, clss_ID, FRNAMLEN,
                    &frcode2,  frname, &center2, &found );

         if ( !found )
            {
            puts( "No joy");
            exit(1);
            }

         printf(  "Class     : %d \n"
                  "Class ID  : %d \n"
                  "Frame name: %s \n"
                  "Frame Code: %d \n"
                  "Center ID : %d \n",
                  clss, clss_ID, frname, frcode2, center2 );

         exit(0);
         }

   The program outputs:

      Class     : 2
      Class ID  : 3000
      Frame name: ITRF93
      Frame Code: 13000
      Center ID : 399

-Restrictions

   See item (1) in the Exceptions section above.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman    (JPL)

-Version

   -CSPICE Version 1.0.0, 14-JUL-2014 (NJB)

       Added to the Brief_I/O header section a description
       of input argument `lenout'.

    Last update was  10-JAN-2011 (NJB)(EDW)

-Index_Entries

   Find info associated with a frame class and class id
   Map frame class and class id to frame info
   Map frame class and class id to frame name, id, and center

-&
*/

{   /* Begin ccifrm_c */



    /*
    Local variables
    */
    logical                 fnd;

    /*
    Participate in error tracing.
    */
    chkin_c ( "ccifrm_c" );

    /*
    Make sure the output string has at least enough room for one output
    character and a null terminator.  Also check for a null pointer.
    */
    CHKOSTR ( CHK_STANDARD, "ccifrm_c", frname, lenout );

    /*
    Map the inputs to frame attributes, if possible.
    */
    ccifrm_( ( integer * ) &frclss,
             ( integer * ) &clssid,
             ( integer * ) frcode,
             ( char    * ) frname,
             ( integer * ) center,
             ( logical * ) &fnd,
             ( ftnlen    ) lenout-1 );

    /*
    The string returned, output, is a Fortranish type string.
    Convert the string to C style.
    */
    F2C_ConvertStr ( lenout, frname );

    /*
    Return the FOUND flag as a SpiceBoolean value.
    */

    *found = (SpiceBoolean)fnd;


    chkout_c ( "ccifrm_c" );

} /* End ccifrm_c */
Exemple #14
0
void pcpool_c ( ConstSpiceChar  * name,
                SpiceInt          n,
                SpiceInt          lenvals,
                const void      * cvals    )
/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   name       I   The kernel pool name to associate with cvals.
   n          I   The number of values to insert.
   lenvals    I   The lengths of the strings in the array cvals.
   cvals      I   An array of strings to insert into the kernel pool.

-Detailed_Input

   name       is the name of the kernel pool variable to associate
              with the values supplied in the array cvals. 'name' is
              restricted to a length of 32 characters or less.

   n          is the number of values to insert into the kernel pool.

   lenvals    is the length of the strings in the array cvals,
              including the null terminators.

   cvals      is an array of strings to insert into the kernel
              pool.  cvals should be declared as follows:

                 char  cvals[n][lenvals];

-Detailed_Output

   None.

-Parameters

   None.

-Exceptions

   1) If name is already present in the kernel pool and there
      is sufficient room to hold all values supplied in values,
      the old values associated with name will be overwritten.

   2) If there is not sufficient room to insert a new variable
      into the kernel pool and name is not already present in
      the kernel pool, the error SPICE(KERNELPOOLFULL) is
      signaled by a routine in the call tree to this routine.

   3) If there is not sufficient room to insert the values associated
      with name, the error SPICE(NOMOREROOM) will be signaled.

   4) If either input string pointer is null, the error
      SPICE(NULLPOINTER) will be signaled.

   5) If the input string name has length zero, the error
      SPICE(EMPTYSTRING) will be signaled.

   6) If the input cvals string length is less than 2, the error
      SPICE(STRINGTOOSHORT) will be signaled.

   7) The error 'SPICE(BADVARNAME)' signals if the kernel pool
      variable name length exceeds 32.

-Files

   None.

-Particulars

   This entry point provides a programmatic interface for inserting
   character data into the SPICE kernel pool without reading an
   external file.

-Examples

   The following example program shows how a topocentric frame for a
   point on the surface of the earth may be defined at run time using
   pcpool_c, pdpool_c, and pipool_c.  In this example, the surface
   point is associated with the body code 300000.  To facilitate
   testing, the location of the surface point coincides with that of
   the DSN station DSS-12; the reference frame MYTOPO defined here
   coincides with the reference frame DSS-12_TOPO.

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

      int main()
      {
         /.
         The first angle is the negative of the longitude of the
         surface point; the second angle is the negative of the
         point's colatitude.
         ./
         SpiceDouble             angles [3]      =  { -243.1945102442646,
                                                       -54.7000629043147,
                                                       180.0              };

         SpiceDouble             et              =    0.0;
         SpiceDouble             rmat   [3][3];

         SpiceInt                axes   [3]      =  { 3, 2, 3 };
         SpiceInt                center          =    300000;
         SpiceInt                frclass         =    4;
         SpiceInt                frclsid         =    1500000;
         SpiceInt                frcode          =    1500000;

         /.
         Define the MYTOPO reference frame.

         Note that the third argument in the pcpool_c calls is
         the length of the final string argument, including the
         terminating null character.
         ./
         pipool_c ( "FRAME_MYTOPO",            1,     &frcode   );
         pcpool_c ( "FRAME_1500000_NAME",      1, 7,  "MYTOPO"  );
         pipool_c ( "FRAME_1500000_CLASS",     1,     &frclass  );
         pipool_c ( "FRAME_1500000_CLASS_ID",  1,     &frclsid  );
         pipool_c ( "FRAME_1500000_CENTER",    1,     &center   );

         pcpool_c ( "OBJECT_300000_FRAME",     1, 7,  "MYTOPO"  );

         pcpool_c ( "TKFRAME_MYTOPO_RELATIVE", 1, 7,  "ITRF93"  );
         pcpool_c ( "TKFRAME_MYTOPO_SPEC",     1, 7,  "ANGLES"  );
         pcpool_c ( "TKFRAME_MYTOPO_UNITS",    1, 8,  "DEGREES" );
         pipool_c ( "TKFRAME_MYTOPO_AXES",     3,     axes      );
         pdpool_c ( "TKFRAME_MYTOPO_ANGLES",   3,     angles    );

         /.
         Load a high precision binary earth PCK. Also load a
         topocentric frame kernel for DSN stations. The file names
         shown here are simply examples; users should replace these
         with the names of appropriate kernels.
         ./
         furnsh_c ( "earth_000101_060207_051116.bpc" );
         furnsh_c ( "earth_topo_050714.tf"           );

         /.
         Look up transformation from DSS-12_TOPO frame to MYTOPO frame.
         This transformation should differ by round-off error from
         the identity matrix.
         ./
         pxform_c ( "DSS-12_TOPO", "MYTOPO", et, rmat );

         printf   ( "\n"
                    "DSS-12_TOPO to MYTOPO transformation at "
                    "et %23.16e = \n"
                    "\n"
                    "    %25.16f  %25.16f  %25.16f\n"
                    "    %25.16f  %25.16f  %25.16f\n"
                    "    %25.16f  %25.16f  %25.16f\n",
                    et,
                    rmat[0][0],  rmat[0][1],  rmat[0][2],
                    rmat[1][0],  rmat[1][1],  rmat[1][2],
                    rmat[2][0],  rmat[2][1],  rmat[2][2]       );

         return ( 0 );
      }


-Restrictions

   None.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman    (JPL)
   W.L. Taber      (JPL)

-Version

   -CSPICE Version 1.3.3,  17-JAN-2014 (NJB)

      Updated Index_Entries section.

   -CSPICE Version 1.3.2,  10-FEB-2010 (EDW)

      Added mention of the restriction on kernel pool variable
      names to 32 characters or less.

      Reordered header sections to conform to SPICE convention.

   -CSPICE Version 1.3.1, 17-NOV-2005 (NJB)

      Replaced code fragment in Examples section of header with
      smaller, complete program.

   -CSPICE Version 1.3.0, 12-JUL-2002 (NJB)

      Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.

   -CSPICE Version 1.2.0, 28-AUG-2001 (NJB)

      Const-qualified input array cvals.

   -CSPICE Version 1.1.0, 14-FEB-2000 (NJB)

       Calls to C2F_CreateStrArr replaced with calls to error-signaling
       version of this routine:  C2F_CreateStrArr_Sig.

   -CSPICE Version 1.0.0, 18-JUN-1999 (NJB) (WLT)

-Index_Entries

   Set the value of a character_variable in the kernel_pool

-&
*/

{   /* Begin pcpool_c */


    /*
    Local variables
    */
    SpiceChar             * fCvalsArr;

    SpiceInt                fCvalsLen;


    /*
    Participate in error tracing.
    */
    chkin_c ( "pcpool_c" );

    /*
    Check the input kernel variable name to make sure the pointer is
    non-null and the string length is non-zero.
    */
    CHKFSTR ( CHK_STANDARD, "pcpool_c", name );


    /*
    Make sure the input string pointer for the cvals array is non-null
    and that the length lenvals is sufficient.
    */
    CHKOSTR ( CHK_STANDARD, "pcpool_c", cvals, lenvals );


    /*
    Create a Fortran-style string array.
    */
    C2F_MapStrArr ( "pcpool_c",
                    n, lenvals, cvals, &fCvalsLen, &fCvalsArr );

    if ( failed_c() )
    {
        chkout_c ( "pcpool_c" );
        return;
    }


    /*
    Call the f2c'd routine.
    */
    pcpool_ (  ( char       * ) name,
               ( integer    * ) &n,
               ( char       * ) fCvalsArr,
               ( ftnlen       ) strlen(name),
               ( ftnlen       ) fCvalsLen     );


    /*
    Free the dynamically allocated array.
    */
    free ( fCvalsArr );


    chkout_c ( "pcpool_c" );

} /* End pcpool_c */
Exemple #15
0
   void ekbseg_c ( SpiceInt           handle,
                   ConstSpiceChar   * tabnam,
                   SpiceInt           ncols,
                   SpiceInt           cnmlen,
                   const void       * cnames,
                   SpiceInt           declen,
                   const void       * decls,
                   SpiceInt         * segno  ) 
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   File handle. 
   tabnam     I   Table name. 
   ncols      I   Number of columns in the segment. 
   cnmlen     I   Length of names in in column name array.
   cnames     I   Names of columns. 
   declen     I   Length of declaration strings in declaration array.
   decls      I   Declarations of columns. 
   segno      O   Segment number. 
  
-Detailed_Input
 
   handle         the handle of an EK file that is open for writing. 
 
   tabnam         is the name of the EK table to which the current 
                  segment belongs.  All segments in the EK file 
                  designated by handle must have identical column 
                  attributes. tabnam must not exceed SPICE_EK_TNAMSZ
                  characters (see SpiceEK.h) in length.  Case is not 
                  significant. Table names must start with a letter and
                  contain only characters from the set
                  {A-Z,a-z,0-9,$,_}. 
 
   ncols          is the number of columns in a new segment. 

   cnmlen,
   cnames         are, respectively, the length of the column name
                  strings in the column name array, and the base
                  address of the array itself.  The array should have
                  dimensions
                  
                     [ncols][cnmlen]
                     
   declen,
   decls          are, respectively, the length of the declaration
                  strings in the declaration array, and the base 
                  address of the array itself.  The array should have
                  dimensions
                  
                     [ncols][declen]
                      
                  The Ith element of cnames and the Ith element of decls
                  apply to the Ith column in the segment. 
 
                  Column names must not exceed CSPICE_EK_CNAMSZ
                  characters (see SpiceEK.h) in length.  Case is not
                  significant.  Column names must start with a letter 
                  and contain only characters from the set 
                  {A-Z,a-z,0-9,$,_}. 
 
                  The declarations are strings that contain 
                  "keyword=value" assignments that define the 
                  attributes of the columns to which they apply.  The 
                  column attributes that are defined by a column 
                  declaration are: 
 
                     DATATYPE 
                     SIZE 
                     <is the column indexed?> 
                     <does the column allow null values?> 
 
                  The form of a declaration is 
 
                     "DATATYPE  = <type>, 
                      SIZE      = <size>, 
                      INDEXED   = <boolean>, 
                      NULLS_OK  = <boolean>" 
 
                  For example, an indexed, scalar, integer column 
                  that allows null values would have the declaration 
 
                     "DATATYPE  = INTEGER, 
                      SIZE      = 1, 
                      INDEXED   = TRUE, 
                      NULLS_OK  = TRUE" 
 
                  Commas are required to separate the assignments 
                  within declarations; white space is optional; 
                  case is not significant. 
 
                  The order in which the attribute keywords are 
                  listed in declaration is not significant. 
 
                  Every column in a segment must be declared. 
 
                  Each column entry is effectively an array, each 
                  element of which has the declared data type.  The 
                  SIZE keyword indicates how many elements are in 
                  each entry of the column in whose declaration the 
                  keyword appears.  Note that only scalar-valued 
                  columns (those for which SIZE = 1) may be 
                  referenced in query constraints.  A size 
                  assignment has the syntax 
 
                     SIZE = <integer> 
 
                  or 
                     SIZE = VARIABLE 
 
                  The size value defaults to 1 if omitted. 
 
                  The DATATYPE keyword defines the data type of 
                  column entries.  The DATATYPE assignment syntax 
                  has any of the forms 
 
                     DATATYPE = CHARACTER*(<length>) 
                     DATATYPE = CHARACTER*(*) 
                     DATATYPE = DOUBLE PRECISION 
                     DATATYPE = INTEGER 
                     DATATYPE = TIME 
 
                  As the datatype declaration syntax suggests, 
                  character strings may have fixed or variable 
                  length.  Variable-length strings are allowed only 
                  in columns of size 1. 
 
                  Optionally, scalar-valued columns may be indexed. 
                  To create an index for a column, use the assignment 
 
                     INDEXED = TRUE 
 
                  By default, columns are not indexed. 
 
                  Optionally, any column can allow null values.  To 
                  indicate that a column may allow null values, use 
                  the assigment 
 
                     NULLS_OK = TRUE 
 
                  in the column declaration.  By default, null 
                  values are not allowed in column entries. 

  


-Detailed_Output
 
   segno          is the number of the segment to which data is to be
                  added. Segments are numbered from 0 to nseg-1, where
                  nseg is the count of segments in the file.  Segment
                  numbers are used as unique identifiers by other EK
                  access routines.
  
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If handle is invalid, the error will be diagnosed by routines 
       called by this routine. 
 
   2)  If tabnam is more than SPICE_EK_TNAMSZ characters long, the 
       error is diagnosed by routines called by this routine. 
 
   3)  If tabnam contains any nonprintable characters, the error 
       is diagnosed by routines called by this routine. 
 
   4)  If ncols is non-positive or greater than the maximum allowed 
       number SPICE_EK_MXCLSG, the error SPICE(INVALIDCOUNT) is 
       signaled. 
 
   5)  If any column name exceeds SPICE_EK_CNAMSZ characters in 
       length, the error is diagnosed by routines called by this 
       routine. 
 
   6)  If any column name contains non-printable characters, the 
       error is diagnosed by routines called by this routine. 
 
   7)  If a declaration cannot be understood by this routine, the 
       error is diagnosed by routines called by this routine. 
 
   8)  If an non-positive string length or element size is specified, 
       the error is diagnosed by routines called by this routine. 
 
   9)  If an I/O error occurs while reading or writing the indicated 
       file, the error will be diagnosed by routines called by this 
       routine. 

   10) If the input string pointer for the table name is null, the 
       error SPICE(NULLPOINTER) will be signaled.
      
   12) If the input tablen name string has length zero, the error 
       SPICE(EMPTYSTRING) will be signaled.
 
   13) If the string pointer for cnames is null, the error
       SPICE(NULLPOINTER) will be signaled.
   
   14) If the string length cnmlen is less than 2, the error 
       SPICE(STRINGTOOSHORT) will be signaled.

   15) If the string pointer for decls is null, the error
       SPICE(NULLPOINTER) will be signaled.
   
   16) If the string length declen is less than 2, the error 
       SPICE(STRINGTOOSHORT) will be signaled.
   
-Files
 
   See the EK Required Reading for a discussion of the EK file 
   format. 
 
-Particulars
 
   This routine operates by side effects:  it prepares an EK for 
   the addition of a new segment.  It is not necessary to take 
   any special action to `complete' a segment; segments are readable 
   after the completion of any record insertion, deletion, write, 
   or update operation. 
 
-Examples
 
   1)  Suppose we have an E-kernel named ORDER_DB.EK 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 file ORDER_DB.EK contains two segments, 
       the first containing the DATAORDERS table and the second 
       containing the DATAITEMS table. 
 
       Below, we show how we'd open a new EK file and start the 
       first of the segments described above. 
 
       
       #include "SpiceUsr.h"
       #include <stdio.h>
       
       
       void main()
       {
          /.
          Constants
          ./
          #define  CNMLEN        SPICE_EK_CSTRLN
          #define  DECLEN        201
          #define  EKNAME        "order_db.ek"
          #define  FNMLEN        50
          #define  IFNAME        "Test EK/Created 20-SEP-1995"
          #define  LNMLEN        50
          #define  LSK           "leapseconds.ker"
          #define  NCOLS         6
          #define  NRESVC        0
          #define  TABLE         "DATAORDERS"
          #define  TNMLEN        CSPICE_EK_TAB_NAM_LEN
          #define  UTCLEN        30
          
          
          /.
          Local variables
          ./
          SpiceBoolean            nlflgs [ NROWS  ];
       
          SpiceChar               cdecls  [ NCOLS ] [ DECLEN ];
          SpiceChar               cnames  [ NCOLS ] [ CNMLEN ];
          SpiceChar               fnames  [ NROWS ] [ FNMLEN ];
          SpiceChar               lnames  [ NROWS ] [ LNMLEN ];
          SpiceChar               dateStr [ UTCLEN ];
        
          SpiceDouble             costs  [ NROWS ];
          SpiceDouble             ets    [ NROWS ];
       
          SpiceInt                cstids [ NROWS ];
          SpiceInt                ordids [ NROWS ];
          SpiceInt                handle;
          SpiceInt                i;
          SpiceInt                segno;
          SpiceInt                sizes  [ NROWS ];
          
          
          /.
          Load a leapseconds kernel for UTC/ET conversion.
          ./
          furnsh_c ( LSK );
          
          /.
          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 constant IFNAME is the internal file name. 
          ./
          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 segment. 
          ./
          ekbseg_c ( handle,  TABLE,   NCOLS,   CNMLEN,  
                     cnames,  DECLEN,  cdecls,  &segno  );

          /. 
          Add data to the segment.  No special action 
          is required to finish the segment. 
          ./
             [Data are added via calls to ekappr_c and the 
              ekacec_c, ekaced_c, and ekacei_c routines.  See any 
              of these routines for examples.] 
 
          /.
          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. 
          ./ 

 
          /. 
          The file must be closed by a call to ekcls_c. 
          ./
          ekcls_c ( handle ); 
       }
  
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.1.0, 12-JUL-2002 (NJB)

      Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.

   -CSPICE Version 1.0.0, 17-NOV-2001 (NJB)

-Index_Entries
 
   start new E-kernel segment 
   start new EK segment 
 
-&
*/

{ /* Begin ekbseg_c */



   /*
   Local variables
   */
   SpiceChar             * fCnameArr;
   SpiceChar             * fCdeclArr;

   SpiceInt                fCnameLen;
   SpiceInt                fCdeclLen;

   /*
   Participate in error tracing.
   */
   chkin_c ( "ekbseg_c" );

   /*
   Check the table name to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ekbseg_c", tabnam );

   /*
   Check the column name array to make sure the pointer is non-null 
   and the string length is non-zero.  Note:  this check is normally
   done for output strings:  CHKOSTR is the macro that does the job.
   */
   CHKOSTR ( CHK_STANDARD, "ekbseg_c", cnames, cnmlen );

   /*
   Check the declaration array to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKOSTR ( CHK_STANDARD, "ekbseg_c", decls, declen );

   C2F_MapStrArr ( "ekbseg_c", 
                   ncols, cnmlen, cnames, &fCnameLen, &fCnameArr );
   
   if ( failed_c() )
   {
      chkout_c ( "ekbseg_c" );
      return;
   }


   C2F_MapStrArr ( "ekbseg_c", 
                   ncols, declen, decls, &fCdeclLen, &fCdeclArr );
   
   if ( failed_c() )
   {
      free ( fCnameArr );
      
      chkout_c ( "ekbseg_c" );
      return;
   }
   

   /*
   Call the f2c'd Fortran routine.  Use explicit type casts for every
   type defined by f2c.
   */
   ekbseg_ ( ( integer  * ) &handle,
             ( char     * ) tabnam,
             ( integer  * ) &ncols,
             ( char     * ) fCnameArr,
             ( char     * ) fCdeclArr,
             ( integer  * ) segno,
             ( ftnlen     ) strlen(tabnam),
             ( ftnlen     ) fCnameLen,
             ( ftnlen     ) fCdeclLen       );

   /*
   Clean up all of our dynamically allocated arrays.
   */
   free ( fCnameArr );
   free ( fCdeclArr );

   /*
   Map segno to C style range.
   */
   
   (*segno)--;
   
   
   chkout_c ( "ekbseg_c" );

} /* End ekbseg_c */
Exemple #16
0
   void swpool_c ( ConstSpiceChar    * agent,
                   SpiceInt            nnames,
                   SpiceInt            lenvals,
                   const void        * names   ) 
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   agent      I   The name of an agent to be notified after updates. 
   nnames     I   The number of variables to associate with agent. 
   lenvals    I   Length of strings in the names array.
   names      I   Variable names whose update causes the notice. 
 
-Detailed_Input
 
   agent       is the name of a routine or entry point (agency) that 
               will want to know when a some variables in the kernel 
               pool have been updated. 
 
   nnames      is the number of kernel pool variable names that will 
               be associated with agent. 
 
   lenvals     is the length of the strings in the array names, 
               including the null terminators.  
              
   names       is an array of names of variables in the kernel pool. 
               Whenever any of these is updated, a notice will be 
               posted for agent so that one can quickly check 
               whether needed data has been modified. 
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Files
 
   None. 
 
-Exceptions
 
   1) If sufficient room is not available to hold a name or new agent,
      a routine in the call tree for this routine will signal an error.
 
   2) If either of the input string pointers are null, the error 
      SPICE(NULLPOINTER) will be signaled.
      
   3) If any input string agent has length zero, the error 
      SPICE(EMPTYSTRING) will be signaled.
      
   4) The caller must pass a value indicating the length of the strings
      in the names array.  If this value is not at least 2, the error
      SPICE(STRINGTOOSHORT) will be signaled.
      
-Particulars
 
   The kernel pool is a convenient place to store a wide variety of
   data needed by routines in CSPICE and routines that interface with
   CSPICE routines.  However, when a single name has a large quantity
   of data associated with it, it becomes inefficient to constantly
   query the kernel pool for values that are not updated on a frequent
   basis.
 
   This entry point allows a routine to instruct the kernel pool to
   post a message whenever a particular value gets updated. In this
   way, a routine can quickly determine whether or not data it requires
   has been updated since the last time the data was accessed.  This
   makes it reasonable to buffer the data in local storage and update
   it only when a variable in the kernel pool that affects this data
   has been updated.
 
   Note that swpool_c has a side effect.  Whenever a call to swpool_c
   is made, the agent specified in the calling sequence is added to the
   list of agents that should be notified that an update of its
   variables has occurred.  In other words the code
 
       swpool_c ( agent, nnames, lenvals, names   ); 
       cvpool_c ( agent,                  &update ); 
 
   will always return update as SPICETRUE. 
 
   This feature allows for a slightly cleaner use of swpool_c and
   cvpool_c as shown in the example below.  Because swpool_c
   automatically loads agent into the list of agents to notify of a
   kernel pool update, you do not have to include the code for fetching
   the initial values of the kernel variables in the initialization
   portion of a subroutine.  Instead, the code for the first fetch from
   the pool is the same as the code for fetching when the pool is
   updated.
 
-Examples
 
   Suppose that you have an application subroutine, MYTASK, that 
   needs to access a large data set in the kernel pool.  If this 
   data could be kept in local storage and kernel pool queries 
   performed only when the data in the kernel pool has been 
   updated, the routine can perform much more efficiently. 
 
   The code fragment below illustrates how you might make use of this 
   feature. 
 
      #include "SpiceUsr.h"
           .
           .
           .
      /.  
      On the first call to this routine establish those variables 
      that we will want to read from the kernel pool only when 
      new values have been assigned. 
      ./
      if ( first )
      {
         first = SPICEFALSE;
         swpool_c ( "MYTASK", nnames, lenvals, names ); 
      }
 
      /.
      If any of the variables has been updated, fetch them from the
      kernel pool.
      ./    
        
      cvpool_c ( "MYTASK", &update ); 
 
      if ( update )
      {
         for ( i = 0;  i < NVAR;  i++ )
         {
            gdpool_c( MYTASK_VAR[i], 1, NMAX, n[i], val[i], &found[i] );
         }
      }
 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 
-Version
 
   -CSPICE Version 1.3.0, 27-AUG-2002 (NJB)

      Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.

   -CSPICE Version 1.2.0, 28-AUG-2001 (NJB)

      Const-qualified input array names.

   -CSPICE Version 1.1.0, 14-FEB-2000 (NJB)

       Calls to C2F_CreateStrArr replaced with calls to error-signaling 
       version of this routine:  C2F_CreateStrArr_Sig.
      
   -CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (WLT)

-Index_Entries
 
   Watch for an update to a kernel pool variable 
   Notify a routine of an update to a kernel pool variable 
-&
*/

{ /* Begin swpool_c */


   /*
   Local variables
   */

   SpiceChar             * fCvalsArr;

   SpiceInt                fCvalsLen;


   /*
   Participate in error tracing.
   */
   chkin_c ( "swpool_c" );


   /*
   Make sure the input string pointer for agent is non-null 
   and that the length is sufficient.  
   */
   CHKFSTR ( CHK_STANDARD, "swpool_c", agent );

   /*
   Make sure the input string pointer for the names array is non-null 
   and that the length lenvals is sufficient.  
   */
   CHKOSTR ( CHK_STANDARD, "swpool_c", names, lenvals );

   /*
   Create a Fortran-style string array.
   */
   C2F_MapStrArr ( "swpool_c", 
                   nnames, lenvals, names, &fCvalsLen,  &fCvalsArr );

   if ( failed_c() )
   {
      chkout_c ( "swpool_c" );
      return;
   }


   /*
   Call the f2c'd routine.
   */
   swpool_ (  ( char       * ) agent,
              ( integer    * ) &nnames,
              ( char       * ) fCvalsArr,
              ( ftnlen       ) strlen(agent),
              ( ftnlen       ) fCvalsLen      );


   /*
   Free the dynamically allocated array.
   */
   free ( fCvalsArr );


   chkout_c ( "swpool_c" );

} /* End swpool_c */
Exemple #17
0
   void dasec_c ( SpiceInt         handle,
                  SpiceInt         bufsiz,
                  SpiceInt         buflen,
                  SpiceInt       * n,
                  void           * buffer,
                  SpiceBoolean   * done   ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   Handle of binary DAS file open with read access. 
   bufsiz     I   Maximum size, in lines, of buffer. 
   buflen     I   Line length associated with buffer.
   n          O   Number of comments extracted from the DAS file. 
   buffer     O   Buffer in which extracted comments are placed. 
   done       O   Indicates whether all comments have been extracted. 
 
-Detailed_Input
 
   handle   The file handle of a binary DAS file which has been 
            opened with read access. 
 
   bufsiz   The maximum number of comments that may be placed into 
            buffer. This would typically be the declared array size 
            for the C character string array passed into this 
            routine. 
 
   buflen   is the common length of the strings in buffer, including the 
            terminating nulls.

-Detailed_Output
 
   n        The number of comment lines extracted from the comment area
            of the binary DAS file attached to handle. This number will
            be <= bufsiz on output. If n == bufsiz and done !=
            SPICETRUE then there are more comments left to extract. If
            n == 0, then done == SPICETRUE, i.e., there were no
            comments in the comment area. If there are comments in the
            comment area, or comments remaining after the extraction
            process has begun, n > 0, always.
 
   buffer   A list of at most bufsiz comments which have been 
            extracted from the comment area of the binary DAS 
            file attached to handle.  buffer should be declared as 
            follows:
              
               ConstSpiceChar   buffer [bufsiz][buflen]
            
            Each string in buffer is null-terminated.
 
   done     A boolean flag indicating whether or not all of the 
            comment lines from the comment area of the DAS file have 
            been read. This variable has the value SPICETRUE after the 
            last comment line has been read. It will have the value 
            SPICEFALSE otherwise. 
 
            If there are no comments in the comment area, this 
            variable will have the value SPICETRUE, and n == 0. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the size of the output line buffer is is not positive, 
      the error SPICE(INVALIDARGUMENT) will be signaled. 
 
   2) If a comment line in a DAS file is longer than the length 
      of a character string array element of BUFFER, the error 
      SPICE(COMMENTTOOLONG) will be signaled. 
 
   3) If there is a mismatch between the number of comment 
      characters found and the number of comment characters 
      expected, the error SPICE(BADDASCOMMENTAREA) will be 
      signaled. 
 
   4) If the binary DAS file attached to HANDLE is not open for 
      reading, an error will be signaled by a routine called by 
      this routine. 
 
   5) If the input buffer pointer is null, the error SPICE(NULLPOINTER) 
      will be signaled.

   6) If the input buffer string length buflen is not at least 2, 
      the error SPICE(STRINGTOOSHORT) will be signaled.

-Files
 
   See argument handle in $ Detailed_Input. 
 
-Particulars
 
   Binary DAS files contain an area which is reserved for storing 
   annotations or descriptive textual information describing the data 
   contained in a file. This area is referred to as the "comment 
   area" of the file. The comment area of a DAS file is a line 
   oriented medium for storing textual information. The comment 
   area preserves any leading or embedded white space in the line(s) 
   of text which are stored, so that the appearance of the of 
   information will be unchanged when it is retrieved (extracted) at 
   some other time. Trailing blanks, however, are NOT preserved, 
   due to the way that character strings are represented in 
   standard Fortran 77. 
 
   This routine will read the comments from the comment area of 
   a binary DAS file, placing them into a line buffer. If the line 
   buffer is not large enough to hold the entire comment area, 
   the portion read will be returned to the caller, and the done 
   flag will be set to SPICEFALSE. This allows the comment area to be 
   read in "chunks," a buffer at a time. After all of the comment 
   lines have been read, the done flag will be set to SPICETRUE. 

   After all of the comments in DAS file have been read, the next
   call to this routine will start reading comments at the start
   of the comment area.
 
   This routine can be used to "simultaneously" extract comments 
   from the comment areas of multiple binary DAS files. 
 
-Examples
 
   1) The following example will extract the entire comment area of a 
      binary DAS file attached to HANDLE, displaying the comments on 
      the terminal screen. 
 
         #include <stdio.h>
         #include "SpiceUsr.h"

         int main( int argc, char ** argv )
         {
  
            #define LNSIZE          81
            #define MAXBUF          25

            SpiceBoolean            done;

            SpiceChar               buffer [MAXBUF][LNSIZE];
            SpiceChar             * filename;

            SpiceInt                handle;
            SpiceInt                i;
            SpiceInt                n;


            filename = argv[1];     

            dasopr_ ( filename, &handle, (ftnlen)strlen(filename) );

            done = SPICEFALSE;

            while ( !done )
            {
               dasec_c( handle, MAXBUF, LNSIZE, &n, buffer, &done );

               for ( i = 0;  i < n;  i++ )
               {
                  printf ( "%s\n", buffer[i] );
               }
            } 

            return ( 0 );
         }


-Restrictions
 
   1) The comment area may consist only of printing ASCII characters, 
      decimal values 32 - 126. 
 
   2) There is NO maximum length imposed on the significant portion 
      of a text line that may be placed into the comment area of a 
      DAS file. The maximum length of a line stored in the comment 
      area should be kept reasonable, so that they may be easily 
      extracted. A good value for this would be 255 characters, as 
      this can easily accommodate "screen width" lines as well as 
      long lines which may contain some other form of information. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL)
   K.R. Gehringer (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 24-FEB-2003 (NJB) (KRG)

-Index_Entries
 
    extract comments from a das file 
 
-&
*/

{ /* Begin dasec_c */


   /*
   Local variables
   */
   logical                 locDone;


   /*
   Participate in error tracing.
   */
   if ( return_c() ) 
   {
      return;
   }
   chkin_c ( "dasec_c" );


   /*
   Make sure the output string has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "dasec_c", buffer, buflen );
 

   /*
   Call the f2c'd routine.
   */
   dasec_  ( (integer *) &handle,
             (integer *) &bufsiz,
             (integer *) n,
             (char    *) buffer,
             (logical *) &locDone,
             (ftnlen   ) buflen-1  );
 
   /*
   Convert the output array from Fortran to C style. 
   */
   if ( *n > 0 );
   {
      F2C_ConvertTrStrArr ( *n,  buflen,  (SpiceChar *)buffer );
   }


   /*
   Set the "done" flag. 
   */
   
   *done = (SpiceBoolean) locDone;


   chkout_c ( "dasec_c" );

} /* End dasec_c */
Exemple #18
0
   void ucase_c ( SpiceChar   * in,
                  SpiceInt      lenout, 
                  SpiceChar   * out    ) 

/*

-Brief_I/O
 
    VARIABLE  I/O  DESCRIPTION 
    --------  ---  -------------------------------------------------- 
    in         I   Input string. 
    lenout     I   Maximum length of output string.
    out        O   Output string, all uppercase. 
 
-Detailed_Input
 
    in          is the input string. 
    
    lenout      is the maximum allowed length of the output string, 
                including the terminating null.
 
-Detailed_Output
 
    out         is the output string. This is the input string 
                with all lowercase letters converted to uppercase. 
                Non-letters are not affected. 
                
                If 
                  
                   lenout < strlen(in)+1
                   
                the output string will be truncated on the right.

                A terminating null will be placed in out at position
                
                   min ( strlen(in),  lenout-1 )
                   
                unless lenout is less than or equal to zero.
                
 
                out may overwrite in. 
 
-Parameters
 
   None. 
 
-Particulars
 
    Convert each lowercase character in IN to uppercase. 
 
-Examples
 
    "This is an example"   becomes   "THIS IS AN EXAMPLE" 
    "12345 +-=? > * $ &"             "12345 +-=? > * $ &" 
 
-Restrictions
 
    None. 
 
-Exceptions
 
 
    1) If the input string pointer is null, the error 
       SPICE(NULLPOINTER) will be signaled.
       
    2) If the output string pointer is null, the error 
       SPICE(NULLPOINTER) will be signaled.
       
    3) If lenout is less than or equal to zero, the error 
       SPICE(STRINGTOOSHORT) will be signaled.      
 
    4) If the output string is shorter than the input string, the
       result will be truncated on the right.
       
-Files
 
    None. 
 
-Author_and_Institution
 
    N.J. Bachman    (JPL)
    K.R. Gehringer  (JPL) 
    I.M. Underwood  (JPL) 
 
-Literature_References
 
    None. 
 
-Version
 
   -CSPICE Version 1.1.0, 26-JAN-2005 (NJB)

       Cast to SpiceInt was applied to strlen output to suppress
       compiler warnings about comparison of signed and unsigned types.

   -CSPICE Version 2.0.0, 26-AUG-1999 (NJB)
   
      Added string error checks.

   -CSPICE Version 1.0.0, 08-FEB-1998 (NJB)

      Based on SPICELIB Version 1.1.0, 13-MAR-1996 (KRG)
      
      
-Index_Entries
 
   convert to uppercase 
 
-&
*/

{ /* Begin ucase_c */


   /*
   Local macros
   */
   #define  LOWA     (  (SpiceInt) ('a')          )
   #define  LOWZ     (  (SpiceInt) ('z')          )
   #define  SHIFT    (  (SpiceInt) ('A')  - LOWA  )


   /*
   Local variables
   */
   SpiceInt                i;
   SpiceInt                ich;
   SpiceInt                nmove;



   
   /*
   Check the input string pointer to make sure it's non-null.
   */
   CHKPTR( CHK_DISCOVER, "ucase_c", in );
   

   /*
   Make sure the output string has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_DISCOVER, "ucase_c", out, lenout );
   
   
   /*
   Move the string from in to out. Step through in one character
   at a time, translating letters between 'a' and 'z' to uppercase.
   
   First, determine how many characters to move.
   */
   
   nmove = MinVal ( (SpiceInt)strlen(in), lenout-1 );
   
   
   for ( i = 0;  i < nmove;  i++ )
   {
      ich = (SpiceInt) in[i];

      if ( ( ich >= LOWA ) && ( ich <= LOWZ ) ) 
      {
         out[i] = (char) ( ich + SHIFT );
      }
      else
      {
         out[i] = in[i];
      }
   }
 
 
   /*
   Terminate the output string with a null. We know it has room for at 
   least one character.
   */
   out[nmove] = NULLCHAR;


} /* End ucase_c */
Exemple #19
0
   void scfmt_c ( SpiceInt      sc, 
                  SpiceDouble   ticks, 
                  SpiceInt      lenout,
                  SpiceChar   * clkstr  )
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   sc         I   NAIF spacecraft identification code. 
   ticks      I   Encoded representation of a spacecraft clock count. 
   lenout     I   Maximum allowed length of output string. 
   clkstr     O   Character representation of a clock count. 
 
-Detailed_Input
 
   sc         is the NAIF ID number for the spacecraft whose clock's 
              time is being decoded. 
 
   ticks      is the double precision encoding of a clock time in 
              units of ticks.  Partition information is not reflected 
              in this value. 
 
              An analogy may be drawn between a spacecraft clock and 
              a standard wall clock.  The number of ticks 
              corresponding to the wall clock string 
 
                 hh:mm:ss 
 
              would be the number of seconds represented by that 
              time. 
 
              For example, 
 
                 Clock string    Number of ticks 
                 ------------    --------------- 
                   00:00:10             10 
                   00:01:00             60 
                   00:10:00            600 
                   01:00:00           3600 
                   01:01:00           3660 
 
              If ticks contains a fractional part the result is the 
              same as if ticks had been rounded to the nearest whole 
              number. 
 
              See the Examples section below for examples of 
              actual spacecraft clock conversions. 
 
   lenout     The allowed length of the output string.  This length
              must large enough to hold the 'clkstr' string plus the
              null terminator.  If the output string is expected to
              have x characters, 'lenout' must be x + 1.

-Detailed_Output
 
   clkstr     is the spacecraft clock character string 
              corresponding to ticks.  Partition information is 
              not included in clkstr. 
 
              Using Galileo as an example, the full format clock 
              string is 
 
                 wwwwwwww:xx:y:z 
 
              where z is a mod-8 counter (values 0-7) which 
              increments approximately once every 8 1/3 ms., y is a 
              mod-10 counter (values 0-9) which increments once 
              every time z turns over, i.e., approximately once every 
              66 2/3 ms., xx is a mod-91 (values 0-90) counter 
              which increments once every time y turns over, i.e., 
              once every 2/3 seconds. wwwwwwww is the Real-Time Image 
              Count (RIM), which increments once every time xx turns 
              over, i.e., once every 60 2/3 seconds. The roll-over 
              expression for the RIM is 16777215, which corresponds 
              to approximately 32 years. 
 
              wwwwwwww, xx, y, and z are referred to interchangeably 
              as the fields or components of the spacecraft clock. 
              SCLK components may be separated by any of these five 
              characters: " "  ":"  ","  "-"  "." 
              The delimiter used is determined by a kernel pool 
              variable and can be adjusted by the user. 
 
              Some spacecraft clock components have offset, or 
              starting, values different from zero.  For example, 
              with an offset value of 1, a mod 20 counter would 
              cycle from 1 to 20 instead of from 0 to 19. 
 
              See the SCLK required reading for a detailed 
              description of the Voyager and Mars Observer clock 
              formats. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the data type for the spacecraft is not supported 
      then the error SPICE(NOTSUPPORTED) is signaled. 
 
   2) If the value for ticks is negative, the error is diagnosed 
      by routines called by this routine. 
 
   3) If the SCLK kernel file does not contain data for the 
      spacecraft specified by sc, then the error is diagnosed 
      by routines called by this routine. 
 
   4) If the output string pointer is null, the error SPICE(NULLPOINTER)
      is signaled.
      
   5) If the output string has length less than two characters, it 
      is too short to contain one character of output data plus a null  
      terminator, so it cannot be passed to the underlying Fortran 
      routine.  In this event, the error SPICE(STRINGTOOSHORT) is
      signaled.
      
   6) If the length of clkstr (indicated by lenout) is at least two
      characters but not large enough to contain the output clock 
      string, the error is diagnosed by a routine called by this 
      routine. 
 
-Files
 
   None. 
 
-Particulars
 
   The routine sctiks_c performs the inverse operation to scfmt_c, 
   converting from clock format to number of ticks. 
 
   Note the important difference between scfmt_c and scdecd_c. scdecd_c 
   converts some number of ticks since the spacecraft clock start 
   time to a character string which includes a partition number. 
   scfmt_c, which is called by scdecd_c, does not make use of partition 
   information. 
 
-Examples
 
 
   The following program fragment finds partition start and stop 
   times for the Galileo spacecraft from a spacecraft clock partition 
   kernel file, called sclk.ker. Since those times are always 
   returned in units of ticks, the program uses scfmt_c to print the 
   times in Galileo clock format. 
 
      #include <stdio.h>
      #include "SpiceUsr.h"
      
      #define                MXPART   9999
      #define                MAXLEN   30
      
      SpiceChar              start  [ 30 ];
      SpiceChar              stop   [ 30 ];
      
      SpiceDouble            pstart [ MXPART ];
      SpiceDouble            pstop  [ MXPART ];
      
      SpiceInt               sc  =  -77; 
      SpiceInt               i; 
      SpiceInt               nparts;
 
 
      furnsh_c ( "sclk.ker" ); 
 
      scpart_c ( sc, &nparts, pstart, pstop );
 
      for ( i = 0;  i < nparts;  i++ )
      {

         scfmt_c ( sc, pstart[ i ], MAXLEN, start ); 
         scfmt_c ( sc, pstop [ i ], MAXLEN, stop  ); 
 
         printf ( "\n"
                  "partition %d: \n" 
                  "start =  %s\n"
                  "stop  =  %s\n",
                   i,
                   start, 
                   stop                ); 
      }
 
 
 
   Below are some examples illustrating various input numbers of 
   ticks and the resulting clock string outputs for the Galileo 
   spacecraft. 
 
      TICKS                 CLKSTR 
      ----------------      -------------------- 
      -1                    Error: Ticks must be a positive number 
      0                     "0:00:0:0" 
      1                     "0:00:0:1" 
      1.3                   "0:00:0:1" 
      1.5                   "0:00:0:2" 
      2                     "0:00:0:2" 
      7                     "0:00:0:7" 
      8                     "0:00:1:0" 
      80                    "0:01:0:0" 
      88                    "0:01:1:0" 
      7279                  "0:90:9:7" 
      7280                  "1:00:0:0" 
      1234567890            "169583:45:6:2" 
 
   The following examples are for the Voyager 2 spacecraft. 
   Note that the third component of the Voyager clock has an 
   offset value of one. 
 
      TICKS                 CLKSTR 
      ----------------      -------------------- 
      -1                    Error: Ticks must be a positive number 
      0                     "00000 00 001" 
      1                     "00000 00 002" 
      1.3                   "00000:00:002" 
      1.5                   "00000.00.003" 
      2                     "00000-00-003" 
      799                   "00000,00,800" 
      800                   "00000 01 001" 
      47999                 "00000 59 800" 
      48000                 "00001 00 001" 
      3145727999            "65535 59 800" 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL)
   J.M. Lynch     (JPL) 
   R.E. Thurman   (JPL) 
 
-Version

   -CSPICE Version 1.1.4, 11-FEB-2008   (NJB)

      Header example was updated to reflect current
      MXPART value of 9999.

   -CSPICE Version 1.1.3, 14-AUG-2006   (EDW)

      Replace mention of ldpool_c with furnsh_c.
 
   -CSPICE Version 1.1.2, 01-OCT-2003 (EDW)

       Added description of the 'lenout' input in the 
       Detailed_Input section.

   -CSPICE Version 1.1.1, 26-MAR-2003 (NJB) 

       Fixed description of exception (6):  replaced "lenout-1"
       with "lenout."

   -CSPICE Version 1.1.0, 09-FEB-1998 (NJB)

      Re-implemented routine without dynamically allocated, temporary 
      strings.  Updated the Exceptions header section.
 
   -CSPICE Version 1.0.0, 25-OCT-1997 (NJB)

      Based on SPICELIB Version 1.0.1, 17-APR-1992 (JML) (WLT)
      
-Index_Entries
 
   convert spacecraft_clock ticks to character clock format 
 
-&
*/

{ /* Begin scfmt_c */
   
   /*
   Participate in error tracing.
   */
   chkin_c ( "scfmt_c");
   
   
   /*
   Make sure the output clkstr has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "scfmt_c", clkstr, lenout );


   /*
   Do the conversion.
   */
   scfmt_ ( ( integer    * ) &sc, 
            ( doublereal * ) &ticks, 
            ( char       * ) clkstr, 
            ( ftnlen       ) lenout-1 );
      
   /*
   Convert the Fortran string to a C string by placing a null
   after the last non-blank character.  This operation is valid
   whether or not the CSPICE routine signaled an error.
   */
   F2C_ConvertStr ( lenout, clkstr );
   

   chkout_c ( "scfmt_c");


} /* End scfmt_c */
Exemple #20
0
   void frmnam_c ( SpiceInt      frcode,
                   SpiceInt      lenout,
                   SpiceChar *   frname  )
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   frcode     I   an integer code for a reference frame 
   lenout     I   Maximum length of output string.
   frname     O   the name associated with the reference frame. 
 
-Detailed_Input
 
   frcode         is an integer code for a reference frame. 
 
   lenout         is the maximum number of characters that can be 
                  accommodated in the output string.  This count 
                  includes room for the terminating null character.
                  For example, if the maximum allowed length of the 
                  output string, including the terminating null, is 33
                  characters, then lenout should be set to 33.
 
-Detailed_Output
 
   frname      is the name associated with the reference frame. 
               It will be returned left-justified. 
 
               If frcode is not recognized as the name of a 
               known reference frame, frname will be returned 
               as an empty string. 
 
               If frname is not sufficiently long to hold the 
               name, it will be truncated on the right. 
 
               All reference frame names are 32 or fewer characters 
               in length.  Thus declaring frname to be SpiceChar[33] 
               will ensure that the returned name will not be 
               truncated. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If frcode is not recognized as the name of a known reference
      frame, frname will be returned as a blank. 
 
   2) If the output string pointer is null, the error SPICE(NULLPOINTER)
      is signaled.
      
   3) If the output string has length less than two characters, it 
      is too short to contain one character of output data plus a null  
      terminator, so it cannot be passed to the underlying Fortran 
      routine.  In this event, the error SPICE(STRINGTOOSHORT) is
      signaled.
      
   4) If the length of frname (indicated by lenout) is at least two
      characters but not large enough to contain the output string, 
      the output string will be truncated on the right. 
 
-Files
 
   None. 
 
-Particulars
 
   This routine retrieves the name of a reference frame associated 
   with a SPICE frame ID code. 
 
   The ID codes stored locally are scanned for a match with frcode. 
   If a match is found, the name stored locally will be returned 
   as the name for the frame. 
 
   If frcode is not a member of the list of internally stored 
   ID codes, the kernel pool will be examined to see if the 
   variable 
 
      FRAME_idcode_NAME 
 
   is present (where idcode is the decimal character equivalent 
   of frcode).  If the variable is located and it has both 
   character type and dimension 1, the string value of the 
   kernel pool variable is returned as the name of the reference 
   frame. 
 
   Note that because the local information is always examined 
   first and searches of the kernel pool are performed only 
   after exhausting local information, it is not possible to 
   override the local name for any reference frame that is 
   known by this routine. 
 
-Examples
 
   Suppose you needed to create a message concerning a reference 
   frame and wish to use the name of the frame in the message. 
   Suppose further that you have only the frame ID code at your 
   disposal.  You can capture the frame name using this routine 
   as shown here. 
 
      #include "SpiceUsr.h"   
           .
           .
           .
      #define NAMELEN         33
      
      SpiceChar               frname [NAMELEN];
      SpiceInt                frcode;

 
      frmnam_c ( frcode, NAMELEN, frname );
 
      if ( iswhsp_c(frname) )  
      { 
         sprintf ( frname, "%ld", frcode );
      }

      printf ( "Concerning reference frame: %s\n", frname );
 
        [Print the rest of your message.]
        
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   W.L. Taber      (JPL) 
   B.V. Semenov    (JPL) 
   N.J. Bachman    (JPL)
   
-Version
 
   -CSPICE Version 1.0.2, 08-JAN-2014 (BVS) 

       Fixed typo in Examples (frname_c -> frmnam_c). Reordered
       header sections.

   -CSPICE Version 1.0.1, 26-MAR-2003 (NJB) 

       Fixed description of exception (4):  replaced "lenout-1"
       with "lenout."  Removed spurious word "clock" from string
       description.

   -CSPICE Version 1.0.0, 13-AUG-2001 (NJB) (WLT)

-Index_Entries
 
   Frame idcode to frame name translation   

-&
*/

{ /* Begin frmnam_c */


   /*
   Participate in error tracing.
   */
   chkin_c ( "frmnam_c" );

   /*
   Make sure the output frmnam has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "frmnam_c", frname, lenout );


   /*
   Do the conversion.
   */
   frmnam_ ( ( integer * ) &frcode, 
             ( char    * ) frname, 
             ( ftnlen    ) lenout-1 );
      
   /*
   Convert the Fortran string to a C string by placing a null
   after the last non-blank character.  This operation is valid
   whether or not the CSPICE routine signaled an error.
   */
   F2C_ConvertStr ( lenout, frname );


   chkout_c ( "frmnam_c" );

} /* End frmnam_c */
Exemple #21
0
   void ekaclc_c ( SpiceInt                handle,
                   SpiceInt                segno,
                   ConstSpiceChar        * column,
                   SpiceInt                vallen,
                   const void            * cvals,
                   ConstSpiceInt         * entszs,
                   ConstSpiceBoolean     * nlflgs,
                   ConstSpiceInt         * rcptrs,
                   SpiceInt              * wkindx  )
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   EK file handle. 
   segno      I   Number of segment to add column to. 
   column     I   Column name. 
   vallen     I   Length of character values.
   cvals      I   Character values to add to column. 
   entszs     I   Array of sizes of column entries. 
   nlflgs     I   Array of null flags for column entries. 
   rcptrs     I   Record pointers for segment. 
   wkindx    I-O  Work space for column index. 
 
-Detailed_Input
 
   handle         the handle of an EK file that is open for writing. 
                  A "begin segment for fast write" operation must 
                  have already been performed for the designated 
                  segment. 
 
   segno          is the number of the segment to which data is to be
                  added. Segments are numbered from 0 to nseg-1, where
                  nseg is the count of segments in the file.

   column         is the name of the column to be added.  All of 
                  the data for the named column will be added in 
                  one shot. 
 
   vallen         is the length of the strings in the cvals array.
                  The array should be declared with dimensions
                  
                     [nrows][vallen]
                     
                  where nrows is the number of rows in the column.
   
   cvals          is an array containing the entire set of column 
                  entries for the specified column.  The entries 
                  are listed in row-order:  the column entry for the 
                  first row of the segment is first, followed by the 
                  column entry for the second row, and so on.  The 
                  number of column entries must match the declared 
                  number of rows in the segment.  For columns having 
                  fixed-size entries, a null entry must be allocated 
                  the same amount of space occupied by a non-null 
                  entry in the array cvals.  For columns having 
                  variable-size entries, null entries do not require 
                  any space in the cvals* array, but in any case must 
                  have their allocated space described correctly by 
                  the corresponding element of the entszs array 
                  (described below). 
 
   entszs         is an array containing sizes of column entries. 
                  The Ith element of entszs gives the size of the 
                  Ith column entry.  entszs is used only for columns 
                  having variable-size entries.  For such columns, 
                  the dimension of entszs must be at least nrows. 
                  The size of null entries should be set to zero. 
 
                  For columns having fixed-size entries, the 
                  dimension of this array may be any positive value. 
 
   nlflgs         is an array of logical flags indicating whether 
                  the corresponding entries are null.  If the Ith 
                  element of nlflgs is SPICEFALSE, the Ith column entry 
                  defined by cvals and entszs is added to the 
                  current segment in the specified kernel file. 
 
                  If the Ith element of nlfgls is SPICETRUE, the 
                  contents of the Ith column entry are undefined. 
 
                  nlflgs is used only for columns that allow null 
                  values; it's ignored for other columns. 
 
   rcptrs         is an array of record pointers for the input 
                  segment.  This array is obtained as an output 
                  from ekifld_c, the routine called to initiate a 
                  fast write. 
 
   wkindx         is a work space array used for building a column 
                  index.  If the column is indexed, the dimension of 
                  wkindx_c must be at nrows, where nrows is the number 
                  of rows in the column.  If the column is not 
                  indexed, this work space is not used, so the 
                  dimension may be any positive value. 
 
-Detailed_Output
 
   None.  See $Particulars for a description of the effect of this 
   routine. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If handle is invalid, the error will be diagnosed by routines 
       called by this routine. 
 
   2)  If column is not the name of a declared column, the error
       SPICE(NOCOLUMN) will be signaled.
        
   3)  If column specifies a column of whose data type is not 
       character, the error SPICE(WRONGDATATYPE) will be 
       signalled. 
 
   4)  If the specified column already contains ANY entries, the 
       error will be diagnosed by routines called by this routine. 
 
   5)  If an I/O error occurs while reading or writing the indicated 
       file, the error will be diagnosed by routines called by this 
       routine. 
 
   6) If the string pointer for column is null, the error 
      SPICE(NULLPOINTER) will be signaled.
      
   7) If the input string column has length zero, the error 
      SPICE(EMPTYSTRING) will be signaled.
 
   8) If the string pointer for cvals is null, the error
      SPICE(NULLPOINTER) will be signaled.
     
   9) If the string length vallen is less than 2, the error 
      SPICE(STRINGTOOSHORT) will be signaled.
    
-Files
 
   See the EK Required Reading for a discussion of the EK file 
   format. 
 
-Particulars
 
   This routine operates by side effects:  it modifies the named 
   EK file by adding data to the specified column.  This routine 
   writes the entire contents of the specified column in one shot. 
   This routine creates columns much more efficiently than can be 
   done by sequential calls to ekacec_c, but has the drawback that 
   the caller must use more memory for the routine's inputs.  This 
   routine cannot be used to add data to a partially completed 
   column. 
 
-Examples
 
   1)  Suppose we have an E-kernel named order_db.ek 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 file ORDER_DB.EK contains two segments, 
       the first containing the DATAORDERS table and the second 
       containing the DATAITEMS table. 
 
       Below, we show how we'd open a new EK file and create the 
       first of the segments described above. 
 
       #include "SpiceUsr.h"
       #include <stdio.h>
       
       
       void main()
       {
          /.
          Constants
          ./
          #define  CNMLEN      ( CSPICE_EK_COL_NAM_LEN + 1 )
          #define  DECLEN        201
          #define  EKNAME        "order_db.ek"
          #define  FNMLEN        50
          #define  IFNAME        "Test EK/Created 20-SEP-1995"
          #define  LNMLEN        50
          #define  LSK           "leapseconds.ker"
          #define  NCOLS         6
          #define  NRESVC        0
          #define  NROWS         9
          #define  TABLE         "DATAORDERS"
          #define  TNMLEN        CSPICE_EK_TAB_NAM_LEN
          #define  UTCLEN        30
          
          
          /.
          Local variables
          ./
          SpiceBoolean            nlflgs [ NROWS  ];
       
          SpiceChar               cdecls  [ NCOLS ] [ DECLEN ];
          SpiceChar               cnames  [ NCOLS ] [ CNMLEN ];
          SpiceChar               fnames  [ NROWS ] [ FNMLEN ];
          SpiceChar               lnames  [ NROWS ] [ LNMLEN ];
          SpiceChar               dateStr [ UTCLEN ];
        
          SpiceDouble             costs  [ NROWS ];
          SpiceDouble             ets    [ NROWS ];
       
          SpiceInt                cstids [ NROWS ];
          SpiceInt                ordids [ NROWS ];
          SpiceInt                handle;
          SpiceInt                i;
          SpiceInt                rcptrs [ NROWS ];
          SpiceInt                segno;
          SpiceInt                sizes  [ NROWS ];
          SpiceInt                wkindx [ NROWS ];
          
          
          /.
          Load a leapseconds kernel for UTC/ET conversion.
          ./
          furnsh_c ( LSK );
          
          /.
          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 constant IFNAME is the internal file name. 
          ./
          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 segment.  We presume the number of  rows 
          of data is known in advance. 
          ./
          ekifld_c ( handle,  TABLE,   NCOLS,  NROWS,   CNMLEN,  
                     cnames,  DECLEN,  cdecls, &segno,  rcptrs );
       
          /.
          At this point, arrays containing data for the 
          segment's columns may be filled in.  The names 
          of the data arrays are shown below. 
       
             Column           Data array 
       
             "ORDER_ID"       ordids 
             "CUSTOMER_ID"    cstids 
             "LAST_NAME"      lnames 
             "FIRST_NAME"     fnames 
             "ORDER_DATE"     odates 
             "COST"           costs 
       
       
          The null flags array indicates which entries are null. 
          It is ignored for columns that don't allow null 
          values.  In this case, only the COST column allows 
          nulls. 
          
          Fill in data arrays and null flag arrays here.  This code
          section would normally be replaced by calls to user functions
          returning column values.
          ./
          
          for ( i = 0;  i < NROWS;  i++ )
          {
             ordids[i]  =  i;
             cstids[i]  =  i*100;
             costs [i]  =  (SpiceDouble) 100*i;
       
             sprintf  ( fnames[i], "Order %d Customer first name", i );
             sprintf  ( lnames[i], "Order %d Customer last name",  i );
             sprintf  ( dateStr,   "1998 Mar %d",                  i );
             
             utc2et_c ( dateStr, ets+i );
       
             nlflgs[i]  =  SPICEFALSE;
          }
       
          nlflgs[1] = SPICETRUE;
          
          
          /.
          The sizes array shown below is ignored for scalar 
          and fixed-size array columns, so we need not 
          initialize it.  For variable-size arrays, the 
          Ith element of the sizes array must contain the size 
          of the Ith column entry in the column being written. 
          Normally, the sizes array would be reset for each 
          variable-size column. 
       
          Add the columns of data to the segment.  All of the 
          data for each column is written in one shot. 
          ./
          ekacli_c ( handle,  segno,   "order_id",    ordids, 
                     sizes,   nlflgs,  rcptrs,        wkindx ); 
       
          ekacli_c ( handle,  segno,   "customer_id", cstids,  
                     sizes,   nlflgs,  rcptrs,        wkindx ); 
       
          ekaclc_c ( handle,  segno,   "last_name",   LNMLEN,
                     lnames,  sizes,   nlflgs,        rcptrs,  wkindx ); 
       
          ekaclc_c ( handle,  segno,   "first_name",  FNMLEN,
                     fnames,  sizes,   nlflgs,        rcptrs,  wkindx ); 
       
          ekacld_c ( handle,  segno,   "order_date",  ets,  
                     sizes,   nlflgs,  rcptrs,        wkindx );
          
          ekacld_c ( handle,  segno,   "cost",        costs,  
                     sizes,   nlflgs,  rcptrs,        wkindx ); 
       
          /.
          Complete the segment.  The rcptrs array is that 
          returned by ekifld_c. 
          ./
          ekffld_c ( handle, segno, rcptrs ); 
       
          /.
          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. 
       
          The file must be closed by a call to ekcls_c. 
          ./
          ekcls_c ( handle ); 
       }

 
-Restrictions
 
   1)  Only one segment can be created at a time using the fast 
       write routines. 
 
   2)  No other EK operation may interrupt a fast write.  For 
       example, it is not valid to issue a query while a fast write 
       is in progress. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version

   -CSPICE Version 1.2.2, 14-AUG-2006   (EDW)

      Replace mention of ldpool_c with furnsh_c.

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

      Documentation change:  instances of the phrase "fast load"
      were replaced with "fast write."

      Const-qualified input array cvals.

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

       Bug fix:  now counts elements rather than rows for vector-valued
       columns.
       
       Bug fix:  now uses dynamically allocated array of type logical
       to interface with underlying f2c'd function ekaclc_.
       
       Now maps segno from C to Fortran range.
       
       Added "undef" of masking macro.  Changed input pointer types
       to pointers to const objects.
       
       Replaced eksdsc_ call with ekssum_c call.  This removes unsightly
       references to segment descriptor alignments.
       
       Fixed some chkout_c calls which referenced ekifld_c.
       
   -CSPICE Version 1.0.0, 25-FEB-1999 (NJB)
   
      Based on SPICELIB Version 1.0.0, 08-NOV-1995 (NJB)

-Index_Entries
 
   write entire character column to EK segment 
 
-&
*/

{ /* Begin ekaclc_c */


   /*
   Local variables
   */
   SpiceBoolean            fnd;

   logical               * logicalFlags;
   
   SpiceEKSegSum           summary;
   
   SpiceChar            ** cvalsPtr;
   SpiceChar             * fCvalsArr;

   SpiceInt                i;
   SpiceInt                fCvalsLen;
   SpiceInt                fSegno;
   SpiceInt                ncols;
   SpiceInt                nelts;
   SpiceInt                nrows;
   SpiceInt                size;



   /*
   Participate in error tracing.
   */
   chkin_c ( "ekaclc_c" );


   /*
   Check the column name to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ekaclc_c", column );


   /*
   Check the value array to make sure the pointer is non-null 
   and the string length is non-zero.  Note:  this check is normally
   done for output strings:  CHKOSTR is the macro that does the job.
   */
   CHKOSTR ( CHK_STANDARD, "ekaclc_c", cvals, vallen );


   /*
   Get the row count for this segment.
   */ 
   ekssum_c ( handle, segno, &summary );
   
   nrows = summary.nrows;
   

   /*
   Locate the index of this column in the segment descriptor.
   */
   ncols = summary.ncols;
   i     = 0;
   fnd   = SPICEFALSE;
   
   while (  ( i < ncols ) && ( !fnd ) )
   {
      if (  eqstr_c( column, summary.cnames[i] )  )
      {
         fnd = SPICETRUE;
      }
      else
      {
         i++;
      }
   }
   
   
   if ( !fnd )
   {
      setmsg_c ( "Column <#> does not belong to segment #. "  );
      errch_c  ( "#",  column                                 );
      errint_c ( "#",  segno                                  );
      sigerr_c ( "SPICE(NOCOLUMN)"                            );
      chkout_c ( "ekaclc_c"                                   );
      return;
   }
   
   
   /*
   Now i is the index within the segment descriptor of the column
   descriptor for the column of interest.  Get the dimension information
   for this column.
   */
   size = summary.cdescrs[i].size;
   
   
   /*
   Compute the total string count of the input array.  If the column
   has fixed-size entries, we ignore the entszs array.  Otherwise, the
   entszs array tells us how many strings we're getting.
   */
   
   if ( size == SPICE_EK_VARSIZ )
   {
      nelts = sumai_c ( entszs, nrows );
   }
   else
   {
      nelts = nrows * size;
   }
   
   
   /*
   Allocate an array of logicals and assign values from the input
   array of SpiceBooleans.
   */
   logicalFlags = ( logical * ) malloc ( nelts * sizeof(logical) );

   if ( !logicalFlags )
   {
      setmsg_c ( "Failure on malloc call to create null flag array "
                 "for column values."                              );
      sigerr_c ( "SPICE(MALLOCFAILED)"                             );
      chkout_c ( "ekaclc_c"                                        );
      return;
   }
      
      
   /*
   Copy the input null flags to our array of type logical.
   */
   for ( i = 0;  i < nrows;  i++ )
   {
      logicalFlags[i] = nlflgs[i];
   }


   /*
   We need to make a blank-padded version of the cvals array.
   We'll first allocate an array of character pointers to index
   the values, initialize this array, and use it to produce
   a dynamically allocated array of Fortran-style strings.
   */
   
   cvalsPtr = ( SpiceChar ** ) malloc ( nelts * sizeof(SpiceChar *) );

   if ( cvalsPtr == 0 )
   {
      free ( logicalFlags );
      
      
      setmsg_c ( "Failure on malloc call to create pointer array "
                 "for column values."                              );
      sigerr_c ( "SPICE(MALLOCFAILED)"                             );
      chkout_c ( "ekaclc_c"                                        );
      return;
   }
   
   for ( i = 0;  i < nelts;  i++  )
   {
      cvalsPtr[i] =  (SpiceChar *)cvals  +  ( i * vallen );
   }
   
   C2F_CreateFixStrArr (  nelts, 
                          vallen,
                          ( ConstSpiceChar ** ) cvalsPtr, 
                          &fCvalsLen, 
                          &fCvalsArr                      );
   
   if ( failed_c() )
   {
      free ( logicalFlags );
      free ( cvalsPtr     );
      
      chkout_c ( "ekaclc_c" );
      return;
   }

   /*
   Map the segment number to the Fortran range.
   */
   fSegno = segno + 1;
   
   
   ekaclc_ ( ( integer    * ) &handle,
             ( integer    * ) &fSegno,
             ( char       * ) column,
             ( char       * ) fCvalsArr,
             ( integer    * ) entszs,
             ( logical    * ) logicalFlags,
             ( integer    * ) rcptrs,
             ( integer    * ) wkindx,
             ( ftnlen       ) strlen(column),
             ( ftnlen       ) fCvalsLen        );


   /*
   Clean up all of our dynamically allocated arrays.
   */
   free ( cvalsPtr     );
   free ( fCvalsArr    );
   free ( logicalFlags );
   

   chkout_c ( "ekaclc_c" );

} /* End ekaclc_c */