|
|
APGen Developer's Guide |
|
See Also: |
This topic discusses the types of errors that occur in APG scripts, and how they can be dealt with.
The first time a script is Run(), the script file is loaded, parsed by the APGen preprocessor, and then compiled by the the appropriate script engines. Errors can occur when the script file is being preprocessed - for example, if an include file can't be found, a fatal error is reported as an "APGen Compile Error". Errors can also occur due to invalid APG Script syntax - for example, if a closing APG script bracket (#%>) can't be found, a warning is reported as an "APGen Syntax Error". Any custom error handlers that were attached before the script is first run will receive notification of these errors.
When the post-processed script is compiled by the script engines, the script engines may determine that the script contains syntax or compile errors. Script engine reported syntax and compile errors are fatal errors, so the APG script is not run. Any custom error handlers that were attached before the script is first run will receive notification of these errors.
After the script is loaded, preprocessed, and compiled by the script engine, it is run. If a run-time error occurs and script language error handling is enabled, no error is reported to APGen or the debugger. Script language error handling includes VBScript On Error Resume Next error handling, and JScript try ... catch exception handling. When you use script language error handling, you are responsible for detecting and handling all errors within the script. Script language error handling is the only way to handle run-time errors within a script and continue script execution.
If a run-time error occurs, and script language error handling is not being used, and the script is being run in the debugger, the debugger catches the error, and no error is reported to APGen. In this situation, the error will usually continue to occur until you do something about it within the debugger.
If a run-time error occurs, and script language error handling is not used, and the script is not being run in the debugger, the error is reported to APGen. At that point, APGen executes the error handler chain, which is covered below.
Win32 exceptions are the worst kind of error that can occur. Many programs crash when exceptions occur. Several types of exceptions exist, including Access Violations (probably the most common), Illegal Instructions, and others. They can be caused by bugs in components that you use in your APG scripts, bugs in script engines, or other bugs. The VBScript and JScript engines don't handle exceptions, so it is not possible to recover from exceptions using script language error handling. APGen does catch exceptions, and executes the error handler chain when one is caught. This behavior makes APG scripts very robust, and allows you to take whatever action you like (in the custom script handler) when a severe error occurs.
The biggest problem with Win32 exceptions is finding their source. APGen is not able to report the line of the script, or even the script file that caused the exception. APGen reports which APG script was executing at the time, but APGen is not able to pinpoint the exception. The best way to find the cause of an exception is to step through the script in a debugger until you isolate the line where it occurs.
The error handler chain is a pluggable and programmable way to customize error handling. You can handle errors with script code, or with external Visual Basic, ASP, or C++ code.
The error handler chain is run for all errors, except errors that are intercepted by script language error handling or the debugger.
There are two varieties of custom error handlers. The first is Script.OnError error handlers. The second is Script Error Event handlers.
When no custom error handlers are installed, the default error handler is used. The default error handler logs errors (depending on the Log.Flags setting), and displays an error dialog box if the error is fatal and Script.Debug is true. For run-time errors, the error dialog box gives the option to debug the script if a script debugger is installed.
The error handler chain consists of running error handlers in this order:
Any error handler can prevent subsequent handlers from running by setting oAPGError.Handled to true.
If a custom error handler is attached within APG script code, that error handler will not receive notification of loading/parsing errors or syntax/compile errors. The reason is that by the time the script is run, any loading/parsing errors and syntax/compile errors will have already occurred. For a custom error handler to receive pre-runtime errors, you should attach the error handler externally before the script is first run. See the Script Error Events topic for an example.
When an APG script is run using Run() or RunArgs(), and a fatal error occurs in the script, an error is normally raised at the Run() or RunArgs() statement. If you don't want an error raised by Run() or RunArgs(), you can do one of the following in a custom error handler: