Heading:qjk40(635)
IDL DESIGN:  Page headingy756qjk40
Page Numbers: Yes  X: 527  Y: 10.5" qjk40
XEROX Palo Alto Research Center					       15 May 1977
Inter-Office Memorandumz18592y762\f2 5f5 1b25f0B5f5 18f0 1f5b
To	IDL Group	IDL Design Note Number:      11z18592l4445d2998e18(0,65535)(1,4445)(2,12347)(3,13411)(4,15796)(5,11684)(6,14146)\2t2 1t0 9t3 1t0
From	Beau Sheil	File:	<IDL>Design.ErrorHandlinge12qjk40(4,65535)(5,65535)(6,65535)\4t2 1t0 10t3 1t0 5t4 1t0
Subject	 The Handling of User Errors e12qjk40(635)\7t2 1t0
This memo outlines the techniques we will use in the IDL code to handle errors that should be redirected to the user.e18j
Error handling can be divided into two parts - the signalling of the error condition, and the interception and handling of the signal.  The handling, in turn, can be divided into deciding what message to print and where the eventual break is to take place.  The general principles that underlie what follows are (a) exactly one error message will be printed, (b) the decision as to which error message to print will be decided dynamically by a system of overrides, and (c) the final break will occur "close" (in a sense that no system code other than the error handler will depend on) to the point at which the user (code) turned control over to IDL.e12j
The method for signalling the occurrence of a user error ise12j
(UERROR PRINTOUT-command-list)e6c\8f1i8f0 13I
which, unless overridden (see below), will call PRINTOUT on its argument list and return directly to the enclosing UENTRY or UERRORGUARD for further action.  In terms of what is to be written in the system code, this does not differ from the current procedure.e6j\48f1 8f0
The method for altering the response to a user error is e18j
(UERRORGUARD form {PRINTOUT-command-list})e6c\13i4I2f1i8f0 13I
which evaluates form with printout from resulting UERRORs suppressed.  Its subsequent action depends on the presence of a PRINTOUT command list.  If one exists, then it is presumed that the desired effect is to redefine the error message for errors produced by the evaluation of form to be that produced by the new PRINTOUT command list.  Thus,e6j\16i4I38v10V54f1 8f0 149i4I32f1 8f0
(UERRORGUARD A_(CONV.ARITH FOO) "GASP: BAD FOO!")e6c
has the effect of replacing the error message produced by CONV.ARITH with a message that is more appropriate given the higher level context.  Note that the printing of the new message will be done (effectively) by calling UERROR on the PRINTOUT command list.  Consequently, if the UERRORGUARD is in the scope of another (higher) UERRORGUARD, the higher UERRORGUARD will override the lower just as the lower overrode the UERROR.  The multiple levels of error handling thus provided allow each function to construct an error message which takes advantage of its context, without concerning itself with the error messages produced in lower functions.e6j\236f1 8f0
If, on the other hand, there is no PRINTOUT command list in a "call" on UERRORGUARD, it is assumed that the caller is interested in keeping control regardless of the result of the computation.  Consequently, UERROR is not reinvoked, but the answer to the question "Did a UERROR occur?" is returned as the value of the UERRORGUARD.  Using this mechanism, the protected evaluation of RESHAPE can be writtene18j\35f1 8f0
	if (UERRORGUARD (SETQ TMP (CONV.SCALAR A)) )
			then	... A could not be converted to a scalar ...
			else	... it could! (and the result is in TMP) ...e6\58i36I13i44I
The climb back up the chain of UERRORs and UERRORGUARDs ends when we get to the function at which the user gave us control (at which some unspecified thing happens).  This point is specified by requiring the body of any function which can be called directly by the user to be of the forme18j
(DLAMBDA argument-list (UENTRY function-body) )e6c\9i13I10i12I
This will cause (effectively) a special UERRORGUARD to be wrapped around the function body so that the error signal will be caught and redirected to the user in some way that bears on his context.e6j
As the redirection to the user may involve showing him both the arguments he presented and the names to which they were bound, we will observe the following conventionse12j
1.	User entry functions will use moderately descriptive names for their arguments (e.g. from RESHAPE - NEWSHAPE is ok; A is not).l3636d2999e6j\93f1 7f0 3f1 8f0 8f1 1f0
2.	No user entry function will reset the variables to which it binds the arguments presented by the user.l3636d2999j
For convenience during debugging, the absence of a containing UERRORGUARD or UENTRY will cause UERROR to call BREAK1 after printing its message.  This may, however, be a fatal system error in the production version.e12j