The Exceptions library provides an Exception object for use in Basic4PPC. It will work on both device and desktop and under both .NET 1.0/1.1 and .NET 2.0. It is supported by the IDE and by both legacy and optimising compilers. The Exceptions2 library will work on both device and desktop but only under .NET 2.0. It has two additional properties that return the stack traces for the exception and inner exception (if any). For most purposes the Exceptions library will be quite adequate. However on the rare occasion for unexpected errors it might be useful to have access to the stack trace.

Until version 6.30 the runtime error handling in Basic4PPC was best described as rudimentary. The fact that an error occurred could be caught but no means was available to enable the type of error to be identified by the running program. Versions 6.30 and later of Basic4PPC now provide an additional B4PObject, B4PObject(6), which enables an external library to access the .NET exception object describing the error .

.NET background

First some background information. Error reporting within the .NET Framework, on which Basic4PPC is implemented, is based upon Exception objects that are "thrown" when an error occurs. These Exceptions are "caught" by code that has been specially written to handle any errors, or if no such code exists the application ends with the unhelpful "... has encountered an error and needs to close" message. Each Exception has a type name that identifies the error and a user friendly message that describes the error associated with it. In addition each Exception has an InnerException that is in fact another Exception object. For the first error that occurs in a particular error situation the InnerException is empty but in some situations when handling an error another error can occur. In this case a new Exception can be thrown identifying the latest error with its' InnerException containing the original Exception. In this way a nested chain of error Exceptions can be created if required.

Basic4PPC introduction

Exception handling in Basic4PPC is a little different to raw .NET. In .NET the occurrence of an exception will "unwind" the call stack until some exception handling code is found or not found as described above. However exceptions cannot go "uncaught" in Basic4PPC as exception handling code is always invisibly provided for every Sub.

In optimised compiled Basic4PPC applications exceptions must always be totally handled within the Sub in which they occurred, although this library will let Subs further back down the call chain re-throw an earlier error if required. In the IDE and legacy compiler errors can "jump" across Subs but this is extremely bad practice and can cause confusion so this possibility is deliberately ignored in this discussion. It is highly recommended that all error handling follows the pattern described here.

Unhandled exceptions in Basic4PPC

When an exception occurs in Basic4PPC it will occur in a Sub that may or may not contain an Errorlabel statement and the behaviour is different in each case.

If there is no Errorlabel statement in the Sub then the invisible exception handling comes into play and a MessageBox is displayed to the user showing the Sub where the exception occurred and the message associated with the exception. The user is given the choice of whether to end the program or to let it continue.

Handling exceptions in Basic4PPC

If there is an Errorlabel statement in a Sub where an exception occurs then program execution is switched to the label specified by the last Errorlabel statement executed before the error. In the IDE and legacy compiler this can be, but is strongly recommended not to be, in another Sub. In the optimising compiler this must be in the same Sub and in the same or wider scope than the point at which the exception occurred. The recommended pattern is to place error handling code at the end of a Sub with a Return statement preceding the label(s) specified by any Errorlabel statement(s). This mimics the mandatory placing of exception handling code after normal code that is required in other .NET program languages.

Note that any exceptions thrown in code before the first Errorlabel statement in a Sub will be treated as an unhandled exception. Any exceptions thrown in code after an Errorlabel will cause execution to transfer to the label specified. It is possible to have more than one Errorlabel in a Sub each pointing to a different label to cope with different anticipated types of exception. It is quite valid to place more than one Errorlabel statement within a loop. Any exceptions will vector to the latest label specified by the last Errorlabel statement that was executed.

If a further exception occurs in the exception handling code without that code having executed any Errorlabel statements the behaviour of the optimised compiler is different to that of the IDE and legacy compiler. An exception occurring within exception handling code in an optimised compiled program will cause an unhandled exception to occur and a message box shown to the user as previously described. In the IDE and a legacy compiled program the exception handling code will be re-entered at its' original entry point, so potentially causing an endless loop.

In order to handle any further exceptions within exception handling code then that code may execute an Errorlabel statement to specify the label to which any further exceptions are vectored. Care is needed in structuring code to handle exceptions within exceptions as infinite loops can be created.