APGScript.OnError

Syntax

VBScript:

oAPGScript.OnError = GetRef("funcHandler")

JScript:

oAPGScript.OnError = funcHandler;

Object

oAPGScript An APGScript object.

Parameters

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

Visual Basic:

Sub funcHandler(ByVal oAPGError As APGenLib.IAPGError)

Java:

void funcHandler(Object oAPGError)

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 APGError Object for a description of the APGError object.

Notes

This property provides external access to the Script.OnError property.

APGScript.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.

The APGScript.OnError property can be set to any IDispatch function. This means it can be pointed to a script function, or to an IDispatch function in Visual Basic, Visual J++, C++, etc. For an example of using Visual Basic for error handling, see the Script Error Events topic.

Normally, if a fatal error occurs in a script, Run() and RunArgs() will raise errors. If you do not want an error to be raised, you can either:

Call Script.Abort() in your custom error handler. Script.Abort() prevents any further script execution, and it assures that Run() and RunArgs() won't return an error.
Or, you can call oAPGError.Clear() in your custom error handler. This clears the error object, and prevents the default error handler from being called. It also prevents Run() and RunArgs() from returning an error.

Example

This example runs another APG script (hello.apg). If any errors occur in hello.apg, OnScriptError() is called. If the error is fatal, it is logged to the NT Event Log, and the script is Abort() ed.

<%# @Language="JScript" #%>
<%#

function Main()
     {
     // Open the script
     var oAPGen = Script.CreateObject("APGen");
     var oScript = oAPGen.OpenScript("c:\\temp\\apgs\\hello.apg");

     // Connect the external error handler to oScript
     oScript.OnError = OnScriptError;

     // Run the script - if any errors occur, they'll
     //     be caught by OnScriptError
     oScript.Run();
     }

// Error event handler for oScript
function OnScriptError(oAPGError)
     {
     if (oAPGError.Severity != apgSeverityFatal)
          return;

     // Send report of fatal error to the NT Event Log
     var sError = "Fatal error occurred in script '" +
                         oAPGError.Script.Path + "'\r\n\r\n";
     Log.LogEvent(sError + oAPGError.Description, apgSeverityFatal,
                    oAPGError.Number);

     // Mark error as handled, so default error handler doesn't run
     oAPGError.Handled = true;

     // Abort the script, so oScript.Run() doesn't raise an error
     oAPGError.Script.Abort();
     }

#%>

Applies To

APGScript Object