Nápověda LibreOfficeDev 7.6
Služba Exception je sada metod napomáhajících ladění kódu ve skriptech Basicu a Pythonu a zpracování chyb ve skriptech Basicu.
Když ve skriptech Basicu nastane běhová chyba, metody a vlastnosti služby Exception pomáhají identifikovat kontext chyby a umožňují chybu zpracovat.
Služba SF_Exception se podobá objektu VBA Err.
Vlastnost Number chybu identifikuje.
Pomocí metody Raise přerušíte zpracování kódu. Metodou RaiseWarning můžete nečekané chování zachytit, aniž by bylo vykonávání makra přerušeno.
Chyby a upozornění vyvolané službou Exception jsou ukládány do paměti a lze je získat pomocí metody Console.
V konzoli služby Exception se ukládají události, hodnoty proměnných a informace o chybách. Její použití je vhodné v případě, že není snadno přístupné IDE Basicu, například v uživatelem definovaných funkcích Calcu nebo během zpracovávání událostí.
Metodou DebugPrint do konzole přidáte libovolnou relevantní informaci. Položky konzole je možné vypsat do textového souboru nebo zobrazit v dialogovém okně.
Jestliže nastane chyba, makro s aplikací může:
Nahlásit chybu do konzole služby Exception.
Informovat o chybě uživatele pomocí standardní nebo vlastní zprávy.
Volitelně zastavit svůj běh.
Ve skriptech Pythonu se služba Exception používá převážně pro ladění. Metody jako DebugPrint, Console nebo DebugDisplay umožňují ze skriptu v Pythonu rychle vypisovat zprávy, ukládat data do protokolu a otevírat okno s konzolí.
Ne všechny metody a vlastnosti jsou pro skripty Pythonu dostupné, protože jazyk Python již obsahuje pokročilý systém pro zpracování chyb.
Následující příklady ukazují tři odlišné způsoby volání metody Raise. Všechny ostatní metody lze spustit obdobně.
    SF_Exception.Raise(...)
  
    Dim exc : exc = SF_Exception
    exc.Raise(...)
  
    Dim exc : exc = CreateScriptService("Exception")
    exc.Raise(...)
  V níže uvedené části kódu se vytvoří instance služby Exception, zaznamená se zpráva do protokolu a zobrazí se okno Console.
    from scriptforge import CreateScriptService
    exc = CreateScriptService("Exception")
    someVar = 100
    exc.DebugPrint("Value of someVar", someVar)
    exc.Console()
  Následující vlastnosti jsou k dispozici pouze pro skripty v jazyce Basic.
| Název | Pouze pro čtení | Popis | 
|---|---|---|
| Description | ne | Text chybové zprávy. Výchozí hodnotou je "" nebo řetězec obsahující zprávu běhové chyby Basicu. | 
| Number | ne | Kód chyby. Jedná se o číselnou hodnotu nebo text. Výchozí hodnotou je 0 nebo číselná hodnota odpovídající kódu běhové chyby Basicu. | 
| Source | ne | Místo v kódu, kde chyba nastala. Jedná se o číselnou hodnotu nebo text. Výchozí hodnotou je 0 nebo číslo řádku kódu u standardní běhové chyby Basicu. | 
Při vyvolání chyby nebo vymazání služby Exception jsou nastaveny její vlastnosti na výchozí.
| Seznam metod služby Exception | ||
|---|---|---|
Nastaví aktuální stav chyby na výchozí a vymaže vlastnosti služby SF_Exception.
    SF_Exception.Clear()
  Následující příklad ukazuje, jak zachytit výjimku při dělení nulou, jejíž kód je 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()
            ' Při dělení nulou se chyba ignoruje
    End Sub
  Úplný seznam kódu běhových chyb Basicu naleznete v části Ladění programu v Basicu.
Zobrazí zprávy konzole v modálním nebo nemodálním dialogovém okně. V obou případech se zobrazí všechny zprávy z minulosti zaznamenané metodou DebugPrint() nebo uložené jako výsledek výjimky. V nemodálním režimu se automaticky budou přidávat následující záznamy.
Je-li již konzole otevřena jako nemodální, přenese se do popředí.
Modální konzoli může zavřít pouze uživatel. Nemodální může být také zavřena uživatelem, navíc se zavře při ukončení makra.
exc.Console(modal: bool = True)
modal: Určuje, zda je okno s konzolí modální (True) nebo nemodální (False). Výchozí hodnotou je True.
        SF_Exception.Console(Modal := False)
  
    exc.Console(modal = False)
  Vymaže konzoli, případně v ní ponechat volitelný počet posledních zpráv. Pokud je konzole aktivována v nemodálním režimu, obnoví se.
exc.ConsoleClear(keep: int = 0)
keep: Počet posledních zpráv, které se mají ponechat. Výchozí hodnotou je 0.
V následujícím příkladu se konzole vymaže, ponechá se v ní přitom 10 posledních zpráv.
        SF_Exception.ConsoleClear(10)
  
    exc.ConsoleClear(10)
  Vyexportuje obsah konzole do textového souboru. Pokud soubor již existuje a konzole není prázdná, přepíše bez upozornění jeho obsah. V případě úspěšného exportu vrátí True.
exc.ConsoleToFile(filename: str): bool
filename: Název textového souboru, do nějž se má konzole vypsat. Název je zapsán v souladu s aktuální vlastností FileNaming služby SF_FileSystem. Ve výchozím nastavení je povolen jak zápis adresy URL, tak nativní formát operačního systému.
        SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")
  
    exc.ConsoleToFile(r"C:\Documents\myFile.txt")
  Spojí všechny argumentu do jediného lidsky čitelného řetězce a zobrazí jej v okně MsgBox spolu s ikonou Informace a tlačítkem OK.
Výsledný řetězec se rovněž přidá do konzole.
exc.DebugDisplay(arg0: any, [arg1: any, ...])
arg0[, arg1, ...]: Jakýkoliv počet argumentů libovolného typu.
    SF_Exception.DebugDisplay("Current Value", someVar)
  
    exc.DebugDisplay("Current Value", someVar)
  Spojí všechny zadané argumenty do jediného lidsky čitelného řetězce a přidá jej jako nový záznam do konzole.
exc.DebugPrint(arg0: any, [arg1: any, ...])
arg0[, arg1, ...]: Jakýkoliv počet argumentů libovolného typu.
    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
  
    exc.DebugPrint(None, [1, 2, 3], "line1\nline2")
    # None  [1, 2, 3]  line1\nline2
  Zobrazí seznam argumentů v čitelné podobě v konzoli systému. Argumenty jsou odděleny znakem tabulátor (napodobeným mezerami).
Stejný řetězec se přidá do ladicí konzole knihovny ScriptForge.
Pokud je aktivní shell Pythonu (APSO), metoda PythonPrint vypíše obsah do konzole APSO místo do konzole systému.
  exc.PythonPrint(arg0: any, [arg1: any, ...])
  arg0[, arg1, ...]: Jakýkoliv počet argumentů libovolného typu. Maximální délka jednotlivých argumentů činí 1024 znaků.
    exc.PythonPrint(a, Array(1, 2, 3), , "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))
  V Pythonu vypíšete obsah do konzole APSO pomocí příkazu print, do konzole knihovny ScriptForge pak pomocí metody DebugPrint.
Otevře shell Pythonu APSO jako nemodální okno. Skript Pythonu pokračuje po otevření shellu v běhu. V shellu se bude zobrazovat výstup ve skriptu spuštěných příkazů print.
Najednou může být otevřena pouze jediná instance shellu APSO. Je-li proto shell již otevřen, volání této metody nic neprovede.
exc.PythonShell(variables: dict)
variables: Slovník Pythonu s názvy a hodnotami proměnných, které se shellu APSO předají. Ve výchozím nastavení jsou předány všechny lokální proměnné pomocí vestavěné funkce Pythonu locals().
V níže uvedeném příkladu se otevře shell Pythonu APSO a předají se do něj všechny globální a lokální proměnné vzhledem ke kontextu, v němž je skript spuštěn.
    exc.PythonShell({**globals(), **locals()})
  Jakmile je shell APSO otevřen, zobrazí se v něm jakýkoliv následující skriptem vypsaný výstup. Zobrazí se v něm tedy i řetězec vypsaný v následujícím příkladu.
    exc.PythonShell()
    print("Ahoj světe!")
  Vyvolá běhovou chybu. Chybová zpráva se zobrazí uživateli a zaznamená se do konzole. Vykonávání programu se zastaví. Metodu Raise() je možné umístit do běžného skriptu i do specializované procedury na zpracování chyb.
    SF_Exception.Raise([Number As Variant], [Source As Variant], [Description As String])
  Uvedené části kódy mají stejný význam, ukazují alternativní způsoby, jak vyvolat výjimku s kódem 2100.
    SF_Exception.Raise(2100)
  
    SF_Exception.Number = 2100
    SF_Exception.Raise()
  
    SF_Exception.Raise Number := 2100
  Number: Chybový kód jako číslo nebo řetězec. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Err.
Source: Místo vzniku chyby jako číslo nebo řetězec. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Err.
Description: Zpráva zobrazená uživateli a zaznamenaná do konzole. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Error$.
    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            ' Viz možnosti níže...
    End Sub
  Vyvolání výjimky se standardními hodnotami:
    Catch:
        SF_Exception.Raise()
  Vyvolání výjimky se specifickým kódem:
    Catch:
        SF_Exception.Raise(11)
  Nahrazení běžné zprávy:
    Catch:
        SF_Exception.Raise(, , "Dělit nulou není dobrý nápad.")
  Vyvolání chyby aplikace:
    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Něco se pokazilo!")
  Tato metoda má naprosto stejnou syntaxi, argumenty a chování jako metoda Raise().
Rozdílem je, že při vyvolání upozornění se vykonávání makra nezastaví.
    SF_Exception.RaiseWarning([Number As Variant], [Source As Variant], [Description As String])
  
    SF_Exception.RaiseWarning(Source:="Example_Raise()", _
        Description:="Something wrong happened !", _
        Number:="MyAppError")