ScriptForge.Exception service (SF_Exception) /text/sbasic/shared/03/sf_exception.xhp
Exception service

ScriptForge.Exception service

The Exception service is a collection of methods for Basic code debugging and error handling. In the advent of a run-time error, the Exception service properties and methods help identify the error context and permit to handle it.
The SF_Exception service is similar to the VBA Err object. The Number property identifies the error. Use Raise() method to interrupt processing, use RaiseWarning() method to trap an anomaly and continue processing. Errors or warnings raised with the Exception service are stored in memory and can be retrieved using its Console() method. The Exception service console stores events, variable values and information about errors. Use the console when Basic IDE is not accessible, for example in Calc user defined functions (UDF) or during events processing. Use DebugPrint() method to aggregate additional user data. Console entries can be dumped to a text file or visualized in a dialogue. When an error occurs, an application macro may: Report the error in the Exception console Inform the user about the error using either a standard message either a customized message Optionally stop its execution

Service invocation

To invoke the Exception service, first you need to load the ScriptForge library using: GlobalScope.BasicLibraries.LoadLibrary("ScriptForge") The following examples show three different approaches to call the method Raise. All other methods can be executed in a similar fashion. SF_Exception.Raise(...) Dim exc : exc = SF_Exception exc.Raise(...) Dim exc : exc = CreateScriptService("Exception") exc.Raise(...)

Properties

Name ReadOnly Description Description No The error message text. Default value is "" or a string containing the Basic run-time error message. Number No The code of the error. It can be a numeric value or text. Default value is 0 or the numeric value corresponding to the Basic run-time error code. Source No The location in the code where the error occurred. It can be a numeric value or text. Default value is 0 or the code line number for a standard Basic run-time error.
Raising or clearing an Exception resets its properties. List of Methods in the Exception Service Clear
Console
ConsoleClear ConsoleToFile
DebugPrint

 Raise
RaiseWarning
Clear -------------------------------------------------------------------------------------------------------------------------- Exception service;Clear

Clear

Resets the current error status and clears the SF_Exception properties.

SF_Exception.Clear()

The following example shows how to catch a division-by-zero exception, whose error code is 11. Sub Example_Clear() Dim a, b, c On Local Error GoTo Catch Try: a = 10 : b = 0 c = a / b '... Exit Sub Catch: If SF_Exception.Number = 11 Then SF_Exception.Clear() 'If division by zero, ignore the error End Sub For a complete list of Basic run-time error codes, refer to Debugging a Basic Program.
Console -------------------------------------------------------------------------------------------------------------------------- Exception service;Console

Console

Displays the console messages in a modal or non-modal dialog. In both modes, all the past messages issued by a DebugPrint() method or resulting from an exception are displayed. In non-modal mode, subsequent entries are added automatically. If the console is already open, when non-modal, it is brought to the front. A modal console can only be closed by the user. A non-modal console can either be closed by the user or upon macro termination.

SF_Exception.Console([Modal As Boolean])

Modal: Determine if the console window is Modal (True) or Non-modal (False). Default value is True.

Sub Example_Console() SF_Exception.Console(Modal := True) End Sub
ConsoleClear -------------------------------------------------------------------------------------------------------------------------- Exception service;ConsoleClear

ConsoleClear

Clears the console keeping an optional number of recent messages. If the console is activated in non-modal mode, it is refreshed.

SF_Exception.ConsoleClear([Keep As Long])

Keep: The number of recent messages to be kept. Default value is 0.

The following example clears the console keeping the 10 most recent messages. Sub Example_ConsoleClear() SF_Exception.ConsoleClear(10) End Sub
ConsoleToFile -------------------------------------------------------------------------------------------------------------------------- Exception service;ConsoleToFile

ConsoleToFile

Exports the contents of the console to a text file. If the file already exists and the console is not empty, it will be overwritten without warning. Returns True if successful.

SF_Exception.ConsoleToFile(FileName As String) As Boolean

FileName: The name of the text file the console should be dumped into. The name is expressed according to the current FileNaming property of the SF_FileSystem service. URL notation and the native operating system's format are both admitted.

Sub Example_ConsoleToFile() SF_Exception.ConsoleToFile("C:\myFile.txt") End Sub
DebugPrint -------------------------------------------------------------------------------------------------------------------------- Exception service;DebugPrint

DebugPrint

Assembles all the given arguments into a single human-readable string and adds it as a new entry in the console.

SF_Exception.DebugPrint(Arg0[, Arg1, ...])

Arg0[, Arg1, ...]: Any number of arguments of any type.

Sub Example_DebugPrint() SF_Exception.DebugPrint(Null, Array(1, 2, 3), "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09)) '[NULL] [ARRAY] (0:2) (1, 2, 3) line1\nLine2 2020-04-09 End Sub
Raise -------------------------------------------------------------------------------------------------------------------------- Exception service;Raise

Raise

Generates a run-time error. An error message is displayed to the user and reported in the console. The execution is stopped. The Raise() method can be placed inside the normal script flow or in a dedicated error-handling routine.

SF_Exception.Raise([Number As Variant], [Source As Variant], [Description As String]) The code snippets presented next are equivalent. They show alternative ways to raise an exception with code 2100. SF_Exception.Raise(2100) SF_Exception.Number = 2100 SF_Exception.Raise() SF_Exception.Raise Number := 2100

Number: The error code, as a number or as a string. Default value is that of Err Basic builtin function. Source: The location of the error, as a number or as a string. Default value is that of Erl Basic builtin function. Description: The message to display to the user and to report in the console. Default value is that of Error$ Basic builtin function.

Sub Example_Raise() Dim a, b, c On Local Error GoTo Catch Try: a = 10 : b = 0 c = a / b '... Exit Sub Catch: 'See variants below ... End Sub To raise an exception with the standard values: Catch: SF_Exception.Raise() To raise an exception with an specific code: Catch: SF_Exception.Raise(11) To replace the usual message: Catch: SF_Exception.Raise(, , "It is not a good idea to divide by zero.") To raise an application error: Catch: SF_Exception.Raise("MyAppError", "Example_Raise()", "Something wrong happened !")
RaiseWarning -------------------------------------------------------------------------------------------------------------------------- Exception service;RaiseWarning

RaiseWarning

This method has exactly the same syntax, arguments and behavior as the Raise() method. However, when a warning is raised, the macro execution is not stopped.

SF_Exception.RaiseWarning[Number As Variant], [Source As Variant], [Description As String])

SF_Exception.RaiseWarning(Source:="Example_Raise()", _ Description:="Something wrong happened !", _ Number:="MyAppError")