Index Page
qcktrc_c
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

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

Procedure

   void qcktrc_c ( SpiceInt     tracelen,
                   SpiceChar  * trace    )

Abstract

 
   Return a string containing a traceback. 
 

Required_Reading

 
   ERROR 
 

Keywords

 
   ERROR 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   tracelen   I   Maximum length of output traceback string.
   trace      O   A traceback string. 
   SPICE_ERROR_MAXMOD   
              P   Maximum traceback module count.
   SPICE_ERROR_MODLEN 
              P   Maximum module name length. 
   SPICE_ERROR_TRCLEN
              P   Maximum length of output traceback string.

Detailed_Input

 
   None. 
 

Detailed_Output

 
   trace          is a list of module names, delimited by the string, 
                  " --> ".  An example would be
 
                     "SPUD --> SPAM --> FOOBAR". 
 
                  The maximum length of the returned string is given
                  by the parameter SPICE_ERROR_TRCLEN. The value of this
                  parameter includes room for the terminating null.

                  In general, the meaning of the trace is as follows:
 
                  The first name in the list is the name of the first
                  module to check in (that hasn't yet checked out). The
                  last name is the name of the module at the end of the
                  call chain; this is the last module that checked in.
 
                  The meaning of the traceback depends on the state 
                  of the error handling mechanism.  There are two 
                  cases: 
 
                     1)  In RETURN mode, when an error is signaled, the
                         traceback at that point is saved. trcdep_c,
                         trcnam_c, and qcktrc_c return values
                         pertaining to the saved traceback.
 
                     2)  In all other modes, the traceback represents
                         the CURRENT call chain. trcdep_c, trcnam_c,
                         and qcktrc_c return values pertaining to the
                         current trace representation.
 
                  Any module names exceeding SPICE_ERROR_MODLEN
                  characters in length are truncated on the right.
 

Parameters

 
   The following parameters are declared in the header file SpiceErr.h:


   SPICE_ERROR_MAXMOD    is the maximum number of module names that can
                         be accommodated in the SPICE trace stack; this
                         is the maximum number of names that can appear
                         in the output traceback.

   SPICE_ERROR_MODLEN    is the maximum module name length that can be
                         accommodated by this routine. 

   SPICE_ERROR_TRCLEN    is the maximum length of the string returned
                         by this routine. The value of this parameter
                         includes room for the terminating null.
 

Exceptions

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


   2)  If the output string has length less than 2 characters, the error
       SPICE(STRINGTOOSHORT) will be signaled.
 

Files

 
   None. 
 

Particulars

 
   This routine is part of the CSPICE error handling mechanism. 
 

Examples

 
   1) Deliberately generate a SPICE error to demonstrate use of 
      this routine together with trcnam_c. We'll attempt to look up 
      a state vector via spkezr_c without first having loaded any
      SPK files.


      Example code begins here.
 

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

         int main()
         {
            /.
            Local constants 
            ./
            #define ACTION          "RETURN"

            /.
            Local variables 
            ./   
            SpiceChar             * abcorr;
            SpiceChar               trace  [ SPICE_ERROR_TRCLEN ];
            SpiceChar             * obsrvr;
            SpiceChar             * frame;
            SpiceChar             * target;

            SpiceDouble             et;
            SpiceDouble             lt;
            SpiceDouble             state [6];

            /.
            Set error handling action to RETURN so that this program
            won't terminate when a SPICE error is signaled. Note that
            the input string length argument is unused for a "SET"
            operation.
            ./
            erract_c ( "SET", 0, ACTION );

            /.
            Generate a SPICE error: call spkezr_c without first having
            loaded an SPK file. 
            ./ 
            et     = 0.0;
            target = "Moon";
            obsrvr = "Earth";
            frame  = "J2000";
            abcorr = "NONE";

            spkezr_c ( target, et, frame, abcorr, obsrvr, state, &lt );

            if ( failed_c() ) 
            {
               /.
               An error has been signaled. Fetch and display
               the traceback.
               ./
               qcktrc_c ( SPICE_ERROR_TRCLEN, trace );

               printf ( "Traceback: \n%s\n", trace );
               /.
               Reset the error status so that CSPICE can resume normal
               operation. 
               ./
               reset_c();
            }

            return ( 0 );
         }

      When this program was executed on a PC/Linux/gcc platform, the
      output (which has been reformatted to fit in the available 
      space in this header) was:


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

         Toolkit version: N0065

         SPICE(NOLOADEDFILES) --

         At least one SPK file needs to be loaded by SPKLEF before beginning 
         a search.

         A traceback follows.  The name of the highest level module is first.
         spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS

         ====================================================================
         ============
         Traceback:
         spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS

Restrictions

 
   1) It is assumed no module names exceed SPICE_ERROR_MODLEN
      characters in length. 
 

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL) 
   K.R. Gehringer  (JPL) 
 

Version

 
   -CSPICE Version 1.0.0, 05-NOV-2013 (NJB) (KRG)

Index_Entries

 
   get quick traceback 
 
Wed Apr  5 17:54:41 2017