True if CSPICE routines should return immediately upon entry. 

    ERROR 

    VARIABLE  I/O  DESCRIPTION 
    --------  ---  -------------------------------------------------- 

    The function returns the value, SPICETRUE, if and only if CSPICE 
    routines should return immediately upon entry. 

    None. 

    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. 

   None. 

    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. 

    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 ] 

                         . 
                         . 
                         . 

    This routine has no effect unless the error action is "RETURN"! 

    This routine does not detect any errors. 

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

    None. 

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

    None. 

   -CSPICE Version 1.1.0, 23-JUL-2001 (NJB)

       Removed tab characters from source file.

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

   immediate return indicator