return_c

Index Page return_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
       SpiceBoolean return_c ( void )
#### Abstract
       True if CSPICE routines should return immediately upon entry.
#### Required_Reading
        ERROR
#### Keywords
        ERROR
#### Brief_I/O
        VARIABLE  I/O  DESCRIPTION
        --------  ---  --------------------------------------------------

        The function returns the value, SPICETRUE, if and only if CSPICE
        routines should return immediately upon entry.
#### Detailed_Input
        None.
#### Detailed_Output
        The function returns the value, SPICETRUE, if and only if CSPICE
        routines should return immediately upon entry.  The criterion
        for this is that the error response action is set to
        "RETURN", and an error condition exists.
#### 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!

        This routine can be referenced in non-toolkit code; in
        fact, its use is encouraged.  Its purpose is to signal
        to the routine calling it that the caller should
        return immediately.  The reference to return_c should
        be the first executable line of the calling program.

        In "RETURN" mode, CSPICE routines
        that have external references, or that can
        detect errors, return immediately upon entry when an
        error condition exists.  They use return_c to determine
        when these conditions are met.  Non--toolkit routines
        can do the same.

        Additionally, when an error is signalled in "RETURN" mode,
        no further errors can be signalled until the error condition
        is reset by a call to reset_c.  Calls to SIGERR simply have
        no effect.  Therefore, the error messages set in response
        to the FIRST error that was detected will be saved until
        reset_c is called.  These messages can be retrieved by
        calls to getmsg_c.

        There are a number of advantages to using this mechanism.
        First, the likelihood of an error resulting in crash
        in a different routine is greatly reduced.  Second,
        a program does not have to test the error status
        (using a reference to failed_c) after each call to a toolkit
        routine, but rather can make one test of status at the end
        of a series of calls.  See "Examples" below.

        See the subroutine erract_c for definitions of the error action
        codes.
#### Examples
        1.  In this example, we show how to place a reference
            to return_c in your code:

           /.
                  No executable lines precede this one.

                  Test whether to return before doing
                  anything else.
           ./

                  if ( return_c() )
                     {
                     return;
                     }

                  [ rest of code goes here]

                            .
                            .
                            .

        2.  Here's how one might code a sequence of calls
            to routines with code that follows the pattern
            given in example #1 above:

                           .
                           .
                           .

                  [ code may go here ]

           /.
                  We call routines A, B, and C;  then we
                  test for errors, using the CSPICE error
                  status indicator, failed_c:
           ./

                  A();
                  B();
                  C();

                  if ( failed_c() )
                     {

           /.
                     If we're here, an error occurred.  The
                     error might have been detected by A, B, C,
                     or by a routine called by one of them.
                     Get the explanation of the short error message
                     and output it using the routine, user_out_c
                     [user_out_c is a fictitious routine]:
           ./

                     getmsg_c ( "EXPLAIN", MSG );

                     user_out_c ( MSG );

                     }

                  [ rest of code goes here ]

                             .
                             .
                             .
#### Restrictions
        This routine has no effect unless the error action is "RETURN"!
#### Literature_References
        None.
#### Author_and_Institution
        N.J. Bachman    (JPL)
        K.R. Gehringer  (JPL)
#### Version
       -CSPICE Version 1.1.0, 23-JUL-2001 (NJB)

           Removed tab characters from source file.

       -CSPICE Version 1.0.0, 08-FEB-1998   (EDW)
#### Index_Entries
       immediate return indicator
#### Link to routine return_c source file return_c.c

    Thu Apr 16 08:59:01 2009