Structured exception handling

Structured exception handling with TRY-CATCH blocks is the conventional way of handling errors in Synergy .NET and is strongly recommended. We encourage you to use structured exception handling where appropriate, even in your traditional Synergy code.

Structured exception handling means that an exception is thrown every time an error is encountered. This causes the stack to unwind until the appropriate exception handler for that type of exception is found. System.Exception is the parent class for all exceptions. A class called Synergex.SynergyDE.SynException extends this parent class with Synergy error information.

The main syntax elements of structured exception handling are the TRY-CATCH-FINALLY statement and the THROW statement. The TRY-CATCH-FINALLY statement is designed to handle any thrown exceptions within the context of a TRY block. An exception can be thrown one of two ways:

• Implicitly by the Synergy Runtime when an error is encountered
• Explicitly by the application with the THROW statement

To use structured exception handling, your Synergy code must contain TRY-CATCH block syntax that includes code to throw a System.Exception. (See TRY-CATCH-FINALLY-ENDTRY for more information.) Each CATCH block should specify the type of exception to be caught and a local variable to use as the exception instance variable within the block.

A Synergy exception enables you to retrieve the following information:

• Error message
• Call stack at the time the current exception was thrown

After you’ve added TRY-CATCH blocks to your code and compiled, you can use the compiled application to test your exception handling code. Any exception that is thrown inside the scope of the TRY block is tested against the declared types for each CATCH block. If the declared exception to be caught is in the hierarchy tree of the thrown exception, that CATCH block will be executed. Otherwise, the call stack is unwound until either the exception is caught or the main routine is reached and the exception is not caught.

The ERRMOD, %ERROR, %ERNUM, %ERLIN, and %SYSERR routines are not supported in multi-threaded scenarios, and you must use TRY-CATCH under these circumstances.

In Synergy .NET, If an exception is thrown by a method called by XSUBR, and the exception is caught in a TRY-CATCH block in the calling method, the caught method will not have the same type as the original exception thrown in the called method. Instead, it will have the type System.Reflection.TargetInvocationException. This type includes the original exception as the InnerException property and is necessary to preserve stack trace information.

Customizing error information

To customize errors, you can extend an exception class to include additional information:

1.

Create a new exception class that extends System.Exception or System.ApplicationException.

2.

Add methods or fields and/or override inherited methods or fields in the new exception class as needed.

3.

Add a THROW statement to your code to throw the new exception.

4.

Add a FINALLY block to your TRY-CATCH code.

The FINALLY block runs on successful completion of the TRY block or when the CATCH block exits on an exception. Exit conditions include end of block, return statements, and statements that jump to a label outside the TRY-CATCH block. The destructors for any objects that go out of scope as the stack unwinds will be called.

If a thrown exception is not caught by any error handler, the application terminates, providing the error information and traceback information that is currently being provided by Synergy. FINALLY blocks and destructors are not executed on an uncaught exception.