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 trcnam_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

       trcnam_c ( Get module name from traceback )

       void trcnam_c ( SpiceInt       index,
                       SpiceInt       namlen,
                       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.
       namlen     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.

       namlen      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)  If `index' is out of range, the error SPICE(INDEXOUTOFRANGE) is
           signaled.

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

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

       3)  If the output string has length less than 2 characters, the error
           SPICE(STRINGTOOSHORT) is 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

       The numerical results shown for this example may differ across
       platforms. The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       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 Mac/Intel/cc/64-bit
          platform, the output was:

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

          Toolkit version: N0066

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

          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

          Warning: incomplete output. 1 line extended past the right
          margin of the header and has been truncated. This line is
          marked by "***" at the end of the line.

          Note that the error SPICE(NOLOADEDFILES) is signaled as expected,
          since no SPK files have been loaded before calling spkezr_c.

#### 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)
       J. Diaz del Rio     (ODC Space)
       K.R. Gehringer      (JPL)
       E.D. Wright         (JPL)

#### Version

       -CSPICE Version 1.1.0, 10-AUG-2021 (JDR)

           Changed the input argument name "namelen" to "namlen" for consistency
           with other routines.

           Edited the header to comply with NAIF standard.

       -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

    Fri Dec 31 18:41:14 2021