Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page qcktrc_c
Table of contents
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       qcktrc_c ( Get Quick Traceback )

       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 `trace' output string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       2)  If the `trace' output string has length less than two
           characters, the error SPICE(STRINGTOOSHORT) is signaled, since
           the output string is too short to contain one character of
           output data plus a null terminator.
#### 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 Mac/Intel/cc/64-bit 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)
       J. Diaz del Rio     (ODC Space)
       K.R. Gehringer      (JPL)
#### Version
       -CSPICE Version 1.0.1, 05-AUG-2021 (JDR)

           Edited the header to comply with NAIF standard.

       -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

    Fri Dec 31 18:41:11 2021