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.

tip

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:

  1. Rapporteer de fout in de console Exception

  2. Informeer de gebruiker over de fout met behulp van een standaardbericht of een aangepast bericht

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

note

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.


tip

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


note

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.

note

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
  
tip

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 Python shell (APSO) console. Argumenten worden gescheiden door een TAB-teken (gesimuleerd door spaties).

Dezelfde tekenreeks wordt toegevoegd aan de ScriptForge-foutopsporingsconsole.

note

Deze methode is alleen beschikbaar voor BASIC-scripts.


Syntaxis:


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

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.


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))
  
note

Gebruik in python gewoon de ingebouwde print()-instructie.


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.

warning

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.

note

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.

note

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")
  

Help ons, alstublieft!