Please visit the sponsor of this series, and don't forget to say where you heard of them!
Please ensure you have the latest version (1.7) of the RMREvent program from the RMR web site before reading through this tutorial. If you use an older version, some of the text may not make sense.
Have you ever tried out a new third-party Psion program and been frustrated by the way it occasionally 'crashed', usually with nothing more than a terse error message from the operating system? One of the goals for any professional programmer should be that the end-user never gets to see this type of screen. Even if something should go horribly wrong (perhaps a file has been deleted by another program, or there's no disk space left to save a file), your goal should always be to inform the user in as friendly way as possible of the type of problem and to suggest a way of fixing it.
RMREvent shows us the two parts of any successful error-handling scheme:
For an example of error-trapping, locate the Run: procedure in the RMREvent code:
PROC Run:
ONERR Handler::
DO
GETEVENT32 A&()
IF A&(1)=Open_or_Close_Document
DocumentName$=GETCMD$
...etc...
ENDIF
UNTIL Forever
Handler::
ONERR OFF
Error_Handler:(Program$)
ENDP
Notice the built-in error trapping in OPL: by using ONERR and a label you're saying to OPL/32 "If any errors occur I want to handle them myself. Just put the error number etc. in the standard place [variables ERR and ERRX$] and I'll sort out what happens next". There are lists of the OPL commands that work with ONERR in the various manuals and help files, so I won't repeat them here, but essentially most of the common 'action' commands are trappable in this way. The label is just a text placeholder later on in the same procedure and the usual way to distinguish them from other variables, commands and procedures is by putting two colons after the name.
Once the program has jumped to the Handler:: label, error trapping is immediately turned off, to preserve the information in ERR and ERRX$. (Note, by the way, that you don't need to define these two variables anywhere - they're just always there, put in place by OPL/32.)
Of course, a simple program might just print the error number to the screen right here in the same procedure that had the error, along with some suitably friendly text for the user to read. RMREvent goes one better, by recognising that there will be many, many possible places in a real-world program where errors can occur and that if the error reporting display statements were put in each time, there would be much unnecessary duplication. Thus a general reporting procedure is used to handle any errors created anywhere within the program. Find the Error_Handler: procedure in the code:
PROC Error_Handler:(P$)
DINIT "",2
dTEXT "","Sorry. it
seems an unexpected error has occured"
dTEXT "","Please E-mail me at :
xxxxxxxx.xxxx@xxxx.com"
dTEXT "","and tell me the EXACT circumstances and
the key"
dTEXT "","presses that led to this error. I will also need"
dTEXT "","the following additional information :"
dTEXT "","",$800
dTEXT "",P$+" Version "+Version$
dTEXT "","There has been an "+ERRX$
dTEXT "","The error was : "+ERR$(ERR)
dBUTTONS "Continue",13 OR $300
DIALOG
ENDP
I'm not quite sure why RMR chose to pass the program name through into the procedure, this could be left out if you wanted as the name of a program is nearly always kept in a suitable global variable by the programmer. The important bits, as said before, are the display of the variables ERRX$ (the program name and procedure that was running at the moment the error happened) and ERR (the error number). The code here also uses the ERR$() function, which simply translates the cyptic error number into plain english, for the benefit of programmer, testers and end users!
RMR Software kindly provided a button on the main toolbar to help us test the error handling procedure. Try it now and see how the quoting of error location and name works:
An especially nice touch that's also worth copying is the inclusion of the address to report errors to within the same screen. If you have to rely on users looking up your email address from somewhere else in order to email you with details of a problem, chances are they won't get round to it at all! Make things as easy for your testers and users as possible and you'll get more feedback and ultimately a better application.
Yes, there are some program errors which cannot be TRAPped in this way, but you'll have to live with that. Make sure you test your program thoroughly as there really is no excuse for unleashing buggy software on the general public. Using a combination of the techniques mentioned above and a team of keen beta-testers, your software can behave as robustly as anything put out by the big commercial software houses!
We wind up our look at RMREvent next week with a peek at OPL/32 database handling.
Go to next lesson | Programming index