Index Page trcnam_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 trcnam_c ( SpiceInt       index,
                       SpiceInt       namelen,
                       SpiceChar    * name     )
#### Abstract
       Return the name of the module having the specified position in
       the trace representation. The first module to check in is at
       index 0.
#### Required_Reading
       ERROR
#### Keywords
       ERROR
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------

       index      I   The position of the requested module name.
       namelen    I   Available space in output name string.
       name       O   The name at position `index' in the traceback.
       SPICE_ERROR_MODLEN
                  P   Maximum length of stored module names.
#### Detailed_Input
       index          is the position in the traceback of the requested
                      module name. Indices are zero-based: the index
                      of the module at the start of the traceback is zero.
                      The last module to check in is located at index
                      depth - 1, where `depth' is the trace stack depth
                      returned by trcdep_c.

       namelen        is the available space in the output string `name,'
                      including room for the null terminator.
#### Detailed_Output
       name           is the name of the module at the position in
                      the traceback indicated by `index'. `name' should
                      be declared with length at least SPICE_ERROR_MODLEN.

                      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.
#### Parameters
        SPICE_ERROR_MODLEN   is the maximum length of any module name that
                             can be returned by this routine, including
                             room for the null terminator. SPICE_ERROR_MODLEN
                             is declared in SpiceErr.h.
#### Exceptions
       If a SPICE error occurs, in order to ensure that this error can be
       signaled, this routine resets the SPICE error status. Error messages
       from any pre-existing error will be lost.

       1)  This routine detects the condition of INDEX being out of
           range. The short error message set in that case is
           SPICE(INDEXOUTOFRANGE).

           Note that the underlying SPICELIB routine trcnam_ cannot
           signal an error if `index' is out of range.

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

       3)  If the output string has length less than 2 characters, the error
           SPICE(STRINGTOOSHORT) will be signaled.
#### Files
       None.
#### Particulars
       SPICE-based applications can use this routine, together with
       trcdep_c, to create a customized traceback report. This is normally
       done after an application detects a SPICE error condition using
       failed_c.

       The CSPICE routine qcktrc_c is an alternative to the combination of
       trcdep_c and trcnam_c; qcktrc_c can be used to fetch a complete,
       fixed-format traceback string in a single call.
#### Examples
       1) Deliberately generate a SPICE error to demonstrate use of
          this routine together with trcdep_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               longms  [ SPICE_ERROR_LMSGLN ];
                SpiceChar               modnam  [ SPICE_ERROR_MODLEN ];
                SpiceChar               shrtms  [ SPICE_ERROR_SMSGLN ];
                SpiceChar             * obsrvr;
                SpiceChar             * frame;
                SpiceChar             * target;

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

                SpiceInt                depth;
                SpiceInt                i;

                /.
                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. First fetch the long
                   and short error message. Next fetch the traceback depth,
                   then fetch and display the module names.
                   ./
                   getmsg_c ( "SHORT", SPICE_ERROR_SMSGLN, shrtms );
                   getmsg_c ( "LONG",  SPICE_ERROR_LMSGLN, longms );

                   printf ( "\n%s\n", shrtms );
                   printf ( "%s\n\n", longms );

                   trcdep_c ( &depth );

                   for ( i = 0;  i < depth;  i++ )
                   {
                      trcnam_c ( i, SPICE_ERROR_MODLEN, modnam );

                      printf ( "Trace level: %d. Module name = %s\n",
                               (int)i,
                               modnam                                 );
                   }

                   /.
                   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

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

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

             Trace level: 0. Module name = spkezr_c
             Trace level: 1. Module name = SPKEZR
             Trace level: 2. Module name = SPKEZ
             Trace level: 3. Module name = SPKGEO
             Trace level: 4. Module name = SPKSFS
#### Restrictions
       1)  If a SPICE error occurs during the execution of this routine,
           this routine resets the SPICE error handling status. See the
           Exceptions section above.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       K.R. Gehringer  (JPL)
#### Version
       -CSPICE Version 1.0.1, 12-JUL-2016 (EDW)

          Edit to example program to use "%d" with explicit casts
          to int for printing SpiceInts with printf.

       -CSPICE Version 1.0.0, 05-NOV-2013 (NJB) (KRG)
#### Index_Entries
       get module name from traceback
#### Link to routine trcnam_c source file trcnam_c.c

    Wed Apr  5 17:54:45 2017