Vsebina

# Storitev ScriptForge.Exception

Storitev Exception je nabor metod za razhroščevanje kode skriptov Basic in Python ter za ravnanje ob napakah v skriptih Basic.

V primeru napake v skriptih Basic ob izvajanju lastnosti in metode storitve Exception pomagajo identificirati kontekst napake in omogočajo ravnanje z njo.

- Storitev SF_Exception je podobna predmetu VBA Err.

- Lastnost Number identificira napako.

- Uporabite metodo Raise, da prekinete obdelavo. Uporabite metodo RaiseWarning, da ujamete nepravilnost, vendar ne prekinete izvajanja makra.

Napake in opozorila storitve Exception se hranijo v pomnilniku in jih lahko pridobite z metodo Console.

Konzola storitve Exception hrani dogodke, vrednosti spremenljivk in podatke o napakah. Uporabite konzolo, ko IDE Basic ni enostavno dosegljiv, npr. za uporabniško-določene funkcije Calc (UDF) ali pri obdelavi dogodkov.

Uporabite metodo DebugPrint za dodajanje vseh relevantnih podatkov v konzolo. Vnose iz konzole lahko izmečete v besedilno datoteko ali prikažete v pogovornem oknu.

Če pride do napake, lahko makro programa:

1. javi napako v konzoli Exception,

2. obvesti uporabnika o napaki prek standardnega sporočila ali sporočila po meri,

3. po želji ustavi svoje izvajanje.

Če je zaznana napaka v klicu API-ja ScriptForge, je vedenje programa določeno z nekaterimi lastnostmi:

1. zabeleži napako v konzoli Exception, to stori vedno;

2. obvesti uporabnika o napaki prek standardnega ali prevedenega sporočila.

   Za vsilitev tihega načina nastavite:

   exception.ReportScriptErrors = False ' Default = True

3. Če ne želite ustaviti izvajanja trenutnega makra, nastavite:

   exception.StopWhenError = False ' Default = True

   Nato je smiselno, da pred nadaljnjo obdelavo raziščete vrednosti:

   exception.ReturnCode ' Short error description

   exception.ReturnCodeDescription ' Long error description

V skriptih Python se storitev Exception večinoma uporablja za razhroščevanje. Metode, kot so DebugPrint, Console in DebugDisplay, so uporabne za hitro izpisovanje sporočil, beleženje podatkov in odpiranje okna konzole iz skripta Python.

Za skripte Python vse metode in lastnosti niso na voljo, saj ima jezik Python zelo razdelan sistem obravnave izjem.

## Priklic storitve

Pred uporabo storitve Exception je potrebno naložiti ali uvoziti knjižnico ScriptForge:

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Za skripte Python mora biti opravljen uvoz iz modula scriptforge:
from scriptforge import CreateScriptService

##### V Basicu

Naslednji primeri prikazujejo tri različne pristope h klicu metode Raise. Vse druge metode je mogoče izvesti na podoben način.

        SF_Exception.Raise(...)

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

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

##### V Pythonu

Spodnji odlomek kode ustvari instanco storitve Exception, zabeleži sporočilo in prikaže okno Console.

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

## Lastnosti

Spodaj naštete lastnosti so na voljo le za skripte Basic. Povezane so z napakami, ki se pojavijo v poljubnem ukazu makra.

Ime | Samo za branje | Opis
--- | --- | ---
Description | Ne | Besedilo sporočila o napaki. Privzeta vrednost je "" ali niz, ki vsebuje sporočilo o napaki Basic med izvajanjem.
Number | Ne | Koda napake. Lahko je številska vrednost ali besedilo. Privzeta vrednost je 0 ali številska vrednost, ki ustreza kodi napake Basic med izvajanjem.
Source | Ne | Mesto v kodi, kjer je prišlo do napake. Lahko je številska vrednost ali besedilo. Privzeta vrednost je 0 ali številka vrstice kode za standardno napako med izvajanjem Basica.

Priklic ali čiščenje izjeme Exception ponastavi njene lastnosti.

Kode napake med 0 in 2000 so rezervirane za LibreOffice Basic. Uporabniško določene napake se lahko začnejo z višjimi vrednostmi, da se preprečijo spori z bodočim razvojem LibreOffice Basic.

Spodaj naštete lastnosti so na voljo za skripte Basic in Python. Povezane so z napakami, ki jih zazna samo API ScriptForge.

Ime | Samo za branje | Vrsta vrnjene vrednosti | Opis
--- | --- | --- | ---
ReportScriptErrors | Ne | Logična vrednost (Boolean) | Nakazuje, ali so napake skripta prikazane v sporočilu, ko se dogodijo. Privzeta vrednost je False.
ReturnCode | Da | Niz (String) | Koda, ki jo vrne zadnji klic API-ja ScriptForge iz uporabniškega skripta. To je niz ničelne dolžine, če je vse potekalo brez napake.
ReturnCodeDescription | Da | Niz (String) | Opis kode, ki jo vrne zadnji klic ScriptForge API iz uporabniškega skripta. To je niz ničelne dolžine, če je vse potekalo brez napake.
StopWhenError | Ne | Logična vrednost (Boolean) | Pokaže, ali je makro ustavljen, ko ScriptForge zazna napako uporabniškega skripta.

Seznam metod v storitvi Exception
Clear Console ConsoleClear ConsoleToFile | DebugDisplay DebugPrint PythonPrint | PythonShell Raise RaiseWarning

## Clear

Ponastavi trenutno stanje napake in počisti lastnosti SF_Exception.

Ta metoda je na voljo samo za skripte Basic.

### Skladnja:

        SF_Exception.Clear()

### Primer:

Naslednji primer prikazuje, kako ujeti izjemo deljenja z nič, za katero je koda napake enaka 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()
                ' Če gre za deljenje z nič, prezri napako
        End Sub

Celoten seznam kod napake med izvajanjem programov v Basicu si oglejte v sestavku Razhroščevanje programa Basic.

## Console

Prikaže sporočila konzole v modalnem ali nemodalnem pogovornem oknu. V obeh načinih se prikažejo pretekla sporočila, izdana z metodo DebugPrint() ali kot rezultat izjem. V nemodalnem načinu so naknadni vnosi dodani samodejno.

Če je konzola že odprta, ko ni modalna, se postavi v ospredje.

Modalno konzolo lahko zapre samo uporabnik. Nemodalno konzolo lahko zapre uporabnik ali pa se zapre ob zaključku izvajanja makra.

### Skladnja:

exc.Console(modal: bool = True)

### Parametri:

modal: določa, ali je konzola modalna (True) ali ne (False). Privzeta vrednost je True.

### Primer:

##### V Basicu

            SF_Exception.Console(Modal := False)

##### V Pythonu

        exc.Console(modal = False)

## ConsoleClear

Počisti konzolo in ohrani (neobvezen parameter) navedeno število nedavnih sporočil. Če je konzola aktivirana v nemodalnem načinu, se osveži.

### Skladnja:

exc.ConsoleClear(keep: int = 0)

### Parametri:

keep: število nedavnih sporočil, ki jih želite ohraniti. Privzeta vrednost je 0.

### Primer:

Naslednji primer počisti konzolo in obdrži 10 nedavnih sporočil.

##### V Basicu

            SF_Exception.ConsoleClear(10)

##### V Pythonu

        exc.ConsoleClear(10)

## ConsoleToFile

Izvozi vsebino konzole v besedilno datoteko. Če datoteka že obstaja in konzola ni prazna, bo prepisana brez opozorila. Vrne True, če uspe.

### Skladnja:

exc.ConsoleToFile(filename: str): bool

### Parametri:

filename: ime besedilne datoteke, v katere naj bo izmetana konzola. Ime je izraženo v skladu s trenutno lastnostjo FileNaming storitve SF_FileSystem. Privzeto sta dovoljeni notacija URL in domoroden zapis operacijskega sistema.

### Primer:

##### V Basicu

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

##### V Pythonu

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

## DebugDisplay

Zbere vse podane argumente v en sam uporabniku prijazen niz ter ga prikaže v oknu MsgBox z ikono Informacija in gumbom V redu.

Zadnji niz se prav tako doda v konzolo.

### Skladnja:

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

### Parametri:

arg0[, arg1, ...]: poljubno število argumentov poljubne vrste.

### Primer:

##### V Basicu

        SF_Exception.DebugDisplay("Current Value", someVar)

##### V Pythonu

        exc.DebugDisplay("Current Value", someVar)

## DebugPrint

Zbere vse podane argumente v en sam uporabniku prijazen niz ter doda nov vnos v konzolo.

### Skladnja:

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

### Parametri:

arg0[, arg1, ...]: poljubno število argumentov poljubne vrste.

### Primer:

##### V Basicu

        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

##### V Pythonu

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

## PythonPrint

Prikaže seznam argumentov v berljivi obliki v konzoli platforme oz. operacijskega sistema. Argumenti so ločeni s tabulatorskim znakom (simuliranih s presledki).

Isti niz se prav tako doda v konzolo razhroščevanja ScriptForge.

Če je lupina Python (APSO) dejavna, se vsebina PythonPrint izpiše v konzoli APSO namesto v konzoli platforme.

Ta metoda je na voljo samo za skripte Basic.

### Skladnja:

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

### Parametri:

arg0[, arg1, ...]: poljubno število argumentov poljubne vrste. Največja dolžina vsakega posameznega argumenta je 1024.

### Primer:

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

V Pythonu uporabite ukaz print za izpis v konzolo APSO ali uporabite metodo DebugPrint za izpis v konzolo ScriptForge.

## PythonShell

Odpre lupino Python APSO kot nemodalno okno. Po odprtju lupine teče skript Python naprej. Izhod ukazov print iz skripta je prikazan v lupini.

V danem trenutku je možno odpreti le eno instanco lupine Python APSO. Če je lupina Python že odprta, klic te metode nima učinka.

Ta metoda zahteva namestitev razširitve APSO (Alternative Python Script Organizer). APSO zahteva prisotnost ogrodja za skriptanje LibreOffice Python. Če APSO ali Python nista nameščena, javi napako.

### Skladnja:

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

### Parametri:

variables: slovar Python z imeni in vrednostmi spremenljivk, ki bo podan naprej lupini Python APSO. Vse krajevne spremenljivke so privzeto podane naprej z vgrajeno funkcijo Python locals().

background: barva ozadja konzole, kot jo določa RGB 24-bitna celoštevilska vrednost. Privzeto ozadje je enako kot pri APSO.

foreground: barva ospredja konzole, kot jo določa RGB 24-bitna celoštevilska vrednost. Privzeto ospredje je enako kot pri APSO.

### Primer:

Spodnji primer lupine Python APSO poda naprej vse globalne in krajevne spremenljivke glede na kontekst, v katerem se skript izvaja. Konzola je prikazana z belimi znaki na črnem ozadju.

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

Če je lupina Python APSO odprta, je vsak nadaljnji izhod, izpisan s skriptom, prikazan v lupini. Zato se niz, izpisan s spodnjim primerom, prikaže v lupini Python.

        s = CreateScriptService('Basic')
        RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
        exc.PythonShell(background=RED, foreground=BLUE)
        print("Žive naj vsi narodi!")

## Raise

Povzroči napako med izvajanjem. Sporočilo o napaki je prikazano uporabniku in sporočeno v konzoli. Izvajanje se ustavi. Metoda Raise() je lahko postavljena v navaden tok skripta ali v posebno proceduro za ravnanje ob napakah.

Ta metoda je na voljo samo za skripte Basic.

### Skladnja:

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

Izseki kode, predstavljeni v nadaljevanju, so ekvivalentni. Prikazujejo različne načine za priklic izjeme s kodo 2100.

        SF_Exception.Raise(2100)

        SF_Exception.Number = 2100
        SF_Exception.Raise()

        SF_Exception.Raise Number := 2100

### Parametri:

Number: koda napake, podana kot število ali kot niz. Privzeta vrednost je vrednost vgrajene funkcije Basic Err, pri čemer je Number neobvezen.

Kode napake med 0 in 2000 so rezervirane za LibreOffice Basic. Uporabniško določene napake se lahko začnejo z višjimi vrednostmi, da se preprečijo spori z bodočim razvojem LibreOffice Basic.

Source: mesto napake, podano kot število ali kot niz. Privzeta vrednost je vrednost vgrajene funkcije Basic Erl.

Description: sporočilo, ki bo prikazano uporabniku in sporočeno v konzoli. Privzeta vrednost je vrednost vgrajene funkcije Basic Error$.

### Primer:

        Sub Example_Raise()
            Dim a, b, c
            On Local Error GoTo Catch
            Try:
                a = 10 : b = 0
                c = a / b
                '...
                Exit Sub
            Catch:
                'Glejte spodnje inačice ...
        End Sub

Če želite priklicati izjemo s standardnimi vrednostmi:

        Catch:
            SF_Exception.Raise()

Če želite priklicati izjemo z določeno kodo:

        Catch:
            SF_Exception.Raise(11)

Če želite zamenjati običajno sporočilo:

        Catch:
            SF_Exception.Raise(, , "Ni pametno deliti z nič.")

Za javljanje napake programa:

        Catch:
            SF_Exception.Raise("MyAppError", "Example_Raise()", "Nekaj je šlo narobe!")

## RaiseWarning

Ta metoda ima povsem enako skladnjo, argumente in vedenje kot metoda Raise().

Če je izdano opozorilo, se izvajanje makra ne ustavi.

Ta metoda je na voljo samo za skripte Basic.

### Skladnja:

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

### Parametri:

Number: koda napake, podana kot število ali kot niz. Privzeta vrednost je vrednost vgrajene funkcije Basic Err, pri čemer je Number neobvezen.

Kode napake med 0 in 2000 so rezervirane za LibreOffice Basic. Uporabniško določene napake se lahko začnejo z višjimi vrednostmi, da se preprečijo spori z bodočim razvojem LibreOffice Basic.

Source: mesto napake, podano kot število ali kot niz. Privzeta vrednost je vrednost vgrajene funkcije Basic Erl.

Description: sporočilo, ki bo prikazano uporabniku in sporočeno v konzoli. Privzeta vrednost je vrednost vgrajene funkcije Basic Error$.

### Primer:

        SF_Exception.RaiseWarning(Source:="Example_Raise()", _
            Description:="Nekaj je šlo narobe!", _
            Number:="MyAppError")

Podobne teme

Funkcije za ravnanje z napakami

Podprite nas!