NAME

runerr - handle run-time error

SYNOPSIS

extern *Berror;

extern runerr(i)
short i;

stop()

doerr()

short err()

float erl()

int ehandl()

errdisable()

DESCRIPTION

Berror is a pointer to a collection of module dependent run-time error handling information.  Runerr is an assembly language routine called at any point when a run-time error with error number i is detected.  Runerr saves the error number, resets the program stack (which has grown due to calls to library routines) and finds and saves the program counter whence it left the user’s BASIC code and entered the library.  Runerr finally calls doerr and if and when it returns, jumps to the location of the BASIC error handling routine.  Runerr implements the ERROR statement. 

Stop effects an untrappable run-time error condition with the word “STOP” as the error message.  This function implements STOP statement. 

Doerr resets the current file (see initio(io)) and if a saved program counter is available it is used to search a list of machine code addresses for the corresponding BASIC code statement.  The value found is saved for subsequent use in the implementation of RESUME statements, the ERL variable and error reportage.  If error recover is enabled but not already being handled, this function returns after indicating that error recovery is now being handled and clearing the program counter.  This last instruction allows doerr to be called directly to implement the ON ERROR GOTO 0 statement in the context of error handling, i.e. to report the previously trapped error. 

The various error reporting contexts are implemented via doerr by flushing and closing all files using _reset (see initio(io)) and producing on standard error output the diagnostic message of the form “Error in line line of module module” where error is the message associated with error number passed to runerr, line is the normally the line number as found by doerr and module is the name of the BASIC module in which the error occurred.  If basic(1) was invoked with the -L switch, ??? (three question marks) are written in place of line.  The process finally terminates with status i.  If i is zero, the process terminates with status -1.  UNIX normally truncates this status value to an 8 bit value so it will appear as 255. 

Err returns the BASIC error number.  If no error has occurred, this function returns zero.  This function implements the BASIC ERR variable. 

Erl returns the BASIC error line number.  If no error has occurred or if basic(1) was invoked with the -L switch, this function returns zero.  This function implements the BASIC ERL variable. 

Ehandl returns non-zero if error handling is occurring and returns zero otherwise.  This function supports bend(err). 

Errdisable disables error handling.  This function supports _reset (see initio(io)) to insure that the user’s program is not executed in case of error. 

WARNINGS

Most every error that might occur can be trapped with runerr.  This must not be viewed as a panacea: the errors are trapped not removed.  The user is responsible for resolving the problem.  This is especially true of errors due to problems during a UNIX system call or a call to malloc(3).  In extreme cases, blithely trapping and ignoring errors can result in core dumps or worse. 

SEE ALSO

bend(err), initio(io)
err, erl(vrbl), error(stmt), resume(stmt), stop(stmt)
basic(1) in the Supplemental Documentation section
write(2), malloc(3) in the UNIX Programmer’s Manual

DIAGNOSTICS

Should doerr fail attempting to write the diagnostic, the process will terminate with the status of the return value of write(2). 

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber