Inhalte

# 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:

1. Den Fehler in der Konsole Exception melden

2. Den Benutzer mithilfe einer Standardnachricht oder einer benutzerdefinierten Nachricht über den Fehler informieren

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

Bevor der Dienst Exception verwendet werden kann, muss die Bibliothek ScriptForge geladen beziehungsweise importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

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

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

Der Fehlercodebereich 0-2000 ist für LibreOffice Basic reserviert. Benutzerdefinierte Fehler sollten bei höheren Werten beginnen, um Kollisionen mit zukünftigen Entwicklungen von LibreOffice 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 LibreOffice Python-Skripting-Frameworks. Wenn APSO oder Python fehlen, tritt ein Fehler auf.

### Syntax:

exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

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

background: Hintergrundfarbe der Konsole, angegeben als RGB 24-Bit Integer-Wert. Der Standardhintergrund ist der von APSO.

foreground: Vordergrundfarbe der Konsole, angegeben als RGB 24-Bit Integer-Wert. Der Standardvordergrund ist der von APSO.

### Beispiel:

Das folgende Beispiel öffnet die APSO Python-Shell und übergibt alle globalen und lokalen Variablen unter Berücksichtigung des Kontexts, in dem das Skript ausgeführt wird. Die Konsole wird mit weißen Zeichen auf schwarzem Hintergrund angezeigt.

        exc.PythonShell({**globals(), **locals()}, \
            background = 0x0, foreground = 0xFFFFFF)

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.

        s = CreateScriptService('Basic')
        RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
        exc.PythonShell(background=RED, foreground=BLUE)
        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 := Err, [Source := Erl], [Description := Error$])

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 Nummer oder Zeichenfolge. Der Standardwert ist der von der integrierten Basic-Funktion Err. In diesem Fall ist Number optional.

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

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 Nummer oder Zeichenfolge. Der Standardwert ist der von der integrierten Basic-Funktion Err. In diesem Fall ist Number optional.

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

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:="Etwas ist schiefgelaufen!", _
            Number:="MyAppError")

Verwandte Themen

Funktionen zur Fehlerbehandlung