ScriptForge.Exception-tjenesten (SF_Exception)

Indhold

# Tjenesten ScriptForge.Exception (Undtagelse)

Tjenesten Exception (undtagelse) er en samling af metoder, der hjælper med at debugge koder i Basic- og Python-sceripts og med håndtering af fejl i Basic-scripts.

I Basic-scripts hjælper tjenesten Exception (undtagelse) metoderne og egenskaberne med at identificere fejlens sammenhæng og tillader håndtering af den, når der forekommer en kørselsfejl.

- Tjenesten SF_Exception (SF-undtagelse) ligner objektet VBA Err.

- Egenskaben Number identificerer fejlen.

- Brug metoden Raise (hæv) for at afbryde behandlingen. Metoden RaiseWarning (hejs advarselsflag) kan bruges til at fange en anomali uden at afbryde makro-udførelsen.

Fejl og advarsel, der er markeret af tjenesten Exception (undtagelse) gemmes i hukommelsen og kan hentes med metoden Console (konsol).

Tjenestekonsolen Exception (undtagelse) gemmer begivenheder, variable værdier og oplysninger om fejl. Brug konsollen, når BASIC-IDE er er let tilgængelig, for eksempel i Calc user defined functions ((UDF) brugerdefinerede funktioner i Calc) eller under behandlingen af hændelser.

Brug metoden DebugPrint (Fejlsøg_udskrift) for at tilføje relevant information til konsollen. Konsolindførsler kan tilføje enhver relevant information til konsollen. Konsolindførsler kan dumpes til en tekstfil eller visualiseres i et dialogvindue.

Når der forekommer en fejl, kan en programmakro:

1. Rapportere fejlen i konsollen Exception (Undtagelse)

2. Informer brugeren om fejlen med enten en standard- eller en tilpasset besked

3. Valgfrit stoppe dens udførelse

Når en fejl konstateres i et kald til ScriptForge API, bestemmes programmets opførsel af specifikke egenskaber:

1. Logfør fejlen i Exception-konsollen. Dette bliver altid gjort.

2. Informér brugeren om fejlen med enten en standardfejlmelding eller en oversat melding.

   For at gennemtvinge en stilletilstand, angiv:

   exception.ReportScriptErrors = False ' Default = True

3. For ikke at stoppe kørslen af den aktuelle makro, angiv:

   exception.StopWhenError = False ' Default = True

   Før videre processering er det fornuftigt at undersøge værdierne af:

   exception.ReturnCode ' Short error description

   exception.ReturnCodeDescription ' Long error description

I Python-scripts bruges tjenesten Exception (undtagelse) mest til fejlsøgningsformål. Metoder som DebugPrint (fejlsøg_udskrift), Console (konsol) og DebugDisplay (fejlsøg_visning) er nyttige til hurtigt at udskrive beskeder, logge data og åbne konsolvinduet fra inde fra et Python-script.

Ikke alle metoder og egenskaber er tilgængelige for Python-scripts, eftersom sproget Python allerede har et omfattende undtagelses-håndteringssystem.

## Kald af tjeneste

Før du bruger Exception-tjenesten skal ScriptForge-biblioteket være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

##### I Basic

De følgende eksempler viser tre forskellige tilgange til at kalde metoden Raise (Sæt flag). Alle andre metoder kan udføres på en lignende måde.

        SF_Exception.Raise(...)

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

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

##### I Python

Kodestumpen herunder opretter et eksemplar af tjenesten Exception (undtagelse), loggger en besked og viser vinduet Console (konsol).

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

## Egenskaber

Egenskaberne opført nedenfor er kun tilgængelige for Basic-scripts. De er relaterede til fejl, som opstår i makrokommandoer.

Navn | Skrivebeskyttet | Beskrivelse
--- | --- | ---
Description | Nej | Fejlmeddelelsens tekst Standardværdien er "" eller en streng, der indeholder Basic-udførselsesmiljøet fejlmeddelelse.
Number | Nej | Fejlens kode. Det kan være en numerisk værdi eller en tekst. Standardværdien er 0 eller den numeriske værdi, der svarer til Basic-afviklingsmiljøets kode.
Source | Nej | Placeringen i koden, hvor fejlen forekom. Det kan være en numerisk værdi eller en tekst. Standardværdien er 0 eller kodelinjenummeret for Basics afviklingsmiljøets fejl.

At sætte eller rydde et Exception- (Undtagelses-)flag nulstiller dens egenskaber.

Fejlkode-området 0-2000 er reserveret til LibreOffice Basic. Brugerdefinerede fejl kan begynde med højere værdier, for at forebygge sammenstød med kommende LibreOffice Basic udvikling.

Egenskaberne opført nedenfor tilgængelige for Basic- og Python-scripts. De er kun relaterede til fejl konstateret af ScriptForge API.

Navn | Skrivebeskyttet (Readonly) | Returtype | Beskrivelse
--- | --- | --- | ---
ReportScriptErrors | Nej | Boolsk | Angiver om scriptfejl skal vises i en dialogboks, når de opstår. Standardværdien er False (falsk).
ReturnCode | Ja | Streng | Koden returneret af det sidste kald til ScriptForge API fra et brugerscript. Det er en tom streng, "", hvis alt kørte uden fejl.
ReturnCodeDescription | Ja | Streng | Beskrivelsen af koden, som blev returneret af det sidste kald til ScriptForge API fra et brugerscript. Det er en tom streng, "", hvis alt kørte uden fejl.
StopWhenError | Nej | Boolsk | Angiver om makroen stoppes, når ScriptForge konstaterer en fejl i et brugerscript.

Linste over metoder i tjenesten Exception (Undtagelse)
Clear Console ConsoleClear ConsoleToFile | DebugDisplay DebugPrint PythonPrint | PythonShell Raise RaiseWarning

## Clear

Nulstiller den aktuelle fejlstatus og rydder egenskaberne i SF_Exception (SF_Undtagelse)

Denne metode er kun tilgængelig for Basic-scripts.

### Syntaks:

        SF_Exception.Clear()

### Eksempel:

Det følgende eksempel viser, hvordan man opfanger en undtagelse ved division-med-nul, hvis fejlkode er 11.

        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()
                'Ved division-med-nul, ignorerer du fejlen
        End Sub

Se en komplet liste over Basic-afviklingsmiljøets koder i Debugging (Aflusning) af et Basic-program.

## Console

Vis konsolbeskederne i en modal eller ikke-modal dialog. I begge tilstande vises alle tidligere beskeder, der er udsendt af metoden DebugPrint() (AflusningsPrint()) eller af en undtagelse. I ikke-modal tilstand, tilføjes efterfølgende indførsler automatisk.

Hvis konsollen allerede er åben som non-modal, sættes den forrest.

En modal konsol kan udelukkende lukkes af brugeren. En ikke-modal konsol kan lukkes enten af brugeren eller efter en makroafbrydelse.

### Syntaks:

exc.Console(modal: bool = True)

### Parametre:

modal: Bestemmer, om konsolvinduet er modalt (True (sand)) eller ikke-modalt (False (falsk)). Standardværdien er (True (sand).

### Eksempel:

##### I Basic

            SF_Exception.Console(Modal := False)

##### I Python

        exc.Console(modal = False)

## ConsoleClear

Rydder konsollen, men beholder et valgfrit antal seneste meddelelser. Hvis konsollen aktiveres i ikke-modal tilstand, genopfriskes den.

### Syntaks:

exc.ConsoleClear(keep: int = 0)

### Parametre:

bevar: Antallet af nylige beskeder, der skal bevares. Standarrdværdien er 0.

### Eksempel:

Det følgende eksempel rydder konsollen og beholder de 10 seneste meddelelser.

##### I Basic

            SF_Exception.ConsoleClear(10)

##### I Python

        exc.ConsoleClear(10)

## ConsoleToFile

Eksporterer konsollens indhold til en tekstfil. Hvis filen eksisterer og konsollen ikke er tom, overskrives filen uden varsel. Returnerer True (Sand), hvis funktionen lykkes.

### Syntaks:

exc.ConsoleToFile(filename: str): bool

### Parametre:

filenavn: Navnet på tekstfilen, som konsollen skal dumpes til. Navet udtrykkes i overensstemmelse med den aktuelle FileNaming (filnavngivelse) i tjenesten SF_FileSystem (SF_Filsystem). Som standard tillades både URL-notation og operativsystemets medfødte format.

### Eksempel:

##### I Basic

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

##### I Python

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

## DebugDisplay

Sammenkæder alle argumenter til en simpel menneske-læselig streng og viser den i et MsgBox (beskedfelt) med et informationsikon og en OK-knap.

Den endelige streng tilføjes også til konsollen.

### Syntaks:

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

### Parametre:

arg0[, arg1, ...]: Et vilkårligt antal argumenter af en vilkårlig type.

### Eksempel:

##### I Basic

        SF_Exception.DebugDisplay("Current Value", someVar)

##### I Python

        exc.DebugDisplay("Current Value", someVar)

## DebugPrint

Samler alle de givne argumenter til en enkelt streng, der er læselig for mennesker, og tilføjer den som en indførsel i konsollen.

### Syntaks:

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

### Parametre:

arg0[, arg1, ...]: Et vilkårligt antal argumenter af en vilkårlig type.

### Eksempel:

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

##### I Python

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

## PythonPrint

Viser listen af argumenter i en læsbar form på platformskonsollen. Argumenter bliver adskilt med et TAB-tegn (simuleret med mellemrum).

Den samme streng tilføjes til ScriptForges fejlfindingskonsol.

Hvis Python-skal (APSO) er aktiv, bliver PythonPrint-indhold skrevet til APSO-konsollen i stedet for til platformskonsollen.

Denne metode er kun tilgængelig for Basic-scripts.

### Syntaks:

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

### Parametre:

arg0[, arg1, ...]: Ethvert antal argumenter af vilkårlig type. Den maksimale længde på hvert individuelle argument er 1024 tegn.

### Eksempel:

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

I Python, brug en print-kommando for at skrive til APSO-konsollen eller brug metoden DebugPrint for at skrive til ScriptForge-konsollen.

## PythonShell

Åbner en APSO Python-skal som et ikke-modalt vindue. Et Python-script bliver kørende efter at skallen er åbnet. Uddata fra print (udskrivnings)-udtryk i scriptet vises i skallen.

Der kan kun åbnes et enkelt eksemplar af APSO Python-skallen på et givet tidspunkt. Derfor har det ingen at kalde denne metode, hvis er allerede er åbent en Python-skal.

Denne metode kræver installation af APSO (Alternative Python Script Organizer)-udvidelsen. APSOkræver på sin side tilstedeværelse af LibreOffice Python scriptrammen. Hvis APSO eller Python mangler, sker der en fejl.

### Syntaks:

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

### Parametre:

variable: en Python-ordbog med variabelnavne og værdier, der videregives til APSO Python-skallen. Som standard videregives alle lokale variable med Pythons indbyggede funktion locals().

background: Baggrundsfarve for konsollen specificeret som RGB 24-bits heltalsværdi. Standardbaggrund er som APSO.

foreground: Forgrundsfarve for konsollen specificeret som RGB 24-bits heltalsværdi. Standardforgrund er som APSO.

### Eksempel:

Eksemplet nedenfor åbner APSO Python-skallen og sender alle globale og lokale variable ud fra konteksten, hvor scriptet kører. Konsollen vises med hvide tegn på en sort baggrund.

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

Når APSO Python-skallen er åben, vises alle efterfølgende uddata, der udskrives af scriptet, i skallen. Derfor bliver strengen, der udskrives i eksemplet herunder, vist i Python-skallen.

        s = CreateScriptService('Basic')
        RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
        exc.PythonShell(background=RED, foreground=BLUE)
        print("Hallo verden!")

## Raise

Genererer en kørselsfejl. Brugeren ser en fejlmeddelelse, der også rapporteres i konsollen. Udførelsen stoppes. MetodenRaise() (Sæt flag()) kan placeres inden i den almindelige skriptstrøm eller i en dedikeret fejlhåndterings-rutine.

Denne metode er kun tilgængelig for Basic-scripts.

### Syntaks:

        SF_Exception.Raise(Number := Err, [Source := Erl], [Description := Error$])

De næste kodestumper er er ligeværdige. De viser alternative måder at sætte et flag på med kode 2100.

        SF_Exception.Raise(2100)

        SF_Exception.Number = 2100
        SF_Exception.Raise()

        SF_Exception.Raise Number := 2100

### Parametre:

Number: Fejlkoden, som et tal eller som en streng. Standardværdien er den fra den indbyggede Basic-funktion Err, i hvilket tilfælde Number er valgfri.

Fejlkode-området 0-2000 er reserveret til LibreOffice Basic. Brugerdefinerede fejl kan begynde med højere værdier, for at forebygge sammenstød med kommende LibreOffice Basic udvikling.

Source (Kilde): Fejlens placering som et tal eller som en streng. Standardværdi er den samme som i den indbyggede Basic-funktion Erl (Fejl-linje).

Description (Beskrivelse): Den besked, der skal vises brugeren og rapporteres i konsollen). Standardværdi er den samme som i den indbyggede Basic-funktion Error$ (Fejl$).

### Eksempel:

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

For sætte en undtagelse med standardværdier:

        Catch:
            SF_Exception.Raise()

For at sætte et undtagelsesflag med en specifik kode:

        Catch:
            SF_Exception.Raise(11)

For at erstatte den sædvanlige besked:

        Catch:
            SF_Exception.Raise(, , "Det er ikke en god ide at dividere med nul.")

For at sætte et programfejls-flag:

        Catch:
            SF_Exception.Raise("MyAppError", "Example_Raise()", "Noget er gået galt!")

## RaiseWarning

Denne metode har nøjagtig samme synks, argumenter og adfærd som metoden Raise() (Sæt flag()).

Når der imidlertid sættes et advarselsflag, stoppes makroudførelsen ikke.

Denne metode er kun tilgængelig for Basic-scripts.

### Syntaks:

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

### Parametre:

Number: Fejlkoden, som et tal eller som en streng. Standardværdien er den fra den indbyggede Basic-funktion Err, i hvilket tilfælde Number er valgfri.

Fejlkode-området 0-2000 er reserveret til LibreOffice Basic. Brugerdefinerede fejl kan begynde med højere værdier, for at forebygge sammenstød med kommende LibreOffice Basic udvikling.

Source (Kilde): Fejlens placering som et tal eller som en streng. Standardværdi er den samme som i den indbyggede Basic-funktion Erl (Fejl-linje).

Description (Beskrivelse): Den besked, der skal vises brugeren og rapporteres i konsollen). Standardværdi er den samme som i den indbyggede Basic-funktion Error$ (Fejl$).

### Eksempel:

        SF_Exception.RaiseWarning(Source:="Example_Raise()", _
            Description:="Noget gik galt!", _
            Number:="MyAppError")

Relaterede emner

Fejlhåndterings-funktioner

Støt os venligst!