service ScriptForge.Exception

De service Exception is een verzameling methoden om te helpen bij het debuggen van code in Basic- en Python-scripts en bij foutafhandeling in Basic-scripts.

Wanneer in Basic-scripts een runtime-fout optreedt, helpen de methoden en eigenschappen van de Exception-service om de foutcontext te identificeren en deze af te handelen.

De service SF_Exception is vergelijkbaar met het VBA Err-object.
De eigenschap Number identificeert de fout.
Gebruik de methode Raise om de verwerking te onderbreken. De methode RaiseWarning kan worden gebruikt om een anomalie op te vangen zonder de uitvoering van de macro te onderbreken.

Fouten en waarschuwingen met de service Exception worden in het geheugen opgeslagen en kunnen worden opgehaald met de methode Console.

De serviceconsole Exception slaat gebeurtenissen, variabele waarden en informatie over fouten op. Gebruik de console wanneer de Basic IDE niet gemakkelijk toegankelijk is, bijvoorbeeld in Calc gebruikergedefinieerde functies (UDF) of tijdens het verwerken van gebeurtenissen.

Gebruik de methode DebugPrint om relevante informatie aan de console toe te voegen. Console-items kunnen naar een tekstbestand worden gedumpt of in een dialoogvenster worden gevisualiseerd.

Als er een fout optreedt, kan een toepassingsmacro:

Rapporteer de fout in de console Exception
Informeer de gebruiker over de fout met behulp van een standaardbericht of een aangepast bericht
Stop eventueel de uitvoering ervan

In Python-scripts wordt de service Exception meestal gebruikt voor foutopsporingsdoeleinden. Methoden zoals DebugPrint, Console en DebugDisplay zijn handig om snel berichten af te drukken, gegevens te loggen en het consolevenster te openen vanuit een Python-script.

Niet alle methoden en eigenschappen zijn beschikbaar voor Python-scripts, aangezien de Python-taal al een uitgebreid systeem voor het afhandelen van uitzonderingen heeft.

Service aanroep

In BASIC

De volgende voorbeelden laten drie verschillende benaderingen zien om de methode Raise aan te roepen. Alle andere methoden kunnen op dezelfde manier worden uitgevoerd.


    SF_Exception.Raise(...)


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


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

In Python

Het onderstaande codefragment maakt een instantie van de service Exception, registreert een bericht en geeft het venster Console weer.


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

Eigenschappen

De onderstaande eigenschappen zijn alleen beschikbaar voor Basic-scripts.

Name	AlleenLezen	Beschrijving
Description	Nee	De tekst van de foutmelding. De standaardwaarde is "" of een tekenreeks die het Basic runtime-foutbericht bevat.
Number	Nee	De code van de fout. Dit kan een numerieke waarde of tekst zijn. De standaardwaarde is 0 of de numerieke waarde die overeenkomt met de Basic runtime-foutcode.
Source	Nee	De locatie in de code waar de fout is opgetreden. Dit kan een numerieke waarde of tekst zijn. De standaardwaarde is 0 of het coderegelnummer voor een standaard Basic runtime-fout.

Name

AlleenLezen

Beschrijving

Description

Nee

De tekst van de foutmelding.

De standaardwaarde is "" of een tekenreeks die het Basic runtime-foutbericht bevat.

Number

Nee

De code van de fout. Dit kan een numerieke waarde of tekst zijn.

De standaardwaarde is 0 of de numerieke waarde die overeenkomt met de Basic runtime-foutcode.

Source

Nee

De locatie in de code waar de fout is opgetreden. Dit kan een numerieke waarde of tekst zijn.

De standaardwaarde is 0 of het coderegelnummer voor een standaard Basic runtime-fout.

Door een Exception te verhogen of te wissen, worden de eigenschappen ervan opnieuw ingesteld.

De foutcodes 0-2000 zijn gereserveerd voor LibreOffice Basic. Als er door gebruikers fouten worden gedefinieerd dan moeten die een hogere foutcode krijgen dan 2000 om in de toekomst problemen met nieuwe uitbreidingen van LibreOffice Basic te voorkomen.

Lijst met methoden in de uitzonderingsservice
Clear Console ConsoleClear ConsoleToFile	DebugDisplay DebugPrint PythonPrint	PythonShell Raise RaiseWarning

Clear

Stelt de huidige foutstatus opnieuw in en wist de eigenschappen SF_Exception.

Deze methode is alleen beschikbaar voor BASIC-scripts.

Syntaxis:


    SF_Exception.Clear()

Voorbeeld:

Het volgende voorbeeld laat zien hoe u een uitzondering voor delen door nul kunt opvangen, waarvan de foutcode 11 is.


    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()
            'Indien deling door nul, negeer de fout
    End Sub

Raadpleeg Debuggen van een basisprogramma voor een volledige lijst met Basic runtime-foutcodes.

Console

Geeft de consoleberichten weer in een modaal of niet-modaal dialoogvenster. In beide modi worden alle eerdere berichten weergegeven die zijn uitgegeven door een DebugPrint()-methode of die het gevolg zijn van een uitzondering. In niet-modale modus worden volgende items automatisch toegevoegd.

Als de console al open is, wordt deze, wanneer deze niet-modaal is, naar voren gebracht.

Een modale console kan alleen door de gebruiker worden afgesloten. Een niet-modale console kan worden gesloten door de gebruiker of bij beëindiging van de macro.

Syntaxis:

exc.Console(modal: bool = True)

Parameters:

modal: Bepaal of het consolevenster modaal (True) of niet-modaal (False) is. Standaardwaarde is True.

Voorbeeld:

In BASIC


        SF_Exception.Console(Modal := False)

In Python


    exc.Console(modal = False)

ConsoleClear

Wist de console en bewaart een optioneel aantal recente berichten. Als de console in niet-modale modus is geactiveerd, wordt deze vernieuwd.

Syntaxis:

exc.ConsoleClear(keep: int = 0)

Parameters:

keep: Het aantal recente berichten dat moet worden bewaard. Standaardwaarde is 0.

Voorbeeld:

In het volgende voorbeeld wordt de console gewist en worden de 10 meest recente berichten bewaard.

In BASIC


        SF_Exception.ConsoleClear(10)

In Python


    exc.ConsoleClear(10)

ConsoleToFile

Exporteert de inhoud van de console naar een tekstbestand. Als het bestand al bestaat en de console niet leeg is, wordt het zonder waarschuwing overschreven. Retourneert True indien succesvol.

Syntaxis:

exc.ConsoleToFile(filename: str): bool

Parameters:

filename: De naam van het tekstbestand waarin de console moet worden gedumpt. De naam wordt uitgedrukt volgens de huidige eigenschap FileNaming van de service SF_FileSystem. Standaard zijn URL-notatie en de indeling van het oorspronkelijke besturingssysteem beide toegestaan.

Voorbeeld:

In BASIC


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

In Python


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

DebugDisplay

Voegt alle argumenten samen tot een enkele door mensen leesbare string en geeft deze weer in een MsgBox met een informatiepictogram en een OK-knop.

De laatste tekenreeks wordt ook toegevoegd aan de console.

Syntaxis:

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

Parameters:

arg0[, arg1, ...]: Een willekeurig aantal argumenten van elk type.

Voorbeeld:

In BASIC


    SF_Exception.DebugDisplay("Current Value", someVar)

In Python


    exc.DebugDisplay("Current Value", someVar)

DebugPrint

Verzamelt alle gegeven argumenten in een enkele door mensen leesbare tekenreeksen en voegt deze toe als een nieuw item in de console.

Syntaxis:

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

Parameters:

arg0[, arg1, ...]: Een willekeurig aantal argumenten van elk type.

Voorbeeld:

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

Toont de lijst met argumenten in een leesbare vorm in de platformconsole. Argumenten worden gescheiden door een TAB-teken (gesimuleerd door spaties).

Dezelfde tekenreeks wordt toegevoegd aan de ScriptForge-foutopsporingsconsole.

Als Python shell (APSO) actief is, wordt PythonPrint-inhoud naar de APSO-console geschreven in plaats van de platformconsole.

Deze methode is alleen beschikbaar voor BASIC-scripts.

Syntaxis:


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

Parameters:

arg0[, arg1, ...]: Een willekeurig aantal argumenten van elk type. De maximale lengte van elk afzonderlijk argument is 1024 tekens.

Voorbeeld:


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

Gebruik in Python een print-statement om af te drukken naar de APSO-console of gebruik de DebugPrint-methode om af te drukken naar de ScriptForge-console.

PythonShell

Opent een APSO Python-shell als een niet-modaal venster. Het Python-script blijft actief nadat de shell is geopend. De uitvoer van print-instructies in het script wordt weergegeven in de shell.

Slechts één exemplaar van de APSO Python-shell kan op elk moment worden geopend. Als een Python-shell al open is, heeft het aanroepen van deze methode dus geen effect.

Voor deze methode is de installatie verplicht van de extensie APSO (Alternative Script Organizer for Python). Voor het gebruik van APSO is de aanwezigheid van LibreOffice Python scripting framework verplicht. Indien APSO of Python ontbreken treedt er een fout op.

Syntaxis:

exc.PythonShell(variables: dict)

Parameters:

variables: een Python-woordenboek met variabelenamen en waarden die worden doorgegeven aan de APSO Python-shell. Standaard worden alle lokale variabelen doorgegeven met behulp van de ingebouwde functie locals() van Python.

Voorbeeld:

Het onderstaande voorbeeld opent de APSO Python-shell en geeft alle globale en lokale variabelen door, rekening houdend met de context waarin het script wordt uitgevoerd.


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

Wanneer de APSO Python-shell open is, wordt elke volgende uitvoer die door het script wordt afgedrukt, in de shell weergegeven. Daarom wordt de tekenreeks die in het onderstaande voorbeeld is afgedrukt, weergegeven in de Python-shell.


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

Raise

Genereert een runtime-fout. Er wordt een foutbericht weergegeven aan de gebruiker en gerapporteerd in de console. De uitvoering wordt stopgezet. De methode Raise() kan in de normale scriptstroom of in een speciale foutafhandelingsroutine worden geplaatst.

Deze methode is alleen beschikbaar voor BASIC-scripts.

Syntaxis:


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

De codefragmenten die hierna worden weergegeven, zijn equivalent. Ze laten alternatieve manieren zien om een uitzondering op te heffen met code 2100.


    SF_Exception.Raise(2100)


    SF_Exception.Number = 2100
    SF_Exception.Raise()


    SF_Exception.Raise Number := 2100

Parameters:

Number: De foutcode, als een getal of als een tekenreeks.Standaardwaarde is die van de ingebouwde Basic-functie Err.

Source: De locatie van de fout, als een getal of als een tekenreeks.Standaardwaarde is die van de ingebouwde Basic-functie Erl.

Description: Het bericht dat aan de gebruiker moet worden weergegeven en in de console moet worden gerapporteerd. Standaardwaarde is die van de ingebouwde Basic-functie Error$.

Voorbeeld:


    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            'Zie onderstaande varianten ...
    End Sub

Een uitzondering maken met de standaardwaarden:


    Catch:
        SF_Exception.Raise()

Een uitzondering maken met een specifieke code:


    Catch:
        SF_Exception.Raise(11)

Om het gebruikelijke bericht te vervangen:


    Catch:
        SF_Exception.Raise(, , "Het is geen goed idee om te delen door nul.")

Een toepassingsfout melden:


    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Er ging iets fout !")

RaiseWarning

Deze methode heeft exact dezelfde syntaxis, argumenten en gedrag als de methode Raise().

Wanneer er echter een waarschuwing wordt gegeven, wordt de uitvoering van de macro niet gestopt.

Deze methode is alleen beschikbaar voor BASIC-scripts.

Syntaxis:


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

Parameters:

Number: De foutcode, als een getal of als een tekenreeks.Standaardwaarde is die van de ingebouwde Basic-functie Err.

Source: De locatie van de fout, als een getal of als een tekenreeks.Standaardwaarde is die van de ingebouwde Basic-functie Erl.

Description: Het bericht dat aan de gebruiker moet worden weergegeven en in de console moet worden gerapporteerd. Standaardwaarde is die van de ingebouwde Basic-functie Error$.

Voorbeeld:


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

Functies voor foutafhandeling