Script.OnError

Syntax

VBScript:

Script.OnError = GetRef("funcHandler")

JScript:

Script.OnError = funcHandler;

Object

Script The Script object.

Parameters

funcHandler
The name of a function that is called when errors occur in the script. The function signature is:

VBScript:
Sub funcHandler(oAPGError)

JScript:
function funcHandler(oAPGError)

The function should set oAPGError.Handled to true if the error is completely handled. This prevents other error handlers from being called. If oAPGError.Handled is not set to true, other error handlers, including the default handler, will be called. See the topic Error Handling for more information on the error handling chain. See Script.GetLastError() for a description of the APGError object.

Notes

Script.OnError allows developers to override the default handling of run-time errors in a script. It does not allow recovery from a fatal error in the script - script language error handling should be used to recover from expected script errors. For more information on different types of error handling, see Error Handling.

Note that if your error handler function is called to report a fatal error, the error handler script is the last code that is run before the script exits. Internal error handlers (error handlers written in the script for which they're handling errors) can only handle run-time errors, and all run-time errors that are reported are fatal. To hook up external error handlers, see APGScript.OnError.

The error-handler function receives an APGError object as a parameter. The error-handler function can indicate whether other error handlers (connected handlers (if any), plus the default handler) should be called after the error-handler function exits. To prevent other error handlers from being called, the error-handler function should set oAPGError.Handled to True. For more information on the different types of error handlers, see Error Handling.

Normally, if an error occurs in a script, Run() and RunArgs() will return errors. If you don't want an error to be returned to Run() or RunArgs(), you can either:

Call Script.Abort() in your custom error handler. Script.Abort() halts script execution, and it assures that Run() and RunArgs() won't return an error.
Or, call oAPGError.Clear() in your custom error handler. This also prevents Run() and RunArgs() from returning an error.

Example

This example uses VBScript to provide a MsgBox function, and uses JScript for the error handler and Main functions. When a fatal error occurs, the user is given a chance to abort the script. If the script is not aborted, the default error handler is run, which asks the user if they want to debug the script.

<%# @LANGUAGE = VBScript #%>
<%#

Function YNBox(sPrompt, sTitle)
     retval = MsgBox(sPrompt, vbYesNo, sTitle)
     If (retval = vbYes) Then
          YNBox = True
     Else
          YNBox = False
     End If
End Function

#%>
<SCRIPT RUNAT=APGen LANGUAGE=JScript>

function ErrorHandler(oAPGError)
     {
     if (oAPGError.Severity == apgSeverityFatal)
          {
          var bAbort = YNBox(oAPGError.Description + "\n\nAbort the script?",
                                        oAPGError.Source);
          if (bAbort)
               {
               oAPGError.Handled = true;
               Script.Abort();
               }
          }
     }


function Main()
     {
     // Set the script error handler
     Script.OnError = ErrorHandler;

     // Cause an error
     MethodNotPresent();
     }

</SCRIPT>

An equivalent VBScript version of Main() is:

...
Sub Main
     ' Set the script error handler
     Script.OnError = GetRef("ErrorHandler")

     ' Cause an error
     MethodNotPresent
End Sub

Applies To

Script Object