void chkin_c ( ConstSpiceChar * module )
Inform the CSPICE error handling mechanism of entry into a
VARIABLE I/O DESCRIPTION
-------- --- ---------------------------------------------------
module I The name of the calling routine.
module is the name of the routine calling chkin_c. The
named routine is supposed to be `checking in'
when it calls chkin_c; that is, the call should be
the first executable statement following the
reference to the function return_c() (which should be
the first executable statement).
1) The error SPICE(EMPTYSTRING) is signalled if the input
string does not contain at least one character, since the
input string cannot be converted to a Fortran-style string
in this case.
2) The error SPICE(NULLPOINTER) is signalled if the input string
pointer is null.
The underlying f2c'd CSPICE routine chkin_ does not signal errors;
rather it writes error messages, so as to avoid recursion. The
errors detected by chkin_ are:
3) If the traceback storage area overflows, the short error
message "SPICE(TRACEBACKOVERFLOW)" is written to the error
4) If the input argument module is blank, the short error message
SPICE(BLANKMODULENAME) is written to the error output device.
This routine is part of the CSPICE error handling mechanism.
Conceptually, the effect of this routine is to `push' the
supplied module name onto a stack. The routine chkout_c performs
the inverse, or `pop', operation.
Every routine that participates in the traceback scheme should
have a call to chkin_c as the second executable statement. The
first executable statements should be:
if ( return_c() )
chkin_c ( module );
Here module is the name of the routine in which this code appears.
The line of code preceding the exit or any return statement should
chkout_c ( module );
All CSPICE routines should call chkin_c and chkout_c, unless they
are classified as `error free'. Programs linked with CSPICE
may also use chkin_c and chkout_c.
Routines that don't call chkin_c and chkout_c won't appear in the
All routines that call chkin_c must also call chkout_c, or else the
trace mechanism will become very confused and require therapy.
It is possible to disable check-ins (and check-outs) by calling
the trcoff_c. chkin_c and chkout_c will return immediately
upon entry after trcoff_c has been called. It is not possible to
re-enable check-ins and check-outs after calling trcoff_c. Routines
that don't call chkin_c and chkout_c won't appear in the traceback.
See `Particulars' for an example of how to call this routine.
Routines that call this routine must call chkout_c immediately
prior to any return or exit statement.
module names are assumed to have no embedded blanks.
K.R. Gehringer (JPL)
N.J. Bachman (JPL)
-CSPICE Version 2.0.3, 23-JUL-2001 (NJB)
Tabs removed from source file.
-CSPICE Version 2.0.2, 25-MAR-1998 (EDW)
Minor corrections to header.
-CSPICE Version 2.0.1, 08-FEB-1998 (EDW)
Corrected and clarified header entries.
-CSPICE Version 2.0.0, 09-JAN-1998 (NJB)
Input argument filename was changed to type ConstSpiceChar *.
Re-implemented routine without dynamically allocated, temporary
-CSPICE Version 1.0.0, 25-OCT-1997 (EDW)
module check in