Tenesta ScriptForge.Exception (SF_Exception)

Innhald

# Tenesta ScriptForge.Exception

Tenesta Exception (unntak) er ei samling av metodar som hjelper til med med feilsøking (debugging) av kode i Basic- og Python-skript og feilhandsaming i Basic-skript.

Når det oppstår ein køyretidsfeil i Basic-skript, hjelper metodane og eigenskapane til Exception-tenesta til å identifisera feilsamanhengen og tillata å handsama han.

- Tenesta SF_Exception liknar på objektet VBA Err.

- Eigenskapen Number identifiserer feilen.

- Bruk metoden Raise for å avbryta handsaminga. Metoden RaiseWarning kan brukast til å fanga opp eit avvik frå reglane utan å bryta av makrokøyringa.

Feil og åtvaringar som oppstår med tenesta Exception vert lagra i minnet og kan hentast fram ved hjelp av metoden Console.

Tenestekonsollen Exception lagrar hendingar, variabelverdiar og opplysningar om feil. Bruk konsollen når BASIC-IDE ikkje er lett tilgjengeleg, for eksempel i Calc user defined functions eller under handsaming av hendingar.

Bruk metoden DebugPrint for å leggja kva relevant informasjon som helst til i konsollen. Konsolloppføringar kan dumpast til ei tekstfil eller visualiserast i eit dialogvindauge.

Når det oppstår ein feil, kan ein programmakro:

1. Rapporter feilen i konsollen Exception

2. Informere brukaren om feilen ved hjelp av ei standardmelding eller ei tilpassa melding

3. Eventuelt stoppa utføringa

Når det vert oppdaga ein feil i eit oppkall til ScriptForge API, vert oppførsla til programmet bestemt av spesifikke eigenskapar:

1. Loggfør feilen i Unntaks-konsollen. Dette vert alltid gjort.

2. Informer brukaren om feilen anten med ei standardmelding eller ei regiontilpassa melding.

   For å tvinga fram ein stillemodus, set:

   exception.ReportScriptErrors = False ' Default = True

3. For ikkje å stoppa køyringa av den gjeldande makroen, set:

   exception.StopWhenError = False ' Default = True

   Før vidare handsaming, er det då fornuftig å utforska verdiane:

   exception.ReturnCode ' Short error description

   exception.ReturnCodeDescription ' Long error description

I Python-skript vert tenesta Exception mest brukt til feilsøkingsføremål. Metodar som DebugPrint, Console og DebugDisplay er nyttige for raskt å skriva ut meldingar, logge data og opna konsollvindauget frå eit Python-skript.

Ikkje alle metodar og eigenskapar er tilgjengelege for Python-skript sidan Python-språket alt har eit omfattande unntakshandsamingssystem.

## Oppkall av tenester

Før du brukar Exception-tenesta må ScriptForge-biblioteket lastast ned eller importerast:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

##### I Basic

Eksempla nedanfor viser tre forskjellige framgangsmåtar for å kalle opp metoden Raise. Alle andre metodar kan utførast på ein liknande måte.

        SF_Exception.Raise(...)

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

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

##### I Python

Kodesnutten nedanfor lagar eit eksemplar av tenesta Exception, loggar ei melding og viser vindauget Console.

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

## Eigenskapar

Eigenskapane som er førte opp nedanfor er berre tilgjengelege for BASIC-skript. Dei er relaterte til feil som oppstår i kva makrosetningar som helst.

Namn | Skriveverna | Beskriving
--- | --- | ---
Description | Nei | Teksten i feilmeldinga. Standardverdien er "" eller ein streng som inneheld Basic-feilmeldinga om køyretid.
Number | Nei | Koden for feilen. Det kan vera ein numerisk verdi eller ein tekst. Standardverdien er 0 eller den talverdien som svarar til koden for Basic køyretidsfeil.
Source | Nei | Staden i koden der feilen oppstod. Det kan vera ein talverdi eller ein tekst. Standardverdien er 0 eller kodelinjenummeret for ein standard Basic køyretidsfeil.

Når du set eller ryddar ein Exception vert eigenskapane nullstilte.

Feilkodane 0-2000 er reserverte for LibreOffice Basic. Brukardefinerte feil må byrja frå høgare verdiar for å unngå kollisjon med framtidige utgåver av LibreOffice Basic.

Eigenskapane som er oppførte nedanfor er tilgjengelege for BASIC- og Python-skript. Dei er berre relaterte til feil som som vert oppdaga av ScriptForge API.

Namn | Skriveverna | Returtype | Skildring
--- | --- | --- | ---
ReportScriptErrors | Nei | Boolsk | Indikerer om skriptfeil skal visast i ein meldingsboks når dei oppstår. Standardverdien er Usann.
ReturnCode | Ja | Streng | Koden som vart returnert av det siste oppkallet til ScriptForge API frå eit brukarskript. Det er strengen med lengde null viss alt køyrde utan feil.
ReturnCodeDescription | Ja | Streng | Skildringa av koden som vart returnert av det siste oppkallet til ScriptForge API frå eit brukarskript. Det er strengen med lengde null viss alt køyrde utan feil.
StopWhenError | Nei | Boolsk | Indikerer om makroen vert stoppa når ScriptForge oppdagar feil i eit brukarskript.

Liste over metodar i tenesta Exception
Clear Console ConsoleClear ConsoleToFile | DebugDisplay DebugPrint PythonPrint | PythonShell Raise RaiseWarning

## Clear

Tilbakestiller gjeldande feilstatus og slettar SF_Exception-eigenskapane.

Denne metoden er tilgjengeleg berre for Basic-skript.

### Syntaks:

        SF_Exception.Clear()

### Eksempel:

Eksempelet nedanfor viser korleis du fangar opp eit unntak for deling med null, der feilkoden 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()
                ' viss divisjon med null, ignorer feilen
        End Sub

Viss du vil ha ei fullstendig liste over feilkoder for Basic køyretid, kan du sjå Debugging a Basic Program.

## Console

Viser konsollmeldingane i eit modalt eller ikkje-modalt dialogvindauge. I begge modusane vert alle tidlegare meldingar utsend av ein DebugPrint()-metode viste, eller som er eit resultat av eit unntak. I ikkje-modal modus vert dei etterfølgjande oppføringane lagde til automatisk.

Viss konsollen alt er ope som ikkje-modal, vert han flytt fremst.

Ein modal konsoll kan berre lukkast av brukaren. Ein ikkje-modal konsoll kan anten lukkast av brukaren eller ved makroavslutning.

### Syntaks:

exc.Console(modal: bool = True)

### Parametrar:

modal: Bestemmer om konsollvindauget er modalt (Sann) eller ikkje-modalt (Usann). Standardverdien er Sann

### Eksempel:

##### I Basic

            SF_Exception.Console(Modal := False)

##### I Python

        exc.Console(modal = False)

## ConsoleClear

Tømmer konsollen og beheld ei valfri mengd av dei siste meldingane. Viss konsollen er slått på i ikkje-modal modus, vert han oppdatert.

### Syntaks:

exc.ConsoleClear(keep: int = 0)

### Parametrar:

keep: Talet på nylege meldingar som skal behaldast. Standardverdien er 0

### Eksempel:

Det neste eksempelet tømmer konsollen men beheld dei 10 siste meldingane.

##### I Basic

            SF_Exception.ConsoleClear(10)

##### I Python

        exc.ConsoleClear(10)

## ConsoleToFile

Eksporterer innhaldet i konsollen til ei tekstfil. Viss fila finst frå før og konsollen ikkje er tom, vert ho overskrive utan varsel. Returnerer Sann viss vellukka.

### Syntaks:

exc.ConsoleToFile(filename: str): bool

### Parametrar:

filnamn: Namnet på tekstfila konsollen skal dumpast inn i. Namnet er uttrykt i samsvar med den gjeldande FileNaming-eigenskapen i tenesta SF_FileSystem. Som standard er både URL-notasjon og formatet brukt av operativsystemet tillatne.

### Eksempel:

##### I Basic

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

##### I Python

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

## DebugDisplay

Slår saman alle argumenta til éin enkelt lesbar streng og viser han i ein MsgBox med eit informasjonsikon og ein OK-knapp.

Den endelege strengen vert også lagt til i konsollen.

### Syntaks:

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

### Parametrar:

arg0[, arg1, ...]: Eit vilkårleg tal på argument av kva type som helst.

### Eksempel:

##### I Basic

        SF_Exception.DebugDisplay("Current Value", someVar)

##### I Python

        exc.DebugDisplay("Current Value", someVar)

## DebugPrint

Set saman alle dei gjevne argumenta til éin enkelt leseleg streng og legg han til som ei ny oppføring i konsollen.

### Syntaks:

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

### Parametrar:

arg0[, arg1, …]: Eit vilkårleg tal på argument av kva type som helst.

### 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 lisa med argument i plattform-konsollen i ei leseleg form. Argumenta vert skilde med eit tabulatorteikn (simulert med mellomrom).

Den same strengen vert lagt til i feilfinningskonsollen for ScriptForges.

Viss Python shell (APSO) er slått på, vert innhaldet i PythonPrint skrive til APSO-konsollen i staden for plattformkonsollen.

Denne metoden er tilgjengeleg berre for Basic-skript.

### Syntaks:

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

### Parametrar:

arg0[, arg1, ...]: Kva tal på argument som helst av vilkårleg type. Maksimal lengd på kvart einskild argument er 1024 teikn.

### Eksempel:

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

I Python brukar du eit print-uttrykk for å skriva til APSO-konsollen eller metoden DebugPrint for å skriva til ScriptForge-konsollen.

## PythonShell

Opnar eit APSO Python-skall som eit ikkje-modalt vindauge. Python-skriptet held fram med å køyra etter at skalet er opna. Utdata frå print-setningar inne i skriptet vert viste i skalet.

Berre éin enkelt førekomst av APSO Python-skalet kan opnast når som helst. Difor, viss eit Python-skal er opna frå før, vil oppkall av denne metoden ikkje ha nokon effekt.

Denne metoden krev at utvidinga APSO (Alternative Script Organizer for Python) er installert. I sin tur krev APSO at LibreOffice Python-scriptramma finst. Viss APSO eller Python manglar, oppstår det ein feil.

### Syntaks:

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

### Parametrar:

variablar: ei Python-ordbok med variabelnamn og verdiar som vert sende vidare til APSO Python-skalet. Som standard vert alle lokale variablar gjevne vidare ved å bruka Python sin innebygde funksjon locals().

bakgrunn: Bakgrunnsfarge for konsollen spesifisert som RGB 24-bits heiltalsverdi. Standardbakgrunnen er som APSO.

forgrunn: Forgrunnsfarge for konsollen spesifisert som RGB 24-bits heiltalsverdi. Standardbakgrunnen er som APSO.

### Eksempel:

Eksempelet nedanfor opnar APSO Python-skallet og sender alle globale og lokale variablar med tanke på samanhengen der skriptet vert køyrd. Konsollen vert vist med kvite teikn på svart bakgrunn.

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

Når APSO Python-skalet er ope, vert alle utdata som følgjer etter og skrivne ut av skriptet viste i skalet. Difor vert strengen som er skrive ut i eksempelet nedanfor vist i Python-skalet.

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

## Raise

Genererer ein køyretidsfeil. Ei feilmelding vert vist til brukaren og rapportert i konsollen. Utføringa er stoppa. Metoden Raise() kan setjast inn i den normale skriptflyten eller i ein dedisert feilhandsamingsrutine.

Denne metoden er tilgjengeleg berre for Basic-skript.

### Syntaks:

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

Dei neste kodesnuttane er likeverdige. Dei viser alternative måtar å gjera unntak på med kode 2100.

        SF_Exception.Raise(2100)

        SF_Exception.Number = 2100
        SF_Exception.Raise()

        SF_Exception.Raise Number := 2100

### Parametrar:

Nummer: Feilkoden, som eit tal eller som ein streng. Standardverdien er den for Err Grunnleggjande innebygd funksjon. I så fall er Nummer valfritt.

Feilkodane 0-2000 er reserverte for LibreOffice Basic. Brukardefinerte feil må byrja frå høgare verdiar for å unngå kollisjon med framtidige utgåver av LibreOffice Basic.

Kjelde: Plasseringa av feilen som eit tal eller som ein streng. Standardverdien er den same som for den innebygde Basic-funksjonen Erl.

Description: Meldinga som skal visast til brukaren og rapporterast i konsollen). Standardverdien er den same som i den innebyggde Basic-funksjonen Error$ (Feil$).

### Eksempel:

        Sub Example_Raise()
            Dim a, b, c
            On Local Error GoTo Catch
            Try:
                a = 10 : b = 0
                c = a / b
                '...
                Exit Sub
            Catch:
                ' Sjå variantar nedanfor …
        End Sub

Slik set du eit unntak med standardverdiar:

        Catch:
            SF_Exception.Raise()

Slik set du eit unntak med ein bestemt kode:

        Catch:
            SF_Exception.Raise(11)

For å byta ut den vanlege meldinga:

        Catch:
            SF_Exception.Raise(, , "Det er ein dårleg ide å dividera med null.")

Slik set du opp ein programfeil:

        Catch:
            SF_Exception.Raise("MyAppError", "Example_Raise()", "Noko har gått gale!")

## RaiseWarning

Denne metode har nøyaktig same syntaks, argument og oppførsel som metoden Raise().

Når ei åtvaring vert sett, vert makroutføringa ikkje stoppa.

Denne metoden er tilgjengeleg berre for Basic-skript.

### Syntaks:

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

### Parametrar:

Nummer: Feilkoden, som eit tal eller som ein streng. Standardverdien er den for Err Grunnleggjande innebygd funksjon. I så fall er Nummer valfritt.

Feilkodane 0-2000 er reserverte for LibreOffice Basic. Brukardefinerte feil må byrja frå høgare verdiar for å unngå kollisjon med framtidige utgåver av LibreOffice Basic.

Kjelde: Plasseringa av feilen som eit tal eller som ein streng. Standardverdien er den same som for den innebygde Basic-funksjonen Erl.

Description: Meldinga som skal visast til brukaren og rapporterast i konsollen). Standardverdien er den same som i den innebyggde Basic-funksjonen Error$ (Feil$).

### Eksempel:

        SF_Exception.RaiseWarning(Source:="Example_Raise()", _
            Description:="Det skjedde noko gale.", _
            Number:="MyAppError")

Liknande emne

Funksjonar for feilhandsaming

Støtt oss!