Dienst ScriptForge.Exception

Der Dienst Exception ist eine Sammlung von Methoden zur Unterstützung beim Code-Debugging in Basic- und Python-Skripten und bei der Fehlerbehandlung in Basic-Skripten.

Wenn in Basic-Skripten ein Laufzeitfehler auftritt, helfen die Methoden und Eigenschaften des Dienstes Exception dabei, den Fehlerkontext zu identifizieren und ihn zu behandeln.

Der Dienst SF_Exception ähnelt dem VBA-Objekt Err.
Die Eigenschaft Number identifiziert den Fehler.
Verwenden Sie die Methode Raise, um die Verarbeitung zu unterbrechen. Die Methode RaiseWarning kann verwendet werden, um eine Anomalie abzufangen, ohne die Makroausführung zu unterbrechen.

Vom Dienst Exception ausgegebene Fehler und Warnungen werden im Speicher gespeichert und können mit der Methode Console abgerufen werden.

Die Servicekonsole Exception speichert Ereignisse, Variablenwerte und Informationen zu Fehlern. Verwenden Sie die Konsole, wenn die Basis-IDE nicht leicht zugänglich ist, beispielsweise in Benutzerdefinierten Calc-Funktionen (UDF) oder während der Ereignisverarbeitung.

Verwenden Sie die Methode DebugPrint, um alle relevanten Informationen zur Konsole hinzuzufügen. Konsoleneinträge können in eine Textdatei ausgegeben oder in einem Dialog angezeigt werden.

Wenn ein Fehler auftritt, kann ein Anwendungsmakro:

Den Fehler in der Konsole Exception melden
Den Benutzer mithilfe einer Standardnachricht oder einer benutzerdefinierten Nachricht über den Fehler informieren
Optional die Ausführung stoppen

In Python-Skripten wird der Dienst Exception hauptsächlich für Debugging-Zwecke verwendet. Methoden wie DebugPrint, Console und DebugDisplay sind nützlich, um innerhalb eines Python-Skripts schnell Meldungen zu drucken, Daten zu protokollieren und das Konsolenfenster zu öffnen.

Nicht alle Methoden und Eigenschaften sind für Python-Skripte verfügbar, da die Python-Sprache bereits über ein umfassendes Ausnahmebehandlungssystem verfügt.

Dienstaufruf

In Basic

Die folgenden Beispiele zeigen drei verschiedene Ansätze, um die Methode Raise aufzurufen. Alle anderen Methoden können auf ähnliche Weise ausgeführt werden.


    SF_Exception.Raise(...)


    Dim exc : exc = SF_Exception
    exc.Raise(...)


    Dim exc : exc = CreateScriptService("Exception")
    exc.Raise(...)

In Python

Der folgende CodeSchnipsel erstellt eine Instanz des Dienstes Exception, protokolliert eine Meldung und zeigt das Konsolenfenster an.


    from scriptforge import CreateScriptService
    exc = CreateScriptService("Exception")
    someVar = 100
    exc.DebugPrint("Value of someVar", someVar)
    exc.Console()

Eigenschaften

Die unten aufgeführten Eigenschaften sind nur für Skripte in Basic verfügbar.

Name	Schreibgeschützt	Beschreibung
Description	Nein	Der Text der Fehlermeldung. Der Standardwert ist "" oder eine Zeichenfolge, welche die Basic-Laufzeitfehlermeldung enthält.
Number	Nein	Der Code des Fehlers. Es kann ein numerischer Wert oder Text sein. Der Standardwert ist 0 oder der numerische Wert, der dem Basic-Laufzeitfehlercode entspricht.
Source	Nein	Die Stelle im Code, an welcher der Fehler aufgetreten ist. Es kann ein numerischer Wert oder Text sein. Der Standardwert ist 0 oder die Codezeilennummer für einen standardmäßigen Basic-Laufzeitfehler.

Name

Schreibgeschützt

Beschreibung

Description

Nein

Der Text der Fehlermeldung.

Der Standardwert ist "" oder eine Zeichenfolge, welche die Basic-Laufzeitfehlermeldung enthält.

Number

Nein

Der Code des Fehlers. Es kann ein numerischer Wert oder Text sein.

Der Standardwert ist 0 oder der numerische Wert, der dem Basic-Laufzeitfehlercode entspricht.

Source

Nein

Die Stelle im Code, an welcher der Fehler aufgetreten ist. Es kann ein numerischer Wert oder Text sein.

Der Standardwert ist 0 oder die Codezeilennummer für einen standardmäßigen Basic-Laufzeitfehler.

Das Auslösen oder Löschen einer Exception setzt ihre Eigenschaften zurück.

Der Fehlercodebereich 0-2000 ist für Collabora Office Basic reserviert. Benutzerdefinierte Fehler sollten bei höheren Werten beginnen, um Kollisionen mit zukünftigen Entwicklungen von Collabora Office Basic zu vermeiden.

Liste der Methoden im Ausnahmedienst
Clear Console ConsoleClear ConsoleToFile	DebugDisplay DebugPrint PythonPrint	PythonShell Raise RaiseWarning

Clear

Setzt den aktuellen Fehlerstatus zurück und löscht die Eigenschaften für SF_Exception.

Diese Methode ist nur für Basic-Skripte verfügbar.

Syntax:


    SF_Exception.Clear()

Beispiel:

Das folgende Beispiel zeigt, wie eine Division-durch-Null-Ausnahme abgefangen wird, deren Fehlercode 11 ist.


    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()
            ' Ignoriert den Fehler, wenn durch Null dividiert wird
    End Sub

Eine vollständige Liste der Basic-Laufzeitfehlercodes finden Sie unter Debuggen eines Basic-Programms.

Console

Zeigt die Konsolenmeldungen in einem modalen oder nicht modalen Dialog an. In beiden Modi werden alle vergangenen Meldungen angezeigt, die von einer Methode DebugPrint() ausgegeben wurden oder aus einer Ausnahme resultierten. Im nicht-modalen Modus werden nachfolgende Einträge automatisch hinzugefügt.

Wenn die Konsole bereits geöffnet ist, wird sie in den Vordergrund gebracht, wenn sie nicht-modal ist.

Eine modale Konsole kann nur vom Benutzer geschlossen werden. Eine nicht-modale Konsole kann entweder vom Benutzer oder bei Beendigung des Makros geschlossen werden.

Syntax:

exc.Console(modal: bool = True)

Parameter:

modal: Legt fest, ob das Konsolenfenster modal (True) oder nicht-modal (False) ist. Der Standardwert ist True.

Beispiel:

In Basic


        SF_Exception.Console(Modal := False)

In Python


    exc.Console(modal = False)

ConsoleClear

Löscht die Konsole und behält eine optionale Anzahl aktueller Nachrichten bei. Wenn die Konsole im nicht-modalen Modus aktiviert wird, wird sie aktualisiert.

Syntax:

exc.ConsoleClear(keep: int = 0)

Parameter:

keep: Die Anzahl der letzten Nachrichten, die aufbewahrt werden sollen. Der Standardwert ist 0.

Beispiel:

Das folgende Beispiel löscht die Konsole und behält die 10 neuesten Nachrichten bei.

In Basic


        SF_Exception.ConsoleClear(10)

In Python


    exc.ConsoleClear(10)

ConsoleToFile

Exportiert den Inhalt der Konsole in eine Textdatei. Wenn die Datei bereits existiert und die Konsole nicht leer ist, wird sie ohne Warnung überschrieben. Gibt bei Erfolg True zurück.

Syntax:

exc.ConsoleToFile(filename: str): bool

Parameter:

filename: Der Name der Textdatei, in der die Konsole abgelegt werden soll. Der Name wird gemäß der aktuellen Eigenschaften für FileNaming des Dienstes SF_FileSystem ausgedrückt. Standardmäßig werden sowohl die URL-Notation als auch das Format des nativen Betriebssystems zugelassen.

Beispiel:

In Basic


        SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")

In Python


    exc.ConsoleToFile(r"C:\Documents\myFile.txt")

DebugDisplay

Verkettet alle Argumente zu einer einzigen für Menschen lesbaren Zeichenfolge und zeigt sie in einer MsgBox mit einem Informationssymbol und einer Schaltfläche "OK" an.

Die letzte Zeichenfolge wird auch der Konsole hinzugefügt.

Syntax:

exc.DebugDisplay(arg0: any, [arg1: any, ...])

Parameter:

arg0[, arg1, …]: Beliebig viele Argumente beliebigen Typs.

Beispiel:

In Basic


    SF_Exception.DebugDisplay("Current Value", someVar)

In Python


    exc.DebugDisplay("Current Value", someVar)

DebugPrint

Fasst alle angegebenen Argumente zu einer einzigen für Menschen lesbaren Zeichenfolge zusammen und fügt sie als neuen Eintrag in der Konsole hinzu.

Syntax:

exc.DebugPrint(arg0: any, [arg1: any, ...])

Parameter:

arg0[, arg1, …]: Beliebig viele Argumente beliebigen Typs.

Beispiel:

In Basic


    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

In Python


    exc.DebugPrint(None, [1, 2, 3], "line1\nline2")
    # None  [1, 2, 3]  line1\nline2

PythonPrint

Zeigt die Liste der Argumente in lesbarer Form in der Plattformkonsole an. Argumente werden durch einen Tabulator getrennt (durch Leerzeichen simuliert).

Dieselbe Zeichenfolge wird der ScriptForge-Debug-Konsole hinzugefügt.

Wenn Python-Shell (APSO) aktiv ist, wird der Inhalt von PythonPrint anstelle der Plattformkonsole in die APSO-Konsole geschrieben.

Diese Methode ist nur für Basic-Skripte verfügbar.

Syntax:


  exc.PythonPrint(arg0: any, [arg1: any, ...])

Parameter:

arg0[, arg1, …]: Beliebig viele Argumente beliebigen Typs. Die maximale Länge jedes einzelnen Arguments beträgt 1024 Zeichen.

Beispiel:


    exc.PythonPrint(a, Array(1, 2, 3), , "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))

Verwenden Sie in Python eine Anweisung print, um an die APSO-Konsole zu drucken, oder verwenden Sie die Methode DebugPrint, um an die ScriptForge-Konsole zu drucken.

PythonShell

Öffnet eine APSO-Python-Shell als nicht-modales Fenster. Das Python-Skript wird nach dem Öffnen der Shell weiter ausgeführt. Die Ausgabe von Anweisungen print innerhalb des Skripts wird in der Shell angezeigt.

Es kann immer nur eine einzige Instanz der APSO-Python-Shell geöffnet werden. Wenn also bereits eine Python-Shell geöffnet ist, hat der Aufruf dieser Methode keine Auswirkung.

Diese Methode erfordert die Installation der Erweiterung APSO (Alternative Script Organizer for Python). APSO wiederum erfordert das Vorhandensein des Collabora Office Python-Skripting-Frameworks. Wenn APSO oder Python fehlen, tritt ein Fehler auf.

Syntax:

exc.PythonShell(variables: dict)

Parameter:

variables: ein Python-Wörterbuch mit Variablennamen und -werten, die an die APSO-Python-Shell weitergegeben werden. Standardmäßig werden alle lokalen Variablen mit der eingebauten Funktion locals() von Python übergeben.

Beispiel:

Das folgende Beispiel öffnet die APSO-Python-Shell und übergibt alle globalen und lokalen Variablen unter Berücksichtigung des Kontextes, in dem das Skript ausgeführt wird.


    exc.PythonShell({**globals(), **locals()})

Wenn die APSO-Python-Shell geöffnet ist, werden alle nachfolgenden Ausgaben, die vom Skript gedruckt werden, in der Shell angezeigt. Daher wird die im folgenden Beispiel gedruckte Zeichenfolge in der Python-Shell angezeigt.


    exc.PythonShell()
    print("Hallo Welt!")

Raise

Erzeugt einen Laufzeitfehler. Eine Fehlermeldung wird dem Benutzer angezeigt und in der Konsole gemeldet. Die Ausführung wird gestoppt. Die Methode Raise() kann in den normalen Skriptablauf oder in eine dedizierte Fehlerbehandlungsroutine eingefügt werden.

Diese Methode ist nur für Basic-Skripte verfügbar.

Syntax:


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

Die folgenden Codeausschnitte sind gleichwertig. Sie zeigen alternative Möglichkeiten zum Auslösen einer Ausnahme mit Code 2100.


    SF_Exception.Raise(2100)


    SF_Exception.Number = 2100
    SF_Exception.Raise()


    SF_Exception.Raise Number := 2100

Parameter:

Number: Der Fehlercode, als Zahl oder als Zeichenfolge. Der Standardwert ist jener der integrierten Basic-Funktion Err.

Source: Der Ort des Fehlers, als Zahl oder als Zeichenfolge. Der Standardwert ist jener der integrierten Basic-Funktion Erl.

Description: Die Nachricht, die dem Benutzer angezeigt und in der Konsole gemeldet werden soll. Der Standardwert ist jener der integrierten Basic-Funktion Error$.

Beispiel:


    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            ' Siehe Varianten unten …
    End Sub

Um eine Ausnahme mit den Standardwerten auszulösen:


    Catch:
        SF_Exception.Raise()

Um eine Ausnahme mit einem bestimmten Code auszulösen:


    Catch:
        SF_Exception.Raise(11)

Um die übliche Nachricht zu ersetzen:


    Catch:
        SF_Exception.Raise(, , "Es ist keine gute Idee, durch Null zu dividieren.")

Um einen Anwendungsfehler zu melden:


    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Etwas falsches ist passiert !")

RaiseWarning

Diese Methode hat genau dieselbe Syntax, dieselben Argumente und dasselbe Verhalten wie die Methode Raise().

Wenn jedoch eine Warnung ausgegeben wird, wird die Makroausführung nicht gestoppt.

Diese Methode ist nur für Basic-Skripte verfügbar.

Syntax:


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

Parameter:

Number: Der Fehlercode, als Zahl oder als Zeichenfolge. Der Standardwert ist jener der integrierten Basic-Funktion Err.

Source: Der Ort des Fehlers, als Zahl oder als Zeichenfolge. Der Standardwert ist jener der integrierten Basic-Funktion Erl.

Description: Die Nachricht, die dem Benutzer angezeigt und in der Konsole gemeldet werden soll. Der Standardwert ist jener der integrierten Basic-Funktion Error$.

Beispiel:


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

Funktionen zur Fehlerbehandlung