ScriptForge.Exception-service (SF_Exception)

Inhoud

# service ScriptForge.Exception

De service Exception is een verzameling methodes 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 methodes 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 waardes 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. Methodes 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 methodes en eigenschappen zijn beschikbaar voor Python-scripts, aangezien de Python-taal al een uitgebreid systeem voor het afhandelen van uitzonderingen heeft.

## Service aanroep

Voordat u de Exception-service kunt gebruiken, moet de ScriptForge-bibliotheek worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

##### In BASIC

De volgende voorbeelden laten drie verschillende benaderingen zien om de methode Raise aan te roepen. Alle andere methodes 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.

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 methodes 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(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

### Parameters:

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

achtergrond: Achtergrondkleur van de console, opgegeven als RGB 24 bits integerwaarde. De standaardachtergrond is die van APSO.

voorgrond: Voorgrondkleur van de console, opgegeven als RGB 24 bits integerwaarde. Standaardvoorgrond is die van APSO.

### 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. Console wordt weergegeven met witte tekens op een zwarte achtergrond.

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

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.

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

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:

Getal: De foutcode, als getal of als tekenreeks. De standaardwaarde is die van Fout Ingebouwde basisfunctie, in welk geval Getal is optioneel.

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.

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

        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:

Getal: De foutcode, als getal of als tekenreeks. De standaardwaarde is die van Fout Ingebouwde basisfunctie, in welk geval Getal is optioneel.

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.

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()", _
            Beschrijving:="Er is iets misgegaan!", _
            Getal:="MyAppError")

Verwante onderwerpen

Functies voor foutafhandeling