WHEN ERRor
Syntax |
WHEN ERRor |
Location |
QL ROM (post JM), THOR XVI |
This command marks the beginning of the SuperBASIC structure which is used to surround lines of SuperBASIC code which should be executed whenever an error is generated whilst error trapping is active. Error trapping is activated as soon as the interpreter reads a line containing WHEN ERRor. It is therefore not activated by a WHEN ERRor command being entered into the command window (#0) - indeed this has a special purpose (see below). The syntax of the SuperBASIC structure can take two forms:
WHEN ERROR: statement *[:statement]*
or
WHEN ERROR *[statements]* .. END WHEN
In the normal course of progress, the WHEN ERRor block would appear at the start of a SuperBASIC program, and error trapping would therefore be enabled as soon as a program is RUN. Once error trapping is enabled, whenever an error is generated, control is passed to the WHEN ERRor clause, allowing you to specify how it the error to be dealt with.
It must however be borne in mind that whilst active, errors will trigger the WHEN ERRor clause whether they are generated whilst the program is being RUN or at some other stage (eg. if a direct command causes an error). If the interpreter comes across more than one WHEN ERRor block, then the latest one is used to trap errors.
Errors generated within the WHEN ERRor block itself are reported as normal, although the message ‘during WHEN processing’ is displayed along with the error message. Unless you include a STOP statement in the WHEN ERRor clause, after going through all of the lines within the clause, the program will continue running from the statement following the one which caused the error.
You can force this to happen with CONTINUE, whereas RETRY can be used to re-execute the command which caused the error. Error trapping is turned off by the command WHEN ERRor (when entered as a direct command), and also when the NEW, CLEAR, LOAD, LRUN, MERGE, and MRUN commands are issued.
Example
A program which provides a fully error trapped educational aid:
100 WHEN ERRor
110 STRIP#0,2
120 IF ERR_XP
130 PRINT#0,'Please enter a number!'\'Press a key'
140 PAUSE:STRIP #0,0:RETRY 320
150 END IF
160 IF ERR_OV
170 PRINT#0,'Divide by zero is undefined!'\'Press a key'
180 PAUSE:STRIP #0,0:RETRY 320
190 END IF
200 STRIP #0,0
210 PRINT #0,'At line: ';ERLIN:REPORT:STOP
220 END WHEN
225 :
230 MODE 8
240 WINDOW 448,200,32,16:PAPER 0:INK 6:CLS
250 WINDOW #0,448,40,32,216:PAPER#0,0:INK#0,7:CLS#0
260 CSIZE 2,0:AT 8,8:PRINT 'Maths Division Tutor'
270 CSIZE 1,0
280 REPeat loop
290 y=RND(1 TO 10):x=RND(1 TO 10)*y
300 IF y>x:ya=x:x=y:y=ya
310 IF RND>.9:x=0:y=0
320 REPeat answer
330 AT 10,0:CLS 2:AT 11,0:CLS#0
340 INPUT 'Enter number to divide'!(x)!'by to give'!(y)!': ';a
350 IF x/a=y THEN EXIT answer
360 PRINT \\'Wrong - Please try again'\'Press a key'
370 PAUSE
380 END REPeat answer
390 PRINT \\'Correct - Another one...'\'Press a key'
400 PAUSE
410 END REPeat loop
NOTE 1
This SuperBASIC structure does not work very reliably on any QL versions other than Minerva v1.77 (or later), SMS or the THOR XVI: although Toolkit II improves the reliability, problems include crashing the machine if an error is generated inside a function whilst error trapping is enabled {eg. PRINT SQRT(-1)}, or if you try to carry out INKEY$ at the end of a file. WHEN ERRor clauses will also remain in force despite NEW, CLEAR, LRUN, LOAD, MERGE and MRUN.
NOTE 2
WHEN ERRor cannot trap the Break key <CTRL><SPACE> (and <ESC> on Minerva), which will continue to stop a SuperBASIC program.
NOTE 3
You should not try to nest several WHEN ERRor clauses - under SMS the error ‘WHEN clauses may not be nested’ is reported.
SMS NOTE
Even in the in-line version of WHEN ERRor it is imperative that END WHEN is specified, otherwise the error ‘Incomplete WHEN clause’ will be reported.
CROSS-REFERENCE
ERLIN returns the line number on which the error occurred. ERNUM returns the error number itself. There are several functions in the form ERR_XX which return 1 if the given error has occurred. BREAK_OFF allows you to turn the Break key off. END WHEN defines the end of the error handling block.