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

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

    Wed Apr  5 17:54:41 2017