Procedure

   void reset_c ( void )

Abstract

   Reset the CSPICE error status to a value of "no error."
   As a result, the status routine, failed_c, will return a value
   of SPICEFALSE

Required_Reading

   ERROR

Keywords

   ERROR

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   None.

Detailed_Input

   None.

Detailed_Output

   None.

Parameters

   None.

Exceptions

   This routine does not detect any errors.

   However, this routine is part of the CSPICE error
   handling mechanism.

Files

   None.

Particulars

   Please read the "required reading" first!

   The effects of this routine are:

   1. The CSPICE status is set to a value of "no error."

   2. The long and short error messages are set to blank.

   3. Setting of the long error message is re-enabled.


   Subsequent to a call to reset_c, references to the status
   indicator function, failed_c, will return a value of SPICEFALSE,
   until an error is detected.

   This routine should be called in cases where one wishes
   to attempt to continue processing after detection of an
   error, and the "RETURN" error action is being used.  When
   the error response action is set to "RETURN", routines
   that have external references, or that can
   detect errors, return immediately upon entry when an
   error condition exists.  This prevents a program from
   crashing, but does not allow for a recovery attempt.

   If one does wish to attempt to recover,
   in general the procedure is to test for an error
   condition, and if one exists, respond to the error
   (by outputting diagnostic messages, for example).  Next,
   a call to reset_c can be made.  After resetting the
   error status, the normal execution thread can be resumed.

   It is also appropriate to call this routine when the error
   response action is "REPORT", if one wishes to recover
   from errors.

Examples

   1.  In this example, we try to read a line from the file,
       SPUD.DAT, using the toolkit routine, rdtext_c.
       When failed_c indicates an error, we grab the short
       error message and its explanation, using getmsg_c (see),
       log the messages using our user-defined routine,
       USER_LOG (NOT a CSPICE routine), reset the
       status, and keep going.

          /.
          We read a line from SPUD.DAT:
          ./

          rdtext_c ( "SPUD.DAT", line, LENOUT, &eof );

          if ( failed_c() )
             {

             /.
             Oops! an error occurred during the read.
             Recover the short error message and its
             explanation, reset the error status,
             log the messages, and continue...
             ./

             getmsg_c   ( "SHORT"  , LENOUT, short_mess );
             getmsg_c   ( "EXPLAIN", LENOUT, explain_mess );

             USER_LOG (  SMSG );
             USER_LOG (  EXPL );

             reset_c();
             }

Restrictions

   It can be dangerous to call this routine without
   RESPONDING to the error condition first; by calling
   reset_c, you are wiping out the CSPICE's knowledge of
   the error.

Literature_References

   None.

Author_and_Institution

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

Version

   -CSPICE Version 1.0.1, 25-MAR-1998 (EDW)

      Minor corrections to header.

   -CSPICE Version 1.0.0, 08-FEB-1998 (EDW)

Index_Entries

   reset error status

Link to routine reset_c source file reset_c.c