reset_c

Index Page reset_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 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

    Thu Apr 16 08:59:00 2009