Notes für Linux: LotusScript Remote Debugger

Der Debugger ist bei der lokalen LotusScript-Programmierung ein unentbehrliches Werkzeug. Er bietet folgende Möglichkeiten:

• die schrittweise Abarbeitung des Programmcodes,

• die zeitweise Unterbrechung der Abarbeitung,

• im Bedarfsfall das Überspringen von Routinen und Unterprogrammen,

• das Setzen von Haltepunkten,

• die Einsicht in die aktuellen Werte der Variablen,

• die Kontrolle von Programmausgaben,

• das Nachvollziehen aufgerufener Routinen und Unterprogramme,

• die Änderung der aktuellen Werte von Variablen zur Beeinflussung der Programmausführung und der Herbeiführung gewünschter Situationen,

• das Beenden des Debuggings mit der Option, den Debugger sofort zu schließen.
  

Bis zur Version 5 konnten Sie nur lokalen LotusScript- Programmcode debuggen. Trat der Fehler bei der Ausführung eines serverbasierten Agenten auf, blieb Ihnen nur eine mühevolle Suche von Hand im Programmcode oder der Versuch, die Funktion des Agenten in einem lokalen Szenario nachzuvollziehen.

Seit der Version 6 steht mit der Prozedur des Remote Debugging eine Lösung für derartige Situationen zur Verfügung. Nach dem einmaligen Einrichten des Remote Debugger auf dem Domino Server können Sie serverbasierte Agenten in ihrer echten Umgebung testen.

Führen Sie folgende Schritte aus, um mit dem Remote Debugger LotusScript-Agenten auf dem Server zu testen:

1.Starten Sie den benötigte Server-Task, und richten Sie den Anschluss des Servers ein.

2. Richten Sie den Agenten für das Remote Debugging ein.

3. Starten Sie Ihren Agenten, und greifen Sie auf ihn zu.

Nach der Konfiguration kann jeder, der ausreichende Rechte in der Zugriffskontrollliste der Datenbank, die
den Agenten enthält, und das Recht,zur Ausführung von LotusScript-Agenten auf dem Server besitzt, das Remote Debugging durchführen.

Serverkonfiguration

Für die Ausführung des Remote Debugging wird der Server-Task RDEBUG benötigt. Bevor dieser gestartet werden kann, muss er aktiviert werden. Im Serverdokument des Servers, auf dem der Agent laufen soll, gehen Sie dazu auf folgende Weise vor:

1. Öffnen Sie den Administrator-Client und wechseln Sie auf das Register Configuration.

2. Wählen Sie dort in der Ansicht Server/All Server Documents das zu bearbeitende Serverdokument.

3. Öffnen Sie es im Bearbeitungsmodus, und wechseln Sie auf das Register Server Tasks. Es verfügt über das Unterregister Remote Debug Manager (Bild 1).

4. Auf diesem wählen Sie im Feld Allow remote debugging on this server den Eintrag Enabled.

Anschließend können Sie in den Feldern Turnoff Server Debug after und Agent Wait at StartTime weitere Einstellungen für den Task vornehmen. Der erste Wert bestimmt, nach welcher Zeitspanne der Server-Task deaktiviert wird. Bei der Wahl von -1 läuft der Task permanent. Eine Deaktivierung erfolgt in diesem Fall nicht. Der zweite Wert ist für den Start des Remote Debugging wichtig. Nach dem Start des Agenten müssen Sie diesen über ein Dialogfenster einfangen (dazu später mehr). Die Ihnen dabei zur Verfügung stehende Zeitspanne bestimmen Sie mit dem Wert Agent Wait at StartTime.

Aktivierung des TCP/IP-Ports

Neben dem Server-Task ist die Aktivierung des TCP/IP-Ports des Servers für das Remote Debugging notwendig.

1. Auf dem Register Ports, Unterregister Internet Ports, Unterregister Remote Debug Manager wählen Sie dazu im Feld TCP/IP port status den Eintrag Enabled (Bild 2).

2. Speichern Sie das Serverdokument, und starten Sie den Server über den Konsolenbefehl restart server neu. Beachten Sie, dass Sie auf dem Server Administrationsrechte benötigen, um die notwendigen Änderungen durchzuführen.

Nach der erfolgreichen Einrichtung können Sie den Server-Task starten. Nutzen Sie dazu den Konsolenbefehl load rdebug Soll der Remote Debugger bei jedem Serverstart aktiviert werden, nehmen Sie den Eintrag rdebug in die Zeile Servertasks = in der Datei notes.ini des Servers auf.

Agenten einrichten

Die Einrichtung eines Agenten, um ihn mittels Remote Debugging zu testen, umfasst zwei Punkte. Zum einen müssen Sie die Eigenschaft Allow remote debugging für diesen Agenten aktivieren. Diese befindet sich in der Infobox auf dem Register Security (Bild 3). Voraussetzung dafür ist, dass Sie als Auslöser für den Agenten auf dem Register Basics die Option On schedule auswählen, sonst haben Sie keinen Zugriff auf die Eigenschaft Allow remote debugging.

Zum andern ist eine kleine Ergänzung im Programmcode notwendig. Wie bereits erwähnt, müssen Sie innerhalb der im Feld Agent Wait at StartTime festgelegten Zeitspanne den Agenten über ein Dialogfenster einfangen. Damit dies möglich ist, muss der Agent seine Ausführung für die Dauer dieser Zeitspanne unterbrechen. Dies erreichen Sie durch das Hinzufügen des Befehls stop zum Programmcode. Für den Fall, dass das Remote Debugging nicht aktiviert ist, hat der Befehl keine negativen Konsequenzen. Er wird bei der Ausführung des Agenten einfach ignoriert.

Zusätzlich können Sie eine Information, dass der Agent läuft, über die Serverkonsole ausgeben lassen. Fügen Sie zu diesem Zweck an den Anfangdes Programmcodes im Ereignis Initialize die folgenden zwei Programmzeilen ein:

print "Agent gestartet! Remote Debugging aufrufen!" Stopp

Remote Debugging ausführen

Für die Ausführung und Überwachung von serverbasierten Agenten ist der Agent-Manager zuständig. Dahinter verbirgt sich der Server-Task AMGR. Für seine Steuerung stehen verschiedene Befehle zur Verfügung (Tabelle 1). So ist auch der Start eines Agenten über einen Konsolenbefehl des Agent-Managers möglich. Geben Sie dazu auf der Serverkonsole den Befehl

tell amgr run "<NameDerDatenbank>" '<NameDesAgenten>'

ein. Achten Sie dabei auf die Anführungszeichen.

Tabelle 1: Die Steuerungsbefehle für den Agent-Manager.

Befehl	Aktion
tell amgr -?	Dieser Befehl zeigt eine Hilfe zu den verschiedenen Konsolenbefehlen des Agent-Managers an.
tell amgr cancel <NameDerDatenbank> <NameDesAgenten>	Der Befehl bricht die Ausführung des geplanten Agenten ab. Der Name des Agenten und der Datenbank, in welcher er sich befindet, werden als Parameter angegeben.
tell amgr debug	Die Debug-Einstellungen des Agent-Managers werden in der Datei notes.ini festgelegt. Alternativ können Sie diese Einstellungen auch über die Serverkonsole vornehmen. Mögliche Parameter sind unter anderem: p – Agentenleistungsstatistiken werden ausgegeben. r – Berichten über die Agentenausführungen werden ausgegeben. r – Ausgabe von Zeitplanungsinformationen
tell amgr run <NameDerDatenbank> <NameDesAgenten>	Der Befehl startet den angegebenen Agenten.
tell amgr pause	Für zeitgesteuerte Agenten können Sie mit diesem Befehl die Zeitplanung außer Kraft setzen.
tell amgr quit	Der Befehl beendet die Ausführung des Agent-Managers auf dem Server.
tell amgr resume	Zur Reaktivierung der Zeitplanung der Agenten nutzen Sie diesen Befehl.
tell amgr schedule	Dieser Befehl erzeugt einen Bericht, welcher die Namen aller für den aktuellen Tag geplanten Agenten enthält. Weiterhin werden der Auslösetyp, die Uhrzeit für die Ausführung und die Datenbank angegeben, in welcher die einzelnen Agenten laufen. Die auszuführenden Agenten werden in so genannte Warteschlangen unterteilt. Dabei werden ausführbare Agenten (Kennzeichen E), zur Ausführung geplante Agenten (S) und Ereignissensitive Agenten, die auf das Eintreten des Ereignisses warten (V) unterschieden. Mögliche Auslösertypen sind: Ausführung des Agenten ist geplant (S), Agent wird von neuer Mail ausgelöst (M) und Agent wird durch das Erstellen und Ändern von Dokumenten ausgelöst (U).
tell amgr status	Zur Ausgabe der Einstellungen des Agent-Managers im Serverdokument sowie der aktuellen Warteschlangen verwenden Sie diesen Befehl.

Start des Agenten

Mit dem Start des Agenten beginnt die im Serverdokument festgesetzte Zeitspanne abzulaufen:

1. Rufen Sie deshalb sofort nach der Eingabedes Konsolenbefehls im Domino Designer den Menüpunkt File/Tools/Remote LotusScript Debugger auf.

2. Klicken Sie auf die Schaltfläche Select debug target. Es öffnet sich das gleichnamige Dialogfenster (Bild 4 folgende Seite).

3. Wählen Sie im Feld Server den Server, auf dem der Agent läuft.

4. Im Feld Database bestimmen Sie die Datenbank, die den Agenten enthält.

5. Sobald Ihnen im Feld Debug Target der im Hintergrund laufende und momentan wartende Agent angeboten wird, wählen Sie ihn aus und betätigen die Schaltfläche Open.
   

Nun steht Ihnen der Agent im Debugger zur Verfügung, und Sie können ihn wie gewohnt nutzen.

Das Debugging über das Netzwerk bietet für viele Aufgabenstellungen klare Vorteile, weil man die Ausführung auf einem entfernten Systeme ohne direkte Eingriffe überwachen kann. Das ist vor allem bei Tests in Serverumgebungen von Bedeutung, aber auch für die Analyse von Laufzeitfehlern in Produktivumgebungen, die sich in anderer Weise nicht erklären lassen. Das Remote- Debugging kann dabei helfen, weil der Eingriff in das System, auf dem der Agent ausgeführt wird, gering ist und weil der laufende Betrieb bis auf die ohnehin bestehenden Probleme mit dem Agent nicht gestört wird.

Außerdem ist im Vergleich mit den meisten anderen Ansätzen für das Remote-Debugging, die es beispielsweise auf Betriebssystemebene gibt, der Debugger des Domino Designer sehr einfach konfigurierbar und einsetzbar. Spezielle Hardwarekomponenten sind nicht erforderlich.