Notes/Domino 5
EDITION Lotus Domino.Solutions – Domino 5 richtig einsetzen Klaus Fochler / Jörg Ungermann / Benedikt Wahl Notes/Domino effektiv nutzen – Groupware in Fallstudien Ulrich Hasenkamp / Oliver Reiss / Thomas Jenne / Matthias Goeken Lotus Notes und Domino im Einsatz – Anwendungen und Lösungen Michael Herkens / Petra Kienle Lotus Notes 5 und Domino – Arbeiten im Team, arbeiten im Web Michael Frerking / Monika Jaszkowski / Klaus-Dieter Kolm Anwendungsentwicklung unter Lotus Notes/Domino 5 Matthias Knäpper / Primoz Perc / Volker Perplies Notes/Domino 5 – Einführung in die LotusScript-Programmiersprache Thomas Muhs / Börries Klatt Lotus Domino.doc – Unternehmensweites Dokumentenmanagement Artur Rueb / Mario Kuhl
Thomas Muhs Boerries Klatt
Notes/Domino 5 Einführung in die LotusScript-Programmierung
Bitte beachten Sie: Der originalen Printversion liegt eine CD-ROM bei. In der vorliegenden elektronischen Version ist die Lieferung einer CD-ROM nicht enthalten. Alle Hinweise und alle Verweise auf die CD-ROM sind ungültig.
ADDISON-WESLEY An imprint of Pearson Education München • Boston • San Francisco • Harlow, England Don Mills, Ontario • Sydney • Mexico City Madrid • Amsterdam
Die Deutsche Bibliothek – CIP-Einheitsaufnahme Ein Titeldatensatz für diese Publikation ist bei der Deutschen Bibliothek erhältlich
Die Informationen in diesem Produkt werden ohne Rücksicht auf einen eventuellen Patentschutz veröffentlicht. Warennamen werden ohne Gewährleistung der freien Verwendbarkeit benutzt. Bei der Zusammenstellung von Texten und Abbildungen wurde mit größter Sorgfalt vorgegangen. Trotzdem können Fehler nicht vollständig ausgeschlossen werden. Verlag, Herausgeber und Autoren können für fehlerhafte Angaben und deren Folgen weder eine juristische Verantwortung noch irgendeine Haftung übernehmen. Für Verbesserungsvorschläge und Hinweise auf Fehler sind Verlag und Herausgeber dankbar. Alle Rechte vorbehalten, auch die der fotomechanischen Wiedergabe und der Speicherung in elektronischen Medien. Die gewerbliche Nutzung der in diesem Produkt gezeigten Modelle und Arbeiten ist nicht zulässig. Fast alle Hardware- und Softwarebezeichnungen, die in diesem Buch erwähnt werden, sind gleichzeitig auch eingetragene Warenzeichen oder sollten als solche betrachtet werden. Umwelthinweis: Dieses Produkt wurde auf chlorfrei gebleichtem Papier gedruckt. Die Einschrumpffolie – zum Schutz vor Verschmutzung – ist aus umweltverträglichem und recyclingfähigem PE-Material. 10 9 8 7 6 5 4 3 2 1 03 02 01 00 ISBN 3-8273-1653-7 © 2000 by Addison-Wesley Verlag, ein Imprint der Pearson Education Deutschland GmbH Martin-Kollar-Straße 10–12, D-81829 München/Germany Alle Rechte vorbehalten Einbandgestaltung: Lektorat: Herstellung: Satz: Druck und Verarbeitung: Printed in Germany
Barbara Thoben, Köln Rolf Pakendorf,
[email protected] Anja Zygalakis,
[email protected] mediaService, Siegen Schoder Druck, Gersthofen
Inhaltsverzeichnis Ei n l e i t un g . .. .... ... ..... .. .... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 25 S at zk o n v e n t io n e n . ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 27 1
Das A n we n d u n gs be is p i e l .. .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 29 1.1 Der Start: Ein erster Aufbau der Anwendung Kontaktmanagement ...........30 1.1.1 Datenbank »Adressen« .............................................................30 1.1.2 Datenbank »Konfiguration« ......................................................35 1.1.3 Datenbank »Kontakte« .............................................................37 1.2 Wie geht es weiter? ..................................................................................39
2
En t w i ckl u n gs u m ge b un g (ID E) . .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 41 2.1 Verständnisvoraussetzungen.....................................................................41 2.2 Lernziel ....................................................................................................41 2.3 Die IDE.....................................................................................................41 2.4 Navigator.................................................................................................42 2.5 Objektstruktur und Referenz.....................................................................43 2.6 Programmierbereich.................................................................................44 2.6.1 Editor .......................................................................................44 2.6.2 Zeilenumbrüche .......................................................................46 2.6.3 Tabulator..................................................................................46 2.6.4 Kommentare ............................................................................46 2.6.5 Hintereinanderhängen von Befehlen.........................................46 2.6.6 Kompilieren und Kompilierfehler ..............................................47 2.7 Debugger.................................................................................................47 2.7.1 Start des Debuggers .................................................................47 2.7.2 Haltepunkte..............................................................................49 2.7.3 Aufrufe verfolgen ......................................................................50 2.7.4 Weitere Navigationsmöglichkeiten............................................51 2.7.5 Variablenwerte verfolgen und manipulieren..............................51 2.8 Probleme .................................................................................................52 2.9 Fragen......................................................................................................53
3
G r u n dl e ge n d e D at e n t yp e n .. ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 55 3.1 Verständnisvoraussetzungen.....................................................................55 3.2 Lernziel ....................................................................................................55 3.3 Allgemeines zur impliziten und expliziten Deklaration von Variablen ........55 3.4 Numerische Datentypen ..........................................................................56 3.4.1 Der Datentyp Integer................................................................56 3.4.2 Der Datentyp Long...................................................................57 3.4.3 Der Datentyp Single .................................................................58
6
Inhaltsverzeichnis
3.5 3.6 4
3.4.4 Der Datentyp Double ...............................................................59 3.4.5 Der Datentyp Currency.............................................................60 3.4.6 Numerischer Typenwandel .......................................................61 3.4.7 Zusammenfassung numerischer Datentypen ............................61 Der Datentyp Variant ...............................................................................61 Fragen......................................................................................................63
D e r D at e n t yp S t r in g .. .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 65 4.1 Verständnisvoraussetzungen.....................................................................65 4.2 Lernziel ....................................................................................................65 4.3 Vorbemerkung .........................................................................................65 4.4 Implizite und explizite Deklaration............................................................65 4.5 Dynamische und statische Zeichenkette ...................................................66 4.6 Initialisierung von Zeichenketten ..............................................................66 4.7 Verwendung von statischen Zeichenketten ..............................................66 4.8 Funktionen und Anweisungen für Zeichenketten ......................................67 4.8.1 Die Funktionen Len, LenB, LenBP und LenC..............................67 4.8.2 Die Funktionen Left und Right ..................................................67 4.8.3 Die Funktion Mid......................................................................68 4.8.4 Die Operationen RSet und LSet.................................................69 4.8.5 Die Funktionen LTrim, RTrim und Trim .....................................69 4.8.6 Die Funktionen LCase und UCase .............................................69 4.8.7 Die Funktion Str........................................................................70 4.8.8 Die Funktionen StrCompare und StrComp................................70 4.8.9 Die Funktion StrConv ...............................................................71 4.8.10 StrLeft, StrLeftBack, StrRight und StrRightBack..........................71 4.8.11 Die Funktion String...................................................................73 4.8.12 Die Funktionen InStr, InstrB, InstrBP und InstrC ........................73 4.8.13 Die Anweisung Option Compare ..............................................73 4.8.14 Die Funktion Space...................................................................73 4.8.15 Die Funktion Val .......................................................................74 4.8.16 Die Funktion Asc.......................................................................74 4.8.17 Die Funktion Chr ......................................................................74 4.8.18 Die Funktion UChr....................................................................74 4.8.19 Die Funktion Uni.......................................................................75 4.8.20 Die Funktion UString ................................................................75 4.9 Operatoren für das Handling von Zeichenketten ......................................75 4.9.1 Konkatenationsoperatoren........................................................75 4.9.2 Vergleichsoperatoren ................................................................75 4.10 Übergabe von Zeichenketten als Parameter..............................................76 4.10.1 Übergabe per Referenz .............................................................76 4.10.2 Übergabe per Wert ...................................................................76 4.11 Verwendung von konstanten Zeichenketten.............................................76
Inhaltsverzeichnis
7
4.12 Grenzen beim Datentyp String.................................................................77 4.13 Besondere Unterschiede zwischen statischen und dynamischen Zeichenketten.....................................................................77 4.13.1 Unterschiede bei der Wertzuweisung ........................................77 4.13.2 Unterschiede bei der Längenermittlung ....................................78 4.14 Fragen......................................................................................................78 5
Zeit5.1 5.2 5.3
u n d D at u m s we r t e ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 79 Verständnisvoraussetzungen.....................................................................79 Lernziel ....................................................................................................79 Einleitung.................................................................................................79 5.3.1 Umwandlung der Einzelwerte Jahr, Monat, Tag in Datumswert ...................................................................80 5.3.2 Umwandlung von Strings in Datumswerte................................81 5.3.3 Umwandlung von Stunden, Minuten, Sekunden in Zeitwert .....81 5.3.4 Umwandlung von Strings in Zeitwerte......................................81 5.3.5 Überprüfung, ob ein Ausdruck ein Datum darstellt ...................82 5.4 Das aktuelle Datum ermitteln und setzen .................................................82 5.4.1 Aktuelles Datum ermitteln ........................................................82 5.4.2 Aktuelles Datum setzen.............................................................82 5.5 Die aktuelle Uhrzeit ermitteln und setzen .................................................83 5.5.1 Aktuelle Uhrzeit ermitteln .........................................................83 5.5.2 Aktuelle Uhrzeit setzen..............................................................83 5.6 Die Funktionen Now, Today und Timer....................................................83 5.6.1 Die Funktion Now ....................................................................83 5.6.2 Die Funktion Today ..................................................................83 5.6.3 Die Funktion Timer ...................................................................84 5.7 Ermitteln von Tag, Monat, Jahr, Wochentag.............................................84 5.7.1 Die Funktion Year .....................................................................84 5.7.2 Die Funktion Month .................................................................84 5.7.3 Die Funktion Day......................................................................85 5.7.4 Die Funktion Weekday ..............................................................85 5.8 Ermitteln von Stunden, Minuten und Sekunden .......................................85 5.8.1 Die Funktion Hour ....................................................................85 5.8.2 Die Funktion Minute.................................................................86 5.8.3 Die Funktion Second ................................................................86 5.9 Wichtige Bemerkung zum Abschluss ........................................................86 5.10 Fragen zu dem Kapitel .............................................................................87
6
A rr rra ay . .. .... ... ..... .. .... ... ..... .. .... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 89 6.1 Verständnisvoraussetzungen.....................................................................89 6.2 Lernziel ....................................................................................................89 6.3 Einleitung.................................................................................................89 6.4 Statische und dynamische Arrays..............................................................90
8
Inhaltsverzeichnis
6.5 6.6 6.7 6.8 6.9
6.10 6.11 6.12 6.13 6.14 6.15 6.16 6.17
Deklaration ..............................................................................................90 6.5.1 Größenveränderung eines dynamischen Arrays.........................90 Zugriff auf Elemente.................................................................................91 Löschen von Elementen ...........................................................................91 Zugriff auf die Indizes...............................................................................92 ArrayAppend und ArrayReplace ................................................................92 6.9.1 ArrayAppend ............................................................................92 6.9.2 ArrayReplace.............................................................................93 Suchen eines Wertes in einem Array .........................................................93 Standarduntergrenze der Indexbereiche...................................................94 6.11.1 Überprüfung auf Arrayreferenz .................................................95 Keine Zuweisungen ..................................................................................95 Verbesserung des Laufzeitverhaltens.........................................................95 Laufzeitverhalten bei dynamischen Arrays ................................................97 Doch eine Zuweisung von zwei Arrays .....................................................97 Problematische Fehler ..............................................................................97 6.16.1 Wichtige Bemerkungen ............................................................97 Fragen zu dem Kapitel .............................................................................98
7
D e r D at e n t yp L i st .. ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... 99 7.1 Verständnisvoraussetzungen.....................................................................99 7.2 Lernziel ....................................................................................................99 7.3 Einleitung.................................................................................................99 7.4 Die Deklaration ........................................................................................99 7.5 Zugriff auf die Elemente .........................................................................100 7.5.1 Wert-Zuweisung bei einem Listen-Element .............................101 7.5.2 Wert-Auslesen bei einem Listen-Element .................................101 7.6 Datentypen der Listen-Elemente.............................................................102 7.7 LotusScript-Befehle für Listen..................................................................103 7.7.1 Löschen aller oder einzelner Elemente einer Liste mit Erase .....103 7.7.2 Die ForAll-Schleife...................................................................103 7.7.3 Die Überprüfung mit IsList ......................................................104 7.7.4 Die Überprüfung der Existenz eines Elementes mit IsElement ..104 7.7.5 Die Anweisung ListTag............................................................104 7.8 Fragen....................................................................................................105
8
P r og r amm mmv v e rz we i g un g ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 07 8.1 Verständnisvoraussetzungen...................................................................107 8.2 Lernziel ..................................................................................................107 8.3 Sprungmarken .......................................................................................107 8.4 Die If-Anweisung ....................................................................................108 8.4.1 If ... Goto-Anweisung..............................................................108 8.4.2 If ... Then ... Else-Anweisung ...................................................108 8.4.3 If ... Then ... ElseIf-Anweisung .................................................109
Inhaltsverzeichnis
9
8.5 8.6
Die Select Case-Anweisung ....................................................................109 Programmschleifen ................................................................................110 8.6.1 Die For ... Next-Anweisung.....................................................110 8.7 Die Do-Schleife ......................................................................................111 8.7.1 Kopfgesteuerte Do ... While-Schleife .......................................111 8.7.2 Fußgesteuerte Do ... While-Schleife ........................................111 8.7.3 Kopfgesteuerte Do ... Until-Schleife ........................................112 8.7.4 Fußgesteuerte Do ... Until-Schleife..........................................112 8.7.5 Die While-Schleife...................................................................112 8.7.6 Do ... Loop-Schleife ................................................................113 8.8 Die ForAll-Anweisung .............................................................................114 8.9 Programmsprung GoTo .........................................................................114 8.9.1 Der GoTo-Sprung ...................................................................114 8.9.2 On ... GoTo-Sprung................................................................115 8.10 GoSub-Anweisungen..............................................................................115 8.10.1 GoSub-Sprung........................................................................115 8.10.2 On ... GoSub-Sprung ..............................................................116 8.11 Exit-Anweisung ......................................................................................116 8.11.1 Exit Sub/Exit Function/Exit Property........................................116 8.11.2 Exit Do, Exit For, Exit Forall .....................................................117 8.12 Fragen....................................................................................................117 9
F e h le r b e h an d lu n g . ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 19 9.1 Verständnisvoraussetzungen...................................................................119 9.2 Lernziel ..................................................................................................119 9.3 Einleitung...............................................................................................119 9.3.1 Einige Tipps zur Fehlerbehandlung .........................................125 9.4 Fragen....................................................................................................127
10 De r P r o t o k o ll m e ch a n i sm u s .. ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 29 10.1 Verständnisvoraussetzungen...................................................................129 10.2 Lernziel ..................................................................................................129 10.3 Einleitung...............................................................................................129 10.4 Allgemeine Implementierung .................................................................131 10.5 Die Protokollmedien...............................................................................132 10.5.1 Protokollieren in einer Datenbank ...........................................132 10.5.2 Protokollierung in einer Textdatei ...........................................133 10.5.3 Protokollierung durch Mails ....................................................134 10.5.4 Protokollierung ins AgentLog..................................................134 10.6 Die verschiedenen Arten der Protokollmeldungen ..................................135 10.6.1 Meldungen.............................................................................135 10.6.2 Fehlermeldungen ...................................................................135 10.7 Fragen....................................................................................................135
10
Inhaltsverzeichnis
11 Di e A g e n t -P r og r amm mmii e ru n g ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 37 11.1 Verständnisvoraussetzungen...................................................................137 11.2 Lernziel ..................................................................................................137 11.3 Funktionen zum Synchronisieren von Agents .........................................137 11.3.1 Die Funktion CreateLock.........................................................138 11.3.2 Die Funktion DestroyLock .......................................................138 11.3.3 Die Funktion CodeLock...........................................................138 11.3.4 Die Funktion CodeUnLock ......................................................138 11.4 Die Anweisung Sleep und ihre Verwendung ...........................................139 11.5 Der Kontext bei Webagents ...................................................................139 11.5.1 Einige Beispiele für CGI-Variablen ...........................................140 11.6 Die RunOnServer-Anweisung..................................................................141 11.7 Einige wichtige Einschränkungen ...........................................................141 11.7.1 Verwendung von Frontend-Klassen.........................................141 11.7.2 Zugriff von Serveragenten auf andere Server ..........................141 11.8 Fragen....................................................................................................142 12 A u fr u f e x t e r n e r P r og r amm mme e ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 43 12.1 Verständnisvoraussetzungen...................................................................143 12.2 Lernziel ..................................................................................................143 12.3 Ausführen von externen Programmen ....................................................143 12.4 Einbinden von externen Anwendungen in eigene LotusScript-Dateien ...143 12.5 Lizenzrechtliche Probleme bei der Verwendung von externen Anwendungen.........................................................................144 12.5.1 Sicherheits-Probleme bei der Verwendung von externen Anwendungen .........................................................144 12.5.2 Administrative Probleme bei der Verwendung von externen Programmen............................................................144 12.5.3 Kompatibilitätsprobleme bei der Verwendung von externen Programmen............................................................144 12.6 Wann der Einsatz von externen Anwendungen sinnvoll ist .....................145 12.7 Art der externen Anwendungen .............................................................145 12.7.1 Dynamische Bibliotheken........................................................145 12.7.2 Verwendung von dynamischen Bibliotheken...........................145 12.7.3 ActiveX-Elemente ...................................................................145 12.7.4 LSX-Klassen ............................................................................146 12.8 Fragen....................................................................................................146 13 Di e V e rw e n d un g v o n O L E .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 47 13.1 Verständnisvoraussetzungen...................................................................147 13.2 Lernziel ..................................................................................................147 13.3 Was ist OLE?...........................................................................................147 13.4 Der Unterschied von Embedded- und Linking-Objects ...........................147 13.5 Erstellung eines Datei-Anhangs...............................................................147
Inhaltsverzeichnis
13.6 13.7 13.8 13.9 13.10 13.11 13.12 13.13 13.14 13.15
11
Erstellen eines eingebetteten bzw. verknüpften Objektes........................148 Zugriff auf einen Datei-Anhang ..............................................................149 Zugriff auf ein eingefügtes oder ein eingebettetes Objekt.......................150 Zugriff auf alle Objekte eines Items oder des ganzen Dokuments ...........150 13.9.1 Die Eigenschaften eines eingebetteten Objektes .....................151 Bearbeiten eines eingebetteten oder verknüpften Objektes ....................151 Entfernen eines eingebetteten oder verknüpften Objekts bzw. eines Datei-Anhangs...............................................................................152 Extrahieren eines Datei-Anhangs ............................................................152 Weitere Möglichkeiten ...........................................................................153 Wichtige Bemerkungen ..........................................................................153 Fragen....................................................................................................153
14 D e r U m ga n g m i t Da t e ie n . .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 55 14.1 Verständnisvoraussetzungen...................................................................155 14.2 Lernziel ..................................................................................................155 14.3 Einleitung...............................................................................................155 14.3.1 Der Dateityp...........................................................................156 14.4 Die sequentielle Datei.............................................................................156 14.4.1 Was ist eine sequentielle Datei? ..............................................156 14.4.2 Das Öffnen einer sequentiellen Datei ......................................156 14.4.3 Schreiben in eine sequentielle Datei........................................157 14.4.4 Lesen aus einer sequentiellen Datei.........................................157 14.4.5 Positionieren des Dateizeigers bei einer sequentiellen Datei ....157 14.4.6 Ermitteln der aktuellen Position des Dateizeigers in einer sequentiellen Datei ........................................................158 14.4.7 Ermitteln des Dateiendes ........................................................158 14.4.8 Das Schließen einer sequentiellen Datei ..................................159 14.4.9 Die Dateinummer ...................................................................159 14.5 Die Random-Datei..................................................................................159 14.5.1 Was ist eine Random-Datei?....................................................159 14.5.2 Die Deklaration der Datenstruktur mit der Type-Anweisung....159 14.5.3 Das Öffnen einer Random-Datei .............................................160 14.5.4 Das Schreiben in eine Random-Datei ......................................160 14.5.5 Das Lesen aus einer Random-Datei .........................................161 14.5.6 Das Schließen einer Random-Datei .........................................161 14.5.7 Das Positionieren des Dateizeigers in einer Random-Datei.......161 14.6 Die Binärdatei ........................................................................................162 14.6.1 Das Öffnen einer Binärdatei ....................................................162 14.6.2 Das Schreiben in eine Binärdatei .............................................162 14.6.3 Das Lesen aus einer Binärdatei ................................................162 14.6.4 Das Schließen einer Binärdatei ................................................162 14.6.5 Das Positionieren eines Dateizeigers in einer Binärdatei...........162
12
Inhaltsverzeichnis
14.7 Locking-Mechanismen ...........................................................................163 14.7.1 Dateilocking ...........................................................................163 14.8 Die Loc-Funktion ....................................................................................165 14.9 Die Lof-Funktion.....................................................................................166 14.10 FileAttr-Funktion....................................................................................166 14.11 Funktion für nicht geöffnete Dateien .....................................................167 14.11.1 Die FileLen-Funktion ...............................................................167 14.11.2 Die FileCopy-Anweisung .........................................................167 14.11.3 Die Dir-Anweisung..................................................................167 14.11.4 ChDir .....................................................................................168 14.11.5 CurDir ....................................................................................168 14.11.6 CurDrive.................................................................................168 14.11.7 Die Anweisung Kill..................................................................168 14.11.8 Die Anweisung Name .............................................................168 14.11.9 Die Anweisung SetFileAttr.......................................................169 14.11.10 Die Anweisung GetFileAttr ......................................................169 14.12 Fragen....................................................................................................169 15 Be n ut ze r i n t e r akt i o n .. .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 71 15.1 Print .......................................................................................................171 15.2 MessageBox ...........................................................................................171 15.3 InputBox ................................................................................................172 15.4 DialogBox ..............................................................................................172 15.5 Picklist ....................................................................................................173 15.6 Fragen....................................................................................................176 16 Mo d u le un d S i ch t ba rk e it e n . ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 77 16.1 Verständnisvoraussetzungen...................................................................177 16.2 Lernziel ..................................................................................................177 16.3 Der Begriff des Moduls ...........................................................................177 16.4 Zugang zu Modulen und deren Aufbau..................................................178 16.5 Wichtige Bemerkungen ..........................................................................185 16.6 Fragen....................................................................................................186 17 O bj e kt o r i e n t ie r t e P r o g ra m mi e r u n g un t e r L o t u sS c ri p t .. ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...1 1 87 17.1 Verständnisvoraussetzungen...................................................................187 17.2 Lernziel ..................................................................................................187 17.3 Motivation .............................................................................................187 17.4 Was ist OOP? .........................................................................................188 17.5 OOP am Beispiel ....................................................................................189 17.6 Funktionale Analyse................................................................................190 17.7 Objektorientierte Analyse .......................................................................192 17.8 Kerngedanken der Funktionalen und der Objektorientierten Programmierung.......................................................193 17.9 Objekte in LotusScript »bauen« ..............................................................193
Inhaltsverzeichnis
13
17.10 Eigenschaften und Methoden.................................................................195 17.11 Abfrage von Eigenschaften .....................................................................196 17.12 Zuweisen von Eigenschaften ..................................................................196 17.12.1 Explizites Setzen von Eigenschaften ........................................196 17.12.2 Implizites Setzen von Eigenschaften........................................197 17.13 Vererbung ..............................................................................................200 17.14 Zustandsvariablen ..................................................................................205 17.15 Methodenvererbung ..............................................................................205 17.16 Properties...............................................................................................207 17.17 Klassenvariablen .....................................................................................209 17.18 New-Methoden mit unterschiedlichen Parameterlisten in derselben Ableitungshierarchie...............................................................211 17.19 Benutzerdefinierte Containerklassen .......................................................213 17.20 Ein Rasenmäher in Aktion .......................................................................217 17.21 Virtuelle Funktionen und Mächtigkeit von LotusScript contra C++ u. a. ..219 17.22 Polymorphismus.....................................................................................220 17.22.1 Variantvariablen für Pseudopolymorphismus...........................222 17.23 Datenstrukturen unter LotusScript ..........................................................223 17.24 Praktisches Beispiel für Objekte aus dem Kontaktmanagement ...............225 17.25 Fragen....................................................................................................228 18 D o m i n o -Kl ass sse e n . .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...2 2 31 18.1 Überblick................................................................................................231 18.2 Notes-Objekte instanziieren....................................................................233 18.2.1 Weg: Einstieg über NotesUIWorkspace ...................................234 18.2.2 Weg: Einstieg über NotesSession ............................................235 18.3 Einige häufige Problemstellungen und ihre Lösung(en) ..........................237 18.3.1 Bearbeite das gerade geöffnete und aktivierte Dokument .......237 18.3.2 Starte einen Agenten ..............................................................237 18.3.3 Erzeuge ein neues Dokument .................................................237 18.3.4 Kopiere Dokumente................................................................237 18.3.5 Versende ein Dokument .........................................................238 18.3.6 Finde bestimmte Dokumente..................................................238 18.3.7 Ergreife alle in einer Ansicht markierten Dokumente ...............239 18.3.8 Öffne eine Datenbank.............................................................239 18.3.9 Finde eine geöffnete Datenbank .............................................239 18.4 Containerklassen: NotesDbDirectory, NotesDocumentCollection, NotesView..............................................................................................240 18.4.1 Erste Methode: GetFirstXXX/GetNextXXX-Kombination .........240 18.4.2 Zweite Methode: GetNthXXX.................................................242 18.5 Neue Funktionalitäten unter Domino R5 ................................................242 18.6 Spezielle Betrachtungen .........................................................................243 18.7 Weitere Klassen, LSX ..............................................................................243
14
Inhaltsverzeichnis
19 A u f D at e n b an ke n u n d Do ku m e n t e zu gr e i f e n u n d s ie be ar b e i te n ... ..... .. .... ... ...2 2 45 19.1 Verständnisvoraussetzungen...................................................................245 19.2 Lernziel ..................................................................................................245 19.3 Datenbanken .........................................................................................245 19.3.1 Allgemeines zum Datenbankzugriff.........................................245 19.3.2 Neue Datenbanken erzeugen .................................................246 19.3.3 Zugriff auf vorhandene Datenbanken .....................................248 19.3.4 Löschen von Datenbanken......................................................251 19.3.5 Programmieren von Datenbanken ..........................................251 19.4 Dokumente finden und darauf zugreifen ................................................256 19.4.1 Zusammenhang zwischen den Klassen NotesDatabase, NotesView und NotesDocumentCollection .............................256 19.4.2 Suchmöglichkeiten in NotesDocumentCollection ...................256 19.4.3 Suchmöglichkeiten in NotesView ............................................262 19.4.4 Suchmöglichkeiten in NotesDatabase .....................................267 19.5 Mit Dokumenten arbeiten ......................................................................269 19.5.1 Neue Dokumente erzeugen ....................................................272 19.5.2 Dokumente speichern.............................................................272 19.5.3 Dokument mit Inhalt füllen.....................................................272 19.5.4 Dokument mit Maske verbinden.............................................273 19.5.5 Items anzeigen .......................................................................273 19.5.6 Extended Syntax.....................................................................273 19.5.7 Beispiele und weitere Syntaxangaben .....................................274 20 P r of il ild do ku m e n t e . .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...2 2 81 20.1 Verständnisvoraussetzungen...................................................................281 20.2 Lernziel ..................................................................................................281 20.3 Was ist ein Profildokument? ...................................................................281 20.3.1 Wie die zwei unterschiedlichen Arten von Profildokumenten erzeugt werden ......................................................................281 20.4 Das Arbeiten mit Profildokumenten ........................................................282 20.4.1 Erstellen bzw. Öffnen eines Datenbankprofils..........................282 20.4.2 Löschen eines Profildokuments ...............................................283 20.5 Die Verwendung von GetProfileDocCollection........................................284 20.6 Die Benutzerprofildokumente.................................................................284 20.6.1 Erstellen bzw. Öffnen eines Benutzerprofildokuments .............284 20.7 Fragen....................................................................................................285
Inhaltsverzeichnis
21 L ot u s 21.1 21.2 21.3
21.4
21.5
21.6 21.7
15
N o t e s -S ic h e r h e it . ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...2 2 87 Verständnisvoraussetzungen...................................................................287 Lernziel ..................................................................................................287 Zugriffsschutz.........................................................................................287 21.3.1 NotesACL ...............................................................................287 21.3.2 NotesACLEntry .......................................................................289 21.3.3 Zugriffslevel ............................................................................290 21.3.4 Zusammenspiel verschiedener Einträge...................................290 Zugriffsschutz auf Dokumentenebene ....................................................291 21.4.1 Autorenfelder .........................................................................291 21.4.2 Leserfelder ..............................................................................291 21.4.3 Mehrere Autoren- und Leserfelder ..........................................292 21.4.4 Beispiele .................................................................................292 21.4.5 Funktionen (Rollen) ................................................................293 21.4.6 Zusammenfassung..................................................................293 21.4.7 Wichtige Bemerkungen ..........................................................294 Verschlüsselungsmechanismen ...............................................................294 21.5.1 Geheimer Schlüssel.................................................................294 21.5.2 Public-Private-Schlüsselpaar ....................................................294 21.5.3 Verschlüsselung mit LotusScript ..............................................295 Elektronische Unterschriften ...................................................................297 Fragen....................................................................................................297
22 O D B C- Sc hn hniitt ttss t e l le ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...2 2 99 22.1 Verständnisvoraussetzungen...................................................................299 22.2 Lernziel ..................................................................................................299 22.3 Was ist ODBC? .......................................................................................299 22.4 ODBC in Lotus-Notes/Domino ...............................................................300 22.5 Einsatzgebiete ........................................................................................300 22.6 Die LS:DO-Klassen..................................................................................301 22.6.1 ODBCConnection...................................................................301 22.6.2 ODBCQuery ...........................................................................309 22.6.3 ODBCResultSet .......................................................................311 22.7 Der praktische Einsatz von LS:DO ...........................................................323 22.8 Fehler.....................................................................................................323 22.9 Fragen....................................................................................................324 23 Ku r zr e f e r e n z d e r N o te s / D o mi n o -K l ass sse e n . ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...3 3 25 23.1 Zum Gebrauch dieser Referenz...............................................................325 23.2 Button....................................................................................................326 23.3 Field .......................................................................................................326 23.4 Navigator...............................................................................................326 23.5 NotesACL...............................................................................................327 23.6 NotesACLEntry .......................................................................................328
16
Inhaltsverzeichnis
23.7 23.8 23.9 23.10 23.11 23.12 23.13 23.14 23.15 23.16 23.17 23.18 23.19 23.20 23.21 23.22 23.23 23.24 23.25 23.26 23.27 23.28 23.29 23.30 23.31 23.32 23.33 23.34 23.35 23.36 23.37 23.38 23.39 23.40 23.41 23.42
NotesAgent............................................................................................330 NotesDatabase.......................................................................................332 NotesDateRange ....................................................................................336 NotesDateTime .....................................................................................337 NotesDbDirectory .................................................................................339 NotesDocument....................................................................................339 NotesDocumentCollection ....................................................................343 NotesEmbeddedObject .........................................................................345 NotesForm ............................................................................................346 NotesInternational ................................................................................347 NotesItem .............................................................................................348 NotesLog ..............................................................................................350 NotesName...........................................................................................351 NotesNewsletter ...................................................................................353 NotesOutline.........................................................................................354 NotesOutlineEntry.................................................................................355 NotesRegistration ..................................................................................357 NotesReplication ...................................................................................358 NotesRichTextItem................................................................................359 NotesRichTextParagraphStyle................................................................361 NotesRichTextStyle ...............................................................................361 NotesRichTextTab .................................................................................362 NotesSession .........................................................................................363 NotesTimer ...........................................................................................365 NotesUIDatabase ..................................................................................365 NotesUIDocument ................................................................................366 NotesUIView .........................................................................................370 NotesUIWorkspace ................................................................................371 NotesView.............................................................................................373 NotesViewColumn ................................................................................377 NotesViewEntry.....................................................................................379 NotesViewEntryCollection .....................................................................380 NotesViewNavigator .............................................................................381 ODBCConnection .................................................................................383 ODBCQuery ..........................................................................................384 ODBCResultSet .....................................................................................385
Inhaltsverzeichnis
17
24 Di e B e f e h l s- Re f e r e n z . .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...3 3 89 24.1 Aufbau der Referenz ...............................................................................389 24.2 Typumwandlung....................................................................................389 24.3 Verdeckte Typumwandlung ...................................................................390 24.3.1 Das automatische Casting ......................................................390 24.3.2 Beispiele für automatisches Casting ........................................390 24.4 Befehlsgruppen ......................................................................................391 24.4.1 Konvertierung.........................................................................391 24.4.2 Typenprüfung ........................................................................391 24.4.3 Datumsfunktionen I ................................................................391 24.4.4 Mathematische Funktionen ....................................................392 24.4.5 Zufallszahlen...........................................................................392 24.4.6 Zeichenkette I.........................................................................392 24.4.7 Zeichenketten II......................................................................393 24.4.8 Zeichenketten III.....................................................................393 24.4.9 Schleifen.................................................................................393 24.4.10 Rundung ................................................................................394 24.4.11 Datumsfunktionen II ...............................................................394 24.4.12 Array ......................................................................................394 24.4.13 Threadhandling und Locking ..................................................394 24.4.14 Dateien...................................................................................395 24.4.15 Standardtypen-Deklaration .....................................................395 24.4.16 Operatoren.............................................................................395 24.5 Die Befehle.............................................................................................396 24.5.1 Abs .........................................................................................396 24.5.2 Acos .......................................................................................396 24.5.3 ActivateApp ............................................................................397 24.5.4 And ........................................................................................398 24.5.5 ArrayAppend ..........................................................................399 24.5.6 ArrayGetIndex ........................................................................401 24.5.7 ArrayReplace...........................................................................402 24.5.8 Asc .........................................................................................403 24.5.9 ASin........................................................................................404 24.5.10 ATn ........................................................................................405 24.5.11 ATn2 ......................................................................................406 24.5.12 Beep .......................................................................................407 24.5.13 Bin..........................................................................................408 24.5.14 Call.........................................................................................408 24.5.15 CCur ......................................................................................410 24.5.16 CDat.......................................................................................411 24.5.17 CDbl.......................................................................................412 24.5.18 ChDir .....................................................................................413
18
Inhaltsverzeichnis
24.5.19 24.5.20 24.5.21 24.5.22 24.5.23 24.5.24 24.5.25 24.5.26 24.5.27 24.5.28 24.5.29 24.5.30 24.5.31 24.5.32 24.5.33 24.5.34 24.5.35 24.5.36 24.5.37 24.5.38 24.5.39 24.5.40 24.5.41 24.5.42 24.5.43 24.5.44 24.5.45 24.5.46 24.5.47 24.5.48 24.5.49 24.5.50 24.5.51 24.5.52 24.5.53 24.5.54 24.5.55 24.5.56 24.5.57 24.5.58 24.5.59 24.5.60
ChDrive ..................................................................................414 Chr.........................................................................................415 CInt ........................................................................................416 Class.......................................................................................416 CLng ......................................................................................418 Close ......................................................................................419 CodeLock ...............................................................................420 CodeLockCheck......................................................................421 CodeUnlock............................................................................422 Const .....................................................................................423 Command ..............................................................................424 Cos.........................................................................................425 CreateLock .............................................................................425 CreateObject ..........................................................................426 CSng ......................................................................................428 CStr........................................................................................428 CurDir ....................................................................................429 CurDrive.................................................................................430 CVar .......................................................................................431 CVdate ...................................................................................432 Date .......................................................................................432 DateNumber ..........................................................................432 DateSerial ...............................................................................434 DataType................................................................................434 DateValue...............................................................................435 Day ........................................................................................436 Declare (external C) C ............................................................437 Declare forward ......................................................................439 DefCur ...................................................................................440 DefDbl....................................................................................441 DefInt .....................................................................................442 DefLng ...................................................................................443 DefSng ...................................................................................444 DefStr .....................................................................................445 DefVar ....................................................................................446 Delete.....................................................................................447 DestroyLock............................................................................448 Dim ........................................................................................449 Dir ..........................................................................................450 Do ..........................................................................................452 DoEvents ................................................................................453 End.........................................................................................453
Inhaltsverzeichnis
24.5.61 24.5.62 24.5.63 24.5.64 24.5.65 24.5.66 24.5.67 24.5.68 24.5.69 24.5.70 24.5.71 24.5.72 24.5.73 24.5.74 24.5.75 24.5.76 24.5.77 24.5.78 24.5.79 24.5.80 24.5.81 24.5.82 24.5.83 24.5.84 24.5.85 24.5.86 24.5.87 24.5.88 24.5.89 24.5.90 24.5.91 24.5.92 24.5.93 24.5.94 24.5.95 24.5.96 24.5.97 24.5.98 24.5.99 24.5.100 24.5.101 24.5.102
19
Environ ...................................................................................454 Erase.......................................................................................455 Erl...........................................................................................456 Err-Funktion............................................................................457 Err Statement .........................................................................458 Error-Funktion ........................................................................458 Error Statement ......................................................................459 Eof..........................................................................................460 Exp .........................................................................................461 Exit .........................................................................................462 Evaluate..................................................................................463 Execute ..................................................................................463 FileAttr....................................................................................464 FileCopy .................................................................................466 FileDateTime ..........................................................................467 FileLen ....................................................................................467 Fix ..........................................................................................468 Fraction ..................................................................................469 FreeFile ...................................................................................470 For..........................................................................................471 ForAll......................................................................................472 Format ...................................................................................473 FullTrim ..................................................................................474 Function .................................................................................475 Get .........................................................................................476 GetAttr ...................................................................................477 GetFileAttr ..............................................................................478 GetObject...............................................................................479 GetThreadInfo ........................................................................480 GoSub ....................................................................................481 GoTo ......................................................................................482 Hex ........................................................................................483 Hour.......................................................................................483 If...Goto..................................................................................484 If...Then...Else .........................................................................485 If...Then...ElseIf .......................................................................486 IMEStatus ...............................................................................488 IMESetMode...........................................................................489 InputBox ................................................................................490 Input# ....................................................................................491 Input ......................................................................................492 InputB ....................................................................................493
20
Inhaltsverzeichnis
24.5.103 24.5.104 24.5.105 24.5.106 24.5.107 24.5.108 24.5.109 24.5.110 24.5.111 24.5.112 24.5.113 24.5.114 24.5.115 24.5.116 24.5.117 24.5.118 24.5.119 24.5.120 24.5.121 24.5.122 24.5.123 24.5.124 24.5.125 24.5.126 24.5.127 24.5.128 24.5.129 24.5.130 24.5.131 24.5.132 24.5.133 24.5.134 24.5.135 24.5.136 24.5.137 24.5.138 24.5.139 24.5.140 24.5.141 24.5.142 24.5.143 24.5.144
InputBP ..................................................................................493 InStr .......................................................................................493 InStrB .....................................................................................494 InStrBP ...................................................................................495 InStrC .....................................................................................495 Int ..........................................................................................495 IsA ..........................................................................................496 IsArray ....................................................................................497 IsDate .....................................................................................498 IsDefined ................................................................................498 IsElement................................................................................499 IsEmpty ..................................................................................500 IsList .......................................................................................501 IsNull......................................................................................502 IsNumeric ...............................................................................502 IsObject ..................................................................................503 IsScalar ...................................................................................504 IsUnknown .............................................................................505 Kill ..........................................................................................506 LBound...................................................................................506 LCase......................................................................................507 Left.........................................................................................508 LeftB.......................................................................................509 LeftBP .....................................................................................509 LeftC ......................................................................................510 Len .........................................................................................510 LenBP .....................................................................................511 LenB .......................................................................................511 LenC.......................................................................................512 Let..........................................................................................512 ListTag....................................................................................512 Loc .........................................................................................513 Lock .......................................................................................514 Lof..........................................................................................515 Log.........................................................................................516 LSet ........................................................................................517 LTrim......................................................................................518 Like ........................................................................................518 Line Input# .............................................................................519 MessageBox ...........................................................................520 Mid-Funktion..........................................................................522 Mid Statement .......................................................................523
Inhaltsverzeichnis
24.5.145 24.5.146 24.5.147 24.5.148 24.5.149 24.5.150 24.5.151 24.5.152 24.5.153 24.5.154 24.5.155 24.5.156 24.5.157 24.5.158 24.5.159 24.5.160 24.5.161 24.5.162 24.5.163 24.5.164 24.5.165 24.5.166 24.5.167 24.5.168 24.5.169 24.5.170 24.5.171 24.5.172 24.5.173 24.5.174 24.5.175 24.5.176 24.5.177 24.5.178 24.5.179 24.5.180 24.5.181 24.5.182 24.5.183 24.5.184 24.5.185 24.5.186
21
MidB ......................................................................................524 MidBP ....................................................................................524 MidC ......................................................................................524 Minute ...................................................................................524 MkDir .....................................................................................525 Month ....................................................................................526 Mod .......................................................................................527 MsgBox ..................................................................................528 Name .....................................................................................528 Not.........................................................................................529 Now .......................................................................................530 Oct.........................................................................................530 On Error .................................................................................531 On...GoSub ............................................................................532 On...GoTo ..............................................................................533 On Event ................................................................................534 Option Base............................................................................535 Option Compare ....................................................................536 Option Declare .......................................................................537 Option Public .........................................................................537 Open......................................................................................538 Or ..........................................................................................540 Print .......................................................................................540 Print# .....................................................................................541 Property Get / Property Set.....................................................542 Put .........................................................................................543 Randomize .............................................................................544 ReDim ....................................................................................545 Rem........................................................................................546 Reset ......................................................................................546 Resume ..................................................................................547 Return ....................................................................................548 Right ......................................................................................548 RightBP ..................................................................................549 RightB ....................................................................................549 RightC ....................................................................................550 Round ....................................................................................550 RmDir.....................................................................................551 Rnd ........................................................................................551 RSet........................................................................................552 RTrim .....................................................................................553 Run ........................................................................................553
22
Inhaltsverzeichnis
24.5.187 24.5.188 24.5.189 24.5.190 24.5.191 24.5.192 24.5.193 24.5.194 24.5.195 24.5.196 24.5.197 24.5.198 24.5.199 24.5.200 24.5.201 24.5.202 24.5.203 24.5.204 24.5.205 24.5.206 24.5.207 24.5.208 24.5.209 24.5.210 24.5.211 24.5.212 24.5.213 24.5.214 24.5.215 24.5.216 24.5.217 24.5.218 24.5.219 24.5.220 24.5.221 24.5.222 24.5.223 24.5.224 24.5.225 24.5.226 24.5.227 24.5.228
Second ...................................................................................554 Seek-Funktion .........................................................................554 Seek-Anweisung .....................................................................555 Select Case .............................................................................556 SendKey .................................................................................558 SetAttr ....................................................................................558 SetFileAttr...............................................................................558 Sgn.........................................................................................559 Shell .......................................................................................560 Sin..........................................................................................562 Sleep ......................................................................................562 Space .....................................................................................563 Spc .........................................................................................564 Sqr .........................................................................................564 Stop .......................................................................................565 Str .........................................................................................566 StrLeft.....................................................................................566 StrLeftBack .............................................................................567 StrRight ..................................................................................568 StrRightBack ...........................................................................569 StrCompare ............................................................................570 StrComp.................................................................................571 StrConv ..................................................................................571 String-Funktion.......................................................................571 Sub.........................................................................................572 Tab.........................................................................................573 Tan.........................................................................................574 Time-Anweisung.....................................................................575 Time-Funktion ........................................................................575 TimeNumber ..........................................................................576 Timer......................................................................................576 TimeValue ..............................................................................577 Today .....................................................................................578 Trim .......................................................................................578 Type .......................................................................................579 TypeName..............................................................................580 UBound ..................................................................................581 UCase.....................................................................................582 UChr ......................................................................................582 Uni .........................................................................................583 UnLock ...................................................................................584 Use .........................................................................................585
Inhaltsverzeichnis
23
24.5.229 UseLSX ...................................................................................586 24.5.230 UString ...................................................................................586 24.5.231 Val..........................................................................................587 24.5.232 VarType ..................................................................................588 24.5.233 Weekday ................................................................................588 24.5.234 While......................................................................................589 24.5.235 Width# ...................................................................................590 24.5.236 Write# ....................................................................................591 24.5.237 With .......................................................................................591 24.5.238 Xor .........................................................................................592 24.5.239 Year ........................................................................................593 24.5.240 Yield .......................................................................................594 24.5.241 %If .........................................................................................595 24.5.242 %Include ................................................................................596 24.5.243 %Rem ....................................................................................597 24.6 Datentypen ............................................................................................598 24.6.1 Numerische Datentypen .........................................................598 24.6.2 Alphanumerische Datentypen.................................................598 24.6.3 Sonstige Datentypen ..............................................................598 24.6.4 Prefix der Zahlensysteme ........................................................599 24.7 Konstanten.............................................................................................599 24.8 Includedateien .......................................................................................599 25 D i e A n w e n d un g au s d e m Ka pi t e l 17 .. ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...6 6 01 S ti c h wo r t ve r z e ic hn hniis . .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ..... .. .... ... ...6 6 07
25
Einleitung Wir möchten wir Ihnen an dieser Stelle kurz vermitteln, womit Sie in diesem Buch rechnen können. Lotus Notes/Domino wird fälschlicherweise oft für ein E-Mailsystem gehalten. Mailen kann dieses System zwar auch, doch ist Lotus Notes/Domino viel mehr: Datenbank, Workgroup-Software, Web-Server usw. Es ist gut geeignet, die täglichen Kommunikationsprozesse in den Unternehmen zu unterstützen, zu vereinfachen und zu beschleunigen. Lotus Notes hat durch seine Flexibilität und Anwenderfreundlichkeit eine starke Position an der Spitze des Groupwaremarktes erreicht. Um dieses große Potential ausschöpfen zu können, stehen mehrere Programmiermöglichkeiten zur Verfügung, beginnend mit der Notes-Formelsprache über LotusScript, JavaScript, Java, bis hin zur C- und C++-API. Trotz all dieser Möglichkeiten ist LotusScript nach wie vor die Sprache, in der Lotus Notes/Domino-Datenbanken programmiert werden. Sie ist einfach zu erlernen und birgt aufgrund des mächtigen Domino-Klassenkonzeptes starke Möglichkeiten. Daher wird sich jeder Notes-Entwickler mit ihr auseinandersetzen. Dieses Buch wurde geschrieben, damit Sie gleich von Anfang an den größten Nutzen aus LotusScript haben können. Es zeigt sowohl die grundlegenden Möglichkeiten als auch die »hohe Kunst« der objektorientierten Programmierung mit den unter LotusScript zugegebenermassen etwas eingeschränkten Möglichkeiten auf. Die Beschäftigung mit der objektorientierten Programmierung (OOP) wird für einen fortgeschrittenen Notes-Entwickler kaum ausbleiben, da ein Großteil der wirklich interessanten Datenbankmanipulationen über die von Lotus zur Verfügung gestellten Domino-Klassen (also objektorientierte Programmiermöglichkeiten) erfolgt. Diesem Thema ist ein umfangreicher Teil des Buches gewidmet. Es wird sehr anschaulich und mit viel praktischem Hintergrund dargelegt. Im Zusammenhang mit den grundlegenden Möglichkeiten der Scriptsprache erhalten Sie eine umfangreiche und durchdachte Referenz. Die einzelnen Sprachmerkmale wurden intensiv ausgetestet, um Ihnen auf engem Raum so viel Informationen wie möglich zu bieten, z.B. auch über häufig anzutreffende implizite Typumwandlungen und andere Merkmale, die sonst nur selten (wenn überhaupt) erläutert werden. Sie erhalten somit auch manche Information, die von Lotus nicht dokumentiert ist. Um die Arbeit mit den Domino-Klassen zu erleichtern, wurde eine Kurzreferenz eingefügt, die sämtliche zur Zeit dokumentierten Domino-Klassen umfasst. Sie dient dazu, sich möglichst schnell einen Überblick über den Aufbau und das Potential der Domino-Klassen zu verschaffen und sie sofort effektiv zu nutzen. Zahlreiche praxisorientierte Beispiele tun ihr übriges, um den Leser zu unterstützen.
26
Einleitung
Das Buch ist so aufgebaut, dass es sowohl dem Einsteiger (der schon ein wenig allgemeine Programmiererfahrung besitzen sollte), als auch dem fortgeschrittenen Notes-Entwickler viele Vorteile bringt. Während sich Einsteiger eher mit den grundlegenden Erläuterungen und den zahlreichen Beispielen beschäftigen werden, wird der bereits Fortgeschrittene gerne auf die nicht alltäglichen Praxishinweise zurückkommen, die ihm helfen, manche Stolperfalle von vornherein zu meiden. Auch wird er immer wieder gerne auf die Referenzen zurückgreifen, die ihn bei der täglichen Arbeit noch lange wirkungsvoll unterstützen werden. Der Code der in diesem Buch mittels der Beispiele entwickelten (rudimentären) Kontaktverwaltung ist neben anderen sehr nützlichen Notes-Tools auch auf der beiligenden CD zu finden.
27
Satzkonventionen Menüaufrufe
Datei | Datenbank | Öffnen...
Bedeutung: Im Hauptmenü den Punkt Datei, in dessen Untermenü den Eintrag Datenbank und dann den Button Öffnen... anklicken.
Buttonaufrufe: Button Durchsuchen... Bedeutung: den Button Durchsuchen... anklicken
Anführungszeichen im Text: »Text«
Syntax:
Set notesItem = notesDocument.AppendItemValue( _ itemName$ As String, value As Variant )
Bedeutung: Die fett gedruckten Wörter sind Schlüsselwörter und in Notes definierte Funktionen und Klassen nebst deren Eigenschaften und Methoden. Domino-Objekte werden in kursiv-normal angegeben. Auch Parameter und benutzerdefinierte Namen werden so geschrieben. Codebeispiele: AppendItemValue(Byval Itemname As String, Newvalue) _ As NotesItem
Fest definierte Werte und Konstanten: TRUE, FALSE, EMPTY, ACCESS_LEVEL_MANAGER usw.
Auslassungen: ...
Syntaxdiagramme und Merksätze: Syntax, Merksatz
Typenbezeichnungen: Wo möglich, durch die Kürzel der impliziten Variablen-Deklaration ($, &, #, %, ...), z. B. name$
1 1
Das Anwendungsbeispiel
Beim Schreiben des Buches stellte sich die Herausforderung, eine möglichst präzise und praxisnahe Einführung in die LotusScript-Programmierung zu bieten. Gleichzeitig sollte dem LotusScript-Einsteiger ein möglichst direkter und schneller Zugang zu den Möglichkeiten der Applikationssprache verschafft werden. Ohne zu versäumen, ihn auf zahlreiche Fallen und Tücken aufmerksam zu machen, die ihm im Alltag häufig begegnen werden. Zur Unterstützung dieses Ziels werden im mittleren Teil des Buches Komponenten einer praxisbezogenen Notes-Anwendung aufgebaut, die ein Kontaktmanagement unterstützt. Sie besteht aus drei Datenbanken, wie sie in der Praxis immer wieder vorkommen werden. Eine Stammdaten-Datenbank (Adressen), eine Konfigurations-Datenbank (mit der einstellbare Daten für die Gesamtanwendung verwaltet werden) und eine Anwendungsdatenbank (Kontakte). Gleichzeitig ist das Werk bewusst über weite Teile wie eine Referenz aufgebaut. Dadurch soll es Ihnen auch über die Einführung hinaus lange Zeit wertvolle Dienste als Nachschlagewerk leisten können. Die Beispielanwendung »Kontaktmanagement« wird insbesondere in den Kapiteln 15 »Benutzerinteraktion«, 19 »Auf Datenbanken und Dokumente zugreifen und sie bearbeiten« und 22 »ODBC-Schnittstelle« betrachtet und programmiert. Für das Kapitel 17 »Objektorientierte Programmierung unter LotusScript« wurde ein ganz anderer Rahmen gewählt, da sich diese Form der Programmierung mit dem gewählten Rasenmäher-Beispiel besser und umfangreicher veranschaulichen liess. Ansonsten wurde Wert darauf gelegt, dass die Möglichkeit besteht, einzelne Kapitel für sich zu studieren, ohne den vorherigen Fortlauf des Beispiels genau zu kennen. Dadurch, dass das Beispiel einfach und doch umfassend ist, wird dies gewährleistet. Den größten Nutzen werden Sie als Leser haben, wenn Sie die Beispiele mit aufbauen und das Zusammenspiel der einzelnen Komponenten und Schritte mitverfolgen. Wenn Ihnen die Zeit zum Mitprogrammieren fehlt, dann können Sie den Code natürlich auch von der beiliegenden CD verwenden.
30
Das Anwendungsbeispiel
1.1 Der Start: Ein erster Aufbau der Anwendung Kontaktmanagement 1.1.1 Datenbank »Adressen« Zunächst erzeugen wir eine neue leere Datenbank. Sie erhält den Namen adressen.nsf und den Titel »Adressen«. Der Einfachheit halber arbeiten wir zunächst lokal im Notes-Datenverzeichnis:
Abbildung 1.1: Erzeugung der neuen Datenbanken für das Kontaktmanagement
Dann erstellen wir zwei Masken, mit der die Adressdaten aufgenommen werden können. Dazu klicken Sie auf den Button »Neue Maske«. Es erscheint (wie in Abbildung 1.2 zu sehen) eine neue, leere Maske.
Der Start: Ein erster Aufbau der Anwendung Kontaktmanagement
31
Abbildung 1.2: Neue, leere Maske für die Adressen
Diese Maske versehen wir mit mehreren Feldern, die zur Aufnahme der Daten dienen. Die Felder erhalten entsprechende Label. Die Abgrenzung der Feldlabel nehmen wir über (mindestens zwei) Tabulatoren vor. Der zweite Tabulator dient dazu, dass wir eventuell Buttons zwischen Label und Feld setzen können, die ebenfalls per Tabulator ausgerichtet werden. Falls zur korrekten Ausrichtung erforderlich, nehmen Sie noch einen dritten Tabulator. Anschließend geben Sie der Maske den Namen »Firma« und speichern sie über Datei | Speichern ab.
32
Das Anwendungsbeispiel
Abbildung 1.3: Maske für Firmenadresse
Bevor wir die Personen-Maske zusammenstellen, benötigen wir noch eine Ansicht, mit der wir auf die Firmen zugreifen können. Da wir diese Ansicht nur für programmatischen Zugriff benötigen, wird sie sehr einfach gestaltet. Sie hat nur eine Spalte, die mit der verwendeten Spaltenformel überschrieben wird: Name + " " + Name2. Dies hat den Vorteil, dass wir später sofort sehen, welchen Inhalt die Spalte hat. Die Zusammensetzung der Formel aus beiden Namensteilen garantiert uns den eindeutigen Zugriff. Die Spalte sollte aufsteigend sortiert sein.
Der Start: Ein erster Aufbau der Anwendung Kontaktmanagement
33
Abbildung 1.4: Die Ansicht für Firmen-Dokumente
Für die Selektion verwenden Sie die Formel SELECT Form = "Firma". Die Ansicht wird unter dem Namen »(Firmen)« abgespeichert. Die Klammern sorgen dafür, dass die Ansicht vom Benutzer normalerweise nicht zu sehen ist (»versteckte Ansicht«). Ganz analog erzeugen Sie eine Ansicht für den schnellen Zugriff auf die PersonenDokumente, wie in Abbildung 1.5 gezeigt.
34
Das Anwendungsbeispiel
Abbildung 1.5: Die Ansicht für Personen-Dokumente
Jetzt müssen wir aber noch eine Maske für die Personen-Dokumente aufbauen. Dabei gehen wir analog zur Firmen-Maske vor. Das Ergebnis sehen Sie in der Abbildung 1.6. Das Feld Firma ist vom Typ »Berechnet beim Anlegen«. Der Hotspot-Button links daneben dient zur Auswahl und Zuordnung einer Firma. Er wird später eine Pickliste öffnen, die dem Benutzer hilft, das Personen-Dokument mit einer Firma zu verknüpfen. Näheres dazu finden Sie in Kapitel 15 »Benutzerinteraktion«. Als Nächstes erstellen wir die Konfigurations-Datenbank. Sie erhält eine Maske für Konfigurations-Dokumente und eine Ansicht, über die die einzelnen Konfigurationswerte gesucht werden können.
Der Start: Ein erster Aufbau der Anwendung Kontaktmanagement
35
Abbildung 1.6: Personen-Maske
1.1.2 Datenbank »Konfiguration« Die Datenbank nennen wir konfiguration.nsf (Titel Konfiguration) und die Maske »Konfiguration«. Der Aufbau der Maske wird in Abbildung 1.7 gezeigt. Die Felder sind bearbeitbar. Das Feld Werte sollte Mehrfachwerte aufnehmen können, als Trennzeichen haben wir die Zeilenumschaltung gewählt (sowohl für die Anzeige als auch für die Eingabe). Die Art des Trenners ist natürlich Geschmacksache, Sie können hier auch ein anderes Zeichen verwenden. Um die Beschreibung der Werte abzusetzen, haben wir eine kleinere Schrift und die Farbe Grau eingesetzt. Die Ansicht hat den Namen »Konfigurationen« und weist eine sortierte Spalte für den Namen der Konfigurationen auf. Die nächsten beiden Spalten sind unsortiert und nehmen die Werte und die Beschreibung auf. Mehrfachwerte sollten durch ein Trennzeichen getrennt angezeigt werden. Wir wählen das Komma.
36
Das Anwendungsbeispiel
Abbildung 1.7: Konfigurations-Maske
Abbildung 1.8: Maximale Ansichtszeilen pro Eintrag wählen
Es werden vorsichtshalber, mit der Option »Zeilenhöhe anpassen«, sechs Textzeilen pro Zeile eingestellt. Dadurch können auch längere Bemerkungen in der Ansicht gelesen werden, ohne dass unnötig Platz verschenkt wird. Geben Sie probeweise schon mal einen Wert ein, der später noch gebraucht werden kann:
Der Start: Ein erster Aufbau der Anwendung Kontaktmanagement
37
Abbildung 1.9: Konfigurations-Dokumente füllen
Die Ansicht sollte dann so ausschauen, wie in Abbildung 1.10 gezeigt.
Abbildung 1.10: Konfigurations-Ansicht
1.1.3 Datenbank »Kontakte« Jetzt brauchen wir nur noch die Anwendungs-Datenbank. Wir nennen Sie kontakte.nsf mit dem Titel Kontaktmanagement. Wir erzeugen eine Maske für die Kontakte. Sie enthält zweckmäßigerweise zwei Felder vom Typ Dialogliste (bearbeitbar): Kontaktart (Telefon, Besuch, ...) und NächsteAktion (Angebot, ...). Das Feld für den Zeitpunkt können Sie mit der Formel @Now vorbelegen. Wenn es bearbeitbar ist, kann der Benutzer bei Bedarf den genauen Zeitpunkt eintragen. Das Feld ist vom Typ Zeit/Datum.
38
Das Anwendungsbeispiel
Abbildung 1.11: Maske »Kontakt«
Fürs Erste erzeugen wir eine Ansicht, in der alle Daten zu sehen sind, sortiert nach Datum, Zeit und Kontaktperson. Die Spaltenformel fürs Datum lautet @Date(Zeitpunkt) und die für die Zeit @Time(Zeitpunkt). Die Auswahlformel lautet SELECT Form = "Kontakt". Abbildung 1.12 zeigt, wie die Dokumente in der Ansicht angezeigt werden.
Abbildung 1.12: Ansicht »Kontakte«
Wie geht es weiter?
39
1.2 Wie geht es weiter? Mit dieser Grundlage sind Sie jetzt gut ausgerüstet, den kommenden Beispielen zu folgen. Doch zunächst werden Sie über mehrere Kapitel hinweg mit den »Basics« versorgt. Insbesondere ab dem Kapitel »Benutzerinteraktion« werden wir dann auf die soeben aufgebaute Beispielanwendung zurückkommen. Und im Kapitel »Auf Datenbanken und Dokumente zugreifen und sie bearbeiten« werden Sie feststellen, wie nützlich und unverzichtbar die Domino-Klassen sind, um solche Anwendungen aufzubauen. Schließlich wird Ihnen das Kontaktmanagement noch einmal im Kapitel »ODBC-Schnittstelle« über den Weg laufen, wo wir den Zugriff auf eine relationale Datenbank (in diesem Falle Access) vorstellen. Und nun: Viel Spaß mit LotusScript und guten Erfolg!
2 2
Entwicklungsumgebung (IDE)
2.1 Verständnisvoraussetzungen In diesem Kapitel werden keine besonderen Voraussetzungen erwartet.
2.2 Lernziel Sie werden in diesem Kapitel mit der IDE von Notes/Domino bekannt gemacht, insbesondere mit den für einen LotusScript-Entwickler wichtigen Details. Sie sind anschließend in der Lage, mit der IDE schnell und einfach LotusScript-Programme zu entwerfen, wobei Sie vollen Gebrauch von den zahlreichen Unterstützungsfunktionen machen können. Außerdem werden wir den übersichtlichen und einfach zu bedienenden Script-Debugger erläutern.
2.3 Die IDE Gegenüber früheren Versionen wartet die Domino-IDE mit einer ganzen Reihe von interessanten Verbesserungen auf: eine baumartige Anzeige der Modulstruktur, die Markierung der mit Code versehenen Modulabschnitte und -eventhandler, eine größere Übersicht bei den Domino-Objekten, eine bessere Referenz usw.
Abbildung 2.1: Domino-IDE
42
Entwicklungsumgebung (IDE)
Abbildung 2.1 zeigt die Domino-IDE, wie sie sich bei der Programmierung einer LotusScript-Bibliothek präsentiert (je nachdem, welches Gestaltungselement gerade bearbeitet wird, kann das Aussehen leicht variieren). Sie teilt sich in drei Bereiche auf: links der Navigator durch die Gestaltungselemente der Datenbank, in der Mitte die Anzeige der Objektstruktur mit der Referenz und rechts das Programmierfenster. Wir werden diese Bereiche genauer untersuchen.
2.4 Navigator Im Navigator des Designers werden die Gestaltungselemente einer Datenbank in die Gruppen Gliederungen, Rahmengruppen, Seiten, Masken, Ansichten, Ordner, Navigatoren, Agenten und Ressourcen aufgegliedert. Die Gruppe Ressourcen selbst lässt sich durch einen Klick öffnen und auch schließen. Sie ist unterteilt in Bilder, Applets, Teilmasken, Gemeinsame Felder, ScriptBibliotheken und Andere. Um diese Elemente des Navigators sichtbar zu machen, muss die zu bearbeitende Datenbank allerdings erst geöffnet werden. Dies geschieht über die Menüeinträge Datei | Datenbank | Öffnen... Es öffnet sich die in Abbildung 2.2 gezeigte Dialogbox.
Abbildung 2.2: Dialogbox zum Suchen einer zu öffnenden Datenbank
In der Kombobox »Server« wählen Sie aus, auf welcher Maschine die Datenbank liegt, und im Listenfeld ermitteln Sie die dort befindlichen Datenbanken. Sie können auch das gesamte Filesystem des lokalen Rechners über den Button Durchsuchen... nach der gewünschten Datenbank durchlaufen. Nach Auswahl der Datenbank und Klicken auf den Button Öffnen wird diese geöffnet und ein Lesezeichen auf dem Navigator abgelegt. Sollten die vorher beschriebenen Gruppierungen der Gestaltungselemente nicht zu sehen sein, klicken Sie einmal auf den angezeigten Datenbanktitel, um die Liste zu öffnen. Umgekehrt kann die Liste durch einen solchen Klick wieder geschlossen werden.
Objektstruktur und Referenz
43
Im Navigator werden auch die Lesezeichen für weitere geöffnete Datenbanken abgelegt und angezeigt.
2.5 Objektstruktur und Referenz In der Mitte des IDE-Fensters werden die Objektstruktur und eine kontextsensitive Referenz angezeigt. Die Objektstrukturanzeige bietet einen Überblick über alle Abschnitte, die in dem Modul bzw. einem Gestaltungselement definiert sind. So werden z. B. bei einer Maske die Abschnitte »(Options)«, »(Declarations)«, »Initialize«, »Terminate« und die Eventhandler angezeigt. Darüber hinaus werden auch Aktionen, Buttons und alle weiteren Objekte aufgeführt. Dies ist eine wesentliche Verbesserung gegenüber den Vorgängerversionen, denn jetzt müssen Sie die einzelnen Objekte nicht mehr mühsam über eine Kombobox suchen, sondern können sehr effektiv navigieren. Zusätzlich erkennen Sie an den abgedunkelten Symbolen, in welchen Abschnitten sich benutzerdefinierter Code befindet. Wenn Sie eines der Symbole anklicken, wird der Inhalt des betreffenden Abschnitts im rechten Bereich, dem Programmierfenster, angezeigt. Die Referenz bietet einen kontextsensitiven Überblick über die Möglichkeiten, die die jeweilige Sprache und der jeweilige Kontext anbieten. Der Kontext wird von einer Einstellung im Programmierfenster bestimmt, das im nächsten Abschnitt genauer besprochen wird. Zwischen der Anzeige der Objektstruktur und der Referenz wird durch Anklicken der Reiter hin- und hergeschaltet. Ein Beispiel für die Referenzanzeige liefert die folgende Abbildung 2.3.
Abbildung 2.3: Kontextsensitive Referenz
44
Entwicklungsumgebung (IDE)
Im oberen Bereich der Anzeige sehen Sie eine Kombobox, mit der verschiedene Teile der Referenz ausgewählt werden können. Es können Bereiche zur LotusScript-Sprache, zu Domino-spezifischen Erweiterungen (Klassen, Konstanten usw.) und OLE-Klassen geöffnet werden. Wenn zusätzliche LSX-Module eingebunden werden, können auch diese hier eingesehen werden. Wir haben in Abbildung 2.3 den Bereich Domino-Klassen geöffnet. Im Listenfeld werden die Klassen mit ihren Eigenschaften (Properties), Methoden (Methods) und Ereignissen (Events) präsentiert. Durch das Listenfeld kann wie durch eine kategorisierte Notes-Ansicht hindurch navigiert werden. Auf unterster Ebene wird die Syntax der Elemente dargestellt. Diese stellt zugleich ein Codestück dar. Durch Ausführen eines Doppelklicks auf das Codestück oder durch Anklicken des Einfügen-Buttons wird es in das Programmierfenster übernommen. Der übernommene Text wird an die Stelle positioniert, an der der Cursor momentan steht. Es gibt zwei Arten der Codestückübernahme: Volltext oder Hauptbezeichner. Der Volltextmodus wird durch das Optionsfeld Volltext einfügen ausgewählt. Volltext bedeutet, dass die ganze angezeigte Zeile übertragen wird. In Abbildung 2.3 würde dies bei Auswahl der Dokument-Methode AppendItemValue bedeuten, dass folgender Text übernommen wird: AppendItemValue(Byval Itemname As String, Newvalue) As NotesItem
Im anderen Modus wird lediglich der folgende Teil übertragen: AppendItemValue
Der Hilfe-Button öffnet die Designerhilfe.
2.6 Programmierbereich 2.6.1 Editor Je nachdem welches Objekt programmiert wird, können unterschiedliche Sprachen verwendet werden, z. B. LotusScript oder Java. Die jeweiligen Möglichkeiten erfährt man über die Dropdown-Liste »Starten« im oberen Teil des Fensters. Teilweise erkennt man die Programmiermöglichkeiten auch über den vorher erwähnten Mittelteil, die Objektstruktur. Hier wird durch die Verwendung verschiedener Symbole angezeigt, welches Sprachmittel verwendet werden kann. Für LotusScript und Java wird eine Schriftrolle angezeigt, für JavaScript eine Kugel, für die Formelsprache eine Raute und für Notes-Systembefehle (Einfache Aktionen) ein Quadrat oder Würfel. Wenn für ein zu programmierendes Element mehrere Programmiermöglichkeiten bestehen, so wird nach dem Speichern und Wiederöffnen das Symbol angezeigt, das der ausgewählten Programmiersprache entspricht.
Programmierbereich
45
Der Editor ist in der Lage, die Syntax schon während der Eingabe zu überprüfen. Erkannte syntaktische Elemente werden mit verschiedenen Farben dargestellt. Dabei sind Schlüsselworte im Allgemeinen blau, Kommentare grün, Konstanten rosa und als fehlerhaft erkannte Teile rot. Es ist auch möglich, die Farbgebung dem eigenen Geschmack anzupassen. Dazu klicken Sie mit der rechten Maustaste in das Programmierfenster. Es öffnet sich die zugehörige Eigenschaftenbox, wie in Abbildung 2.4 gezeigt.
Abbildung 2.4: Eigenschaftenbox zur Anpassung des IDE-Editors
Wie Sie rechts in der Box sehen, können Sie die Farbe für die einzelnen syntaktischen Komponenten auswählen. Auch der verwendete Schrifttyp kann bestimmt werden. Die Einstellungen können ebenfalls für die Formelsprache und für Einfache Aktionen vorgenommen werden. Wenn Sie den zweiten Reiter wählen, können Sie noch zwei Einstellungen zur Formatierung vornehmen.
Abbildung 2.5: Zweiter Reiter der Eigenschaftenbox des IDE-Editors zur Einstellung der Formatierung von Programmcode
Es klang bei der Besprechung der Eigenschaftenbox schon durch: Seit Notes/ Domino R5 wird auch die Struktur von Formelprogrammen analog dem Erscheinungsbild von LotusScript farblich gekennzeichnet. Dies gehört zwar nicht zum Thema dieses Buches, mag aber doch für den einen oder anderen interessant sein.
46
Entwicklungsumgebung (IDE)
2.6.2 Zeilenumbrüche Zeilenumbrüche werden durch einen Unterstrich (_) erzeugt. Diese dürfen nicht innerhalb von Schlüsselworten oder von Strings und anderen Werten angeordnet werden. Ein Unterstrich zum Erzeugen eines solchen Umbruchs muss immer am Ende der vorhergehenden Zeile stehen und durch mindestens ein Leerzeichen von dem letzten Zeichen der Zeile getrennt sein. Es können mehrere Zeilenumbrüche hintereinander erfolgen. MessageBox _ "Dies ist ein extra langer Text, der deshalb in der Folgezeile steht."
2.6.3 Tabulator Im Gegensatz zu früheren Versionen können Sie unter der Version R5 auch die Tabulatortaste zum Erzeugen von Leerräumen verwenden.
2.6.4 Kommentare Kommentare können auf drei verschiedene Arten eingefügt werden: mit dem Hochkomma, der REM- und der %REM...%ENDREM-Anweisung. Mit den ersten beiden Möglichkeiten können nur einzeilige, mit der dritten auch mehrzeilige Kommentare geschrieben werden. 'Dies ist ein Kommentar (mit Hochkomma eingeleitet) REM Dies ist auch ein Kommentar, REM wobei dies die zweite Zeile ist, die ein neues REM benötigt %REM Dies ist auch ein Kommentar, wobei dies die zweite Zeile ist, die KEIN neues REM benötigt %ENDREM
2.6.5 Hintereinanderhängen von Befehlen Mehrere in eine Zeile geschriebene Befehle und Anweisungen werden durch Doppelpunkte (:) getrennt. Diese Technik ist aufgrund der Übersichtlichkeit nur in Ausnahmefällen zu empfehlen. If nZahl = 1 Then nZahl = 2 : Exit Sub
In diesem Fall werden, wenn die Bedingung nZahl = 1 erfüllt ist, zwei Anweisungen ausgeführt. Als erstes wird der Variablen »nZahl« ein neuer Wert zugewiesen (2) und anschließend wird die Prozedur, in der sich dieser Code befindet, mit »Exit Sub« verlassen.
Debugger
47
2.6.6 Kompilieren und Kompilierfehler Bei jedem Speichern wird Code, der neu eingegeben oder verändert wurde, automatisch kompiliert und auf Kompilierfehler untersucht. Treten solche auf, so werden sie in der unteren Zeile mit der Bezeichnung »Fehler« angezeigt. Wenn es sich um mehrere Fehler handelt, können Sie die Zeile als Kombo-Box öffnen und einen beliebigen Fehler per Mausklick auswählen. Der Cursor des ScriptEditors springt dann genau zu der Zeile, in der der Fehler aufgetreten ist. Wenn Sie an der betreffenden Zeile eine Änderung vornehmen, wird die dazugehörige Fehlermeldung aus der Kombo-Box entfernt. Beim nächsten Abspeichern des Codes wird dann wieder versucht, den veränderten Code zu kompilieren. Code, der nicht kompiliert werden kann, wird auch nicht abgespeichert.
2.7 Debugger Der Debugger in der Domino-IDE hat sich schon in den vergangenen Versionen durch einfache Handhabung und gute Übersicht ausgezeichnet. Mit ihm können komfortabel Laufzeitfehler erkannt und verfolgt werden. Er verfügt über die Möglichkeit, sofort aus dem geschriebenen Code heraus gestartet zu werden. Sie können schrittweise durch den Code gehen oder bestimmte Teile überspringen. Auch Haltepunkte sind möglich, und zwar sowohl solche, die nur für einen einzelnen Aufruf gelten, als auch solche, die fest im Code verankert werden. Während des Durchlaufs hat man zu jeder Zeit einen guten Überblick über sämtliche Variablen, die im jeweiligen Gültigkeitsbereich liegen, und deren Inhalt. Auch kann ihr Wert jederzeit während des Laufs durch Eingabe verändert werden. Was an diesem gelungenen Werkzeug hauptsächlich fehlt, sind bedingte Haltepunkte. Na ja, vielleicht kommt ja auch dieses Feature in nicht allzu ferner Zeit? (Allerdings lassen sich bedingte Haltepunkte durch »harte« Codierung im Programmtext einbinden. Wie dies funktioniert, zeigen wir Ihnen in Kapitel 2.7.2 »Haltepunkte«, Abschnitt »Programmierte Haltepunkte«.)
2.7.1 Start des Debuggers Im Unterschied zu vielen anderen Programmier-Umgebungen wird ein DebugDurchlauf des Programms genauso gestartet wie der normale Ablauf. Allerdings wird der Domino-Client zunächst in den »Debug-Modus« geschaltet: Datei | Extras | Debug LotusScript. Wird jetzt das Programm wie üblich gestartet (Klick auf den Button, der das Script enthält, oder auch Start des Agenten, Öffnen des Dokuments, dessen PostOpen-Event programmiert wurde usw.), dann wird es nach dem Aufruf automatisch in der ersten ausführbaren Zeile stehen bleiben. Der durchlaufene Code wird im oberen weißen Fenster angezeigt. Die nächste ausführbare Zeile ist durch einen kleinen Pfeil auf der linken Seite markiert. Mit vier Schaltflächen kann der Weiterlauf beeinflusst werden.
48
Entwicklungsumgebung (IDE)
Abbildung 2.6: Der Debugger in Aktion
Die Funktionen der Schaltflächen können auch über Menüeinträge aufgerufen werden:
Abbildung 2.7: Menüfunktionen zum Steuern des Debuggers
Debugger
49
F o rt f a h r e n Die Schaltfläche Fortfahren lässt das Script ohne weiteren Halt bis zum nächsten Haltepunkt oder, wenn keiner mehr vorhanden ist, zu Ende laufen. S ch r itt a us f ü h r e n Die Schaltfläche Schritt ausführen reagiert genauso, wie Sie es aufgrund der Bezeichnung erwarten würden: sie führt den nächsten ausführbaren Schritt aus. Wenn zwischen der vorher eingenommenen Cursorposition und der nächsten ausführbaren Zeile nicht ausführbare Zeilen liegen, werden diese übersprungen. Mit Schritt ausführen können Sie auch in aufgerufene Funktionen hineinspringen. S ch r itt ü b e rs p r in g e n Die Schaltfläche Schritt überspringen arbeitet ähnlich wie Schritt ausführen, aber sie springt nicht in Funktionsaufrufe hinein. Dies ist nützlich, um den Code schneller zu durchlaufen und entweder bereits getestete Funktionen zu übergehen oder die Stelle, an der ein Fehler auftritt, schneller zu finden. S ch r itt b ee een nden Wird die Schaltfläche Schritt beenden gewählt, so wird die gerade durchlaufene Funktion oder Prozedur ohne Halt berechnet und zur nächsthöheren Ebene zurückgesprungen. Dort bleibt der Debugger wieder stehen. Wenn es keine höhere Ebene mehr gibt, dann wird auf diese Weise das Programm zu Ende ausgeführt, als wäre der Button Fortfahren angeklickt worden. D e b ug ge r S t o p pe n Mit dem Button Stop wird der Debuglauf abgebrochen. Vor dem endgültigen Abbruch wird zur Sicherheit noch einmal nachgefragt, ob Sie es wirklich ernst meinen.
2. 7.2 H al tep u nkte N ic h tp r o gr amm mmii e r t e H al t e p un kt e Sie können während des Debuglaufs auf jede Zeile mit ausführbarem Code wie folgt einen (nichtprogrammierten) Haltepunkt setzen: entweder die Zeile doppelt anklicken, oder den Cursor (blauer Balken) auf die Zeile setzen und F9 drücken oder im Menü den Punkt Debug | Breakpoint festlegen/löschen. Nichtprogrammierte Haltepunkte bleiben nur während eines Debuglaufs gültig. Sie müssen bei jedem neuen Lauf neu gesetzt werden. Während eines Durchlaufs können Sie zu einzelnen Haltepunkten springen, indem Sie im unteren weißen Fenster den Reiter Breakpoints auswählen und in der Liste der Haltepunkte den gewünschten Punkt anklicken.
50
Entwicklungsumgebung (IDE)
In diesem Abschnitt besprechen wir nur solche nichtprogrammierten Haltepunkte. Programmierte Haltepunkte werden im folgenden Abschnitt abgehandelt. Haltepunkte können aktiviert und deaktiviert werden. Dies geschieht z. B. über das Menü Debug | Breakpoint aktivieren bzw. Debug | Breakpoint deaktivieren. Eine andere Möglichkeit, Haltepunkte zu aktivieren oder zu deaktivieren, ist der Doppelklick auf die Zeile, die den Haltepunkt enthält. Bei mehreren hintereinander ausgeführten Doppelklicks durchwandert eine Zeile bezüglich ihres Haltepunkts drei Zustände in folgender Reihenfolge: aktiviert, deaktiviert, nicht gesetzt (bzw. gelöscht) und (bei weiterem Klicken) wieder von vorne. Auch deaktivierte Haltepunkte werden angesprungen, wenn man sie in dieser Liste auswählt. Wahlweise können über das Menü auch sämtliche Haltepunkte auf einmal aktiviert oder deaktiviert werden. Zum Löschen eines Haltepunktes wählen Sie entweder den Menüpunkt Debug | Breakpoint löschen, oder Sie führen wie oben besprochen auf der betreffenden Zeile ein oder zwei Doppelklicks aus, bis er verschwunden ist. P r og r amm mmii e rt e H al t e pu n kt e Programmierte Haltepunkte werden durch die einfache Script-Anweisung Stop definiert. Sie können damit unbedingte Haltepunkte setzen, indem Sie sie in die entsprechende Zeile schreiben. Entgegen unserer früheren Behauptung können mit Hilfe der Stop-Anweisung in LotusScript auch bedingte Haltepunkte gesetzt werden, allerdings müssen sie bei der Programmierung hart codiert werden. Dazu kombinieren Sie die Stop-Anweisung mit Bedingungsausdrücken. Ein Haltepunkt, der nur dann zum Stoppen führen soll, wenn eine Variable mit Name IsOpen den Wert FALSE aufweist, sieht beispielsweise so aus: If Not IsOpen Then Stop
Die programmierten Haltepunkte führen wie die nicht programmierten nur im Debug-Modus zum Anhalten des Programmlaufs. Im normalen Ablauf sind sie ohne Wirkung.
2. 7.3 A ufr ufe v er fo lg e n In der Mitte zwischen den beiden weißen Bereichen befindet sich eine DropdownListe (»Aufrufe«), die Auskunft über die Position in der Aufrufschachtelung gibt. Der oberste Eintrag gibt den letzten Aufruf, also die momentan tiefste Schachtelungsebene, wieder. Sie können die Ansicht einer bestimmten Aufrufebene anzeigen lassen, indem Sie aus der Dropdownliste einen Eintrag auswählen.
Debugger
51
2.7.4 Weitere Navigationsmöglichkeiten Während eines Debuglaufs möchten Sie manchmal schnell an eine spezielle Stelle im Code gelangen. Dies kann beispielsweise bei der Schachtelung mehrerer Bibliotheken recht schwierig werden. Um ein bestimmtes Modul bzw. Objekt anzusteuern, wählen Sie dieses in der linken Dropdown-Liste oben im Debuggerfenster aus (»Objekt«). Das im Codebereich angezeigte Script wechselt dann auf diesen ausgewählten Eintrag. Innerhalb von Modulen können Sie verschiedene Abschnitte oder Funktionen auswählen, indem Sie die Dropdown-Liste (Ereignis) rechts oben nutzen. Dann wird genau in diesen Abschnitt gesprungen. Diese Navigation dient nur der Information oder dem Setzen und Manipulieren von Haltepunkten. Sie beeinflusst nicht den Ablauf des Debuggings.
2.7.5 Variablenwerte verfolgen und manipulieren V a r i a b le n w e r t e a n se h e n Unterhalb der Aufruf-Liste befindet sich der zweite größere weiße Bereich. Er hat drei Reiter. Der linke Reiter steht wie bereits besprochen für eine Liste der gesetzten Haltepunkte. In diesem Abschnitt ist der mittlere Reiter unser Thema. Er listet die im jeweiligen Gültigkeitsbereich zu »sehenden« Variablen und Konstanten auf. Die Liste ist sehr übersichtlich. In der linken Spalte sehen Sie die Namen der Variablen. Wenn vor einem Namen ein kleines grünes Dreieck erscheint, dann besteht die Variable aus mehreren Elementen. Dies trifft zu bei zusammengesetzten Typen und Objektvariablen, die instanziierte Objekte referenzieren. In der mittleren Spalte werden die Werte angezeigt. Bei zusammengesetzten Typen und Objektvariablen, die instanziierte Objekte referenzieren, wird für jedes Element der entsprechende Wert angezeigt. In Höhe des Namens für die Typ- oder Objektvariable werden zudem in einer eckigen Klammer die Werte der einzelnen Elemente aufgezählt (durch Kommas getrennt). M a n i p u l a t io n d e r V a r ia b l e n w e r te Sie können die Werte der im Debugger angezeigten Variablen für die Dauer des verbleibenden Programmlaufs verändern. Dies kann sehr praktisch sein, beispielsweise um festzustellen, wie sich der weitere Ablauf gestaltet, wenn eine Variable einen bestimmten Wert aufweist. Dies interessiert insbesondere dann, wenn eine Variable an einer bestimmten Stelle einen unerwarteten Wert aufweist, Sie aber vor einer Korrektur des Programms zunächst einmal feststellen wollen, wie sich der weitere Ablauf gestalten würde, wenn der Wert derjenige wäre, den Sie erwartet haben. Um den Wert einer Variablen oder deren Elemente zu verändern, klicken Sie den Namen an. Dann erscheint der Wert in der unten befindlichen Zeile »Neuer Wert«. Sie können jetzt durch Anklicken den Cursor dort hinsetzen und den Wert verändern. Damit er in den Programmlauf übernommen wird, wählen Sie das rechts
52
Entwicklungsumgebung (IDE)
befindliche grüne Häkchen. Zum Rückgängigmachen wählen Sie das rote Kreuzchen. Anschließend können Sie den Debuglauf fortsetzen.
Abbildung 2.8: Sicht auf die Variablen und deren Inhalte
Wenn die Variable einen Text mit Zeilenumbrüchen enthält, dann können Sie in der Zeile »Neuer Wert« zwischen den einzelnen Zeilen navigieren. Noch ein Hinweis: Werte können nur in skalaren Variablen bzw. bei zusammengesetzten Variablen in deren skalaren Elementen bearbeitet werden.
2.8 Probleme So genial der Debugger auch aufgebaut ist, so hat er doch eine recht gravierende Schwachstelle, die einen Programmierer manchmal ziemlich verzweifeln lassen kann: Es kommt im Debug-Modus wesentlich häufiger zu einem harten Absturz als im normalen Ablauf. Bei diesem Absturz wird ein rotes Fenster geöffnet, das im Allgemeinen darauf hinweist, dass ein Objekthandle ungültig ist. Dies ist eine Fehlermeldung, mit der Sie normalerweise nicht viel anfangen werden, außer dass Sie sich darüber ärgern.
Fragen
53
Es lohnt sich in einem solchen Fall, einmal zu testen, ob das Programm ohne den Debug-Modus lauffähig ist. Manchmal hilft es, den fehlerproduzierenden Script-Code per Copy-and-Paste in ein anderes neues Gestaltungselement umzustellen. Den Autoren begegnete einmal eine Teilmaske, die bei einer API-Programmierung ähnliche Abstürze verursachte. Durch Neuerstellen der Maske konnte das Problem behoben werden. Die wesentliche Erkenntnis ist, dass das rote Fenster auf irgendwelche internen Inkonsistenzen hinweist, die mit normalen Methoden kaum zu finden sind. Hier hilft nur, mit solchen unkonventionellen Mitteln wie den beschriebenen auf halbwegs systematische Art die Fehlerquelle einzukreisen und zu eliminieren. Selbst wenn eine solche Fehlersuche manchmal ergebnislos zu sein scheint: Es gibt mit entsprechender Ausdauer immer eine Lösung. Also nicht verzagen und weitermachen. Manchmal hilft auch ein Blick in Foren, die sich mit Lotus-Programmierung befassen, z. B. die Foren von Iris unter www.notes.net (das Iris-Team ist das eigentliche Entwicklerteam von Notes).
2.9 Fragen 1. Wie ist die IDE des Domino-Designers aufgebaut? 2. Wie wird der Debugger gestartet? 3. Wie können Sie einen unbedingten Haltepunkt setzen? 4. Wie setzt man bedingte Haltepunkte? 5. Wie können Sie zu einem bestimmten Haltepunkt springen? 6. Wo werden Variablenwerte verfolgt? 7. Können Sie den Inhalt von Variablen während eines Debuglaufs beeinflussen? 8. Wie können Sie den Code einer bestimmten Aufrufebene einsehen? 9. Wie können Sie den Code einer bestimmten Funktion anzeigen? 10. Welchen Vorteil hat der Stop-Befehl gegenüber anderen Arten von Haltepunkten? 11. Welchen Nachteil hat der Stop-Befehl?
3 3
Grundlegende Datentypen
3.1 Verständnisvoraussetzungen Das Lesen dieses Kapitels erfordert keine besonderen Voraussetzungen.
3.2 Lernziel Das Kapitel macht den Leser mit den grundlegenden Datentypen in LotusScript vertraut. Außerdem wird das allgemeine Vorgehen bei der impliziten und expliziten Deklaration von Variablen erläutert. Der Datentyp String wird im Detail in Kapitel 4 »Der Datentyp String« besprochen.
3.3 Allgemeines zur impliziten und expliziten Deklaration von Variablen Variablen sollten im Normalfall vor ihrer Verwendung deklariert werden. Dies geschieht in LotusScript über die Verwendung der Anweisung Dim. Dabei wird über die Klausel »As Datentyp« oder über ein Suffix (z. B. $, % usw.) der Datentyp der Variablen festgelegt: Dim Text As String Dim Text$ Dim Text
Wie Sie sehen, kann man auf die Angabe des Datentyps auch ganz verzichten. Dann wird bei der Deklaration defaultmäßig der Datentyp Variant angenommen, es sei denn, Sie haben über eine Def...-Anweisung (z. B. DefStr, DefInt usw.) einen anderen Datentyp voreingestellt: DefStr T Dim Text
Hier wurde die Variable Text als Datentyp String angelegt, im oberen Beispiel dagegen als Datentyp Variant. Man kann die Deklaration auch implizit durchführen, d. h. ohne ausdrückliche Anweisung. Dies geschieht, indem eine Variable einfach verwendet wird, z. B.
56
Grundlegende Datentypen
durch eine Wertzuweisung. Für die Angabe des Datentyps gilt dasselbe wie bei der expliziten Deklaration: Zahl = 1234 Zahl% = 1234 DefInt Z Zahl = 1234
Die erste implizite Deklaration legt eine Variable vom Typ Variant an, die zweite und die dritte eine vom Typ Integer. Allerdings zeugt es von besserem Programmierstil, wenn Sie Variablen immer explizit deklarieren. Dies hilft Ihnen vor allem, manchen Laufzeitfehler schneller zu finden. Ansonsten kann es beispielsweise passieren, dass Sie eine Variable verwenden, der nie ein Wert zugewiesen wird. Oder es werden im Falle einer Umbenennung verschiedene Vorkommen einer Variablen vergessen, die dann »in der Luft hängen«. Am besten Sie erzwingen die explizite Deklaration durch Angabe von »Option Declare« im Modulabschnitt »(Options)«.
3.4 Numerische Datentypen 3.4.1 Der Datentyp Integer Der Datentyp Integer wird verwendet, um ganzzahlige Werte von –32.768 bis 32.767 aufzunehmen. Dazu belegt er 2 Byte im Speicher. Eine Deklaration kann mit der Dim ... As Integer-Anweisung oder durch das Suffix % erfolgen. Außerdem kann über die Anweisung DefInt Integer als Defaulttyp für Variablen-Deklarationen festgelegt werden. Dim Wert1 As Integer Diese Anweisung deklariert die Variable Wert1 als Integer-Variable. Wert2% = 123
Hier wird die Variable durch das Typensuffix % als Integervariable deklariert. Defint W-Z Wert3 = 100
Die Variable Wert3 hat hier den Datentyp Integer, weil die Anweisung Defint den Datentyp Integer für alle Variablen mit den Anfangsbuchstaben W bis Z festlegt. Mit Integerwerten können alle mathematischen Operationen ausgeführt werden. Bei einer Wertzuweisung einer Zahl mit Nachkommastellen wird die Zahl entsprechend gerundet.
Numerische Datentypen
57
Dim Wert As Integer Wert = 2.5 MessageBox Wert
Ausgegeben wird der Wert 2. F e h le r q u e ll e n Es gibt zwei häufige Fehlermeldungen bei der Verwendung von Integervariablen: Overflow- sowie Type Mismatch-Fehler. Der Overflow-Fehler Beim Speichern des Programms meldet der Compiler den
Fehler Overflow, wenn versucht wird, einer Integer-Variable einen Wert zuzuweisen, welcher nicht in ihrem Wertebereich liegt. Das heißt ein Wert kleiner als – 32.768 oder größer als 32.767. Dieser Fehler kann auch zur Laufzeit auftreten, wenn eine solche unzulässige Zuweisung versucht wird. Wert% = 40000
Diese Wertzuweisung erzeugt einen Overflow-Fehler. Der Type Mismatch-Fehler Dieser Fehler deutet auf den Versuch hin, einer Integer-
variablen einen Wert mit einem fremden Datentyp wie z. B. einer Zeichenkette zuzuweisen. Auch dieser Fehler kann während der Kompilierung und während der Laufzeit auftreten. Wert% = "Hallo" Diese Wertzuweisung erzeugt einen Type Mismatch-Fehler.
3. 4.2 D e r D ate nty p L o ng Long ist ein weiterer ganzzahliger Datentyp. Long belegt 4 Byte und kann dadurch ganzzahlige Werte von –2.147.483.648 bis 2.147.483.647 beinhalten. Sein Suffix bei der impliziten Deklaration ist das &-Zeichen. Dim Wert As Long
Diese Anweisung deklariert die Variable Wert1 als Variable vom Typ Long. Wert2& = 100 Die Variable Wert2 wird durch das Suffixzeichen als Longvariable deklariert. DefLng W-Z Wert3 = 100
Die Variable Wert3 hat hier den Datentyp Long, weil die Anweisung DefLng den Datentyp Long für alle Variablen mit den Anfangsbuchstaben W bis Z festlegt. Auch bei dem Datentyp Long werden Werte mit Nachkommastellen bei einer Zuweisung gerundet.
58
Grundlegende Datentypen
F e h le r q u e ll e n Die Fehlerquellen sind die gleichen wie beim Datentyp Integer: Overflow- sowie Type Mismatch-Fehler. Der Overflow-Fehler Wird das Programm gespeichert, meldet der Compiler den
Fehler Overflow, wenn versucht wird, einer Long-Variablen einen Wert außerhalb des Long-Wertebereichs zuzuweisen. Dieser liegt zwischen -2.147.483.647 und 2.147.483.648. Dieser Fehler kann auch während des Programmlaufs auftreten, wenn eine unzulässige Zuweisung versucht wird. Wert& = -3000000000000
Diese Wertzuweisung erzeugt einen Overflow-Fehler. Der Type Mismatch-Fehler Dieser Fehler tritt auf, wenn versucht wird, einer Long-
Variablen einen fremden Datentyp wie beispielsweise eine Zeichenkette zuzuweisen. Auch dieser Fehler kann während der Kompilierung und während der Laufzeit auftauchen. Wert& = "Hallo"
Diese Wertzuweisung erzeugt einen Type Mismatch-Fehler.
3. 4.3 D e r D ate nty p S ing l e Single ist der kleinste nicht ganzzahlige Datentyp in LotusScript. Single belegt 4 Byte im Speicher. Der Wertebereich Single liegt zwischen –3,402823E+38 und 3,402823E+38. Für die implizite Deklaration mit einem Suffixzeichen wird bei dem Datentyp Single das !-Symbol verwendet. Dim Wert1 As Single Deklariert die Variable Wert1 als Single-Datentyp. Wert2! = 100 Deklariert die Variable Wert2 als Single-Datentyp und weist ihr den Wert 100 zu. DefSng W Legt für alle Variablen mit dem Anfangsbuchstaben W den Standarddatentyp Single fest.
F e h le r q u e ll e n Overflow und Type Mismatch. Der Overflow-Fehler Bei der Speicherung des Programms meldet der Compiler
einen Overflow, wenn versucht wird, einer Single-Variablen Werte außerhalb des Single-Wertebereichs zuzuweisen. Dieser liegt zwischen -3.402823E+38 und 3,402823E+38. Dieser Fehler kann auch während des Programmlaufs auftreten, wenn eine unzulässige Zuweisung versucht wird. Wert! = -3000000000000^40
Diese Wertzuweisung erzeugt einen Overflow-Fehler.
Numerische Datentypen
59
Der Type Mismatch-Fehler Dieser Fehler tritt auf, wenn versucht wird, einer Sin-
gle-Variablen einen fremden Datentyp wie beispielsweise eine Zeichenkette zuzuweisen. Dieser Fehler kann während der Kompilierung und während der Laufzeit auftauchen. Wert! = "Hallo"
Diese Wertzuweisung erzeugt einen Type Mismatch-Fehler.
3.4.4 Der Datentyp Double Der Datentyp Double ist der größte nicht ganzzahlige Datentyp in LotusScript. Er belegt 8 Byte im Speicher. Der Wertebereich umfasst –1,77975931348623158E+308 bis 1,77975931348623158E+308. Sein Suffixzeichen ist das #-Symbol. Dim Wert1 As Double
Diese Anweisung deklariert die Variable Wert1 als Double-Variable. Wert2! = 100
Auch die Variable Wert2 wird durch das Suffixzeichen als Double-Variable deklariert. DefDbl W-Z Wert3 = 100
Die Variable Wert3 hat hier den Datentyp Double, weil die Anweisung DefDbl diesen Datentyp für alle Variablen mit den Anfangsbuchstaben W bis Z festlegt. F e h le r q u e ll e n Auch hier treten häufig die Fehlermeldungen Overflow sowie Type Mismatch auf. Der Overflow-Fehler Bei der Speicherung des Programms meldet der Compiler
den Fehler Overflow, wenn versucht wird, einer Double-Variablen einen Wert außerhalb des Double-Wertebereichs zuzuweisen. Dieser liegt zwischen -1,77975931348623158E+308 und 1,77975931348623158E+308. Der OverflowFehler kann auch während des Programmlaufs auftreten, wenn eine unzulässige Zuweisung versucht wird. Da der Datentyp Double den größten Wertebereich hat und somit die größten und kleinsten Zahlen speichern kann, muss sich der Entwickler bei Auftreten dieser Meldung vermutlich einige Gedanken über seine Variablenstruktur machen. Die Frage lautet dann: Wie kann man die gewünschten großen Zahlen anders darstellen? Wert# = -3000000000000^308
Diese Wertzuweisung erzeugt einen Overflow-Fehler.
60
Grundlegende Datentypen
Der Type Mismatch-Fehler Dieser Fehler tritt auf, wenn versucht wird, einer
Double-Variablen einen fremden Datentyp wie beispielsweise eine Zeichenkette zuzuweisen. Dieser Fehler kann wieder während der Kompilierung oder auch zur Laufzeit auftreten. Beispiel: Wert# = "Hallo"
Diese Wertzuweisung erzeugt einen Type Mismatch-Fehler.
3.4.5 Der Datentyp Currency Der Datentyp Currency hat einen speziellen Wertebereich: er umfasst die Zahlen von -922.337.203.685.477,5807 bis 922.337.203.685.477,5807, und zwar jeweils alle Zahlen mit 4 Nachkommastellen. Sein Suffix ist das Zeichen @. Eine Variable dieses Datentyps belegt 8 Byte. Dim Wert1 As Currency
Diese Anweisung deklariert die Variable Wert1 als Currency-Variable. Wert2@ = 100
Auch die Variable Wert2 wird durch das Suffixzeichen als Currency-Variable deklariert. DefCur W-Z Wert3 = 100
Die Variable Wert3 hat hier den Datentyp Currency, weil die Anweisung DefCur den Datentyp Currency für alle Variablen mit den Anfangsbuchstaben W bis Z festlegt. F e h le r q u e ll e n Die zwei häufigsten Fehlermeldungen bei der Verwendung lauten: Overflow- oder auch Type Mismatch-Fehler. Der Overflow-Fehler Bei der Speicherung des Programms meldet der Compiler
einen Overflow, wenn versucht wird, einer Currency-Variablen einen Wert außerhalb des Currency-Wertebereichs zuzuweisen. Das heißt, einen Wert kleiner als -922.337.203.685.477,5807 oder größer als 922.337.203.685.477,5807. Dieser Fehler kann auch während des Programmlaufs auftreten, wenn eine unzulässige Zuweisung versucht wird. Wert@ = -3000000000000000000000000
Diese Wertzuweisung erzeugt einen Overflow-Fehler.
Der Datentyp Variant
61
Der Type Mismatch-Fehler Dieser Fehler tritt auf, wenn versucht wird, einer Cur-
rency-Variablen einen fremden Datentyp wie beispielsweise eine Zeichenkette zuzuweisen. Er kann während der Kompilierung und während der Laufzeit auftauchen. Wert@ = "Hallo"
Diese Wertzuweisung erzeugt einen Type Mismatch-Fehler.
3.4.6 Numerischer Typenwandel Jeder numerische Datentyp kann jedem anderen numerischen Datentyp zugewiesen werden. Wenn ein Wert mit Nachkommastellen einer Variable mit einem Datentyp ohne Nachkommastellen zugewiesen wird, werden die Nachkommastellen vorher gerundet. Wert% = 10.5 Messagebox Wert%
'Liefert 10
3.4.7 Zusammenfassung numerischer Datentypen Datentyp Integer Long Single Double Currency
Speichergröße 2 Byte 4 Byte 4 Byte 8 Byte 8 Byte
Nachkomma Nein Nein Ja Ja Ja
Min -32.768 2.147,483.648 3,402823E+38 -1,7976931348623158+308 -922.337.203.685.477,5807
Max 32.767 2.147,483.647 3,402823E+38 1,7976931348623158+308 922.337.203.685.477,5807
3.5 Der Datentyp Variant Der Datentyp Variant belegt 16 Byte im Speicher und kann jeden anderen Datentyp außer benutzerdefinierten Typen aufnehmen. Trotz der erwähnten Einschränkung kann einem Variant jedes Objekt, also auch jedes benutzerdefinierte Objekt, zugewiesen werden. Jede Variable, die ohne eine Typangabe deklariert wird, hat den Datentyp Variant. (Ausnahme: Variablen, die aufgrund einer DefType-Anweisung einen anderen Default-Typ haben.) Bei der Initialisierung wird die Variable mit dem Wert EMPTY versehen. Dim WertA As Variant Dim WertB
Beide Variablen werden als Variant-Variablen deklariert und mit dem Wert EMPTY initialisiert. Der Wert einer Variant-Variablen wird im Speicher auf 8 Byte ausgerichtet.
62
Grundlegende Datentypen
Z u we i s u n g vo n W e r t e n a us V a r i a n t va r ia b l e n a n a n d e re D a t e n t y p e n Variant-Variablen können zwar im Rahmen ihrer Möglichkeiten alle Werte aus anderen Variablen aufnehmen, aber anders herum ist eine Zuweisung nicht immer möglich. Dies hängt davon ab, ob die Zielvariable einen Datentyp aufweist, der zu dem zu übergebenden Wert »passt«. Dim WertA As Integer Dim WertB As String Dim WertC As Variant WertA = 100 WertB = "Hallo" WertC = WertA MsgBox WertC WertC = WertB MsgBox WertC
Die Variable WertA wird als Integer deklariert und mit dem Wert 100 belegt. Variable WertB ist vom Typ STRING und bekommt die Zeichenkette »Hallo« zugewiesen. Nach der ersten Zuweisung an die Variable WertC wird die Zahl 100 ausgegeben. Die zweite Ausgabe nach der zweiten Zuweisung gibt die Zeichenkette »Hallo« aus. Außerdem kann eine Variant-Variable den Wert NULL oder EMPTY annehmen. Der Wert EMPTY wird bei numerischen Operationen zu 0 gewandelt. Bei Stringoperationen wird der Wert zu einem Leerstring ("") gewandelt.
X
X
Um den Datentyp des aktuell gespeicherten Wertes in einer Variant-Variablen zu ermitteln, können die beiden Funktionen DataType und TypeName eingesetzt werden. Die Funktion DataType liefert einen numerischen Wert zurück. Syntax der DataType-Funktion: DataType ( expression ) TypeName gibt eine Zeichenkette mit dem Datentyp des Ausdrucks zurück. Syntax der TypeName-Funktion: TypeName ( expression ) Dim Kette As String Dim Zahl As Integer Dim Element As Variant Kette = Element 'Kette beinhaltet danach eine leere 'Zeichenkette Zahl = Element 'Die Variable Zahl beinhaltet nach der 'Zuweisung den Wert 0 Element = Kette MessageBox DataType(Element) 'Liefert eine 8 zurück Element = Zahl MessageBox TypeName(Element) 'Liefert den Wert "INTEGER" zurück
Fragen
63
3.6 Fragen 1. Was verstehen Sie unter einer impliziten und unter einer expliziten Deklaration von Variablen? 2. Wie werden unter LotusScript implizite und explizite Deklarationen von Variablen durchgeführt? 3. Welche Deklarations-Art sollte im Sinne von Programmlesbarkeit und Fehlervermeidung verwendet werden? Wie können Sie diese Art erzwingen? 4. Wie wird bei der Deklaration der Datentyp einer Variablen angegeben? 5. Wann wird der Datentyp gemäß der Voreinstellung verwendet? 6. Wie kann der Datentyp durch Voreinstellung festgelegt werden? 7. Welche numerischen Datentypen unter LotusScript kennen Sie? 8. Was ist ein Variant? 9. Welche Fehler treten häufig beim Gebrauch von Variablen auf?
4 4
Der Datentyp String
4.1 Verständnisvoraussetzungen In diesem Kapitel werden die allgemeinen Kenntnisse zur Variablen-Deklaration in LotusScript vorausgesetzt, wie sie in Kapitel 3.3 »Allgemeines zur impliziten und expliziten Deklaration von Variablen« erläutert wurden.
4.2 Lernziel Das Kapitel zeigt den Umgang mit Zeichenketten unter LotusScript auf.
4.3 Vorbemerkung Für das Verarbeiten von Zeichenketten wird in LotusScript der Datentyp String benutzt. Intern wird in LotusScript der Zeichencode im so genannten UNICODEFormat gespeichert. Dies bedeutet, dass für jedes Zeichen der Zeichenkette jeweils 2 Byte Speicherplatz belegt werden. Bei der Verwendung der Systemoption wird die Zeichenkette in das plattformabhängige Systemformat umgewandelt. Die Zeichenkette belegt pro Zeichen 2 Byte Speicherplatz.
4.4 Implizite und explizite Deklaration Die explizite Deklaration einer Variable als String erfolgt mit der Dim-Anweisung durch Angabe des Datentyps String oder durch das Suffix $. Sie können das Suffix $ auch ohne die Dim-Anweisung zur Festlegung des Datentyps bei einer impliziten Variablen-Deklaration verwenden. Die implizite Deklaration können Sie mit der DefStr-Anweisung für eine Gruppe von Variablen auf den Datentyp String voreinstellen. Die explizite Deklaration einer Variable vom Datentyp String erfolgt entweder mit Dim ... As String oder mit Dim in Verbindung mit dem Suffix $. Die implizite Deklaration kann durch DefStr auf den Typ String voreingestellt werden und erfolgt ansonsten durch Verwendung des Suffix $(ohne Dim). Weitere Einzelheiten zur impliziten und expliziten Variablen-Deklaration siehe Kapitel 3.3, »Allgemeines zur impliziten und expliziten Deklaration von Variablen«.
66
Der Datentyp String
4.5 Dynamische und statische Zeichenkette LotusScript kennt zwei Arten von Zeichenketten. Die statische Zeichenkette hat eine feste Anzahl von Zeichen. Die dynamische Zeichenkette besteht aus einer variablen Anzahl von Zeichen. Dynamische Zeichenketten können eine variable Anzahl von Zeichen aufnehmen, statische Zeichenketten dagegen bestehen aus einer festen Anzahl von Zeichen. Die Art der Zeichenkette wird durch ihre Deklaration bestimmt. Implizit deklarierte Variablen vom Datentyp String sind immer dynamische Zeichenketten. Statische Zeichenketten werden bei der expliziten Deklaration mit Dim durch die Angabe der Länge festgelegt. Implizit deklarierte Zeichenketten sind immer dynamische Zeichenketten.
Syntax Dim: { Dim | Static | Public | Private } variableName As String [ * length ] Dim ZeichenketteA As String Dim ZeichenketteB As String * 10 ZeichenketteC$ = "Hallo"
'dynamische Zeichenkette 'statische Zeichenkette 'dynamische Zeichenkette
Defstr Z ZeichenketteD = "Hallo"
'dynamische Zeichenkette
4.6 Initialisierung von Zeichenketten Alle Variablen vom Datentyp String werden bei ihrer Deklaration automatisch initialisiert. Dabei wird einer dynamischen Zeichenkette der Wert Leerstring ("") zugewiesen. Eine statische Zeichenkette wird bei der Deklaration mit der der angegebenen Länge entsprechenden Anzahl von Leerzeichen aufgefüllt.
4.7 Verwendung von statischen Zeichenketten Statische Zeichenketten mit fester Länge werden häufig bei Übergabepunkten zu C-Routinen oder bei I/O-Operationen (Eingabe-/Ausgabeoperationen) verwendet.
Funktionen und Anweisungen für Zeichenketten
67
4.8 Funktionen und Anweisungen für Zeichenketten 4.8.1
Die Funktionen Len, LenB, LenBP und LenC
Die Funktion Len Mit der Funktion Len wird die Länge einer Zeichenkette ermittelt. Bei einer dynamischen Zeichenkette ist dies die Anzahl der Zeichen des aktuellen Wertes. Bei einer statischen Zeichenkette gibt Len die Länge zurück, die bei der Deklaration angegeben wurde. Syntax Len: Len ( text$ ) Dim Kette1 As String * 10 Dim Kette2 As String Kette1 = "Hallo" Kette2 = "Welt" Print Len(Kette1) Print Len(Kette2)
'Liefert 10 'Liefert 4
Die Funktion LenB Diese Funktion liefert die Größe des Speicherbereiches zurück, welchen die Zeichenkette einnimmt. Angabe in Bytes. Die Funktion LenBP Mit dieser Funktion erhält man die Größe des Speicherbereiches, welcher benötigt wird, um die Zeichenkette im plattformabhängigen Format zu speichern. Angabe in Bytes. Die Funktion LenC Die Funktion LenC wird bei spaltenorientierten Sprachen verwendet, wie z. B. Thailändisch. Sie gibt die Länge einer Zeichenspalte in Anzahl der Zeichen zurück.
4.8.2
Die Funktionen Left und Right
Die Funktion Left liefert den linken und die Funktion Right den rechten Teil eines Strings. Den Funktionen wird der Quellstring und die gewünschte Anzahl der Stellen übergeben. Bei der Rückgabe ist zwischen einem dynamischen und einem statischen Quellstring zu unterscheiden. Für die Auswertung eines statischen Strings ist zu beachten, dass er am Ende mit den Füllzeichen bis zur deklarierten Länge aufgefüllt ist. Sollte die Länge des übergebenen Quellstrings kleiner als die gewünschte Anzahl der Stellen sein, wird der gesamte Quellstring zurückgegeben. Die Funktionen LeftB, LeftBP und LeftC arbeiten analog. Die Unterschiede liegen in der Inter-
68
Der Datentyp String
pretation der Längenangaben. Sie werden analog zu den Spielarten der Len-Funktion in Unicode-Bytes, Bytes im plattformabhängigen Codesystem und Zeichenanzahl der Spalte gemessen. Syntax Left: Left[$] ( text$, length ) Syntax Right: Right[$] ( text$, length ) Dim Kette1 As String * 10 Dim Kette2 As String Kette1 = "Hello" Kette2 = "Welt" Msgbox Right$(Kette1, 6) Msgbox Right$(Kette2, 2) Msgbox Left$(Kette1, 6) Msgbox Left$(Kette2, 2)
4.8.3
'Liefert 'Liefert 'Liefert 'Liefert
'o' lt Hello We
Die Funktion Mid
Die Funktion Mid liefert einen Teilstring aus einer Zeichenkette zurück. Hierfür wird die Zeichenkette, die Startposition und die gewünschte Länge übergeben. Sollte der gewünschte Teilstring teilweise außerhalb der Ausgangszeichenkette liegen, werden wie bei Left und Right die Zeichen des Quellstrings zurückgegeben, die innerhalb des Bereichs liegen, der für den Teilstring angegeben wurde. Dies bedeutet einfacher ausgedrückt: Es wird einfach das zurückgegeben, was verfügbar ist und innerhalb des gewünschten Bereichs liegt. Auch bei dieser Funktion existieren Varianten bezüglich der Längenangaben in Form von MidB, MidBP, MidC. Nähere Angaben dazu finden Sie bei der Beschreibung der Len-Funktion in Abschnitt 4.8.1. Syntax Mid: Mid[$] ( text$, begin [, length ] ) Dim Kette1 As String * 10 Dim Kette2 As String Kette1 = "Hallo" Kette2 = "Welt" Msgbox Mid$(Kette1, 5, 2) Msgbox Mid$(Kette2, 3, 2)
'liefert "o " 'liefert "lt"
Funktionen und Anweisungen für Zeichenketten
4.8.4
69
Die Operationen RSet und LSet
Die Schlüsselworte RSet und LSet dienen bei Zuweisungen an statische Strings dazu, die Zeichenkette entweder links- oder rechtsbündig auszurichten. Syntax RSet und LSet: RSet variable = text$ LSet variable = text$ Dim Kette As String * 10 RSet Kette = "Hallo" Msgbox "-" + Kette + "-"
4.8.5
'liefert "-
Hallo-"
Die Funktionen LTrim, RTrim und Trim
Die Funktion LTrim entfernt führende Leerzeichen aus einem String. Am Ende abschließende Leerzeichen werden durch RTrim entfernt. Bei dem Aufruf von Trim werden sowohl führende als auch alle abschließenden Leerzeichen entfernt. Syntax LTrim, RTrim, Trim: LTrim ( text$ ) RTrim ( text$ ) Trim ( text$ ) Dim Kette As String Kette = " Hallo Msgbox LTrim(Kette) Msgbox RTrim(Kette) Msgbox Trim(Kette)
4.8.6
" 'liefert "Hallo " 'liefert " Hallo" 'liefert "Hallo"
Die Funktionen LCase und UCase
Die Funktion LCase wandelt alle Großbuchstaben einer Zeichenkette zu Kleinbuchstaben um. Umgekehrt wandelt die Funktion UCase alle Kleinbuchstaben in Großbuchstaben um. Syntax LCase und UCase: LCase[$] ( text$ ) RCase[$] ( text$ ) Print LCase("Hallo") Print UCase("Hallo")
'liefert hallo 'liefert HALLO
70
Der Datentyp String
4.8.7
Die Funktion Str
Die Funktion Str wandelt einen Ausdruck in eine Zeichenkette um. Syntax Str: Str[$] ( numericValue ) Print Str(100)
4.8.8
'liefert "100"
Die Funktionen StrCompare und StrComp
StrCompare und StrComp repräsentieren dieselbe Funktion. Sie vergleicht zwei Zeichenketten und liefert das Ergebnis als numerischen Wert zurück. Dabei ist es möglich, die Vergleichsmethode auszuwählen. Syntax StrCompare und StrComp: StrCompare ( text1$, text2$ [, comparisonMethod ] ) StrComp ( text1$, text2$ [, comparisonMethod ] ) Dabei sind folgende Vergleichsmethoden möglich: Wert
Groß-/Kleinschreibung
Pitch
0
relevant
relevant
1
nicht relevant
relevant
4
relevant
nicht relevant
5
nicht relevant
nicht relevant
Als Ergebnis können folgende Werte zurückgeliefert werden: Mindestens eine der übergebenen Zeichenketten ist NULL
NULL
Zeichenkette1 ist kleiner Zeichenkette2
-1
Zeichenkette1 ist gleich Zeichenkette2
0
Zeichenkette1 ist größer Zeichenkette2
1
Print Print Print Print
StrCompare("A", "b", 0) StrCompare("A", "a", 1) StrCompare("A", "A", 0) StrCompare(NULL, "A", 0)
'liefert 'liefert 'liefert 'liefert
–1 0 0 NULL
Funktionen und Anweisungen für Zeichenketten
4.8.9
71
Die Funktion StrConv
Diese Funktion wandelt eine Zeichenkette in verschiedene Zeichensätze um. Dabei werden der Quellstring und das bzw. die gewünschten Formate angegeben. Syntax StrConv: StrConv ( text$ , convertType ) Dabei gibt es folgende Konvertierungstypen: Wert
Typ der Konvertierung
1
Großbuchstaben
2
Kleinbuchstaben
3
Erster Buchstabe groß, Rest klein
4
Einzelbyte zu Zweibyte
8
Zweibyte zu Einzelbyte
16
Hiragana zu Katakana
32
Katakana zu Hiragana
Print StrConv("abc", 3)
'liefert "Abc"
4.8.10 StrLeft, StrLeftBack, StrRight und StrRightBack D i e F u n k t io n St r L e f t Die Funktion StrLeft sucht einen Teilstring in einem gegebenen Quellstring, beginnend von links. Wenn der Teilstring im Quellstring gefunden wird, werden alle Zeichen aus dem Quellstring ausgegeben, welche links von dem Teilstring stehen. Außerdem kann eine Anzahl bestimmt werden, welche beschreibt, wie häufig die Zeichenkette gefunden werden muss, damit eine Ausgabe erfolgt. Ein Flag bestimmt die Vergleichsmethode analog zur Funktion StrCompare (siehe dort). Syntax StrLeft: StrLeft ( text1$, text2$ [, flag% [, count ]] ) Print StrLeft("Eins Zwei Eins Drei", "Zwei") 'liefert "Eins " Print StrLeft("Eins Zwei Eins Drei", "Eins", 0, 2) 'liefert "Eins Zwei "
D i e F u n k t io n St r R ig h t Die Funktion StrRight sucht einen Teilstring in einem gegebenen Quellstring, beginnend von links. Wenn der Teilstring im Quellstring gefunden wird, werden alle Zeichen aus dem Quellstring ausgegeben, welche rechts von dem Teilstring stehen. Außerdem kann eine Anzahl bestimmt werden, welche beschreibt, wie häufig
72
Der Datentyp String
die Zeichenkette gefunden werden muss, damit eine Ausgabe erfolgt. Ein Flag bestimmt die Vergleichsmethode analog zur Funktion StrCompare (siehe dort). Syntax StrRight: StrRight ( text1$, text2$ [, flag% [, count ]] ) Print StrRight("Eins Zwei Eins Drei", "Zwei") 'liefert " Eins Drei" Print StrRight("Eins Zwei Eins Drei", "Eins", 0, 2) 'liefert " Drei"
D i e F u n k t io n St r L e f tB a c k Die Funktion StrLeftBack sucht einen Teilstring in einem gegebenen Quellstring, beginnend von rechts. Wenn der Teilstring im Quellstring gefunden wird, werden alle Zeichen aus dem Quellstring ausgegeben, welche links von dem Teilstring stehen. Außerdem kann eine Anzahl bestimmt werden, welche beschreibt, wie häufig die Zeichenkette gefunden werden muss, damit eine Ausgabe erfolgt. Der Flag bestimmt die Vergleichsmethode analog zur Funktion StrCompare (siehe dort). Syntax StrLeftBack: StrLeftBack ( text1$, text2$ [, flag% [, count ]] ) Print StrLeftBack("Eins Zwei Eins Drei", "Zwei") 'liefert "Eins " Print StrLeftBack("Eins Zwei Eins Drei", "Eins", 0, 2) 'liefert ""
D i e F u n k t io n St r R ig h t Ba c k Die Funktion StrRightBack sucht einen Teilstring in einem gegebenen Quellstring von rechts beginnend. Wenn der Teilstring im Quellstring gefunden wird, werden alle Zeichen aus dem Quellstring ausgegeben, welche rechts von dem Teilstring stehen. Außerdem kann eine Anzahl bestimmt werden, welche beschreibt, wie häufig die Zeichenkette gefunden werden muss, damit eine Ausgabe erfolgt. Das Flag bestimmt die Vergleichsmethode analog zur Funktion StrCompare (siehe dort). Syntax StrRightBack: StrRightBack ( text1$, text2$ [, flag% [, count ]] ) Print StrRightBack("Eins Zwei Eins Drei", "Zwei") 'liefert " Eins Drei" Print StrRightBack("Eins Zwei Eins Drei", "Eins", 0, 2) 'liefert " Zwei Eins Drei"
Funktionen und Anweisungen für Zeichenketten
73
4.8.11 Die Funktion String Der Funktion String wird ein Zeichencode oder String und eine Anzahl übergeben. Als Rückgabe erhält man einen Zielstring, welcher das als Zeichencode übergebene Zeichen oder das erste Zeichen des Quellstrings in der übergebenen Anzahl enthält. Syntax String String[$] ( length, { charCode | text$ } ) Print String(5, "A") Print String(5, 69)
'liefert "AAAAA" 'liefert "EEEEE"
4.8.12 Die Funktionen InStr, InstrB, InstrBP und InstrC Die Funktion InStr bzw. die Varianten für die entsprechenden Zeichensätze werden verwendet, um in einem Quellstring einen Teilstring zu suchen und dessen Position zurückzugeben. Es kann die Anfangsposition der Suche und die Vergleichsmethode bestimmt werden. Syntax InStr: InStr ( [ start, ] text1$, text2$, [ comparisonType ] ) Print InStr("Test Test", "es") Print InStr(4, "Test Test", "es")
'liefert 2 'liefert 7
4.8.13 Die Anweisung Option Compare Die Anweisung Option Compare dient dazu, die Standardvergleichsmethode bei Zeichenkettenvergleichen festzulegen. Option
Beschreibung
Option Compare Binary
Vergleich erfolgt auf binärer Ebene
Option Compare Case
Groß-/Kleinschreibung ist relevant
Option Compare NoCase
Groß-/Kleinschreibung ist nicht relevant
Option Compare Pitch
Die Größe ist relevant
Option Compare NoPitch
Die Größe ist nicht relevant
4.8.14 Die Funktion Space Die Funktion Space liefert einen String mit einer angegebenen Anzahl von Leerzeichen zurück. Syntax Space: Space[$] ( numberValue# ) Print "-"+Space(4)+"-"
'liefert "-
-"
74
Der Datentyp String
4.8.15 Die Funktion Val Die Funktion wandelt eine Zeichenkette in einen numerischen Wert um. Es wird versucht, den Inhalt der übergebenen Zeichenkette als Zahl zu interpretieren. Syntax Val: Val ( text$ ) Print Val("100")
'liefert 100
4.8.16 Die Funktion Asc Die Funktion liefert den plattformabhängigen numerischen Zeichencode für ein Zeichen zurück. Syntax Asc: Asc ( text$ ) Print Asc("E")
'liefert 69
4.8.17 Die Funktion Chr Die Funktion Chr liefert das Zeichen zurück, welches einem plattformabhängigen numerischen Zeichencode entspricht. Syntax Chr: Chr[$] ( numberValue& ) Print Chr(69)
'liefert E
4.8.18 Die Funktion UChr Die Funktion UChr liefert das Zeichen, welches dem numerischen UNICODE-Zeichencode entspricht. Syntax UChr: UChr[$] ( numberValue& ) Print UChr(69)
'liefert E
Operatoren für das Handling von Zeichenketten
75
4.8.19 Die Funktion Uni Liefert den numerischen UNICODE-Code für das erste Zeichen im übergebenen String zurück. Syntax Uni: Uni ( text$ ) Print
Uni("Hallo")
'liefert 72
4.8.20 Die Funktion UString Der Funktion UString wird eine Anzahl und ein UNICODE-Zeichencode oder ein Quellstring übergeben. Als Rückgabe erhält man einen Zielstring, welcher das als Zeichencode übergebene UNICODE-Zeichen oder das erste Zeichen des Quellstrings in der übergebenen Anzahl enthält. Syntax Funktion UString: UString[$] ( length, { charCode | text$ } ) Print UString(5, "A")
'liefert "AAAAA"
4.9 Operatoren für das Handling von Zeichenketten 4.9.1
Konkatenationsoperatoren
Unter einem Konkatenationsoperator versteht man einen Operator, der für das Aneinanderhängen von zwei Zeichenketten steht. In LotusScript sind das die Symbole & und +. Konkatenation von Zeichenketten bedeutet Aneinanderhängen. In LotusScript gibt es dafür die Symbole & und +.
4.9.2
Vergleichsoperatoren
Bei den Vergleichsoperatoren wird die Einstellung beachtet, die ggf. mit der Anweisung Option Compare getroffen wurde. Mit dieser Anweisung bestimmt man, ob die Groß-/Kleinschreibung bei einem Vergleich relevant ist. Operator
Bedeutung
=
Gleich
<> oder ><
Ungleich
<
In der Sortierreihenfolge vorher
76
Der Datentyp String
Operator
Bedeutung
<= oder =<
In der Sortierreihenfolge vorher oder gleich
>
In der Sortierreihenfolge nachher
>= oder =>
In der Sortierreihenfolge nachher oder gleich
Like
Beinhaltet
4.10 Übergabe von Zeichenketten als Parameter 4.10.1 Übergabe per Referenz Bei der Übergabe einer Zeichenkette per Referenz wird ein 4 Byte langer Pointer (Zeiger) auf den internen Speicherbereich übergeben, in welchem die Zeichenkette im LotusScript-Format gespeichert ist. Wenn diese Übergabe bei dem Aufruf einer externen C-Funktion verwendet wird, treten Probleme auf, da unter Programmiersprachen wie C die Struktur einer Zeichenkette anders aussieht. Diese Übergabe würde nur funktionieren, wenn innerhalb der C-Funktion eine entsprechende Umwandlung durchgeführt würde.
4.10.2 Übergabe per Wert Wenn eine Übergabe per Wert erfolgt, wird ein 4 Byte langer Zeiger auf eine mit Null terminierte Zeichenkette zurückgegeben. Eine externe C-Funktion kann den Inhalt der Zeichenkette verändern, aber nicht deren Länge.
4.11 Verwendung von konstanten Zeichenketten Konstante Zeichenketten werden in LotusScript zwischen Anführungszeichen, vertikalen Strichen( | ) oder geschweiften Klammern ( {} ) eingegeben. Dabei können Zeichenketten zwischen den vertikalen Strichen oder den geschweiften Klammern auch über mehrere Zeilen laufen. Wird innerhalb einer konstanten Zeichenkette das Zeichen { verwendet, wird dieses als Bestandteil der Zeichenkette angenommen. Wenn eins der anderen begrenzenden Zeichen innerhalb der Zeichenkette verwendet werden soll, muss dieses Zeichen doppelt aufgeführt werden. "A "A |A {A
quoted string with {braces} and a bar | in it" quoted string with ""quotes"" in it" bar string with a bar || in it| brace string with {braces}} in it}
Grenzen beim Datentyp String
77
4.12 Grenzen beim Datentyp String Die Anzahl der Variablen mit dem Datentyp String sowie des insgesamt für Zeichenketten verwendeten Speicherbereichs wird durch den verfügbaren Speicher des Systems bestimmt. Die maximale Länge einer Variable vom Datentyp String beträgt 2 Gigabyte. Die maximale Länge einer konstanten Zeichenkette beträgt 16.267 Zeichen oder dementsprechend 32.000 Byte und alle konstanten Zeichenketten eines Moduls dürfen maximal 2 Gigabyte Speicher belegen.
4.13 Besondere Unterschiede zwischen statischen und dynamischen Zeichenketten 4.13.1 Unterschiede bei der Wertzuweisung Wenn einer Variable, welche als statische Zeichenkette deklariert ist, ein Wert zugewiesen wird, werden ggf. über die festgelegte Länge hinausgehende Zeichen abgeschnitten. Wenn die Zeichenkette, die zugewiesen wird, kürzer ist, werden die fehlenden Stellen mit dem Zeichen, welches dem ASCII-Code 0 entspricht (Chr$(0)), aufgefüllt. Dim Wert As String * 5 Wert = "Zeichenkette" MsgBox Wert
Diese Anweisungen führen zur Ausgabe von »Zeich«. Dim Wert As String * 10 Wert = "Zeichen" MsgBox "-"+Wert+"-"
Nach diesen Anweisungen wird »-Zeichen -« ausgegeben. Die Variable Wert beinhaltet dann die Zeichenketten »Zeichen« und die auffüllenden Zeichen bis zur festen Zeichenkettenlänge. Der Unterschied zwischen Zeichenketten mit fester und variabler Länge wird besonders bei dem folgenden Beispiel deutlich: Dim ZeichenA As String * 10 Dim ZeichenB As String ZeichenA = "Zeichen" ZeichenB = "Zeichen" MsgBox Right$(ZeichenA, 4) MsgBox Right$(ZeichenB, 4)
In diesem Beispiel wird, obwohl sich die Variablen nur in der Art des Stringdatentyps unterscheiden, zuerst »n« ausgegeben und im zweiten Fall »chen«.
78
Der Datentyp String
4.13.2 Unterschiede bei der Längenermittlung Auf einen weiteren Unterschied zwischen dynamischen und statischen Zeichenketten stößt man bei der Verwendung der Funktion Len. Diese Funktion liefert bei einer dynamischen Zeichenkette die aktuelle Länge und bei einer statischen Zeichenkette die Länge, welche bei der Deklaration angegeben wurde. Dim Kette1 As String * 10 Dim Kette2 As String Kette1 = "Hallo" Kette2 = "Hallo" Print Len(Kette1) Print Len(Kette2)
'liefert 10 'liefert 5
4.14 Fragen 1. Welche zwei Arten von Datentypen »String« haben Sie unter LotusScript kennengelernt? 2. Wie wird die Art des Datentyps String von der Art und Weise der Deklaration beeinflusst? 3. Wozu dient die Funktion Len? Welche unterschiedlichen Ausprägungen dieser Funktion kennen Sie? 4. Was müssen Sie bei der Verwendung der Funktionen Right und Left bezüglich der zwei unterschiedlichen String-Arten beachten? 5. Wozu würden Sie die Funktion Mid verwenden? 6. Wie können Sie die Ausrichtung in statischen Strings beeinflussen? 7. Welche unterschiedlichen Ausprägungen der Funktion Trim kennen Sie? 8. Mit welcher Funktion können Sie einen Ausdruck in eine Zeichkette umwandeln? 9. Welche Funktionen dienen dem Vergleich zweier Zeichenketten? 10. Wie unterscheiden sich die Funktionen StrLeft, StrLeftBack, StrRight und StrRightBack? 11. Wie können Sie die Position von Teilstrings in Zeichenketten ermitteln? 12. Beschreiben Sie, wie der Vergleich von Zeichenketten mit einer Anweisung beeinflusst werden kann? 13. Welche Vergleichsoperatoren für Zeichenketten kennen Sie? 14. Wie werden Zeichenketten aneinander gehängt? 15. Wie werden konstante Zeichenketten festgelegt?
5 5
Zeit- und Datumswerte
5.1 Verständnisvoraussetzungen Das Kapitel setzt voraus, dass die Deklaration von Variablen bekannt ist. Außerdem sollte der generelle Aufbau eines LotusScript-Programms bekannt sein.
5.2 Lernziel Das Kapitel beschäftigt sich mit dem Umgang mit Datums- und Zeitwerten in LotusScript. Es wird auf Eigenarten eingegangen, die von der Speicherung eines Datums- bzw. Zeitwertes als numerischer Wert herrühren. Außerdem lernen Sie, wie Datums- und Zeitwerte in ihre Bestandteile zerlegt werden können.
5.3 Einleitung LotusScript stellt keinen speziellen Datentyp für die Verarbeitung von Zeit- oder Datumswerten zur Verfügung. Stattdessen werden die Zeit- und Datumswerte in einer Variablen vom Datentyp Variant gespeichert. Für die systeminterne Speicherung wird ein numerischer Wert verwendet. Dabei stehen in LotusScript die Vorkommastellen für die Anzahl der Tage und die Nachkommastellen für die Uhrzeit. Der numerische Wert 0 steht für den 30.12.1899. Negative Werte werden als ein Datum vor dem 30.12.1899 und positive für ein Datum nach dem 30.12.1899 interpretiert. Für jede Erhöhung um den Wert 1 wird ein Tag weiter gezählt und bei jeder Verminderung einen Tag zurück. Ausgehend von einem Zeitraum eines Tages (der dem Wert 1 entspricht), gilt für eine Stunde der Wert 1/24 (ca. 0,042), für eine Minute der Wert 1/(24*60) = 1/1440 (ca. 0,000694) und für eine Sekunde 1/(24*60*60) = 1/ 86400 = (ca. 0,000011574). Der Wertebereich einer Zeitangabe liegt in LotusScript zwischen dem 1.1.0100 und dem 31.12.9999.
80
Zeit- und Datumswerte
Zeitangaben sind in LotusScript wie folgt definiert: Vorkommastellen Tage Nachkommastellen Zeit 0 30.12.1899 +1 Einen Tag später -1 Einen Tag früher +1/24 Eine Stunde später - 1/24 Eine Stunde früher + 1/1440 Eine Minute später - 1/1440 Eine Minute früher Frühestes Datum 1.1.0100 Spätestes Datum 31.12.9999
X
Umwandlung von Datums- und Zeitwerten
Es gibt unter LotusScript mehrere Funktionen zur Umwandlung und Bearbeitung von Datumswerten. Die wichtigste Datumsfunktion ist CDat, eine Funktion zur Umwandlung eines beliebigen Ausdrucks in einen Zeitwert. Als Parameter erwartet CDat einen numerischen oder alphanumerischen Wert, der als Datums- oder Zeitwert interpretiert werden kann. Syntax CDat: CDat( dateTime ) DatumV MsgBox DatumV MsgBox
= CDat("01.01.1990") DatumV = CDat("18:00") DatumV
'Liefert das Datum 01.01.1990 'Liefert 18:00:00
5.3.1 Umwandlung der Einzelwerte Jahr, Monat, Tag in Datumswert
X
Um die drei Einzelangaben Tag, Monat und Jahr in einen Datumswert zu verwandeln, wird die Funktion DateNumber verwendet. Dazu werden die drei Werte übergeben und als Rückgabewert erhält man den entsprechenden Datumswert. Zu beachten ist, dass auch negative Werte zulässig sind und entsprechend umgesetzt werden. Syntax DateNumber: DateNumber( year%, month%, day% )
Datum1 MsgBox Datum2 MsgBox
= DateNumber(2010, 1, 1) Datum1 = DateNumber(2010, -1, 1) Datum2
'Liefert 01.01.2010 'Liefert 01.11.2009
Einleitung
81
5.3.2 Umwandlung von Strings in Datumswerte Die Umwandlung einer Zeichenkette in einen Datumswert erfolgt mit der Funktion DateValue. Dieser Funktion wird das Datum als Zeichenkette übergeben und liefert dieses als Datumswert zurück. Syntax DateValue: DateValue( date$ ) MsgBox DateValue("1.1.2011") MsgBox DateValue("1.12.2009")
' liefert 01.01.2011 ' liefert 01.12.2009
5.3.3 Umwandlung von Stunden, Minuten, Sekunden in Zeitwert Vergleichbar zu DateNumber wird die Funktion TimeNumber zum Umwandeln von Uhrzeiten eingesetzt. Auch hierbei werden negative Werte beachtet und verarbeitet. Syntax TimeNumber: TimeNumber( hours% , minutes%, seconds% ) MsgBox TimeNumber(15, 10, 0) MsgBox TimeNumber(10, -30, 0)
'liefert 15:10:00 'liefert 09:30:00
5.3.4 Umwandlung von Strings in Zeitwerte Um eine Zeichenkette, die einer Uhrzeit entspricht, in den entsprechenden Zeitwert zu verwandeln, wird die Funktion TimeValue eingesetzt. Sie stellt das entsprechende Gegenstück zu DateValue dar, welches das Analogon für die Umwandlung von Datumswerten darstellt. Syntax TimeValue: TimeValue( time$ ) MsgBox TimeValue("12:00:00")
Liefert 12:00:00
82
Zeit- und Datumswerte
5.3.5 Überprüfung, ob ein Ausdruck ein Datum darstellt Um in einem Programm sicherzugehen, dass ein übergebener Ausdruck einen Datumswert darstellt, wird die Funktion IsDate eingesetzt. Syntax IsDate: IsDate( expression ) MsgBox IsDate("01.01.1980") MsgBox IsDate(200) MsgBox IsDate(CDat(200))
'liefert True 'liefert False 'liefert True
5.4 Das aktuelle Datum ermitteln und setzen 5.4.1 Aktuelles Datum ermitteln Zur Ermittlung des aktuellen Datums gibt es in LotusScript zwei Funktionen. Diese unterscheiden sich im Typ des Rückgabewertes. Die Funktion Date liefert das aktuelle Datum als Variant bzw. Datumswert. Die Funktion Date$ hingegen gibt das Datum in einer Zeichenkette zurück. Syntax Funktion Date: Date[$] MsgBox "Wir haben heute den " + Date
Gibt das aktuelle Datum aus
5.4.2 Aktuelles Datum setzen Das aktuelle Datum des Systems setzt man in LotusScript mit der Date- oder Date$Anweisung. Man kann das gewünschte Datum als Zeichenkette oder Zeitwert übergeben. Syntax Statement Date: Date[$] = date Date = "1.1.1998"
Setzt das aktuelle Datum auf den 1.1.1998
Die aktuelle Uhrzeit ermitteln und setzen
83
5.5 Die aktuelle Uhrzeit ermitteln und setzen 5.5.1 Aktuelle Uhrzeit ermitteln Auch zur Ermittlung der aktuellen Uhrzeit gibt es in LotusScript zwei Funktionen: Time und Time$. Die Funktion Time liefert hierbei analog zu Date die aktuelle Uhrzeit als Zeitwert und die Funktion Time$ die aktuelle Uhrzeit als Zeichenkette zurück. Syntax Funktion Time: Time[$] MsgBox "Wir haben jetzt " + Time + " Uhr"
Liefert die aktuelle Uhrzeit
5.5.2 Aktuelle Uhrzeit setzen Gesetzt wird die aktuelle Uhrzeit mit den Anweisungen Time bzw. Time$. Syntax Statement Time: Time[$] = time Time = "18:00:00"
Setzt als aktuelle Uhrzeit 18:00 Uhr
5.6 Die Funktionen Now, Today und Timer 5.6.1 Die Funktion Now Die Funktion Now liefert das aktuelle Datum und die aktuelle Zeit als Variant zurück. Syntax Now: Now MsgBox "Beim nächsten Ton ist es " + Now
Liefert das aktuelle Datum und die aktuelle Zeit
5.6.2 Die Funktion Today Die Funktionsweise von Today ist identisch mit der der Funktion Date. Eine nähere Beschreibung finden Sie im Abschnitt 5.5.1 »Aktuelles Datum ermitteln«.
84
Zeit- und Datumswerte
5.6.3 Die Funktion Timer Mit dieser Funktion erhält man die Anzahl der Sekunden, die seit Mitternacht abgelaufen sind. Dabei wird die Anzahl der Sekunden auf den nächsten Hundertstel-Wert gerundet. Diese Funktion eignet sich z. B. sehr gut, um Durchlaufzeiten in Anwendungen zu ermitteln. Syntax Timer: Timer Start! = Timer() For Schritt&=1 To 1000000 X = Sin(Schritt&) Next Schritt& Ende! = Timer() MsgBox "Die Schleife brauchte " + Str$(Ende! – Start!) + " Sekunden"
5.7 Ermitteln von Tag, Monat, Jahr, Wochentag 5.7.1 Die Funktion Year Mit der Funktion Year können Sie die Jahresangabe aus einem Datumswert extrahieren. Dazu übergeben Sie der Funktion eine Datumsangabe in Form einer Zeichenkette oder eines anderen unter Lotus Notes zulässigen Datentyps für einen Datumswert. Als Rückgabewert liefert Ihnen die Funktion die Jahreszahl des übergebenen Datums. Syntax Funktion Year: Year( date ) MsgBox Year("10.01.98") MsgBox Year("12.02.2001")
'liefert 1998 'liefert 2001
5.7.2 Die Funktion Month Mit der Funktion Month extrahieren Sie den Monat eines Datumswertes. Dieser Funktion wird wie der Funktion Year ein Datum in Form eines beliebigen Datentyps übergeben. Zurückgeliefert wird eine Zahl zwischen 1 und 12 einschließlich, welche für den Monat des Datumswertes steht. Syntax Funktion Month: Month( date )
Ermitteln von Stunden, Minuten und Sekunden
MsgBox Month("10.01.98") MsgBox Month("12.02.2001")
85
'liefert 1 'liefert 2
5.7.3 Die Funktion Day Den Tag innerhalb eines Monats liefert die Funktion Day zurück. Auch dieser Funktion wird ein Datumswert in einem zulässigen Datentyp übergeben. Ihr Rückgabewert liegt im Bereich von 1 bis 31. Syntax Funktion Day: Day( date ) MsgBox Day("10.01.98") MsgBox Day("12.02.2001")
'liefert 10 'liefert 12
5.7.4 Die Funktion Weekday Diese Funktion liefert den Wochentag, auf den ein Datum fällt. Der Rückgabewert ist eine Zahl zwischen 1 bis 7. Syntax Funktion Weekday: Weekday( date ) MsgBox Weekday("10.01.98") MsgBox Weekday("12.02.2001")
'liefert 7 für Samstag 'liefert 2 für Montag
5.8 Ermitteln von Stunden, Minuten und Sekunden Analog zur Handhabung der Datumswerte stellt LotusScript Funktionen zur Bearbeitung von Bestandteilen der Uhrzeit zur Verfügung.
5.8.1 Die Funktion Hour Mit der Funktion Hour ermitteln Sie den Stundenanteil eines Uhrzeit-Ausdrucks. Als Rückgabe erhalten Sie einen Wert zwischen 0 und 23, welcher die Stunde darstellt. Syntax Hour: Hour( time ) MsgBox Hour("18:30:20") MsgBox Hour("19:20:10")
'liefert 18 'liefert 19
86
Zeit- und Datumswerte
5.8.2 Die Funktion Minute Die Funktion Minute liefert die Minute eines Uhrzeitwertes. Der Rückgabewert liegt zwischen 0 und 59 einschließlich. Syntax Minute: Minute( time ) MsgBox Minute("18:30:20") MsgBox Minute("19:20:10")
'liefert 30 'liefert 20
5.8.3 Die Funktion Second Die Sekunden können Sie mit der Funktion Second ermitteln. Der Funktion wird ein Zeitwert übergeben. Der Rückgabewert liegt zwischen 0 und 59 einschließlich. Syntax Second: Second( time ) MsgBox Second("18:30:20") MsgBox Second("19:20:10")
'liefert 20 'liefert 10
5.9 Wichtige Bemerkung zum Abschluss Der Umgang mit Datums- und Zeitwerten gehört zu den heikelsten Aufgaben in einer Notesanwendung. Hier können Sie leicht über zahlreiche Fallen stolpern, die mit unterschiedlichen Datumsformaten zusammenhängen. Notes zeichnet sich dadurch aus, dass das System für einen Großteil der verschiedenen Zeitformate, die auf der ganzen Welt eingesetzt werden, konfiguriert werden kann. Wenn die Konfigurierung sauber durchgeführt wird, können Mitarbeiter eines weltweiten Unternehmens ohne Probleme auf gemeinsame Daten zugreifen und sie bearbeiten, obwohl die Formatierung der Datums- und Zeitwerte sehr unterschiedlich sein mag. Auch unterschiedliche Zeitzonen werden mühelos bewältigt. Ein Kardinalfehler, mit dem Sie diesen mächtigen Notes-/Domino-Mechanismus empfindlich stören können, ist das Hardcoding von Datums-/Zeitformaten. Wenn Sie zum Beispiel einen bestimmten Tag, einen bestimmten Monat und ein bestimmtes Jahr als einzelne Werte vorliegen haben, diese nun als String kombinieren und diesen ohne weitere Bearbeitung im Dokument abspeichern wollen, dann müssen Sie sehr vorsichtig vorgehen. Angenommen, Sie bauen im deutschen Sprachraum mit deutscher Datumsformatierung zur Angabe des 10. März 2000 folgenden String zusammen und speichern ihn anschließend in einem Dokumentenfeld ab (die Objektreferenzvariable für das Dokument heißt note):
Fragen zu dem Kapitel
87
Dim sDatum As String sDatum = "10" & "." & "3" & "." & "2000" Call note.ReplaceItemValue("Beginn", sDatum)
Dann erhält das Feld den Typ Text. Wenn Sie dieses Dokument selbst mit einer Maske öffnen, die das Feld Beginn als Datum anzeigt, so wird Ihnen nichts Besonderes auffallen. Sollte aber ein in Amerika ansässiger Kollege auf Ihr Dokument mit der gleichen Maske zugreifen, so wird er merkwürdige Ergebnisse erzielen. Im günstigsten Fall wird das Datum als der 3. Oktober im Jahre 2000 angezeigt. Höchstwahrscheinlich wird sein Rechner allerdings mit dem Wert gar nichts anfangen können. Woran liegt das? Wir gehen davon aus, dass der amerikanische Kollege vor einem Notes-Client sitzt, der auf ein amerikanisches Format eingestellt ist. Dies sieht z. B. so aus: MMDDYYYY. Unser per Script formatiertes Datum hat aber den Aufbau DDMMYYYY. (Die meist unterschiedlichen Trenner für die Bestandteile eines Datums lassen wir der Einfachheit halber mal außer Betracht. Das dürfen Sie in der realen Programmierung natürlich nicht vernachlässigen!) Die Maske versucht nun beim Öffnen, den ins Dokument geschriebenen String als Datum zu interpretieren, geht aber von einer ganz anderen Formatierung aus. Notes könnte diese Unterschiede selbstständig ausgleichen, vorausgesetzt der Datumswert würde nicht als String, sondern als Datums-/Zeitwert abgespeichert. Fazit: Seien Sie bei der Umwandlung und Zusammenstellung von Datumsformaten extrem vorsichtig! Am besten arbeiten Sie NIE mit Datumswerten in Textform. Ausnahme sollte nur der Fall sein, wo sie Datumswerte als String aus Fremdsystemen erhalten und daher auf die Formatierung keinen Einfluss haben. Ansonsten können Sie Fehler noch dadurch reduzieren, dass sie mit Hilfe der Klasse NotesInternational die eingestellte Formatierung abfragen und genau diese verwenden.
5.10 Fragen zu dem Kapitel 1. Mit welcher Funktion wird genau das aktuelle Datum ermittelt? 2. Mit welcher Funktion wird genau die aktuelle Uhrzeit ermittelt? 3. Wie lautet die Funktion zum Ermitteln der aktuellen Uhrzeit und des aktuellen Datums? 4. Mit welcher Funktion wird der Tag aus einem Datumsausdruck separiert? 5. Was ist bei der Bearbeitung von Datums-/Zeitwerten zu beachten, wenn die Daten von verschiedenen Stellen eines international operierenden Unternehmens verwendet werden sollen?
6 6
Array
6.1 Verständnisvoraussetzungen Das Kapitel setzt Kenntnisse über die Deklaration und das Handling von Variablen voraus. Außerdem sollte die Grundstruktur des LotusScript-Programmaufbaus bekannt sein.
6.2 Lernziel Im folgenden Kapitel werden zwei Hauptziele verfolgt: Erläuterung des Einsatzes von Arrays in der Programmiersprache LotusScript. Hinweis auf laufzeitrelevante Eigenarten bei der Verwendung von Arrays.
6.3 Einleitung Im alltäglichen Leben werden Daten häufig in Form von Listen oder Tabellen dargestellt. Um solche Daten in einem Computer ähnlich strukturiert verarbeiten zu können, wurde der Datentyp Array eingeführt. Ein Array besteht aus einer Menge von Einträgen, die alle den gleichen Datentyp besitzen. Daher bezieht man diesen Datentyp auch einheitlich auf das gesamte Array. In LotusScript gibt es Arrays vom Typ eines einfachen Datentyps, eines Klassentyps oder auch eines benutzerdefinierten Datentyps. Die einfachste Form eines Arrays kann man sich vereinfachend wie eine Liste des täglichen Lebens vorstellen. Man spricht dann von einem eindimensionalen Array. Die nächstkomplexere Variante ist eine Tabelle, also ein zweidimensionales Array. In LotusScript gibt es Arrays mit bis zu acht Dimensionen. Die Position der Einträge innerhalb eines Arrays wird mit Hilfe von Indizes unterschieden. Für jede Dimension gibt es einen Index. Für eine Liste benötigt man also einen Index. Für eine Tabelle benötigt man zwei. Einer gibt die horizontale und der andere die vertikale Position an. Einschränkung: Ein Array kann bis zu acht Dimensionen haben.
90
Array
6.4 Statische und dynamische Arrays In LotusScript gibt es zwei Arten von Arrays: statische und dynamische. Statische Arrays zeichnen sich dadurch aus, dass bei ihnen die Größe, also der Wertebereich der Indizes, bei der Deklaration festgelegt wird. Sie kann anschließend nicht mehr verändert werden. Bei den dynamischen Arrays wird die Größe erst während der Laufzeit festgelegt und kann weiterhin geändert werden. Die Indizes eines Arrays müssen im Bereich von -32.768 bis 32.767 liegen. Die untere Grenze, die bei der Deklaration eines Arrays nicht angegeben wurde, liegt entweder bei 0 oder bei 1. Dieses hängt von der Einstellung per Option Base-Anweisung ab.
6.5 Deklaration Die Deklaration eines Arrays erfolgt mit der Dim-, Static-, Public- oder PrivateAnweisung. Dabei wird gleichzeitig der Datentyp festgelegt. Außerdem bestimmt die Art der Deklarationsanweisung, ob es sich um ein statisches oder dynamisches Array handelt. Syntax Array Deklaration: { Dim | Static | Public | Private } arrayName$ ( bounds% ) [ As datatype ] [ , arrayName$ ( bounds% ) [ As dataType ]]… Die Parameter bounds% stehen für die Indexlisten des Arrays. Diese bestehen aus einer oder mehreren Indexangaben. Mehrere solcher Angaben werden durch Kommas getrennt. Untere und obere Grenzen werden durch das Schlüsselwort To getrennt. Wird auf die Angabe der unteren Grenzen verzichtet, gilt für diese die Defaulteinstellung. Statisches zweidimensionales Array mit Indizes von 0 bis 100. Die Daten des Arrays sind vom Typ Integer: Dim FeldA(100, 100) As Integer
Dynamisches Array mit Daten vom Typ Integer: Dim FeldB() As Integer
Statisches Array mit Indizes von 5 bis 10 und Datentyp Variant: Dim FeldC(5 To 10, 5 To 10, 5 To 10)
6.5.1 Größenveränderung eines dynamischen Arrays Die Größe eines dynamischen Arrays kann während der Laufzeit durch die Anweisung ReDim nachträglich verändert werden. Der Aufbau der ReDim-Anweisung ähnelt sehr stark der Dim-Anweisung. Durch den Zusatz Preserve erreicht man,
Zugriff auf Elemente
91
dass der bisherige Inhalt des Arrays bei einer Änderung erhalten bleibt. Wenn der Zusatz Preserve fehlt, dann werden alle Elemente neu initialisiert. Syntax Redim-Anweisung: ReDim [ Preserve ] arrayName$ ( bounds% ) [ As dataType ] [ , arrayName$ ( bounds% ) [As dataType ] ] ... Dim Feld() As Integer Redim Feld(1) Feld(0) = 10 Feld(1) = 20 Print Feld(0), Feld(1) 'Liefert 10 20 Redim Preserve Feld(2) As Integer Feld(2) = 30 Print Feld(0), Feld(1), Feld(2) 'Liefert 10 20 30
6.6 Zugriff auf Elemente Der Zugriff auf die Elemente eines Arrays erfolgt immer über den Namen des Arrays und die Angabe der Indizes, welche die Position des Elementes angeben. Dabei erfolgt die Wertzuweisung genauso wie das Auslesen eines Wertes. Dim Matrix(2, 2) As Integer For X = 0 TO 2 For Y = 0 TO 2 Matrix(X, Y) = (X+1)*Y+1 Next Y Next X
6.7 Löschen von Elementen Für das Löschen von Elementen eines Arrays verwendet LotusScript die EraseAnweisung. Bei der Anwendung auf ein Array mit fixer Größe werden alle Elemente des Arrays reinitialisiert und die Größe des Arrays bleibt bestehen. Wenn die Erase-Anweisung auf einen Array mit dynamischer Größe angewendet wird, wird die Größe des Arrays auf 0 gesetzt, er behält allerdings seinen Datentyp. Syntax der Erase-Anweisung: Erase arrayName$ [,arrayName$ ]...
92
Array
6.8 Zugriff auf die Indizes Um den Indexbereich eines Arrays zu ermitteln, verwendet man die Anweisungen UBound und LBound. Die Anweisung UBound ermittelt die obere Indexgrenze und LBound die untere Grenze. Als Parameter wird der Arrayname angegeben und ggf. die Dimension, für die der Indexbereich ermittelt werden soll. Zur Bearbeitung aller Elemente eines Arrays wird die ForAll-Anweisung verwendet. Sie dient dem Durchlauf jedes Elementes in einer Schleife. Dabei wird mit dem ersten Index begonnen und dieser hochgezählt, danach wird der zweite Index um eins erhöht und wieder der erste Index von „unten nach oben“ hochgezählt usw. Syntax LBound und Ubound: UBound ( arrayName$ [ , dimension% ] ) LBound ( arrayName$ [ , dimension% ] )
6.9 ArrayAppend und ArrayReplace 6.9.1 ArrayAppend Mit der Funktion ArrayAppend können zwei eindimensionale Arrays aneinander gehängt werden. Der Funktion werden die zwei Arrays übergeben und sie liefert als Rückgabewert den zusammengesetzten Array. Syntax ArrayAppend: array3 = ArrayAppend(array1 As Variant, array2 As Variant ) Dim FeldA(1) As Integer Dim FeldB(1) As Integer Dim FeldC As Variant FeldA(0) = 1 FeldA(1) = 2 FeldB(0) = 3 FeldB(1) = 4 FeldC = ArrayAppend(FeldA, FeldB) For Counter = Lbound(FeldC) To Ubound(FeldC) Msgbox Str(FeldC(Counter)) Next
Dieses Beispiel gibt die Zahlen 1,2,3 und 4 aus. Besonderheiten im Verhalten von ArrayAppend array1 und array2 werden grundsätzlich nicht verändert. Wenn array1 und array2 denselben Datentyp haben, dann hat auch array3 diesen Datentypen.Wenn array1 und array2 unterschiedliche Datentypen haben, dann hat array3 den Datentypen Variant. Die Untergrenze von array2 muss gleich der Untergrenze vom array1
Suchen eines Wertes in einem Array
93
sein.Wenn der Ausdruck array1 kein Array ist, wird ein Type Mismatch-Fehler ausgegeben. Wenn der Indexbereich des neuen Arrays außerhalb der zulässigen Grenzen liegt, wird ein Subscription out of Range-Fehler erzeugt.Wenn ein Array mit mehr als einem Index angegeben wird, wird ein Type Mismatch-Fehler erzeugt.
6.9.2 ArrayReplace Durch die Anweisung ArrayReplace werden Einträge von array1, die dem array2 entsprechen, durch Einträge des array3 ersetzt. Dabei wird als Ersetzungswert immer das Element von array3 gewählt, das die gleiche Position besitzt wie der Entsprechungswert in array2. Syntax ArrayReplace: ArrayReplace( array1 As Variant, array2 As Variant, array3 As Variant ) As Variant Dim A(0 To 3) As Integer Dim B(0 To 1) As Integer Dim C(0 To 1) As Integer Dim D As Variant A(0) = 1 A(1) = 2 A(2) = 3 A(3) = 4 B(0) = 3 B(1) = 2 C(0) = 8 C(1) = 9 D = Arrayreplace(A, B, C) For Counter = Lbound(D) To Ubound(D) Msgbox Str(D(Counter)) Next
Die Werte in D nach Durchlauf der Funktion: D(0) = 1, D(1) = 9, D(2) = 8, D(3) = 4
6.10 Suchen eines Wertes in einem Array Um einen Wert innerhalb eines Arrays zu suchen, wird unter LotusScript die Anweisung ArrayGetIndex angeboten. Diese Funktion liefert den Index der Position des gesuchten Wertes. Syntax ArrayGetIndex: ArrayGetIndex( array As Variant, value As Variant [, flag% ] ) As Variant Dim A(0 To 3) As Integer
94
Array
Dim D As Variant A(0) = 1 A(1) = 2 A(2) = 3 A(3) = 4 D = Arraygetindex (A, 3) Msgbox Str(D)
Rückgabewert in D: 2 Zusätzlich kann der Textvergleich des Suchalgorithmus durch die Angabe eines Flags beeinflusst werden. Der Suchflag hat folgende Bedeutung: Suchflag
Groß-/Kleinschreibung Relevant
Pitch Relevant
0
Ja
Ja
1
Nein
Ja
4
Ja
Nein
5
Nein
Nein
Dim A(0 To 3) As String Dim D As Variant A(0) = "A" A(1) = "B" A(2) = "C" A(3) = "D" D = Arraygetindex(A, "b", 0) Print D REM Findet keine Position, D enthält den Wert NULL D = ArrayGetIndex(A, "b", 1) Print D REM Findet den Wert, gibt 1 für die Position zurück
6.11 Standarduntergrenze der Indexbereiche Mit der Anweisung Option Base wird der Standardanfangswert eines Arrays definiert. Diese untere Grenze für den Index wird dann eingesetzt, wenn bei der Deklaration keine untere Grenze gewählt wird. Mit der Anweisung kann zwischen 0 und 1 als Standard gewählt werden. Syntax Option Base: Option Base 0 | 1 Option Base 0 Dim A(3) ' Der Indexbereich des Arrays liegt zwischen 0 und 3 Option Base 1 Dim B(3) ' Der Indexbereich des Arrays liegt zwischen 1 und 3
Keine Zuweisungen
95
6.11.1 Überprüfung auf Arrayreferenz Um zu überprüfen, ob eine Variable eine Referenz auf einen Array beinhaltet, kann die Funktion IsArray verwendet werden. Wenn der übergebene Ausdruck ein Array ist, liefert die Funktion TRUE zurück, ansonsten wird FALSE zurückgegeben. Syntax isArray: IsArray ( expression ) Dim A(100) As Integer Dim B As String MsgBox isArray(A) 'Liefert True zurück MsgBox isArray(B) 'Liefert False zurück
6.12 Keine Zuweisungen Eine Zuweisung zwischen zwei Arrayvariablen ist bei LotusScript verboten. Bei einigen anderen Programmiersprachen ist eine solche Zuweisung erlaubt, aber sie führen dort zu vielen Problemen und Missverständnissen. In einigen Fällen wird bei einer Zuweisung von Arrays der komplette Speicherbereich kopiert und in anderen Fällen wird nur eine Referenz auf den Speicherbereich des Arrays übergeben. Um diese Probleme von vornherein zu vermeiden, sind Zuweisungen zwischen Arrays in LotusScript verboten. Einschränkung: Keine Zuweisung von Arrays Dim A(10) As Integer Dim B(10) As Integer A = B
' Verboten
6.13 Verbesserung des Laufzeitverhaltens Jeder Zugriff auf einen Wert in einem Array benötigt mehr Zeit als der Zugriff auf einen Wert in einer einzelnen Variable. Daher sollte man sich Arrayzugriffe innerhalb von Schleifen oder anderen häufig durchlaufenden Programmteilen besonders gut überlegen. Häufig kann die Laufzeit durch geschickte Wertzuweisungen vor und nach dem Durchlauf minimiert werden. Das folgende Beispiel verdeutlicht diesen Umstand anhand einer (absteigenden) Bubblesort-Routine. (Bubblesort ist eines von vielen Sortierverfahren. Bei Bubblesort wird in jedem Durchlauf in der noch unsortierten Folge nach dem größten Element gesucht und dieses an den bereits sortierten Bereich angehängt. Dadurch wird der sortierte Bereich bei jedem Durchlauf um ein Element länger und der noch zu sortierende Bereich um eines kürzer.)
96
Array
Beispiel »Laufzeit 1« Option Base 1 Dim Kurswert(100) As Integer .... For Counter1 = Lbound (Kurswert) To Ubound (Kurswert) For Counter2 = Counter1 + 1 TO Ubound(Kurswert) IF Kurswert(Counter1) < Kurswert(Counter2) Then Temp = Kurswert(Counter1) Kurswert(Counter1) = Kurswert(Counter2) Kurswert(Counter2) = Temp END IF Next Next
In diesem Beispiel wird jeder Arraywert, der benötigt wird, explizit aus dem Array ausgelesen. Dadurch wird in der inneren For-Schleife bei jedem Durchlauf mindestens zweimal auf ein Arrayelement zugegriffen (zur Auswertung der If-Bedingung Kurswert[Counter1] < Kurswert[Counter2]). Im ungünstigsten Fall (die Sortierfolge ist umgekehrt sortiert) wird auch noch der Block innerhalb der If-Anweisung bei jedem Durchlauf dieser Schleife ausgeführt. Dann werden bei jedem Durchlauf sechs Element-Zugriffe auf das Array fällig. Die Anzahl der fälligen Zugriffe liegt also zwischen ungefähr 100 * 2 * 50 und 100 * 6 * 50, also zwischen 10.000 und 30.000. (Die Zahl 100 steht für die Anzahl der Durchläufe der äußeren For-Schleife. Genaugenommen beträgt diese Zahl allerdings »nur« 99, denn beim letzten Durchgang wird die innere For-Schleife nicht mehr durchlaufen. Allerdings ist auch die Zahl 50 nur eine Näherung für die mittlere Häufigkeit, mit der die innere Schleife durchlaufen wird.) Beispiel »Laufzeit 2« Option Base 1
Dim Kurswert(100) As Integer .... For Counter1 = Lbound(Kurswert) To Ubound(Kurswert) Zwischen = Kurswert(Counter1) For Counter2 = Counter1+1 TO Ubound(Kurswert) IF Zwischen < Kurswert(Counter2) Then Temp = Zwischen Zwischen = Kurswert(Counter2) Kurswert(Counter2) = Temp END IF Next Kurswert(Counter1) = Zwischen Next
Laufzeitverhalten bei dynamischen Arrays
97
Hier werden zunächst einmal bei jedem Durchlauf zwei Zugriffe auf ein Array durchgeführt (vor und nach der inneren For-Schleife). Dann wird innerhalb der inneren For-Schleife je Durchlauf mindestens einmal auf das Array zugegriffen (zur Berechnung der If-Bedingung) und maximal dreimal. Dies sind bei ähnlichen Näherungsüberlegungen wie im ersten Beispiel 200 + 100 * 50 * 1 bis 200 + 100 * 50 *3, also zwischen 5.200 und 15.200. Dies ist schon um einiges besser als bei der ersten Variante!
6.14 Laufzeitverhalten bei dynamischen Arrays Eine Vergrößerung eines Arrays kann leicht dazu führen, dass ein neuer Speicherbereich für das Array reserviert werden muss und dieses mit seinen gesamten Werten dorthin kopiert werden muss. Daher sollte die Verwendung der Redim-Anweisung nicht zu häufig stattfinden und der Speicherbereich eher etwas großzügiger vergeben werden.
6.15 Doch eine Zuweisung von zwei Arrays Um trotz des Verbotes der direkten Zuweisung zwischen zwei Arrays die Werte eines Arrays in einen anderen zu kopieren, kann bei eindimensionalen Arrays die Anweisung ArrayReplace verwendet werden. Um eine Kopie der Daten eines Arrays in einem neuen Array anzulegen, muss als zweiter und dritter Parameter der Anweisung der Wert NULL übergeben werden. Dim A(3) As Integer …. C = ArrayReplace(A, Null, Null)
Kopiert alle Werte des Arrays A in den ArrayC.
6.16 Problematische Fehler Achtung: Absturz bei ArrayAppend (X, NULL) oder ArrayAppend (X, NOTHING)
6.16.1 Wichtige Bemerkungen
X X X X
Ein Array hat maximal 8 Dimensionen. Keine direkte Zuweisung zwischen zwei Arrays. Bei einem statischen Array werden die Größe und der Datentyp bei der Deklaration festgelegt. Bei einem dynamischen Array können die Größe und der Datentyp nachträglich verändert werden.
98
Array
6.17 Fragen zu dem Kapitel 1. Wie viele Dimensionen kann ein Array in LotusScript maximal haben? 2. Was ist bei einer Wertzuweisung bei Arrays zu beachten? 3. Mit welcher Anweisung können Größe und Datentyp eines dynamischen Arrays nachträglich verändert werden? 4. Bei welchem Typ von Array kann die Größe oder der Datentyp nachträglich verändert werden? 5. Mit welchem Befehl ermittelt man die Untere Indexgrenze eines Arrays? 6. Mit welchem Befehl ermittelt man die Obere Indexgrenze eines Arrays? 7. Wie erreicht man, dass ein dynamiches Array bei der Änderung der Größe nicht neu initialisiert wird? 8. Welche Anweisung erlaubt das Aneinanderhängen von Arrays? 9. Mit welchem Befehl können Werte in einem Array gesucht und ersetzt werden?
7 7
Der Datentyp List
7.1 Verständnisvoraussetzungen Zum Verständnis dieses Kapitels werden keine über die Basisanforderungen hinausgehenden Kenntnisse erwartet.
7.2 Lernziel Ziel dieses Kapitels ist die Einführung des Datentyps List und der Umgang mit ihm.
7.3 Einleitung Eine Variable vom Datentyp List beinhaltet (wie der Name schon sagt) eine Liste von Elementen. Diese Elemente müssen alle den gleichen Datentyp besitzen. Dabei kann der Datentyp ein Notes-Datentyp, ein beliebiger Klassentyp oder ein anderer benutzerdefinierter Datentyp sein. Eine Liste kann als Werte alle Notes-Datentypen, Klassen-Datentypen und benutzerdefinierte Datentypen besitzen. Der Vorteil des Datentyps List ist der Speichermechanismus für die Listen-Elemente. Dieser erlaubt, den Speicherplatz für die Listen-Elemente erst während der Laufzeit dynamisch festzulegen. Dieses ermöglicht es dem System, neuen Speicherplatz für weitere Einträge während der Laufzeit zu reservieren und diesen bei Bedarf auch wieder freizugeben. Somit muss auch bei der Deklaration keine maximale Anzahl von Elementen angegeben werden.
7.4 Die Deklaration Deklariert wird eine Liste durch die Dim-Anweisung. Dabei kann der Datentyp der Listen-Elemente festgelegt werden. Sollte kein Datentyp angegeben werden, so sind die Listen-Elemente vom Datentyp Variant bzw. dem per DefType voreingestellten Datentyp. Direkt nach der Deklaration ist die Liste initialisiert und beinhaltet keine Elemente. Syntax der Dim-Anweisung für Listen: { Dim | Static | Public | Private } listname [ suffix ] List [ As dataType ] [, listname [ suffix ] List [ As dataType ] ]…
100
Der Datentyp List
Dim Werteliste List As Integer
Diese Anweisung deklariert die Variable Werteliste als Listenvariable mit Einträgen des Datentyps Integer. Dim Werteliste$ List
Durch diese Deklaration wird eine Liste von Zeichenketten angelegt. Dim Einfacheliste List
Hier ist eine Liste mit Elementen vom Typ Variant angelegt worden.
7.5 Zugriff auf die Elemente Um auf einzelne Elemente der Liste zuzugreifen, wird ein eindeutiger Schlüssel benötigt. Diesen Schlüssel bezeichnet man als ListTag. Bei einer Liste wird der Schlüssel durch eine Zeichenkette gebildet. Der Zugriff auf Werte innerhalb der Liste erfolgt über einen ListTag ; dies ist ein eindeutiger Schlüssel, der entweder ein numerischer Wert oder eine Zeichenkette sein kann. Wird ein numerischer Wert verwendet, dann wird er bei der Verwendung automatisch in eine Zeichenkette konvertiert, da ein ListTag immer vom Typ String ist. Es hängt von der Deklaration in der Programmumgebung ab, ob bei dem Schlüsselwert die Groß-/Kleinschreibung relevant ist. Dieses kann durch die Option CompareAnweisung beeinflusst werden. Syntax der Option Compare-Anweisung: Option Compare { BINARY | CASE | NOCASE | PITCH | NOPITCH } [,{BINARY | CASE | NOCASE | PITCH | NOPITCH } ]...
Option
Beschreibung
BINARY
vergleicht den Schlüssel auf Binärebene
CASE
vergleicht den Schlüssel und beachtet dabei Groß-/Kleinschreibung
NOCASE
vergleicht den Schlüssel und beachtet dabei keine Groß-/Kleinschreibung
PITCH
vergleicht den Schlüssel und beachtet dabei die verschiedenen Zeichenebenen bei bestimmten Sprachen
NOPITCH
vergleicht den Schlüssel und beachtet dabei nicht die verschiedenen Zeichenebenen bei bestimmten Sprachen
Option Compare NOCASE ' Hier bezeichnen Liste(A) und Liste(a) denselben Eintrag
Zugriff auf die Elemente
101
Option Compare CASE 'Hier bezeichnen Liste(A) und Liste(a) jeweils zwei verschiedene Einträge
7.5.1 Wert-Zuweisung bei einem Listen-Element Die Wert-Zuweisung bei einer List-Variable erfolgt durch die Angabe des Namens der Liste, des ListTags und dem Wert in folgender Form: Listenname ( Schlüssel ) = Wert.
7.5.2 Wert-Auslesen bei einem Listen-Element Das Auslesen der Werte erfolgt auf ähnlichem Wege, dazu wird einfach der Variablen-Name und der Schlüssel des gesuchten Eintrages angegeben. Variable = Listenname ( Schlüssel ) Dim Werteliste List As Integer Werteliste("Wert1") = 100 Werteliste("Wert2") = 200 MsgBox Werteliste("Wert1")
Diese Anweisungen deklarieren die Variable Werteliste als Listenvariable mit Einträgen des Datentyps Integer. Dann wird dem Eintrag in der Liste mit dem Namen »Wert1« der Wert 100 zugewiesen. Danach folgt für den Eintrag »Wert2« der Wert 200. Danach wird der Eintrag mit der Bezeichnung »Wert1« ausgegeben. Option Compare NOCASE Dim Werteliste List As Integer Werteliste("Wert") = 100 Werteliste("wert") = 200 MsgBox Werteliste("Wert") MsgBox Werteliste("wert")
Dieses Beispiel wird beide Male den Wert 200 ausgeben, da beide Wert-Zuweisungen als Zuweisungen an denselben Eintrag angesehen werden. Option Compare CASE Dim Werteliste List As Integer Werteliste("Wert") = 100 Werteliste("wert") = 200 MsgBox Werteliste("Wert") MsgBox Werteliste("wert")
Dieses Beispiel gibt zuerst den Wert 100 aus und dann den Wert 200, da die Einträge als zwei verschiedene Elemente der Liste angesehen werden.
102
Der Datentyp List
7.6 Datentypen der Listen-Elemente Der Datentyp der Einträge kann wie oben beschrieben mit Hilfe der Dim-Anweisung oder aufgrund eines Suffixes beim Listennamen festgelegt werden. Wenn kein Datentyp festgelegt wurde, versucht der Compiler den Datentyp anhand der gegebenenfalls benutzten DefType-Anweisung zu ermitteln. Wenn auf keinem dieser Wege ein Datentyp ermittelt werden kann, wird als Datentyp Variant eingesetzt. Dim Werteliste1 List As Long
Durch diese Zeile wird die Werteliste1 als Liste von Elementen mit dem Datentyp Long deklariert. Dim Werteliste2$ List
Diese Zeile wiederum deklariert eine Liste mit Zeichenketten als Einträge. DefDbl W-Z Dim Werteliste3 List
Durch die DefDbl-Anweisung werden alle Variablen mit den Anfangsbuchstaben W bis Z als Doublevariablen angesehen, dadurch wird den Elementen der Liste ebenso der Datentyp Double zugewiesen. Dim Werteliste4 List Werteliste4("Erstens") = "Hallo"
Weil der Datentyp der Liste nicht aufgrund der Dim-Anweisung bzw. eines Suffix definiert wird und auch kein Standarddatentyp definiert wurde, wird als Datentyp der Listeneinträge der Variant ausgewählt. Eine Variable des Datentyps List kann auf Modulebene, Prozedurebene oder innerhalb einer Klasse verwendet werden. Nicht verwendet werden kann der List-Datentyp innerhalb eines benutzerdefinierten Datentyps. Dim Werteliste1 List As Integer Private Werteliste3 List As Integer Public Werteliste4 List As Integer Sub Unterprogramm Dim Werteliste1 List As Integer Static Werteliste2 List As Integer End Sub Class Klasse Public Werteliste1 List As Integer Private Werteliste2 List As Integer End Class
LotusScript-Befehle für Listen
103
7.7 LotusScript-Befehle für Listen 7.7.1 Löschen aller oder einzelner Elemente einer Liste mit Erase Mit dem Befehl Erase kann eine Liste oder ein Listen-Element gelöscht werden. Wenn auf das Schlüsselwort Erase als Parameter eine Referenz auf eine Liste folgt, wird diese dadurch gelöscht. Im folgenden Beispiel wird eine Liste angelegt und mit Elementen gefüllt. Danach werden alle Elemente der Liste mit Erase gelöscht. Syntax Erase-Anweisung (1) Erase listName [ ,listName ]... Dim Werteliste List As Integer Werteliste(1) = 100 Werteliste(2) = 200 Erase Werteliste
Außerdem kann als Parameter auch ein einzelnes Listen-Element übergeben werden. Dieses führt dann zum Löschen des angegebenen Listen-Elementes. Syntax Erase-Anweisung (2) Erase { arrayName | listName | listName(tag$) } [, { arrayName | listName | listName(tag$) } ]... Dim Werteliste List As Integer Werteliste(1) = 100 Werteliste(2) = 200 Erase Werteliste(1)
7.7.2 Die ForAll-Schleife Mit ForAll kann eine Schleife konstruiert werden, die für jedes Element einer Liste oder eines Arrays einmal durchlaufen wird. Im Kopf der ForAll-Schleife werden die Laufvariable und der Name der Liste oder des Arrays (Container) angegeben. Die Laufvariable beinhaltet dann bei dem jeweiligen Schleifendurchlauf das entsprechende Listen- bzw. Array-Element. Syntax ForAll ForAll referenceVar In container [ statements ] End ForAll Im folgenden Beispiel werden alle Elemente der Liste mit einer Messagebox ausgegeben.
104
Der Datentyp List
Dim Werteliste List As Integer Werteliste(1) = 100 Werteliste(2) = 200 Werteliste(3) = 300 ForAll x In Werteliste MessageBox x End Forall
7.7.3 Die Überprüfung mit IsList Mit der Funktion IsList kann überprüft werden, ob eine Variable eine Referenz auf eine Liste beinhaltet. Dabei wird der Funktion als Parameter der Variablen-Name übergeben und diese liefert dann TRUE oder FALSE zurück. Dim Werteliste List As Integer Dim Variable As Integer Messagebox IsList(Werteliste) Messagebox IsList(Variable)
’liefert True ’liefert False
7.7.4 Die Überprüfung der Existenz eines Elementes mit IsElement Die Funktion IsElement dient zum Überprüfen, ob ein Element mit dem angegebenen Schlüssel in der Liste existiert. Der Funktion wird das Listen-Element in der Form Listenname (Schlüsselwert) übergeben. Danach liefert die Funktion TRUE zurück, wenn ein Element mit dem angegebenen Schlüsselwert in der Liste enthalten ist. Ansonsten wird FALSE zurückgegeben. Bei dem folgenden Beispiel wird bei der ersten Ausgabe eine –1 (= TRUE) zurückgegeben und beim zweiten Aufruf der Messagebox eine 0 (FALSE): Dim Werteliste List As Integer Werteliste(1) = 100 Werteliste(2) = 200 Werteliste(3) = 300 Messagebox IsElement(Werteliste(1)) Messagebox IsElement(Werteliste(5))
’liefert True ’liefert False
7.7.5 Die Anweisung ListTag Um in einer ForAll-Schleife, welche eine Liste durchläuft, den Namen des aktuellen Listen-Elements zu ermitteln, wird die Funktion ListTag verwendet. Diese kann aus der ihr übergebenen Referenz des Elements den Namen zurückliefern. Syntax ListTag: ListTag ( referenceVar )
Fragen
Dim Liste List As String Liste("Eins")="EintragA" Liste("Zwei")="EintragB" Liste("Drei")="EintragC" ForAll i in Liste Print ListTag(i) End ForAll
105
'liefert "Eins", "Zwei", "Drei"
7.8 Fragen 1. Was ist ein Vorteil einer Script-Liste gegenüber einem Array? 2. Was können Sie in einer Liste alles speichern (denken Sie daran, dass Sie auch eine Liste mit Elementtyp »Variant« deklarieren können!)? 3. Wie kann man eine Liste mittels ForAll-Schleife komfortabel auswerten? 4. Wozu dient die Anweisung ListTag? 5. Wie können Sie Listen-Elemente und auch ganze Listen löschen? 6. Was ist beim Elementzugriff bezüglich der Schreibweise des ListTags zu beachten?
8 8
Programmverzweigung
8.1 Verständnisvoraussetzungen Dieses Kapitel setzt keine besonderen Kenntnisse voraus.
8.2 Lernziel Das Kapitel soll die Standardstrukturen einer Notes-Applikation vermitteln.
8.3 Sprungmarken Mit Hilfe von Sprungmarken werden Programmpunkte markiert, die von einer GoTo-Anweisung angesprungen werden. Die Sprungmarke hat immer nur in der aktuellen Prozedur oder Funktion ihre Gültigkeit. Ein Verwenden von Sprungzielen über Prozedurgrenzen hinweg ist nicht möglich. Syntax der GoTo-Anweisung: GoTo label Syntax der Sprungmarke: label: Sub Proc MsgBox "Hallo" GoTo Marke MsgBox "Wieder Hallo" Marke: MsgBox "Tschau" Exit Sub
Hier wird erst Hallo ausgegeben und dann Tschau. Durch die Verwendung von GoTo-Anweisungen wird der Programmcode sehr unstrukturiert. Daher sollte im Interesse einer besseren Programmlesbarkeit auf diese Anweisung wann immer möglich verzichtet werden. Der Einsatz von Sprungmarken sollte so sparsam wie möglich erfolgen.
108
Programmverzweigung
8.4 Die If-Anweisung 8.4.1 If ... Goto-Anweisung Durch diese Anweisung wird ein bedingter Sprung implementiert. Wenn die angegebene Anweisung als Ergebnis den booleschen Wert TRUE liefert, wird die Programmausführung an dem entsprechenden Sprungziel fortgesetzt. Bei dem Wert FALSE werden die Anweisungen hinter Else ausgeführt (falls vorhanden). Allerdings ist die Verwendung von Programmsprüngen zu einem Label eine Option, die nur sehr wohlüberlegt und ausnahmsweise verwendet werden sollte, da unnötige Sprünge dieser Art die Lesbarkeit des Programms stark erschweren. Syntax: If condition GoTo labelA [ Else [ statements ] ] Beispiel: If Personen = 2 GoTo Doppel Else MsgBox "Einzel" Doppel:
Wenn die Variable Personen den Wert 2 beinhaltet und somit die angegebene Bedingung wahr (TRUE) ist, dann wird das Programm an der Stelle, die mit dem Label Doppel gekennzeichnet ist, fortgesetzt. Ansonsten erfolgt die Ausgabe »Einzel«. Da der Ausdruck gegebenenfalls konvertiert wird, erfolgt der Sprung ebenfalls bei einem numerischen Wert ungleich 0.
8.4.2 If ... Then ... Else-Anweisung Die If-Anweisung in dieser Form stellt die übliche Programmverzweigung dar. Die Anweisungen im ersten Teil werden ausgeführt, wenn der Ausdruck wahr ist (TRUE). Ansonsten werden die Anweisungen aus dem zweiten Teil ausgeführt. Syntax: If condition Then [ statements1 ] [ Else [ statements2 ] ] End If If Reserviert = "Ja" Then MsgBox "Reservierte Zimmer" Else MsgBox "Nicht reservierte Zimmer" End If
Bei diesem Beispiel erfolgt die Ausgabe »Reservierte Zimmer« nur, wenn die Bedingung erfüllt ist; ansonsten wird »Nicht reservierte Zimmer« ausgegeben.
Die Select Case-Anweisung
109
8.4.3 If ... Then ... ElseIf-Anweisung Diese Form prüft der Reihe nach die angegebenen Ausdrücke. Wenn ein geprüfter Ausdruck den Wert TRUE hat, werden die dahinter angegebenen Anweisungen ausgeführt, ansonsten wird der Vergleich mit dem nächsten Ausdruck fortgesetzt. Sollte kein Ausdruck den Wert TRUE liefern, werden die Anweisungen aus dem Else-Zweig ausgeführt (sofern er vorhanden ist, ansonsten wird das Programm direkt hinter dem End If fortgesetzt). Syntax: If condition1 Then statements1 [ ElseIf condition2 Then statements2 ] ... [ Else statementsN ] End If If Personen = 1 Then MsgBox "Einzelzimmer" ElseIf Personen = 2 Then MsgBox "Doppelzimmer" Else MsgBox "Suite" End If
Hier wird zunächst überprüft, ob die erste Bedingung erfüllt ist, wenn ja, dann wird der Text »Einzelzimmer« ausgegeben. Wenn die erste Bedingung nicht erfüllt ist, wird die zweite Bedingung überprüft. Ist die zweite Bedingung erfüllt, erfolgt dort die entsprechende Ausgabe. Wenn weder die erste noch die zweite Bedingung erfüllt ist, wird die Ausgabe aus dem Else-Zweig erzeugt.
8.5 Die Select Case-Anweisung Dies ist eine Fallunterscheidung. Sie tritt häufig an die Stelle einer If...Elseif..Elseif...-Anweisungskette. Der hinter dem Schlüsselwort Select Case angegebene Ausdruck bestimmt, welcher Anweisungsblock ausgeführt werden soll. Es wird nur der Anweisungsblock ausgeführt, dessen zugeordneter Wert dem oberen Auswahlausdruck entspricht. Sollte keine Übereinstimmung gefunden werden, so wird der Anweisungsblock im Case Else-Zweig ausgeführt.
110
Programmverzweigung
Syntax: Select Case expression [Case value1 [ statements1 ] ] [Case value 2 [statements 2 ] ] ... [ Case Else [statements 3 ] ] End Select Select Case Richtung Case "N" MsgBox "Nordseite" Case "S" MsgBox "Südseite" Case "W" MsgBox "Westseite" Case "O" MsgBox "Ostseite" Case Else MsgBox "Falsche Richtungsangabe" End Select
In diesem Beispiel wird die Ausgabe erzeugt, welche dem Inhalt der Variable Richtung entspricht. Das heißt, beinhaltet die Variable Richtung ein »N«, so wird die Ausgabe Nordseite generiert, bei »S« Südseite usw. Sollte der Inhalt der Variablen Richtung keiner Angabe entsprechen, so wird die Anweisung in dem Case ElseZweig abgearbeitet.
8.6 Programmschleifen 8.6.1 Die For ... Next-Anweisung Die For ... Next-Anweisung stellt eine typische Zählschleife dar. Zu Beginn wird der Zähler mit dem Startwert initialisiert. Danach wird bei jedem Schleifendurchlauf der Zähler um den hinter Step angegebenen Wert erhöht. Dies erfolgt, bis der Inhalt des Zählers gleich oder größer als der Endwert ist. Syntax: For count = begin To end [ Step interval ] statements Next [count ] For Counter = 0 To 1000 Step 10 Msgbox Counter Next Counter
Die Do-Schleife
111
Dieses Beispiel durchläuft die Zahlen von 0 bis 1000 jeweils in 10er Schritten und gibt diese aus. Step kann positive und negative Werte annehmen. Wenn Step ausgelassen wird, beträgt die Schrittweite +1.
8.7 Die Do-Schleife 8.7.1 Kopfgesteuerte Do ... While-Schleife Die Schleife wird so lange durchlaufen, bis die angegebene Bedingung nicht mehr erfüllt ist. Hierbei bedeutet der Ausdruck »kopfgesteuert«, dass die Überprüfung der Bedingung immer zum Beginn eines Schleifen-Durchlaufs (also im Schleifenkopf) erfolgt. Syntax: Do While condition statements Loop Counter=1 Do While Counter < 10 MsgBox Counter Counter = Counter + 1 Loop
Diese Schleife gibt die Zahlen 1 bis 9 aus.
8.7.2 Fußgesteuerte Do ... While-Schleife Bei dieser Bauart einer Schleife wird die Bedingung im Gegensatz zur kopfgesteuerten Schleife erst am Ende eines Durchlaufs untersucht. Syntax: Do statements Loop While condition Counter=1 Do MsgBox Counter Counter = Counter + 1 Loop While Counter < 10
Diese Schleife gibt die Zahlen 1 bis 10 aus.
112
Programmverzweigung
8.7.3 Kopfgesteuerte Do ... Until-Schleife Die Schleife wird so lange durchlaufen, bis die angegebene Bedingung erfüllt wird. Die Überprüfung der Bedingung findet immer zum Beginn eines Schleifendurchlaufs statt. Syntax: Do Until condition statements Loop Counter=1 Do Until Counter = 10 MsgBox Counter Counter = Counter + 1 Loop
Die Schleife gibt die Zahlen 1 bis 9 aus.
8.7.4 Fußgesteuerte Do ... Until-Schleife Die Schleife wird so lange durchlaufen, bis die angegebene Bedingung erfüllt ist. Die Überprüfung der Bedingung findet immer am Ende eines Durchlaufs statt. Syntax: Do statements Loop Until condition Counter = 1 Do MsgBox Counter Counter = Counter + 1 Loop Until Counter = 10
Die Schleife gibt die Zahlen 1 bis 9 aus.
8.7.5 Die While-Schleife Diese Schleifenstruktur ist äquivalent zur kopfgesteuerten Do ... While- oder auch Do ... Until-Schleife. Die Schleife wird solange wiederholt, wie die Bedingung erfüllt ist. Die Überprüfung findet vor jedem Schleifendurchlauf statt. Es handelt sich also um eine kopfgesteuerte Schleife.
Die Do-Schleife
113
Syntax: While condition statements Wend Counter = 1 While Counter < 10 MsgBox Counter Counter = Counter + 1 Wend
Die Schleife gibt die Zahlen 1 bis 9 aus.
8.7.6 Do ... Loop-Schleife Die Do ... Loop-Schleife ist eine Schleife ohne irgendeine zu überprüfende Bedingung. Die Schleife kann nur durch eine Exit Do-Anweisung innerhalb eines Schleifendurchlaufs verlassen werden. Sollte kein Exit Do erreicht werden, wird die Schleife endlos durchlaufen. Syntax: Do statements Loop Counter = 1 Do MsgBox Counter If Counter = 10 Then Exit Do Counter = Counter + 1 Loop Diese Schleife gibt die Werte 1 bis 10 aus. Counter=1 Do Counter = Counter + 1 Loop
Diese Schleife wird so lange abgearbeitet, bis ein Fehler auftritt (Overflow) oder der Rechner abgeschaltet wird.
114
Programmverzweigung
8.8 Die ForAll-Anweisung Die ForAll-Anweisung kommt bei der Verwendung von Listen zum Einsatz. Sie dient dazu, eine Schleife zu konstruieren, in welcher jedes Element der gegebenen Liste einmal bearbeitet wird. Man kann mit ForAll auch Array-Elemente der Reihe nach durchlaufen. Dabei wird zunächst die erste Dimension elementweise abgearbeitet, dann die zweite usw. Diese letzte Möglichkeit ist seltener von Interesse, da man sonst gezwungen ist, explizit zu überprüfen, wie »lang« eine Dimension ist, da es keinen anderen Weg gibt festzustellen, wann die nächste Zeile beginnt. Syntax: ForAll referenceVar In container statements End ForAll Dim Liste List As Integer Liste(1) = 100 Liste(2) = 200 Liste(3) = 300 Forall x in Liste MsgBox x End Forall
Dieses Beispiel gibt die Zahlen 100, 200 und 300 aus.
8.9 Programmsprung GoTo 8.9.1 Der GoTo-Sprung Der GoTo-Befehl stellt eine gefährliche Hinterlassenschaft der frühen Basic-Programmierung dar. Dieser Befehl springt zu dem angegebenen Zielpunkt und fährt dort mit der Programmausführung fort. Durch den GoTo-Befehl werden Programme schnell ziemlich unübersichtlich und unstrukturiert. Dieser Befehl sollte nur eingesetzt werden, wenn es keinen anderen vernünftigen Weg gibt. Das GoToStatement stellt einen unbedingten Sprungbefehl dar. Syntax: GoTo label Sub Proc MsgBox "Hallo" GoTo Marke MsgBox "Nochmals Hallo" Marke: End Sub
GoSub-Anweisungen
115
In diesem Beispiel wird die zweite Messagebox nicht angezeigt, da mit dem GoToBefehl bereits vorher zum Label Marke gesprungen wird.
8.9.2 On ... GoTo-Sprung Dieser Befehl ist eine Erweiterung des GoTo-Befehls und auch dieser Befehl sollte nur wohlüberlegt und dosiert verwendet werden. In dieser Variante kann durch einen numerischen Wert bestimmt werden, zu welchem Sprungziel verzweigt wird. Es wird zu der Sprungmarke verzweigt, deren Position in der Liste dem numerischen Wert entspricht. Wenn der Ausdruck einen numerischen Wert beinhaltet, welcher 0 oder größer der Anzahl der Sprungmarken ist, wird kein Sprung ausgeführt. Syntax: On value% GoTo labell1, label2, ... Sub Proc(Wahl As Integer) On Wahl GoTo Marke1, Marke2 Exit Sub Marke1: MsgBox "Marke1" Exit Sub Marke2: MsgBox "Marke2" Exit Sub End Sub
Hier wird anhand des übergebenen Wertes entschieden, welche Ausgabe erfolgen soll. Wenn die Variable Wahl eine 1 beinhaltet, wird zur Sprungmarke Marke 1 gesprungen und bei 2 zur Sprungmarke 2.
8.10 GoSub-Anweisungen 8.10.1 GoSub-Sprung Mit diesem Sprungbefehl wird die Programmausführung an der angegebenen Sprungmarke fortgesetzt. Nach der Ausführung oder dem Antreffen einer ReturnAnweisung wird an die Ausgangsstelle zurückgesprungen. Auch über eine Exitoder eine GoTo-Anweisung kann der Bereich der Sprungmarke verlassen werden. Syntax: GoSub label Sub Proc MsgBox "Prozeduranfang" GoSub Aufruf
116
Programmverzweigung
Exit Sub Aufruf: MsgBox "Unterprogramm" Return End Sub Es erfolgt erst die Ausgabe »Prozeduranfang«. Dann folgt der Unterprogrammaufruf mit der Ausgabe »Unterprogramm« und danach wird an die aufrufende Stelle zurückgekehrt und die Programmausführung dort fortgesetzt.
8.10.2 On ... GoSub-Sprung Dieser Befehl ist dem On ... GoTo-Befehl ähnlich. Mit On ... GoSub wird die Programmausführung an dem mit einem numerischen Wert gewählten Sprungziel als Unterprogramm fortgesetzt. Nach der Ausführung und dem Antreffen einer Return-Anweisung wird an die Ausgangsstelle zurückgesprungen. Auch über eine Exit- oder eine GoTo-Anweisung kann der Bereich der Sprungmarke verlassen werden. Syntax: On value% GoSub labell1, label2, ... Sub Proc(Wahl As Integer) On Wahl GOSub Marke1, Marke2 MsgBox "Ende der Prozedur" Exit Sub Marke1: MsgBox "Wahl war 1" Return Marke2: MsgBox "Wahl war 2" Return End Sub
Hier erfolgt die Ausgabe in der MessageBox in Abhängigkeit vom übergebenen Wert in der Variable Wahl. Sollte der Wert von Wahl weder 1 noch 2 sein, wird kein Sprung durchgeführt.
8.11 Exit-Anweisung 8.11.1 Exit Sub/Exit Function/Property Diese Anweisung dient dem vorzeitigen Verlassen einer Prozedur, Funktion oder eines Property-Programmblocks. Wenn die Programmausführung auf diese Anweisung trifft, springt sie sofort aus der aktuellen Prozedur heraus.
Fragen
117
8.11.2 Exit Do, Exit For, Exit Forall Diese Anweisungen dienen zum vorzeitigen Verlassen eines Schleifenblocks. Wenn die Programmausführung auf diese Anweisung trifft, wird die Programmanweisung unmittelbar hinter dem Schleifenblock fortgesetzt.
8.12 Fragen 1. Welche unbedingten Sprunganweisungen gibt es in LotusScript? 2. Warum sind GoTo-Anweisungen möglichst zu vermeiden? 3. Welche bedingten Sprunganweisungen haben Sie kennen gelernt? 4. Durch welche Anweisung wird eine längere If...Elseif...Elseif...-Kette üblicherweise ersetzt? 5. Welche Schleifenkonstrukte gibt es unter LotusScript? 6. Was bedeutet kopf- und was fußgesteuert? 7. Konstruieren Sie eine Endlos-Schleife. Kann diese Schleife verlassen werden? Wenn ja, wie?
9 9
Fehlerbehandlung
9.1 Verständnisvoraussetzungen Dieses Kapitel setzt Kenntnisse über die Deklaration von Prozeduren und deren Aufruf voraus. Außerdem sollte der Aufbau von LotusScript-Programmen bekannt sein.
9.2 Lernziel Dieses Kapitel zeigt Ihnen, wie Fehler in LotusScript erkannt und behandelt werden. In diesem Kapitel werden unter Fehlern ausschließlich Laufzeitfehler verstanden. Die Erkennung und Behandlung von Kompilierfehlern wird in Kapitel 2 »Entwicklungsumgebung(IDE)« besprochen.
9.3 Einleitung Die Fehlerbehandlung ist ein wichtiger Bestandteil der professionellen Programmierung. Sie ist ein unverzichtbares Hilfsmittel bei der Erstellung von ausfallsicheren und zuverlässigen Anwendungen. Durch die Fehlerbehandlung wird ein zuverlässiger Programmablauf gewährleistet, selbst dann, wenn ein oder mehrere Programmteile nicht ordnungsgemäß wie vorgesehen abgearbeitet werden können. Für das Abfangen der Laufzeitfehler wird in LotusScript die Anweisung On Error verwendet. Dieser Befehl legt fest, wie auf einen solchen Fehler während der Laufzeit reagiert werden soll. Ein Laufzeitfehler wird in anderen Programmiersprachen wie C++ auch als Ausnahme bezeichnet. Dabei bietet der Befehl dem Programmierer drei Variationen, auf solche Ausnahmen zu reagieren. Die erste Variation von On Error GoTo legt fest, dass bei Auftreten einer Ausnahme zu einer mit einem Label markierten Programmstelle gesprungen wird. Mit der zweiten Variante On Error Resume Next wird erreicht, dass das Programm ungeachtet eines Fehlers mit der folgenden Anweisung fortgesetzt wird. Im Standardfall wird bei einer Ausnahme diese an die darüber liegende Umgebung weitergegeben. Wenn also in einer aufgerufenen Funktion ein Fehler auftritt, dann wird diese sofort abgebrochen. Die Kontrolle des Programmablaufs wird unmittelbar an die aufrufende Funktion zurückgegeben. Falls in dieser an der Stelle des Programmaufrufs eine On Error...–Anweisung gültig ist, springt die Abarbeitung zum entsprechenden Label. Falls nicht, wird sofort zur nächsten darüber liegenden Funktion zurückgesprungen und wiederum der Laufzeitfehler mitgegeben. Dies setzt sich so
120
Fehlerbehandlung
lange fort, bis das Zurückspringen auf eine Fehlerbehandlung oder auf die Ebene des Programmeinstiegs stößt. Dieses Verhalten wird auch durch die dritte Variation On Error GoTo 0 erreicht. Wenn der Fehler die oberste Programmebene erreicht und auch diese den Fehler nicht bearbeitet, wird das Programm abgebrochen und eine Fehlermeldung an den Benutzer ausgegeben. Bei allen drei Varianten besteht die Möglichkeit, durch eine Fehlernummer den Fehlertyp zu bestimmen, auf den reagiert werden soll. Wenn kein Fehlertyp angegeben wird, reagiert die On Error-Anweisung auf alle Fehler. Die Syntax der On Error-Anweisung sieht also wie folgt aus: Syntax Statement On Error: On Error [ errNumber ] { GoTo label$ | Resume Next | GoTo 0 } Das folgende Beispiel zeigt das Verhalten sowohl ohne eine Fehlerbehandlung als auch mit den zwei möglichen Arten der Fehlerbehandlung: Sub Fehlerhaft1() On Error GoTo 0 Wert% = 0 A = 0% Wert% = 1/A% Msgbox Wert% End Sub
'Wie Standard ohne Fehlerbehandlung
'Löst den Fehler Division durch 0 aus
Dieses Programm würde mit der System-Fehlermeldung »Division by Zero« abbrechen. Eine Ausgabe durch das Programm findet nicht statt, da schon vor der Messagebox abgebrochen wird. Sub Fehlerhaft2() On Error Resume Next
Wert% = 0 A% = 0 Wert% = 1 /A%
'Bewirkt, dass bei einem Fehler die 'Programmausführung in der nächsten 'Zeile fortgesetzt wird
'Löst den Fehler "Division by Zero" 'aus, läuft aber ohne eine Ausgabe weiter
Msgbox Wert% End Sub
Bei dieser Prozedur wird keine Fehlermeldung ausgegeben. Bei Auftreten des Divisionsfehlers wird das Programm mit der Msgbox-Ausgabe fortgesetzt. Es folgt die Ausgabe von 0. Sub Fehlerhaft3() On Error GoTo Fehlereinsprung 'Bewirkt, dass bei einem Fehler die Programmausführung 'bei dem Label Fehlereinsprung fortgesetzt wird
Einleitung
Wert% = 0 A% = 0 Wert% = 1 /A%
121
'Löst den Fehler Division durch 0 aus
Msgbox Wert% Exit Sub Fehlereinsprung: 'Label, welches bei einem Fehler angesprungen wird Msgbox "Fehler bei Division" 'Ausgabe einer Meldung Resume Next End Sub
Durch die Verwendung des On Error-Befehls in dieser Prozedur wird beim Auftreten des Divisionsfehlers die Programmausführung am Label Fehlereinsprung fortgesetzt und die dortige Meldung mit der Messagebox ausgegeben. Danach wird die Prozedur normal beendet. Sehr wichtig ist das Setzen der Exit Sub-Anweisung vor dem Label. Dieses wird gerne vergessen, was dazu führt, dass auch ein fehlerfreier Programmlauf am Schluss noch den Abschnitt des Labels abarbeitet. Dies soll aber nur im Fehlerfall geschehen! Wie oben erwähnt, lässt sich eine On Error-Anweisung auf bestimmte Fehlertypen einschränken. Dazu ein kleines Beispiel: Sub Proc On Error 6 Resume Next A% = 0 Wert% = 1 / A% End Sub
Die On Error-Anweisung definiert die Fehlerroutine für Fehler mit der Fehlernummer 6. Dieser Fehlerwert steht für einen Overflow-Fehler. Da aber hier ein Divisionsfehler auftritt, wird der Fehler nicht abgefangen und die Fehlerbehandlung wird der darüber liegenden Prozedur überlassen. Eine On Error-Anweisung gilt immer innerhalb einer Prozedurumgebung. Das heißt, eine in einer Prozedur definierte Fehlerbehandlung verliert ihre Gültigkeit beim Verlassen dieser Prozedur. Beispiel für Gültigkeitsbereiche von Fehlerbehandlungen: Sub ProcA On Error GoTo Fehlereinsprung ’Fehlerbehandlung gilt innerhalb der ProcA A% = 0 Wert1% = 1 / A% ’Fehler führt zur Fehlerbehandlung Msgbox Wert1% Exit Sub
122
Fehlerbehandlung
Fehlereinsprung: Msgbox "Fehler bei Division" Resume Next End Sub Sub ProcB Call ProcA A% = 0 Wert2% = 1 / A% ’Führt zu einem Abbruch aufgrund des zweiten ’Divisionsfehlers, da die Fehlerbehandlung nur in der ’Prozedur ProcA gilt. Msgbox Wert2% End Sub
In diesem Beispiel soll die Funktion ProcB als erste ausgeführt werden. Die Prozedur ProcB ruft als Erstes die Prozedur ProcA auf. In der Prozedur ProcA wird eine Fehlerbehandlung definiert, die in Aktion tritt, wenn versucht wird, die Division für Wert1 auszuführen. Da eine Fehlerbehandlung definiert wurde, wird die Ausführung bei dem Label Fehlereinsprung fortgesetzt und die Fehlermeldung mit der Msgbox-Anweisung ausgegeben. Nach dem Rücksprung aus der Prozedur ProcA wird die Ausführung in ProcB fortgeführt. Dort taucht in der folgenden Programmzeile ein Fehler auf. Da aber in dieser Umgebung keine Fehlerbehandlung definiert ist, wird der Fehler als Systemfehler ausgegeben. Sub ProcA A% = 0 Wert1% = 1 / A% Msgbox Wert1% End Sub Sub ProcB On Error GoTo Fehlereinsprung Call ProcA Wert2% = 12 Msgbox Wert2% Exit Sub Fehlereinsprung: Msgbox "Fehler" Resume Next End Sub
In diesem Beispiel wird die Ausführung mit der Prozedur ProcB begonnen und als Erstes eine Fehlerbehandlung definiert. Danach wird die Prozedur ProcA aufgerufen. In dieser Prozedur löst die Division einen Fehler aus. Da innerhalb dieser Prozedur keine Fehlerbehandlung definiert wurde, wird der Fehler an die aufrufende Prozedur weitergegeben. Dort ist eine Fehlerbehandlung vorhanden und der Programmablauf springt zu dem Label Fehlereinsprung, wo die Fehlermeldung mit der Messagebox ausgegeben wird.
Einleitung
123
Wenn innerhalb einer Umgebung mehrere Fehlerbehandlungen für dieselben Fehlerarten definiert werden, wird immer die letzte Definition berücksichtigt. Wenn die erste Definition mit einer Fehlernummer eingeschränkt wurde und die zweite Definition ohne Fehlernummer erfolgt, gilt ebenfalls die letzte Definition. Eine besonders kritische Situation tritt ein, wenn innerhalb einer Fehlerbehandlung ein weiterer Fehler auftritt. In diesem Fall bricht das Programm sofort mit einer Fehlermeldung ab. Sub ProcA On Error GoTo Fehlereinsprung A% = 0 Wert% = 1 / A% Exit Sub Fehlereinsprung: Wert% = 1 / A% Resume Next End Sub
Hier taucht ein Fehler in der Fehlerbehandlung auf, und das Programm bricht sofort ab. Dieses lässt sich zum Glück auf einfache Weise vermeiden. Dazu muss innerhalb der Fehlerbehandlung einfach eine weitere On Error-Anweisung eingefügt werden: Diese muss allerdings über eine Resume Next-Variante aufgebaut werden. Da ein Fehler hierbei nicht beachtet wird, muss der Programmierer selbst dafür sorgen, dass dies geschieht. Dazu steht ihm die Funktion Err() zur Verfügung, die im Fehlerfall eine von 0 verschiedene Integerzahl liefert. Eine nähere Beschreibung finden Sie weiter unten. Sub ProcB On Error Resume Next Wert% = 1 / A% If Err <> 0 then Msgbox "Fehler bei der zweiten Division" End Sub Sub ProcA On Error GoTo Fehlereinsprung A% = 0 Wert% = 1 / A% Exit Sub Fehlereinsprung: Call ProcB Resume Next End Sub
Eine Fehlerbehandlung wird durch das Verlassen der aktuellen Umgebung (mit einer Exit Sub- oder Exit Function-Anweisung) oder durch Aufruf einer Variante von Resume beendet.
124
Fehlerbehandlung
Es gibt drei Varianten der Resume-Anweisung. Die Variante Resume 0 setzt die Programmausführung an der Stelle fort, an der der Fehler ausgelöst wurde (der Befehl, der den Fehler ausgelöst hatte, wird also wiederholt). Bei der Verwendung von Resume Next wird die Ausführung mit der Anweisung fortgesetzt, die dem Befehl folgt, welcher den Fehler erzeugt hat. Ein Sprung zu einem Label erfolgt mit der Resume Label-Anweisung. Syntax von Resume Resume [ 0 | Next | label$ ] Sub Proc On Error GoTo Fehlereinsprung A% = 0 Wert% = 1 / A% Exit Sub Fehlereinsprung: Msgbox "Fehler" Resume Next End Sub
In diesem Beispiel wird mit der Definition der Fehlerroutine begonnen. In der nächsten Programmzeile wird ein Fehler erzeugt, der dazu führt, dass die Anweisung nach dem Label fortgesetzt wird und die Ausgabe der Fehlermeldung mit der MessageBox getätigt wird. Nach der Ausgabe trifft das Programm auf die Resume Next-Anweisung und springt hinter den Befehl, der den Fehler ausgelöst hat. Danach wird die Prozedur ordnungsgemäß verlassen. Hätten wir das Exit SubStatement an dieser Stelle vergessen, so würde das Programm nach dem Rücksprung automatisch ein zweites Mal in den Abschnitt Fehlereinsprung laufen. Bei der Ausführung einer Fehlerroutine können Sie mittels den Funktionen Err, Erl und Error wichtige Information zur Identifikation des Fehlers abfragen. Die Funktion Err liefert die Fehlernummer als Integerwert. Syntax von Err() Err() Durch Erl lässt sich (zumindest theoretisch) die Zeile ermitteln, in der der Fehler aufgetaucht ist. Der Fehlertext wird mit Error herausgefunden. Allerdings werden Sie feststellen, dass die Funktion Erl zur Abfrage der Fehler erzeugenden Programmzeile praktisch unbrauchbar ist. Sie gibt im Allgemeinen eine Zahl zurück, die sich kaum mit der entsprechenden Zeile in Verbindung bringen lässt. Dies liegt im Wesentlichen daran, dass beim Kompilieren und Abspeichern das Script eines gesamten Moduls hintereinander geschrieben wird. Außerdem werden unsichtbare Zeilen hinzugefügt bzw. weggelassen. Weitere Einzelheiten wollen wir Ihnen ersparen. Der Tipp lautet: Hände weg von dieser Funktion! Dieser Fehler (als etwas anderes kann ein »normaler« Programmierer das beschriebene Verhalten wohl kaum empfinden) wird auch in den Foren von www.notes.net disku-
Einleitung
125
tiert. Voraussichtlich wird er in einem der folgenden Releases beseitigt werden. Wäre sehr schön! Mit der Anweisung Error wird ein Fehler erzeugt und die Fehlernummer und der Fehlertext werden an die Fehlerroutine geschickt. Syntax von Error Error integer%, [ errorText$ ] Die Parameter stehen für eine vom Benutzer frei vergebbare Fehlernummer und die Zeichenkette für den Text, der dem Fehler zugeordnet werden soll. Sub Proc Msgbox "Hallo" Error 9999, "Fehlermeldung" End Sub
Dieses Beispiel erzeugt nach der Ausführung der Messagebox die durch die ErrorAnweisung definierte Fehlermeldung. Wird eine Fehlernummer übergeben, die bereits von Notes vergeben wurde, wird der entsprechende Fehlertext des Systems ausgegeben. Daher kann man in diesem Fall den Fehlertext auch weglassen. Die verschiedenen Fehlernummern von LotusScript sind in der Datei lserr.lss als Konstanten abgelegt. Möchten Sie die Konstanten-Bezeichner verwenden, können Sie diese Datei per Include-Anweisung in das Script einbinden.
9.3.1 Einige Tipps zur Fehlerbehandlung Jede professionelle Anwendung sollte eine effiziente und strukturierte Fehlerbehandlung besitzen. Bei der Planung der Fehlerbehandlung sollte man daher einiges bedenken. Eine wichtige Aufgabe der Fehlerbehandlung ist es, dafür zu sorgen, dass alle reservierten Ressourcen wie Speicher, Dateien oder z. B. Peripheriegeräte auch in einem Fehlerfall wieder freigegeben werden, so dass andere Prozesse und Programme auf diese zugreifen können. Bei einer Datei wäre es z. B. fatal, wenn ein Prozess eine Datei (mittels Locking) in Beschlag nimmt und diese dadurch bei einem Laufzeitfehler von keinem anderen Programm mehr benutzt werden kann. Ein Beispiel hierfür ist eine Ausgabedatei, in welche von mehreren Prozessen abwechselnd Daten geschrieben werden. Sollte während der Laufzeit ein Programmfehler in einem der beteiligten Programme auftreten, würde der jeweilige Prozess diese Datei nicht ordnungsgemäß schließen und die anderen Prozesse könnten auf diese nicht mehr zugreifen. Sub AusgabeInDatei On Error GoTo Fehler Open "Ausgabe.txt" For Output As #1 Print #1, "Ausgabe des Programmteils begonnen"
126
Fehlerbehandlung
.... Print #1, "Ausgabe des Programmteils abgeschlossen" Close #1 Ende: Exit Sub Fehler: Print #1, "Ausgabe nach Programmfehler" Close #1 Resume Ende End Sub
Dieses Beispiel würde nach einem Laufzeitfehler, der während der Ausgabe in die Datei auftritt, die entsprechende Meldung in dieselbe Datei schreiben und diese dann ordnungsgemäß schließen. Würde das Close-Statement im Abschnitt Fehler vergessen, so könnte ein anderer Prozess auf die Datei nicht zugreifen. Des Weiteren sollte die Fehlerbehandlung eingesetzt werden, um Fehlermeldungen für den Benutzer auszugeben. So ist es im Falle eines unerwarteten Auftretens eines Laufzeitfehlers möglich, die Fehlerquelle anhand der Meldung ungefähr einzugrenzen. Sub AusgabeMeldung On Error GoTo Fehler Open "Datei.DAT" For Input As #1 Input #1, Kette$ Close #1 Ende: Exit Sub Fehler: MessageBox "Fehler " & Error() & _ " in der Funktion AusgabeMeldung" Close #1 Resume Ende End Sub
Ein guter Leitsatz für den Aufbau einer effektiven Ausnahmebehandlung lautet: eine Ausnahme in einer Programmschachtelung so tief wie möglich erzeugen und sie so hoch wie möglich bearbeiten. Sub ProcA() A$ = InputBox("Eingabe") IF A$ = "" Then Error 9999, "Leere Eingabe" End Sub Sub ProcB() B$ = InputBox("Weitere Eingabe") IF B$ = "" Then Error 9999, "Leere Eingabe" End Sub
Fragen
127
Sub MainProc On Error GoTo Fehler Call ProcA() Call ProcB() Ende: Exit Sub Fehler: MessageBox Error() & " in Prozedur MainProc" Resume Ende End Sub
In diesem Beispiel wird der jeweilige Fehler in den einzelnen Prozeduren erzeugt und in der obersten Prozedur aufgefangen.
9.4 Fragen 1. Mit welchem Befehl werden Fehlerbehandlungsmaßnahmen definiert? 2. Welche Anweisung müssen Sie wählen, damit die Programmausführung im Fehlerfall mit der auf den Fehler folgenden Zeile fortgesetzt wird? 3. Was müssen Sie in Bezug auf Fehler beachten, die innerhalb einer Fehlerbehandlungsroutine auftreten können? 4. Wie können Sie erreichen, dass für bestimmte Fehlertypen eine bestimmte Behandlungsroutine aufgerufen wird? 5. Wie werden Fehlerbehandlungen abgeschlossen? 6. Welche Anweisung sollte vor der ersten mit einem Label versehenen Fehlerbehandlungsroutine stehen, damit diese nur im Fehlerfall abgearbeitet wird? 7. Wie verhält sich Notes/Domino, wenn Sie einen Fehler nicht behandeln?
10 10
Der Protokollmechanismus
10.1 Verständnisvoraussetzungen Das Kapitel setzt ein fundiertes Grundwissen über die Programmierung unter LotusScript voraus.
10.2 Lernziel In diesem Kapitel wird vermittelt, wie in LotusScript eine effektive Methode der Protokollierung des Programmablaufs aufgebaut werden kann.
10.3 Einleitung In jeder komplexeren Anwendung sollte eine Protokollierung von wichtigen Ereignissen und auftretenden Fehlern implementiert werden. Eine Protokollierung dient zur Dokumentation erfolgreicher Programmabläufe sowie der Analyse von auftretenden Laufzeitfehlern. Häufig richtet sich eine Fehlermeldung nicht an den aktuellen Anwender, sondern an den Administrator der Anwendung. Der aktuelle Benutzer kann mit der Fehlermeldung nur bedingt etwas anfangen. Dafür ermöglicht das Protokoll mit einer detaillierten Fehlerbeschreibung dem Administrator die genauere Fehleranalyse. Dabei ist besonders wichtig, dass die Protokollierung bei im Hintergrund ablaufenden Prozessen ohne eine Interaktion mit dem Anwender ablaufen kann. Der Administrator kann im Nachhinein feststellen, ob solche »unsichtbar« ablaufenden Programme fehlerfrei gearbeitet haben. Auch ist ihm eine schnelle Fehlereingrenzung möglich. Aufgaben des Protokolls:
X X
Information über den Erfolg wichtiger Programmläufe Ausgabe wichtiger Fehlermeldungen, die eine nachhaltige Auswirkung haben
Bei der Planung der Protokollausgaben sollte man unbedingt bedenken, dass dieses später auch jemand lesen muss. Das heißt, die Ausgaben sollten kurz und bündig aufgebaut und eindeutig zu verstehen sein. Als Erstes sollte zu erkennen sein, ob es sich um einen Fehler, eine Warnung oder nur ein Ereignis handelt. Des Weiteren sollte die Anzahl von Meldungen ein gewisses Maß nicht überschreiten, da das Protokoll sonst unübersichtlich wird und die Analyse erschwert. Es ist auch denkbar,
130
Der Protokollmechanismus
verschiedene Log-Level aufzubauen, die sich im Detaillierungsgrad des Protokolls unterscheiden. Aufbau des Protokolls:
X X X
kurz und sachlich deutliche Kennzeichnung von Fehlern, Warnungen oder Ereignissen eine maßvolle Menge von Meldungen
Je komplexer und umfangreicher eine Anwendung ist, umso mehr Fehlermeldungen, Warnungen oder Ereignisse werden ausgegeben. Bei keiner Anwendungsentwicklung sollte man die Dokumentation der Anwendung ganz aus den Augen verlieren. In einer guten Dokumentation sollten auch die wichtigsten Meldungen der Protokolle beschrieben werden. Bei Fehlermeldungen oder Warnungen sollten nach Möglichkeit auch Wege zur Fehlerbeseitigung aufgezeigt werden. Die Protokollmeldungen sollten in der Anwendungsdokumentation aufgeführt und erklärt werden. Eine wichtige oft nicht bedachte Situation sind möglicherweise auftretende Fehler während der Protokollierung selbst. Ein solcher Fehler kann dazu führen, dass eine Endlos-Schleife bzw. eine Endlos-Rekursion entsteht. Letztere ist natürlich nur theoretisch »endlos«. Sie wird spätestens mit dem Überlaufen des Programm-Stacks beendet. Bei einem Fehler im Protokollmechanismus sollte daher unter Umständen ein anderer Mechanismus gewählt werden, um den Anwender über das Problem zu informieren. Sollte auch dieses nicht fehlerfrei funktionieren, bleibt nur das Unterdrücken dieser speziellen Meldung. Eine Fehlermeldung innerhalb der Fehlerroutine sollte immer verhindert werden. Ein anderer wichtiger Punkt bei der Realisierung der Protokollierung ist das regelmäßige Archivieren oder Löschen alter Protokolldaten. Sollte dieses bei der Implementierung nicht bedacht werden, kann ein Protokoll sehr schnell unnötig viel Speicherplatz belegen. Nicht mehr benötigte Einträge sollten aus dem Protokoll entfernt werden. In Lotus Notes existieren vier mögliche Ziele für die Protokollausgaben. Als Medien der Protokollausgabe stehen die Textdatei, die Notes-Datenbank, das Agent-Protokoll oder E-Mails zur Verfügung. Alle diese Variationen werden mit Hilfe der Scriptklasse NotesLog verwendet. Die Medien der Protokollausgabe:
X X
Textdatei Notes-Datenbank
Allgemeine Implementierung
X X
131
Agent-Protokoll E-Mails
10.4 Allgemeine Implementierung Jede Implementierung der Protokollierung beginnt mit der Generierung einer Instanz der NotesLog-Klasse. Der Konstruktor der NotesLog-Klasse erwartet als Parameter den (frei vergebbaren) Programmnamen der laufenden Anwendung, aus der die Protokollmeldungen erzeugt werden. Syntax des Konstruktors: Dim variableName As New NotesLog( programName$ ) Für das Erzeugen eines Objektes vom Typ NotesLog stehen dem Entwickler zwei Möglichkeiten zur Verfügung. Bei der ersten Möglichkeit wird das Objekt bei der Deklaration gleichzeitig mit dem Schlüsselwort New angelegt. Beispielsweise so: Dim LogObj As New NotesLog("Protokollprogramm")
Die andere Möglichkeit ist, zunächst eine Variable vom Typ NotesLog zu deklarieren und die Instanz erst später mit den Befehlen New und Set zu erzeugen und zuzuweisen. Dim LogObj As NotesLog Set LogObj = New NotesLog("Protokollprogramm")
Nach dem Anlegen der Instanz folgt die Wahl des Ziel-Mediums des Protokolls (Notes-Datenbank, Textdatei, Mail oder Agent-Protokoll). Ungeachtet des ZielMediums muss die Instanz der NotesLog-Klasse am Ende mit der Methode Close wieder geschlossen werden. Jedes geöffnete Protokoll muss wieder geschlossen werden. Ein mögliches Beispiel für das Initialisieren und ordnungsgemäße Schließen eines Protokolls sähe also wie folgt aus: Dim LogObj As New NotesLog("Protokollprogramm") Call LogObj.Close()
132
Der Protokollmechanismus
10.5 Die Protokollmedien 10.5.1 Protokollieren in einer Datenbank Unter Lotus Notes bietet sich naturgemäß die Protokollierung in einer NotesDatenbank an. Um dem System mitzuteilen, dass eine Notes-Datenbank verwendet werden soll, wird diese zu Beginn der Protokollierung geöffnet und mit dem Protokollobjekt (NotesLog) verbunden. Dazu wird die Methode OpenNotesLog der Klasse NotesLog verwendet. Bei dieser Methode werden der Server und der Dateiname der Protokoll-Datenbank übergeben. Syntax OpenNotesLog: Call notesLog.OpenNotesLog( serverName$, fileName$ ) Ein Aufruf könnte zum Beispiel so aussehen: Call LogObj.OpenNotesLog("", "log4a.nsf")
Dieses Beispiel öffnet die angegebene Notes-Datenbank log4a.nsf auf dem aktuellen Server und schreibt alle folgenden Meldungen in diese Datentank. Hierbei ist zu beachten, dass ein auf einem Server ablaufendes Script auf keine Datenbank auf einem anderen Server zugreifen kann. Außerdem benötigt die Anwendung mindestens Leserechte auf der Datenbank, um diese zu öffnen. Zur Protokollierung wird darüber hinaus mindestens das Schreibrecht als Autor benötigt. Etwaige Fehler bei dem Zugriff auf die Protokolldatei sollten in der Fehlerbehandlung berücksichtigt werden, da sonst die oben erwähnten Probleme Endlos-Schleife oder Endlos-Rekursion auftreten können. Für die Protokoll-Datenbank existiert unter Notes eine Datenbank-Vorlage, die sofort genutzt werden kann. Diese Vorlage hat den Titel StdR4AgentLog und ist unter dem Dateinamen ALOG4.NTF zu finden. Für jede Fehlermeldung oder Ereignismeldung wird in ihr ein Dokument mit vordefinierten einheitlichen Items angelegt. Beschreibung der Items eines Protokolldokuments Das Item A$PROGNAME übernimmt den Namen des Programms, welcher dem NotesLog-Objekt bei der Instanziierung übergeben wurde. Das Item A$LOGTIME enthält Uhrzeit und Datum der Meldung. Der Name des Anwenders, welcher die Aktion ausgeführt hat, wird in dem Item A$USER gespeichert. Das Item A$LOGTYPE enthält einen der beiden Werte »Error« oder »Action« und ermöglicht damit, den Typ der Meldung zu unterscheiden. Das Item A$ACTION existiert nur auf einem Protokolldokument des Typs Meldung und beinhaltet die Beschreibung der Aktion. Bei einer Fehlermeldung ist zusätzlich das Item A$ERRCODE mit der Fehlernummer und das Item A$ERRMSG mit der Fehlermeldung im Klartext zu finden. Das folgende Beispiel öffnet eine Protokolldatenbank auf dem Server »Testserver« mit dem Dateinamen »Logdb.nsf« und schließt sie am Ende wieder.
Die Protokollmedien
133
Dim LogObj As New NotesLog("Protokollprogramm") Call LogObj.OpenNotesLog("Testserver", "Logdb.nsf") .... Call LogObj.Close()
10.5.2 Protokollierung in einer Textdatei Auch eine Textdatei kann Protokollierungsmeldungen aufnehmen. Diese wird ebenso wie die Protokolldatenbank mit dem Einsatz eines Objektes der Klasse NotesLog realisiert. Im Unterschied zur vorher beschriebenen Protokollierungsart wird hier bei der Instanziierung eine Datei als Ziel gewählt und geöffnet. Dafür steht die Methode OpenFileLog zur Verfügung. Dieser Methode wird als Parameter der Dateiname des Protokollziels übergeben. Das könnte z. B. auf folgende Weise implementiert werden: Syntax OpenFileLog: Call notesLog.OpenFileLog( path$ ) Call LogObj.OpenFileLog("Meldung.txt")
Durch die OpenFileLog-Methode wird eine neue oder eine eventuell bestehende Datei geöffnet und die neuen Meldungen angehängt. Der bereits bestehende Inhalt geht dabei nicht verloren. Neue Protokolleinträge werden an ggf. bereits bestehende Inhalte angehängt. Eine andere Möglichkeit wäre es, die Eigenschaft OverwriteFile zu verwenden. Wenn diese Eigenschaft den Wert TRUE hat, wird die Datei vor dem Öffnen gelöscht und neu angelegt. Der Standardwert dieser Eigenschaft ist FALSE. LogObj.OverwriteFile = True LogObj.OpenFileLog("Meldung.txt")
Hiernach liegt die geöffnete Textdatei vor und kann mit den Meldungen gefüllt werden. Sollte die Datei nicht existieren, wird sie durch die beiden Methoden neu angelegt. Sollte allerdings der angegebene Pfad nicht existieren oder keine entsprechenden Rechte in dem Verzeichnis vorliegen, wird ein Fehler erzeugt. So ein Fehler sollte unbedingt abgefangen werden, damit nicht die oben erwähnte Endlos-Schleife oder Endlos-Rekursion auftreten kann.
134
Der Protokollmechanismus
10.5.3 Protokollierung durch Mails Bei dieser Variante werden die Protokollmeldungen in ein Mail-Dokument geschrieben und dieses dann an eine angegebene Adresse geschickt. Diese Variante wird mit der Methode OpenMail eingeleitet. Als Parameter werden der Mail-Empfänger und die Angabe eines Themas (Subject) erwartet. Syntax von OpenMail: Call notesLog.OpenMailLog( recipient$, subject$ ) Call LogObj.OpenMailLog("Klaus Frankenstein",_ "Achtung Explosionsgefahr im Agent")
Nach dem Öffnen können (Fehler)meldungen aufgezeichnet werden. Beim Schließen mit der Methode Close wird die mit den Meldungen »gefüllte« Mail an die angegebene Adresse versandt. Für unser Beispiel sieht das so aus: Call LogObj.Close()
Anders als beim üblichen Mail-Versand, den der Anwender kennt, wird bei der Protokollierung keine Kopie für den Absender aufbewahrt.
10.5.4 Protokollierung ins AgentLog Für die Protokollierung von Aktivitäten eines Agenten bietet sich das AgentLog als Ziel der Aufzeichnungen an. Dieses Protokoll erhält der Anwender, wenn er den Agent markiert und den Menüpunkt Log Agent | Protokoll... aufruft. Das AgentLog wird vor jeder Ausführung des Agents gelöscht. Syntax von OpenAgentLog: Call notesLog.OpenAgentLog Das Protokollieren in einem AgentLog ist nur bei der Ausführung von Agents möglich. Zu Beginn wird das AgentLog mit dem Befehl Call LogObj.OpenAgentLog
geöffnet. Dann folgt wieder die Erzeugung der Meldungen. Am Ende der Protokollierung wird das Logging-Objekt auch bei dieser Variante mit dem Befehl Call LogObj.Close
geschlossen.
Die verschiedenen Arten der Protokollmeldungen
135
10.6 Die verschiedenen Arten der Protokollmeldungen 10.6.1 Meldungen Die Aktions-Meldung ist die einfachere Art. Sie ist zum Beispiel vorgesehen, um während des Programmablaufs verschiedene Hinweise auf gestartete oder abgeschlossene Programm-Abschnitte zu dokumentieren. Häufig ist es ratsam, den Start und das Ende eines Agentenlaufes per Aktions-Meldung anzuzeigen. Eine AktionsMeldung wird mit der Methode LogAction erzeugt. Dieser Methode wird als Parameter der Meldungstext übergeben. Call LogObj.LogAction("Start des Programms XYZ um " & Now & ".")
10.6.2 Fehlermeldungen Diese Meldungsart kommt bei einem Laufzeitfehler zum Einsatz. Sie schreibt eine Fehlermeldung ins Protokoll. Sie wird mittels der Methode LogError erzeugt. Als Parameter werden Fehlernummer und Fehlerbeschreibung übergeben. Call LogObj.LogError(1, "Ich stehe vor einer Situation, die ich nicht selbstständig meistern kann")
Auch bei dieser Variante muss das Protokoll am Ende mit der Methode Close() geschlossen werden.
10.7 Fragen 1. Wozu dient eine Protokollierung? 2. An wen richtet sich die Protokollierung? 3. Welche unterschiedlichen Arten der Protokollmeldungen kennen Sie? 4. Welche Klasse dient unter LotusScript der vereinfachten Protokollierung? 5. Welche Ziele zur Aufnahme und Sichtbarmachung der Protokollmeldungen können in dieser Klasse verwendet werden? 6. Was ist hinsichtlich möglicher Fehler innerhalb der Protokollierungsroutinen zu beachten? 7. Was ist bezüglich der Anhäufung von alten Protokollmeldungen zu beachten?
11 11
Die AgentProgrammierung
11.1 Verständnisvoraussetzungen Das Kapitel setzt umfangreiche Kenntnisse in der LotusScript-Programmierung, insbesondere auch Kenntnisse der Notes/Domino-Klassen voraus.
11.2 Lernziel Das Kapitel will aufzeigen, was bei der Programmierung von Agents unter LotusScript zu beachten ist. Es kommen insbesondere Aspekte der Synchronisation und zu beachtende Details bei Hintergrund-Agenten zur Sprache. Als HintergrundAgenten werden Agenten bezeichnet, die auf einem Server automatisiert ablaufen, also beispielsweise die periodischen Agenten. Neu ist die Möglichkeit, einen Agenten per RunOnServer-Methode auch von einem Script aus als Hintergrund-Agent ablaufen zu lassen. Als Synonym für den Begriff »Hintergrund Agent« wird auch der Ausdruck »Server Agent« verwendet.
11.3 Funktionen zum Synchronisieren von Agents Es gibt unter LotusScript einige Funktionen, die es ermöglichen, den Ablauf von parallelen Agents zu steuern. Dazu wird das Handling durch eine Art Lock-Objekt ermöglicht. Damit kann man die gleichzeitige Bearbeitung von Objekten und Ressourcen durch parallel ablaufende Programme verhindern bzw. serialisieren (in Serie zwingen). Würde man dies unterlassen, könnte der gleichzeitige Zugriff von parallelen Agenten zu unvorhersehbaren Resultaten führen, wie das folgende Szenario kurz erläutert: Stellen Sie sich einen Agenten vor, der den Kontostand einer Person pflegt, der in einem Notes-Dokument abgelegt ist. Stellen Sie sich weiter vor, der Agent würde (quasi) zur gleichen Zeit zweimal aufgerufen, wobei er im ersten Fall den Auftrag erhält, dem Konto 100 DM gutzuschreiben und im anderen Fall den Auftrag, 50 DM als Abgang zu buchen. Dann würden beide Aufrufinstanzen (Threads) zunächst den Kontostand abfragen und dann in dem einen Fall 100 DM addieren und im anderen Fall 50 DM subtrahieren und beide würden anschließend den neuen Betrag in das Feld Kontostand zurückschreiben. Da beide Aufrufinstanzen zur gleichen Zeit aufgerufen wurden, haben beide den gleichen Kontostand gele-
138
Die Agent-Programmierung
sen. Je nachdem, welche Instanz mit ihrer Bearbeitung zuletzt fertig ist, wird diese ihr Ergebnis auch als letzte in das Feld Kontostand schreiben. Damit würde das Ergebnis der anderen Aufrufinstanz überschrieben. Damit wäre aber das Ergebnis der ersten Aufrufinstanz »verloren gegangen«. Deshalb muss dafür gesorgt werden, dass eine der beiden »parallel« arbeitenden Instanzen zunächst das Ergebnis der anderen abwartet, bevor sie selbst den (nun bereits veränderten) Kontostand abfragt und dann ihre Operation darauf ausführt.
11.3.1 Die Funktion CreateLock Als Erstes wäre da die Funktion CreateLock. Mit dieser Funktion wird ein LockObjekt angelegt. Dazu wird der Funktion der Name des neuen Lock-Objektes übergeben. Zurück erhält man einen Handle in Form eines Integerwertes, welcher auf das Lock-Objekt referenziert. Syntax der Funktion CreateLock: handle% = CreateLock( name$ )
11.3.2 Die Funktion DestroyLock Ein mit CreateLock erzeugtes Lock-Objekt wird mit der Funktion DestroyLock wieder entfernt. Dazu wird die Funktion mit dem Handle des Lock-Objekts aufgerufen. Die Funktion liefert TRUE zurück, falls das Lock-Objekt erfolgreich gelöscht werden konnte. Syntax der Funktion DeleteLock: flag% = DeleteLock( handle% )
11.3.3 Die Funktion CodeLock Die Funktion CodeLock identifiziert ein Lock-Objekt anhand des übergebenen Handles und versucht dieses für sich zu reservieren. Sollte das Lock-Objekt frei sein, so wird es reserviert und der Wert TRUE zurückgegeben. Ansonsten wartet das System mit der Programmausführung, bis das Lock-Objekt verfügbar wird. Auf diese Weise kann ein Lock-Objekt zwischen verschiedenen parallel arbeitenden Agenten »herum gereicht« werden. Dadurch wird dafür gesorgt, dass immer nur die Aufrufinstanz, die gerade über das Lock-Objekt verfügt, mit einer bestimmten Ressource arbeiten kann. Syntax der Funktion CodeLock: flag% = CodeLock( handle% )
11.3.4 Die Funktion CodeUnLock Das Gegenstück zu der Funktion CodeLock ist die Funktion CodeUnLock. Diese Funktion hebt die Reservierung, welche durch CodeLock erfolgt ist, wieder auf.
Die Anweisung Sleep und ihre Verwendung
139
Syntax der Funktion CodeUnLock: flag% = CodeUnLock( handle% ) Dim nLocking As Integer Sub Initialize nLocking = CreateLock("Meine Anwendung") Call Kritisch End Sub Sub Terminate x = DestroyLock(nLocking) End Sub Sub Kritisch result = CodeLock(nLocking) Print "Dieser Bereich kann nur von einer " &_ " Aufrufinstanz gleichzeitig durchlaufen werden." result = CodeUnLock(nLocking) End Sub
11.4 Die Anweisung Sleep und ihre Verwendung Im Zusammenhang mit der Multithread-Programmierung ist die Sleep-Anweisung ein wichtiges Hilfsmittel. Sleep dient dazu, die Programmausführung für einen bestimmten Zeitraum zu unterbrechen. Anders als bei vom Entwickler eingebauten Endlos-Schleifen wird bei der Ausführung von Sleep keine unnötige Prozessorzeit verschwendet. Für die Zeit »des Schlafens« kann sich die CPU anderen Prozessen widmen. Syntax der Funktion Sleep: Sleep( seconds# ) Sleep(60)
'Wartet mit der Programmausführung 1 Minute
11.5 Der Kontext bei Webagents Um die Umgebung eines Webaufrufs in den Webagents verarbeiten zu können, kann man die Eigenschaft DocumentContext der NotesSession-Klasse nutzen. Diese Eigenschaft beinhaltet eine Referenz auf ein Notes-Dokument, welches die CGI-Variablen der aktuellen Webumgebung enthält. Dieses Dokument kann einerseits auf die CGI-Variablen hin ausgelesen werden. Es kann aber auch mit zusätzlichen Informationen versehen werden.
140
Die Agent-Programmierung
Dim session As New NotesSession Dim note As NotesDocument Set note = session.DocumentContext Print "Anwender = " + note.remote_user(0)
Dieses Beispiel gibt mittels der CGI-Variablen »Remote_User« den Namen des aktuellen Webanwenders aus.
11.5.1 Einige Beispiele für CGI-Variablen CGI-Variablenname
Inhalt
Auth_Type
Benutzer-Authentifikationsmethode der Seite
Content_Length
Länge der vom Web-Client übermittelten Inhalte
Content_Type
MIME-Type der übermittelten Inhalte
Gateway_Interface
CGI-Version, die der Server unterstützt.
HTTP_Accept
MIME-Typen, die vom Client akzeptiert werden.
HTTP_Referer
Die angeforderte URL
HTTPS
Zeigt an, ob SSL aktiviert ist
HTTP_User_Agent
Typ des Client-Browsers
Path_Info
Zusätzliche Information in der Pfadangabe
Path_Info_Decoded
Decodierte Pfadangabe
Path_Translated
Übersetzte Pfadangabe
Query_String
Angaben, welche dem ? in der URL folgen (also Aktionsbezeichner und eventuell vorhandene Parameter)
Query_String_Decoded
Decodierte Querystringangabe
Remote_Addr
IP-Adresse des Clients
Remote_Host
Name des Clientcomputers
Remote_Ident
Benutzername, der dem Server gemeldet wird
Remote_User
Authentifizierter Benutzername
Request_Content
Daten, welche mit einer HTTP-POST-Anforderung geschickt wurden
Request_Method
HTTP-Methode, mit welcher die Anforderung gemacht wurde (POST, GET, HEAD, ...)
Script_Name
Virtueller Pfad zum ausführenden Script
Server_Name
Servername
Server_Protocol
Serverprotokoll, mit dem die Anfrage geschickt wurde
Server_Port
Der IP-Port, über die die Anfrage einging
Server_Software
Name und Version der Serversoftware, welche den CGI-Code ausführt
Tabelle 11.1: CGI-Variablen
Die RunOnServer-Anweisung
141
11.6 Die RunOnServer-Anweisung Die Anweisung RunOnServer dient zum Ausführen eines Server-Agents durch ein lokales LotusScript-Programm. Sie bewirkt also die Ausführung im »Hintergrund«. Dim Dim Dim Dim
session As New NotesSession db As NotesDatabase agent As NotesAgent nStatus As Integer
Set db = session.CurrentDatabase Set agent = db.GetAgent("Testagent") nStatus = agent.RunOnServer() Print nStatus
Dieses Programm führt den Agenten »Testagent« auf dem Server aus und wartet mit der weiteren Ausführung, bis dieser Agent auf dem Server beendet wurde. Dann gibt es den Status aus. Die Anweisung RunOnServer kann nur auf Datenbanken ausgeführt werden, die auf dem Server liegen.
11.7 Einige wichtige Einschränkungen 11.7.1 Verwendung von Frontend-Klassen Die LotusScript-Notes-Klassen lassen sich in zwei Gruppen einteilen. Die eine Gruppe umfasst die Frontend-Klassen und die andere die Backend-Klassen. Es ist nicht möglich, in Agents, welche auf dem Server als Hintergrund-Agenten ablaufen, Frontend-Klassen zu verwenden. Zu den Frontend-Klassen gehören z. B. NotesUIWorkspace und NotesUIDocument.
11.7.2 Zugriff von Serveragenten auf andere Server Es ist nicht möglich, von einem Agenten, welcher auf einem Server als Hintergrundagent ausgeführt wird, auf eine Datenbank auf einem anderen Server zuzugreifen. Dim session As New NotesSession Dim db As NotesDatabase Set db = session.GetDatabase("AndererServer", "names.nsf")
Sollte »AndererServer« nicht gerade der Name des eigenen Servers sein, so können diese Anweisungen nicht ausgeführt werden.
142
Die Agent-Programmierung
11.8 Fragen 1. Was ist ein Hintergrund-Agent? 2. Wie können parallel laufende Hintergrund-Agenten synchronisiert werden? 3. Wozu dient die Anweisung Sleep? Welche Vorteile hat sie gegenüber EndlosSchleifen? 4. Was kann ein Hintergrund-Agent nicht tun? 5. Wie kann ein Agent von einem Script als Hintergrund-Agent gestartet werden?
12 12
Aufruf externer Programme
12.1 Verständnisvoraussetzungen Es werden keine besonderen Kenntnisse vorausgesetzt.
12.2 Lernziel Die hier besprochenen Funktionalitäten eröffnen dem Notes-Entwickler die Einbindung von externem Programmcode in LotusScript-Anwendungen. Da damit einige Schwierigkeiten administrativer und rechtlicher Art verbunden sind, die dem Entwickler nur auf diesem speziellen Gebiet begegnen, wird auf diese Problemfelder besonders eingegangen. Auch wird auf wichtige Aspekte der Plattformunabhängigkeit hingewiesen.
12.3 Ausführen von externen Programmen In Lotus Notes wird dem Entwickler die Möglichkeit geboten, externe Programme in das eigene Programm einzubinden und aufzurufen. Dabei gibt es unter anderem die Möglichkeit, solche Aufrufe mit Hilfe von DLL-Dateien zu realisieren.
12.4 Einbinden von externen Anwendungen in eigene LotusScript-Dateien Um eine externe Anwendung benutzen zu können, wird diese bei der Entwicklung und bei der Ausführung des Programms auf dem jeweiligen Computer benötigt. Dies sollte schon im Vorfeld einer Entwicklung bedacht werden, denn das Einspielen von externen Programmen wirft in vielen Fällen einige Diskussionspunkte auf.
144
Aufruf externer Programme
12.5 Lizenzrechtliche Probleme bei der Verwendung von externen Anwendungen Zuerst gilt es, die lizenzrechtlichen Bestimmungen für den Einsatz der externen Programmdateien zu klären. Die externen Programme müssen nicht immer komplette Anwendungen sein. Aber auch externe Bibliotheken unterliegen den Lizenzbestimmungen und eine unerlaubte Kopie stellt einen Verstoß dar. Daher sollte schon im Vorfeld geklärt werden, welche Dateien auf dem Zielrechner, auf dem später die Anwendung laufen soll, vorhanden sind und welche kopiert werden müssen.
12.5.1 Sicherheits-Probleme bei der Verwendung von externen Anwendungen Eine externe Datei in Form einer kompilierten Anwendung, deren Programmcode nur noch in kompilierter Form vorhanden ist, ist nicht mehr ohne weiteres zu analysieren. Daher kann ein Administrator nicht so einfach feststellen, welche Aktionen in solch einer Anwendung verborgen sind. Auch hat so eine Anwendung einen großen Freiraum, was den Zugriff auf den jeweiligen Computer betrifft. Alle diese Punke werden bei einem sicherheitsbewussten Administrator ein mulmiges Gefühl in der Magengegend verursachen. Die Einspielung einer fremden Anwendung ohne Programmcode fordert großes Vertrauen in den Entwickler seitens des Administrators. Auf diese Probleme sollten sich also LotusScript-Entwickler einstellen, da Nichtbeachtung das Scheitern eines ganzen Projektes zur Folge haben könnte.
12.5.2 Administrative Probleme bei der Verwendung von externen Programmen Wenn eine Anwendung für Lotus Notes entwickelt wird, wird diese meistens über den Notes Server allen Anwendern zugänglich gemacht. Dieses funktioniert allerdings nicht für externe Anwendungen. Bei externen Anwendungen müssen separate Dateien auf die Arbeitsplätze der Anwender verteilt oder sogar installiert werden. Dieses kann in großen Netzwerken einen größeren Aufwand bedeuten. Unter Umständen bringt die Verwendung von externen Anwendungen z. B. in Form von dynamischen Bibliotheken den »Turnschuh«-Administrator hervor, der die DLLs in jede lokale Maschine »per Hand« einspielt.
12.5.3 Kompatibilitätsprobleme bei der Verwendung von externen Programmen Lotus Notes ist auf vielen verschiedenen Systemen im Einsatz. Die Entwicklung unter LotusScript erlaubt es, die meisten Datenbanken gleichzeitig unter unterschiedlichen Systemen wie z. B. Windows und AS/400 zu nutzen. Bei externen Anwendungen ist dieses systemübergreifende Austauschen nicht mehr so einfach möglich. Eine externe Anwendung wie z. B. eine DLL-Datei ist meistens nur für ein
Wann der Einsatz von externen Anwendungen sinnvoll ist
145
System entwickelt worden und der Einsatz auf einem anderen System ist nicht möglich. Um die Notes-Entwicklungen auf mehreren Systemen verfügbar zu machen, müsste die externe Anwendung also für alle eingesetzten Systeme vorhanden sein, was unter Umständen einen großen Aufwand bedeutet.
12.6 Wann der Einsatz von externen Anwendungen sinnvoll ist Es sprechen also viele Gründe gegen den Einsatz von externen Anwendungen, aber es gibt auch viele Punkte, die für einen solchen Einsatz sprechen. Wenn z. B. eine Anwendung nur unter Windows betrieben wird und sichergestellt ist, dass alle Arbeitsplätze die externe Anwendung zur Verfügung stellen, dann kann die Verwendung von externen Programmen durchaus angezeigt sein.
12.7 Art der externen Anwendungen 12.7.1 Dynamische Bibliotheken Die einfachste Möglichkeit, externe Applikationen in einer Notes-Anwendung einzubinden, ist die Verwendung von dynamischen Bibliotheken. Unter vielen Entwicklungssystemen werden statische Bibliotheken verwendet. Die statischen Bibliotheken werden bei der Entwicklung in das Programm eingebunden. Die dynamischen Bibliotheken werden hingegen erst zur Laufzeit der Anwendung aufgerufen. Während der Laufzeit wird die Bibliothek geladen und die Prozedur aufgeführt und dann die Bibliothek wieder aus dem Speicher entfernt. Dynamische Bibliotheken sind in vielen Betriebssystemen vorhanden. Unter MSDOS heißen sie Overlays, unter Windows bzw. OS2 DLL und unter Unix LIB.
12.7.2 Verwendung von dynamischen Bibliotheken Um unter LotusScript dynamische Bibliotheken zu verwenden, wird der Befehl Declare verwendet. Mit diesem Befehl werden die Dateien (bzw. die darin befindlichen Funktionen) dem System bekannt gemacht. Weitere Informationen entnehmen Sie bitte der Befehlsreferenz unter dem Stichwort Declare.
12.7.3 ActiveX-Elemente Unter LotusScript ist es selbstverständlich auch möglich, die Microsoft ActiveXElemente zu verwenden. Weitere Informationen erhalten Sie in Kapitel 13 »Die Verwendung von OLE« (ActiveX-Elemente sind OLE-Objekte).
12.7.4 LSX-Klassen Ebenso besteht die besondere Möglichkeit, über LSX-Klassen die Funktionalität der Notes-Anwendungen zu verbessern bzw. zu erweitern. LSX-Klassen sind dynami-
146
Aufruf externer Programme
sche Bibliotheken in einem speziellen Notes-Format. Durch dieses Format sind sie in der Lage, in LotusScript zusätzliche Klassen verfügbar zu machen. Dies geschieht durch Verwendung der Anweisung UseLSX. Weitere Informationen finden Sie in Kapitel 18.7 »Weitere Klassen, LSX«.
12.8 Fragen 1. Welche allgemeinen Probleme können entstehen, wenn externe Anwendungen eingebunden werden? 2. Welche Formen von externen Anwendungen können in LotusScript-Programme eingebunden werden? 3. Wie werden Funktionen aus dynamischen Bibliotheken eingebunden? 4. Wie kann man unter LotusScript weitere Klassen anbieten?
13 13
Die Verwendung von OLE
13.1 Verständnisvoraussetzungen Vor dem Studium dieses Kapitels sollten schon umfangreiche Noteskenntnisse vorhanden sein, wie beispielsweise Kenntnisse im Umgang mit Objekten.
13.2 Lernziel Das Kapitel zeigt die Möglichkeiten der Verwendung des OLE-Mechanismus in LotusScript-Programmen auf.
13.3 Was ist OLE? OLE ist die Abkürzung für Object Linking or Embedding. OLE steht für eine Schnittstelle zwischen zwei Windows-Anwendungen, die es ermöglicht, die Funktionalitäten der verschiedenen Anwendungen zu kombinieren. Über OLE kann auf Funktionalitäten (Klassen) anderer Programme zugegriffen werden.
13.4 Der Unterschied von Embedded- und Linking-Objects Unter OLE werden die Mechanismen Object-Linking, welches für »Objekt-Verknüpfung« steht, und Object-Embedding, welches für »Objekt-Einbettung« steht, zusammengefasst. Der Unterschied zwischen dem Verknüpfen und dem Einbetten von Objekten besteht in dem Ort, an welchem die zum Objekt gehörenden Daten gespeichert werden. Bei einem eingebundenen Objekt werden die Daten innerhalb der Datei der aufrufenden Anwendung gespeichert. Bei verknüpften Objekten wird nur ein Verweis auf die Daten eingefügt.
13.5 Erstellung eines Datei-Anhangs Ein Datei-Anhang in einem Dokument ist eine besondere Variante für das Einbetten von Objekten. Ein Datei-Anhang kann ausschließlich in ein Feld des Typs
148
Die Verwendung von OLE
RichText eingefügt werden. Das Einfügen erfolgt mit der Methode EmbedObject der Notes/Dominoklasse NotesRichTextItem. Syntax der Methode EmbedObject für einen Datei-Anhang: Set notesEmbeddedObject = notesRichTextItem.EmbedObject ( EMBED_ATTACHMENT, "", source$, [ name$ ] ) Der Methode wird die Quelle in Form des Dateipfades zur Quelldatei übergeben, außerdem der Name des zukünftigen Objektes. Dim Dim Dim Dim Dim
session As New NotesSession db As NotesDatabase note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set Set Set Set
db = session.CurrentDatabase note = Db.CreateDocument item = New NotesRichTextItem(note, "attach") obj = item.EmbedObject _ (EMBED_ATTACHMENT, "", "C:\Autoexec.bat", "Autoexec") Call note.Save(True, False)
Dieses Beispiel erzeugt in der aktuellen Datenbank ein neues Dokument und hängt an dieses die Autoexec.bat-Datei als Anhang an.
13.6 Erstellen eines eingebetteten bzw. verknüpften Objektes Auf ähnlichem Wege wird ein veknüpftes bzw. eingebettetes Objekt erstellt. Die Erstellung des Objektes erfolgt ebenfalls mit der Methode EmbedObjekt der Klasse NotesRichTexItem. Als erster Parameter wird angegeben, ob das Objekt vom Typ "Eingebettet" oder "Verknüpft" sein soll. Als zweiter Parameter wird ggf. die Klassenbezeichnung des OLE-Objektes übergeben. Wird der Parameter class$ genutzt, so sollte source$ leer sein. Der Parameter class$ hat beispielsweise die Form Anwendung$.Dokumentenart$. Diesem folgt der Parameter source$. Er enthält den Pfad zu der Datei, aus der das Objekt generiert werden soll. Zuletzt folgt dann noch der optionale neue Name für das Objekt. Syntax der Methode EmbedObject für eingebettete bzw. verknüpfte Objekte:
Set notesEmbeddedObject = notesRichTextItem.EmbedObject ( EMBED_OBJECT | EMBED_OBJECTLINK, class$, source$, [ name$ ] ) Dim session As New NotesSession Dim db As NotesDatabase Dim note As NotesDocument
Zugriff auf einen Datei-Anhang
149
Dim item As NotesRichtTextItem Dim obj As NotesEmbeddedObject Set Set Set Set
db = session.CurrentDatabase note = db.CreateDocument item = New NotesRichTextItem(note, "Anhang") obj = Item.EmbedObject_ (EMBED_OBJECTLINK, "", "C:\Autoexec.bat", "Autoexec") Call note.Save(True, False)
Dieses Beispiel legt ein neues verknüpftes Objekt auf Grundlage der Datei C:\Autoexec.bat an. Dim Dim Dim Dim Dim
session As New NotesSession db As NotesDatabase note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set Set Set Set
db = session.CurrentDatabase note = db.CreateDocument item = New NotesRichTextItem(note, "Anhang") obj = item.EmbedObject _ (EMBED_OBJECT, "Word.Document", "", "Worddokument") Call note.Save(True, False)
Dieses Beispiel legt ein neues eingebettetes Objekt mit einem neuen Word-Dokument an.
13.7 Zugriff auf einen Datei-Anhang Um auf einen Datei-Anhang zuzugreifen, kann unter anderem die Methode GetAttachment der Klasse NotesDocument verwendet werden. Der Methode wird der Dateiname des gesuchten Objektes übergeben. Die Methode liefert (wenn vorhanden) eine Referenz auf das gesuchte Objekt zurück. Syntax der Methode GetAttachment der NotesDocument-Klasse:
Set notesEmbeddedObject = notesDocument.GetAttachment ( file$ ) Dim ws As New NotesUIWorkspace Dim note As NotesDocument Dim obj As NotesEmbeddedObject Set note = ws.CurrentDocument.Document Set obj = note.GetAttachment(" Autoexec ")
Dieses Beispiel liefert eine Referenz auf das im obigen Beispiel angelegte Objekt.
150
Die Verwendung von OLE
13.8 Zugriff auf ein eingefügtes oder ein eingebettetes Objekt Eine andere Möglichkeit des Zugriffs auf ein Objekt ist die Methode GetEmbeddedObject der Klasse NotesRichTextItem. Auch dieser Methode wird der Dateiname des gesuchten Objektes übergeben. Syntax der Methode GetEmbeddedObject der Klasse NotesRichTextItem: Set notesEmbeddedObject = notesRichTextItem.GetEmbeddedObject ( file$) Dim Dim Dim Dim
ws As New NotesUIWorkspace note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set note = ws.CurrentDocument.Document Set item = note.GetFirstItem("Anhang") Set obj = item.GetEmbeddedObject("Microsoft Word-Dokument ")
Dieses Beispiel würde auch eine Referenz auf das im obigen Beispiel angelegte Objekt zurückliefern.
13.9 Zugriff auf alle Objekte eines Items oder des ganzen Dokuments Eine Möglichkeit, um auf alle Objekte eines RichText-Items oder des gesamten Dokuments zuzugreifen, ist die Verwendung der Eigenschaft EmbeddedObjects der Klassen NotesRichtTextItem und NotesDocument. In dieser Eigenschaft sind alle Objekte des Items oder des Dokuments enthalten. Es bietet sich an, diese Eigenschaft mit dem Schleifenkonstrukt ForAll zu verwenden. Dim ws As New NotesUIWorkspace Dim note As NotesDocument Dim item As NotesEmbeddedObject Set note = ws.CurrentDocument.Document Set item = note.GetFirstItem("Anhang") ForAll x in item.EmbeddedObjects Print x.Type End ForAll
Dieses Beispiel zeigt den Typ aller OLE-Objekte des NotesRichText-Items "Anhang" über die Print-Anweisung.
Bearbeiten eines eingebetteten oder verknüpften Objektes
151
13.9.1 Die Eigenschaften eines eingebetteten Objektes Ein eingebettetes Objekt besitzt verschiedene Eigenschaften, welche durch LotusScript ausgelesen werden können. Als Erstes wäre da die Eigenschaft FileSize, welche die Größe des Objektes in Byte angibt. Des Weiteren folgt ein Zeiger auf das RichTextItem-Objekt, welches das Objekt beinhaltet. Der Pfad der Quelldatei ist in der Eigenschaft Source aufgezeichnet. Zuletzt gibt es noch die Eigenschaft Type mit dem Typ des Objektes. FileSize Parent Source Type Dim Dim Dim Dim
Größe des Objektes Referenz auf das RichText-Item, welches das Objekt beinhaltet Dateipfad der Quelle der Datei Typ des Objektes
ws As New NotesUIWorkspace note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set note = ws.CurrentDocument.Document Set item = note.GetFirstItem("Anhang") Set obj = item.GetEmbeddedObject("Autoexec") Print obj.FileSize Print obj.Source
Dieses Beispiel gibt die Dateigröße und die Quelle der Datei zurück.
13.10 Bearbeiten eines eingebetteten oder verknüpften Objektes Um ein eingebettetes oder verknüpftes Objekt zu bearbeiten, wird die Methode Activate der NotesEmbeddedObject verwendet. Diese Methode aktiviert ein OLEObjekt, so dass es bearbeitet werden kann. Dabei kann mit einem booleschen Parameter bestimmt werden, ob die OLE-Anwendung sichtbar sein soll oder ob das Objekt zwar aktiviert, aber für den Anwender unsichtbar sein soll. Syntax der Methode Activate der Klasse NotesEmbeddedObject: Set handle% = notesEmbeddedObject.Activate ( flag% ) Die Methode liefert einen Handle auf das OLE-Objekt zurück. Diese Methode darf allerdings nicht auf Dateianhängen ausgeführt werden. Sollte dieses trotzdem der Fall sein, wird ein Fehler ausgegeben. Sollte diese Methode auf einem Domino-Server verwendet werden, so sollte das Sichtbarkeitsflag flag% mit FALSE angegeben werden, da sonst ebenfalls ein Fehler ausgegeben wird.
152
Dim Dim Dim Dim
Die Verwendung von OLE
ws As New NotesUIWorkspace note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set note = ws.CurrentDocument.Document Set item = note.GetFirstItem("Anhang") Set obj = item.GetEmbeddedObject("Microsoft Word-Dokument ") Call obj.Activate(True)
Dieses Beispiel aktiviert das eingebettete Objekt mit Namen »Dokument.Doc« im Vordergrund auf dem Bildschirm.
13.11 Entfernen eines eingebetteten oder verknüpften Objekts bzw. eines DateiAnhangs Ein OLE-Objekt oder Datei-Anhang kann mit der Methode Remove der Klasse NotesEmbeddedObjekt entfernt werden. Dim Dim Dim Dim
ws As New NotesUIWorkspace note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set note = ws.CurrentDocument.Document Set item = note.GetFirstItem("Anhang") Set obj = item.GetEmbeddedObject("Microsoft Word-Dokument") Call obj.Remove() Call notes.save(True, False)
Dieses Beispiel entfernt das OLE-Objekt mit dem Namen »Dokument.Doc« aus dem Dokument.
13.12 Extrahieren eines Datei-Anhangs Um einen Datei-Anhang zu extrahieren, kann die Methode ExtractFile der Klasse NotesEmbeddedObject verwendet werden. Der Methode wird die Zieldatei als Parameter übergeben. Sollte versucht werden, diese Funktion auf ein eingebettetes oder verknüpftes Objekt anzuwenden, wird ein Fehler ausgegeben. Syntax von ExtractFile der Notesklasse NotesEmbeddedObject:
Call notesEmbeddedObject.ExtractFile ( path$ )
Weitere Möglichkeiten
Dim Dim Dim Dim
153
ws As New NotesUIWorkspace note As NotesDocument item As NotesRichTextItem obj As NotesEmbeddedObject
Set note = ws.CurrentDocument.Document Set item = note.GetFirstItem("Anhang") Set obj = item.GetEmbeddedObject("Document.doc") Call obj.ExtractFile("C:\Dokument.Doc")
Dieses Beispiel extrahiert das Objekt mit Namen »Dokument.Doc« aus dem Dokument in die Datei »C:\Dokument.Doc«.
13.13 Weitere Möglichkeiten Über OLE-Objekte ist der LotusScript-Entwickler in der Lage, auf andere OLE-fähige Programme zuzugreifen und sie zu steuern. Dazu müssen diese Anwendungen in der Lage sein, als OLE-Server zu dienen. Wenn Sie die Klassen bzw. OLE-Objekte der Serveranwendungen kennen (in deren Dokumentation zu erfahren), dann können Sie diese innerhalb von LotusScript ansprechen und bearbeiten. Nähere Einzelheiten und Beispiele finden Sie in der Designer-Hilfe. Umgekehrt ist Notes/Domino ebenfalls in der Lage als OLE-Server für andere Anwendungen zu dienen. So können Sie Dominoanwendungen beispielsweise von Lotus 1-2-3 aus über OLE ansprechen und steuern. Einzelheiten finden Sie ebenfalls in den einschlägigen Dokumentationen.
13.14 Wichtige Bemerkungen OLE ist ein Standard, der nicht auf jedem Betriebssystem verfügbar ist. Es gibt zwei OLE-Standards, die mit OLE1 und OLE2 bezeichnet werden. Es wird in den NotesHilfedatenbanken zwar davon gesprochen, dass die hier vorgestellten Methoden wie EmbedObject auf OS/2, UNIX-Systemen und MacIntosh nicht verfügbar sind. Dennoch können auf diesen Betriebssystemen über die vorgestellten Methoden Dateianhänge als OLE1-Objekte erstellt und verarbeitet werden.
154
Die Verwendung von OLE
13.15 Fragen 1. Was ist ein OLE-Objekt? 2. Welche unterschiedlichen Typen von OLE-Objekten gibt es? 3. Was ist ein Datei-Anhang? 4. Wie kann man ein OLE-Objekt erzeugen? 5. Welche Parameter gibt es bei der Erzeugung von OLE-Objekten? 6. Wie können Sie einen Datei-Anhang erstellen? 7. Wie können Sie ihn ablösen? 8. Können in einem Dokument mehrere OLE-Objekte gehalten werden? Wie können Sie auf sie zugreifen? 9. Was ist bei verschiedenen Betriebssystem-Plattformen zu beachten?
14 14
Der Umgang mit Dateien
14.1 Verständnisvoraussetzungen Es werden Grundkenntnisse in der LotusScript-Programmierung vorausgesetzt. Das schließt die Deklaration von Variablen sowie die Grundlagen des Programmablaufs ein.
14.2 Lernziel Das Kapitel will die Grundzüge des Umgangs mit Dateien erklären. Es werden die verschiedenen Arten besprochen, mit denen in Dateien geschrieben bzw. aus ihnen gelesen werden kann (z. B. sequentiell, binär usw.). Des Weiteren werden Sie mit den Möglichkeiten des File-Lockings vertraut gemacht, also der Möglichkeit, den gleichzeitigen Zugriff verschiedener Benutzer zu regeln.
14.3 Einleitung Eine sehr häufige Aufgabenstellung in Lotus Notes ist die Verarbeitung von Dateien, welche von externen Applikationen erzeugt wurden. Der Dateizugriff in Lotus Notes folgt dabei wie auch in vielen anderen Programmiersprachen einem festen allgemeinen Ablaufschema. Zuerst muss die Datei geöffnet werden, dabei legt man den Typ der Datei, den Zugriffsmodus und die Zugriffsart fest. Danach kann auf die geöffnete Datei mit Schreib- oder Leseoperationen zugegriffen werden. Nach dem Zugriff muss diese Datei wieder geschlossen werden. Bei dem Schließen der Datei werden alle Daten auf das Medium zurückgeschrieben, welche sich zur Pufferung noch im Speicher befinden. Sollte eine Datei nach den Zugriffen nicht geschlossen werden, gehen die gepufferten Daten im Arbeitsspeicher verloren. Eine im Zuge des Programmablaufs nicht geschlossene Datei kann somit zum Datenverlust führen. Darüber hinaus kann die Art bestimmt werden, wie eine geöffnete Datei vor dem gleichzeitigen Zugriff mehrer Benutzer geschützt wird. Mehr erfahren Sie zu diesem speziellen Thema in Abschnitt 14.7 »Locking-Mechanismen« Reihenfolge der Dateizugriffe:
X X X
Öffnen Schreiben oder Lesen Schließen
156
Der Umgang mit Dateien
14.3.1 Der Dateityp In LotusScript werden die drei Dateitypen »Sequentiell«, »Binär« und »Random« unterschieden. Je nach Dateityp wird auf diese Dateien in unterschiedlicher Art und Weise zugegriffen.
14.4 Die sequentielle Datei 14.4.1 Was ist eine sequentielle Datei? Die sequentielle Datei stellt die einfachste Form einer Datei dar. In einer sequentiellen Datei können beliebige Daten hintereinander abgespeichert werden. Das bedeutet, die Datei unterliegt keiner festen Struktur.
14.4.2 Das Öffnen einer sequentiellen Datei Zum Öffnen einer sequentiellen Datei dient der Open-Befehl. Es wird zuerst der Dateiname angegeben, dann folgt der Zugriffsmodus. Es stehen die Möglichkeiten »Input«, »Output« und »Append« zur Verfügung. Anschließend muss die Zugriffsart mitgeteilt werden, hierfür wird zwischen »Read«, »Write« und »Read Write« gewählt. Die Zugriffsart bestimmt, ob auf die Datei nur lesend, nur schreibend oder lesend und schreibend zugegriffen werden darf. Zuletzt wird in der Open-Anweisung noch die Dateinummer angegeben, über welche die Datei durch die späteren Dateibefehle angesprochen wird. Syntax der Open-Anweisung bei sequentiellen Dateien: Open fileName$ [ For { Input | Output | Append } ] [ Access { Read | Read Write | Write } ] As [#]filenumber Dieses Beispiel öffnet eine sequentielle Datei zum Lesen: Open "Dateiname.dat" For Input Access Read As #1 Dieses Beispiel öffnet eine sequentielle Datei zum Schreiben: Open "Dateiname.dat" For Output Access Write As #1 Beispiel für das Öffnen einer sequentiellen Datei zum Schreiben und Lesen: Open "Dateiname.dat" For Append Access Read Write As #1
Für jede geöffnete Datei existiert ein Dateizeiger, welcher die Position in der Datei markiert, an welcher die nächste Dateioperation ausgeführt wird. Wenn eine Datei mit dem Dateityp Input zum Lesen geöffnet wird, steht dieser Dateizeiger am Dateianfang und es können die Daten der Datei eingelesen werden. Wurde hingegen die Datei mit dem Dateityp Output für Schreiboperationen geöffnet, so wird die Datei neu angelegt oder, wenn sie bereits besteht, überschrieben. Auch hier steht der Dateizeiger nach dem Öffnen am Dateianfang. Danach können die Daten in die Datei geschrieben werden. Um Daten an eine bestehende Datei anzuhängen,
Die sequentielle Datei
157
wird der Dateityp Append verwendet. Bei diesem Dateityp wird eine bestehende Datei geöffnet und der Dateizeiger an das Ende der Datei gesetzt, wo dann Daten angehängt werden können.
14.4.3 Schreiben in eine sequentielle Datei Um in eine Datei zu schreiben, muss diese entweder mit dem Dateityp Append oder mit Output geöffnet worden sein. Außerdem muss als Zugriffsart Write oder Read Write gewählt worden sein. Für das Schreiben in eine sequentielle Datei verwendet man in LotusScript die Print#-Anweisung. Diese Anweisung ähnelt stark der normalen Print-Anweisung, nur dass hier nicht auf die Statuszeile, sondern in eine Datei geschrieben wird. Dafür muss als Erstes die Dateinummer angegeben werden, die in der Open-Anweisung verwendet wurde. Danach folgen die Ausdrücke, welche in die Datei geschrieben werden sollen. Bei jeder Schreiboperation wird der Dateizeiger entsprechend weiter gesetzt. Syntax der Print-Anweisung: Print # filenumber%, [ valueList ] Print #1, "Hallo"
' Schreibt das Wort Hallo in die Datei
Print #1, 100
' Schreibt den Wert 100 in die Datei
14.4.4 Lesen aus einer sequentiellen Datei Das Lesen aus einer sequentiellen Datei ist möglich, wenn diese mit dem Dateityp Input oder Append geöffnet wurde. Außerdem muss die Zugriffsart Read oder Read Write gewählt worden sein. Mit der Anweisung Input# kann dann aus der sequentiellen Datei gelesen werden. Dazu wird der Anweisung die Dateinummer übergeben. Danach folgen die Variablen, in die die Daten aus der Datei eingelesen werden sollen. Syntax Input-Anweisung: Input[$] ( count% , [#]filenumber% ) Input #1, Kette$ Input #1, Wert%
'Liest eine Zeichenkette und speichert 'diese in der Variable Kette$ 'Liest einen numerischen Wert ein und 'speichert diesen in der Variable Wert
14.4.5 Positionieren des Dateizeigers bei einer sequentiellen Datei Um die Position des Dateizeigers bei einer sequentiellen Datei zu verändern, wird die Seek-Anweisung verwendet. Der Anweisung wird die Dateinummer und die gewünschte Position in Form eines numerischen Wertes, welcher die Anzahl der Bytes vom Dateianfang bis zur gewünschten Position angibt, übergeben.
158
Der Umgang mit Dateien
Syntax der Seek-Anweisung: Seek [#]fileNumber%, recordPosition Open "Dateiname.dat" For Input As #1 Seek #1, 100 Input #1, A$ Close #1
'Öffnet die Datei 'Setzt den Dateizeiger auf die 'Position 100 'Liest einen alphanumerischen 'Wert aus der Datei 'Schließt die Datei
14.4.6 Ermitteln der aktuellen Position des Dateizeigers in einer sequentiellen Datei Die aktuelle Position des Dateizeigers wird mit der Funktion Seek() ermittelt. Die Funktion liefert die Position in Form eines numerischen Wertes zurück. Er beinhaltet die Anzahl der Bytes vom Dateianfang bis zur aktuellen Position. Syntax der Seek-Funktion: Seek( fileNumber% ) Open "Dateiname.dat" For Input As #1 TempPos = Seek(1) Seek #1, 100 Input #1, A$ Seek #1, TempPos Input #1, A$ Close #1
'Öffnet die Datei 'Speichert die aktuelle Position 'Setzt den Dateizeiger auf die 'Position 100 'Liest einen alphanumerischen 'Wert aus der Datei 'Setzt Dateizeiger wieder auf 'alten Wert 'Liest einen alphanumerischen 'Wert aus der Datei 'Schließt die Datei
14.4.7 Ermitteln des Dateiendes Um das Dateiende zu erkennen, wird in LotusScript die Funktion Eof eingesetzt. Diese Funktion liefert den Wert TRUE zurück, wenn das Dateiende erreicht wurde. Syntax der Funktion Eof: Eof( fileNumber% ) Open "Dateiname.dat" For Input As #1 While Not Eof(1) Input #1, Kette$ Msgbox Kette$ Wend Close #1
Die Random-Datei
159
14.4.8 Das Schließen einer sequentiellen Datei Eine sequentielle Datei wird durch die Close-Anweisung wieder geschlossen. Das Schließen der Datei ist notwendig, um gepufferte Dateien nicht zu verlieren. Syntax der Close-Anweisung: Close [[#]fileNumber% [ , [#]fileNumber% ] ... ] Close #1
14.4.9 Die Dateinummer In LotusScript wird jede Datei durch eine eindeutige Dateinummer referenziert. Bisher wurde hier einfach eine Zahl bei der Open-Anweisung verwendet. Da aber so die Gefahr besteht, an zwei verschiedenen Stellen die gleiche Dateinummer für unterschiedliche Dateien zu verwenden, sollte die Funktion FreeFile verwendet werden. Diese Funktion liefert die nächste freie Dateinummer zurück. Syntax FreeFile: FreeFile Dateinummer = FreeFile Open "Dateiname.dat" For Input As Dateinummer .... Close Dateinummer
14.5 Die Random-Datei 14.5.1 Was ist eine Random-Datei? In einer Random-Datei werden gleichstrukturierte Datensätze gespeichert. Dazu wird zuerst für die jeweiligen Daten eine Struktur angelegt. Danach wird die Datei mit der Angabe der Länge der Datenstruktur geöffnet.
14.5.2 Die Deklaration der Datenstruktur mit der Type-Anweisung Die Deklaration der Datenstruktur für die Datei erfolgt mit der Type-Anweisung vor dem Öffnen der Datei. Syntax der Type-Anweisung:
[ Public | Private ] Type typeName elements End Type
160
Der Umgang mit Dateien
Type Datensatz Vorname As String*30 Nachname As String*30 End Type
14.5.3 Das Öffnen einer Random-Datei Eine Random-Datei wird nach der Deklaration der Datenstruktur mit der OpenAnweisung geöffnet. Dafür wird wie bei der sequentiellen Datei die Zugriffsart festgelegt. Danach erfolgt wie bei der sequentiellen Datei die Angabe der Dateinummer. Zuletzt muss bei einer Random-Datei noch die Datensatzlänge, also die Länge der Datenstruktur, angegeben werden. Syntax der Open-Anweisung für Random-Dateien: Open fileName$ For Random [ Access { Read | Read Write | Write } ] As [#]fileNumber% Len = recordLength Type Datensatz Vorname As String*30 Nachname As String*30 End Type Dim Satz As Datensatz Open "Dateiname.dat" For Random _ Access Read Write As #1 Len = Len(Satz)
14.5.4 Das Schreiben in eine Random-Datei Das Schreiben in eine Random-Datei erfolgt mit der Anweisung Put. Dabei müssen die Dateinummer und die Datensatznummer sowie die Quellvariable übergeben werden. Die Dateinummer referenziert die behandelte Datei. Mit der übergebenen Datensatznummer wird der Datensatz ausgewählt, der geschrieben werden soll. An die Stelle des angegebenen Datensatzes wird der Inhalt aus der übergebenen Quellvariable geschrieben. Syntax der Put-Anweisung: Put [#]fileNumber% , [ recordNumber] , variable Type Datensatz Vorname As String*30 Nachname As String*30 End Type Dim Satz As Datensatz Open "Dateiname.dat" For Random _ Access Read Write As #1 Len = Len(Satz) Satz.Vorname = "Hans"
Die Random-Datei
161
Satz.Nachname = "Meier" Put #1, 1, Satz Close #1
14.5.5 Das Lesen aus einer Random-Datei Um Daten aus einer Random-Datei zu lesen, wird die Get-Anweisung verwendet. Der Anweisung wird die Dateinummer übergeben, welche die Datei referenziert, aus der gelesen werden soll. Des Weiteren wird die Datensatznummer des gewünschten Datensatzes übergeben. Zuletzt folgt die Zielvariable, in die die gelesenen Daten hineingeschrieben werden sollen. Syntax der Get-Anweisung: Get [#]fileNumber% , [ recordNumber ] , variable Type Datensatz Vorname As String*30 Nachname As String*30 End Type Dim Satz As Datensatz Open "Dateiname.dat" For Random _ Access Read Write As #1 Len = Len(Satz) Get #1, 1, Satz MessageBox "Vorname = " & Satz.Vorname MessageBox "Nachname = " & Satz.Nachname Close #1
14.5.6 Das Schließen einer Random-Datei Das Schließen einer Random-Datei erfolgt genauso wie bei einer sequentiellen Datei.
14.5.7 Das Positionieren des Dateizeigers in einer Random-Datei Auch in einer Random-Datei wird zum Positionieren des Dateizeigers die Anweisung Seek verwendet, nur wird hier der übergebene Wert nicht als Zeichenanzahl zum Dateianfang gewertet, sondern als Datensatznummer. Dasselbe gilt für die Ermittlung der aktuellen Position in der Datei. Auch hierfür wird die Funktion Seek verwendet. Der Rückgabewert ist hier die Datensatznummer des nächsten Datensatzes.
162
Der Umgang mit Dateien
14.6 Die Binärdatei Der Dateityp Binär ähnelt sehr stark dem sequentiellen Dateityp. Auch in einer Binärdatei werden alle Daten hintereinander geschrieben. Der Unterschied zur sequentiellen Textdatei besteht darin, dass in einer Binärdatei die einzelnen Zeichen keine ASCII-Zeichen sein müssen. Jede Position in der Binärdatei beinhaltet einen Byte-Wert, welcher einen Wert von 0 bis 255 annehmen kann.
14.6.1 Das Öffnen einer Binärdatei Das Öffnen und Schließen der Datei verläuft genauso wie bei der sequentiellen Datei, nur dass der Zusatz in der Open-Anweisung Binary lauten muss. Syntax der Open-Anweisung für binäre Dateien: Open fileName$ For Binary [ Access { Read | Read Write | Write } ] As [#]fileNumber%
14.6.2 Das Schreiben in eine Binärdatei In Binärdateien wird mit der Anweisung Put geschrieben, wobei explizit angegeben wird, an welcher Stelle der Datei geschrieben werden soll.
14.6.3 Das Lesen aus einer Binärdatei Um Daten aus einer Binärdatei zu lesen, wird die Get-Anweisung verwendet. Der Anweisung wird die Dateinummer übergeben, welche die Datei referenziert, aus der gelesen werden soll. Des Weiteren wird die Byte-Position des gewünschten Datei-Bereiches übergeben. Zuletzt folgt die Zielvariable, in die die gelesenen Daten übertragen werden sollen. Syntax der Get-Anweisung: Get [#]fileNumber% , [ recordNumber ] , variable Dim Buffer% Dim Satz As Datensatz Open "Dateiname.dat" For Binary _ Access Read Write As #1 Get #1, 1, Buffer% MessageBox Buffer% Close #1
14.6.4 Das Schließen einer Binärdatei Das Schließen einer Binärdatei erfolgt wie bei einer sequentiellen Datei.
Locking-Mechanismen
163
14.6.5 Das Positionieren eines Dateizeigers in einer Binärdatei Auch in einer Binärdatei wird zum Positionieren des Dateizeigers die Anweisung Seek verwendet, nur wird hier der übergebene Wert nicht als Zeichenanzahl zum Dateianfang gewertet, sondern als Byte-Position. Dasselbe gilt für die Ermittlung der aktuellen Position in der Datei. Auch hierfür wird die Funktion Seek verwendet. Der Rückgabewert ist ebenfalls die Byte-Position des nächsten Datensatzes.
14.7 Locking-Mechanismen 14.7.1 Dateilocking In einem Multitaskingsystem ist es wichtig, sich über den gleichzeitigen Zugriff zweier Programme auf dieselbe Datei Gedanken zu machen. Wenn beispielsweise zwei Programme gleichzeitig versuchen, in eine Datei zu schreiben, kommt es meistens zu einem inkonsistenten Datenbestand. Dieses kann man dadurch verhindern, dass man sich das Verfahren des Lockings zunutze macht. In LotusScript sind die entsprechenden Befehle zum Setzen von Sperren implementiert. Mit Lockingmechanismen können gleichzeitige Zugriffe mehrerer Prozesse auf dieselbe Datei verhindert werden. Hierbei wird einerseits unterschieden, in welchem Umfang die Sperren gesetzt werden. Bei einer sequentiellen Datei wird eine Sperre immer auf die gesamte Datei gesetzt. Bei einer Binärdatei kann die Sperre für die ganze Datei oder aber auch nur für einen bestimmten Datenbereich gesetzt werden. Dabei wird der Datenbereich durch seine Anfangs- und Endposition bestimmt. Bei der Random-Datei gibt es die Möglichkeit, einzelne Datensätze zu sperren. Andererseits wird unterschieden, ob die Sperrung nur für Lese-, Schreib- oder für Lese- und Schreibzugriffe gilt. Es gibt in LotusScript zwei Möglichkeiten, den Zugriff eines anderen Tasks auf eine Datei zu unterbinden. Einerseits kann der Lockingmechanismus beim Öffnen der Datei aktiviert werden. Andererseits kann er bei einer geöffneten Datei mit dem Lock-Befehl aktiviert und mit dem Unlock-Befehl deaktiviert werden. Durch das Locking beim Öffnen der Datei wird die Sperrung für die gesamte Datei gesetzt. Bei dem Lock/Unlock Befehl (nach erfolgter Öffnung der Datei) kann der Bereich der Sperrung feiner gewählt werden.
164
Der Umgang mit Dateien
Standardmäßig befindet sich die Datei, wenn im Open-Befehl nicht anders angegeben, im Shared-Modus. Unter Windows 3.1 muss die Anwendung SHARE.EXE gestartet werden. Bei allen früheren Versionen ist der Mechanismus nicht verfügbar. Im Standardmodus Shared ist es beliebig vielen Prozessen gestattet, Daten in und aus der Datei zu lesen. Die nächste Stufe ist der Lock-Read-Modus. In diesem Modus kann kein anderer Prozess den Inhalt der Datei lesen. Die Alternative dazu ist der Modus Lock-Write, hier werden Schreibzugriffe von anderen Prozeduren verhindert. Bei dem Modus Read-Write-Lock werden beide Zugriffsarten gesperrt. Lockmodus
Schreiben (durch andere)
Lesen (durch andere)
Shared
Erlaubt
Erlaubt
Read
Erlaubt
Verboten
Write
Verboten
Erlaubt
Read Write
Verboten
Verboten
Wie oben bereits erwähnt, gibt es zwei Stellen, an denen man das Dateilocking aktivieren kann. Bei der einen Möglichkeit erlaubt der Open-Befehl einen entsprechenden Zusatz. Syntax des Lockings beim Open-Befehl: Open fileName$ [ For { Random | Input | Output | Append | Binary } ] [ Access { Read | Read Write | Write } ] [{ Shared | Lock Read | Lock Read Write | Lock Write } ] As [#]fileNumber% [ Len = recordLength ] Versucht ein anderer Prozess auf eine Datei zuzugreifen, welche bei einem OpenBefehl gelockt wurde, verursacht dieses einen Fehler. Eine weitere und viel feiner einzustellende Möglichkeit ist die Verwendung der Lock-Anweisung. Syntax der Lock- und der Unlock-Anweisung: Lock [#]fileNumber% [ , recordNumber | { [ start ] To end } ] Unlock [#]fileNumber% [ , recordNumber | { [ start ] To end } ] Mit dem Lock- bzw. dem Unlock-Befehl kann eine geöffnete Datei oder ein Teil von ihr für fremde Prozesse gesperrt bzw. entsperrt werden. Dies ist derselbe Mechanismus, der zur Sperrung in dem Open-Befehl verwendet wird.
Die Loc-Funktion
165
Mit dem Lock-Befehl kann der zu sperrende Bereich genauer eingegrenzt werden. Bei binären Dateien wird die Start- und die Endposition des zu sperrenden Bereiches angegeben. Bei einer Random-Datei wird die Datensatznummer erwartet. Bei sequentiellen Dateien ist keine Einschränkung des Lockings möglich. Sollte beim Lock-Befehl keine nähere Spezifikation angegeben werden, so wird immer die gesamte Datei gesperrt. Die Sperrung durch den Lock-Befehl ist immer eine ReadWrite-Sperrung. Dateityp
Sperrbereich
Binär
Von Start- bis Endposition (gemäß Byte-Angabe)
Random
Von Start- bis Endposition (gemäß Datensatznummern)
Sequentiell
Nur die gesamte Datei
Der Unlock-Befehl hebt eine Sperrung durch den Lock-Befehl wieder auf. Dabei müssen die Parameter in der Unlock-Anweisung genau den Parametern in der Lock-Anweisung entsprechen. Bei einer Sperrung von einem Dateibereich heißt dies, dass der Bereich genau dem Bereich entsprechen muss, der beim Aktivieren der Sperrung angegeben war. Auch ein größerer Bereich, welcher den gesperrten Bereich beinhaltet, ist nicht zulässig, um die Sperrung eines enthaltenen Teilbereichs aufzuheben. Sonst erhalten Sie unvorhersehbare Ergebnisse.
14.8 Die Loc-Funktion Mit Hilfe der Loc-Funktion lässt sich die aktuelle Position des Dateizeigers abfragen. Bei einer Binärdatei enthält der Rückgabewert der Position des Dateizeigers minus 1. Dies entspricht der Anzahl der gelesenen oder geschriebenen Bytes. In einer Random-Datei beträgt der Rückgabewert ebenfalls die Position des Dateizeigers minus 1, was hier der Anzahl der gelesenen oder geschriebenen Datensätze entspricht. In einer sequentiellen Datei ist der Rückgabewert die Anzahl der gelesenen und geschriebenen Bytes dividiert durch 128 ohne die Nachkommastellen. Syntax Loc-Anweisung: Loc( fileNumber% ) Dim FileNr As Integer FileNr = FreeFile Open "DATEINAME.BIN" For Binary As FileNr Get FileNr, 1, Wert1% Get FileNr, 3, Wert2% MsgBox Loc(FileNr) Close FileNr
Dieses Beispiel gibt den Wert 4 aus, weil zweimal ein Integer-Wert gelesen wird (wobei davon ausgegangen wird, dass auf dem betrachteten System ein IntegerWert zwei Bytes umfasst). Der Zeiger selbst steht hinter dem vierten gelesenen Byte, also auf Position 5.
166
Der Umgang mit Dateien
14.9 Die Lof-Funktion Mit der Lof-Funktion kann man die aktuelle Dateilänge in Bytes einer geöffneten Datei ermitteln. Syntax der Lof-Anweisung: Lof( filenumber% ) Dim FileNr As Integer FileNr = FreeFile Open "DATEINAME.TXT" For Input As FileNr Msgbox Lof(FileNr) Close FileNr
Dieses Beispiel liefert die Dateilänge der angegebenen Datei in Bytes zurück.
14.10 FileAttr-Funktion Mit dieser Anweisung kann der aktuelle Zugriffsmodus einer geöffneten Datei ermittelt werden. Der Rückgabewert gibt an, ob die Datei als sequentielle, binäre oder Random-Datei geöffnet wurde. Syntax der FileAttr-Funktion: FileAttr( fileNumber%, attribute% ) Wert
Bedeutung
Konstante
1
Sequentiell + Input
ATTR_INPUT
2
Sequentiell + Output
ATTR_OUTPUT
4
Random
ATTR_RANDOM
8
Sequentiell + Append
ATTR_APPEND
32
Binary
ATTR_BINARY
Mit dem Parameter attribute% geben Sie an, welche Information FileAttr zurückgeben soll. Im Falle »2« (entspricht der Konstanten ATTR_HANDLE) erhalten Sie den Dateihandle des Betriebssystems. Im anderen Fall (»1«, bzw. ATTR_MODE) entspricht der Rückgabewert folgenden Situationen:
Funktion für nicht geöffnete Dateien
167
14.11 Funktion für nicht geöffnete Dateien 14.11.1 Die FileLen-Funktion Diese Funktion liefert die Dateilänge der angegebenen Datei in Bytes zurück. Dazu muss ihr der Dateiname mit Pfadangabe übergeben werden. Syntax FileLen: FileLen( fileName$ ) MsgBox FileLen("c:\Lotus\Notes\Data\notes.ini") 'Liefert die Länge der Datei 'c:\Lotus\Notes\Data\notes.ini 'zurück
14.11.2 Die FileCopy-Anweisung Mit dieser Anweisung werden zwei Dateien kopiert. Dazu müssen der Quellname und der Zielname angegeben werden. Syntax FileCopy: FileCopy source$, target$ FileCopy "c:\Lotus\Notes\Data\notes.ini", "a:\notes.ini" 'Kopiert die Datei c:\Lotus\Notes\Data\notes.ini auf Diskette
14.11.3 Die Dir-Anweisung Die Dir-Anweisung dient zum Ermitteln der Liste von Dateien in einem bestimmten Verzeichnis, welche einem gegebenen Suchmuster entsprechen. Dabei wird der Anweisung eine Dateispezifikation in Form der vom Betriebssystem bekannten Notation mit Hilfe von Platzhaltern übergeben. Außerdem besteht noch die Möglichkeit, eine Selektion aufgrund der Dateiattribute vorzunehmen. Die Suchmaske und die Dateiattribute werden mit dem ersten Aufruf der Anweisung Dir übergeben. Der Befehl liefert dann die erste entsprechende Datei zurück. Bei wiederholtem parameterlosem Aufruf werden die folgenden Dateinamen zurückgegeben, die der Suchmaske entsprechen. Wenn keine solche Dateien mehr vorhanden sind, so gibt der erneute Aufruf einen Leerstring zurück. Syntax Dir-Befehl: Dir[$] [ ( fileNameSpec$ [ , fileAttributeMask% ] ) ] Dateiname$ = Dir$("*.BAT") While (Dateiname$ <> "") MessageBox Dateiname$ Dateiname$ = Dir$() Wend
'Sucht die erste Batchdatei im ’aktuellen Verzeichnis
'Liefert nächste Batchdatei im 'aktuellen Verzeichnis
168
Der Umgang mit Dateien
14.11.4 ChDir Die Anweisung ChDir kann verwendet werden, um das aktuelle Verzeichnis auf einem Laufwerk zu wechseln. Dazu muss nur der neue Pfad angegeben werden. Syntax ChrDir: ChDir path$ ChDir "C:\"
'wechselt in das Root-Verzeichnis von C
14.11.5 CurDir Diese Funktion liefert das aktuelle Verzeichnis des jeweiligen Laufwerks zurück. Hierfür muss nur der Buchstabe des Laufwerks an die Anweisung übergeben werden. Syntax CurDir: CurDir[$] [ ( drive$ ) ] ChDir "C:\TEMP" MessageBox CurDir("C:")
'Wechsel auf C in das Laufwerk TEMP 'Liefert C:\TEMP als aktuelles Verzeichnis für 'das Laufwerk C zurück
14.11.6 CurDrive Diese Funktion liefert das aktuelle Laufwerk des Systems zurück. Syntax CurDrive: CurDrive[$] MessageBox CurDrive()
'liefert das aktuelle Laufwerk zurück
14.11.7 Die Anweisung Kill Die Anweisung Kill wird verwendet, um eine Datei zu löschen. Dazu wird ihr der Dateiname der zu löschenden Datei übergeben. Syntax Kill: Kill fileName$ Kill "C:\TEMP\TEMP.DAT"
'Löscht die Datei temp.dat in dem 'Verzeichnis C:\TEMP
14.11.8 Die Anweisung Name Durch diese Anweisung wird eine Datei oder ein Verzeichnis umbenannt. Dazu werden der alte und der neue Dateiname bzw. Verzeichnisname übergeben.
Fragen
169
Syntax Name: Name fileNameOld$ As fileNameNew$ Name "c:\alt.dat" As "c:\neu.dat"
'Benennt c:\alt.dat in c:\neu.dat um
14.11.9 Die Anweisung SetFileAttr Mit dieser Anweisung werden die Dateiattribute für eine Datei gesetzt. Dazu werden der Dateiname und die zu setzenden Attribute übergeben. Syntax SetFileAttr: SetFileAttr fileName$ , fileAttribute% SetFileAttr "C:\DATEN.DAT", 1
'Setzt die Datei 'DATEN.DAT auf 'Readonly
14.11.10 Die Anweisung GetFileAttr Diese Funktion dient zum Auslesen der Dateiinformationen, der Dateiname wird dazu an die Funktion übergeben. Syntax der GetFileAttr-Funktion: GetFileAttr( fileName$ ) MsgBox GetFileAttr("C:\Autoexec.bat")
'liefert die Dateiattribute 'der Autoexec.bat-Datei zurück
14.12 Fragen 1. Welche drei grundsätzlichen Dateitypen können Sie unter LotusScript ansprechen? 2. Welche Angaben müssen Sie beim Öffnen von Dateien machen? 3. Wie können Dateien gegen unberechtigten gleichzeitigen Zugriff geschützt werden? 4. Wie kann man die aktuelle Position in geöffneten Dateien verändern? 5. Wie würden Sie bei den unterschiedlichen Dateitypen vorgehen, um Daten einzulesen? 6. Welche Funktionen kennen Sie, um geschlossene Dateien zu bearbeiten? 7. Wie können Sie alle Dateien eines bestimmten Verzeichnisses erhalten?
15 15
Benutzerinteraktion
Unter LotusScript gibt es eine Reihe von Möglichkeiten, mit dem Benutzer zu kommunizieren. Obwohl LotusScript zugegebenermaßen vielen mächtigeren Programmierwerkzeugen in dieser Hinsicht das Wasser nicht reichen kann, bietet es mit dem Mechanismus der DialogBox doch ein besonderes Tool, das recht flexibel ist.
15.1 Print Diese Art der Kommunikation ist die einfachste. Mit dem Befehl Print werden Informationen am unteren Fensterrand des Notes-Hauptfensters auf der Statuszeile ausgegeben. Wenn das Script auf einem Server läuft, wird die Nachricht auf der Statuszeile des Server-Clients angezeigt und zusätzlich in die NotesLog-Datenbank geschrieben. Print "15 Dokumente bearbeitet"
15.2 MessageBox Die MessageBox bietet die Möglichkeit, dem Benutzer die Informationen mittels Dialogfenster anzuzeigen. Darüber hinaus ist der Benutzer gezwungen, per Buttonclick zu antworten. Welche Buttons angeboten werden, wird durch die Programmierung vorgegeben. Dabei können Sie aus einer größeren Palette von Kombinationsmöglichkeiten hinsichtlich Icon und Button wählen. MessageBox "15 Dokumente bearbeitet"
'Zeigt eine Messagebox mit 'dem vorgegebenen Text an. Es 'gibt keinen Titel. Die Box 'kann nur mit einem OK 'bestätigt werden.
MessageBox "2 schadhafte Dokumente", 16, "Fehler" 'Diese Meldung zeigt den Text »2 schadhafte Dokumente« an und trägt 'den Titel »Fehler«. Darüber hinaus wird statt des Standard-Icons ein 'rotes Kreuz im Kreis angezeigt, was z. B. auf das Misslingen einer 'Aktion hindeutet.
172
Benutzerinteraktion
15.3 InputBox Die InputBox kann einen Titel tragen, mit einem Text zur Erläuterung der Eingabeaufforderung versehen sein und einen Vorgabetext anzeigen. A$ = InputBox("15 Dokumente bearbeitet") 'Zeigt eine Inputbox mit dem vorgegebenen Text an. Es gibt keinen Titel Dim nAnzahl As Integer nAnzahl = InputBox("Bitte geben Sie die Anzahl ein:", _ "Bearbeiten", "5")
Zeigt eine Inputbox mit dem Text »Bitte geben Sie die Anzahl ein:« an. Der Titel lautet: »Bearbeiten«. Die Box fordert mit einem weißen Feld zur Werteingabe auf. Darin erscheint der Vorgabewert »5«
15.4 DialogBox Wie schon erwähnt, stellt die Dialogbox das mächtigste Instrument zur Unterstützung der Benutzer-Interaktion unter Lotus Notes dar. Eine Dialogbox bringt ein ausgewähltes Dokument mittels einer vorzugebenden Maske zur Ansicht. Je nach Einstellung kann das Dokument bearbeitet werden oder nicht. Die Dialogbox wird mit einer Methode der Klasse NotesUIWorkspace aufgerufen. Dim ws As New NotesUIWorkspace Dim note As NotesDocument Dim success As integer Set note = ws.CurrentDocument.Document success = ws.DialogBox("SalaryEdit", True, True, False, True, _ False,False, "Ändern",note, False, False)
Der Benutzer »steht« auf einem Personendokument, dessen Daten er ändern möchte. Die Felder, die zu bearbeiten sind, sind vom Typ »Berechnet beim Anlegen«. Dadurch können sie nur über Dialogboxen oder Hintergrundfunktionalitäten bearbeitet werden. Durch Anklicken des Buttons »Gehaltsdaten ändern« öffnet sich eine Dialogbox. Ihr wird die Maske »SalaryEdit« mitgegeben, die im Gegensatz zu der Anzeigemaske Person editierbare Felder aufweist. Die korrelierenden Felder in der Maske SalaryEdit haben die gleichen Namen wie diejenigen im Dokument. Durch die Option noFieldUpdate = FALSE werden Eingabewerte der Dialogbox an das darunter liegende Dokument (note) beim Schließen der Box weitergegeben. QueryClose-Event Dialogboxen bieten fast alle Möglichkeiten, die auch von normalen Masken zur Verfügung gestellt werden. So können Sie bei Bedarf Berechnungen innerhalb der Dialogbox vornehmen, die bei Abschluss der Eingabe an das Dokument weitergegeben werden.
Picklist
173
Dazu können Sie z. B. das QueryClose-Event der Maske SalaryEdit verwenden. Wenn der Benutzer seine Eintragungen erledigt hat und die Box schließen will, tritt das Event auf. Sie können nun innerhalb des Eventhandlers Berechnungen vornehmen. Wenn z. B. zu einem festen Grundgehalt eines Verkäufers eine Prämie zu zahlen ist, die sich nach einer Staffel über die verkauften Einheiten berechnet, so ist dies eine Aufgabe, die mit Formelmakros kaum zu lösen ist. Deshalb können wir auch nicht die automatische Wertberechnung des Feldes »Provision« verwenden (hier ist ja nur Formelberechnung möglich), sondern müssen uns etwas anderes einfallen lassen. Der Einfall lautet: Wir nehmen LotusScript zu Hilfe und führen die Berechnung im QueryClose-Event aus. Nach der Berechnung wird der gefundene Wert für die Provision explizit in das zugehörige Feld geschrieben. Also etwa so: Sub Queryclose(Source As Notesuidocument, Continue As Variant) Dim note As NotesDocument Dim view As NotesView Dim session As New NotesSession Dim noteProvision As NotesDocument Dim nVerkaufteEinheiten As Integer Dim nStaffel As Integer Set note = Source.Document nVerkaufteEinheiten = note.VerkaufteEinheiten(0) Set db = session.CurrentDatabase Set view = db.GetView("Provisionsstaffel") Set noteProvision = view.GetFirstDocument Do While Not (noteProvision Is Nothing) nStaffel = Cint(noteProvision.Staffel(0)) Set noteProvision = view.GetNextDocument(noteProvision) If (noteProvision Is Nothing) Then Exit Do If nVerkaufteEinheiten < Cint(noteProvision.Staffel(0))_ Then Exit Do Loop Call note.ReplaceItemValue("Provision", nStaffel) Call note.Save(True, True) End Sub
15.5 Picklist Mit Picklisten können Sie dem Benutzer sehr bequem eine Auswahl von Dokumenten anbieten. Eine Picklist basiert immer auf einer bereits erstellten Ansicht, die in einer Dialogbox präsentiert wird.
174
Benutzerinteraktion
Der Benutzer kann je nach Parametrisierung ein oder auch mehrere Dokumente per Mausklick auswählen. Je nachdem welche Funktion Sie einsetzen, erhalten Sie als Resultat ein Array von Werten oder eine NotesDocumentCollection, also eine Sammlung von ausgewählten Dokumenten zurück. Wir demonstrieren den Einsatz von Picklisten anhand der Methode PickListCollection der Klasse NotesUIWorkspace: Sub Click(Source As Button) 'Erzeuge ein Objekt, das den Arbeitsbereich repräsentiert Dim ws As New NotesUIWorkspace 'Erzeuge ein Objekt zum Zugriff auf die Sitzung Dim session As New NotesSession Dim db As NotesDatabase Dim note As NotesDocument Dim vStringArray As Variant 'Ergreife die Datenbank, in der das Script läuft Set db = session.CurrentDatabase 'Die Methode PickListStrings des Arbeitsbereichs 'präsentiert eine Picklist auf Basis der versteckten 'Ansicht (Firmen). Für jedes vom Benutzer ausgewählte 'Dokument wird ein Wert im Array zurückgegeben. 'Der Wert wird der mit einer Zahl bezeichneten Spalte 'entnommen, in diesem Fall der ersten. vStringArray = ws.PickListStrings(PICKLIST_CUSTOM, False, _ db.Server, db.FilePath, "(Firmen)", "Firma", _ "Bitte wählen Sie aus", 1, "") 'Wenn der Benutzer kein Dokument gewählt hat, wird die Sub 'verlassen If Isempty(vStringArray) Then Exit Sub 'Bestimme das Backend-Dokument, auf dem gerade gearbeitet 'wird. Set note = ws.CurrentDocument.Document 'Trage die gefundene Firma ins Feld Firma ein Call note.ReplaceItemValue("Firma", vStringArray(0)) 'Es wird nicht gespeichert. Das überlassen wir dem Benutzer, 'für den Fall, dass er die Aktion abbrechen will. End Sub
Picklist
175
Dieses Script wird in den Button der Personen-Maske in der Adressdatenbank gelegt. Es sorgt dafür, dass der Benutzer ein Personen-Dokument einer Firma zuordnen kann. Erläuterungen zum Script: Der erste Parameterwert PICKLIST_CUSTOM besagt, dass in dieser Pickliste eine vom Programmierer erzeugte Ansicht präsentiert wird.
Der folgende Wert FALSE sorgt dafür, dass der Benutzer nur jeweils ein Dokument auswählen kann. Danach werden Server und Pfad der Datenbank übergeben, in der die gesuchten Dokumente liegen. Es folgt der Name der präsentierten Auswahlansicht. Wir haben hier mit (Firmen) eine versteckte Ansicht gewählt. Sie sehen, dass man solche Ansichten über entsprechende Funktionalitäten dem Benutzer zur Verfügung stellen kann. Sie sind nur dem direkten Zugriff vom UI aus entzogen. Der vorletzte Wert (1) nennt die Spalte, deren Wert in dem Rückgabearray übergeben werden soll. Das Array enhält je ausgewähltem Dokument ein Element. Da wir dafür gesorgt haben, dass der Benutzer immer nur ein Dokument auswählen kann, können wir sicher sein, dass sich dieser Wert im Element mit dem Index 0 befindet. Wenn Sie den Button anklicken, sehen Sie das folgende Resultat (Abbildung 15.1).
Abbildung 15.1: Versteckte Ansicht über den Picklist-Mechanismus zur Verfügung stellen
176
Benutzerinteraktion
15.6 Fragen 1. Welche Arten der Benutzerinteraktion bietet LotusScript? 2. Mit welchem Befehl würden Sie einfache Meldungen anzeigen? 3. Mit welchem Befehl kann man einfache Eingaben abfragen? 4. Wozu dient eine Pickliste? 5. Wie lauten die Rückgabewerte einer Pickliste? 6. Was ist eine Dialogbox? 7. Welche verschiedenen Optionen bietet eine Dialogbox?
16 16
Module und Sichtbarkeiten
16.1 Verständnisvoraussetzungen Der Leser dieses Kapitels sollte mit der Deklaration von Variablen, Funktionen und Prozeduren vertraut sein. Ansonsten gibt es keine besonderen Voraussetzungen.
16.2 Lernziel Der Leser wird mit dem für ein LotusScript-Programm grundlegenden Begriff des Moduls bekannt gemacht. Er erfährt, wie Module aufgebaut sind, wo sie verwendet werden und wie Module programmiert werden. Des Weiteren wird gezeigt, wie die Sichtbarkeit von Variablen, Funktionen, Prozeduren, Klassen- und Typdeklarationen innerhalb und außerhalb von Modulen gesteuert werden kann.
16.3 Der Begriff des Moduls Ein Umstand, der Einsteiger verwirren kann, besteht darin, dass eine LotusScriptAnwendung im Normalfall in einzelne bis in viele Module zerfällt. Diese können jeweils für sich autark sein. Oft sind sie aber auch aufeinander angewiesen. Dieser Umstand ist nicht nur im Script-Umfeld zu beachten. Auch und sogar noch stärker war er bei der Formelsprache gegeben. Wer eine ganze Anwendung in Makro schrieb oder vielleicht sogar noch schreibt, der kennt den Kampf mit zahlreichen Feldern, die über die ganze Maske verteilt und mit Funktionalitäten voll gepfropft sind, die in fast unübersehbarer Weise aufeinander zugreifen und sich gegenseitig beeinflussen. Kaum zu findende Ringschlüsse sind oftmals die Folge. Das ist in LotusScript schon wesentlich einfacher. Aber dennoch muss man sich mit der Aufteilung des Codes und den daraus resultierenden Sichtbarkeiten auskennen. Der Grundbegriff zur Aufteilung des Script-Codes ist das Modul. Ein Modul ist ein Gültigkeitsbereich, angereichert um je einen Initializeund einen Terminate-Eventhandler. In diesen Gültigkeitsbereichen können Sie Variablen deklarieren und definieren, Klassen deklarieren und Objekte erzeugen, Funktionen und Prozeduren deklarieren und ausführen.
178
Module und Sichtbarkeiten
Alle innerhalb eines Moduls angelegten Elemente sind innerhalb seines Gültigkeitsbereiches frei verfügbar. Ob sie von außen zugreifbar sind, ist eine ganz andere Frage, deren Antworten sehr unterschiedlich ausfallen können.
16.4 Zugang zu Modulen und deren Aufbau Doch vorher muss noch die Frage beantwortet werden, wo der Notes-Entwickler die Module in der Praxis findet. Der am einfachsten zu verstehende Fall ist die Script-Bibliothek. Hier handelt es sich ganz augenscheinlich um ein abgeschlossenes Codestück, mit den Subs Initialize und Terminate. Diese Abgeschlossenheit kommt schon darin zum Ausdruck, dass man eine Script-Bibliothek per Copy-and-Paste in einem Stück von einer Datenbank in die andere packen kann. Andere Module sind der Programmcode eines Buttons, einer Aktion, eines Agenten, einer Maske, einer Teilmaske, einer Datenbank usw. In all diesen Modulen werden Sie vier grundlegende Abschnitte wiederfinden, die wir in der Folge besprechen werden. Script-Bibliotheken stellen eine Form von LotusScript-Modulen dar. Andere Beispiele für Module sind das Script, das in einem Agent läuft, das Script einer Maske, einer Teilmaske, eines Buttons usw. Dazu werden wir gleich ein wenig mit Modulen und Sichtbarkeiten experimentieren. Also beginnen wir mit der Erzeugung eines Moduls, in diesem Fall einer Scriptbibliothek. Zu diesem Zweck wählen Sie aus den Gestaltungselementen die Kategorie Ressourcen und darunter den Punkt Script-Bibliotheken aus. Wenn Sie den rechts oben befindlichen Button »Neue Bibliothek« anklicken, wird eine neue Bibliothek angelegt, und Sie sehen gleich in der mittleren Spalte die vier Abschnitte (Optionen), (Deklarationen), Initialize und Terminate.
Abbildung 16.1: Neue Script-Bibliothek erstellen
Zugang zu Modulen und deren Aufbau
179
Jedes Modul enthält mindestens die vier Abschnitte »(Options)«, »(Declarations)«, »Initialize« und »Terminate«.
Abbildung 16.2: Die neue Bibliothek mit den vier Abschnitten in der mittleren Spalte
Er s t e r A b s chn hnii tt : (O p t i on s ) Dieser Abschnitt nimmt verschiedene Optionen auf und dient zum Laden weiteren Codes. Als Optionen kommen in Betracht: Option Public
besagt, dass jede im Modul vorgenommene Deklaration Public erfolgt
Option Declare
sorgt dafür, dass keine impliziten Deklarationen möglich sind
Option Base
verschiebt den Beginn der Array-Indexe
Option Compare
beeinflusst die Methode, die beim Vergleich zweier Strings verwendet wird
Besonders interessant ist die Möglichkeit, weiteren Code hinzuzuladen: Use "library"
Lädt eine Bibliothek mit dem Namen »library«
UseLSX "lsx.dll"
Lädt die Deklarationen und Definitionen einer LSX-Datei mit dem Namen »lsx.dll«
%Include "include.txt"
Lädt den Code aus der Textdatei »include.txt«
Alle drei Statements haben ihre unterschiedlichen Vorzüge. Durch das erste Statement wird eine Scriptbibliothek innerhalb des betrachteten Moduls mit allen Deklarationen und Definitionen verfügbar gemacht, die innerhalb der geladenen Bibliothek als Public deklariert sind. Auch eine Verschachtelung ist möglich. Der UseLSX-Befehl dient zum Laden von kompiliertem C++-Code, der im Allgemeinen spezielle Klassen anbietet. Nähere Informationen finden Sie in den Kapiteln 12.7.4 und 18.7.
180
Module und Sichtbarkeiten
Das %Include-Statement verlängert sozusagen den Umfang eines Moduls, indem ein Teil des Codes in eine Textdatei ausgelagert wird. Die Include-Datei wird durch den Präprozessor beim Compilieren eingebunden, so dass sie nur für den Entwickler zur Verfügung stehen muss, nicht aber für den späteren Anwender. Allerdings muss die Datei in der Praxis immer dann mitgeliefert werden, wenn dem Anwender die Veränderung des Scripts ermöglicht werden soll. Auch kann der Anwender die in der Include-Datei deklarierten Elemente für Eigenentwicklungen nur dann nutzen, wenn ihm die Datei zur Verfügung steht. Im Abschnitt »(Options)« werden verschiedene Optionen gesetzt und eventuell auf Code anderer Bibliotheken oder Dateien referenziert. Es gibt drei Anweisungen, über die »fremder« Code in einem Modul verfügbar gemacht werden kann, der in anderen Bibliotheken oder Dateien beheimatet ist: Use, UseLSX und %Include. Syntax der Anweisungen Use, UseLSX und %Include: Use file$ UseLSX file$ %Include file$ Z w e i te r A bs chn hnii tt tt:: ( De cl ar at i o n s ) Dieser Abschnitt nimmt die Deklaration von Variablen, Typen und Klassen auf, die innerhalb des Moduls global zur Verfügung stehen sollen. Ist die Option Public gesetzt, sind die hier deklarierten Elemente automatisch auch außerhalb des Moduls zugänglich. Dazu muss dieses Modul allerdings von einem anderen Modul, das Zugriff auf die Elemente begehrt, über ein Use-Statement im Abschnitt »(Options)« geladen werden. Ist die Option Public nicht gesetzt, so sind die hier deklarierten Elemente nur innerhalb des Moduls global zugänglich. Man kann in diesem Fall für die einzelnen Elemente durch eine explizite Public-Deklaration dafür sorgen, dass sie dennoch »von außen« gesehen werden können. Im Abschnitt »(Declarations)« werden Deklarationen abgelegt. Dr i t te r un d v i e rt e r A bs chn hnii tt tt:: In i t ia l iz e u n d T e r m i n at e Dies sind zwei grundlegende Prozeduren, die Sie in jedem Modul finden. Initialize wird als Eventhandler immer dann ausgeführt, wenn das entsprechende Modul (hier die Bibliothek) geladen wird und kann z. B. zur Initialisierung von (modul)globalen Variablen verwendet werden. Terminate ist der Eventhandler fürs Aufräumen, der zu der Zeit ausgeführt wird, da die Bibliothek entladen wird. Die Abschnitte »Initialize« und »Terminate« sind Eventhandler für die Zeit des Ladens und des Entladens des betreffenden Moduls.
Zugang zu Modulen und deren Aufbau
181
We i t e r e A b s chn hnii t te (F u n kt io n e n un d P r o ze du r e n ) Jedem Modul können weitere Abschnitte hinzugefügt werden, nämlich eine mehr oder weniger beliebige Anzahl von Funktionen (Function) und Prozeduren (Sub). Dies ist in der Praxis ganz einfach. Man fügt in einen freien Bereich eines bereits bestehenden Abschnitts einfach einen neuen Funktionskopf oder Prozedurkopf ein und drückt die Enter-Taste. Und schon ist ein neuer Abschnitt entstanden. Sie müssen nur Obacht geben, dass Sie dies nicht innerhalb von bereits vorhandenen Funktionen, Prozeduren oder Klassen tun. Das würde im Allgemeinen zu sehr unschönen Ergebnissen führen. Um ein Gefühl dafür zu bekommen, sollten Sie es einmal versuchen. Der Editor wird den Code insbesondere im Falle von Klassendeklarationen in Stücke zerlegen, die Sie gar nicht beabsichtigt hatten. Die entstehende Sortierarbeit werden Sie sich in Zukunft sicher ersparen wollen. Weitere benutzerdefinierte Abschnitte werden in einem Modul durch die Deklaration von weiteren Funktionen und Prozeduren eingerichtet. D e r B i bli lio o th e k e i n e n N a m e n g e b e n Klicken Sie einmal mit der rechten Maustaste in den größeren weißen Bereich im rechten Drittel des Programmierfensters. Es sollte sich eine Dialogbox öffnen, in der Sie in einem Textfeld den Eintrag »unbenannt« finden. Überschreiben Sie diesen mit einem Namen Ihrer Wahl. Wir entscheiden uns für den Namen »Konfiguration«. Sollte die Dialogbox nicht aufgehen, dann klicken Sie noch einmal oder öffnen Sie sie mittels des SmartIcons »Eigenschaften«. Be is p i e le fü r d as A r b e it e n mi t B i bli lio o th e k e n u n d a n de r e n M o d ul e n Wir werden zunächst ein paar Experimente durchführen. Daher bitten wir Sie, im Abschnitt (Options) den voreingestellten Eintrag Option Public zu löschen. Im täglichen Programmierablauf würden Sie ihn meistenteils stehen lassen, da er dafür sorgt, dass alle in diesem Modul deklarierten Elemente von außen sichtbar sind. Das ist zwar nicht immer gut, aber auch nur selten hinderlich. Jetzt definieren Sie in demselben Abschnitt die folgenden Konstanten: Const nERR_NO_PARAMETER_NAME = 19001 Const sERR_NO_PARAMETER_NAME = "Parameter ohne Bezeichnung"
Anschließend muss die Bibliothek gespeichert werden, damit sie für die folgenden Experimente zur Verfügung steht. Da die Konstanten nicht Public deklariert sind (weder implizit durch eine Option noch durch explizite Angabe), sollten sie nach außen nicht zu sehen sein. Das prüfen wir, indem wir eine neue Maske bauen, der wir den Titel »Test« und den Namen »Testmaske« und einen Button namens »Test« verpassen. In diesen Button legen Sie bitte das folgende Script:
182
Module und Sichtbarkeiten
Sub Click(Source As Button) Dim sKonstante As String sKonstante = sERR_NO_PARAMETER_NAME End Sub
Und ganz wichtig: in den Abschnitt (Options) gehört noch der Befehl zum Laden der eben gebauten Bibliothek: Use "Konfiguration"
Jetzt können Sie Ihre Testmaske ausprobieren. Wählen Sie im Menü Gestaltung | Vorschau in Notes. Nachdem Sie die Frage bezüglich des Abspeicherns bejaht haben, präsentiert sich der Testbutton, den Sie einmal anklicken. Die Reaktion? Nichts! Wenn Sie in den Debugger schauen, werden Sie sehen, dass sich auch wirklich nichts getan hat (Abbildung 16.3).
Abbildung 16.3: Ein Blick in den Debugger zeigt, dass sich nichts getan hat
Jetzt öffnen Sie die Bibliothek »Konfiguration« wieder und fügen im Abschnitt (Options) die folgende Zeile ein: Option Declare
oder Option Explicit
'(bewirkt dasselbe)
Wieder abspeichern und den Test durchführen. Jetzt ist das Ergebnis ein anderes (Abbildung 16.4).
Zugang zu Modulen und deren Aufbau
183
Abbildung 16.4: Diesmal wird ein Fehler ausgeworfen
In diesem Fall können Sie die Bibliothek nicht abspeichern. Sie erhalten die Fehlermeldung »Daten werden aufgrund von Fehlern in Script nicht gespeichert«. Zwar sind Fehlermeldungen lästig, aber in diesem Fall sollten Sie froh sein, dass sie kommt. Ohne die Option Declare (Explicit) würde uns nämlich nicht bewusst, dass die Konstante sERR_NO_PARAMETER_NAME im Modul des Testbuttons nicht sichtbar war. Sie wurde implizit deklariert und mit dem Defaultwert "" (Leerstring) versehen. Das war aber nicht das, was wir wollten. Durch die Option, die dazu zwingt, jede benutzte Konstante und jede Variable vorher zu deklarieren, konnte der Fehler auffallen. Wenn Sie im vorigen »Testlauf« die Wertzuweisung im Debugger verfolgt hätten, wäre Ihnen aufgefallen, dass ein Leerwert übergeben wurde, was wiederum auf die implizite Deklaration hingewiesen hätte. Jetzt setzen Sie vor die Deklaration der Konstanten ein »Public«, speichern die Bibliothek und wiederholen den Test. Jetzt funktioniert er! Sollten Sie wieder keinen Erfolg haben (im Debugger verfolgen!), so müssen Sie die Maske, die die Bibliothek lädt, noch einmal öffnen, im Abschnitt (Options) eine kleine Änderung vornehmen (irgendwohin ein Zeichen setzen und wieder löschen) und abspeichern. Spätestens jetzt wird der Test funktionieren. Und im Debugger sieht es so aus, wie Sie es in Abbildung 16.5 sehen.
184
Module und Sichtbarkeiten
Abbildung 16.5: Jetzt wird die globale Variable angezeigt
Der große Unterschied zum Bild davor: Im Variablenfenster erscheint jetzt vor dem Wort Globals ein grünes Dreieck und nach dem Aufklappen sieht man die importierte Konstante, die jetzt den in der Bibliothek zugewiesenen Wert hat. Dass sie im Abschnitt Globals auftaucht zeigt, dass sie jetzt auch für das Modul Button public global ist. Vorher stand die Konstante unter den anderen Modulvariablen und hatte keinen Wert. Wie schon erläutert, handelte es sich hier um eine neue, andere Konstante, die im Modul Button implizit deklariert worden war. Damals haben wir im Abschnitt Globals keine Konstante sehen können, ein Beleg dafür, dass die Konstante aus dem Modul »Konfiguration« nicht importiert worden war. Wenn der Debugger noch eine Zeile weiterläuft, wird der Wert der Konstanten der Variablen sKonstante zugewiesen:
Wichtige Bemerkungen
185
Abbildung 16.6: Jetzt wird der Variablen sKonstante ein Wert zugewiesen
Die gleichen Prinzipien gelten auch im Umgang mit Variablen, Klassen, Objekten, Funktionen und Prozeduren.
16.5 Wichtige Bemerkungen Theoretisch ist es kein Problem, Module in mehreren Ebenen zu verschachteln. In der Praxis gibt es aber Probleme mit Hintergrundagenten (= periodische Agenten), die sich der Verschachtelung von Modulaufrufen bedienen. Wenn Sie in einen solchen Agenten ein Modul laden, das selbst wieder andere aufruft, dann sollten Sie sämtliche Aufrufe der tieferen Schachtelungsebenen im Agenten wiederholen. Wenn Sie dies nicht tun, werden Sie zwar nicht unbedingt einen Kompilierfehler erhalten, aber es kann gut sein, dass der Agent einfach nicht läuft. Oder er bedankt sich mit dem schwer zu ortenden Fehler »Type mismatch on external name«. Eine andere Ursache für den gleichen Fehler ist das Nichtbeachten der Groß-/Kleinschreibung beim Aufruf von Bibliotheken. Zwar soll der Aufruf nicht Case-sensitiv sein, insbesondere nicht unter Windows, Hintergrundagenten denken aber auch hier anders!
186
Module und Sichtbarkeiten
Beispiel für die fehlerfreie Einbindung von verschachtelten Bibliotheken in einem Hintergrundagenten: Es gebe die drei Bibliotheken Lib1 Lib2, ruft Lib1 auf Lib 3, ruft Lib 2 auf Unser Beispielagent nutze Lib3. Dann sollte im Abschnitt Options Folgendes stehen: Use "Lib1" Use "Lib2" Use "Lib3"
Um einen fehlerfreien Lauf von Hintergrundagenten zu gewährleisten, sollte man beim Verwenden der Direktive Use unbedingt auf übereinstimmende Groß-/Kleinschreibung achten. Außerdem müssen alle Bibliotheken, die implizit über mehrere Schachtelungsstufen aufgerufen werden, im Abschnitt »(Options)« noch einmal explizit eingebunden werden.
16.6 Fragen 1. Wie ist ein LotusScript-Programm aufgebaut? 2. Was ist ein Modul? 3. Welche grundlegenden Abschnitte enthält jedes Modul? 4. Welche Funktion haben die Eventhandler Initialize und Terminate? 5. Wie können Sie in Modulen weitere Abschnitte einrichten? 6. Welche Möglichkeiten gibt es, Scriptcode abzuspeichern und zu verwalten? 7. Wie können Sie erreichen, dass Elemente eines Moduls für andere Module sichtbar sind? 8. Wie können Sie erreichen, dass Elemente eines Moduls für andere Module nicht sichtbar sind? 9. Welche Besonderheiten sind bei periodischen Agenten (= Hintergrundagenten) zu beachten?
17 17
Objektorientierte Programmierung unter LotusScript
Für die einen »neumodischer Kram« und suspekt, für die anderen fast ein Glaubensbekenntnis: die OOP
17.1 Verständnisvoraussetzungen Die wesentlichen Sprachelemente von LotusScript sollten bekannt sein, da die Beispiele darauf aufbauen. Insbesondere sollte die Deklaration und Definition von Variablen, Funktionen, Prozeduren und Klassen (Class End-Konstrukt) bekannt sein.
17.2 Lernziel Das Ziel dieses Kapitels ist es zu zeigen, was OOP im Prinzip ist und wie man unter LotusScript objektorientiert arbeiten kann. Dabei gehen wir nur so weit, wie wir die erarbeiteten Konzepte in LotusScript einfach und nutzbringend anwenden können.
17.3 Motivation Der Sympathiegrad für die Objektorientierte Programmierung (OOP) reicht von glatter Ablehnung bis hin zu fast überschwänglicher Verehrung. Lotus nennt LotusScript eine »vollständig objektorientierte Sprache«, während man aus anderer Richtung manchmal den Vorwurf hört, es sei keine objektorientierte Sprache. Des Weiteren werden die Grenzen der OOP unter LotusScript beleuchtet. Wir verraten den einen oder anderen Trick, mit dem man vordergründig Unmögliches doch noch in die Tat umsetzen kann. Neulingen der OOP wollen wir es so leicht wie möglich machen. Wenn das Konzept manchem Leser im ersten Moment dennoch etwas schwer verständlich erscheinen sollte, so wollen wir dazu ermuntern, sich trotzdem mit dieser genialen Design- und Programmierweise auseinander zu setzen. Wenn man die grundlegende Idee erst einmal verstanden hat, wird ein anfängliches Unbehagen sehr schnell anhaltender Begeisterung weichen.
188
Objektorientierte Programmierung unter LotusScript
Kennern der OOP, die mit dem theoretischen Hintergrund vertraut sind, mögen die Erläuterungen recht einfach, manchmal vielleicht sogar zu sehr vereinfachend vorkommen. Solchen fortgeschrittenen Lesern empfehlen wir, den Stoff mehr oder weniger zu überfliegen. Auslassen sollten Sie ihn aber auf keinen Fall! Konzentrieren Sie sich bitte auf die hier dargelegten speziellen Möglichkeiten der OOP unter LotusScript. Nur dann werden Sie in der Lage sein, das Maximale aus den zugegebenermaßen eingeschränkten Möglichkeiten herauszuholen.
17.4 Was ist OOP? OOP ist eine Art, ein zu programmierendes Problem analytisch aufzufassen. Dazu gibt es in der Softwarearchitektur viele unterschiedliche Möglichkeiten. Eine sehr grundlegende ist die der prozeduralen Zerlegung. In diesem Fall fasst man ein Programm als eine einzige große Funktion auf, die in mehrere Teilfunktionen zerlegt werden kann, die ihrerseits wiederum in weitere Funktionen zerfallen. Dies treibt man soweit, bis die entstehenden untersten Teilfunktionen atomar sind; diese können sofort und sehr leicht in Programmcode umgesetzt werden. Der Nachteil dieser Methode ist, dass ein solches System bei großen Softwareentwicklungen sehr komplex werden kann. Gleichartige Vorgänge, die womöglich noch mit den gleichen Datenarten ablaufen, mögen in dieser Architektur an ganz unterschiedlicher Stelle auftreten. Dadurch entstehen im Allgemeinen Redundanzen, die nicht ohne weiteres erkannt werden können und sich auch aufgrund des Modells kaum vermeiden lassen. Sollte sich die den Daten zugrunde liegende Struktur einmal ändern, müssen diese Änderungen in einem solchen Softwaresystem an sehr vielen Stellen nachgepflegt werden. Alle diese Nachteile der rein funktionalen Sichtweise kann man mit der OOP elegant und auch recht einfach umgehen. In der OOP beschäftigt man sich zunächst weniger damit, was die Software später einmal leisten soll. Vielmehr macht man sich zunächst Gedanken darüber, welche Objekte in dem System eingeschlossen sind und wie sie miteinander arbeiten (»kommunizieren«). Erst wenn dieser Aspekt völlig klar ist und die einzelnen Objekte im Kern fertig gestellt sind, wird die eigentliche Funktionalität des gewünschten Programms mittels dieser Objekte zusammengestellt. Dadurch tritt das Erkennen der einzelnen Objekte und das Studieren ihres Verhaltens in den Vordergrund, während die Erstellung der Funktionalität des Programms (scheinbar) zweitrangig wird. Eine solche Herangehensweise erscheint im ersten Moment nicht sehr logisch und scheint auch eine Fülle an Mehrarbeit zu verursachen. Und tatsächlich entsteht in der ersten Phase, in der man sich mehr mit den Objekten als mit der Funktionalität befasst, einiges mehr an Aufwand. Hat man aber erst einmal die beteiligten Objekte mit dem ihnen eigenen Verhalten klar herausgearbeitet, dann wird die Zusammenstellung der Programmfunktionalität fast ein Kinderspiel. Sollten später Änderungen an den Daten oder auch am Programm selber erforderlich werden, so wird diese Arbeit in einem Bruchteil der Zeit erledigt werden können, als dies sonst der Fall wäre. Last-but-not-least ist ein gut aufgebautes
OOP am Beispiel
189
objektorientiertes Programm von Außenstehenden wesentlich leichter lesbar und erheblich schneller durchschaubar. Sollte also nach einigen Jahren der ursprüngliche Entwickler nicht mehr zur Verfügung stehen, so wird die OOP auch hier ihre Stärken zeigen. OOP
Vorteile
Nachteile
Kleine Programme
Wiederverwendbarkeit im Zusammenhang mit größeren Systemen.
Hoher Designaufwand, der sich in kleinen Programmen nicht durch schnellere Implementierung wettmachen lässt.
Große Programme
Klareres Design, das dem natürlichen Denken des Menschen näher kommt. Veränderungen in den Datenstrukturen erfolgen nur lokal in den Objekten. Dadurch ist die Wartung und Weiterentwicklung von Software wesentlich leichter.
Unter gewissen Umständen kann das Laufzeitverhalten gegenüber einem funktionalen Design zurückfallen. Dies wird allerdings häufig vorschnell als Gegenargument gebraucht. Ein gutes objektorienties Design kann auch in einer Interpretersprache wie LotusScript sehr performant sein.
Tabelle 17.1: Vor- und Nachteile der Objektorientierten Programmierung
Um die OOP einzuführen und die Vorgehensweise zu demonstrieren, betrachten wir in der Folge ein Beispiel.
17.5 OOP am Beispiel Wir wollen das Rasenmähen in Zukunft dem Computer überlassen, während wir selbst uns höheren Aufgaben widmen (z. B. dieses Buch studieren). Dies ist nicht unbedingt ein Beispiel aus Ihrer täglichen Programmierpraxis. Insbesondere ist es nicht sehr geeignet, das veranschaulichte Problem speicherschonend zu bearbeiten. Wenn die verwendeten Rasenstücke groß genug sind, werden schnell 7-Stellige Zahlen für die Anzahl der Grashalmobjekte erreicht. Da für jeden Grashalm ständig ein Objekt im Arbeitsspeicher gehalten wird, ist dieses Beispiel recht speicherhungrig. Wir haben es dennoch gewählt, weil es gut geeignet ist, alle Aspekte der OOP zu veranschaulichen, die wir hier vorstellen möchten. Und wer den Stoff gut verstanden hat, wird die hier erläuterten Prinzipien leicht auf nützlichere Anwendungsgebiete anwenden können. Damit die Praxis nicht zu kurz kommt, werden wir am Ende des Kapitels noch ein Beispiel für die OOP anführen, das die gelernten Kernpunkte zur Abrundung praxisnah anhand unserer Anwendung Kontaktmanagement veranschaulicht.
190
Objektorientierte Programmierung unter LotusScript
Beim Rasenmäher-Beispiel zeigen wir zu Beginn, wie der funktionale Ansatz im Kern aussehen würde. Dies soll Sie in Verbindung mit den daran anschließenden Ausführungen davon überzeugen, dass der objektorientierte Ansatz auf jeden Fall eine ernsthafte Erwägung wert ist. Betrachten wir die Sache also zunächst einmal »funktional«.
17.6 Funktionale Analyse Bei der funktionalen Betrachtungsweise würde man zunächst das Hauptprogramm mit dem Funktionsnamen »Rasenmähen« bezeichnen. Dieses zerfällt in die Funktionen »Rasenmäher schieben« und »Gras schneiden«. »Rasenmäher schieben« wiederum wird unterteilt in »Gärtner läuft« und »Rasenmäher bewegt sich«, »Gras schneiden« in »Messer rotiert« und »Grashalme kürzen« usw. Betrachten wir die Funktion »Rasenmäher bewegt sich« ein wenig genauer. Man wird sie in eine horizontale Fortbewegung und in eine rotierende Bewegung der Räder unterteilen. Den Rasenmäher packen wir mit allen wesentlichen Angaben (momentane Position, momentane Stellung der Räder, momentane Stellung des Messers usw.) in eine Datenstruktur, die wir mittels der Script-Anweisung Type deklarieren. Type Rasenmäher XPosition As Integer YPosition As Integer RäderWinkelstellung As Integer MesserWinkelstellung As Integer RadRadius As Integer End Type
Durch die Zerlegung sind also mittlerweile die Funktionen »Horizontal bewegen« und »Räder drehen« entstanden, die beide auf derselben Datenstruktur Rasenmäher arbeiten. Function HorizontalBewegen(oMäher As Rasenmäher, _ nBewegungX As Integer, nBewegungY As Integer) oMäher.XPosition = oMäher.XPosition + nBewegungX oMäher.YPosition = oMäher.YPosition + nBewegungY End Function Function RäderDrehen(oMäher As Rasenmäher, nWinkel As Integer) oMäher.RäderWinkelstellung = oMäher.RäderWinkelstellung + _ nWinkel End Function
Funktionale Analyse
191
Die Funktion »Messer drehen« würde etwa so aussehen: Function MesserDrehen(oMäher As Rasenmäher, nWinkel As Integer) oMäher.MesserWinkelstellung = oMäher.MesserWinkelstellung + _ nWinkel End Function
Während der Gärtner den Rasenmäher schiebt, müssen jetzt wechselweise diese beiden Funktionen so lange aufgerufen werden, wie geschoben wird. Jedesmal wird der Mäher ein Stück vorgerückt und jedesmal werden die Räder ein wenig weitergedreht. Und das Drehen des Messers nicht vergessen! Und das Stutzen der Grashalme! Usw. usw. Function MäherSchieben(oMäher As Rasenmäher, nStrecke As Integer) Dim nWinkelÄnderung As Integer HorizontalBewegen oMäher, nStrecke 'Winkelveränderung berechnen '- voller Winkel beträgt 2 * PI = eine Umdrehung '- Radumfang beträgt 2 * PI * Radius = Strecke einer Umdrehung '--> Anzahl Umdrehungen = nStrecke / Radumfang = nStrecke / ' (2 * PI * Radius) '--> Winkelveränderung = Anzahl Umdrehungen * voller Winkel = ' nStrecke / Radius nWinkelÄnderung = nStrecke / oMäher.RadRadius RäderDrehen oMäher, nWinkelÄnderung ' Messer bewegen .... '... End Function
Alle Bewegungen im Sinn zu behalten und zu jeder Zeit sämtliche Vorgänge programmiertechnisch zu kontrollieren, erfordert bei dieser Vorgehensweise also schon einiges von der Fähigkeit eines Jongleurs. Man ahnt schon, worin die Schwierigkeit liegt: Wenn der Jongleur einmal kurz unaufmerksam wird, dann kann die ganze Sache ganz plötzlich zusammenbrechen. Ein weiterer Nachteil ist, dass sämtliche Teilfunktionen (»Horizontal bewegen«, »Räder drehen«, »Messer drehen« usw.), die mit dem Mäher zu tun haben, auf derselben Datenstruktur arbeiten. Wehe also, wenn die Datenstruktur aus irgendeinem Grund nachträglich geändert werden muss! Dann muss jede auf ihr arbeitende Funktion ebenfalls kontrolliert, evtl. angepasst und auf jeden Fall neu kompiliert werden. Das hat wieder etwas von einem Jongleur.
192
Objektorientierte Programmierung unter LotusScript
Funktionale Programmierung
Vorteile
Nachteile
Kleine Programme
Wenig Aufwand.
Die Wiederverwendbarkeit für sich ergebende größere Programme ist eingeschränkt.
Große Programme
Die funktionale Programmierung mag für einzelne laufzeitkritische Teile die bessere Wahl sein. Hier würde man u. U. sogar globale Variablen zulassen. Allerdings ist dieses Argument selten stichhaltig.
Die Übersicht geht verloren. Es treten verstärkt Code-Redundanzen auf. Dies verursacht hohe Wartungskosten und behindert die Weiterentwicklung.
Tabelle 17.2: Vor- und Nachteile der funktionalen Programmierung
Im Folgenden werden wir sehen, wie sich all diese Nachteile mit dem objektorientiertem Ansatz vermeiden lassen.
17.7 Objektorientierte Analyse Die Objektorientierte Analyse wird auch mit dem Kürzel OOA bezeichnet. Bei dieser Vorgehensweise ermitteln wir zunächst die beteiligten Objekte: Gärtner, Rasenmäher, Rasen. Dann betrachten wir die Eigenschaften und Fähigkeiten der Objekte jeweils für sich: Der Gärtner z. B. hat einen Namen, eine typische Schrittgeschwindigkeit (je nachdem, ob fleißig oder faul), eine Schuhgröße; der Rasenmäher hat eine Marke, ein Messer, vier Rollen; der Rasen wiederum hat eine bestimmte Höhe und viele Grashalme und sonstiges (Un)kraut. Der Gärtner kann laufen, essen, wachsen; der Rasenmäher kann schneiden, Krach machen; der Rasen kann wachsen und geschnitten werden. Wir haben nur einige »wesentliche« Eigenschaften aufgezählt. In Wirklichkeit können die einzelnen Objekte noch viel mehr. Bevor wir uns jetzt aber darüber Gedanken machen, welche Konfektionsgröße und Hobbys der Gärtner hat und welche Schrauben zum Bau des Rasenmähers gebraucht werden, halten wir erst einmal inne. Wir vergegenwärtigen uns, dass wir für das »Problem« Rasenmähen nicht jedes mögliche Detail benötigen, das die Objekte aufweisen mögen. Daher spezifizieren wir die Objekte nur soweit, wie es momentan notwendig erscheint. Insofern haben wir auch beim Erstellen des OOD (Objektorientiertes Design) die Funktionalität im Auge. Allerdings ist es nicht sehr schädlich, wenn die Funktionalität noch nicht bis ins Kleinste festgelegt wird. Bei der funktionalen Analyse wäre das tödlich.
Kerngedanken der Funktionalen und der Objektorientierten Programmierung
193
Die OOP hat i. A. zunächst mehr die Eigenschaften und das Verhalten der beteiligten Objekte im Auge. Das heißt aber nicht, dass man sich über die letztendlich gewünschte Funktionalität keine Gedanken zu machen braucht. Die Auswahl der passenden Objekte mit den passenden Eigenschaften und Methoden orientiert sich an der gewünschten Programmfunktionalität. Das Gute an der OOP ist, dass man den Objekten eventuell vergessene Eigenschaften und Fähigkeiten jederzeit hinzufügen kann, ohne dass dadurch ein bereits erstelltes Programm beeinträchtigt würde.
17.8 Kerngedanken der Funktionalen und der Objektorientierten Programmierung Designmethode
Grundidee
Funktionale Analyse
Ein Programm wird als eine einzige große Aufgabe (Funktion) aufgefasst. Diese wird immer weiter in kleinere Funktionen aufgegliedert, bis man zu elementaren Funktionen gelangt, die sich praktisch unmittelbar aus der Spezifikation in Programmcode umsetzen lassen.
Objektorientierte Analyse (OOA, OOD)
Ein Programm wird als das Zusammenwirken von Objekten aufgefasst. Objekte sind Datenstrukturen mit darauf wirkenden Funktionen. Die nach außen sichtbaren Daten eines Objektes werden als Eigenschaften bezeichnet, die Funktionen als Methoden. Objekte »kommunizieren« miteinander und mit der Außenwelt über ihre Methoden. Diese Designmethode kommt i. A. dem natürlichen Verständnis von Aufgabenstellungen wesentlich näher als die funktionale Vorgehensweise.
Tabelle 17.3: Gegenüberstellung Funktionale und Objektorientierte Programmierung
17.9 Objekte in LotusScript »bauen« Wie bauen wir nun solche Objekte in LotusScript? Zunächst einmal muss es für jedes Programmobjekt eine zugrunde liegende »Klasse« geben. Eine Klasse ist der Bauplan für ein Objekt. So wie es für unseren Rasenmäher in der Herstellerfirma einen Bauplan gibt, nach dem Hunderte und Tausende gleicher Rasenmäher gebaut werden, so kann man auch nach Erstellung einer Klasse so viele darauf basierende Objekte anlegen, wie man will. Die Klasse ist der Bauplan, der als Schablone (einmal) irgendwo im Arbeitsspeicher abgelegt wird, selbst aber über keinerlei sonstige Fähigkeiten verfügt. Das Objekt dagegen ist eine Bit- und Bytestruktur
194
Objektorientierte Programmierung unter LotusScript
(ebenfalls im Speicher), die genau das tut, was der Bauplan ihr vorgibt. Objekte kann es im Gegensatz zur Klasse so viele geben, wie der Arbeitsspeicher hergibt. Eine Klasse ist der Bauplan, nach dem bei der Instanziierung die Objekte im Arbeitsspeicher angelegt werden. Das Programm selbst arbeitet mit Objekten, nicht mit Klassen. Doch häufig werden beide Begriffe synonym verwendet. Das ist auch in diesem Buch der Fall. Dies ist zwar nicht ganz korrekt, liegt aber nahe, weil sich die Objekte genau nach dem Bauplan der Klassen verhalten. Klassen müssen wie Variablen und Datentypen vor ihrer Verwendung deklariert werden. Objekte hingegen werden auf Basis dieser Deklaration definiert oder, wie man auch sagt, instanziiert. Deklaration von Klassen: Class Gärtner End Class Class Rasenmäher End Class Class Rasen End Class
Die Class End-Anweisung legt den Beginn und den Abschluss des Gültigkeitsbereiches einer Klasse fest. Das bedeutet, dass sämtliche innerhalb dieser Anweisung deklarierten Elemente (dies können Variablen und Funktionen bzw. Prozeduren sein) nur über die Angabe des Bezeichners der Objektreferenzvariablen und des Bezeichners des jeweiligen Elements (getrennt durch einen Punkt) aufgerufen werden können. Beispiele hierzu finden Sie in Abschnitt 17.11. Definition von Objekten: Dim oFleißig As New Gärtner Dim oKlappergestell As New Rasenmäher Dim oUnserGanzerStolz As New Rasen
Das Präfix »o« bei den Objektvariablennamen macht deutlich, dass sich diese Variablen auf Objekte beziehen. Sie können natürlich auch jedes andere Ihnen zusagende Präfix verwenden, oder es je nach Geschmack ganz weglassen. Letzteres ist allerdings aus Gründen der Lesbarkeit nicht zu empfehlen. Zusammenfassend können wir sagen: Wir haben mit der Class End-Anweisung zunächst die »Baupläne« erstellt und darauf aufbauend mit Dim Objektname As New Klassenname von jedem Bauplan ein Objekt im Arbeitsspeicher erzeugt.
Eigenschaften und Methoden
195
17.10 Eigenschaften und Methoden Allerdings sind das noch sehr nichtssagende Objekte. Denn sie verfügen zurzeit weder über Eigenschaften noch irgendwelche Fähigkeiten. Fähigkeiten nennt man in der OOP auch »Methoden«. Eigenschaften sind ganz einfach Variablen, die einem Objekt zugeordnet werden, während Methoden ihm zugeordnete Funktionen bzw. Prozeduren sind. Eigenschaften werden durch Variablen beschrieben, die innerhalb des Gültigkeitsbereiches einer Klasse definiert sind. Methoden werden durch Funktionen und Prozeduren beschrieben, die innerhalb des Gültigkeitsbereiches einer Klasse definiert sind. Versehen wir also den Gärtner mit einigen Eigenschaften und Fähigkeiten. Zunächst die Eigenschaften: Class Gärtner Public Name As String Public SchrittGeschwindigkeit As Single Schuhgröße As Integer End Class
Eigenschaften werden innerhalb der Class End-Anweisung wie Variablen deklariert. Dabei gibt es zwei wichtige Unterschiede zur normalen Variablen-Deklaration: innerhalb einer Klassendeklaration können Variablen nicht definiert werden. Das heißt, man kann sie zwar deklarieren, ihnen aber keine Werte zuweisen. Also fällt auch eine Anweisung wie Dim Objektname As New Klassenname für eine Eigenschaftendeklaration flach. Wertzuweisungen sind nur über Klassenmethoden oder durch Zuweisung »von außen« möglich. Des Weiteren ist Ihnen sicherlich aufgefallen, dass wir bei der Schuhgröße das Schlüsselwort Dim ausgelassen haben. Es ist in diesem Kontext nicht erlaubt. Und noch etwas Interessantes: die Eigenschaften Name und SchrittGeschwindigkeit sind Public deklariert worden. Damit sind diese Eigenschaften von außen sichtbar, die Schuhgröße hingegen nicht. Das heißt, die Schuhgröße ist nur dem Gärtner selbst bekannt (er verrät nicht gerne, dass seine Plattfüße schon Größe 52 erfordern). Wenn das Objekt auch diese Eigenschaft nach außen bekannt geben will, so muss es dies auf andere Weise tun, wie wir noch sehen werden. Man hätte zur Verdeutlichung dieses Sachverhalts vor die Schuhgröße auch das Schlüsselwort Private setzen können. Das hat aber keinen anderen Effekt als das bereits vom Compiler »unsichtbar eingefügte« Private. Wenn wir von dieser erweiterten Klasse den Gärtner Fleißig mit der Anweisung Dim oFleißig As New Gärtner anlegen, dann hat Fleißig also die Eigenschaften Name, SchrittGeschwindigkeit und Schuhgröße. Allerdings sind die Eigenschaftsvariablen noch leer.
196
Objektorientierte Programmierung unter LotusScript
Noch ein Hinweis zu den Bezeichnern der Eigenschaftsvariablen. Normalerweise sollen Präfixe anzeigen, welchen Datentyp eine Variable repräsentiert. Nun gibt es in Klassendefinitionen bei den Eigenschaftsvariablen noch die Unterscheidung in Public und Private. Eine Möglichkeit, dies deutlich zu machen, wäre ein weiteres Präfix. Dies würde ein weitergehendes Stilkonzept erfordern, mit dem wir den Stoff dieses Buches nicht belasten wollen. Daher wird bei den Public-Eigenschaften das Präfix einfach weggelassen.
17.11 Abfrage von Eigenschaften Den Namen von oFleißig erhält man analog zur Abfrage von Type-Elementen mit dem Punktoperator: oFleißig.Name
Diesen Namen kann man einer String- oder auch Variant-Variablen zuweisen: Dim sGärtnerName As String sGärtnerName = oFleißig.Name
Die Abfrage von Eigenschaften anderer Datentypausprägung erfolgt analog. Eigenschaften vom Datentyp Integer würde man also einer Integer- oder Variantvariablen zuweisen, Eigenschaften vom Datentyp Long dagegen einer Long- oder einer Variantvariablen usw.
17.12 Zuweisen von Eigenschaften 17.12.1 Explizites Setzen von Eigenschaften Da der Name noch leer ist, müssen wir ihm erst einmal einen Wert zuweisen; dies geschieht über den Zuweisungsoperator: oFleißig.Name = "Anton"
Wenn wir einen zweiten Gärtner haben, z. B. den Gärtner oFaul, dann legen wir vom gleichen »Bauplan« (= Klasse Gärtner) ein zweites Objekt an und geben diesem den entsprechenden individuellen Namen: Dim oFaul As New Gärtner oFaul.Name = "Wilhelm"
Nun geben wir noch die Arbeitsgeschwindigkeiten der beiden Gärtner an: oFleißig.SchrittGeschwindigkeit = 2 oFaul.SchrittGeschwindigkeit = 0.5
Zuweisen von Eigenschaften
197
Die Zahlen mögen für km/h stehen. Dies vereinbaren wir ganz willkürlich. Denn noch haben wir dafür keine Eigenschaft deklariert. Dies folgt im nächsten Abschnitt.
17.12.2 Implizites Setzen von Eigenschaften Wenn die Maßeinheit im Objekt festgehalten werden soll, dann können auch hierfür Eigenschaftsvariablen deklariert und später entsprechend belegt werden. Allerdings wäre es lästig, für zehn Gärtner jedesmal nach der Erzeugung des Objektes die Maßeinheit explizit definieren zu müssen. Wie können wir dies umgehen? N ew-M etho de Für solche Probleme gibt es die New-Methode, den Konstruktor in Basic-Sprachen. Dies ist eine Methode der Klasse, die beim Erzeugen der Objekte automatisch in Aktion tritt, wenn beispielsweise die Anweisung Dim Durchschnittlich As New Gärtner einen weiteren elektronischen Gärtner erzeugt. Eine New-Methode kann in jeder Klasse angelegt werden. Man kann sie aber auch ohne Schaden weglassen. Nur ist die Initialisierung des Objektes dann dem Programmierer überlassen. Objekte können bei der Erzeugung (Instanziierung) automatisch initialisiert werden. Dazu dient die New-Methode, in anderen Programmiersprachen auch Konstruktor oder New-Operator genannt. Da wir selbstverständlich zu viel Arbeit vermeiden wollen, spendieren wir unserem Gärtner eine New-Methode: Class Gärtner Public Name As String Public SchrittGeschwindigkeit As Single Public MassEinheit As String Sub New MassEinheit = "km/h" End Sub End Class
Erzeugen wir nun ein weiteres Gärtnerobjekt, dann wird die Maßeinheit automatisch bei der Erzeugung eingetragen. Wir können sie bereits unmittelbar danach ohne weiteres Zutun abfragen: Dim oDurchschnittlich As New Gärtner Dim sEinheit As String sEinheit = oDurchschnittlich.MassEinheit
198
Objektorientierte Programmierung unter LotusScript
I n i ti ali liss i e r un g i m De b u gg e r Wenn wir die Variable Einheit im Debugger betrachten, stellen wir fest, dass sie den Wert »km/h« enthält. Sie sollten sich überhaupt möglichst viele Beispiele im Debugger anschauen, um ein Gefühl dafür zu bekommen, wie sich die Objekte zur Laufzeit verhalten. Dazu kann ein einfacher Agent dienen. Die Klassendeklarationen packen Sie in den Abschnitt »(Declarations)« und im Abschnitt »Initialize« legen Sie die Objekte an und führen auch die Verarbeitung durch. Welche Möglichkeiten Ihnen der Debugger bietet, um die Initialisierung der Objekte und ihre Verarbeitung zu verfolgen, finden Sie im Kapitel Entwicklungsumgebung (IDE). U n te r s c h i e d l ic h e I n i ti a li s i e r un g v e r w a n d t e r O b j e k t e Solange sich alle Gärtner mit metrischer Geschwindigkeit fortbewegen, ist diese Art der Objektinitialisierung ausreichend. Was ist aber, wenn wir nicht nur deutsche, sondern auch britische Gärtner einsetzen möchten? Ein britischer Gärtner wird sich vorzugsweise in »miles/h« bewegen. Die weniger elegante Möglichkeit wäre, eine Klasse DeutscherGärtner und eine Klasse BritscherGärtner zu erzeugen, die unterschiedliche New-Methoden enthalten: Class DeutscherGärtner ... Public MassEinheit As String Sub New MassEinheit = "km/h" End Sub End Class Class BritischerGärtner ... Public MassEinheit As String Sub New MassEinheit = "miles/h" End Sub End Class
N e w- M e t h o de pa ra me tr i s i e r e n Etwas unelegant ist dieses Vorgehen, weil wir jetzt zwei Klassen erzeugt haben, die einander ziemlich ähnlich sind. Dadurch müssen wir unter Umständen eine Menge Code doppelt schreiben. Und ihn auch an doppelt so vielen Stellen warten. Da schüttelt’s einen vernünftigen Softwareentwickler: brrrrrr ...! Was können wir tun?
Zuweisen von Eigenschaften
199
Die einfachere Lösung führt zur Parametrisierung der New-Methode: Class Gärtner ... Public MassEinheit As String Sub New(in_MassEinheit As String) MassEinheit = in_MassEinheit End Sub End Class
Beim Erzeugen eines neuen Gärtner-Objektes müssen wir nun dem New-Operator mitteilen, mit welchen Werten das Objekt initialisiert werden soll: Dim oDurchschnittlich As New Gärtner("km/h")
oder Dim oDurchschnittlich As New Gärtner("miles/h")
K o n t r o l le im D e b u g g e r Wie wir uns im Debug-Modus überzeugen können, wird der Gärtner Durchschnittlich entweder mit der deutschen oder der britischen Maßeinheit ausstaffiert, je nachdem welchen Parameterwert wir bei der Erzeugung mitgeben. Die hier beschriebene Methode ist gut geeignet, wenn sich die zu erzeugenden Objekte nur durch wenige Initialisierungswerte unterscheiden. W e i t e r e V e re i n f a c h un g b e i vi e l e n P a r a me t e r n Bei der Betreuung einer großen Parkanlage kann es sein, dass wir viele deutsche und viele britische Gärtner zu betreuen haben. Wenn wir dann bei jeder Objekterzeugung alle Parameterwerte, die deutsche und britische Gärtner voneinander unterscheiden, jeweils angeben müssten, so wäre das nicht besonders schön. Also verändern wir unsere Gärtner-Klasse folgendermaßen: Class Gärtner ... Public MassEinheit As String Public Sprache As String Sub New(in_Nationalität As String) If in_Nationalität = "deutsch" then MassEinheit = "km/h" Sprache = "Deutsch" Elseif in_Nationalität = "britisch" then MassEinheit = "miles/h" Sprache = "Englisch" End if End Sub End Class
200
Objektorientierte Programmierung unter LotusScript
Jetzt brauchen wir beim Erzeugen neuer Gärtner nur noch die jeweilige Nationalität anzugeben und schon werden alle zugehörigen Eigenschaften richtig gesetzt. Ein britischer Kollege würde so erzeugt: Dim oDurchschnittlich As New Gärtner("britisch")
Dieser Gärtner hat automatisch die Maßeinheit »miles/h« und die Sprache »Englisch«. Dies ist von Vorteil, wenn die Gärtner sich durch eine ganze Anzahl Unterschiede auszeichnen, die bei der Initialisierung durch Angabe der Nationalität automatisch festgelegt werden können.
17.13 Vererbung Angenommen, wir beschäftigen Gärtner vieler Nationalitäten. Dann kann man sich sofort ausmalen, dass die New-Methode unter Umständen sehr lang und unhandlich werden kann. Denn wir müssten in dieser einen Methode sämtliche Unterschiede für alle vorkommenden Nationalitäten beschreiben. Dieses Problem kann man durch das Konzept der Vererbung ganz leicht aus der Welt schaffen. Vererbung bedeutet vereinfacht gesagt, dass neue Klassen von bereits vorhandenen abgeleitet werden. Sie erben dann die spezifischen Merkmale und Methoden der zugrunde liegenden Basisklassen. Dies geschieht in LotusScript mit der Class Klassenname As Basisklasse End-Anweisung. Das Konzept der Vererbung beschreibt die Beziehung von zwei Klassen, bei der die so genannte Subklasse Eigenschaften der Basisklasse übernimmt (also »erbt«). Die Basisklasse einer Subklasse wird auch als Superklasse bezeichnet, da man sich die Vererbungshierarchie als »von oben nach unten«, also topdown verlaufend, vorstellt. Setzt man das Konzept der Vererbung ein, so ist zunächst zu überlegen, welche Klassen gemeinsame Merkmale besitzen, die sich von einer gemeinsamen Basisklasse ableiten lassen. Bei den Gärtnern verschiedener Herkunft könnte die Basisklasse so aussehen: Class Gärtner Name As String SchrittGeschwindigkeit As String MassEinheit As String Sprache As String Kleidung As String Sub New End Sub End Class
Vererbung
201
Die abgeleiteten Klassen: Class BritischerGärtner As Gärtner Sub New MassEinheit = "miles/h" Sprache = "Englisch" End Sub End Class Class DeutscherGärtner As Gärtner Sub New MassEinheit = "km/h" Sprache = "Deutsch" End Sub End Class
Die Erzeugung der einzelnen Gärtnerobjekte sieht jetzt wie folgt aus: Dim oDurchschnittlich As BritischerGärtner
oder Dim oDurchschnittlich As DeutscherGärtner
Man kann die Vererbung beliebig weitertreiben. So kann man zum Beispiel von BritischerGärtner die Klasse SchottischerGärtner und die Klasse EnglischerGärtner ableiten und von DeutscherGärtner die Klasse BayrischerGärtner und die Klasse PreussischerGärtner. Dies tun wir stellvertretend für zwei Gärtner-Klassen: Class SchottischerGärtner As BritischerGärtner Sub New Kleidung = "Schottenrock" End Sub End Class Class BayerischerGärtner As DeutscherGärtner Sub New Kleidung = "Lederhose" End Sub End Class
Wollten wir diesen Code so abspeichern bzw. kompilieren, würden wir eine entsprechende Fehlermeldung erhalten, die besagt, dass wir eine Eigenschaftsvariable (Kleidung) ansprechen, die die Klasse gar nicht kennt. Wir könnten diese Eigenschaft noch in die jeweilige Klassendeklaration einfügen, also z. B.: Class BayerischerGärtner As DeutscherGärtner Public Kleidung As String Sub New Kleidung = "Lederhose" End Sub End Class
202
Objektorientierte Programmierung unter LotusScript
Dies zeigt, wie man in abgeleitete Klassen zusätzliche Eigenschaften einfügen kann, die dann nur für diese und alle von ihr wiederum abgeleiteten Klassen zur Verfügung stehen. Abgeleitete Klassen können zusätzliche Eigenschaften und Methoden erhalten. Diese werden in der abgeleiteten Klasse einfach zusätzlich deklariert und definiert. In unserem Beispiel benötigen wir die Eigenschaft »Kleidung« allerdings für sämtliche Landsmänner. Wir müssten also die Ergänzung in jeder der vier abgeleiteten Klassen der untersten Ebene anwenden. So würden wir unversehens redundanten Code erzeugen. Daher verlegen wir die Deklaration der Eigenschaft in die in der Vererbungshierarchie höchstliegende Basisklasse. Dadurch kann die Vererbung ihre volle Kraft entfalten. In diesem Fall würden wir uns für die Basisklasse Gärtner entscheiden. (Wir könnten auch die Klassen BritischerGärtner und DeutscherGärtner wählen. Dann müssten wir die Definition nur noch zweimal vollziehen. Aber auch zweifache Redundanz ist ungesund. Besser ist gar keine!) Class Gärtner Name As String SchrittGeschwindigkeit As String MassEinheit As String Sprache As String Kleidung As String Sub New End Sub End Class
Die Eigenschaft Kleidung steht jetzt für alle abgeleiteten Klassen in allen Ableitungsebenen zur Verfügung. Sie kann in jeder dieser Klassen angesprochen werden, ohne dass sie jedesmal neu deklariert werden müsste. Nun haben wir Maßeinheiten speziell für deutsche und britische Gärtner implementiert. Dies müssten wir auch für alle Gärtner anderer Nationalitäten ganz analog tun. Da aber fast die ganze Welt im metrischen System rechnet, kann dies ganz schön lästig und schon wieder redundant werden. Was mit dieser Redundanz passiert, wenn die ganze Welt ihr metrisches System auf ein anderes umstellen sollte, kann man sich schon vorstellen. An allen Gärtner-Klassen, die auf dieses System zurückgreifen, müssten Veränderungen vorgenommen werden. We i t e r e R e du n da n zv e r me i d un g Man kann die Vornahme so umfangreicher Änderungen aber sehr einfach vermeiden. Zu diesem Zweck legen wir für die allgemeine Basisklasse »Gärtner« mit deren NewMethode zunächst das metrische System fest:
Vererbung
203
Class Gärtner ... MassEinheit As String ... Sub New MassEinheit = "km/h" End Sub End Class
Alle von dieser Klasse abgeleiteten Gärtner-Klassen sind jetzt auf das metrische System eingestellt. Dazu muss deren New-Methode natürlich entsprechend gekürzt werden. Man entfernt dort jeweils die Zeile MassEinheit = ... Lediglich in der Klasse der britischen Gärtner bleibt die New-Methode, wie sie ist: Class BritischerGärtner As Gärtner Sub New MassEinheit = "miles/h" Sprache = "Englisch" End Sub End Class
A b l a u f d e s V e r e r b u n g sm e c h a n i s m us Was passiert denn nun, wenn ein Objekt der Klasse BritischerGärtner angelegt wird? Sie sollten das einmal tun und dabei den Vorgang der Initialisierung im Debugger beobachten. Sie werden feststellen, dass als Erstes die New-Methode der Basisklasse Gärtner abgearbeitet wird und anschließend diejenige der abgeleiteten Klasse BritischerGärtner. Dabei wird die MassEinheit zunächst mit »km/h« initialisiert und anschließend mit »miles/h« überschrieben. So hat der britische Kollege zwar für einen winzigen Moment den falschen Wert, aber dies wird sofort wieder richtig gestellt. Wenn man anschließend mit dem so erzeugten Objekt arbeitet, merkt man von dem kurzen Umweg nichts. Es verhält sich so, als wäre die Eigenschaft von Anfang an richtig gesetzt worden. Warum wird denn dieser Umweg überhaupt beschritten? Er ist eine Folge des Vererbungskonzeptes. Dies wird sofort deutlich, wenn wir einen bayrischen Gärtner produzieren. Tun Sie dies bitte einmal und beobachten Sie das Ganze wieder im Debug-Modus. Sie werden wiederum feststellen, dass zunächst die New-Methode der Basisklasse Gärtner die MassEinheit auf »km/h« setzt. Dann wird die New-Methode der nächsten abgeleiteten Klasse DeutscherGärtner tätig und setzt die Sprache auf Deutsch. Zu guter Letzt sorgt die dritte Ableitungsstufe für die richtige Kleidung eines Bayern. So erbt jede abgeleitete Klasse die Einstellungen der vorherigen Klasse. Dabei wird folgerichtig die Vererbung von der obersten Ebene bis zur untersten abgearbeitet. Dies gilt für die New-Methode. Analoges gilt auch noch für die Delete-Methode, auf die wir etwas weiter unten eingehen. Für alle anderen Methoden, die Sie
204
Objektorientierte Programmierung unter LotusScript
implementieren mögen, gilt dieser Vorgang nicht. Dies ist auch logisch. Denn die New-Methode dient normalerweise der Initialisierung. Und dass diese der Vererbungshierarchie folgen muss, lässt sich gut einsehen. Alle anderen Methoden beschreiben irgendeine Funktionalität der Klassen bzw. Objekte. Und wie soll eine Funktionalität »in Teilen« vererbt werden? Man müsste einen Mechanismus erfinden, der festlegt, welche Teile zu vererben sind und welche nicht. Das wäre aber recht schwierig. Deshalb gibt es einen solchen Mechanismus auch nicht. Kr i t e r ie n fü r d i e G l e i chh hhe e i t v o n M e th o d e n Im Allgemeinen überschreibt eine Methode, die in Name, Typ und Parameterliste mit einer Methode der Basisklasse übereinstimmt, diese vollständig. Für eine Gleichheit zweier Parameterlisten genügt es, wenn die Anzahl und die Typen der Parameter übereinstimmen. Die Namen der Parameter selbst brauchen nicht identisch zu sein. Wird eine Methode auf diese Weise überschrieben, dann wird bei ihrem Aufruf nur die überschreibende Methode angesprochen. Es erfolgt kein Aufruf der namensgleichen Methode der zugrunde liegenden Basisklasse. Hat das Objekt selbst keine solche Methode, so wird dynamisch gesucht, welche nächste Superklasse eine solche hat, und diese wird ausgeführt. Auch diese überschreibt eine eventuell noch weiter oben in der Vererbungshierarchie angesiedelte Methode, die im obigen Sinne gleich ist, vollständig. Wir wollen uns diesen Vorgang mit Rasenmäher-Klassen vergegenwärtigen. Zunächst produzieren wir eine grundlegende Klasse Rasenmäher (die Definition der Klasse »Rasenmäher«, die in der Methode Schneiden verwendet wird, finden Sie etwas weiter unten im Abschnitt 17.19 »Benutzerdefinierte Containerklassen«): Class Rasenmäher nSchnittbreite As Integer nSchnitthöhe As Integer IstAmLaufen As Integer Sub New IstAmLaufen = False End Sub Function Anlassen As Integer Anlassen = Not IstAmLaufen End Function Sub Schneiden(in_oRasenStück As RasenStück) Forall halm In in_oRasenStück.Grashalme halm.Höhe = Schnitthöhe End Forall End Sub End Class
Zustandsvariablen
205
Wenn wir von dieser Klasse Rasenmäher ein Objekt oMäher anlegen, Dim oMäher As New Rasenmäher
dann wird die Eigenschaft IstAmLaufen auf FALSE gesetzt. Denn wenn man den Rasenmäher aus dem Geräteschuppen holt, kann man im Allgemeinen davon ausgehen, dass er noch nicht läuft. IstAmLaufen ist eine einfache Zustandsvariable. Solche Zustandsvariablen verdienen oft eine Sonderbehandlung, wie wir später noch sehen werden.
17.14 Zustandsvariablen Wenn wir den Anlasser betätigen, wird der Rasenmäher (hoffentlich) anspringen. Allerdings freut sich kaum ein Motor darüber, im laufenden Betrieb angelassen zu werden. Deshalb schlägt die Methode Anlassen auch fehl, falls der Motor bereits angelassen worden ist. Ansonsten wird sie den Motor starten. Da dies bei elektrischen Rasenmähern ein ganz anderer Vorgang ist als bei Benzinern, verlegen wir diesen Teil der Anlasser-Methode in die jeweiligen abgeleiteten Klassen. (Beispielsweise muss man beim Benziner mit Schwung an der Strippe ziehen, je doller, desto mehr Chancen auf Erfolg. Wer dasselbe beim Elektromäher versucht, wird einen ganz anderen »Erfolg« feststellen können. Der Kundendienst freut sich schon ...) Class Rasenmäher Sub New End Sub Function Anlassen As Integer Anlassen = Not IstAmLaufen End Function End Class
Die Eigenschaften »Schnittbreite«, »Schnitthöhe« und »IstAmLaufen« werden vererbt und brauchen daher nicht noch einmal definiert zu werden. Da das Schneiden mit einem Elektromäher und einem Benziner der gleiche Vorgang ist, kann auch diese Methode vererbt werden.
17.15 Methodenvererbung Betrachten wir also lediglich das Anlassen. Da beide Mäher nicht im laufenden Betrieb »angelassen« werden sollten, haben wir ein berechtigtes Interesse daran, den Teil, der dies sicherstellt, aus der Funktion Anlassen aus der Basisklasse an die Superklassen zu vererben. Vorher haben wir behauptet, dass dies nicht geht. Und jetzt zeigen wir den Mechanismus, mit dessen Hilfe es doch geht (es ist nur nicht ganz so einfach wie bei der New-Methode, wo der Mechanismus automatisch arbeitet!).
206
Objektorientierte Programmierung unter LotusScript
Das syntaktische Geheimnis lautet: NameDerBasisklasse..NameDerFunktionDerBasisklasse
Man kann das Ausführen einer Methode einer Basisklasse durch den ..-Operator erzwingen. Der Nachteil gegenüber der Automatik in der New-Methode ist gleichzeitig ihr Vorteil: Wir sind zwar gezwungen, die Methode der Basisklasse über den ..-Operator explizit aufzurufen, wir können aber auf diese Weise auch steuern, zu welchem Zeitpunkt dies geschieht. Somit ist diese »künstliche« Vererbung wesentlich flexibler als die automatische. Darüber hinaus kann man natürlich genauso gut irgendeine andere Methode der Basisklasse aufrufen. Es braucht keine namensgleiche zu sein. Und noch ein Vorteil: man kann einige Vererbungsebenen überspringen, indem man den Namen der gewünschten Superklasse angibt. Wir deklarieren also eine Klasse Benzinmäher: Class Benzinmäher As Rasenmäher IstTankLeer As Integer Sub New End Sub Sub AnStrippeZiehen IstAmLaufen = Not IstTankLeer End Sub Function Anlassen As Integer If Not Rasenmäher..Anlassen Then Exit Function AnStrippeZiehen Anlassen = IstAmLaufen End Function End Class
Und eine Klasse Elektromäher: Class Elektromäher As Rasenmäher nHatStrom As Integer IstKabelAnStrom As Integer Sub New nHatStrom = False IstKabelAnStrom = False End Sub Sub AnStrippeZiehen nHatStrom = False End Sub Function Anlassen As Integer Anlassen = Rasenmäher..Anlassen End Function End Class
Properties
207
Sie erkennen, wie unterschiedlich die Methode Anlassen bei den unterschiedlichen Rasenmähertypen arbeitet. In dem einen Fall greift sie erfolgreich auf die Anlasserstrippe zurück. Im anderen Fall wäre es fatal, an der »Strippe«, nämlich dem Elektrokabel, zu ziehen. In beiden Fällen müssen unterschiedliche Randbedingungen geprüft werden. Beim Benziner darf der Tank nicht leer sein, beim Elektromäher muss Strom anliegen.
17.16 Properties Warum haben wir eigentlich für die Sache mit dem Strom zwei Eigenschaften angelegt: »nHatStrom« und »IstKabelAnStrom«? Weil es zwei verschiedene Dinge sind, ob der Mäher selbst Strom hat oder nur das Kabel, aber der Mäher nicht. Letzteres würde einen Kabelbruch signalisieren. Wir kommen daher auf die Idee, dass die Klasse Elektromäher mit der Eigenschaft IstKabelGebrochen versehen werden könnte. Da sich diese Eigenschaft aber aus dem Vergleich zweier anderer Eigenschaften ergibt, können wir sie nicht einfach als Eigenschaftsvariable deklarieren. Was uns hilft, ist das Konstrukt der Property. Eine »Property« können Sie sich als einen Zwitter von Methode und Eigenschaft einer Klasse vorstellen. Eine Property kann wie eine Eigenschaftsvariable abgefragt werden. Zusätzlich kann sie während der Abfrage wie eine Methode eine Berechnung vornehmen oder irgendwelche anderen Vorgänge anstoßen. Und eine dritte bemerkenswerte Eigenschaft der Properties ist, dass man mit ihrer Hilfe Eigenschaftsvariablen vor Schreib- oder Lesezugriffen nach außen schützen kann. Theoretisch könnte man sie auch vor beidem schützen. Allerdings dürfte Letzteres kaum von praktischem Nutzen sein. Properties können zwei »Richtungen« haben. Die eine Richtung der Property wird mit dem Schlüsselwort Get bezeichnet und dient dazu, Abfragen an die Property zu bedienen. Die andere Richtung wird mit Set bezeichnet und bietet die Möglichkeit, zugewiesene Werte entgegenzunehmen. Durch die Aufspaltung in die beiden »Richtungen« können Zuweisungen an ein Objekt ganz anders behandelt werden als Abfragen. Wir setzen nun eine Property Get ein, um feststellen zu können, ob das Kabel eines Elektromähers gebrochen ist. Class Elektromäher As Rasenmäher nHatStrom As Integer IstKabelAnStrom As Integer Property Get IstKabelGebrochen As Integer IstKabelGebrochen = _ (IstKabelAnStrom And Not nHatStrom) End Property ... End Class
208
Objektorientierte Programmierung unter LotusScript
Wenn Sie ein Objekt auf Basis dieser Klasse anlegen, können Sie die Auswirkungen beim Aufruf der Eigenschaft IstKabelGebrochen im Debugger studieren: Dim oMäher As Elektromäher Dim nKabelGebrochen As Integer nKabelGebrochen = oMäher.IstKabelGebrochen
Die durch den Property-Code erzeugten Berechnungen lesen sich so: Lies zunächst die Eigenschaften IstKabelAnStrom und nHatStrom aus und bilde die boolesche Verknüpfung »And Not«. Das Ergebnis wird der Property zugewiesen, wodurch dieses einer »äußeren Abfrage« zur Verfügung steht. Das Ergebnis wird also in der Zuweisung nKabelGebrochen = oMäher.IstKabelGebrochen an die Variable nKabelGebrochen weitergereicht. Wollen Sie umgekehrt der Eigenschaft IstKabelGebrochen einen Wahrheitswert zuweisen, so wird der Compiler einen Fehler auswerfen: oMäher.IstKabelGebrochen = True
Der Grund ist, dass das Schlüsselwort »Get« im Kopf der Property angibt, dass diese Property nur abgefragt, aber nicht beschrieben werden kann. Wollen wir den Wert für IstKabelGebrochen nicht nur implizit über die beiden Teil-Eigenschaften nHatStrom und IstKabelAnStrom, sondern auch ganz explizit setzen können, so müssen wir eine Property Set definieren: Class Elektromäher As Rasenmäher nHatStrom As Integer IstKabelAnStrom As Integer Property Get IstKabelGebrochen As Integer IstKabelGebrochen = _ (IstKabelAnStrom And Not nHatStrom) End Property Property Set IstKabelGebrochen As Integer If IstKabelGebrochen Then nHatStrom = False Else If IstKabelAnStrom Then nHatStrom = True End If End Property ... End Class
Die Vorgänge zur Laufzeit lesen sich so: Zunächst wird der an die Property übergebene Wert in der If-Abfrage auf den enthaltenen Wahrheitswert hin geprüft. Je nach dem Ergebnis werden innerhalb des Objektes Berechnungen bzw. Zuweisungen vorgenommen. Auf diese Weise wird also ein »von außen« zugewiesener Wert in das Objekt »hineingereicht«.
Klassenvariablen
209
Wir sehen an diesem Beispiel sehr schön, wie uns das Property-Konzept eine große Flexibilität beim Umgang mit Eigenschaften erlaubt. Das Property-Konzept erlaubt eine große Flexibilität im Umgang mit Objekteigenschaften. Es gibt für die zwei Richtungen der Zuweisung (an eine Eigenschaft oder von einer Eigenschaft, Letzteres wird auch als Abfrage der Eigenschaft bezeichnet) auch zwei Typen von Properties: die Property Get und die Property Set. Das Property-Konzept wird auch eingesetzt, um Eigenschaften zu definieren, die von außen abgefragt, aber nicht gesetzt werden können. Zum Beispiel ist die Schnittbreite eine normalerweise unwandelbare Eigenschaft eines bestimmten Mähermodells. Daher schützen wir sie durch eine Property GetKonstruktion. Dazu benennen wir die Schnittbreite in der Basisklasse Rasenmäher um, schützen sie vor äußerem Zugriff durch das Schlüsselwort Private und bauen eine Property Get, die den Namen der Eigenschaft trägt: Class Rasenmäher ... nSchnittbreite As Integer ... Property Get Schnittbreite As Integer Schnittbreite = nSchnittbreite End Property Sub New (in_Schnittbreite As Integer) IstAmLaufen = False nSchnittbreite = in_Schnittbreite End Sub ... End Class
Auf diese Weise wird die Schnittbreite beim Anlegen eines Rasenmäher-Objektes über die New-Methode und den Parameter in_Schnittbreite einmal intern belegt. Danach kann sie von außen nur noch über die Property Schnittbreite abgefragt werden.
17.17 Klassenvariablen Allen bis jetzt definierten Eigenschaften ist gemeinsam, dass sie zwar teilweise von Basisklassen vererbt wurden, aber letztlich für jedes von einer Klasse erzeugte Objekt jede Eigenschaft speziell für dieses Objekt gesetzt wurde. Im Arbeitsspeicher existiert also für eine Objekt-Eigenschaft jedes Objektes ein separater Speicherplatz. Daher können diese Eigenschaftsvariablen prinzipiell alle unabhängig voneinander gesetzt werden. Sie werden auch Objektvariablen genannt.
210
Objektorientierte Programmierung unter LotusScript
Manchmal möchte man aber, dass eine Eigenschaft für alle Objekte einer Klasse denselben Wert hat. Und wenn sich dieser Wert ändert, soll er sich gleichzeitig auch für alle anderen Objekte gleichermaßen ändern. Solche Eigenschaften nennt man auch Klassenvariablen. Für Klassenvariablen wird nur ein einziger Wert gespeichert, auf den alle von dieser Klasse erzeugten Objekte zugreifen. Eine Objektvariable ist eine Objekteigenschaft, deren Wert nur für dieses eine Objekt Gültigkeit hat. Andere Objekte der gleichen Klasse können davon völlig unabhängige Werte haben. Eine Klassenvariable dagegen gilt für alle davon abgeleiteten Objekte. Verändert ein Objekt diesen Wert, ist er gleichermaßen auch in allen anderen Objekten der gleichen Klasse verändert. In Java beispielsweise gibt es das Konstrukt der Klassenvariable von Haus aus. Dies ist in LotusScript nicht der Fall. Aber man kann Klassenvariablen zumindest annähernd nachbauen. Zu diesem Zweck deklarieren wir die Klassenvariable im Bereich »Declarations« in der Bibliothek, in der sich auch die Klassendeklaration befindet. Zum Beispiel: Dim nHatMesser As Integer
(Wir deklarieren sie nicht mit dem Schlüsselwort »Public«, da sie sonst von außen unkontrolliert manipuliert werden könnte. Wenn dies egal ist, kann sie natürlich Public deklariert sein.) In der Basisklasse fügen wir jetzt eine Zugriffs-Property ein: Property Get HatMesser As Integer HatMesser = nHatMesser End Property
Die Initialisierung nehmen wir jetzt an zentraler Stelle für die ganze Klasse nur einmal vor. Wir könnten dies die New-Methode der Basisklasse erledigen lassen. Dann würde die Variable allerdings bei jeder Instanzerzeugung neu überschrieben. Dies ließe sich natürlich mit einer entsprechenden If-Abfrage verhindern. Aber es gibt einen eleganteren Weg. Wir nutzen das »Initialize«-Event der Bibliothek aus, die die Basisklasse enthält. Dort fügen wir die folgende Zeile ein: nHatMesser = True
Leider gibt es bei dieser Hilfskonstruktion keinerlei Möglichkeit zu verhindern, dass eine andere Methode, Funktion oder Property innerhalb der Bibliothek diese Klassenvariable überschreibt. Sie ist nur außerhalb dieser Bibliothek geschützt. Aber so viel Selbstdisziplin bringen wir doch noch auf, oder?
-
New-Methoden mit unterschiedlichen Parameterlisten in derselben Ableitungshierarchie
211
17.18 New-Methoden mit unterschiedlichen Parameterlisten in derselben Ableitungshierarchie Methoden, die von abgeleiteten Klassen überschrieben werden, müssen den gleichen Funktionskopf nutzen wie die jeweilige Basisklasse. Sonst wirft der Compiler einen Fehler aus. Dies gilt auch für die New-Methode. Dies kann aber ganz schön lästig werden, da man die komplette Parameterliste über alle über die Hierarchie verbundenen Klassen mitführen muss. Und das, obwohl manche Parameter vielleicht bereits in einer viel tiefer liegenden Vererbungsstufe gesetzt werden könnten. Als Beispiel betrachten wir noch einmal unsere Rasenmäher-Klasse. Wir stellen fest, dass Rasenmäher mit allen anderen großen beweglichen Geräten ein Fahrgestell in irgendeiner Form gemeinsam haben. Wir definieren daher eine Klasse Class Fahrgestell AnzahlRäder As Integer Sub New (in_AnzahlRäder As Integer, in_AnzahlAchsen As Integer) AnzahlRäder = in_AnzahlRäder End Sub End Class
Und Rasenmäher werden jetzt von dieser Klasse abgeleitet: Class Rasenmäher As Fahrgestell ... nSchnittbreite As Integer ... Sub New(in_Schnittbreite As Integer) IstAmLaufen = False nSchnittbreite = in_Schnittbreite End Sub ... End Class
Das Problem, das sich sofort stellt, sind die beiden unterschiedlichen Funktionsköpfe bei den New-Methoden. Die erste Lösungsmöglichkeit wäre, beide Methoden so zu erweitern, dass sie eine gemeinsame Parameterliste enthalten. Dazu müssten wir also alle Parameter der einzelnen New-Methoden in einer Ableitungshierarchie betrachten und die einfache Vereinigungsmenge aller vorkommenden Parameter für jede Methode verwenden. Die Köpfe sähen in unserem Beispiel so aus: Sub New(in_Schnittbreite As Integer, in_AnzahlRäder As Integer,_ in_AnzahlAchsen As Integer)
212
Objektorientierte Programmierung unter LotusScript
oder beispielsweise auch: Sub New(in_AnzahlRäder As Integer, in_AnzahlAchsen As Integer,_ in_Schnittbreite As Integer)
Welche Reihenfolge bei den Parametern gewählt wird ist egal, solange sie in allen zu betrachtenden New-Methoden gleich ist. Nun ist es aber nicht sehr befriedigend, für jeden Mäher immer mit angeben zu müssen, wie viele Räder er hat. Dies kann man glücklicherweise durch eine Besonderheit der New-Methode verhindern. Die zu verwendende Konstruktion lautet: Sub New(Parameterliste), NameBasisklasse(Argumentliste)
Die der Basisklasse übergebene Argumentliste stellt keine Parameter dar, sondern konkrete Werte. Sie werden an die New-Methode der Basisklasse übergeben. Wenn sie auf diese Weise an die Basisklasse übergeben werden, müssen die Anzahl und der Typ genau mit den von der Basisklasse erwarteten Merkmalen übereinstimmen. In der Liste »Parameter« werden die Parameter aufgelistet, die dieser abgeleiteten Klasse bei der Instanziierung übergeben werden sollen. Was machen wir aber, wenn die Basisklasse zwei Parameter benötigt, wir aber bei der Konstruktion einer Subklasse nur einen davon mit einem Wert füllen können? Das heißt, ein Parameter wird jetzt vorbelegt, der andere soll bei Anlage eines Objektes vom Typ der Subklasse weiterhin von außen übergeben werden. Nun, wir müssen auf jeden Fall beide Parameter der Basisklasse mit einem festen Wert belegen. Oder wir können das Ganze gleich vergessen. Also tun wir das. Zusätzlich wird der Parameter, der von außen übergeben werden soll, in der NewMethode der Subklasse wieder aufgeführt. Im Prozedurrumpf muss dafür gesorgt werden, dass die Zuweisung und/oder die Berechnungen, die die New-Methode der Basisklasse mit dem übergebenen Wert vornimmt, durch die New-Methode der Subklasse wieder mit dem von außen übergebenen Parameter überschrieben wird. Hier wirkt es sich günstig aus, dass die Private-deklarierten Eigenschaften von Basisklassen innerhalb der abgeleiteten Klassen voll zugänglich sind (anders als bei C++, wo solche Properties nur in der Basisklasse, in der sie angelegt wurden, angesprochen werden können). In unserem Beispiel sieht das wie folgt aus: Class Rasenmäher As Fahrgestell ... Sub New(in_Schnittbreite As Integer), Fahrgestell(4, 2)_ 'setzt Anzahl Räder auf 4 und Anzahl Achsen auf 2 IstAmLaufen = False nSchnittbreite = in_Schnittbreite 'setzt Schnittbreite auf 'übergebenen Parameterwert End Sub ... End Class
Benutzerdefinierte Containerklassen
213
Bei einem räderlosen Luftkissenmäher würde der Code entsprechend verändert: Class LuftkissenMäher As Fahrgestell ... Sub New(in_Schnittbreite As Integer), Fahrgestell(0, 0) 'setzt Anzahl Räder und Achsen auf 0 IstAmLaufen = False nSchnittbreite = in_Schnittbreite End Sub ... End Class
Wenn wir jetzt ein Objekt instantiieren (z. B. einen Luftkissenmäher), dann brauchen wir nur noch die Schnittbreite zu übergeben. Die Anzahl der Räder »berechnet« die entsprechende Klasse schon selbsttätig. Dim oMäher1 As New LuftkissenMäher(40) Dim oMäher2 As New RasenMäher(40)
Wenn Sie die Sache im Debugger überprüfen, werden Sie feststellen, dass oMäher1 null (0) Räder aufweist, oMäher2 hingegen vier (4).
17.19 Benutzerdefinierte Containerklassen Containerklassen zeichnen sich dadurch aus, dass sie eine unbestimmte Menge anderer Objekte beinhalten können. Im Allgemeinen bieten sie Methoden an, die einen Zugriff auf diese Objekte ermöglichen. Es stellt sich die Frage, wie die beinhalteten Objekte »aufbewahrt« und referenziert werden können. Dies werden die folgenden Beispiele deutlich machen. Eine Containerklasse ist eine Klasse, die auf eine unbestimmte Menge Instanzen (Objekte) anderer Klassen Zugriff hat. Da wir unsere Objekte letztlich dazu nutzen wollen, um einen Rasen »programmtechnisch« zu stutzen, benötigen wir noch ein Rasen-Objekt. Dieses Rasen-Objekt wird eine benutzerdefinierte Containerklasse sein. Wie kann der Rasen im Computer aussehen? Nun, ein Rasen besteht naturgemäß aus vielen Grashalmen. Daher definieren wir zunächst die Klasse Grashalm: Class Grashalm Public Höhe As Integer Breite As Integer Sub New(in_AktuelleHöhe As Integer) Höhe = in_AktuelleHöhe Breite = 1 End Sub
214
Objektorientierte Programmierung unter LotusScript
Sub Wachsen(in_GewachseneLänge As Integer) Höhe = Höhe + in_GewachseneLänge End Sub End Class
Wir tun einmal so, als wären alle Grashalme dieser Welt gleich breit (= 1). Um das Schützen der Eigenschaftsvariablen Höhe und Breite machen wir uns an dieser Stelle nicht so viele Sorgen. Wenn Sie einen solchen Schutz vor ungewollten Zugriffen brauchen, dann wissen Sie ja schon, wie Sie ihn errichten können (Property usw.). Nun benötigen wir noch das Rasenobjekt. Dieses wird im Wesentlichen aus vielen Grashalmen bestehen. Beispielsweise so: Class Rasenstück Länge As Integer Breite As Integer Public Grashalme List As Grashalm
'Diese Liste macht das 'Rasenstück 'zur Containerklasse
Sub New(in_Länge As Single, in_Breite As Single, _ in_Grashalme List As Grashalm) Höhe = in_Länge Breite = in_Breite Erase in_Grashalme Forall x In in_Grashalme Set Grashalme(Listtag(x)) = x End Forall End Sub Sub Schneiden(in_SchnittHöhe As Integer) Forall halm in Grashalme halm.Höhe = in_SchnittHöhe End Forall End Sub End Class
Der interessante neue Aspekt an dieser Klasse ist in der Eigenschaftsvariablen »Grashalme« begründet. Da in dieser Liste einzelne Objekte vom Typ Grashalm abgelegt werden können, haben wir der Klasse Rasenstück auf diese Weise Unterobjekte zugeordnet. Man nennt diese Beziehung zwischen einem Ober- und einem Unterobjekt auch eine »Hat-Beziehung«. Das Oberobjekt vom Typ Rasenstück hat also einige Unterobjekte vom Typ Grashalm. Dass wir hier eine Script-Liste gewählt haben, liegt nur daran, dass wir einen Container für viele Unterobjekte benötigen. Man sagt auch, es handelt sich um eine 1:n-Beziehung. Bei einer 1:1-Beziehung hätte auch eine einfache Objektvariable statt der Liste ausgereicht.
Benutzerdefinierte Containerklassen
215
Objekte können in unterschiedlicher Hat-Beziehung zu anderen Objekten stehen. So gibt es beispielsweise die 1:n-Beziehung und die 1:1-Beziehung. In diesem Fall wird die Liste der Grashalme durch die New-Methode gefüllt. Man hätte genauso gut eine Methode »AddGrashalm« wählen können, die dann nach der Objektinstanziierung die Grashalme einzeln übernommen hätte. Daher hierzu ein kurzes Codestück: Class Rasenstück ... Public Grashalme List As Grashalm Zähler As Long Sub New (in_Länge As Single, in_Breite As Single) Höhe = in_Länge Breite = in_Breite End Sub Sub AddGrashalm(in_Grashalm As Grashalm) Zähler = Zähler + 1 Set Grashalme(Zähler) = in_Grashalm End Sub ... End Class
Der Einsatz des Zählers dient der Unterscheidung der einzelnen Listenelemente. Leider arbeitet dieser Container, der von LotusScript zur Verfügung gestellt wird, nicht ohne solche »Listtags«. Wollen Sie eine namenlose Speicherung erreichen, so müssen Sie selbst eine entsprechende Datenstruktur bauen, z. B. einen Heap. Wie man solche Strukturen in LotusScript verwirklichen kann, betrachten wir etwas später. Als Listtag werden normalerweise Stringwerte verlangt. Allerdings können auch Zahlenwerte übergeben werden, da diese implizit in Strings umgewandelt werden. Analog haben Container-Klassen im Allgemeinen weitere Standard-Methoden wie »DeleteObject«, »GetObject«. Auch eine Property »HasObject« kann sehr nützlich sein. Wenn man Container-Klassen baut (also Klassen, deren Objekte eine Anzahl anderer Objekte aufnehmen können), so ist es i. A. zu empfehlen, solche StandardMethoden von vornherein vorzusehen. Man wird sie nicht immer im ersten Moment benötigen. Aber irgendwann wird man sie dann doch vermissen. Hier zeigt sich wieder, dass Klassen bzw. Objekte vor Erstellung eines damit arbeitenden Programmes zunächst getrennt betrachtet und hinsichtlich ihrer Objekteigenschaften komplettiert werden sollten.
216
Objektorientierte Programmierung unter LotusScript
Containerklassen stellen i. A. Standardmethoden zur Verfügung, die einen gezielten Zugriff auf die beinhalteten Objekte ermöglichen. Solche Methoden heißen beispielsweise GetObject, DeleteObject, AddObject, GetFirstObject, GetNextObject usw. Object ist hier als ein Platzhalter für den Namen des Typs der tatsächlich beinhalteten Objekte zu sehen. Eine Oberklasse kann auf ihre Unterklassen und deren Eigenschaften und Methoden zugreifen. Dies gilt allerdings nur für die Eigenschaften und Methoden, die Public deklariert sind (egal ob implizit oder explizit). Demgegenüber kann eine abgeleitete Klasse auf alle Eigenschaften und Methoden von Superklassen zugreifen. Dies gilt also selbst für Private deklarierte Elemente. Eine Subklasse (abgeleitete Klasse) kann in LotusSript auch auf die privaten Elemente einer Superklasse (= Oberklasse oder Basisklasse) zugreifen. Dies ist bei lediglich in irgendeiner Hat-Beziehung stehenden Objekten nicht möglich. Zum Schluss dieses Abschnitts optimieren wir unsere Klasse Rasenstück noch ein wenig. Denn die einzelnen Grashalme interessieren uns nur wenig. Wir erwarten, dass ein Rasenstück seine Grashalme selbst kennt und verwaltet. Lediglich die Menge an Grashalmen, die so ein Stück beinhaltet, wollen wir noch vorgeben können: Class Rasenstück Länge As Integer Breite As Integer Public Grashalme List As Grashalm
'Diese Liste macht das 'Rasenstück 'zur Containerklasse
Sub New(in_Länge As Single, in_Breite As Single, _ nMenge As Long, nHöhe As Integer) Dim i% Höhe = in_Länge Breite = in_Breite For i% = 1 To nMenge Dim oHalm As New Grashalm(nHöhe) Set Grashalme(i%) = oHalm Next End Sub Function Höhe ... End Function ... End Class
Ein Rasenmäher in Aktion
217
17.20 Ein Rasenmäher in Aktion Um ein Stück Rasen zu mähen, benötigen wir einen Gärtner, einen Mäher und den zu schneidenden Rasen. Da wir im metrischen System bleiben wollen, entscheiden wir uns für einen bayrischen Gärtner: Dim oGärtner As New BayerischerGärtner oGärtner.Schrittgeschwindigkeit = 2 Dim oMäher As New Elektromäher(50) oMäher.Schnitthöhe = 3
'2 km/h 'Schnittbreite 50 cm '3 cm
Den Rasen vereinfachen wir ein wenig. Wir gehen davon aus, dass er sehr schmal und dafür lang ist. Er bestehe aus lauter hintereinander gelegten Stücken, die einen Meter lang und genauso breit sind, wie die Schnittbreite des Mähers. Auf diese Weise kann sich der Gärtner eindimensional fortbewegen. Da wir nur das Prinzip zeigen möchten, erhält jedes Rasenstück auch nur einen einzigen Grashalm. Der Rasen sei genau 1000 m lang (wie gut, dass wir diese Arbeit dem elektronischen Gärtner überlassen können). Außerdem bauen wir noch eine Funktion ein, die uns gestattet, die Länge einer bestimmten Stelle im Rasen zu prüfen. Damit können wir feststellen, wo bereits gemäht wurde und wo noch nicht: Class Rasen Public Stücke List As Rasenstück Position As Long Sub AddStück (oStück As Rasenstück) Position = Position + 1 Set Stücke(Position) = oStück End Sub Function GetHöhe(nPosition as Long) Dim oStück AS Rasenstück Set oStück = Stücke(nPosition) GetHöhe = oStück.Höhe End Function End Class Dim oRasen As New Rasen For i% = 0 To 999 'Erzeuge Stücke von 1 m Länge, 0,5 m Breite, mit 'je 100 Grashalmen und 10 cm Höhe Dim oStück As New Rasenstück(1, 0.5, 100, 10) Call oRasen.AddStück(oStück) Next
Der Gärtner mäht eine Viertelstunde, bevor er eine kurze Pause einlegt: Call oGärtner.Mähen(oRasen, oMäher, 0.25)
218
Objektorientierte Programmierung unter LotusScript
Die Methode Mähen hatten wir noch nicht definiert. Da alle Gärtner in der Lage sind, Rasen zu schneiden, definieren wir sie zweckmäßigerweise in der Basisklasse Gärtner. Wir möchten aus Vereinfachungsgründen eine Funktion haben, die einen Rasen jeweils bei Position 0 zu mähen beginnt, und die Strecke kürzt, die seiner Schrittgeschwindigkeit und der Mähdauer entspricht: Class Gärtner ... Sub Mähen(oRasen As Rasen, oMäher As Rasenmäher, _ nDauer As Single) 'Mähstrecke in m bestimmen (= Anzahl der Rasenstücke) Dim nMähStrecke As Long nMähStrecke = nDauer * Schrittgeschwindigkeit * 1000 If Not oMäher.IstAmLaufen Then _ Error nERR_MÄHER_PROBLEM, "Mäher läuft nicht" Dim i% For i% = 1 To nMähStrecke oMäher.Schneiden oRasen.Stücke(i%) Next End Sub ... End Class
Wie hoch ist jetzt der Rasen auf dem ersten Stück? Auf dem Abschnitt an Position 500 (499 - 500 m)? Und wie hoch an der Position 501 (500 m – 501 m)? MessageBox oRasen.GetLänge(1) MessageBox oRasen.GetLänge(500) MessageBox oRasen.GetLänge(501)
Die Ausgaben lauten: 3, 3, 10 Wir sehen, wie selbst komplexe Abläufe unter OOP starkt vereinfacht werden können. Vor allem hat man die Abläufe i. A. viel besser im Griff, weil Objekte in einem guten Design häufig eine konkrete Anschauung vermitteln, wie sie arbeiten. Im Umgang mit ihnen hat man nur mit deren unmittelbaren Funktionalitäten zu tun. Wie das Objekt die jeweilige Funktionalität bewerkstelligt, mit welchen weiteren Objekten es dazu in anderen Ebenen kommunizieren muss und welche Reaktionen darauf erfolgen, interessiert den Entwickler dann kaum noch. Er verlässt sich darauf, dass jedes Objekt »weiss«, wie es die angebotene Funktionalität (Methode) umzusetzen hat. Natürlich läuft bei einer funktionalen Analyse und Programmierung letztlich das Gleiche ab. Allerdings ist der Aufbau solcher Programme wesentlich komplexer. Es ist kaum möglich, auf höhere Ebenen zu abstrahieren, die dennoch stark anschaulichen Charakter haben und einen so einfachen und intuitiven Umgang mit den zusammenwirkenden Programmteilen ermöglichen.
Virtuelle Funktionen und Mächtigkeit von LotusScript contra C++ u. a.
219
17.21 Virtuelle Funktionen und Mächtigkeit von LotusScript contra C++ u. a. Ein wichtiges Argument von Gegnern der OOP unter LotusScript ist: »LotusScript bietet keine virtuellen Funktionen. Also ist LotusScript nicht objektorientiert.« Selbst wenn es das Konzept der virtuellen Funktionen nicht gäbe, so wäre LotusScript gleichwohl objektorientiert. Den Beweis dafür haben wir in diesem Kapitel bereits zur Genüge erbracht, denn wir haben vielerlei Objekte erzeugt. Dabei haben wir ausgiebig vom Mechanismus der Vererbung Gebrauch gemacht. Die Frage kann daher höchstens sein: Hat LotusScript die gleiche Mächtigkeit wie C++ und andere objektorientierte Sprachen, was die Werkzeuge für die OOP betrifft? Und hier können wir klar sagen: Dies hat LotusScript nicht! Wozu auch? LotusScript und C++ haben einen sehr unterschiedlichen Anspruch zu erfüllen. C++ bietet sehr ausgefeilte Programmiertechniken für alle möglichen Anwendungsgebiete. Dadurch ist C++ auch nicht ganz einfach zu erlernen, was jeder Anfänger bestätigen wird. Im Gegensatz dazu ist LotusScript im Notes-Kontext in erster Linie dazu gedacht, Notes-Anwendungen schnell und einfach programmieren zu können. Und das kann man! Dabei wird der Entwickler vor den vielen Fehlern, denen er in C++ aufgrund der umfangreichen Möglichkeiten zur Zeigermanipulation immer wieder begegnet, von vornherein bewahrt. Wem die Möglichkeiten von LotusScript dennoch nicht genügen, der kann ohne weiteres die Möglichkeiten von C++ über die API-Programmierung ausnutzen. Hier können wir mittels C++-API und auch C-API viele Dinge erreichen, die unter LotusScript definitiv nicht möglich sind. Beispielsweise das Schreiben von Server-Tasks, Abfangen des Notes-Login-Prompts usw. Mit der API erzeugte Funktionalitäten lassen sich dann sogar in LotusScript einbinden. Eine weitere mächtige Möglichkeit ist die Programmierung von LSX-Klassen. Mit dem LSX-Toolkit von Notes lassen sich mittels C/C++-API Klassen konstruieren, die dann über die LSX-Schnittstelle vollständig in LotusScript eingebunden werden können. Sie erscheinen dort wie Domino-Klassen. Kein Wunder; schließlich bedienen sich Domino-Klassen selbst des LSX-Mechanismus. LotusScript bietet durch diese zahlreichen Schnittstellen viele Möglichkeiten, die Stärken der verschiedenen Sprachen gezielt auszunutzen. Zudem kann man spätestens ab Notes R 5 auf die ebenfalls mögliche Java-Programmierung umsteigen. Allerdings muss man einschränkend sagen, dass sich nur Teile von Notes über Java ansprechen und programmieren lassen. Genauso wie LotusScript nach wie vor nicht in allen Designelementen von Notes verwendet werden kann (z. B. Spaltenformeln von Ansichten). Wie ist es nun mit den virtuellen Funktionen? Gibt es sie oder gibt es sie nicht? Es gibt sie! Allerdings nur implizit. Und man kann über sie auch keine rein abstrakten Klassen erzeugen, wie dies unter C++ der Fall ist. Aber wenn man virtuelle Funktionen zunächst mal hauptsächlich unter dem Aspekt des Polymorphismus betrachtet, dann gibt es auch unter LotusScript virtuelle Funktionen.
220
Objektorientierte Programmierung unter LotusScript
Es gibt in LotusScript keine virtuellen Funktionen im strengen Sinne. Insbesondere lassen sich dadurch auch keine rein abstrakten Klassen implementieren. Allerdings lassen sich in Hinblick auf den Polymorphismus auch in LotusScript Methoden implementieren, die sich wie virtuelle Funktionen verhalten.
17.22 Polymorphismus Polymorphismus ist die Fähigkeit, den Typ eines Objektes zur Laufzeit dynamisch zu erkennen. Und zwar, ohne dass der Programmierer ein spezielles Typkennzeichen setzt. Der Nutzen des Polymorphismus liegt darin, dass zur Laufzeit die dem speziellen Objekt zugeordnete Methode oder Eigenschaft angesprochen wird. Der Polymorphismus baut auf das Konzept der virtuellen Funktionen auf. Um diesen Sachverhalt besser zu verstehen, betrachten wir wieder ein Beispiel. Wir stellen uns vor, jemand übergibt uns ein Objekt, das in irgendeiner Weise einen Rasenmäher darstellt. Wir wissen aber nicht, was für ein Rasenmäher es ist. Wir möchten dies ohne genaueres Hinsehen erfahren können. Dazu bauen wir unsere Rasenmäher-Klassen so um, dass sie den Polymorphismus unterstützen. Zunächst nehmen wir eine entsprechende Änderung an der Klasse Rasenmäher vor: Class Rasenmäher As Fahrgestell ... Sub Print Print "Ich bin ein Rasenmäher." End Sub ... End Class Class Elektromäher As Rasenmäher HatStrom As Integer IstKabelAnStrom As Integer Property Get IstKabelGebrochen As Integer IstKabelGebrochen = _ (IstKabelAnStrom And Not HatStrom) End Property ... Sub Print Print "Ich bin ein Elektromäher."
Polymorphismus
221
If IstKabelGebrochen Then Print "Mein Kabel ist gebrochen." Else Print "Mein Kabel ist OK." End If End Sub ... End Class Class LuftkissenMäher As Fahrgestell ... Sub Print Print "Ich bin ein Luftkissenmäher." End Sub ... End Class
Anschließend schreiben wir in einem Agenten oder auch in einem Button einer Maske eine Funktion, die ein Rasenmäher-Objekt übernehmen kann. Sie soll die Print-Funktion des Rasenmäher-Objektes anstoßen: Sub AnalysiereRasenmäher(oMäher As Rasenmäher) oMäher.Print End Sub
Was wird nun passieren? Angenommen wir übergeben ein Objekt vom Typ Rasenmäher, dann wird die Analysefunktion den Text »Ich bin ein Rasenmäher« auswerfen. Übergeben wir dagegen ein Objekt vom Typ Elektromäher, so wird die Botschaft sein: »Ich bin ein Elektromäher.« Und falls es zutrifft, wird auch noch die folgende Meldung hinterhergeschoben: »Mein Kabel ist gebrochen.« Analog wirft die Analysefunktion für einen Luftkissenmäher die Nachricht »Ich bin ein Luftkissenmäher.« aus. Diese Erscheinung ist der beschriebene Polymorphismus. Ohne dass wir uns irgendwelche Gedanken machen mussten, hat der Compiler selbst erkannt, welches Objekt der Funktion übergeben wurde, und er hat die zugehörige Print-Funktion angestoßen.
222
Objektorientierte Programmierung unter LotusScript
Die Print-Funktion der Basisklasse, in der sie das erste Mal deklariert wurde, ist somit eine virtuelle Funktion, ohne dass dies explizit angegeben werden muss. Dafür gibt es in LotusScript auch kein Schlüsselwort. Polymorphismus ist die Fähigkeit, beim Aufruf einer Objektmethode zu unterscheiden, zu welcher Hierarchiestufe das übergebene Objekt in einer Vererbungshierarchie gehört und die dazu passende Methode aufzurufen.
17.22.1 Variantvariablen für Pseudopolymorphismus Wir könnten den gleichen Effekt wie im letzten Abschnitt erzielen, indem wir den Funktionskopf der AnalysiereRasenmäher-Funktion leicht ändern: Sub AnalysiereRasenmäher(vMäher As Variant) vMäher.Print End Sub
Der kleine Unterschied ist, dass hier als Parameter kein Objekt vom Typ Rasenmäher spezifiziert wurde. Stattdessen lässt der Variant alle möglichen Argumente zu. Dies ist allerdings recht gefährlich, da zur Compilierzeit nicht erkannt werden kann, ob der Aufruf vMäher.Print überhaupt möglich ist. Wählen Sie eine solche Konstruktion, so kann es sein, dass Sie erst zur Laufzeit durch eine Meldung erfahren, dass Sie gerade versuchen, auf eine nicht existente Methode zuzugreifen. Vorteile hat der Einsatz einer Variantvariablen, wenn Sie unterschiedliche Objekte übergeben möchten, die nicht von einer gemeinsamen Basisklasse abgeleitet sind. Dann lässt sich der Mechanismus des Polymorphismus nicht nutzen, auch wenn sie beide Methoden mit gleichem Namen anbieten. Wenn Sie also beispielsweise noch eine Klasse Baum definieren, die ebenfalls eine Methode Print aufweist, dann können Sie auch diese einer Prozedur AnalysiereObjekt übergeben, ohne dass die Klassen eine gemeinsame Basisklasse benötigen würden: Class Baum Sub Print Print "Ich bin ein Baum." End Sub End Class Sub AnalysiereObjekt(vObjekt As Variant) vObjekt.Print End Sub
Man kann Variant-Variablen einsetzen, um auf namensgleiche Methoden unterschiedlicher Objekte mit dem gleichen Codestück zugreifen zu können, ohne dass die automatische Typprüfung des Compilers eine Fehlermeldung generiert. Man sollte sich aber der Gefahren der daduch unterlaufenen Typprüfung bewusst sein.
Datenstrukturen unter LotusScript
223
17.23 Datenstrukturen unter LotusScript Etwas weiter oben haben wir angekündigt, dass noch gezeigt wird, wie man unter LotusScript Datenstrukturen wie binäre Bäume, verkettete Listen, Heaps usw. erstellen kann. Motivation Sie werden vermutlich nicht gleich am Anfang vor die Herausforderung gestellt, eigene Datenstrukturen in LotusScript entwerfen zu müssen. Allerdings entstehen zurzeit viele Notes-Anwendungen, die verschiedene Schnittstellen zu anderen Systemen unterhalten müssen. Wenn vor der Übergabe die Daten zunächst in Notes zusammengesucht werden müssen, kann es sein, dass Sie diese gerne in entsprechenden möglichst performant arbeitenden Strukturen ablegen möchten. Oder Sie möchten gewisse Sortierungen vornehmen, ohne dass Sie dabei auf Ansichten zurückgreifen können. Dann benötigen Sie zum Aufbau einer schnellen Sortierfunktion die zum Algorithmus passenden Datenstrukturen. Ein dritter Fall, der sich zum Gebrauch eigener Datenstrukturen anbietet, ist der Wunsch, Werte in einer Struktur abspeichern zu können, ohne dazu irgendein Unterscheidungskriterium angeben zu müssen, wie Sie es bei einer LotusScriptListe tun müssten. Spätestens zu einer solchen Zeit werden Sie dieses Kapitel wieder zu Rate ziehen wollen. Und es ist gut, schon im Vorfeld die Möglichkeiten, die LotusScript zu diesem Thema bietet, zu kennen. Die Kernfrage Der wesentliche Aspekt, der geklärt werden muss, um eigene Datenstrukturen zu erzeugen, ist: Wie kann man in LotusScript Objekte (per Zeiger) miteinander verketten? Nun, Zeiger werden unter LotusScript durch Objektreferenzen bzw. Objektvariablen repräsentiert. Zudem lassen sich Objekte rekursiv definieren. Das heißt, man kann innerhalb des Gültigkeitsbereichs von Klassen dieselben Klassen verwenden. Verschiedene Datenstrukturen Verkettete Liste Ein Element einer einfach verketteten Liste ließe sich beispielsweise so definieren: Class ListElement Public Nachfolger As ListElement Public Value As Variant End Class
224
Objektorientierte Programmierung unter LotusScript
Die Eigenschaft Nachfolger speichert die Referenz auf das Nachfolgeelement, die Variable Wert den Wert des Listenelements. Die Operationen auf dieser Struktur können entweder als Funktionen und Prozeduren in das gleiche Modul wie die Klassendefinition gelegt werden (also zum Beispiel in die gleiche Script-Bibliothek). Oder Sie legen eine weitere Klasse an, die die Datenstruktur an sich repräsentiert und die einerseits die Listenelemente referenziert und andererseits die Operationen auf der Struktur als ihre Methoden anbietet. Dieses ist der elegantere Weg und wir wollen ihn kurz demonstrieren. Um dem Beispiel etwas mehr Praxisbezug zu geben, demonstrieren wir es gleich bei einer anderen Datenstruktur, die sich in diesem Fall einer Liste bedienen soll, und zwar konstruieren wir einen Stack (Keller). 1. Stack (LIFO-Struktur) Class Stack Private Ende As ListElement Function IstLeer As Integer If Ende Is Nothing Then IstLeer = True End Function Sub Push(vValue As Variant) Dim oElement As New ListElement If IsObject(vValue) then Set oElement.Value = vValue Else oElement.Value = vValue End If End Sub Sub Pop If Not IstLeer Then Dim oEnde As ListElement Set oEnde = Ende Set Ende = oEnde.Nachfolger Delete oEnde End If End Sub Function Top As Variant If IsObject(Ende.Value) then Set Top = vValue Else Top = vValue End If End Function End Class
Praktisches Beispiel für Objekte aus dem Kontaktmanagement
225
Dieser Stack verfügt über alle Methoden, die ein Stack benötigt. Die im Stack gespeicherten Werte werden in einer verketteten Liste aufbewahrt. Da wir im Stack immer nur auf das Ende der Liste zugreifen müssen, wird dieses Ende über die Eigenschaftsvariable Ende »festgehalten«, also referenziert. Dadurch, dass wir zur Aufnahme der zu speichernden Werte in den Listenelementen einen Variant gewählt haben, sind wir in der Lage, sehr unterschiedliche Arten von Werten in dem Stack abzulegen: skalare Werte, Arrays, Objekte, LotusScriptListen usw. Weitere Datenstrukturen Die bisher behandelten Beipiele müssten ausreichen, um
Ihnen einen Einblick zu gewähren, wie Sie unter LotusScript Datenstrukturen erzeugen können. Ideen für weitere Strukturen können Sie der einschlägigen Literatur entnehmen, zum Beispiel dem Klassiker »Algorithmen in C« von R. Sedgewick aus dem Addison-Wesley-Verlag, oder auch der für C++ angepassten Version »Algorithmen in C++«.
17.24 Praktisches Beispiel für Objekte aus dem Kontaktmanagement Anschauliche Objekte aus dem Kontaktmanagement sind zum Beispiel die Personen und die Kontakte zu diesen Personen. Es bietet sich an, eine Klasse Person zu definieren, die die Adressdaten aufnimmt und auf eine Liste aller Kontakte verweist. Die Kontakte selbst werden auch als Objekte modelliert. Mit Hilfe dieser beiden Klassen könnten wir beispielsweise mehrere Personen mit deren Kontakten komfortabel im Arbeitsspeicher halten und komfortabel darauf zugreifen, ohne dass wir die Kontakte jedesmal wieder über eine Ansicht suchen müssten. (Die Suche über eine Ansicht ist zwar schon recht schnell, aber die Referenzierung innerhalb des Objektes kann noch schneller sein.) Der Hauptnutzen ist aber, dass die Daten in übersichtlichen und anschaulichen Strukturen bearbeitet werden können. Wir konstruieren zunächst die Klasse Kontakt: Class Kontakt Public Public Public Public Public Public End Class
Zeitpunkt As Variant Thema As String Kontaktart As String Ergebnis As String NächsteAktion As String NächsterZeitpunkt As String
Dann kümmern wir uns um die Klasse Person: Class Person Nachname As String Vorname As String
226
Objektorientierte Programmierung unter LotusScript
Titel As String Strasse As String PLZ As String Ort As String Firma As String Kontakte List As Kontakt Sub AddKontakt(oKontakt As NotesDocument) ... End Sub End Class
In der Eigenschaftsvariablen Kontakte werden alle Kontakte zur Person abgespeichert. Der Listtag zu einem Kontakt könnte beispielweise eine Kombination aus Namen des Kontaktierten, Datum und Art des Kontakts sein. Da die Kontakte schon über die Hat-Beziehung der Person des Kontaktierten zugeordnet werden, genügt als Schlüssel die Kombination Datum und Kontaktart: Sub AddKontakt(oKontNote As NotesDocument) 'In der Realität müsste hier zunächst geprüft werden, 'ob es sich bei dem Dokument wirklich um einen Kontakt 'handelt. Lassen wir als für unser Beispiel unwesentlich 'weg. 'Schlüssel bilden Dim sKey As String sKey = oKontNote.Zeitpunkt(0) & "," & _ oKontNote.KontaktArt(0) 'Kontaktobjekt anlegen Dim oKontakt As New Kontakt oKontakt.Zeitpunkt = oKontNote.Zeitpunkt oKontakt.Thema = oKontNote.Thema oKontakt.Kontaktart = oKontNote.KontaktArt oKontakt.Ergebnis = oKontNote.Ergebnis oKontakt.NächsteAktion = oKontNote.NächstAktion oKontakt.NächsterZeitpunkt = oKontNote.NächsterZeitpunkt 'Der internen Liste hinzufügen Set Kontakte(sKey) = oKontakt End Sub
Allerdings ist auch diese Schlüssel-Kombination nicht unbedingt eindeutig und so wird man sich eher für einen anderen Schlüssel entscheiden, wahrscheinlich einen numerischen Schlüssel, der in der relationalen Datenbank gepflegt und in den Notes-Dokumenten hinterlegt wird. Bis jetzt besteht der Hauptnutzen der beiden Klassen darin, dass wir zusammengehörige Daten übersichtlich strukturiert verwalten können. Da mag man noch
Praktisches Beispiel für Objekte aus dem Kontaktmanagement
227
sagen: Das kann ich auch anders lösen, zum Beispiel mit Hilfe von benutzerdefinierten Datentypen. Allerdings wird es jetzt noch einmal richtig spannend. Angenommen, Sie möchten dafür sorgen, dass die Richtigkeit der Daten über Script geprüft wird. Also, die über die einzelnen Felder einer Notes-Maske verstreuten Validierungsformeln sagen Ihnen nicht so recht zu. Sie möchten es übersichtlich und bequem haben. Kein Problem! Konstruieren Sie eine Validierungsklasse: Class Validierung Function Text(sText As String, nMaxLänge As Long) As Integer Text = (Len(sText) <= nMaxLänge) End Function ... End Class
Und was hilft uns das jetzt? Ganz einfach: Um die soeben geschriebene Validierungsfunktion in allen zu prüfenden Objekten verfügbar zu machen, machen wir die Klasse Validierung ganz einfach zur Basisklasse aller zu prüfenden Klassen. Dann stehen alle in der Klasse Validierung definierten Funktionen in allen abgeleiteten Klassen zur Verfügung! Schön, nicht wahr? Class Kontakt As Validierung Zeitpunkt As Variant Thema As String Kontaktart As String Ergebnis As String NächsteAktion As String NächsterZeitpunkt As String Function Validierung As Integer If Not Text(Thema, 100) Then _ Print "Thema zu lang. Bitte auf 100" & _ " Zeichen beschränken." If Not Text(Kontaktart, 20) Then _ Print "Kontaktart zu lang. Bitte auf 20" & _ " Zeichen beschränken." If Not Text(Ergebnis, 20) Then _ Print "Ergebnis zu lang. Bitte auf 20" & _ " Zeichen beschränken." ... End Function End Class
228
Objektorientierte Programmierung unter LotusScript
Natürlich können Sie diese Prüffunktionen auch in einer Bibliothek hinterlegen und durch die Use-Direktive in anderen Modulen verfügbar machen. Allerdings können Sie dann diese Funktionen nicht gezielt in bestimmte Objekte vererben und in anderen je nach Notwendigkeit überschreiben. Auch können Sie solche angepassten Funktionen nicht weitervererben, sondern Sie müssten dann jeder abgewandelten Form der Prüfung einen neuen Namen geben. In der Praxis werden Sie dann entweder Prüffunktionen mit einer immer weiter wachsenden Liste an Parametern zur Einstellung aller Eventualitäten erhalten oder aber eine immer größer werdende Anzahl von einander sehr ähnlichen, aber mit speziellen Ausprägungen versehenen Funktionen erhalten. Bei größeren Anwendungen wird dann der Überblick sehr schnell verloren gehen. Außerdem besteht dann keine Bindung zwischen den einzelnen Ausprägungen der Prüffunktionen und den Daten, zu denen sie gehören. Unter solchen Umständen erweist sich das OOD bzw. die OOP als eine wirklich geniale Vereinfachung. Unsere abschließende Empfehlung: Lassen Sie sich nicht von anfänglichen Schwierigkeiten im Verständnis der OOP abschrecken. Und für die Leser, die schon mächtigere objektorientierte Sprachen kennen gelernt haben: Nutzen Sie die OOP auch unter LotusScript. Es wird Sie ein wenig frustrieren, dass Sie manche Möglichkeiten, die Sie aus diesen anderen Sprachen kennen, hier nicht zur Verfügung haben. Lassen Sie sich dennoch nicht davon abhalten, Ihr klares Verständnis für eine gute OOP auch in LotusScript nutzbringend zu verwenden. Es lohnt sich aufgrund des übersichtlicheren Designs und der daraus resultierenden besseren Wartbarkeit und Erweiterbarkeit allemal, zumindest in größeren Anwendungssystemen.
17.25 Fragen 1. Wie würden Sie die wesentlichen Unterschiede zwischen der Funktionalen und der Objektorientierten Analyse einer Problemstellung im Bereich Softwareentwicklung beschreiben? 2. Was ist eine Klasse? 3. Was ist ein Objekt? 4. Wie unterscheiden sich Objekte von Klasen? 5. Wie erzeugt man in LotusScript eine Klasse? 6. Wie erzeugt man in LotusScript ein Objekt? 7. Was sind Eigenschaften und Methoden? Wie werden sie in LotusScript dargestellt? 8. Was verstehen Sie unter Vererbung? Wozu kann sie gebraucht werden? 9. Wie wird die Vererbung in LotusScript codiert? 10. Was verstehen Sie unter Polymorphismus? 11. Können Sie in LotusScript Polymorphismus einsetzen? Wenn ja, wie? 12. Was ist eine virtuelle Funktion? Gibt es diese Konstruktion in LotusScript? Wenn ja, in welcher Form und mit welchen Einschränkungen?
Fragen
229
13. Wie können Sie unter LotusScript eigene Datenstrukturen schaffen, wie z. B. einen Heap oder einen Stack? 14. Was ist eine Containerklasse und wie würden Sie eine solche implementieren? 15. Welche Standardmethoden werden von Containerklassen häufig zur Verfügung gestellt? 16. Wie würden Sie den Nutzen eines Objektorientierten Designs gegenüber dem Funktionalen Design beschreiben? 17. Wie beurteilen Sie die Möglichkeiten einer OOP unter LotusScript im Unterschied zu anderen objektorientierten Sprachen, die Sie kennen, wie z. B. C++?
18 18
Domino-Klassen
18.1 Überblick Der komfortable Zugriff auf die Elemente einer Lotus Notes-Anwendung
X X X
Domino-Klassen bieten eine komfortable Möglichkeit, auf die wesentlichen Elemente einer Domino-Anwendung zuzugreifen. Sie sind gut strukturiert und lassen sich daher recht einfach erlernen. Domino-Klassen teilen sich zunächst in Frontend- und Backend-Klassen auf. Erstere werden auch als UI-Klassen bezeichnet. Sie sind durch das »UI« innerhalb ihres Namens gekennzeichnet. Ein User im Serverkontext hat nur auf die Backend-Klassen Zugriff. Das wird auch dadurch deutlich, dass periodische Agenten, die ja im Server-Kontext ablaufen, nicht starten, wenn in ihrem Code eine Bezugnahme auf eine UI-Klasse enthalten ist.
Ba cke n d -Kl ass sse en Klasse
Beschreibung
NotesACL
Bietet Zugriff auf die ACL (Zugriffskontrollliste) einer Notes-Datenbank
NotesACLEntry
Einzelner Eintrag einer Datenbank-ACL
NotesAgent
Notes-Agent
NotesDatabase
Notes-Datenbank
NotesDateRange
Eine Zeitspanne (kann Tages- und Zeitdifferenz umfassen)
NotesDateTime
Repräsentiert ein Zeitobjekt. Dient darüber hinaus der Konvertierung zwischen dem LotusScript- und dem Domino-Zeitformat.
NotesDbDirectory
Eine Aufzählung aller Domino-Datenbanken auf einem Server oder einem lokalen Rechner.
NotesDocument
Notes-Dokument
NotesDocumentCollection
Aufzählung von Notes-Dokumenten einer Datenbank.
NotesEmbeddedObject
Repräsentiert ein eingebettetes Objekt, eine NotesVerknüpfung oder einen Datei-Anhang.
NotesForm
Notes-Maske
NotesInternational
Internationale Einstellungen des Betriebssystems
232
Domino-Klassen
Klasse
Beschreibung
NotesItem
Ein Datenfragment in einem Notes-Dokument. Wenn das Dokument durch eine Maske erzeugt oder angezeigt wird, entspricht es dem Inhalt eines berechneten oder bearbeitbaren Maskenfeldes.
NotesLog
Dient dem Erstellen von Logging-Informationen.
NotesName
User- oder Servername. Dient bei hierarchischen Namen der Konvertierung zwischen verschiedenen Formaten.
NotesNewsLetter
Zusammenfassung von Notes-Dokumenten. Diese Zusammenfassung kann auf einfache Weise in einem anderen Notes-Dokument sichtbar gemacht werden.
NotesOutline
Notes-Gliederung (R5)
NotesOutlineEntry
Verzeichniseintrag (R5)
NotesRegistration
Dient der Registrierung von Notes-Ids (R4.6)
NotesReplication
Replikationseinstellungen einer Domino-Datenbank (R5)
NotesRichTextTab
Eigenschaften eines Tabstops in einem Richtext-Item
NotesRichTextItem
Notes-Item vom Typ RichText
NotesRichTextParagraph-Style
Stil-Eigenschaften eines Abschnitts in einem RichtextItem
NotesRichTextStyle
Stil eines Richtext-Items
NotesSession
Notes-Arbeitssitzung. Enthält den Kontext, in dem das Script abläuft, die internationalen Einstellungen des Betriebssystems und weitere Informationen über die aktuelle Sitzung. Erlaubt außerdem den Zugriff auf NotesUmgebungsvariablen.
NotesTimer
Zeitgesteuerter Aufruf von Ereignissen
NotesView
Notes-Datenbank-Ansicht
NotesViewColumn
Spalte einer Ansicht
NotesViewEntry
Ein Eintrag in einer Ansicht (R5)
NotesViewEntryCollection
Aufzählung von Ansichtseinträgen (R5)
NotesViewNavigator
Repräsentiert ein Objekt zur Navigation innerhalb einer Notes-Ansicht. Er kann sämtliche Einträge oder auch nur eine Auswahl davon umfassen.
Button
Objekt für einen Button, einen sonstigen Hotspot oder auch eine Aktion.
Field
Masken-Feld
Navigator
Navigator-Objekt
Notes-Objekte instanziieren
233
U I- Kl ass sse en Klasse
Beschreibung
NotesUIDocument
Dokument im Frontendbereich. Beinhaltet auch Zugriff auf Maskenereignisse. Ist von daher ein Mittelding zwischen Dokument und Maske
NotesUIView
Ansicht im Frontend-Bereich. Bietet z. B. die Möglichkeit, den Cursor auf ein bestimmtes Dokument zu stellen. Wird über Maskenereignisse erreicht.
NotesUIWorkspace
Repräsentiert den Notes-Arbeitsbereich. Bietet davon ausgehend Zugriff auf das Dokument im Frontend-Bereich.
18.2 Notes-Objekte instanziieren Viele Notes-Objekte können auf verschiedene Weise instanziiert werden. Oft wird der Weg, wie man den Zugriff auf das gewünschte Objekt erhält, durch den Kontext vorgegeben. So ist es nahe liegend, dass man im Kontext einer Maske das entsprechende von ihr angezeigte und bearbeitete Dokument haben möchte. Daher bieten die Masken-Events dessen Objekt an. Ähnlich verhält es sich bei den Datenbankund den Ansichts-Events. Dort werden Ihnen ein NotesUIDatabase-Objekt bzw. ein NotesUIView-Objekt angeboten. Oft möchte man aber auch noch auf andere Elemente Zugriff haben. Beim Bearbeiten von Masken-Events möchte man häufig auf andere Dokumente der gleichen oder auch einer anderen Datenbank zugreifen, oder Sie möchten Agenten aufrufen. Vielleicht benötigen Sie auch Zugriff auf den Agenten, dessen Script Sie gerade bearbeiten. Dies macht es häufig erforderlich, noch andere »Einstiegsobjekte« als die von den Event-Handlern schon bereitgestellten zu finden und zu nutzen. In der Praxis wird der Einstieg oft über zwei verschiedene Wege durchgeführt, die wir Ihnen in den folgenden Abschnitten vorstellen möchten. Der Erste führt über das UI und bietet zunächst Zugriff auf das im Frontend geöffnete Dokument. Er kann nur von lokal ablaufenden Scripts verwendet werden. Der Zweite führt über das NotesSession-Objekt und kann sowohl von lokal als auch von auf dem Server ablaufenden Scripts genutzt werden. Dafür erhält man keinen Zugriff auf das Frontend-Dokument. Manche Objekte können auch »aus dem Stand« instanziiert werden, beispielsweise ein Lotus Notes-Datenbankobjekt. Damit lässt sich ebenfalls auf Ansichten, Ordner und Dokumente und verschiedene Elemente einer Datenbank zugreifen. Diese Möglichkeit zeigen wir Ihnen in Kapitel 19. »Auf Datenbanken und Dokumente zugreifen und sie bearbeiten«. Außerdem sind die Einstiegsobjekte NotesUIWorkspace und NotesSession nicht beliebig austauschbar. Auch wenn Sie über beide auf die gerade geöffnete (Backend) Datenbank zugreifen können, so gibt es doch viele sich gegenseitig ausschließende Unterschiede, so dass Sie häufig sogar beide Objekte in demselben Script nutzen werden. So können Sie im Allgemeinen nur über NotesUIWorkspace Zugriff auf das im Frontend geöffnete Dokument erhalten und Dialogboxen öffnen, während Sie
234
Domino-Klassen
den gerade aktiven Agenten nur über NotesSession ergreifen können. Man wird also häufig beide Objekte benötigen.
18.2.1 Weg: Einstieg über NotesUIWorkspace Durch den Einstieg über ein Objekt vom Typ NotesUIWorkspace erlangt man Zugriff auf verschiedene Elemente des Arbeitsbereiches. Dazu gehören insbesondere alle angebotenen Eigenschaften und Methoden dieser Klasse und der Zugriff auf das zurzeit geöffnete und im Fenster aktivierte Dokument. Wenn der Einstieg über NotesUIWorkspace gewählt wird und das Backend-Dokument erreichbar ist, dann kann man auf diese Weise auch alle Backend-Klassen erreichen. Allerdings liegt in gewissen Situationen das Backend-Dokument nicht im Zugriffsbereich. Etwa, weil das Script vom Initialize- oder auch vom QueryOpen-Event einer Maske aufgerufen wurde. Zurzeit dieser Ereignisse ist die Maske noch gar nicht aufgebaut und schon gar nicht geöffnet, so dass auch das BackendDokument nicht erreichbar ist. Dann wird man das zu bearbeitende Dokument über das Frontend überhaupt noch nicht greifen können. Man hat in diesem Fall noch die Möglichkeit, es über Backend-Methoden anhand bekannter Eigenschaften zu suchen. Ein Einstieg über NotesUIWorkspace kommt nur in Betracht, wenn das Script vom Benutzer lokal gestartet wurde. Ansonsten bleibt nur der Weg über die NotesSession. (Die Möglichkeit, direkt über NotesDatabase Zugriff auf Datenbanken zu erhalten, wird in einem anderen Kapitel behandelt.) Cod ebeispiele Auf das im Frontend geöffnete Dokument zugreifen und ein Feld beschreiben Dim ws As New NotesUIWorkspace Dim uidoc As NotesUIDocument Set uidoc = ws.CurrentDocument Call uidoc.FieldSetText("NachName", "Pfannkuch") Call uidoc.Save
Auf das zum im Frontend geöffneten Dokument gehörende Backend-Dokument zugreifen und ein Item beschreiben Dim ws As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim note As NotesDocument Set uidoc = ws.CurrentDocument Set note = uidoc.Document Call note.ReplaceItemValue("NachName", "Pfannkuch") Call note.Save(True, False)
Notes-Objekte instanziieren
235
Auf die zum im Frontend geöffneten Dokument gehörende Backend-Datenbank zugreifen und eine Ansicht öffnen Dim ws As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim note As NotesDocument Dim db As NotesDatabase Set uidoc = ws.CurrentDocument Set note = uidoc.Document Set db = note.ParentDatabase Call db.GetView("Persons")
Über die zum im Frontend geöffneten Dokument gehörende Backend-Datenbank auf die NotesSession zugreifen und eine Datenbank anlegen Dim ws As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim note As NotesDocument Dim db As NotesDatabase Dim session As NotesSession Set uidoc = ws.CurrentDocument Set note = uidoc.Document Set db = note.ParentDatabase Set session = db.Parent Dim newdb As New NotesDatabase("", "") Call newdb.Create("", "Test.nsf", True)
Das letzte Beispiel soll einerseits die Möglichkeit des Hindurchnavigierens durch die Objekte aufzeigen. Aber es soll auch zeigen, dass es in manchen Fällen besser ist, das richtige Einstiegsobjekt zu wählen. Denn mit dem Einstieg über NotesSession wäre der Code wesentlich kürzer geworden, wie ein Beispiel im folgenden Abschnitt zeigen wird.
18.2.2 Weg: Einstieg über NotesSession Dieser Weg hat gegenüber dem vorhin skizzierten den Vorteil, dass er in jeder Situation gewählt werden kann. Es ist unerheblich, ob das Script lokal oder auf einem Server läuft, ob es vom Benutzer oder von einem Server gestartet wurde. Letzteres ist bei periodischen Agenten der Fall. Ein Nachteil liegt darin, dass man keinen Zugriff auf die Elemente des Arbeitsbereiches hat. Wenn das Script auf einem Server läuft, wird Sie dieser Sachverhalt kalt lassen (da er dann kein Nachteil ist). Etwas anderes ist es schon, wenn das Script auf der Workstation, also lokal, läuft. Über die NotesSession erhalten Sie Zugriff auf die Datenbank, in der das Script läuft. Sie können auch ein Verzeichnis der Datenbanken erhalten, die auf dem betreffenden Computer installiert sind (NotesDbDirectory), und diese dann öffnen. Sie haben Zugriff auf die internationalen Einstellungen des Betriebssystems.
236
Domino-Klassen
Oder Sie ergreifen den Agenten, in dem das Script läuft. Und Sie können über die Eigenschaft DocumentContext mit Web-Nutzern kommunizieren. Das Beispiel aus dem NotesUIWorkspace-Abschnitt wird jetzt erheblich kürzer: Über NotesSession eine Datenbank anlegen Dim session As New NotesSession Dim db As NotesDatabase Dim newdb As New NotesDatabase("", "") Call newdb.Create("", "Test.nsf", True)
Den Agenten ergreifen, in dem das ablaufende Script liegt Dim session As New NotesSession Dim agent As NotesAgent Set agent = Session.CurrentAgent
Über DocumentContext mit Web-Nutzern kommunizieren Dim session As New NotesSession Dim webNote As NotesDocument Dim sWebClient As String Dim sQuery As String Set webNote = Session.DocumentContext sWebClient = webNote.HTTP_User_Agent(0) sQuery = webNote.Query_String(0)
Über das im letzten Beispiel angedeutete Vorgehen können Sie in der Web-Programmierung Informationen über den Web-Benutzer und die von ihm eingesetzten Technik erlangen. Dazu wird ein über ein spezielles Web-Ereignis getriggerter Agent programmiert, der das von ihm mitgeführte Kontext-Dokument ausliest. Er kann darin zum einen CGI-Variablen auswerten, zum anderen kann er dort selbst Informationen temporär ablegen. Allerdings sind diese Informationen nur für diesen einen Agenten »sichtbar«. Auf diese Weise können temporäre Informationen nach Web-Nutzer getrennt abgelegt werden. Sollen sie dauerhaft gespeichert werden, müsste der skizzierte Agent zusätzlich entsprechende Dokumente in einer Notes-Datenbank ablegen. Sehr interessant ist die Möglichkeit, über die CGI-Variable Query_String Informationen auszutauschen. Denn gemäß Domino-URL-Syntax lassen sich hinter dem URL-Befehl OpenAgent noch Parameter anhängen, die mittels »&« vom Befehl abgetrennt werden. Weitere Informationen zu diesem speziellen Notes-Thema erhalten Sie in der einschlägigen Literatur, zum Beispiel im Buch »Lotus Domino 4.6« von Fochler, Perc und Ungermann aus dem Addison-Wesley-Verlag.
Einige häufige Problemstellungen und ihre Lösung(en)
237
18.3 Einige häufige Problemstellungen und ihre Lösung(en) 18.3.1 Bearbeite das gerade geöffnete und aktivierte Dokument Das gerade geöffnete Dokument wird über die UI-Klassen gefunden. Hat man kein Masken-Ereignis zur Verfügung, das den Parameter Source As NotesUIDocument liefert, wird man im Allgemeinen ein Objekt vom Typ NotesUIWorkspace anlegen und darüber das NotesUIDocument und darüber das zugehörige Backend-Dokument erhalten. Dim ws As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim note As NotesDocument Set uidoc = ws.CurrentDocument Set note = uidoc.Document
18.3.2 Starte einen Agenten Agenten werden über eine Methode der Backend-Datenbank gefunden, die den Agenten »hostet«, also beherbergt. Dim agent As NotesAgent Set agent = db.GetAgent("TestAgent")
18.3.3 Erzeuge ein neues Dokument Ein »jungfräuliches« Notes-Dokument wird durch die Datenbank-Methode CreateDocument angelegt. Des Weiteren können Sie ein Dokument mit einer bestimmten Maske erzeugen, wobei die Maske für Benutzereingaben geöffnet wird. Dim note As NotesDocument Dim uidoc As NotesUIDocument 'Backend-Dokument erzeugen Set note = notesDatabase.CreateDocument 'Frontend-Dokument mit sich öffnender Maske erzeugen Set uidoc = notesUIWorkspace.ComposeDocument
18.3.4 Kopiere Dokumente Ein Dokument kann sehr komfortabel »in einem Stück« kopiert werden. Dim copyNote As NotesDocument Set copyNote = note.CopyToDatabase(notesDatabase) Call copyNote.save(True, True)
238
Domino-Klassen
Wenn nur Teile von Dokumenten kopiert werden sollen, so muss man dies wohl oder übel zu Fuß durchführen. Es wird ein neues Notes-Dokument angelegt und die zu kopierenden Items werden einzeln transferiert. Dim item As NotesItem Dim copyNote As NotesDocument Set copyNote = notesDatabase.CreateDocument 'Und für jedes zu übertragenden Item folgende Schritte erledigen Set copyItem = notesDocument.GetFirstItem("Subject") Set item = copyItem.CopyItemToDocument(copyNote, "Thema")
Als Resultat erhält man in der Variable Item das auf dem Zieldokument neu erzeugte NotesItem, das anschließend weiter bearbeitet werden kann. Dieses ZielItem kann beim Kopieren auch einen anderen Namen erhalten (muss es aber nicht). Im Beispiel wurde der neue Name »Thema« vergeben. Wenn der alte Name beibehalten werden soll, übergeben Sie einfach einen Leerstring (""). Das ganze Item auf die beschriebene Weise zu kopieren hat den Vorteil, dass sämtliche Eigenschaften automatisch mit übernommen werden. Natürlich können Sie den Inhalt eines Items auch mit der NotesDocument-Methode GetItemValue auslesen und ihn beispielsweise mit der NotesDocument-Methode ReplaceItemValue in ein auf dem neuen Dokument erstelltes Item schreiben. Dann müssen Sie sich aber womöglich noch um die korrekte Einstellung der Item-Eigenschaften kümmern. Über das konkrete Vorgehen muss im Einzelfall gemäß den Erfordernissen entschieden werden.
18.3.5 Versende ein Dokument Das ist sehr einfach. Sie rufen nach Fertigstellung des zu versendenden Dokuments einfach dessen Methode Send([recipientName As String]) auf. Wenn das Dokument kein SendTo-Feld mit einem oder mehreren eingetragenen Empfänger(n) enthält, müssen diese über den Parameter recipientName übergeben werden. Call note.Send(False, "Testuser/Testorganisation@Testdomäne")
Über weitere mailspezifische Felder können Sie das Verhalten des Mails ähnlich wie im Notes-Client im Detail steuern. Weitere Einzelheiten finden Sie in der NotesHilfe.
18.3.6 Finde bestimmte Dokumente Dazu gibt es eine Fülle verschiedener Möglichkeiten. Dokumente können über Feldinhalte, seine Ids, Links, URLs oder andere Merkmale wie Erstellungs- und Änderungsdatum gefunden werden.
Einige häufige Problemstellungen und ihre Lösung(en)
239
Auch in der Art des Zugriffs gibt es eine große Bandbreite. Diese haben ganz unterschiedliche Möglichkeiten, Vor- und auch Nachteile. Die wesentlichen Zugriffsmethoden lauten: Suche über die ganze Datenbank, Suche über einen Vollltextindex und Suche über Ansichten. Wobei Ansichten nichts anderes als Dokumentindizes sind. Weitere Einzelheiten finden Sie in Kapitel 19.4.
18.3.7 Ergreife alle in einer Ansicht markierten Dokumente Dies bewerkstelligen Sie über die Eigenschaft UnprocessedDocuments der geöffneten Datenbank (NotesDatabase). Diese Methode ist nur für Scripte verfügbar, die im Kontext eines Agenten oder einer Aktion ablaufen. Je nach Kontext und Einstellung der Agentenoptionen erhalten Sie ganz unterschiedliche Ergebnisse. So führt die Option »Alle gewählten Dokumente« zum Erhalt aller markierten Dokumente. Andere Optionen wie »Alle neuen oder veränderten Dokumente« würden zu entsprechend anderen Resultaten führen. Eine genaue Aufstellung zur Auswirkung der unterschiedlichen Agenten-Optionen auf die Eigenschaft UnprocessedDocuments finden Sie in der Domino Designer-Hilfe unter diesem Stichwort.
18.3.8 Öffne eine Datenbank Im Normalfall legen Sie dazu ein Objekt vom Typ NotesDatabase an. Je nachdem, ob Sie schon bei der Instanziierung Server und Pfad angeben oder ob Sie sich dies für später vorbehalten wollen, unterscheidet sich das weitere Vorgehen. Geben Sie Server und Pfad sofort an, erhalten Sie im Erfolgsfalle ein »geöffnetes« NotesDatabase-Objekt. Das bedeutet, die Datenbank ist an der angegebenen Stelle im Filesystem verfügbar und Sie haben unmittelbaren Zugriff auf das Datenbankobjekt. Dim db As New NotesDatabase("Testserver/Testorganisation", "Testdatenbank")
Wählen Sie den zweiten Weg, dann erhalten Sie ebenfalls ein instanziiertes Datenbankobjekt, das aber noch geschlossen ist. In diesem Fall müssen Sie vor dem Zugriff auf die Datenbank das Objekt noch öffnen. Dazu gibt es eine ganze Reihe verschiedener Methoden, je nachdem, auf welche Weise die Datenbank spezifiziert wird. Dim db As New NotesDatabase("", "") Call db.Open("Testserver/Testorganisation", "Testdatenbank")
18.3.9 Finde eine geöffnete Datenbank Eine im Frontend geöffnete Datenbank wird über den UI-Einstieg gefunden. Sie erzeugen zunächst ein Objekt des Arbeitsbereichs (NotesUIWorkspace). Über dessen Eigenschaft CurrentDocument erhalten Sie das Frontend-Dokument und über dessen Eigenschaft Document wiederum erhalten Sie das Backend-Dokument, das geöffnet wurde. Dessen Eigenschaft Parent führt dann zur im Arbeitsbereich geöff-
240
Domino-Klassen
neten Datenbank. Es sei noch einmal vermerkt, dass dieser Einstieg nur bei einem Dokument im aktivierten Fenster zum Erfolg führt. Auf diese Weise wird dessen Backend-Datenbank erreicht. Dim Dim Dim Dim Set Set Set
ws As NotesUIWorkspace uidoc As NotesUIDocument note As NotesDocument db As NotesDatabase uidoc = ws.CurrentDocument note = uidoc.Document db = note.Parent
Andere Datenbanken müssen explizit gesucht werden, siehe Kapitel 19.3. Wenn Sie das Backend-Dokument bereits »in der Hand halten« (über eine Objektvariable referenzieren), erreichen Sie die geöffnete Datenbank über dessen Eigenschaft Parent: Dim db As NotesDatabase Set db = note.Parent
18.4 Containerklassen: NotesDbDirectory, NotesDocumentCollection, NotesView Die Klassen NotesDbDirectory, NotesDocumentCollection und NotesView stellen Containerklassen dar, auch wenn sie in der Notes-Hilfe nicht so bezeichnet werden. Das bedeutet, dass sie selbst weitere Objekte in unbestimmter Anzahl aufnehmen können, die man über den Container erreichen und bearbeiten kann. Allen Containerklassen gemeinsam sind die Methoden GetFirstXXX, GetNextXXX, GetNthXXX. Die Buchstaben »XXX« stehen für die Bezeichnung der Objekte, die die jeweiligen Klassen beinhalten. Mit diesen Methoden erhalten Sie Zugriff auf diese Objekte. Sie werden häufig in Schleifen eingesetzt, um alle Objekte der Container durchzugehen. Dabei gibt es zwei grundsätzliche Methoden.
18.4.1 Erste Methode: GetFirstXXX/GetNextXXXKombination Bei dieser Vorgehensweise wird vor der Schleife die GetFirstXXX-Methode aufgerufen. Mit ihr erhält man Zugriff auf das erste Objekt des Containers. In allen weiteren Durchgängen erlangt man mit Hilfe der GetNextXXX-Methode das jeweils nächste Objekt. Der Vorgänger wird beim Aufruf mit übergeben. Dadurch ist es auch möglich, im ersten Schritt über eine andere Such-Methode ein Objekt zu suchen, das sich an einer anderen Position im Container befindet, und dieses dann als Startpunkt für die GetNextXXX-Methode zu wählen.
Containerklassen: NotesDbDirectory, NotesDocumentCollection, NotesView
241
Dieses Vorgehen kommt in der Praxis seltener vor, bietet sich aber an, wenn man erwartet, eine Anzahl von Objekten in einem zusammenhängenden Block zu finden. Auf diese Weise kann man die sonst für das Überspringen der ersten Objekte notwendige Berechnungszeit erheblich verkürzen. Wenn kein Objekt mehr zurückgegeben werden kann (entweder gibt es überhaupt keines oder die Schleife ist abgearbeitet), dann liefert die GetNextXXX-Methode NOTHING zurück. Jetzt heißt es Obacht geben, dass kein weiterer Aufruf von GetNextXXX erfolgt. Wird das nicht beachtet, gibt die GetNextXXX-Methode im nächsten Durchgang einen Notes-Error aus. Angenommen, Sie möchten eine Ansicht nach allen verfügbaren Dokumenten durcharbeiten. Dann würden Sie als Erstes vor Eintritt in die Schleife die GetFirstDocument-Methode von NotesView aufrufen und erhielten das erste Dokument. Die Do While-Schleife prüft bei Eintritt, ob ein Dokument zurückgegeben wurde (Not (note Is NOTHING)). Ist dies der Fall, so wird das Dokument bearbeitet und am Schluss der Schleife das nächste mit GetNextDocument(note) ermittelt. Nachdem wieder überprüft wurde, ob ein Dokument zurückgegeben wurde, wird dieses im nächsten Durchlauf bearbeitet usw. Das Beispiel geht davon aus, dass die zu betrachtende Datenbank db bereits ermittelt worden ist. Dim view Dim note Set view Set note Do While
as NotesView as NotesDocument = db.GetView("....") = view.GetFirstDocument Not (note Is Nothing) ..... 'bearbeite Dokument ..... Set note = view.GetNextDocument(note)
Loop
Man könnte sich auch andere Schleifen vorstellen, wie z. B. eine Do Until-Schleife. Diese hätte aber den Nachteil, dass man für den ersten Durchlauf auf andere Weise sicherstellen müsste, dass auch ein Dokument gefunden wurde, das bearbeitet werden kann. Eine While Wend-Schleife ist der Do While-Schleife gleichwertig und kann daher genau wie oben beschrieben verwendet werden. Wenn Sie Dokumente bearbeiten, die Sie über eine NotesView gefunden haben, ist eine Besonderheit zu beachten. Sollten Sie Merkmale eines Dokuments bearbeiten, die dazu führen, dass das Dokument nicht mehr zu der Suchansicht gehört, und speichern Sie dieses ab, dann können Sie es auch in der NotesDocumentCollection nicht mehr finden. In diesem Fall erhält die Objektreferenz aus unserem Beispiel (note) den Wert NOTHING und der Aufruf der Methode GetNextDocument führt unvermittelt zu einem Fehler. Um dies zu vermeiden, ergreifen Sie bereits vor der Bearbeitung des Dokuments das nächste, das erst im nächsten Schritt bearbeitet werden soll:
242
Domino-Klassen
Dim nextNote As NotesDocument Set note = view.GetFirstDocument Do While Not (note Is Nothing) Set nextNote = view.GetNextDocument(note) 'Das Dokument ergreifen, das erst im nächsten Schritt 'bearbeitet werden soll ..... 'bearbeite Dokument note '..... Call note.Save(True, False) 'Dokument "fällt aus der Ansicht raus" und note hat jetzt 'den Wert Nothing Set note = nextNote Loop
18.4.2 Zweite Methode: GetNthXXX Diese Methode verlangt als Parameter die Angabe, welches Objekt Sie ansprechen möchten. Wenn Sie wissen, das wievielte Objekt Sie im Container-Objekt erhalten möchten, ist diese Methode die richtige. Dies ist insbesondere während des Durchlaufs einer For-Next-Schleife der Fall. Als Beispiel wählen wir den Zugriff auf eine NotesDocumentCollection. Über die Eigenschaft Count erfahren wir, wie viele Dokumente sie insgesamt beinhaltet. Dim i% Dim note As NotesDocument For i% = 1 To notesDocumentCollection.Count Set note = notesDocumentCollection.GetNthDocument(i%) Next
Die Methode ist offensichtlich einfacher zu handhaben und scheint daher besser als die GetFirstXXX/GetNextXXX-Kombination zu sein. Allerdings muss gleich zu Anfang bekannt sein, wie viele Objekte zu durchlaufen sind, außerdem hat die Methode den gravierenden Nachteil, langsamer zu arbeiten als die GetFirstXXX-/ GetNextXXX-Kombination.
18.5 Neue Funktionalitäten unter Domino R5 Die bereits gut gestalteten Notes-Klassen wurden für die Version R5 noch um eine ganze Reihe von interessanten Funktionalitäten erweitert. Dass diese Funktionalitäten in der Tat fehlten, wurde dem Entwickler nicht immer sofort bewusst, da man sie etwas seltener benötigte. Benötigte man sie aber, musste man den beschwerlicheren Weg über die Notes-APIs wählen (z. B. C++-API). Allerdings gibt es immer noch eine ganze Reihe von Möglichkeiten, die den APIs vorbehalten bleiben. Zum Beispiel können Sie über die Script-Klasse NotesDatabase zwar
Spezielle Betrachtungen
243
abfragen, wie die Gestaltungsschablone dieser Datenbank heißt, Sie können sie aber nicht verändern. Dies ist in der C++-API hingegen ohne weiteres möglich. Des Weiteren gibt es natürlich auch neue Domino-Funktionalitäten für die neu hinzugekommenen Notes-Gestaltungselemente. Dazu zählen insbesondere die neuen Klassen für Gliederungen (NotesOutline und NotesOutlineEntry). In Kapitel 23 werden die neuen Funktionalitäten durch ein Kreuzchen (X) in der Spalte »R5« gekennzeichnet. Bei Klassen, die völlig neu sind, sind auch sämtliche Eigenschaften und Methoden durch das Kreuzchen gekennzeichnet. Dies betrifft die Klassen NotesOutline, NotesOutlineEntry, NotesReplication, NotesRichTextParagraphStyle, NotesRichTextTab, NotesViewEntry, NotesViewEntryCollection, NotesViewNavigator. Abschließend sei der Vollständigkeit halber noch erwähnt, dass es zwei Klassen gibt, die bereits unter R4.6 neu eingeführt wurden, nämlich NotesRegistration und NotesRichTextStyle.
18.6 Spezielle Betrachtungen Wenn Sie sich ins objektorientierte Design vertiefen sollten, wird bei Ihnen sehr bald der Wunsch aufkommen, Klassen innerhalb von LotusScript von den bestehenden Notes-Klassen abzuleiten und diese mit weiteren Fähigkeiten zu versehen. Leider wird es bei diesem Wunsch bleiben. Da die Notes-Klassen durch die LSXTechnologie eingebunden werden und diese Technologie das Ableiten von Klassen innerhalb von LotusScript nicht erlaubt, werden Sie zu anderen Taktiken greifen müssen. Es bietet sich in der Regel an, für die zu erstellenden Klassen eigene Script-Klassen zu definieren. Diese können Sie dann weiter vererben, so oft Sie wollen. Die benutzten Notes-Objekte werden als Eigenschaften eingebunden. Den Zugriff erlauben Sie nur über die Properties und Methoden (Funktionen und Prozeduren der Klasse). Dann können Sie Ihre Klassen nach außen hin wie von den nativen Notes-Klassen abgeleitete Klassen erscheinen lassen, obwohl sie es nicht sind und diese Vorgehensweise natürlich auch einiges an Mehraufwand bedeutet. Andere Möglichkeiten, Notes-Klassen anzupassen, finden Sie in Abschnitt 18.7, Weitere Klassen, LSX.
18.7 Weitere Klassen, LSX Über den LSX-Mechanismus können weitere Klassen eingebunden werden. Da auch die Domino-Backend-Klassen über LSX verfügbar gemacht werden, können die hinzugefügten Klassen wie Domino-Backend-Klassen angesprochen werden. LSX-Klassen werden über die Anweisung UseLSX ähnlich wie Script-Bibliotheken geladen.
244
Domino-Klassen
'(Options) UseLSX "c:\Programme\Lotus\Domino\LSX\TestLSX.dll" '(Declarations) Dim oTest As TestLSXClass
In diesem Beispiel wird unter Windows die Datei TestLSX.dll eingebunden. Anschließend wird eine Objektreferenzvariable deklariert, die vom Typ der in dieser Datei vorhandenen LSX-Klasse TestLSXClass ist. Es bleibt zu erwähnen, dass solche LSX-Klassen sowohl von Lotus selbst als auch von Drittanbietern bezogen werden können. Außerdem können Sie das LSX-Toolkit von Lotus-Seiten im Internet beziehen (www.lotus.com oder www.notes.net) und selbst neue Klassen entwerfen.
19 19
Auf Datenbanken und Dokumente zugreifen und sie bearbeiten
19.1 Verständnisvoraussetzungen Es wird ein grundlegendes Verständnis der LotusScript-Sprachelemente vorausgesetzt. Des Weiteren ist es wichtig, einen guten Überblick über OOP unter LotusScript zu haben.
19.2 Lernziel Sie lernen, wie Sie mit den LotusScript-Sprachelementen und den Notes/DominoKlassen auf Datenbanken und Dokumente zugreifen und sie bearbeiten können.
19.3 Datenbanken In diesem Kapitel wird diskutiert, wie Sie neue Datenbanken erzeugen und auf diese oder auch auf schon bestehende Datenbanken zugreifen können. Sie lernen, wie Sie den Titel einer Datenbank einstellen und Funktionalitäten der Datenbanken nutzen können. Dabei werden Sie neue Dokumente erzeugen und bestehende Dokumente datenbankweit suchen. Auch lernen Sie einiges darüber, wie Sie Dokumente bearbeiten und per Mail verschicken können. Am Schluss wird Ihnen noch eine Möglichkeit vorgestellt, über die sich Dokumente auf einfache Art zusammenstellen und dem Benutzer präsentieren lassen.
19 .3 .1 Al lg em e in e s z u m Da t e nb an k zug ri ff Sowohl beim Zugreifen auf vorhandene als auch auf neu zu erzeugende Datenbanken werden Ihnen immer wieder die Parameter server$ und fileName$ begegnen. Sie stehen für den Speicherort der Datenbank auf der Platte. Der Parameter server$ steht für den Server, auf dem eine Datenbank liegt bzw. auf dem sie erzeugt werden soll. Der Parameter fileName$ bezeichnet den Dateinamen der Datenbank mit komplettem Pfad. Wenn die Datenbank in einem Unterverzeichnis des Notes-Datenverzeichnisses zu finden ist, genügt hier die relative Angabe (also die Angabe des Pfa-
246
Auf Datenbanken und Dokumente zugreifen und sie bearbeiten
des ab dem Notes-Datenverzeichnis), ansonsten ist die komplette Angabe mit Laufwerk bzw. der komplette Pfad unter Unix erforderlich. Wenn für den Parameter server$ ein Leerstring ("") übergeben wird, bezieht sich das Script auf den Computer, auf dem es läuft. Wird der Parameter fileName$ als Leerstring übergeben, so wird auf die aktuelle Datenbank zugegriffen, also diejenige, in der das Script läuft. Datenbanken werden häufig über die Parameter server$ und fileName$ angesprochen. Ist Ersterer leer, so ist die Datenbank auf dem Computer gemeint, auf dem das Script läuft, ist Letzterer leer, so ist die eigene Datenbank gemeint. Auf betriebssystemabhängige Unterschiede beim Parameter filename$ ist zu achten.
19.3.2 Neue Datenbanken erzeugen Als geübter Notesanwender werden Sie wissen, dass man neue Datenbanken auf sehr unterschiedliche Weise anlegen kann. Im Wesentlichen unterscheidet man das Erzeugen leerer Datenbanken (sie verfügen noch über keinerlei Anpassungen) vom Erzeugen solcher, die das Design vorhandener Datenbanken oder Schablonen übernehmen. Diese unterschiedlichen Methoden werden in der Folge kurz beleuchtet. Dabei bedeutet die Variable notesDatabaseNew jeweils eine Objektreferenz der neuen Datenbank. Die Variable notesDatabase stellt eine Objektreferenz auf die Ausgangsdatenbank dar. Ei g e n s t ä n di g e D a te n b a n k e n Syntax Create, CreateCopy, CreateFromTemplate Set notesDatabaseNew = notesDatabase.Create ( server$, fileName$, open% ) Set notesDatabaseNew = notesDatabase.CreateCopy ( server$, fileName$ ) Set notesDatabaseNew = notesDatabase.CreateFromTemplate ( server$, fileName$, inherit% ) Erläuterungen zu den Parametern finden Sie im folgenden Text. Leere Datenbanken
So erzeugen Sie eine neue leere Datenbank, also ohne vererbte Gestaltungselemente oder irgendwelche Daten: Set notesDatabaseNew = notesDatabase.Create ( server$, fileName$, open% ) Das Flag open% gibt an, ob die Datenbank sofort geöffnet werden soll. In der ACL wird der Benutzer, unter dem das Script läuft, als Manager vermerkt.
Datenbanken
247
Datenbanken, die das Design einer bestehenden Datenbank übernehmen
Möchten Sie eine bereits vorhandene Datenbank kopieren, so verwenden Sie: Set notesDatabaseNew = notesDatabase.CreateCopy ( server$, fileName$ ) Kopieren bedeutet: alle Dokumente der Ausgangsdatenbank werden übernommen, und die ACL hat die gleichen Einträge wie die Ursprungsdatenbank. Soll die Datenbank das Design einer vorhandenen Schablone erben, so ist die folgende Methode zu wählen: Set notesDatabaseNew = notesDatabase.CreateFromTemplate( server$, fileName$, inherit% ) Die neue Datenbank erhält das Design der Schablone und alle ihre Dokumente. In der ACL wird, wie bei der Create-Methode, der Benutzer, unter dem das Script läuft, als Manager vermerkt. Wenn Sie das Flag inherit% auf TRUE setzen, wird die Ausgangsschablone in der neuen Datenbank als Gestaltungsschablone eingetragen. Dadurch werden auch künftige Designänderungen der Ausgangsschablone automatisch an die neue Datenbank weitergegeben. R e p l ik e n Syntax CreateReplica: Set notesDatabaseNew = notesDatabase.CreateReplica ( server$, fileName$ ) Repliken sind Kopien einer Datenbank. Der große Unterschied ist, dass eine Replik die gleiche Replik-ID aufweist wie das Original. Dies führt dazu, dass die Replik jederzeit mit der Originaldatenbank per Replikation automatisiert abgeglichen werden kann. Von diesem Abgleich können sowohl das Design als auch die Dokumente betroffen sein. Zum Erzeugen einer neuen Replik muss man lediglich den Speicherort für die neue Datenbank angeben: Set notesDatabaseNew = notesDatabase.CreateReplica ( server$, fileName$ ) Das Replikationsverhalten wird über das GUI eingestellt und über die Klasse NotesReplication abgefragt. W e i t e r e I n f o r m a t io n e n z u d e n P fa d a n g a b e n Wenn Sie aus Versehen einen Pfad angeben, der nicht verwendet werden kann (Server nicht bekannt oder Datenbank mit gleichem Namen und Pfad schon vorhanden), wirft das Script einen Notes-Error. Verzeichnisse, die noch nicht existieren, aber angelegt werden können, werden automatisch erzeugt. A u s de r Be i s pi e l an w e n d un g Unsere Logging-Funktion soll alle Meldungen in eine Datenbank legen, die das Design der Notesschablone agentlog.nsf hat.
248
Auf Datenbanken und Dokumente zugreifen und sie bearbeiten
Diese Datenbank können wir natürlich vom Administrator erzeugen lassen. Da er aber viel um die Ohren hat, nehmen wir ihm diese Arbeit ab: Function CreateAgentLog As NotesDatabase Dim dbAgentLogTemplate As NotesDatabase Dim dbAgentLog As NotesDatabase 'Öffne die Notesschablone (alog4.nsf) Set dbAgentLogTemplate = New NotesDatabase("Office/BK-Soft", _ "alog4.nsf") 'Erzeuge die neue Agentlog-Datenbank (agentlog.nsf) 'Der Parameter True sorgt dafür, dass künftige 'Gestaltungsänderungen der Schablone auf unsere Datenbank 'übertragen werden. Set dbAgentLog = dbAgentLogTemplate.CreateFromTemplate(_ "Office/BK-Soft", "agentlog.nsf", True) 'Gib die neue Datenbank zurück Set CreateAgentLog = dbAgentLog End Function
Um die Fehlerbehandlung machen wir uns erst weiter unten Gedanken, denn dazu müssen wir uns noch etwas mehr mit dem Zugriff auf Notes-Datenbanken beschäftigen.
19.3.3 Zugriff auf vorhandene Datenbanken Für den Zugriff auf bestehende Datenbanken gibt es einiges mehr an Methoden als für das Erzeugen neuer Datenbanken. Letztendlich arbeiten sie aber alle sehr ähnlich. Sie unterscheiden sich hauptsächlich in der Art der Informationen, die zur Laufzeit zum Zugreifen übergeben werden (können). Syntax New, CurrentDatabase, OpenMail, OpenByReplicaID: Dim notesDatabase As New NotesDatabase ( server$, fileName$ ) Set notesDatabase = New NotesDatabase ( server$, fileName$ ) Call notesDatabase.OpenMail flag% = notesDatabase.OpenByReplicaID ( server$, fileName$ ) Der Parameter flag% zeigt an, ob die Datenbank auf dem angegebenen Server gefunden und geöffnet werden konnte. Be is p i e le z u m Z u g r e i f e n a u f v o rh a n d e n e D a t e n b a n k e n "aus dem Stand": Dim notesDatabase As New NotesDatabase(server$, fileName$) Set notesDatabase = New NotesDatabase(server$, fileName$)
Datenbanken
249
ausgehend von anderen Objekten: 'Zugriff auf die Datenbank, in der das Script läuft Set notesDatabase = notesSession.CurrentDatabase 'Zugriff auf die Datenbank, in der ein Element liegt, 'auf das bereits Zugriff besteht Set notesDatabase = notesDocument.Parent Set notesDatabase = notesView.Parent aufgrund sonstiger Informationen: 'Zugriff auf die Mail-Datenbank des Benutzers, unter dessen 'Kennung das Script läuft Call notesDatabase.OpenMail Call notesDatabase.OpenByReplicaID(server$, replicaID$)
Ö f fn e n e i n e r D a t e n b a n k Bevor eine Datenbank bearbeitet werden kann, muss sie im Allgemeinen geöffnet sein. Es gibt nur wenige Informationen, auf die Sie auch ohne die Datenbank zu öffnen zugreifen können. Die wesentlichen Informationen, die Sie so erhalten, sind der Server und der Pfad, soweit diese bei der Anlage des NotesDatabase-Objektes angegeben wurden. Hingegen können Sie bei geschlossenen Datenbanken auf keinen Fall auf Dokumente oder Gestaltungselemente zugreifen. Manche Zugriffs- und Erstellungsmethoden öffnen die Datenbank schon automatisch, andere hingegen nicht. Diese Aussage gilt insbesondere für den Fall, dass die vorher ausgeführte Zugriffs- oder Erstellungsmethode erfolgreich war. War sie nicht erfolgreich, ist das NotesDatabase-Objekt sowieso geschlossen. Daher müssen Sie im Falle der nicht automatisch öffnenden Methoden immer darauf achten, das Öffnen mit der Methode Open() explizit nachzuholen. Am besten prüfen Sie vor weiteren Aktionen immer, ob die Datenbank mit Erfolg geöffnet wurde: notesDatabase.IsOpen() Syntax IsOpen(): flag% = notesDatabase.Open ( server$, fileName$ ) Sonst wird der Benutzer früher oder später auf den folgenden für ihn nicht sofort verständlichen Fehler stoßen (Abbildung 19.1).
Abbildung 19.1: Dialogbox, die standardmäßig darauf hinweist, dass eine Datenbank noch nicht geöffnet wurde
250
Auf Datenbanken und Dokumente zugreifen und sie bearbeiten
In diesem Fall wurde für den Namen der Datenbankschablone mit Absicht der falsche Name alog24.nsf gewählt. Richtig wäre alog4.ntf (eine Datenbank-Schablone) gewesen. Die Notes-Fehlermeldung zeigt aber nicht, dass alog24.nsf gar nicht existiert, sondern weist nur darauf hin, dass sie nicht geöffnet wurde. Es ist besser, wenn wir für diesen Fehler eine andere Meldung vorsehen, die weniger verwirrend ist: Function CreateAgentLog As NotesDatabase Dim dbAgentLogTemplate As NotesDatabase Dim dbAgentLog As NotesDatabase 'Öffne die Notesschablone (alog4.nsf) Set dbAgentLogTemplate = New NotesDatabase("Office/BK-Soft", _ "alog4.nsf") 'Fehlerbehandlung If Not dbAgentLogTemplate.IsOpen Then Error _ ERR_DATABASE_NOT_FOUND, _ "Die Schablone alog4.nsf wurde"& _ "auf dem Server Office/BK-Soft nicht gefunden" 'Erzeuge die neue Agentlog-Datenbank (agentlog.nsf) 'Der Parameter True sorgt dafür, dass künftige 'Gestaltungsänderungen der Schablone auf unsere Datenbank 'übertragen werden Set dbAgentLog = dbAgentLogTemplate.CreateFromTemplate(_ "Office/BK-Soft", "agentlog.nsf", True) 'Gib die neue Datenbank zurück Set CreateAgentLog = dbAgentLog End Function
Die Meldung dazu sehen Sie in Abbildung 19.2.
Abbildung 19.2: Dialogbox, die die durch den Entwickler definierte Fehlermeldung bei nicht geöffnetem Datenbankobjekt anzeigt
Datenbanken
251
19.3.4 Löschen von Datenbanken Datenbanken löschen ist sehr einfach: Call notesDatabase.Remove
Syntax Remove(): Call notesDatabase.Remove Die Datenbank wird ohne weitere Nachfrage von der Platte gelöscht. Die Objektreferenz notesDatabase hat anschließend den Wert NOTHING.
19.3.5 Programmieren von Datenbanken Beim Programmieren von Datenbanken können Sie zum einen Scripte schreiben, die auf bestimmte Ereignisse in den Datenbanken reagieren, zum anderen können Sie auch Einfluss auf Datenbanken nehmen, indem Sie die Eigenschaften und Methoden des NotesDatabase-Objekts ausnutzen. Dat e n b an k e r e i gn i ss sse e Die Handler für die vorgesehenen Datenbankereignisse (Events) finden Sie in der Datenbankgestaltung unter Ressourcen | Andere | Datenbank-Script. Event- oder Ereignishandler sind Prozeduren, die auf ein Ereignis hin aufgerufen und ausgeführt werden. Es stehen folgende Ereignishandler zur Verfügung: Bezeichnung
Beschreibung (Zeitpunkt des Eintretens)
Initialize
Beim Initialisieren des Objekts
Queryclose
Vor dem Schließen der Datenbank
Querydocumentdelete
Vor dem Löschen eines Dokuments
Querydocumentundelete
Vor der Zurücknahme des Löschens eines Dokuments
Querydragdrop
Bevor ein Dokument per Drag-And-Drop empfangen wird
Postopen
Nach dem Öffnen der Datenbank
Postdocumentdelete
Nach dem Löschen eines Dokuments
Postdragdrop
Nachdem ein Dokument per Drag-And-Drop empfangen wurde
Terminate
Beim Zerstören des Objekts
Diese Ereignishandler bilden zusammen mit den obligatorischen Abschnitten (Options) und (Declarations) ein eigenständiges Modul. In der Folge gehen wir auf die Eventhandler noch etwas genauer ein.
252
Auf Datenbanken und Dokumente zugreifen und sie bearbeiten
Auf das Öffnen oder Schließen von Datenbanken reagieren
Mit Postopen können Sie irgendwelche Aktionen anstoßen, die sofort nach dem Öffnen und bevor der Benutzer eingreift durchgeführt werden sollen. Dazu kann auch das Anzeigen oder Abfragen von Informationen gehören. Wenn Sie öffentliche Variablen deklariert haben, können Sie sie jetzt initialisieren. Queryclose versetzt Sie in die Lage, dafür zu sorgen, dass eine Datenbank nur verlassen werden kann, wenn ein bestimmter Zustand besteht oder eingetreten ist, oder man kann über dieses Event für die Ausführung bestimmter Aktionen beim Schließen der Datenbank sorgen. Auf Ereignisse in Verbindung von Dokumenten in der Datenbank reagieren
Interessant sind auch die ganzen Methoden, die auf das Hinzufügen, Ausschneiden oder Löschen von Dokumenten reagieren: Postdocumentdelete, Querydocumentdelete, Querydocumentundelete, Querydragdrop, Postdragdrop. Im Unterschied zu ihren Pendants in den Ansichten beziehen sich diese Events auf jedes Dokument, das in Beziehung zur Datenbank tritt. Bei einer Ansicht reagieren diese Events nur, wenn die entsprechende Ansicht im aktiven Fenster geöffnet ist. Be is p i e l fü r e i n D a t e n b a n k e re ig n i s Wir möchten, dass der Benutzer beim Öffnen der Kontaktmanagement-Datenbank per Meldung erfährt, wie viele Kontakte heute anliegen. Dazu nutzen wir das Datenbankereignis PostOpen. Öffnen Sie also im Designer die Datenbank Kontakte und machen Sie das Ereignis im Gestaltungsnavigator über Ressourcen | Andere | Datenbank-Script ausfindig. Dort geben Sie die folgende Formel ein: Sub Postopen(Source As Notesuidatabase) Dim nKontakteFürHeute As Integer 'nKontakteFürHeute = GetAnzahlHeuteFälligerKontakte() Messagebox "Für heute sind " & nKontakteFürHeute & _ " Kontakte zu erledigen", 32, "Zu erledigen" End Sub
Die auskommentierte Zeile werden wir später vervollständigen, wenn die dort angegebene Funktion zur Verfügung steht. Aber auch ohne diese Zeile können wir schon erkennen, wie der Mechanismus arbeiten wird. Schließen Sie dazu einfach die Datenbank und öffnen Sie sie durch einen Doppelklick auf die Kachel wieder. Dann sehen Sie die Meldung (Abbildung 19.3).
Datenbanken
253
Abbildung 19.3: Die programmierte Meldung über anstehende Kontakte
Ei g en s ch af t en Von den zahlreichen Eigenschaften gibt es nur fünf, die über Script direkt beeinflusst werden können. Sie finden sie in der Tabelle 19.1. Die übrigen können nur abgefragt werden. Name
Datentyp
Categories
String
R5
Beschreibung
DelayUpdates
Integer Flag
X
(Read-Write) Gibt an, ob Veränderungen an Dokumenten sofort oder verzögert auf die Platte geschrieben werden (steigert die Performance)
FolderReferencesEnabled
Integer Flag
X
(Read-Write) Gibt an, ob die Datenbank Ordnerverweise führt
SizeQuota
Long
(Read-Write) Größenbeschränkung der Datenbank
Title
String
(Read-Write) Titel der Datenbank
(Read-Write) Die Kategorien, unter denen die Datenbank im Datenbankverzeichnis geführt wird
Tabelle 19.1: Ausgewählte Eigenschaften der NotesDatabase-Klasse
Von diesen Eigenschaften wird wohl Title am häufigsten gebraucht. Wir nutzen diese, um die Funktion CreateAgentLog zu vervollständigen, indem wir den Titel der neu erzeugten Datenbank auf "Agentlog Kontaktmanagement" setzen: Function CreateAgentLog As NotesDatabase Dim dbAgentLogTemplate As NotesDatabase Dim dbAgentLog As NotesDatabase 'Öffne die Notesschablone (alog4.nsf) Set dbAgentLogTemplate = New NotesDatabase("Office/BK-Soft", _ "alog4.nft") 'Fehlerbehandlung If Not dbAgentLogTemplate.IsOpen Then Error _ ERR_DATABASE_NOT_FOUND, "Die Schablone alog4.nft"& _ " wurde auf dem Server Office/BK-Soft"& _ " nicht gefunden" 'Erzeuge die neue Agentlog-Datenbank (agentlog.nsf) 'Der Parameter True sorgt dafür, dass künftige
254
Auf Datenbanken und Dokumente zugreifen und sie bearbeiten
'Gestaltungsänderungen der Schablone auf unsere Datenbank 'übertragen werden Set dbAgentLog = dbAgentLogTemplate.CreateFromTemplate(_ "Office/BK-Soft", "agentlog.nsf", True) 'Neuen Titel geben DbAgentLog.Title = "Agentlog Kontaktmanagement" 'Gib die neue Datenbank zurück Set CreateAgentLog = dbAgentLog End Function
Syntax Title: title$ = notesDatabase.Title notesDatabase.Title = title$ In den Zeilen für die Fehlerbehandlung sehen Sie mit IsOpen() ein Beispiel für den Gebrauch einer Eigenschaft, die nur abgefragt werden kann. Man sollte Sie möglichst immer nach einem Zugriff auf eine Datenbank verwenden, um auszuschließen, dass der Zugriff fehlgeschlagen ist. Method en In Tabelle 19.2 sind die Methoden aufgelistet, die Einfluss auf eine Datenbank nehmen. Über die Einordnung der Methoden GrantAccess, QueryAccess und RevokeAccess kann man sich streiten. Denn sie beeinflussen eigentlich nicht direkt die Datenbank selbst, sondern die ACL, die auch über ein eigenes Objekt vom Typ NotesACL angesprochen werden kann. Name
Datentyp
R5
Create
NotesDatabase
(X)
Erzeugt eine neue Datenbank. Der optionale Parameter maxSize% ist neu. Er steht für die Größenbeschränkung von R4-Datenbanken.
CreateCopy
NotesDatabase
(X)
Erzeugt eine Datenbankkopie. Der optionale Parameter maxSize% ist neu. Er steht für die Größenbeschränkung von R4-Datenbanken.
CreateFromTemplate
NotesDatabase
(X)
Erzeugt eine Datenbankkopie. Der optionale Parameter maxSize% ist neu. Er steht für die Größenbeschränkung von R4-Datenbanken.
CreateReplica
NotesDatabase X
Aktiviert einen Ordner. Falls noch nicht vorhanden, wird er erstellt.
Compact
EnableFolder GrantAccess
Beschreibung Verdichtet eine lokale Datenbank.
Erzeugt eine Datenbankreplik.
Richtet eine Zugriffsberechtigung ein.
Datenbanken
255
Name
Datentyp
R5
Beschreibung
Open
Integer Flag
Öffnet eine Datenbank. Der Rückgabewert informiert über den Erfolg.
OpenByReplicaID
Integer Flag
Wie Open, jedoch wird die Datenbank auf einem bestimmten Server über die ReplikID gefunden.
OpenIfModified
Integer Flag
Wie Open. Die Datenbank wird allerdings nur geöffnet, wenn sie seit einem bestimmten Zeitpunkt geändert wurde.
OpenMail
Öffnet die Mail-Datenbank des Benutzers, unter dessen Name das Script läuft.
OpenURLDb
Öffnet die Web Navigator-Datenbank.
OpenWithFailover
Wie Open. Wenn die spezifizierte Datenbank auf einem Server liegt, der zu einem Cluster g