Best Practices: Error Handling in Lotus Script: Einleitung

[Semeaphoros]

An verschiedenen Stellen haben wir unterdessen über das Error-Handling geschrieben und verschiedentlich versprochen, dass wir das zum selbständigen Thema erheben wollen. Ich möchte damit hier jetzt anfangen. Folgendes Vorgehen habe ich mir vorgestellt (wobei die Diskussion diesen Weg bestimmt erweitern wird):

Ich werde im nächsten Posting mal zuerst einen generellen Ueberblick über Runtime-Errors in LotusScript machen, in den dann folgenden Postings stelle ich dann die für das Error-Handling relevanten LotusScript Statements vorstellen. Daraufhin möchte ich die Diskussion in der Form eröffnen, dass einzelne von Euch ihre eigenen Taktiken für das Error-Handling vorstellen. Bernhard hat kürzlich schon mal ein ganz grobes Grundgerüst skizziert, wie man das angehen kann. Gleichzeitig werden dabei auch die Haken und Ecken des Error-Handlings auftauchen, und es wird hoffentlich an manchen Orten zum Ueberdenken des Error-Handling-Ansatzes führen, tatsächlich ist es eines der Gebiete, die mehr als verträglich vernachlässigt wird.

Also, gleich gehts los ......  


PS: Ich will auch endlich meinen eigenen Thread haben ....  

[Semeaphoros]

Eigentlich gibt es in einer LS-Applikation 3 Sorten von Fehlern, die während der Laufzeit auftreten können:

1. Fehler, welche von LotusScript entdeckt und mit einer Fehlermeldung versehen werden. Wenn man gegen solche Fehler nichts unternimmt, bekommt der Benutzer eine Fehlermeldung und das Script bricht ab. Beispiel:

Code

Resultat = Var1 / 0

erzeugt einen Fehler, weil die Division durch 0 nicht erlaubt ist.

2. Fehlerzustände, die LotusScript nicht eindeutig als solche erkennen kann, auf die das Programm dann entweder selber reagieren muss, oder es führt dann später im Code zu einer entsprechenden Fehlfunktion des Programmes, weil die Umstände nicht so waren wie erwartet. Beispiel:

Code

Dim db As NotesDatabase
Call db.Open( "HongKong", "sales.nsf"

Wenn auf dem Server "HonKong" die Datenbank "sales.nsf" nicht existiert, passiert hier mal gar nichts. Erst wenn ich zum Beispiel mit db.GetDociumentById(..), erhalte ich die Fehlermeldung, dass die Datenbank nicht offen ist.

3. Dann gibt es natürlich auch noch die logischen Fehler. Das Programm läuft zwar korrekt ab, erzeugt weder Fehlermeldungen noch werden "illegale Zustände" wie unter 2. erzeugt, aber trotzdem ist das Ergebnis nicht das, was man erwartet. Entweder stimmt die Applikationslogik nicht, oder das Programm ist nicht nach den Spezifikationen umgesetzt worden. Natürlich können wir hier nicht über diese Probleme reden, da diese ganz individuell angegangen werden können. Was wir hier diskutieren können, sind Taktiken, die man anwenden kann, um diese Probleme einzugrenzen und zu lösen.

[Semeaphoros]

Die oben aufgeführten einzelnen Fehlerkategorien erfordern natürlich unterschiedliche Ansätze, um sie zu "behandeln":

1. Von LotusScript erkannte und behandelte Fehler
Da in diesem Fall ein Abbruch des Programmes erfolgt, ist dies eigenlich für den Anwender eine Katastrophensituation, die man wenn immer möglich vermeiden sollte. LotusScript stellt dafür eine ganze Reihe von Statements zur Verfügung, die einem ermöglichen, die "Situation" zu retten. Im Vordergrund stett das On Error Statement. Diese Fehlerbehandlungs-Mechanismen werden in den nächsten Postings im einzelnen noch vorgestellt.

2. Fehlersituationen, die von LotusScript nicht mit einem "Fehler belohnt" werden
Hier gibt es verschiedene Strategien:
A Gar nichts machen und warten, bis irgendwann einmal später die Situation 1. eintrifft und ein Fehler generiert wird, der abgehandelt werden kann.
B In Abhängigkeit von der Situation versuchen, festzustellen, ob das Statement den gewünschten Erfolg gebracht hat. Im Fall von NotesDatabase.Open gibt es da verschiedene Varianten:
Diese Methode hat einen Rückgabewert: True, wenn die Datenbank geöffnet werden konnte, andernfalls False, wir können also den Rückgabewert auswerten:

Code

Dim db As NotesDatabase
If Not db.Open( "HongKong", "sales.nsf" Then
   Messagebox "Die Datenbank konnte nicht geöffnet werden"
Else
   ........
End If

Alternativ kann die Eigenschaft IsOpen abgefragt werden:

Code

Dim db As NotesDatabase
Call db.Open( "HongKong", "sales.nsf" 
If Not db.IsOpen Then
   Messagebox "Die Datenbank konnte nicht geöffnet werden"
Else
   ........
End If

Die Designer-Hilfe ist dabei zu Rate zu ziehen, bei jedem Befehl, bei jeder Methode und Funktion ist jeweils angegeben, was passiert, wenn nicht das erwartete Resultat erreicht wird. Insbesondere ist zu beachten, dass es grundsätzlich keine Systematik vorhanden ist, wann Methode 1 mit der Fehlermeldung und wann Methode 2 über einen Status-Returnwert oder eine Status-Abfrage oder ähnliches zur Anwendung gelangen muss.

[Semeaphoros]

Das On Error Statement verändert das Verhalten von LotusScript. Sobald dieses Statement ausgeführt wurde, wird keine Fehlermeldung generiert, sondern eine vom Programmierer definierte Aktion ausgeführt.

1. On Error ohne Fehlernummer
Diese Variante von On Error kann in 3 verschiedenen Formen erscheinen:

a. On Error Goto Sprungadresse
In diesem Falle wird der Code ausgeführt, der hinter der Sprungadresse (Label) aufgeführt wird. Dieser Code muss mit einer Form von Resume abgeschlossen werden, damit LotusScript weiss, dass der Fehler jetzt behandelt ist. (Das besagt nciht zwingend, dass der Fehler dadurch behoben oder beseitigt wurde!).
Beispiel:

Code

Sub Demo
On Error Goto ErrHandler
 ...... hier steht der Programmcode, bei einem Fehler wird statt einer Fehlermeldung
        der unten aufgeführte Code ausgeführt
.....
Exit Sub
ErrHandler:
  Print "Es ist ein Fehler aufgetreten"   ' Hey, hier sollte sinnvoller Code stehen :-)
Resume

b. On Error Goto 0
Mit diesem Statement wird eine besondere Fehlerbehandlungsroutine wieder zurückgesetzt. Es hängt jetzt davon ab, ob meherere On Error-Statements definiert waren oder nicht. Dieses Statement setzt zurück auf den Zustand, der vor dem zuletzt ausgeführten On Error Statement existierte. Allenfalls wird dadurch wieder das LotusScript Standardverfahren hergestellt. Auch wenn On Error Goto 0 nicht verwendet wird, werden alle On Error-Statements deaktiviert, sobald man an das Ende eines Moduls (sub oder function oder Methode) erreicht hat und das Modul verlässt. Beispiel unter c.

c. On Error Resume Next
Eine der gefährlichsten Konstruktionen überhaupt, die Fehlermeldung wird ganz einfach unterdrückt und das Programm mit dem nächsten Statement fortgesetzt. Auf diesem Weg werden Fehler vom Typ 1. zu Fehlern vom Typ 2., die anschliessend eine Ueberprüfung des Zustandes erfordern.

Code

Dim dir As NotesDbDirectory
Dim db As NotesDatabase
Set dir = s.GetDbDirectory("")
On Error Resume Next
Set db = dir.CreateDatabase("quack.nsf", True)
On Error Goto 0
If db is nothing then
   Messagebox "Datenbank existiert bereits"
End if

2. On Error mit Fehlernummer
Alle drei oben beschriebenen Varianten können mit einer Fehlernummer versehen werden. Während bei obigen Beispielen immer alle Fehlermeldungen unterdrückt und speziell behandelt werden, lässt sich mit Angabe einer Fehlernummer dieses Verfahren auf genau eine einzige Fehlermeldung beschränken. Beispiel:

Code

Sub Demo
  On Error 11 goto DivByZero
  Resultat = Var1 / 0
  On Error Goto 0

Exit Sub

DivByZero:
   Messagebox "Division durch 0 aufgetreten"
   Resume Next
End Sub

Die Fehlernummern findet man in der Designerhilfe. Ausserdem kann man statt mit Nummern mit "sprechenden" Konstanten arbeiten, wenn man die folgenden Dateien mit HIlfe von %include in sein Programm integriert:

lsxbeerr.lss defines constants for errors raised by Domino Designer back-end methods.
lsxuierr.lss defines constants for errors raised by Domino Designer front-end (UI) methods.
lserr.lss defines constants for errors raised by LotusScript.
lsconst.lss defines constants for use as arguments in LotusScript statements and functions.

[Semeaphoros]

Resume schliesst eine Fehlerbehandlungsroutine ab und teilt somit LotusScript mit, dass der Fehler nicht mehr als solcher zu betrachten ist (technisch gemeint natürlich)

Das Statement kann in 4 Formen auftreten:

Resume
Resume 0
Resume Next
Resume Sprungadresse

Resume und Resume 0 sind gleichbedeutend:
Mit diesen Befehlen wird das Statement, das den Fehler verurstachte, noch einmal ausgeführt: Achtung: das darf natürlich nur gemacht werden, wenn in der Fehlerbehandlungsroutine der Grund für den Fehler beseitigt wurde, also beispielsweise nach einem neuen Dateinamen gefragt wurde. Sonst passiert der Fehler ja gleich noch einmal und wir landen gleich wieder am selben Ort ....... und haben eine Endlosschleife ...... (Hinweis für TMC: Das wäre vielleicht als Beispiel in die Weihnachsschleifen-Sammlung aufzunehmen)

Mit Resume Next wird die Programmausführung beim nächsten Befehl hinter dem Statement, welches den Fehler auslöste, fortgesetzt. Auch hier gilt: im Fehlerbehandlungsprgramm sollte dafür gesorgt werden, dass das Programm weitergeführt werden kann. Hier ist es allerdings nicht so tragisch wie oben, das Programm wird ja einen Schritt nach der Fehlerstelle weitergeführt. Also auch wenn ein weiterer Fehler auftritt und die Routine wieder aufgerufen wird, kommen wir trotzdem im Programmablauf vorwärts. Vorsicht ist natürlich angebracht.

Resume Sprungadresse
Hier können wir das Programm an einem beliebigen Label fortsetzen, damit Teile, die sonst durch den Fehler nicht laufen würden, überspringen.
Beispiel:

Code

Sub Demo
  On Error Goto ErrHandler
  ... hier der Code
AfterError:
  Print "Routine Demo beendet"
Exit Sub

ErrHandler:
   Print "Es ist ein Fehler aufgetreten"
   Resume AfterError:
End Sub

[Semeaphoros]

Da wir ja jetzt mit On Error die Fehlermeldungen unterdrücken können, müssen wir in unserer Fehlerbehandlungsroutine feststellen können, was denn nun passiert ist. Dafür stehen uns 3 Funktionen zur Verfügung:

Err gibt uns die Fehlernummer an.
Errl gibt uns die Zeilennummer des Fehlers an (Achtung, funktioniert nur richtig, wenn der Fehler nicht in einer aufgerufenen selbst definierten Funktion oder Subroutine auftritt)
Error$ gibt uns den Text der Standard-Fehlermeldung  an.

Beispiel:

Code

Sub Demo
  On Error Goto ErrHandler
  ... hier der Code
AfterError:
  Print "Routine Demo beendet"
Exit Sub

ErrHandler:
  Print "Der Fehler mit Nummer " &  Str(Err) & " mit der Meldung " & Error$ & " ist bei Zeile " & Str(Errl) & " aufgetreten. Wir steigen aus"
  Resume AfterError:
End Sub

[Semeaphoros]

Da gibt es jetzt zu allem noch die Möglichkeit, dass wir als Trittbrettfahrer auf das System aufspringen können: Mit dem Error-Statement können wir selber eigene Fehlernummern und Fehlermeldungen generieren:

Error 100

löst die Fehlerbehandlung mit Nummer 100 aus

Error 101,"Dies ist unser eigener Fehler"

macht dasselbe, erzeugt aber zusätzlich noch den Fehlertext "Dies ist unser eigener Fehler"

Mit Hilfe des Error-Statements lassen sich an beliebiger Stelle im Programm entweder eigene Fehler "produzieren" oder alle LotusScript Fehler simulieren (praktisch, wenn man nicht das richtige Umfeld zur Verfügung hat).

Beispiel:

Code

Public x As Single
Const TOO_SMALL = 1001, TOO_BIG = 1002 
Sub GetNum
   Dim Num As String
   On Error GoTo Errhandle
   Num$= InputBox$("Enter a value between 1 and 100:")
   x! = CSng(Num$)     ' Convert the string to a 4-byte single.
   ' Check the validity of the entry.
   If x! < 1 Then
      Error TOO_SMALL, "The number is too small or negative."
   ElseIf x! > 100 Then
      Error TOO_BIG, "The number is too big."
   End If
   ' If the script gets here, the user made a valid entry.
   MessageBox "Good job! " & Num$ & " is a valid entry."
   Exit Sub
   ' The user did not make a valid entry.
   ' Display the error number and error message.
Errhandle:    
   ' Use the Err function to return the error number and 
   ' the Error$ function to return the error message.
   MessageBox "Error" & Str(Err) & ": " & Error$
   Exit Sub
End Sub

[Semeaphoros]

Ich habe glaube ich ziemlich vollständig abgedeckt, was an Theorie zur Fehlerbehandlung gehört. Garantieren tue ich das natürlcih nicht   da aber andere Leute schon ihre zusätzlichen Beiträge versprochen haben, werden allfällige Lücken sicher rasch gefüllt.

Es gibt verschiedene Taktiken, mit den oben aufgeführten Mitteln funktionierende Fehlerbehandlungen zu erstellen. Jeder hat da gewisse Vorlieben. Gerne würde ich jetzt von Euch Beispiele sehen, wie Ihr das macht und wir können dann gemeinsam Vor- und Nachteile der einzelnen Taktiken diskutieren. Das wird bestimmt sehr spannend.

Jens

[animate]

Ich habe einen Tipp hinzuzufügen:

mit der LS-Funktion GetThreadInfo kann man sich Informationen besorgen, die man sehr gut in einem Errorhandler gebrauchen kann (z. B. den Namen der Funktion in der der Fehler auftritt oder gleich den ganzen call stack)

Bei dem Beispiel

Sub Demo
  On Error 11 goto DivByZero
  Resultat = Var1 / 0
  On Error Goto 0

Exit Sub

würde ich mit gutem Beispiel voran gehen und anstelle der 11 die entsprechende Konstante ErrDivisionByZero (definiert in lserr.lss) verwenden, also

Sub Demo
  On Error ErrDivisionByZero goto DivByZero
  Resultat = Var1 / 0
  On Error Goto 0

Exit Sub

(ein persönlicher Kampf gegen nichtssagende Zahlenkonstanten)

[Semeaphoros]

Danke

Diese Funktion ist wirklich sehr hilfreich, nicht nur beim ErrorHandling, im Gegensatz zu den obigen Statements, die alle dem ANSI-Standard folgen, ist GetThreadInfo nur LotusScript und darüber hinaus auch noch Plattformabhängig (besonders wichtig bei Script, welches auf dem Server läuft).

Auch der Hinweis auf die Konstanten ist richtig, das steht eigentlich gerade unterhalb des Beispiels, das Du zitierst, Dein Beispiel wäre dort oben wirklich hilfreich gewesen :-)

Hier noch der Auszug aus der Hilfe zu GetThreadInfo:

Returns system information about the thread.

Syntax

GetThreadInfo (Dim InfoID  as Integer)

Elements

InfoID

Information to be returned

Return values

Data

A variant containing the information to be returned.

Usage

Pass any of the LSI_ constants from the table below to GetThreadInfo to have it return the current value of that constant.

LSI_THREAD_LINE   Current Line Number
LSI_THREAD_PROC   Name of current procedure
LSI_THREAD_MODULE   Name of current module
LSI_THREAD_VERSION   LotusScript version number
LSI_THREAD_LANGUAGE   (Human) language setting
LSI_THREAD_COUNTRY   Country or region setting
LSI_THREAD_TICKS   Get current clock ticks
LSI_THREAD_TICKS_PER_SEC   Get clock ticks per second (supported only on platforms that support parallel processing primitives)
LSI_THREAD_PROCESS_ID   Get current process ID (supported only on platforms that support parallel processing primitives)
LSI_THREAD_TASK_ID   Get current task ID (supported only on platforms that support parallel processing primitives)
LSI_THREAD_CALLPROC   Get the name of the calling procedure
LSI_THREAD_CALLMOD   Get the name of the calling module
The values of the constants are defined in LSPRVAL.LSS, which is automatically included through LSCONST.LSS.

[Glombi]

Ich habe mal folgendes ausprobiert:

ErrorHandling:
   
Dim cproc As Variant
Dim cmod As Variant
Dim cline As Variant

cproc = Getthreadinfo( LSI_THREAD_CALLPROC )
cmod = Getthreadinfo( LSI_THREAD_CALLMODULE )   
cline = Getthreadinfo( LSI_THREAD_LINE )

cmod liefert mir aber leider nur wohl nur die Notes-interner ID des Modules, nicht den Namen des Moduls, in dem der Fehler auftrat.
cline liefert eine andere Zahl als Erl.

Ich kann mich dunkel erinnern, dass LSI_THREAD_CALLMODULE  schon mal den Namen der Sub ausgegeben hat (evtl. liegt es an meiner Versio 5.0.9)

Andreas

[Glombi]

Wenn man ein On Error... verwendet, sollte man sich ebenfalls überlegen, wo man das überall macht:
- in jeder Sub / Function ?
- nur in der Main Sub (Initialize, Click,...)
- Was ist bei Verwendung von Script Libraries, wenn dort ein Fehler auftritt?

Ich habe den Fall gehabt, dass ich in einer Sub das On Error goto ...hatte, das Script aber bei Auftreten eines Fehler die Sprungmarke aus der aufrufenden Sub, wo auch On Error goto... stand, verwendet hatte.

Wenn in einer Unterfunktion ein Fehler auftritt, so muß man das in der Hauptfunktion berücksichtigen! Man kann zwar in der Unterfunktion wunderbar eine Fehlermeldung ausgeben, in der Hauptfunktion geht es dann aber munter weiter...
Daher kann es sinnvoll sein, alle Unterfunktionen als Function zu definieren, die dann True oder False zurückgeben. Oder man verwendet ein Parameter (Call by reference), denn man dann auf True oder False setzt, und dann in der aufrufenden Sub abfragt.

[animate]

Mir fällt gerade noch was ein: es kann auch sehr vorteilhaft sein, wenn man Fehler, die auftreten, loggt. Dazu bietet LS eine sehr schöne Klasse an: NotesLog.

Gleichzeitig habe ich noch eine Frage, die mich zur Zeit beschäftigt: Die für mich wichtigsten Informationen zu einem Fehler neben seinem Namen sind Zeilennummer und Funktionsname. Diese Infos stehen mir auch zur Verfügung(über Erl, GetThreadInfo), wenn das Script in einem Designelement (Form, Agent, ScriptLibrary, etc.) steht.
Was mache ich aber, wenn ich den Code in ASCII-Dateien auslagere und per %Include in die Designelemente einbinde?  Dann bekomme ich als Zeilennummer die Zeile geliefert, in der das %Include-Statement steht und als Funktionsnamen den Namen der Funktion, in der das %Include-Statement steht.

Wie komme ich zu sinvollen Informationen?
Hat jemand schon etwas auf diesem Gebiet geforscht?

[Glombi]

Es bietet sich an, neben den von Notes mitgelieferten Bordmitteln noch was eigenes zu machen.

Bspw. in jeder Function/Sub :

Sub NameDerSub
Dim MODULE_NAME as String
MODULE_NAME = NameDerSub

 On Error Goto ErrHandler
  ... hier der Code
AfterError:
  Print "Routine Demo beendet"
Exit Sub

ErrHandler:
  Print MODLULE_NAME & ": Der Fehler mit Nummer " &  Str(Err) & " mit der Meldung " & Error$ & " ist bei Zeile " & Str(Errl) & " aufgetreten. Wir steigen aus"
  Resume AfterError:

End Sub

[Semeaphoros]

Leider habe ich keine Notizen gemacht seinerzeit, wir hatten mal mit GetThreadInfo in der Error-Behandlung experimentiert, sind aber auch nicht wirklich glücklich geworden. Weder Erl noch GetThreadInfo lieferte uns zuverlässige Angaben über den Fehlerort, sobald irgendwelche Subroutinen oder Funktionen aufgerufen wurden. Mit Custom-Klassen haben wirs schon gar nicht probiert!

Ich selbst realisiere es schliesslich so, dass ich in jedem Modul eine eigene Fehlerbehandlung definiere und die Fehlerroutine, damit sie nicht immer neu geschrieben werden muss, als Subroutine ausgestalte, welche als einen der Parameter in der Regel den Namen des Moduls enthält. Damit bin ich aber auch plattform-unabhängig und bewege mich innerhalb des Standards (grade Errorhandling ist ja etwas, das man vielleicht auch mal in einem VBA brauchen kann :-)

[animate]

den Namen der Fuktion, in der der Fehler auftritt, bekommt man mit Getthreadinfo(LSI_THREAD_PROC) - zumindest in R5. Ich benutze diese Funktion und sie hat noch nie ein falsches Ergebnis geliefert, auch nicht in eigenen Klassen.

[Semeaphoros]

So viel weiss ich noch:
Wir haben versucht, eine generelle Error-Routine zu erstellen, die im HauptModul eingesetzt würde. Wenn sie angesprungen wird, dann sollte sie uns ModulNamen und die Fehlerzeile mitsamt den Fehlermeldungen angeben. Das hat eigentlich auch geklappt, der ModulName war nie ein Problem, wie Du richtig beschreibst. Nur mit der Fehlerzeile wars dann essig, die ist nicht zuverlässig rübergekommen. Aehnliche Probleme wie bei der Bord-Funktion ErrL, welche ja auch nur die richtige Zeile angibt, wenn die ErrorRoutine im selben Modul steht wie der auftretende Fehler. Damit waren wir aber nicht weit genug, um das Erstellen einer eigenen Fehlerroutine in jedem einzelnen Modul abzulösen.

Folgerung: Wenn ich eh in jedes einzelne Modul eine Errorroutine einbauen muss, dann bin ich mit GetThreadInfo eigentlich genauso weit wie mit Standard-Basic Bordmitteln auch, einzig den Modulnamen muss ich da von Hand jedesmal mit nachtragen, aber da ich ja eh pro Modul eine Routine habe, kann ich den auch gleich dort mit reinschreiben, so wie das Andreas oben schon vorgeführt hat (ok, wir machens ohne Variable, direkt inder Error-Routine, die Version von Andreas ist  flexibler, der Bearbeitungsaufwand für ein neues Modul etwa deselbe).

[Rob Green]

das könnte als ergänzende Quelle dienen auch die Kommentare vaD!

http://www.lotusgeek.com/SapphireOak/LotusGeekBlog.nsf/plinks/ROLR-5MXR69

zB das hidden Feature hier:
But since 6 was released, there is a new 'undocumented' function lsi_info in my error handler stuff. the following can be done with the funciton:

lsi_info(1) = current line number
lsi_info(2) = current sub/function name
lsi_info(3) = current module
lsi_info(6) = lotusscript version
lsi_info(12) = name of lotuscript function that called this one, to build stack traces
lsi_info(50) = lotusscript memory allocated
lsi_info(51) = lotusscript memory allocated from os
lsi_info(52) = lotusscript blocks used

[Glombi]

Gute Quelle,
insbesondere das On Error goto 0 deckt ja eine meiner Anmerkungen bzgl. Error handling in Subfunktionen und Ausgabe des Funktionsnamens ab.

Schon witzig, dass ausgerechnet an Halloween 2 unabhängige (?) Foren sich mit Error Handling beschäftigen.

Andreas

[Rob Green]

ach so, der obige Link ist ein etwas älterer Artikel vor ca. 3 Monaten und stellt den Blog von Rocky Oliver dar (den Author von Teach Yourself Lotus Script und dem neuen Buch über R6 .. Volker Weber fand dat Buch nicht schlecht).