Notes Domino 5. Einführung in die LotusScript-Programmierung

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 gehört, dann wird im Fehlerfall versucht, eine Replik auf einem anderen Clusterserver zu öffnen.

QueryAccess

Integer

Remove Replicate

Ermittelt den Zugriffslevel eines bestimmten Benutzers, einer Gruppe oder eines Servers bezüglich der Datenbank. Löscht die Datenbank von der Platte (ohne weitere Nachfrage!).

Integer Flag

Stößt eine Replikation an. Das Script hält an, bis die Replikation abgeschlossen ist und meldet über das Flag das Ergebnis.

RevokeAccess

Eine bestimmte Zugriffsberechtigung widerrufen.

UpdateFTIndex

Führt ein Update auf den Volltextindex durch.

Tabelle 19.2: Ausgewählte Methoden der NotesDatabase-Klasse

Die Methode, die wohl am häufigsten benötigt wird, ist Open(). Die Gründe dafür haben wir bereits besprochen. Konkrete Beispiele dafür schenken wir uns an dieser Stelle, da Sie in den kommenden Beispielscripten unweigerlich eine ganze Reihe davon sehen werden.

256

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

19.4 Dokumente finden und darauf zugreifen Dokumente können über vielerlei Wege gefunden werden. Es gibt drei ContainerKlassen, über die auf Dokumente zugegriffen werden kann: NotesDatabase, NotesView und NotesDocumentCollection. Die unterschiedlichen Suchmethoden steigern sich von NotesDocumentCollection über NotesView bis hin zur NotesDatabase-Klasse. Deshalb werden wir sie auch in dieser Reihenfolge besprechen. Es sollte noch vorausgeschickt werden, welcher Zusammenhang zwischen diesen Klassen besteht.

19.4.1 Zusammenhang zwischen den Klassen NotesDatabase, NotesView und NotesDocumentCollection NotesDatabase repräsentiert eine einzelne Datenbank, in der eine Menge von Dokumenten liegt. Auf diese kann zunächst einmal in ihrer Gesamtheit zugegriffen werden. Dann gibt es Suchmethoden, die ebenfalls über die Gesamtheit der in der Datenbank enthaltenen Dokumente laufen. Wollen Sie nur über einen Ausschnitt der in der Datenbank enthaltenen Dokumente suchen, so können Sie über eine NotesView (Ansicht) suchen, die über ihre Suchformel genau diese Dokumente umfasst. Ein anderes Objekt, mit dem man Teilmengen der Dokumente einer Datenbank betrachten kann, ist die NotesDocumentCollection. Sie erhält man durch eine vorherige Suche über eine Datenbank oder eine Ansicht, so dass eine NotesDocumentCollection oft auch eine Teilmenge der in einer Ansicht enthaltenen Dokumente umfasst. NotesDocumentCollection nimmt eine durch eine Suche oder sonstige Auswahlmethode bestimmte Menge an Dokumenten auf. In diesen kann anschließend in jeder Richtung navigiert werden. Genauer gesagt enthält NotesDocumentCollection lediglich Objektreferenzvariablen zu diesen Dokumenten. Doch nun zu den Details. Wie gesagt, wir fangen umgekehrt an, nämlich bei der NotesDocumentCollection, da sich so die Erläuterungen besser aufbauen lassen.

19.4.2 Suchmöglichkeiten in NotesDocumentCollection Eine NotesDocumentCollection beinhaltet im Allgemeinen mehrere Dokumente in ungeordneter Reihenfolge. Ausnahme: Wenn die Collection das Resultat einer Volltextsuche ist, dann sind die Dokumente gemäß der Reihenfolge der Relevanz sortiert.

Dokumente finden und darauf zugreifen

257

Method en Name

Datentyp

FTSearch

NotesDocumentCollection

R5

Beschreibung

GetDocument

NotesDocument

GetFirstDocument

NotesDocument

Gibt das erste Dokument zurück.

GetLastDocument

NotesDocument

Gibt das letzte Dokument aus.

GetNextDocument

NotesDocument

Gibt das nächste Dokument der Collection zurück. Der Ausdruck »nächste« bezieht sich dabei auf das Dokument, das der Methode zur Suche übergeben wird.

GetNthDocument

NotesDocument

Gibt das Dokument zurück, das sich an der mit einer Ordnungsnummer bezeichneten Stelle befindet.

GetPrevDocument

NotesDocument

Analog zu GetNextDocument, nur dass das vorhergehende Dokument ausgegeben wird.

Reduziert die in der Collection enthaltenen Dokumente auf diejenigen, die bei der Volltextsuche über die Collection gefunden werden. X

Gibt das übergebene Dokument zurück, wenn es sich in der Collection befindet. Ansonsten wird NOTHING zurückgegeben.

Tabelle 19.3: Ausgewählte Methoden zur Navigation in der Klasse NotesDocumentCollection

Wie die unterschiedlichen Arten des Dokumentzugriffs verwendet werden können, wurde im Kapitel zur allgemeinen Beschreibung der Domino-Klassen behandelt (Abschnitt 18.4, »Containerklassen: NotesDbDirectory, NotesDocumentCollection, NotesView«). Noch einmal zur Erinnerung: Die Kombinationen GetFirstDocument/GetNextDocument und GetLastDocument/GetPrevDocument eignen sich zum Durchlaufen aller Dokumente per Do Loop-Schleifen (oder While Wend), und zwar von vorne nach hinten bzw. umgekehrt. Dagegen dient die Methode GetNthDocument hauptsächlich zum Durchlauf von For Next-Schleifen. Syntax GetFirstDocument, GetNextDocument, GetLastDocument, GetPrevD ocument, GetNthDocument: Set notesDocument = notesDocumentCollection.GetFirstDocument Set notesDocument = notesDocumentCollection.GetNextDocument ( notesDocument ) Set notesDocument = notesDocumentCollection.GetLastDocument Set notesDocument = notesDocumentCollection.GetPrevDocument ( notesDocument ) Set notesDocument = notesDocumentCollection.GetNthDocument ( position% )

258

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Bei GetNextDocument und GetPrevDocument geben Sie mit dem Parameter notesDocument (in Klammern) das Dokument an, von dem aus zum nächsten bzw. zum vorherigen Dokument navigiert werden soll. Wenn als Rückgabewert NOTHING erscheint, dann gibt es an der bezeichneten Stelle kein Dokument. Besonders interessant ist die Methode FTSearch. Mit ihr können Sie auf den in der NotesDocumentCollection enthaltenen Dokumenten eine Volltextsuche durchführen. Als Resultat werden die in der NotesDocumentCollection enthaltenen Dokumente auf die Dokumente eingeschränkt, die die Bedingung der Suche erfüllen. Auf diese Weise lassen sich also Volltextsuchen auf bestimmte Teilmengen von Dokumenten innerhalb einer Datenbank beschränken. Syntax FTSearch: Call notesDocumentCollection.FTSearch ( query$, maxDocs% ) Mit dem Parameter maxDocs% wird festgelegt, wie viele Dokumente maximal aufgegriffen werden sollen. Wenn Sie 0 angeben, werden alle gefundenen Dokumente in die NotesDocumentCollection aufgenommen. Mit query$ legen Sie den Suchausdruck fest. Nähere Einzelheiten zum Aufbau von Suchausdrücken finden Sie in der Notes-Hilfedatenbank. Eine NotesDocumentCollection wird ihrerseits ausschließlich über vorherige Suchabfragen erhalten. Zum Beispiel liefert die NotesDatabase-Methode Search ein solches Objekt zurück. Syntax Search: Set notesDocumen = notesDocumentCollection.Search ( query$, notesDateTime, maxDocs% ) Mit dem Parameter maxDocs% wird festgelegt, wie viele Dokumente maximal aufgegriffen werden sollen. Wenn Sie 0 angeben, werden alle gefundenen Dokumente in die NotesDocumentCollection aufgenommen. Mit query$ legen Sie die Suchformel fest. Im Unterschied zu den verschiedenen Formen der Volltextsuche (beispielsweise FTSearch) ist hier eine Notes-Formel anzugeben, die als Ergebnis TRUE oder FALSE zurückgeben muss. Sie hat den gleichen Aufbau wie eine Auswahlformel einer Ansicht. Sie wird ebenfalls mit dem Schlüsselwort SELECT eingeleitet. Der Parameter notesDateTime legt ein Datum fest, bis zu dem gesucht werden soll, das heißt Dokumente, die älter sind, werden bei der Suche nicht berücksichtigt. Wir nutzen die NotesDocumentCollection für unsere Beispielanwendung einmal ein wenig anders. Und zwar möchten wir die Funktion GetAnzahlHeuteFälligerKontakte() aus dem Abschnitt 19.3.5 (Programmieren von Datenbanken, Unterabschnitt Datenbankereignisse) ausprogrammieren. In diesem Fall benötigen wir keinen Zugriff auf die Dokumente, sondern uns interessiert lediglich die Anzahl bestimmter Kontaktdokumente, nämlich solcher, die am aktuellen Tag zur Bearbeitung anstehen. Zu diesem Zweck führen wir mit der NotesDatabase-Methode Search eine Suche nach den gewünschten Kontakten durch. Wir erhalten diese Dokumente in einer

Dokumente finden und darauf zugreifen

259

NotesDocumentCollection. Wir greifen dann aber nicht auf die einzelnen Dokumente zu, sondern fragen lediglich die Eigenschaft Count ab. Damit wissen wir, wie viele Kontakte zur Bearbeitung anstehen. Syntax Count: Count% = notesDocumentCollection.Count Die Methode Search führt eine Suche über die ganze Datenbank aus und verwendet dabei eine Selektionsformel in Notes-Makrosprache. Unsere Selektionsformel lautet wie folgt: Dim sSelection As String sSelection = |Form = "Kontakt" & @Date(NächsterZeitpunkt) <= @Today|

Wir verwenden für den Suchstring keine Anführungszeichen, da wir sonst gezwungen wären, die Anführungszeichen zur Kennzeichnung von Makro-Strings zu verdoppeln. Dies ist kein großer Aufwand, aber unübersichtlich. Durch Verwendung des Pipezeichens erhält der Suchstring das gleiche Aussehen wie innerhalb einer Makroumgebung. Da wir alle Dokumente suchen, die am heutigen Tag zur Bearbeitung anstehen (und die, die schon vorher fällig waren), vergleichen wir @Today() mit dem Inhalt des Feldes NächsterZeitpunkt. Da in diesem Feld auch eine Uhrzeitangabe stehen könnte, eliminieren wir diese mit der Funktion @Date(). Unsere Funktion sieht nun wie folgt aus: Function GetAnzahlHeuteFälligerKontakte() As Integer Dim session As New NotesSession Dim collection As NotesDocumentCollection Dim sSelection As String Dim dtCutOff As New NotesDateTime("") 'Bilde Selektionsformel sSelection = |Form = "Kontakt" & @Date(NächsterZeitpunkt) _ <= @Today| 'Führe Suche aus Set collection = session.CurrentDatabase.Search(sSelection, _ dtCutOff, 0) End Function

Zwei Parameter bedürfen noch der Erklärung. Zunächst wäre da der Parameter dtCutOff. Dieser stellt einen Zeitpunkt dar. Alle Dokumente, die älter als dtCutOff sind, werden in der Suche nicht berücksichtigt. Damit alle Dokumente, die sich in der Datenbank befinden mögen, berücksichtigt werden, wird dtCutOff auf den niedrigsten Datumswert gesetzt, der möglich ist. Das ist in LotusScript der 31.12.1899. Demzufolge hätten wir das Datum so setzen können:

260

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Dim dtCutOff As New NotesDateTime("31.12.1899")

Einfacher ist allerdings der im Beispiel gewählte Weg, einen Leerstring zu übergeben. Aufgrund der Defaulteinstellung der Klasse NotesDateTime wird dann automatisch das frühestmögliche Datum gewählt. Der andere zu besprechende Parameter wurde mit 0 angegeben. Mit diesem Parameter kann festgelegt werden, wie viele gefundene Dokumente maximal zurückgegeben werden sollen. Da wir hier keine Einschränkung wünschen, haben wir den Wert 0 übergeben. Damit werden sämtliche gefundenen Dokumente berücksichtigt. Diese Funktion können Sie nun im Modul Datenbank-Script der Datenbank Kontaktmanagement einfügen. Kommentieren Sie anschließend im ebenfalls dort angesiedelten PostOpen()-Eventhandler die Zeile nKontakteFürHeute = GetAnzahlHeuteFälligerKontakte()

aus. Nach dem Abspeichern sollte die Messagebox beim Öffnen der Datenbank die tatsächliche Anzahl der zur Bearbeitung fälligen Kontakte zurückgeben. Haben Sie es ausprobiert? Dann wissen Sie, dass es so nicht funktioniert. Die Selektionsformel wird angemahnt. Zu Recht. Denn wir haben mitten in das NotesMakro einen Script-Zeilenumbruch mit dem Zusammenhaltesymbol »_« geschrieben. Da es sich bei den durch den Zeilenumbruch getrennten Teile nicht um ScriptCodestücke, sondern um einen geschlossenen String handelt, wird das Zusammenhaltesymbol vom Script-Compiler nicht etwa entfernt, sondern genauso belassen und an den Formelinterpreter weitergereicht. Der kann damit aber nichts anfangen. Wir müssen also den Zeilenumbruch verschieben: sSelection = |Form = "Kontakt" & @Date(NächsterZeitpunkt) <= @Today|

Übrigens, im »richtigen Leben« würden wir nicht so viele Zeilenumbrüche einführen, da der Script-Editor an einem genügend großen Bildschirm viel längere Zeilen anzeigen kann, ohne dass der Entwickler hin- und herscrollen muss. Lediglich die Breitenbeschränkungen der Buchseiten machen die häufigen Umbrüche notwendig. Sollte sich die Datenbank nach dieser Ausprogrammierung weigern, das PostOpen()-Event aufzurufen, schließen Sie einfach den Designer, soweit geöffnet. Anschließend wird das PostOpen()-Event beim Öffnen der Datenbank reagieren. (Eines der typischen Notes-Probleme, die einen aufgrund von fehlenden oder schwer zu interpretierenden Fehlermeldungen zur Weißglut treiben können. Aber nicht Bange machen lassen. Es gibt fast immer eine Lösung!) Die Meldung, die Sie erhalten, wenn nur ein Kontakt ansteht (Abbildung 19.4).

Dokumente finden und darauf zugreifen

261

Abbildung 19.4: Meldung, wenn nur ein Kontakt ansteht

Grundsätzlich ist noch zu empfehlen, eine Unterscheidung beim Meldungstext einzuführen, je nachdem, ob die Ein- oder die Mehrzahl angebracht ist oder ob überhaupt kein Kontakt zur Bearbeitung ansteht. Dann sieht der Code für den PostOpen()-Handler wie folgt aus: Sub Postopen(Source As Notesuidatabase) Dim nKontakteFürHeute As Long nKontakteFürHeute = GetAnzahlHeuteFälligerKontakte() If nKontakteFürHeute = 0 Then Messagebox "Für heute ist kein Kontakt zu erledigen", _ 32, "Zu erledigen" Elseif nKontakteFürHeute = 1 Then Messagebox "Für heute ist " & nKontakteFürHeute & _ " Kontakt zu erledigen", 32, "Zu erledigen" Else Messagebox "Für heute sind " & nKontakteFürHeute & _ " Kontakte zu erledigen", 32, "Zu erledigen" End If End Sub

Die entsprechenden Meldungen (Abbildung 19.5 - Abbildung 19.7).

Abbildung 19.5: Meldung, wenn kein Kontakt ansteht

Abbildung 19.6: Meldung, wenn nur ein Kontakt ansteht

262

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Abbildung 19.7: Meldung, wenn mehrere Kontakte anstehen

19.4.3 Suchmöglichkeiten in NotesView In einer NotesView haben Sie zunächst einmal die gleichen Suchmöglichkeiten wie in der vorhin beschriebenen NotesDocumentCollection. Darüber hinaus stehen weitere Methoden zur Verfügung, die unten in Tabelle 19.5 zusammengefasst sind. Mit R5 sind in Bezug auf NotesViews zwei neue Klassen eingeführt worden. Die Klasse NotesViewEntryCollection bezeichnet die Containerklasse für eine Menge von NotesViewEntries. Die Klasse NotesViewEntry hingegen steht für einen einzelnen Eintrag in der View. Ein NotesViewEntry steht für eine beliebige Zeile in einer NotesView. Dies können die Spaltenwerte sein, mit denen ein Dokument angezeigt wird. Darüber hinaus kann ein NotesViewEntry eine Ansichtskategorie, eine Summenzeile oder auch eine Zeile sein, die für ein Konfliktdokument steht. Wenn der NotesViewEntry die Zeile eines angezeigten Dokuments wiedergibt, können Sie das im Hintergrund stehende Dokument über die Eigenschaft Document erhalten. Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

AllEntries

NotesViewEntry-Collection

X

Alle Einträge in der Ansicht, sortiert in der Reihenfolge der zugrunde liegenden Ansicht.

Tabelle 19.4: Eigenschaft der NotesView-Klasse, die der Rückgabe von Einträgen dient

Method en Name FTSearch

Datentyp

R5

Beschreibung Führt auf der Ansicht eine Volltextsuche durch. Die Ansicht zeigt anschließend nur noch die gefilterten Dokumente an. Der Rückgabewert zeigt die Anzahl der gefundenen Dokumente an.

Dokumente finden und darauf zugreifen

263

Name

Datentyp

R5

Beschreibung

GetAllDocumentsByKey

NotesDocumentCollection

GetAllEntriesByKey

NotesViewEntryCollection

GetChild

NotesDocument

Gibt das Kind-Dokument zu dem übergebenen Dokument zurück (falls vorhanden).

GetDocumentByKey

NotesDocument

Analog zur Methode GetAll-DocumentsByKey. Im Unterschied zu dieser wird hier nur das jeweils erste Trefferdokument zurückgegeben.

GetEntryByKey

NotesViewEntry

GetParentDocument

NotesDocument

Gibt das Eltern-Dokument zu dem übergebenen Dokument zurück (falls vorhanden).

GetPrevSibling

NotesDocument

Gibt das nächste Bruder-Dokument zurück. Näheres dazu siehe Notes-Hilfe.

Gibt sämtliche Dokumente aus, die über einen Schlüssel in der Ansicht gefunden werden. Die Suche wird über die erste sortierte Spalte der Ansicht geführt. X

X

Analog zur Methode GetAll-DocumentsByKey, allerdings für NotesViewEntryObjekte.

Analog zur Methode Get-DocumentByKey, allerdings für NotesViewEntry-Objekte.

Tabelle 19.5: Methoden der NotesView-Klasse, die der Suche in einer Ansicht dienen

G e t A ll llD D o c u m e n t sB y K e y ( ) Wir hätten statt der Search()-Methode in der NotesDatabase im Beispiel des letzten Abschnitts auch eine entsprechende Ansicht verwenden können. Diese Ansicht müsste in irgendeiner Weise eine Datumsauswahl für uns treffen. So könnten wir eine Ansicht bauen, die in der ersten sortierten Spalte das Datum für die nächste Kontaktaktion (Feld NächsterZeitpunkt) anzeigt. Dann könnten wir die NotesView-Methode GetAllDocumentsByKey() verwenden. Als Rückgabewert würden wir wie bei der Search()-Methode eine NotesDocumentCollection erhalten, so dass die übrige Verarbeitung analog zum vorigen Beispiel ist. Syntax GetDocumentByKey(), GetAllDocumentsByKey(): Set notesDocument = notesView.GetDocumentByKey ( keyArray [ , exact% ] ) Set notesDocumentCollection = notesView.GetAllDocumentsByKey ( keyArray [, exact% ] ) Die erste Methode gibt nur das erste gefundene Dokument zurück, die zweite Methode dagegen alle. Der Parameter keyArray beinhaltet die Schlüssel, nach denen gesucht werden soll. Er ist entweder ein skalarer Typ (String, Integer, Long, Single oder Double) oder ein String-Array. Bei skalaren Typen wird in der ersten sortierten Spalte der Ansicht nach einem entsprechenden Wert gesucht. Bei einem Array wird je Arrayelement in einer sortierten Spalte gesucht. Es muss wenigstens eine sor-

264

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

tierte Spalte zur Verfügung stehen, sonst können die beiden Methoden kein passendes Dokument finden (selbst wenn es ein solches gäbe). Wenn der Parameter exact% TRUE ist, werden nur die Dokumente zurückgegeben, deren Spaltenwert exakt dem Suchwert entspricht. Im anderen Fall reicht es aus, wenn lediglich der linke Teil des Spaltenwerts dem Suchwert entspricht. Wir konstruieren zunächst die entsprechende Ansicht. Sie wird ähnlich zur Ansicht »Kontakte« aufgebaut. Sie können sie zunächst als Kopie dieser Ansicht anlegen und dann entsprechend anpassen. Wir nennen diese Ansicht »Kontakte nach Datum«. Der entscheidende Unterschied zur Ansicht »Kontakte« ist, dass hier die Datumsspalte nicht auf das Feld Zeitpunkt, sondern auf das Feld NächsterZeitpunkt abhebt. Wenn eine Zeit angezeigt werden soll, dann muss der Feldname natürlich auch hier angepasst werden.

Abbildung 19.8: Ansicht »Kontakte nach Datum«

Es gilt allerdings noch eine Schwierigkeit zu beheben. Wenn wir die Ansicht so stehen lassen, dann wird die Suche fehlschlagen. Das liegt daran, dass Ansichten alle Werte als Text anzeigen (ausgenommen davon sind die Spalten, die ihren Inhalt als Icon interpretieren). Das bedeutet, dass der Datumswert, den die Formel @Date(NächsterZeitpunkt) zurückgibt, implizit in einen String umgewandelt wird, als würden Sie die Formel so schreiben: @Text(@Date(NächsterZeitpunkt)). Sie können die jetzige Form beibehalten, falls Sie dem Benutzer die Kontakte nach Datum präsentieren wollen.

Dokumente finden und darauf zugreifen

265

Aber für die Suchfunktion müssen wir die obige Ansicht noch ein wenig umbauen, was Sie an einer Kopie nachvollziehen können. Wir haben die Kopie »(Kontakte nach Datum)« benannt, also genauso wie das Original, nur dass sie versteckt wird. Denn die Anzeige, die diese Ansicht produziert, wird einem Betrachter weniger gefallen als der Suchfunktion. Das Entscheidende ist die Umformulierung der Formel in der Spalte »Datum«. Sie erkennen, dass wir das Ergebnisdatum der Formel @Date(NächsterZeitpunkt) mittels der Funktionen @Day(), @Month() und @Year() in seine Bestandteile zerlegen. Die sich ergebenden Zahlen werden in Text umgewandelt und im Falle von Tag und Monat noch auf Zweistelligkeit formatiert. Sodann geben wir das Datum in der Form YYYY.MM.DD zurück, mit anderen Worten »seitenverkehrt«. Dadurch wird gewährleistet, dass unsere Ansicht richtig sortiert ist. Hätten wir den beschriebenen Aufwand nicht betrieben, so würde beispielsweise das Datum 01.10.2000 vor dem 10.09.2000 erscheinen, da dies der Sortierfolge für Text entspricht.

Abbildung 19.9: Suchansicht

Der Beispielcode für die neue Form der Funktion GetAnzahlHeuteFälligerKontakte lautet (wir unterscheiden sie von der vorhergehenden durch den Index 2, da wir sonst beide Formen nicht gleichzeitig im Scriptmodul abspeichern können): Function GetAnzahlHeuteFälligerKontakte2() As Long Dim collection As NotesDocumentCollection Dim session As New NotesSession Dim view As NotesView

266

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

'Zugriff auf die Suchansicht verschaffen Set view = session.CurrentDatabase.GetView("(Kontakte nach Datum)") If view Is Nothing Then Error nERR_NO_VIEW, _ "Die Ansicht ""Kontakte nach Datum"" konnte nicht gefunden " & "werden:" 'Führe Suche aus Set collection = view.GetAllDocumentsByKey(Format(Today, _ "yyyy.mm.dd"), True) 'Wert zurückgeben GetAnzahlHeuteFälligerKontakte2 = collection.Count End Function

Wollen wir den PostOpen()-Eventhandler jetzt auf diese neue Form umstellen, müssen wir nur eine 2 an den Namen der Funktionsbezeichnung anhängen: Sub Postopen(Source As Notesuidatabase) Dim nKontakteFürHeute As Long nKontakteFürHeute = GetAnzahlHeuteFälligerKontakte2() If nKontakteFürHeute = 0 Then Messagebox "Für heute ist kein Kontakt zu erledigen", _ 32, "Zu erledigen" Elseif nKontakteFürHeute = 1 Then Messagebox "Für heute ist " & nKontakteFürHeute & _ " Kontakt zu erledigen", 32, "Zu erledigen" Else Messagebox "Für heute sind " & nKontakteFürHeute & _ " Kontakte zu erledigen", 32, "Zu erledigen" End If End Sub

Sie können nun abspeichern und sich von der korrekten Funktionsweise überzeugen, indem Sie den Designer wieder schließen und die KontaktmanagementDatenbank im Notes-Client öffnen. Übrigens: Sollte die Suche nach wie vor fehlschlagen, dann lohnt es sich nachzusehen, ob die Spalte Datum auch sortiert ist. Dies zu vergessen ist ein sehr beliebter Fehler! FTSearch()

Eine andere Suchmöglichkeit bietet die Methode FTSearch(). Die Syntax ist die gleiche wie bei der Klasse NotesDocumentCollection. Nähere Einzelheiten finden Sie dort. Function GetAnzahlHeuteFälligerKontakte3() As Long Dim session As New NotesSession Dim view As NotesView 'Zugriff auf die Suchansicht verschaffen

Dokumente finden und darauf zugreifen

267

Set view = session.CurrentDatabase.GetView("Kontakte") If view Is Nothing Then Error nERR_NO_VIEW, _ "Die Ansicht ""Kontakte"" konnte nicht gefunden " & _ "werden:" 'Führe Suche aus GetAnzahlHeuteFälligerKontakte3 = view.FTSearch( _ "FIELD NächsterZeitpunkt = " & Format(Today, "dd.mm.yyyy"), 0) End Function

Unser Vorteil ist hier, dass wir die vorher für die Suche speziell neu gebaute Ansicht »(Kontakte nach Datum)« überhaupt nicht benötigen. Denn hier dient die Ansicht selbst nicht zur Suche über Spaltenwerte. Hier dient sie nur dazu, eine Vorauswahl aus den Dokumenten der Datenbank zu treffen, so dass die aufwendigere Volltextsuche nur auf Kontakte beschränkt wird. Gesucht wird über die Werte des Dokumentfelds NächsterZeitpunkt. Ein Nachteil ist allerdings, dass ein Volltextindex angelegt sein sollte. Dies wird nicht immer möglich sein. Zwar arbeitet die Methode auch ohne Index, dann ist sie aber erheblich langsamer. Und das ist nur selten akzeptabel.

19.4.4 Suchmöglichkeiten in NotesDatabase In der Klasse NotesDatabase finden Sie die meisten Möglichkeiten, Dokumente gezielt über bestimmte Informationen zu suchen. Zudem lassen sich über die aufgeführten Suchmethoden in NotesDatabase auch Objekte vom Typ NotesDocumentCollection und NotesView gewinnen, über die man dann zusätzlich zu den Datenbankmethoden auch noch über die in den vorigen Abschnitten skizzierten Möglichkeiten auf Dokumente zugreifen kann. Ei g en s ch af t en Name

Datentyp

AllDocuments

NotesDocumentCollection

R5

Alle Dokumente einer Datenbank

Beschreibung

UnprocessedDocuments

NotesDocumentCollection

Die Dokumente, die vom ausgeführten Script als noch nicht bearbeitet gewertet werden. Es sind nur solche Dokumente eingeschlossen, die von diesem Script noch bearbeitet werden.

Tabelle 19.6: Eigenschaften zur Suche in der NotesDatabase-Klasse

268

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Method en Name

Datentyp

R5

Beschreibung

FTDomainSearch

NotesDocument

X

Volltextsuche über alle im Domänenkatalog eingetragenen Datenbanken, die für die Mehrfachdatenbanksuche markiert sind. Das zurückgegebene Dokument enthält eine formatierte Liste aller gefundenen Dokumente.

FTSearch

NotesDocumentCollection

Führt eine Volltextsuche über alle Dokumente der Datenbank durch.

GetDocumentByID

NotesDocument

Sucht ein Dokument anhand der NoteID.

GetDocumentByUNID

NotesDocument

Sucht ein Dokument anhand der UniversalID.

GetDocumentByURL

NotesDocument

Sucht ein Dokument anhand einer URL.

GetProfileDocCollection

NotesDocumentCollection

GetProfileDocument

NotesDocument

Sucht das angegebene Profildokument. Wenn es gefunden werden kann, wird ein neues angelegt.

Search

NotesDocumentCollection

Führt eine Suche nach Dokumenten über die ganze Datenbank durch. Die Auswahl wird durch eine Makroformel festgelegt.

UnprocessedFTSearch

NotesDocumentCollection

Wie FTSearch mit dem Unterschied, dass nur solche Dokumente eingeschlossen werden, die für das Script als noch unbearbeitet gelten.

UnprocessedSearch

NotesDocument-Collection

Wie Search mit dem Unterschied, dass nur solche Dokumente eingeschlossen werden, die für das Script als noch unbearbeitet gelten.

X

Gibt alle Dokumente eines bestimmten Profils zurück.

Tabelle 19.7: Methoden zur Suche in NotesDatabase

Für die Methode Search, die relativ häufig zum Einsatz kommt, haben wir bereits in Abschnitt 19.4.2, »Suchmöglichkeiten in NotesDocumentCollection«, ein Beispiel angeführt. Diese Methode hat einen großen Vorteil, wenn wir Dokumente suchen, in denen wir anschließend Feldwerte verändern wollen. Würden wir diese Dokumente über eine Ansicht suchen und wären die zu ändernden Feldwerte Bestandteil der Ansichtsselektionsformel, so würden die Dokumente beim Abspeichern eventuell aus der

Mit Dokumenten arbeiten

269

Ansicht herausfallen. Dann hat man in Do Loop- oder auch While Wend-Schleifen, die die gefundenen Dokumente mit GetNextDocument ergreifen, ein Problem. Wie Sie damit umgehen können, finden Sie in Kapitel 18 (Domino-Klassen).

19.5 Mit Dokumenten arbeiten Dokumente tragen die Daten der Notes-Datenbanken in sich. Will man mit den Daten einer Datenbank arbeiten, wird man mit den Dokumenten konfrontiert. Ein Dokument selbst kann man sich wiederum als Container vorstellen; es beherbergt eine unbestimmte Anzahl von NotesItems, die letztlich die eigentlichen Datenträger darstellen. Was kann man mit Notes-Dokumenten tun? Nun, man kann sie erstellen, kopieren, in andere Datenbanken verlegen, löschen, mit weiteren Daten versehen, einzelne Daten löschen und auch modifizieren (Letzteres wird im nächsten Abschnitt diskutiert). Eine besondere Stärke von Notes ist, dass sich diese Dokumente per Mail versenden lassen. Dies alles wird über Eigenschaften und Methoden der Klasse NotesDocument gesteuert. In den beiden folgenden Tabellen finden Sie die Möglichkeiten, die uns in diesem Zusammenhang interessieren. Eigenschaften Name

Datentyp

R5

Beschreibung

EmbeddedObjects

NotesEmbeddedObject Array

Die im Dokument eingebetteten OLE-Objekte. Nicht unterstützt unter OS/2, Unix, Macintosh!

EncryptOnSend

Integer Flag

(Read-Write) Gibt an, ob das Dokument beim Mailversand verschlüsselt wird.

FTSearchScore

Integer

Relevanz hinsichtlich einer Volltextsuche, über die das Dokument erhalten wurde.

HasEmbedded

Integer Flag

Gibt an, ob eingebettete Objekte, Links oder Dateianhänge enthalten sind.

IsProfile

Integer Flag

Handelt es sich um ein ProfilDokument?

IsResponse

Integer Flag

Handelt es sich um ein AntwortDokument?

Items

NotesItem Array

Alle Dokumenten-Items (Felder).

270

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Name

Datentyp

R5

Beschreibung

Key

String

Falls es sich um ein Profildokument handelt, ist hier der Benutzername (= Schlüssel) für das Profildokument abgelegt.

NameOfProfile

String

Falls es sich um ein Profildokument handelt, ist hier der Name des Profils abgelegt.

ParentDatabase

NotesDatabase

Datenbank, in der das Dokument enthalten ist.

ParentView

NotesView

Ansicht, über die auf das Dokument zugegriffen wurde.

Responses

NotesDocumentCollection

Die direkten Antwortdokumente.

SaveMessageOnSend

Integer Flag

(Read-Write) Wenn TRUE, dann wird ein neues Dokument beim Mailversand abgespeichert.

SignOnSend

Integer Flag

(Read-Write) Gibt an, ob das Dokument beim Mailversand unterschrieben wird.

Tabelle 19.8: Eigenschaften zur Dokumentbearbeitung

Method en Name

Datentyp

R5

Beschreibung

FTDomainSearch

NotesDocument

X

Volltextsuche über alle im Domänenkatalog eingetragenen Datenbanken, die für die Mehrfachdatenbanksuche markiert sind. Das zurückgegebene Dokument enthält eine formatierte Liste aller gefundenen Dokumente.

FTSearch

NotesDocumentCollection

Führt eine Volltextsuche über alle Dokumente der Datenbank durch.

AppendItemValue

NotesItem

Erzeugt ein neues Item mit dem übergebenen Inhalt. Dies ist auch der Fall, wenn es schon ein Item mit demselben Namen gibt.

ComputeWithForm

Integer Flag

Berechnet das Dokument mit der im Form-Feld angegebenen Maske. Dabei werden auch die Validierungsformeln durchlaufen.

CopyAllItems CopyItem

Kopiert die Items eines Dokuments auf ein anderes Dokument. NotesItem

Wie CopyAllItems, aber nur für ein einzelnes Item.

Mit Dokumenten arbeiten

271

Name

Datentyp

CopyToDatabase

NotesDocument

Kopiert das gesamte Dokument in eine Datenbank.

CreateReplyMessage

NotesDocument

Erzeugt eine Antwortmail.

CreateRichTextItem

NotesRichTextItem

Erzeugt ein neues RichTextItem auf dem Dokument.

Encrypt

R5

Beschreibung

Verschlüsselt das Dokument.

GetAttachment

NotesEmbeddedObject

Gibt einen spezifizierten Anhang zurück.

GetFirstltem

NotesItem

Gibt das erste Item mit dem spezifizierten Namen zurück. Will man auch die übrigen Items des gleichen Namens erhalten, verwendet man die DokumentEigenschaft Items.

GetItemValue

Variant Array

Gibt die Werte des Items zurück.

HasItem

Integer Flag

Überprüft, ob das Item auf dem Dokument existiert.

MakeResponse

Verwandelt ein unabhängiges Dokument in ein Antwortdokument.

PutInFolder

Legt das Dokument in einem Ordner ab. Falls dieser noch nicht existiert, wird er erzeugt.

Remove

Integer Flag

Löscht das Dokument von der Platte (ohne weitere Nachfrage!).

RemoveFromFolder

Nimmt das Dokument aus einem Ordner.

RemoveItem

Entfernt ein Item. Die Löschung wird erst dann auf die Platte geschrieben, wenn die SaveMethode aufgerufen wird.

RenderToRTItem

Integer Flag

Legt ein Bild des Dokuments in einem RichTextItem ab. Dabei werden Maskenformeln ausgeführt!

ReplaceItemValue

NotesItem

Ersetzt alle Items gleichen Namens durch ein neues. Falls es noch keines gibt, wird ein neues Item angelegt.

Save

Integer Flag

Speichert Dokumentänderungen auf die Platte.

Send Tabelle 19.9: Methoden zur Dokumentbearbeitung

Versendet das Dokument per Mail.

272

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

19.5.1 Neue Dokumente erzeugen Dafür gibt es zwei Möglichkeiten: Syntax New, CreateDocument: Dim notesDocument As New NotesDocument ( notesDatabase ) Set notesDocument = notesDatabase.CreateDocument Bei beiden Möglichkeiten wird in der Datenbank notesDatabase ein neues Dokument angelegt, d. h., es wird im Arbeitsspeicher ein freier Platz dafür geschaffen. Erst nach dem Aufruf der NotesDocument-Methode Save wird es dauerhaft in die Datenbank auf der Platte geschrieben. Doch vorher muss das Dokument noch mit Inhalten gefüllt und im Allgemeinen auch mit einer Maske verbunden werden.

19.5.2 Dokumente speichern Wenn neue Dokumente oder Änderungen an Dokumenten festgehalten, also auf die Platte geschrieben werden sollen, muss explizit die Methode Save der NotesDocument-Klasse aufgerufen werden. Syntax Save: Call notesDocument.Save( force%, createResponse% [ , markRead% ] ) Die ersten beiden Parameter entscheiden darüber, wie im Falle eines auftretenden Konflikts vorgegangen wird. (Ein Konflikt tritt auf, wenn ein anderer Benutzer das Dokument zur gleichen Zeit wie Sie ebenfalls ändert und vor Ihnen abspeichert. Dies ist ein so genannter Speicherkonflikt, im Gegensatz zu einem unter anderen Umständen auftretenden Replikationskonflikt.) Hat der Parameter force% den Wert TRUE, so wird im Konfliktfall das Dokument dennoch gespeichert. Das zuletzt gespeicherte Dokument »gewinnt«. Das ältere wird verworfen. In diesem Fall hat der zweite Parameter (createResponse%) keine Bedeutung. Falls der zweite Parameter (createResponse%) ebenfalls auf TRUE gesetzt ist, wird eine Kopie des vorher vom anderen Benutzer gespeicherten Dokuments als Antwortdokument abgespeichert.

19.5.3 Dokument mit Inhalt füllen Um das Dokument mit Inhalt zu füllen, wird es mit verschiedenen Items versehen, z. B. durch die Methode AppendItemValue oder auch ReplaceItemValue. Syntax AppendItemValue, ReplaceItemValue: Set notesItem = notesDocument.AppendItemValue( itemName$, value ) Set notesItem = notesDocument.ReplaceItemValue( itemName$, value )

Mit Dokumenten arbeiten

273

Mit AppendItemValue wird immer ein neues Item erzeugt, auch wenn im Dokument bereits ein Namensgleiches existiert, und die in value enthaltenen Werte hineingeschrieben. Der Typ des Items richtet sich nach dem Datentyp der in value enthaltenen Werte. Wenn value ein Array mit mehr als einem Element ist, dann enthält das erzeugte Item eine Liste mit diesen Werten. Die obigen Ausführungen gelten bei ReplaceItemValue analog. Der einzige Unterschied ist, dass ein neues Item nur erzeugt wird, wenn noch kein Namensgleiches vorhanden ist, sonst wird dieses überschrieben. Dabei kann sich der Datentyp des Items ändern. Es gilt auf jeden Fall der Typ, der den übergebenen Werten entspricht. Es gibt zu ReplaceItemValue noch eine andere Form, ein Item anzulegen bzw. zu überschreiben. Diese ist kürzer in ihrer Schreibweise und hat die Bezeichnung »Extended Syntax«. Nähere Erläuterungen finden Sie in Abschnitt 19.5.7.

19.5.4 Dokument mit Maske verbinden Bevor ein Dokument angezeigt werden kann, muss es in der Regel noch ein besonderes Item erhalten, das Item Form. In dieses wird der Name der Maske geschrieben, mit der es dem Betrachter präsentiert werden soll.

19.5.5 Items anzeigen Eine Maske ist praktisch ein Guckloch auf das Dokument. Nur die Items, für die in der Maske Felder vorgesehen sind, werden dem Betrachter präsentiert. Diese Items haben gewöhnlich den gleichen Namen wie die korrelierenden Felder. Natürlich können Sie auch weitere Items im Dokument abspeichern, jedoch sind diese für den Betrachter unsichtbar. Solche unsichtbaren Items können jedoch sehr hilfreich sein und werden häufig verwendet, um Informationen festzuhalten, die eine Applikation im Zusammenhang mit dem Dokument benötigt, z. B. Angaben zum momentanen Status des Dokuments innerhalb eines Workflows.

19.5.6 Extended Syntax Syntax Extended Syntax: notesDocument.item = value value = notesDocument.item Bei der Extended Syntax tut man praktisch so, als wäre das Item schon vorhanden, selbst wenn dies nicht der Fall ist. Wenn auf diese Weise ein Wert zugewiesen wird, dann wird das Item mit diesem Wert so beschrieben, wie in der Erläuterung zur Methode ReplaceItemValue dargelegt wurde. Sollte das Item noch nicht existieren, dann wird es erzeugt. Umgekehrt lassen sich Items mit der Extended Syntax-Methode auch sehr einfach auslesen. Man weist gedanklich das über das Dokument referenzierte Item ganz

274

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

einfach wie eine Eigenschaft einer Variablen vom Typ Variant zu. Der Typ Variant ist wichtig, weil durch diese Zuweisung ein Array zurückgegeben wird. Es ist allerdings auch möglich, ein erwartetes Element per Array-Index auszulesen. In diesem Fall darf der Wert auch einer skalaren Variablen vom passenden Typ zugewiesen werden. Beispiel: Dim sText As String sText = note.Text(0)

Sie müssen natürlich wissen, ob es das indizierte Arrayelement überhaupt gibt. Würden wir im letzten Beispiel statt des Index 0 den Index 2 wählen, und das Item hätte nur einen oder zwei Einträge, dann würde der Zugriff auf das nicht vorhandene dritte Element einen Fehler verursachen. Beim Einsatz der Extended Syntax-Syntax zum Abfragen von Objekteigenschaften müssen Sie auf die Wahl eines passenden Index achten. Sie können ihn auch weglassen. Dann muss die Rückgabevariable auf jeden Fall ein Variant sein. Von der obigen Regel gibt es eine Ausnahme: Wenn das Item leer oder gar nicht vorhanden ist, wird über die Extended Syntax-Syntax dennoch ein Array zurückgegeben, und zwar eines mit einem einzigen Element mit einem Leerstring.

19.5.7 Beispiele und weitere Syntaxangaben Er ze ug e ei e i n ne n e u e s D ok um e n t i n d e r g le i c h e n D a t e n b a n k Sub Click(Source As Button) On Error Goto ErrorHandler Dim session As New NotesSession Dim db As NotesDatabase Dim note As NotesDocument Set db = session.CurrentDatabase

'Datenbank, in der das Script 'läuft Set note = db.CreateDocument 'Neues Dokument erzeugen Call note.ReplaceItemValue("Form", "Person") 'Mit Maske Person verbinden note.Nachname = "Meier" 'Item mit Daten anlegen note.Vorname = "Hugo" 'Item mit Daten anlegen Call note.Save(True, False) Exit Sub

Mit Dokumenten arbeiten

275

ErrorHandler: Print "Error occured while creating document: " & Error Exit Sub End Sub

In diesem Beispiel wird die aktuelle Datenbank über die CurrentDatabase-Eigenschaft des NotesSession-Objekts gegriffen, und dann wird darin über die CreateDocument-Methode ein neues Dokument angelegt. Es werden danach auf zwei unterschiedliche Arten Items erzeugt; zunächst das Item »Form« mit der ReplaceItemValue-Methode und dann zwei Items mit der Extended Syntax-Funktionalität. Beide Vorgehensweisen sind in diesem Kontext als gleichwertig anzusehen. Wir haben lediglich aus Anschauungsgründen beide verwendet. Wichtig ist das abschließende Speichern des Dokuments mit der Save-Methode, weil Sie ansonsten das Dokument und seine Items beim Beenden des Programms verlieren würden. Ein Item trägt den Namen »Form«. Dies ist das Item, das das Dokument mit einer Maske verbindet, in diesem Fall die Maske Person. Er ze ug e ei e in D o k u m e n t in e i n e r a n d e re n D a t e n b a n k , p r ü fe a u f b e r e i t s v o r h a n dene Datensätze Sub Click(Source As Button) On Error Goto ErrorHandler Dim db As NotesDatabase Dim note As NotesDocument Dim flag As Integer 'Referenz auf Datenbank erzeugen und öffnen Set db = New NotesDatabase("", "") flag = db.Open("office/BK-Soft", "adressen.nsf") 'Referenz auf Suchansicht erzeugen 'Konstante ERR_NO_VIEW muss vorher definiert werden, oder 'anderen numerischen Wert nehmen Set view = db.GetView("(Personen)") If view Is Nothing Then Error ERR_NO_VIEW, _ "Ansicht nicht gefunden 'Dokument suchen. Abbrechen, falls vorhanden Set note = view.GetDocumentByKey("Meier, Hugo") If note Is Nothing Then Exit Sub 'Neues Dokument anlegen Set note = db.CreateDocument 'Items anlegen und Werte eintragen note.Form = "Person"

276

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

note.VorName = "Sabine" note.NachName = "Bäcker" Call note.Save(True, False) Exit Sub ErrorHandler: Print "Error occured while creating document: " & Error Exit Sub End Sub

Bevor das neue Dokument angelegt wird, wird geprüft, ob der Datensatz nicht bereits existiert. Dazu sucht die Prozedur mit der GetDocumentByKey-Methode der NotesView zunächst ein eventuell bereits vorhandenes Dokument, das den gleichen Datensatz repräsentiert. Ist der Rückgabewert NOTHING, dann ist klar, dass der Datensatz noch nicht existiert, und es wird ein neues Dokument angelegt. Ei n vo r h an d e n e s D o k u m e n t b e ar be i t e n u n d ve r s e n d e n Sub Click(Source As Button) On Error Goto ErrorHandler Dim db As NotesDatabase Dim note As NotesDocument Dim flag As Integer 'Referenz auf Datenbank erzeugen und öffnen Set db = New NotesDatabase("", "") flag = db.Open ("office/BK-Soft", "adressen.nsf") 'Referenz auf Suchansicht erzeugen 'Konstante ERR_NO_VIEW muss vorher definiert werden, oder 'anderen numerischen Wert nehmen Set view = db.GetView("(Personen)") If view Is Nothing Then Error ERR_NO_VIEW, _ "Ansicht nicht gefunden" 'Dokument suchen Set note = view.GetDocumentByKey("Meier, Hugo") 'Neue Items anlegen bzw. neue Werte eintragen 'der Inhalt des Items Subject wird in der Inbox der 'Mail-Datenbank angezeigt. note.ReplaceItemValue("Gehalt", "6000") note.Subject = "Genehmigung Gehaltserhöhung" 'Anschließend Dokument per Mail versenden 'Die Maske wird mitgesandt (Parameterwert True)

Mit Dokumenten arbeiten

277

Call note.Send(True, "Ida Müller") Call note.Save(True, False) Exit Sub ErrorHandler: Print "Error occured while creating document: " & Error Exit Sub End Sub

Es wird das Personen-Dokument von Herrn Hugo Meier gesucht. In dieser Prozedur wird darauf vertraut, dass es existiert. In einer ausgefeilteren Programmierung hätte man eher Grund, dies kritisch zu betrachten und zunächst zu prüfen, ob es überhaupt existiert. Nach Ergreifen des Dokuments werden zwei neue Items angelegt, nämlich »Gehalt« und »Subject«. Das Item Gehalt enthält eine neue Information, während das Feld Subject dazu dient, in der Mail-Datenbank eine Betreffzeile zu präsentieren. Der dann folgende Aufruf von Send schickt das Mail an Frau Ida Müller. Mit dem Parameter TRUE wird dafür gesorgt, dass die Personenmaske im Dokument gespeichert und mitgesendet wird. Das ist deshalb wichtig, weil in der normalen Mailschablone, die von Lotus standardmäßig mitgeliefert wird, keine solche Maske vorhanden ist. Würden wir sie nicht mitsenden, könnte sich der Empfänger das Dokument nicht ansehen. Do ku m e n t e ei e i n e s be s t i mm mmtt e n A l t e rs lö s c h e n Sub Click(Source As Button) On Error Goto ErrorHandler Dim session As New NotesSession Dim db As NotesDatabase Dim collection As NotesDocumentCollection Dim note As NotesDocument Dim i% As Integer Set db = session.CurrentDatabase

'Datenbank, in der das Script 'läuft

Set collection = _ db.Search("@Date(@Created) < @Adjust(@Today; 0,0,-20,0,0,0)") 'Dokumente, die älter als 20 'Tage sind Set note = collection.GetFirstDocument Do While Not(note Is Nothing) Call note.Remove(True) Set note = view.GetFirstDocument 'Nach dem Löschen ist das 'nächste Dokument 'wieder das 'erste aus der Collection

278

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Loop Exit Sub ErrorHandler: Print "Error occured while deleting log-documents: " & Error Exit Sub End Sub

Eine Prozedur von dieser Art wird häufig benötigt, um Datenbanken wie LogDatenbanken von veralteten Daten zu befreien. Das Beispiel führt die Arbeitsweise der Search-Methode in der NotesDocument-Klasse vor Augen. Ei n e D at e i al s D o k um e n t e n a nh nha an g ve r s e n d e n Sub Click(Source As Button) On Error Goto ErrorHandler Dim session As New NotesSession Dim db As NotesDatabase Dim note As NotesDocument Dim richText As NotesRichTextItem Dim embObject As NotesEmbeddedObject Set db = session.CurrentDatabase Set note = db.CreateDocument

'Datenbank, in der das Script 'läuft 'Neues Dokument erzeugen

note.Form = "Dateiversand" 'Mit Maske verbinden note.Subject = "Dateiversand" 'Items mit Daten anlegen note.Body = |Sehr geehrte Damen und Herren, anbei erhalten Sie die gewünschten Dateien als Anhang. Mit freundlichen Grüßen ... | Set richText = New NotesRichTextItem(note, "Anhang") Set embObject = richText.EmbedObject(EMBED_ATTACHMENT, "", _ "C:\Temp\Datei.txt") Call note.Save(True, False) Exit Sub ErrorHandler: Print "Error occured while sending file: " & Error Exit Sub End Sub

Mit Dokumenten arbeiten

279

In diesem Beispiel wird wieder ein neues Dokument erzeugt und mit Werten (Items) gefüllt. Anschließend wird ein besonderes Item angelegt, ein RichTextItem. Dieses dient uns zur Aufnahme eines Datei-Anhangs mit der Methode EmbedObject. Syntax Dim notesRichTextItem As New NotesRichTextItem ( notesDocument, name$ ) Set notesRichTextItem = New NotesRichTextItem ( notesDocument, name$ ) Die Klasse NotesRichTextItem ist von der Klasse NotesItem abgeleitet und beinhaltet daher deren Eigenschaften und Methoden zuzüglich der eigenen. Der Parameter notesDocument referenziert das Dokument, auf dem das neue RichTextItem angelegt werden soll. Der Parameter name$ bezeichnet den Namen des Items. Syntax Set notesEmbeddedObject = notesRichTextItem.EmbedObject ( type%, class$, source$, [ name$ ] ) Ein eingebettetes Objekt kann einem von drei Typen angehören; dies wird durch den Parameter type% bestimmt. type% kann einen von den Werten EMBED_ATTACHMENT, EMBED_OBJECT, EMBED_OBJECTLINK annehmen. Nach dieser Angabe richtet sich, ob das Objekt ein Datei-Anhang, ein OLE-Objekt oder eine OLE-Verknüpfung darstellt. Nur wenn das eingebettete Objekt vom Typ EMBED_OBJECT ist, wird der Parameter class$ benötigt. Er gibt den Klassennamen des OLE-Objekts an. source$ bezeichnet Pfad und Dateinamen im Dateisystem. Der Parameter name$ bezeichnet den Namen des Attachments. Ei n e n Ne w s l e t te r e r st e ll lle e n u n d ve r s e n d e n Mit einem Newsletter können Sie eine bestimmte Menge von Dokumenten schnell und komfortabel in einem anderen Dokument zusammenfassen. Syntax Dim notesNewsletter As New NotesNewsletter ( notesDocumentCollection ) Set notesNewsletter = New NotesNewsletter ( notesDocumentCollection ) Set notesNewsletter = notesSession.CreateNewsletter ( notesDocumentCollection ) In dem Newsletter werden die Dokumente zusammengefasst, die mittels einer NotesDocumentCollection übergeben werden. Um diese Zusammenfassung sichtund nutzbar zu machen, müssen Sie eine der beiden Methoden FormatDocument oder FormatMsgWithDocLinks anwenden. Dadurch wird ein Notes-Dokument erstellt, das im ersten Fall einen »Screenshot« eines ausgesuchten Dokuments enthält. Im anderen Fall wird in dem Zusammenfassungsdokument für jedes enthaltene Dokument ein Link erstellt. Das auf diese Weise erhaltene Dokument kann auf die übliche Weise weiter bearbeitet werden.

280

Auf Datenbanken und Dokumente zugreifen und sie bearbeiten

Syntax Set notesDocument = notesNewsletter.FormatDocument ( notesDatabase, n% ) Set notesDocument = notesNewsletter.FormatMsgWithDoclinks ( notesDatabase ) Der Parameter notesDatabase bezeichnet die Datenbank, in der das NewsletterDokument erstellt werden soll. n% bestimmt das Dokument, das bei der FormatDocument-Methode als »Screenshot« abgebildet werden soll. notesDocument referenziert auf das neu erstellte Zusammenfassungsdokument (= Newsletter-Dokument). In unserem Fall versenden wir das Zusammenfassungsdokument per Mail: Sub Click(collection As NotesDocumentCollection) Dim newsLett As New NotesNewsLetter(collection) Dim note = newsLett.FormatDocument Call note.Send( True, "Anton Müller") End Sub

Ein praktisches Beispiel könnten Log-Dokumente sein, die man dem Administrator zu Beginn eines Tages automatisch zusenden möchte.

02

20

Profildokumente

20.1 Verständnisvoraussetzungen Das Kapitel setzt grundlegende Kenntnisse in der LotusScript-Programmierung voraus.

20.2 Lernziel Es wird gezeigt, wie Datenbank- und Benutzerprofildokumente eingesetzt werden, um Einstellungsdaten zu speichern und zu lesen.

20.3 Was ist ein Profildokument? Profildokumente sind Dokumente einer Notes-Datenbank, die spezifische Werte für die Datenbank oder deren Benutzer speichern. Es gibt im Prinzip zwei Arten von Profildokumenten. Die einen sind datenbankbezogen, die anderen benutzerbezogen. In jeder Datenbank können mehrere Profildokumente beider Arten vorkommen. Profildokumente sind zunächst einmal wie jedes andere Dokument einer NotesDatenbank aufgebaut. Die besondere Eigenschaft dieser Dokumente ist, dass sie in den Ansichten der Datenbank nicht auftauchen, gewissermaßen unsichtbar sind. Außerdem tauchen die Profildokumente bei keiner Suchfunktion der LotusScriptKlassenbibliothek auf. Ausgenommen davon sind die speziellen Suchfunktionen GetProfileDocument und GetProfileDocCollection in der Klasse NotesDatabase. Diese Methoden sind neu in R5 und geben explizit nur Profildokumente zurück. Profildokumente werden schneller gefunden als »normale« Dokumente, da sie im Cache der Datenbank zwischengelagert werden.

20 .3 .1 W ie d ie zw ei un ter schi ed li che n Arte n v o n Pr o fil ild d o kum e nte n e rze ug t we rd en Grundsätzlich beinhalten alle Profildokumente einen Bezug zu einer bestimmten Maske und einem bestimmten Benutzer. Wir bezeichnen sie hier als Benutzerprofildokumente. Über die Angabe dieser Werte können Profildokumente sehr schnell gefunden werden. Es ist weder nötig noch möglich, Ansichten zu bauen, die diese Dokumente beinhalten und indizieren. Es ist also bereits ein »fest verdrahteter« Index vorhanden, der die schnelle Suche entlang dieser beiden Werte ermöglicht.

282

Profildokumente

Be n ut ze r p ro f il ild dokum ente Es kann pro Maske und Benutzer immer nur ein Profildokument existieren. Für jede Maske kann wiederum je Benutzer ein spezielles Profildokument erzeugt werden. D a t e n b a n k - P r o f il d o k um e n t e Gibt man keinen Benutzernamen an, so handelt es sich um ein Datenbank-Profildokument. Für jede Maske kann genau ein Datenbank-Profildokument erstellt werden Wie Sie schon erkennen können, gibt es hinsichtlich des Aufbaus und der Funktionsweise der beiden Arten von Profildokumenten keinerlei Unterschied. Sie werden daher bei den Such- und Bearbeitungs-Funktionen bzw. -Methoden auch nicht unterschieden. Das einzige Kriterium, nach denen sie getrennt werden können, ist, ob bei ihrer Erzeugung ein Benutzername mit angegeben wurde oder nicht.

20.4 Das Arbeiten mit Profildokumenten Ein Datenbank-Profildokument wird in einer Notes-Datenbank genutzt, um Einstellungen für die jeweilige Datenbank zu speichern, welche auf alle Datenbankanwender zutreffen. Dabei können in einer Datenbank mehrere dieser DatenbankProfildokumente enthalten sein.

20 .4 .1 Ers te ll en b zw . Ö ff ffn ne n e ine s D a ten ba nkp ro fi ls Jedes Datenbank-Profildokument erhält einen eindeutigen Namen als Schlüssel, anhand dessen auf das Dokument zugegriffen wird. Das Öffnen eines bestehenden Profildokuments und das Anlegen eines neuen Profildokuments erfolgt über dieselbe Methode. Die Methode für den Zugriff auf Profildokumente unter LotusScript ist »GetProfileDocument« in der Klasse NotesDatabase. Wenn ein Dokument mit dem angegebenen Namen in der Datenbank noch nicht exsistiert, wird es automatisch neu angelegt. Sollte das Profildokument bereits bestehen, wird dieses geöffnet. Die Methode liefert als Rückgabewert das Profildokument als Instanz der NotesDocument-Klasse. Syntax von GetProfileDocument (Datenbankprofil): Set notesDocument = Notes-Datenbank.GetProfileDocument( profilName$ ) Sub Beispiel ’Deklaration Dim session As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument

Das Arbeiten mit Profildokumenten

283

’Ermitteln der aktuellen Datenbank Set db = session.CurrentDatabase ’Ermittelt bestehendes Profil oder legt neues Profil ’(Datenbankprofildokument, da kein Benutzername angegeben) an Set doc = db.GetProfilDocument("DatenbankProfil") ’Ermitteln des Werts des Feldes AnzahlLesungen AnzahlLesung = doc.GetItemValue("AnzahlLesungen")(0) ’Bei Neuem Profildokument ist der Wert des Feldes AnzahlLesung = "" If AnzahlLesung = "" Then MessageBox "Neues Profildokument angelegt" ’Setzen des Feldes AnzahlLesungen auf 1 Call doc.ReplaceItemValue("AnzahlLesungen", 1 ) Else MessageBox "Profildokument "+ CStr(AnzahlLesung) + " gelesen" ’Erhöhen des Feldes AnzahlLesung um 1 Call doc.ReplaceItemValue("AnzahlLesungen ",AnzahlLesungen + 1) End If Rem Speichern des geänderten Dokumentes Call doc.Save(True, False) End Sub

Dieses Beispiel versucht, in der aktuellen Datenbank ein Datenbank-Profildokument mit dem Namen »DatenbankProfil« zu öffnen. Sollte das Profildokument nicht vorhanden sein, so wird es angelegt. Danach wird der Wert des Feldes AnzahlLesungen betrachtet. Wenn es leer ist, dann wurde das Dokument neu angelegt und es wird eine entsprechende Meldung ausgegeben. Danach wird das Feld mit dem Wert 1 initialisiert. Wenn das Feld einen numerischen Wert besitzt, wird dieser angezeigt und danach um 1 erhöht.

20.4.2 Löschen eines Profildokuments Um ein Profildokument zu löschen, muss das Dokument zuerst mit der Methode GetProfileDocument ermittelt werden. Danach kann dieses Dokument mit Hilfe der Methode Remove der LotusScript-Klasse NotesDocument gelöscht werden.

284

Profildokumente

20.5 Die Verwendung von GetProfileDocCollection Eine besondere Möglichkeit, um auf eine Sammlung von Profildokumenten einer Datenbank zuzugreifen, ist die Methode GetProfileDocCollection der LotusScriptKlasse NotesDatabase. Dieser Methode liefert eine Instanz der Klasse NotesDocumentCollection zurück, welche alle Profildokumente der Datenbank enthält, die dem übergebenen Profilnamen entspricht. Diese Methode ist neu unter R5. Syntax GetProfileDocCollection: Set notesDocumentCollection = notesDatabase.GetProfileDocCollection ( profileName$ ) ’Aktuelle Notes Session Dim session As new NotesSession ’aktuelle Datenbank Dim Db As NotesDatabase Set Db = session.CurrentDatabase() ’Profilsammlung aller Profildokumente mit dem Namen Datenbankprofil Dim Col As NotesDocumentCollection Set Col = Db.GetProfileDocCollection("Datenbankprofil") REM Durchwandern aller Dokumente und Ausgabe des Feldinhaltes Message Dim Doc As NotesDocument Set Doc = Col.GetFirstDocument() While Not (Doc is Nothing) MessageBox Doc.GetItemValue("Message")(0) Set Doc = Col.GetNextDocument(Doc) Wend

20.6 Die Benutzerprofildokumente Das Benutzerprofildokument ist im Unterschied zum Datenbank-Profildokument zum Speichern von benutzerspezifischen Daten gedacht. Ein Benutzerprofildokument bezieht sich immer auf einen Benutzer der Datenbank.

20.6.1 Erstellen bzw. Öffnen eines Benutzerprofildokuments Das Öffnen eines Benutzerprofildokuments erfolgt ebenfalls mit der Methode GetProfileDocument der LotusScript-Klasse NotesDatabase. Dazu wird dieser Methode der Name des Profils und der Username als Parameter übergeben. Die Methode liefert dann entweder ein bestehendes Profildokument mit dem angebenden Namen für den gewünschten Benutzer oder legt es für den Benutzer neu an.

Fragen

285

Syntax von GetProfileDocument (Benutzerprofil): Set notesDocument = Notes-Datenbank.GetProfileDocument( profilName$ [, userName$ ] ) ’Aktuelle Notes Session Dim session As new NotesSession ’Aktuelle Datenbank Dim Db As NotesDatabase Set Db = session.CurrentDatabase() ’Benutzerprofildokument Dim Doc As NotesDocument Set Doc = Db.GetProfileDocument("Benutzerprofile", session.CommonUserName) ’Auslesen des Feldes Einstellung MessageBox Doc.GetItemValue("Einstellung")(0)

20.7 Fragen 1. Was sind Profildokumente? 2. Wozu werden sie häufig verwendet? 3. Was ist der Unterschied zwischen einem Datenbank-Profildokument und einem Benutzerprofildokument? 4. Wie viele Profildokumente kann eine Datenbank enthalten? 5. Wie können Sie ein bestimmtes Profildokument in einer Datenbank ermitteln? 6. Wie wird ein Datenbank-Profildokument angelegt? 7. Wie wird ein Benutzerprofildokument erzeugt? 8. Was findet eine »normale« Suchfunktion nicht?

12

21

Lotus Notes-Sicherheit

21.1 Verständnisvoraussetzungen Die Funktionsweise der LotusScript-Sprachelemente sollte bekannt sein. Des Weiteren wird die Kenntnis der OOP unter LotusScript vorausgesetzt.

21.2 Lernziel Sicherheit kann in Notes/Domino auf den unterschiedlichsten Ebenen gewährleistet werden. Es gibt im Wesentlichen zwei Arten der Sicherheit: Zugriffsschutz und Verschlüsselungsmechanismen. Außerdem besteht die Möglichkeit, elektronische Unterschriften zu erstellen und zu überprüfen. Sie lernen in diesem Kapitel die beschriebenen Sicherheitsaspekte und deren Programmiermöglichkeiten unter LotusScript kennen.

21.3 Zugriffsschutz Notes bietet Zugriffsschutz auf verschiedenen Ebenen. Dazu zählt der Schutz auf den Ebenen Server, Datenbank, Ansichten, Dokumente, Abschnitte und Felder. Der Zugriff wird über Zugriffskontrolllisten im Serverdokument, Datenbanken, Ansichten usw. eingeschränkt oder gewährt. Uns werden in diesem Zusammenhang insbesondere die NotesACL (Zugriffskontrollliste der Datenbanken) und Zugriffsbeschränkungen auf Dokumentenebene interessieren. Hier kann mit Script programmiert werden; andere Zugriffsschutzmechanismen sind der Programmierung mit NotesFormelsprache vorbehalten.

21 .3 .1 Note sAC L Die ACL einer Notes-Datenbank wird über Objekte der Klasse NotesACL kontrolliert. Sie erhalten dieses Objekt über eine Eigenschaft von NotesDatabase: Dim acl As NotesACL Set acl = db.ACL

Über dieses Objekt können die allgemeinen Einstellungen der ACL vorgenommen und die Menge der zur Verfügung stehenden Funktionen (Rollen) eingetragen werden. Die Einstellungen zu den einzelnen Einträgen hingegen werden über Objekte vom Typ NotesACLEntry vorgenommen, die über die Klasse NotesACL zu instanziieren sind.

288

Lotus Notes-Sicherheit

Bei den allgemeinen Einstellungen gibt es unter R5 eine Reihe von neuen Möglichkeiten: Setzen von Eigenschaften wie »Konsistente ACL über alle Repliken dieser Datenbank erzwingen« und »Max. Namens- & Kennwortzugriff«. Syntax UniformAccess : notesACL.UniformAccess = flag% flag% = notesACL.UniformAccess Der Parameter flag% kann TRUE oder FALSE sein, je nachdem, ob die Option aktiviert oder deaktiviert werden soll. Syntax AddRole : Call notesACLEntry.AddRole( name$ ) Der Parameter name$ ist der Name der hinzuzufügenden Rolle, eingeschlossen in eckige Klammern. Syntax CreateACLEntry : Call notesACL.CreateACLEntry( name$, level% ) Der Parameter name$ ist der Name der hinzuzufügenden Rolle, eingeschlossen in eckige Klammern. Der Parameter level% steht für einen der sieben möglichen Zugriffslevel, die mit den Konstanten ACLLEVEL_NOACCESS (kein Zugriff), ACLLEVEL_DEPOSITOR (Archivar = darf Dokumente erstellen, aber keines davon lesen, natürlich auch keine anderen Dokumente), ACLLEVEL_READER (Leser), ACLLEVEL_AUTHOR (Autor), ACLLEVEL_EDITOR (Bearbeiter), ACLLEVEL_DESIGNER (Entwickler) und ACLLEVEL_MANAGER (Manager) bezeichnet werden. Dim acl As NotesACL Set acl = db.ACL acl.UniformAccess = True Call acl.AddRole("Bearbeiter") Call acl.CreateACLEntry("Administratoren", ACLLEVEL_MANAGER)

Zuerst wird in dem Beispiel die Option "Konsistente ACL über alle Repliken dieser Datenbank erzwingen" gesetzt. Dann wird die Rolle [Bearbeiter] hinzugefügt und zuletzt wird ein neuer ACL-Eintrag mit Manager-Zugriffsrechten erzeugt.

Zugriffsschutz

289

21.3.2 NotesACLEntry Ein NotesACLEntry repräsentiert einen einzelnen ACL-Eintrag. Er zeichnet sich durch einen Namen, zugeordnete Funktionen (Rollen), einen bestimmten Zugriffslevel und verschiedene Optionen aus. Diese Einträge können wie über das UI gesetzt werden. Neu unter R5 ist die Möglichkeit, den Einträgen auch eine Benutzerart (Person, Gemischte Gruppe, Personengruppe, Server, Servergruppe, Unbestimmt) zuweisen zu können. Dies hat teilweise erhebliche Auswirkungen, da ein Eintrag, der die Benutzerart Server oder Servergruppe aufweist, automatisch Einschränkungen gegenüber einem Eintrag mit der Benutzerart Person oder Personengruppe erhält. Dies gilt auch und insbesondere, wenn die beiden Einträge ansonsten die gleichen Rechte aufweisen. Syntax CanDeleteDocuments : notesACLEntry.CanDeleteDocuments = flag% flag% = notesACLEntry.CanDeleteDocuments Der Parameter flag% kann TRUE oder FALSE sein, je nachdem, ob die Option aktiviert oder deaktiviert werden soll. Die anderen Optionen sind syntaktisch analog aufgebaut. Eine interessante Möglichkeit ist auch, Rollen zu aktivieren und zu deaktivieren. Stellvertretend die Syntax fürs Aktivieren: Syntax EnableRole : Call notesACLEntry.EnableRole( name$ ) Der Parameter name$ ist der Name der zu aktivierenden Rolle, eingeschlossen in eckige Klammern. Dim acl As NotesACL Dim aclEntry As NotesACLEntry Set acl = db.ACL Set aclEntry = acl.GetEntry("Administratoren") aclEntry.CanDeleteDocuments = True Call aclEntry.EnableRole("[Bearbeiter]")

290

Lotus Notes-Sicherheit

21.3.3 Zugriffslevel Insgesamt gibt es sieben verschiedene Zugriffslevel (Kein Zugriff, Archivar, Leser, Autor, Editor, Designer, Manager), die wiederum durch eine Anzahl von Optionen modifiziert werden können. Dabei ist zu beachten, dass nicht bei jedem Level jede Option möglich ist. Gewisse Kombinationen von Zugriffslevel und Option sind auch fest vorgegeben. Für ACL-Einträge gibt es sieben unterschiedliche Zugriffslevel, die über verschiedene Optionen noch weiter verfeinert werden können.

21.3.4 Zusammenspiel verschiedener Einträge Das Zusammenspiel verschiedener Einträge kann außerordentlich komplex sein. Es beginnt mit der Feststellung, dass es zwei Default-Einträge gibt: -Default- und Anonymous. Der Erste kann sowohl für anonyme Notes- als auch Webzugriffe Gültigkeit entfalten, während der Zweite nur für anonyme Webzugriffe gilt. Des Weiteren bricht das Recht des separat eingetragenen Benutzers das Recht irgendeiner Gruppe, in der der Benutzer außerdem noch eingetragen sein mag. Sind einem Benutzer über zwei verschiedene Gruppen unterschiedliche Rechte eingeräumt worden und ist dieser nicht auch noch als Person eingetragen, so kommt das höherwertige Recht der beiden Gruppen zum Zuge. Das Zusammenspiel mehrerer Einträge, durch die einer einzelnen Person unter Umständen gleichzeitig mehrere und unterschiedliche Rechte eingeräumt werden, kann sehr komplex sein. Man sollte sich damit sehr gut auskennen, um keine ungewollten Sicherheitslücken entstehen zu lassen. Umgekehrt könnten auch unbeabsichtigte Sperren auftreten. Be is p i e l: Angenommen, der Benutzer Hugo Meier befindet sich in der Gruppe Administratoren und der Gruppe Bearbeiter. Beide Gruppen sind in der Anwendungsdatenbank Kontakte eingetragen. Die Gruppe Administratoren hat das Recht Manager, die Gruppe Bearbeiter das Recht Editor. Dann »sticht« die Gruppe mit dem höheren Recht. Ist Hugo Meier jetzt noch zusätzlich als Person eingetragen und erhält er das Recht Kein Zugriff, so »sticht« dieser Eintrag die beiden Gruppeneinträge in seinem Fall aus. Hugo hat keinen Zugriff auf die Datenbank Kontakte. Nun möchte auch Sabine Meier-Bohn (die Frau von Hugo Meier) auf die Datenbank Kontakte zugreifen. Sie ist aber weder als Person noch über eine Gruppe eingetragen. Nun »zieht« das Recht -Default-. Glücklicherweise ist hier Autor eingetragen. Daher kann Sabine Dokumente erstellen und die eigenen Dokumente auch bearbeiten. Auf andere Dokumente darf sie nicht zugreifen, es sei denn, dass durch eventuell vorhandene Autorenfelder in Einzelfällen noch zusätzliche Rechte gewährt werden. Weitere Einzelheiten finden Sie in Abschnitt 21.4.1, Autorenfelder.

Zugriffsschutz auf Dokumentenebene

291

In der Datenbank Kontakte sei für den »Maximalen Internet-Zugriff« der Eintrag »Kein Zugriff« eingestellt. Selbst wenn auf dem Server, auf dem die Datenbank liegt, der HTTP-Task laufen würde und serverseitig keinerlei Zugriffsbeschränkungen vorlägen, könnte dennoch kein Internet-Nutzer auf die Datenbank zugreifen. Diese Ausführungen mögen für einen Überblick genügen. Weitere Details finden Sie in den einschlägigen Notes-Hilfedatenbanken. Wichtig war nur, Ihnen zu verdeutlichen, welche enormen Möglichkeiten Sie mit den besprochenen Notes-Klassen haben, um Zugriffsrechte an die unterschiedlichen Nutzer dosiert in unterschiedlichsten Variationen zu erteilen. Doch in den folgenden Abschnitten werden noch eine ganze Reihe weiterer interessanter Möglichkeiten beschrieben. Dabei geht es um den Schutz einzelner Teile der Datenbanken.

21.4 Zugriffsschutz auf Dokumentenebene Es gibt in Notes-Dokumenten zwei Arten von speziellen Feldern, die den Zugriff auf Dokumentenebene regeln: Autoren- und Leserfelder.

21.4.1 Autorenfelder Normalerweise können Personen, die Dokumente erstellt haben und auf die jeweilige Datenbank das Zugriffsrecht Autor haben, diese Dokumente lesen, bearbeiten und löschen. Autorenfelder dehnen nun die Rechte von solchen Personen auf weitere Dokumente aus, und zwar auf bestimmte Dokumente, die sie selbst nicht erstellt haben, die aber ein Autorenfeld besitzen, in dem der Notes-Name dieser Person eingetragen ist. Auch Gruppen- und Rolleneinträge entfalten diese Rechte für Personen, die sich in dieser Gruppe befinden oder die die eingetragene Rolle besitzen. Zur Beachtung: Autorenfelder haben nur für Personen mit Autorzugriff eine Wirkung!

21.4.2 Leserfelder Normalerweise können Personen, die auf eine Datenbank zumindest über das Zugriffsrecht Leser verfügen, alle Dokumente dieser Datenbank lesen. Mit Leserfeldern können Sie nun den Kreis der Personen, die Dokumente unter den erwähnten Voraussetzungen lesen können, einschränken. Denn sobald ein Dokument über mindestens ein Leserfeld verfügt, können nur noch die Personen es lesen, deren Notes-Name in mindestens einem dieser Leserfelder eingetragen ist. Auch Gruppen- und Rolleneinträge entfalten diese Wirkung oder eine Rolle, die die zugreifende Person besitzen mag. Leserfelder haben für alle Personen mit mindestens Leserzugriff die beschriebene Wirkung.

292

Lotus Notes-Sicherheit

21.4.3 Mehrere Autoren- und Leserfelder Wenn ein Dokument mehrere Autoren- und/oder Leserfelder besitzt, so werden sie so betrachtet, als gäbe es insgesamt nur eines von ihrer Art. Hat ein Dokument also beispielsweise zwei Leserfelder und steht im einen die Rolle [Admin] und im anderen die Rolle [Office], so wird das Dokument so behandelt, als hätte es nur ein einziges Feld, in dem beide Einträge zusammen eingetragen sind.

21.4.4 Beispiele Autoren- und Leserfelder sind im Prinzip ganz normale NotesItems, nur dass sie bei der Erzeugung ein spezielles Flag erhalten: Syntax zur Erzeugung von Autoren- und Leserfeldern: Dim itemAuthors As New NotesItem( notesDocument, name$, value, AUTHORS ) Dim itemReaders As New NotesItem( notesDocument, name$, value, READERS ) Die Konstanten AUTHORS und READERS zeigen an, dass es sich um Items vom Typ Autoren bzw. vom Typ Leser handelt. Diese Eigenschaften müssen bei der Erzeugung angegeben werden, da sich die Flags IsAuthors und IsReaders nicht nachträglich beschreiben lassen. Wenn die Items bereits vorhanden sind, müssen sie die gewünschte Ausprägung bereits mitbringen. Sei es, dass sie zu früherer Zeit auf die beschriebene Art erzeugt und abgespeichert worden sind, sei es, dass sie durch Maskenfelder vom Typ Autoren bzw. Leser erzeugt worden sind. Dim note As New NotesDocument(notesDatabase) Dim item As New NotesItem (note, "BerechtigteAutoren", "Heinz Meier", AUTHORS) Dim item As New NotesItem (note, "BerechtigteLeser", "Anton Müller", _READERS) note.Save True, True

Zugriffsschutz auf Dokumentenebene

293

21.4.5 Funktionen (Rollen) Neben den oben bereits beschriebenen ACL-Einträgen können in einer Datenbank auch Funktionen definiert werden. (Diese wurden früher »Rollen« genannt. Daher wird dieser Begriff von vielen Entwicklern weiterhin synonym verwendet.) Gemeint sind Zusätze zu den ACL-Einträgen, die mit diesen Einträgen beliebig verknüpft werden können. Die durch sie gewährten Rechte bzw. die durch sie erzeugten Einschränkungen werden nicht über ACL-Optionen gesteuert, sondern durch die Programmierung der Anwendungssoftware. So kann beispielsweise ein zugriffsbeschränkter Abschnitt in einer Maske die Rollen eines Benutzers überprüfen und das Zugriffsrecht nur solchen Benutzern einräumen, die einer bestimmten Funktion zugeordnet sind. Ein Großteil der Verwendung von Funktionen greift wie beim eben erwähnten Beispiel auf Notes-Formelsprache zurück. Als LotusScript-Entwickler müssen Sie im Wesentlichen nur wissen, dass es Rollen gibt und wie sie wirken. Sie werden die Funktionen dann hauptsächlich im Zusammenhang mit Autoren- und Leserfeldern kennen lernen, denen Sie manchmal die eine oder andere Rolle hinzufügen müssen. Wenn ein Benutzer über die Funktion »Bearbeiter« verfügt und diese Rolle in einem Autorenfeld eines Dokuments eingefügt ist, das er selbst nicht geschrieben hat, so kann er dennoch dieses »fremde« Dokument lesen und bearbeiten. Rollen werden in LotusScript mit ihrem Namen, eingeschlossen in eckige Klammern, verwendet. Damit dieser Mechanismus greift, muss er natürlich über Autorenzugriff auf die in Betracht kommende Datenbank verfügen. Als LotusScript-Entwickler können Sie die Funktionen (Rollen) eines Benutzers abfragen und gewisse Aktionen davon abhängig machen. Des Weiteren können Sie solche Rollen in Autoren- und Leserfeldern verwenden und dadurch zusätzliche Zugriffsrechte vergeben. Rollen werden in LotusScript mit ihrem Namen, eingeschlossen in eckige Klammern, verwendet.

21.4.6 Zusammenfassung Autorenfelder dienen also dazu, Rechte von Autoren auch auf Dokumente auszudehen, die sie selbst nicht erstellt haben. Leserfelder dagegen haben eine einschränkende Wirkung, so dass Dokumente nur noch von Personen gelesen werden können, die in den Leserfeldern aufgeführt sind. Personen können über den Notes-Namen, einen Gruppeneintrag oder auch eine Rolle in solche Felder eingetragen werden.

294

Lotus Notes-Sicherheit

21.4.7 Wichtige Bemerkungen Dokumente, die auf diese Weise vor dem Zugriff geschützt sind, werden in einer Ansicht nicht angezeigt. Allerdings gilt es zu beachten, dass in kategorisierten Ansichten die Kategorien dennoch angezeigt werden, selbst wenn kein einziges Dokument in der Ansicht zu sehen ist (vorausgesetzt, es gibt überhaupt Dokumente, die aufgrund der Ansichtsauswahlformel angezeigt werden könnten). Dadurch kann es passieren, dass trotz der Zugriffsbeschränkungen ungewollt Informationen preisgegeben werden. Durch Kategorisierungen geben manchmal Ansichten ungewollt Informationen preis, obwohl auf die zugrunde liegenden Dokumente nicht zugegriffen werden kann. Um solche Probleme zu vermeiden, dürfen Sie bei kritischen Ansichten entweder keine Kategorien einbauen, oder Sie müssen für verschiedene Personenkreise verschiedene Ansichten bauen, die dann nur für die jeweils berechtigten Benutzer freigegeben werden.

21.5 Verschlüsselungsmechanismen Notes verfügt über zwei Verschlüsselungssysteme: 1. Geheimer Schlüssel 2. RSA-Public-Private-Schlüsselsystem

21.5.1 Geheimer Schlüssel Der »Geheime Schlüssel« wird sowohl zum Ver- als auch zum Entschlüsseln verwendet. Er darf nur solchen Parteien gegeben werden, denen vertraut wird. Der »Geheime Schlüssel« darf nur an Parteien ausgegeben werden, denen man vertraut. Mit diesem Ein-Schlüssel-Verfahren kann nur verschlüsselt, aber nicht elektronisch unterschrieben werden.

21.5.2 Public-Private-Schlüsselpaar Der RSA-Mechanismus bedient sich eines Schlüsselpaares: eines privaten und eines öffentlichen Schlüssels. Der »Private Schlüssel« wird ausschließlich in der ID des Benutzers gespeichert, der öffentliche dagegen wird zwar auch in der ID gespeichert, ist aber darüber hinaus der Öffentlichkeit frei verfügbar. Daher wird er auch im Personendokument des Schlüsselinhabers im Öffentlichen Namens- und Adressbuch hinterlegt.

Verschlüsselungsmechanismen

295

Zum Verschlüsseln wird nun der öffentliche Schlüssel eines Benutzers verwendet. Da dieser Schlüssel frei verfügbar ist, kann praktisch jeder diese Art der Verschlüsselung verwenden. Die Entschlüsselung kann nur demjenigen gelingen, der den privaten Schlüssel besitzt, also dem rechtmäßigen Benutzer der entsprechenden ID. Das Public-Private-Schlüsselpaar besteht aus einem öffentlich verfügbaren und einem privaten, vom Besitzer geheim zu haltenden zweiten Schlüssel. Mit diesem Paar kann verschlüsselt und elektronisch unterschrieben werden.

21.5.3 Verschlüsselung mit LotusScript Was kann man nun mit LotusScript verschlüsseln? Mails, Felder eines Dokuments und Datenbanken. Wenn Sie eine Mail verschicken, bestimmen Sie gleichzeitig über die Option EncryptOnSend, ob sie verschlüsselt werden soll: Syntax EncryptOnSend : notesDocument.EncryptOnSend = flag% flag% = notesDocument.EncryptOnSend Der Parameter flag% ist TRUE, falls das Dokument beim Versenden verschlüsselt werden soll, oder FALSE, falls dies nicht geschehen soll. Wenn die Eigenschaft auf TRUE gesetzt ist, sucht die Send-Methode im Adressbuch nach dem öffentlichen Schlüssel des Empfängers, um die Mail damit zu verschlüsseln. Dann kann nur der Empfänger, der im Besitz des privaten Gegenstücks ist, die Mail wieder entschlüsseln. Allerdings hat die Methode einen kleinen Haken: Falls der öffentliche Schlüssel eines Empfängers nicht gefunden werden kann, dann wird die Mail dieser Person unverschlüsselt zugesandt. Wenn gerade diese Mail abgefangen wird, dann hat die Verschlüsselung der übrigen Mails nicht allzu viel gebracht. Dokumente, die an Mail-in-Datenbanken gesandt werden, werden mit diesem Mechanismus nicht verschlüsselt. Auch dann nicht, wenn die Eigenschaft EncryptOnSend auf TRUE gesetzt ist. Dim note As New NotesDocument(notesDatabase) note.EncryptOnSend = True note.Send True, "Boerries Klatt/BK-Soft"

Felder eines Dokuments werden verschlüsselt, indem bei der Maskendefinition angegeben wird, dass sie verschlüsselt werden sollen. Beim Abspeichern des Dokuments werden die so markierten Felder automatisch verschlüsselt, wenn vorher die NotesDocument-Methode Encrypt ausgeführt wurde.

296

Lotus Notes-Sicherheit

Dim note As New NotesDocument(notesDatabase) note.Encrypt note.Save True, True

Wenn die NotesDocument-Eigenschaft EncryptionKeys nicht gesetzt ist, wird das Dokument mit dem öffentlichen Schlüssel des Benutzers verschlüsselt. Wenn dagegen in der Eigenschaft EncryptionKeys andere Schlüssel eingetragen sind, werden diese Schlüssel verwendet. Nur die Benutzer, die im Besitz des privaten Gegenparts sind, können das Dokument dann entschlüsseln. Achtung: Es werden nur die Items verschlüsselt, deren IsEncrypted-Eigenschaft auf TRUE gesetzt ist.

Syntax IsEncrypted : notesItem.IsEncrypted = flag% flag% = notesItem.IsEncrypted Der Parameter flag% ist TRUE, falls das Item beim Speichern verschlüsselt werden soll, oder FALSE, falls nicht. Dim note As New NotesDocument(notesDatabase) Dim notesItem As NotesItem Set notesItem = note.ReplaceItemValue("Form", "Person") notesItem.IsEncrypted = False Set notesItem = note.ReplaceItemValue("NachName", "Müller") notesItem.IsEncrypted = True Set notesItem = note.ReplaceItemValue("VorName", "Anton") notesItem.IsEncrypted = True note.Encrypt note.Save True, True

In diesem Beispiel werden die Items »VorName« und »NachName« verschlüsselt, das Item Form hingegen nicht. Beachten Sie, dass die Inhalte der Items erst verschlüsselt werden, wenn das Dokument beim Speichern auf die Platte geschrieben wird.

Elektronische Unterschriften

297

21.6 Elektronische Unterschriften Der im vorigen Abschnitt beschriebene RSA-Mechanismus bietet auch die Möglichkeit, elektronische Unterschriften zu erstellen. Zum Erstellen der Unterschrift verwendet der Benutzer seinen privaten Schlüssel. Jemand, der die Echtheit der Unterschrift prüfen will, verwendet dazu den frei verfügbaren öffentlichen Schlüssel des Benutzers. Zum Unterschreiben verwendet der Benutzer seinen nur ihm bekannten privaten Schlüssel. Die Öffentlichkeit kann über das öffentlich verfügbare Gegenstück die Echtheit der elektronischen Unterschrift prüfen. Über Script können Sie ein Dokument elektronisch unterschreiben. Die Unterschrift wird erst durch Abspeichern dauerhaft aufs Dokument geschrieben. Syntax Sign : Call notesDocument.Sign Dim note As New NotesDocument(notesDatabase) Call note.Sign Call note.Save(True, True)

21.7 Fragen 1. Welche Arten des Zugriffsschutzes können Sie in Notes/Domino über LotusScript anbieten? 2. Welche Ebenen, auf denen gezielt vor unberechtigtem Zugriff geschützt werden kann, wurden besprochen? 3. Wie können Sie unter Verwendung von Notes-Klassen die Datenbank-ACL anpassen? 4. Wie können Sie Zugriffsrechte auf Dokumentebene einschränken? 5. Was sind Autoren- und Leserfelder? 6. Welche Unterschiede bestehen zwischen Autoren- und Leserfeldern? 7. Wie erzeugt man Autoren- und Leserfelder? 8. Welche unterschiedlichen Arten der Dokumentverschlüsselung haben Sie kennen gelernt? 9. Wie kann man an Notes-Dokumenten eine elektronische Unterschrift anbringen? 10. Was verstehen Sie im Zusammenhang mit der ACL unter einer Funktion? Was ist eine Rolle? 11. Wo kann der LotusScript-Entwickler Funktionen verwenden?

22

22

ODBC-Schnittstelle

22.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. Von Vorteil wäre es, einen gewissen Einblick in den Aufbau von relationalen Datenbanken zu haben. Dies ist aber nicht unbedingt notwendig.

22.2 Lernziel Sie lernen kennen, wie Sie externe Datenquellen unter Zuhilfenahme der ODBCSchnittstelle in LotusScript-Programme einbinden können. Sie können anschließend Daten aus solchen Quellen abfragen, Daten in solchen Quellen erzeugen und sogar die Datendefinition selbst beeinflussen. Letzteres bedeutet zu wissen, auf welchem Wege man z. B. neue Tabellen anlegen oder bestehende verändern kann usw.

22.3 Was ist ODBC? ODBC ist ein von Microsoft geschaffener Standard zum Zugriff auf Daten verschiedenster Art. Über ODBC kann auf relationale Datenbanken, auf unstrukturierte Datenbanken wie Lotus Notes und sogar auf Textdateien unterschiedlichen Aufbaus zugegriffen werden. ODBC ist ein Standard, der eine einheitliche Schnittstelle zum Zugriff auf Datenquellen der unterschiedlichsten Art ermöglicht. Vereinfacht gesagt ist alles, was dazu benötigt wird, ein ODBC-Treiber, der die Spezifika der zuzugreifenden Daten bzw. DBMS (Datenbank-Managementsysteme) auf den Standard der ODBC-Schnittstelle umsetzt. Im Allgemeinen werden solche Treiber von den Lieferanten der DBMS bereitgestellt. Natürlich gibt es auch solche von Fremdfirmen. Darüber hinaus muss das Betriebssystem des Computers, auf dem ODBC genutzt werden soll, ODBC-Treiber per ODBC-Manager einbinden. Im ODBC-Manager werden die auf dem Rechner installierten ODBC-Treiber und die Verbindungen zu einzelnen Datenbanken/Textdateien verwaltet. Diese Verbindungen werden als »Datenquellen« bezeichnet. Beim Datenzugriff via ODBC greift man auf diese Datenquellen zu.

300

ODBC-Schnittstelle

Über ODBC können Daten eines DBMS oder auch RDBMS (Relationales Datenbank-Managementsystem) gelesen, verändert und geschrieben werden. Über SQLStatements können sogar Änderungen an der Datendefinition vorgenommen werden, also die Struktur der Datenbank verändert werden.

22.4 ODBC in Lotus-Notes/Domino Der ODBC-Zugriff wird in Notes/Domino über das so genannte LS:DO (LotusScriptDatenobjekt) zur Verfügung gestellt. Dabei handelt es sich um die drei Klassen ODBCConnection, ODBCQuery und ODBCResultSet. Sie sind zwar im Standardlieferumfang von Notes enthalten, aber da sie nicht fest in die Scriptumgebung eingebunden sind, müssen sie bei Bedarf per LSX-Aufruf nachgeladen werden. Sodann können diese Klassen genauso verwendet werden wie die Standard-Notes-Klassen. In Notes/Domino wird die ODBC-Schnittstelle über das LS:DO (LotusScriptDatenobjekt) realisiert. Es ist über UseLSX in den Script-Code einzubinden.

22.5 Einsatzgebiete Der Einsatz von LS:DO bietet sich für einen Großteil der Fälle an, bei denen auf Nicht-Notes-Daten zugegriffen werden soll, so zum Beispiel für:

X X X X

vom Benutzer zur Laufzeit definierte Lookups Echtzeit-Abfragen Eingabeprüfungen gegen Nicht-Notes-Daten Vermeidung von Doubletten (doppelte Datensätze)

Notes wird häufig als Frontend zur Dateneingabe in ein größeres System (RDBMS) verwendet. Die Daten können vom Benutzer zunächst unter Zuhilfenahme der starken Kommunikationsmöglichkeiten und Workflow-Unterstützung bearbeitet und schließlich in das RDBMS zur Haltung und Verwaltung von Massendaten transferiert werden. Genauso können Daten aus einem RDBMS nach Notes übernommen, dort bearbeitet und schließlich zu einem definierten Zeitpunkt mit dem RDBMS abgeglichen werden. Allerdings muss dann in den zugehörigen Tabellen des RDBMS ein Flag gesetzt werden, das anzeigt, dass der Datensatz in Bearbeitung und womöglich bereits veraltet ist. Für die oben geschilderten Fälle ist die Performance von LS:DO absolut ausreichend. Das gilt allerdings nicht unbedingt für das Transferieren von Massendaten, so dass diese Technologie hier selten zum Einsatz kommen wird.

Die LS:DO-Klassen

301

22.6 Die LS:DO-Klassen 22.6.1 ODBCConnection Die Klasse ODBCConnection dient dazu, eine Verbindung zur ODBC-Datenquelle aufzubauen und zu verwalten. Außerdem kann sie mehrere Anfragen zu einer Transaktion zusammenfassen, die schließlich ausgeführt oder zurückgeführt werden können (commit bzw. rollback). Die Möglichkeiten, die die Klasse anbietet, sind davon abhängig, welche Möglichkeiten der gegebene ODBC-Treiber zur Verfügung stellt. Daher sollten Sie immer kontrollieren, ob sich die Einstellungen bestimmter Eigenschaften wirklich verändern lassen, da Sie sich hier nicht auf Fehlermeldungen verlassen können. Die Klasse ODBCConnection dient zum Öffnen und Kontrollieren einer Verbindung zur Datenquelle. Sie stellt ggfs. auch Transaktions-Mechanismen zur Verfügung. Zum Beispiel könnte es sein, dass eine Datenquelle den Autocommit-Modus nicht unterstützt. Wenn Sie nun die AutoCommit-Eigenschaft eines ODBCConnectionObjektes auf TRUE setzen, werden Sie zwar keine Fehlermeldung erhalten, aber die Eigenschaft wird den Wert TRUE nicht annehmen. Sie bleibt auf FALSE. Dass Ihre Erwartungen an die ODBC-Verbindung nicht erfüllt werden, realisieren Sie im schlimmsten Fall erst, wenn Ihre Daten im RDBMS durch Inkonsistenzen auffallen. Prüfen Sie aber, ob eine Eigenschaftsänderung wirklich durchgeführt wurde, sind Sie auf der sicheren Seite. Sie sollten sich auch auf keinen Fall darauf verlassen, dass eine neue Version eines ODBC-Treibers genauso funktioniert wie eine frühere. Die Erfahrung lehrt, dass ein Treiber der Version 8.000.400 etwas ganz anderes sein kann als ein solcher der Version 8.000.300. Gleiches gilt auch für das Verhalten der LS:DO-Klassen selbst. Hier gab es in der Vergangenheit sogar innerhalb der Entwicklungsstände des NotesReleases 4.6x erhebliche Abweichungen. Sie sollten bei der Entwicklung einer ODBC-Anbindung also sehr genau darauf achten, auf welchen Versionen Sie sowohl bei der Notes-Software als auch beim ODBC-Treiber aufsetzen und diese Versionen für den laufenden Betrieb als Voraussetzung festschreiben. Wenn Sie diesen Hinweis gewissenhaft beachten, werden Sie mit Ihren ODBC-Anbindungen keine Probleme haben. Beim Arbeiten mit LS:DO und verbundenen ODBC-Treibern müssen Sie sehr genau auf den Einsatz der »richtigen«, also der als problemlos erkannten Versionen achten. Diese sind im Einzelfall durch Testen zu bestimmen.

302

ODBC-Schnittstelle

Ei g en s ch af t en Name

Datentyp

AutoCommit

Integer Flag

R5

(Read-Write) Zeigt an, ob der Autocommit-Modus aktiv ist. Dazu muss die Datenbank diesen Modus unterstützen.

Beschreibung

CommitOnDisconnect

Integer Flag

(Read-Write) Gibt an, ob eingeleitete Transaktionen beim Verbindungsabbau automatisch abgeschlossen oder zurückgefahren werden.

DataSourceName

String

Name der Datenquelle.

GetLSDOMasterRevision

String

Die Revisionsnummer der ODBC-LSX-Datei.

SilentMode

Integer Flag

(Read-Write) Verhindert, dass die LoginDialogbox gezeigt wird.

Der Autocommit-Modus sorgt dafür, dass sämtliche Änderungen sofort und automatisch in die Tabellen des verbundenen RDBMS geschrieben werden. Auf ähnliche Weise bewirkt die Eigenschaft CommitOnDisconnect, dass durchgeführte Änderungen bei einem Abbruch der Verbindung in die Tabellen geschrieben werden, auch wenn Commit nicht explizit aufgerufen wurde. DataSourceName ist der Name der Datenquelle, so wie er im ODBC-Manager des Betriebssystems festgelegt wurde. Die Eigenschaft GetLSDOMasterRevision wurde unter Release 4.6 neu eingeführt. Interessanterweise wurden zu dieser Zeit auch erhebliche Änderungen an den ODBC-Klassen durchgeführt. Und praktische Erfahrungen haben gezeigt, dass die Abwärtskompatibilität nicht immer gewährleistet war (siehe oben). So sollten Sie im Einklang mit der weiter oben geäußerten Warnung immer die Version des LS:DO abfragen und auf diese Weise das Vorhandensein der korrekten Voraussetzungen sicherstellen. Syntax GetLSDOMasterRevision : revisionNumber$ = odbcConnection.GetLSDOMasterRevision Beim Aufbau einer ODBC-Verbindung müssen im Allgemeinen Login-Parameter an die Datenquelle weitergegeben werden (Benutzername, Passwort usw.). Im Standardfall werden sie über eine Login-Promptbox abgefragt. Für Hintergrund-Prozesse können Sie dies natürlich nicht gebrauchen. In diesem Fall geben Sie diese Angaben beim Verbindungsaufbau als Parameter mit und unterdrücken zusätzlich das Aufpoppen der Login-Dialogbox durch Setzen der Eigenschaft SilentMode auf FALSE. Zwar wird das Aufpoppen schon durch Übergabe der korrekten Login-Werte verhindert. Wissen Sie allerdings immer, ob die Werte korrekt sind? Im Falle falscher Angaben würde die Box nämlich ohne die explizite Unterdrückung mit Bestimmtheit aufgerufen.

Die LS:DO-Klassen

303

Method en Name

Datentyp

CommitTransactions

Integer Flag

R5

Schließt alle aufgelaufenen Transaktionen ab.

Beschreibung

ConnectTo

Integer Flag

Baut eine Verbindung zur ODBC-Datenquelle auf.

Disconnect

Integer Flag

Schließt die ODBC-Verbindung.

GetError

Integer

Gibt die Nummer des zuletzt aufgetretenen Fehlers zurück.

GetErrorMessage

String

Gibt die Fehlermeldung zurück, die zu der übergebenen Fehlernummer gehört.

GetExtendedError-Message

String

Gibt eine erweiterte Fehlermeldung zu der übergebenen Fehlernummer zurück.

IsConnected

Integer Flag

Zeigt an, ob die Verbindung noch steht.

IsSupported

Integer Flag

Gibt an, ob eine bestimmte Eigenschaft von der Datenquelle unterstützt wird.

ListDataSources

String Array

Gibt alle Namen der registrierten ODBCDatenquellen zurück.

ListFields

String Array

Gibt alle Feldnamen einer Tabelle zurück.

ListProcedures

String Array

Gibt die Namen aller in der Datenquelle gespeicherten Prozeduren (Stored Procedures) zurück.

ListTables

String Array

Gibt die Namen aller Tabellen der Datenquelle zurück.

RollbackTransactions

Integer Flag

Führt alle eingeleiteten und noch nicht per CommitTransactions abgeschlossenen Transaktionen zurück.

Wie bereits unter dem Stichpunkt Eigenschaften gezeigt, wird der Aufbau einer Verbindung mit der Methode ConnectTo eingeleitet. Die benötigten Parameter und was es in Verbindung mit der Login-Dialogbox zu beachten gilt, entnehmen Sie bitte den dortigen Ausführungen. Mit Disconnect wird eine bestehende Verbindung beendet. Sollen Verbindungen des Öfteren auf- und wieder abgebaut werden, so empfiehlt es sich, das ReferenzObjekt mit dem Scriptbefehl Delete explizit zu löschen. Wie die Erfahrung mit früheren Versionen gezeigt hat, wird ein sauberes Aufräumen des Notes-Caches dann am ehesten gewährleistet. Ansonsten kann es beim mehrmaligen Aufbau der Verbindung zu unerwarteten Ergebnissen kommen. Syntax ConnectTo, Disconnect : flag% = odbcConnection. ConnectTo( dataSourceName$ [ , userID$, password$ ] )

304

ODBC-Schnittstelle

Das Flag flag% zeigt an, ob die Verbindung erfolgreich aufgebaut werden konnte. Hinter dem Parameter dataSourceName$ verbirgt sich der Name der Datenquelle, wie er im ODBC-Manager des Betriebssystems festgelegt wurde. Eventuell erwartet die Datenquelle darüber hinaus Angaben zum Login-Namen des Benutzers (userID$) und das passende Kennwort (password$). In der Vergangenheit kam es in Verbindung mit Oracle-ODBC-Treibern zu einem Problem, wenn eine gewisse Zahl von abgesetzten SQL-Statements überschritten wurde. LS:DO beschwerte sich dann über eine Überschreitung seiner Möglichkeiten. Leider ließ sich nicht feststellen, wonach diese Grenze bemessen wird. Sie variierte ständig. Auch war der Fehler in späteren Versionen nicht mehr festzustellen. Sollte allerdings ein Leser über ein solches Problem stolpern, so hilft nur ständiges Schließen und Wiederaufbauen der Verbindung. Mit IsConnected kann während der Verarbeitung geprüft werden, ob die Verbindung noch besteht. Syntax IsConnected : flag% = odbcConnection.IsConnected Mit dem Öffnen einer Verbindung wird automatisch eine neue Transaktion eröffnet. Sämtliche folgenden Änderungen und SQL-Statements werden vorerst temporär ausgeführt, es sei denn, es gilt der Autocommit-Modus. Sie werden erst dann dauerhaft in die Datenbank geschrieben, wenn die Methode CommitTransactions aufgerufen wird. Das Gleiche geschieht, wenn die Verbindung bei CommitOnDisconnect = TRUE gekappt wird. Dabei ist es egal, welcher Umstand zur Unterbrechung der Verbindung führt. Sollen die bislang lediglich temporär durchgeführten Änderungen zurückgesetzt werden, muss in diesem Fall die Methode RollbackTransactions aufgerufen werden. Gilt CommitOnDisconnect = FALSE, dann wird ein Rollback bei Unterbrechungen automatisch durchgeführt. In diesem Fall müsste ein Commit explizit aufgerufen werden, um die Änderungen in die Datenbank zu schreiben. Syntax CommitOnDisconnect : flag% = odbcConnection.CommitOnDisconnect odbcConnection.CommitOnDisconnect = flag% Eine wichtige Eigenschaft der Klasse ODBCConnection ist, dass Sie über ein und dieselbe Verbindung mit vielen verschiedenen ResultSets arbeiten und auch verschiedene Queries (SQL-Anfragen) absetzen können. Dadurch entfällt häufiges Öffnen von neuen Verbindungen. Dieser Vorteil spart Zeit. Ist dennoch einmal ein neuerliches Öffnen nötig, so wird die neue Verbindung wesentlich schneller geöffnet als die erste, denn ODBCConnection verfügt über einen entsprechenden Cache.

Die LS:DO-Klassen

305

Da die Eigenschaften einzelner Datenquellen aufgrund der Verschiedenartigkeit der ODBC-Treiber oder auch der RDBMS selbst sehr verschieden sein können, besteht die Möglichkeit, über die Methode IsSupported festzustellen, ob eine bestimmte Funktionalität unterstützt wird. Dadurch sind Sie als Entwickler in der Lage, auf solche Unterschiede entsprechend zu reagieren. Die Fehlerbehandlung und die damit verbundenen Methoden GetError, GetErrorMessage und GetExtendedErrorMessage arbeiten bei allen drei LS:DO-Klassen analog. Daher werden sie in einem Extra-Abschnitt nach der Besprechung der Klassen diskutiert. Was noch bleibt, sind die Methoden, deren Namen auf »List« beginnen. Sie geben jeweils Namen zu Datenquellen, Tabellen, Feldern (Spalten) und Prozeduren zurück. Sie können also mit Hilfe dieser Funktionen die für die ODBC-Verbindung wichtigen Informationen über die Struktur der angesteuerten Datenbank erfahren. Be is p i e l Wir möchten unserer Beispielanwendung ermöglichen, neue Kontakte von Notes nach einer relationalen Datenbank (RDBMS) zu transferieren. Notes dient also als Frontend für diese Datenbank. Zu diesem Zweck bauen wir uns eine Access-Datenbank, die eine Tabelle Kontakte enthält (Wer sich die Mühe sparen will, kann die Datenbank von der CD nehmen). Die Tabelle hat im Entwurf das folgende Aussehen (Abbildung 22.1).

Abbildung 22.1: Tabelle »Kontakte«

306

ODBC-Schnittstelle

Für unsere Lernzwecke genügen uns einige wenige Felder: Person, Art und Zeitpunkt der Kontakte. Die Spalte ID dient der automatischen Vergabe eines eindeutigen Schlüssels im RDBMS. Solche Schlüssel werden in RDBMS zum Aufbau von relationalen Zusammenhängen benötigt. Da sie in der Access-Tabelle automatisch generiert werden können, brauchen wir in Notes keine zu erzeugen. Würden wir ein anderes RDBMS wählen, wie z. B. Oracle, dann würden wir uns unter Umständen dort integrierter Sequenzen bedienen, die bei ihrem Aufruf jeweils den nächsten Wert eines eindeutigen Schlüssels liefern. Vor dem Abspeichern der Tabelle können Sie die Datenbank noch durch die Vergabe eines Kennwortes schützen (unter Extras | Zugriffsrechte | Datenbankkennwort zuweisen ...), wie in Abbildung 22.2 gezeigt.

Abbildung 22.2: Datenbank-Kennwort einrichten

Nun muss die Datenquelle dem Betriebssystem bekannt gemacht werden. Unter Windows 9x starten Sie dazu den ODBC-Manager in der Systemsteuerung. Achten Sie unbedingt darauf, die 32-Bit-Variante zu nehmen, da auch Notes R5 mit 32-Bit arbeitet. Registrieren Sie die Datenbank als Benutzer-Datenquelle.

Abbildung 22.3: Tabelle »Kontakte« als ODBC-Datenquelle registrieren

Die LS:DO-Klassen

307

Klicken Sie zum Fortfahren den Button »Hinzufügen...« an. Wählen Sie den richtigen Datenbanktreiber aus (hier MS Access 97-Datenbank). Unter Umständen müssen Sie den benötigten Treiber vorher installieren. Bei Windows 9x wird der Access-Treiber schon mitgeliefert.

Abbildung 22.4: Tabelle Kontakte als ODBC-Datenquelle registrieren: Treiber auswählen

Klicken Sie nun auf Fertig stellen. Im folgenden Dialog geben Sie noch den Namen an, unter dem Sie die Datenquelle über ODBC ansprechen möchten (hier Kontakte). Geben Sie dann über den Button Auswählen... die Lage der Datenbank im Filesystem an:

Abbildung 22.5: Name der Datenquelle festlegen

Nach Klicken des OK-Buttons erscheint wieder der Ausgangsdialog des ODBCManagers. Klicken Sie auch hier auf OK und die Einrichtung ist abgeschlossen.

308

ODBC-Schnittstelle

Wir wollen nun per Script auf unsere neu erzeugte Datenquelle zugreifen. Das Script dazu bringen wir aus Gründen der Übersichtlichkeit und der Wiederverwendbarkeit in einer Bibliothek mit dem Namen ODBC-Verarbeitung unter: Function InterfaceAccessDb Dim oConnection As New ODBCConnection Dim nIsConnected As Integer nIsConnected = oConnection.ConnectTo("Kontakte", _ "Administrator", "password") End Function

Wie Sie sehen, ist es ganz einfach, eine ODBC-Verbindung aufzubauen. Man benötigt dazu lediglich ein Objekt vom Typ ODBCConnection und die Zugangsparameter zur Datenbank. Wenn diese Parameter stimmen, wird die Verbindung erfolgreich aufgebaut, was durch Testen der Variablen nIsConnected (Rückgabewert der Methode ConnectTo) verifiziert werden kann. Der Name der Datenquelle (»Kontakte«) muss zwingend angegeben werden. Wenn die anderen beiden Parameter weggelassen werden, wird beim Versuch, die Verbindung zu erstellen, eine Login-Dialogbox hochpoppen, die den Benutzer nach diesen Angaben befragt. Wollen Sie die ODBC-Verarbeitung im Hintergrund ablaufen lassen (also in einem periodischen Agenten), so ist das Aufpoppen der Dialogbox unerwünscht. Es würde die Anwendung zum Abbruch bringen. Da Sie nicht immer garantieren können, dass die übergebenen Login-Namen und Passwörter korrekt sind, kann dies recht hinderlich sein. Abhilfe schafft hier die Eigenschaft SilentMode. Setzen Sie diese für Hintergrundagenten auf FALSE und fragen Sie nach Aufruf der ConnectTo-Methode den Rückgabewert ab, um auf nicht erfolgreiche Verbindungsversuche entsprechend reagieren zu können. Syntax SilentMode : flag% = odbcConnection.SilentMode odbcConnection.SilentMode = flag% Function InterfaceAccessDb Dim oConnection As New ODBCConnection Dim nIsConnected As Integer oConnection.SilentMode = False nIsConnected = oConnection.ConnectTo("Kontakte", _ "Administrator", "password")

Die LS:DO-Klassen

309

If Not nIsConnected Then Error nERR_NO_ODBC_CONNECTION, _ "Die ODBC-Verbindung zur Datenquelle Kontakte " & _ "konnte nicht aufgebaut werden." End Function

Im nächsten Abschnitt werden wir auf die Tabelle Kontakte zugreifen. Doch möchten wir sichergehen, dass sie vorhanden ist. Dazu verwenden wir die Methode ListTables: Syntax ListTables : tables() = odbcConnection.ListTables( [ dataSource$ [ , userID$ [, password$ ] ] ] ) Der Parameter tables() ist ein Array mit den gefundenen Tabellennamen. Die übrigen Parameter sind optional. Wenn sie angegeben werden, entsprechen sie denjenigen, die bei der Methode ConnectTo verwendet werden. Dim vTables As Variant vTables = oConnection.ListTables If IsNull(ArrayGetIndex(vTables, "Kontakte")) Then _ Error nERR_TABLE_MISSING, "Tabelle Kontakte nicht gefunden."

Diesen Code fügen wir in der Funktion InterfaceAccessDb am Ende ein.

22.6.2 ODBCQuery Die Klasse ODBCQuery dient dazu, Datenbankabfragen in SQL-Form aufzunehmen. Nachdem mit Hilfe einer ODBCConnection die Verbindung zur Datenquelle hergestellt worden ist, wird durch eine Abfrage eine bestimmte Menge von Daten ausgefiltert. Die ODBC-Query wird dazu wie folgt an die ODBC-Connection gehängt: Dim oConnection As New ODBCConnection Dim oQuery As New ODBCQuery Set oQuery.Connection = oConnection

Syntax Connection : Set odbcQuery.Connection = odbcConnection Ein SQL-Statement, das der Eigenschaft SQL zugewiesen wurde, wird beim »Andocken« der ODBCQuery syntaktisch überprüft. Gegebenenfalls wird ein entsprechender Fehler ausgegeben.

310

ODBC-Schnittstelle

Syntax SQL : odbcQuery.Query = sql$ Hinter dem Parameter sql$ verbirgt sich das zu übergebende SQL-Statement als String. Ei g en s ch af t en Name

Datentyp

Connection

ODBCConnection

R5

(Write-Only) Ordnet die SQL-Abfrage einer Verbindung zu.

Beschreibung

QueryExecuteTimeOut

Integer

(Read-Write) Legt die Zeitspanne in Sekunden fest, nach der ein Timeout für eine SQL-Abfrage festgestellt wird.

SQL

String

(Read-Write) Ein SQL-Statement (Datenbankabfrage).

UseRowID

Integer Flag

(Read-Write) Legt fest, ob auf die Tabellen der ODBC-Datenquelle per Zeilennummer zugegriffen wird.

Method en Name

Datentyp

R5

Beschreibung

GetError

Gibt die Nummer des zuletzt aufgetretenen Fehlers zurück.

GetErrorMessage

Gibt die Fehlermeldung zurück, die zu der übergebenen Fehlernummer gehört.

GetExtendedError-Message

Gibt eine erweiterte Fehlermeldung zu der übergebenen Fehlernummer zurück.

Im einfachsten Fall will man bei der Arbeit mit ODBC auf sämtliche Datensätze einer Tabelle zugreifen. In unserem Fall (Tabelle Kontakte) sieht das SQL-Statement so aus: oQuery.Query = "SELECT * FROM Kontakte"

Diese Abfrage ermöglicht uns, nach der Ausführung in sämtlichen Datensätzen zu navigieren. Ganz analog lassen sich auch andere Abfragen gemäß SQL-Syntax formulieren.

Die LS:DO-Klassen

311

D a t e n m a n i p ul a ti o n u n d D a t e n d e f in i t i o n m i tt e l s S Q L Da das SQL-Statement einfach ans RDBMS durchgereicht wird, können mit SQL auch Datenmanipulations- und Datendefinitionsoperationen durchgeführt werden. Zum Beispiel können wir über ODBC eine neue Tabelle anlegen: oQuery.Query = "CREATE TABLE Kontaktarten"

Dies wollen wir in dieser Einführung nicht weiter vertiefen. Das Handbuch des RDBMS beschreibt die weiteren Möglichkeiten der Datenbankbearbeitung per SQL.

22 .6 .3 OD BCR e sultS e t Die Klasse ODBCResultSet steht für das Ergebnis einer SQL-Abfrage oder einer Aktion, die durch Methoden dieser Klasse definiert sind. Das Ergebnis wird zum Client übertragen und kann dort ohne weitere Zugriffe auf das Remote-RDBMS untersucht werden. Wenn das Ergebnis mehrere Datensätze umfasst, kann innerhalb dieser Datensätze sehr schnell navigiert werden. Aus diesen Ausführungen wird klar, dass ResultSets auch dazu dienen können, Datenbankabfragen durch Cacheing zu beschleunigen. Dazu existieren im ODBCResultSet einige Eigenschaften, durch die Sie das Cache-Verhalten beeinflussen können. Dabei geht es im Wesentlichen um die Menge der Datensätze, die bei einem einzelnen ODBC-Zugriff übertragen werden. Ist diese Anzahl hoch, dauert die Übertragung relativ lange und damit ist der erste Ergebnisdatensatz nur verzögert verfügbar. Dafür können Sie anschließend durch die weiteren Ergebnisdatensätze erheblich schneller navigieren. Es sind keine weiteren Remote-Anfragen erforderlich. Die diesbezüglichen Einstellungen sind also nach dem Gesichtspunkt zu wählen, wie sich das Verhältnis von der Anzahl notwendiger Abfragen zur Menge der in einem Ergebnis zu erwartenden Datensätze darstellt. Sind viele verschiedene Abfragen notwendig und ist die jeweils zu erwartende Anzahl an Ergebnisdatensätzen gering, dann sollten je Abfrage auch nur wenige Datensätze übertragen werden. Im umgekehrten Fall wird man die Einstellungen so wählen, dass bei jeder Anfrage möglichst viele Datensätze auf einmal übertragen werden. Die besprochenen Einstellungen sind über die Eigenschaften CacheLimit, FetchBatchSize und MaxRows zu wählen. Sie finden sie in der folgenden Tabelle. Syntax CacheLimit : limit& = odbcResultSet.CacheLimit odbcResultSet.CacheLimit = limit&

312

ODBC-Schnittstelle

Syntax FetchBatchSize size& = odbcResultSet.FetchBatchSize odbcResultSet.FetchBatchSize = size& Syntax MaxRows rows& = odbcResultSet.MaxRows odbcResultSet.MaxRows = rows& Die Parameter limit&, size&, rows& bezeichnen der Reihe nach das Cache-Limit, die Größe für die Eigenschaft FetchBatchSize und die maximale Anzahl der Zeilen. Ein Objekt vom Typ ODBCResultSet wird zur Aufnahme der Ergebnisdatensätze einer Abfrage an das ODBCQuery-Objekt angedockt: Dim oQuery As ODBCQuery Dim oResultSet As ODBCResultSet Set oResultSet.Query = oQuery

Zum Ausführen des SQL-Statements muss nach dem Zusammenschließen von ODBCConnection, ODBCQuery und ODBCResultSet die Methode Execute aufgerufen werden. Syntax Execute : flag% = odbcResultSet.Execute Der Parameter flag% gibt Auskunft darüber, ob das RDBMS die SQL-Anfrage mit Erfolg ausführen konnte. Anschließend kann durch das zurückgegebene Ergebnis navigiert werden. Um Zugriff auf alle Datensätze zu erhalten, die in der Tabelle Kontakte enthalten sind, dient also das folgende Script: Function InterfaceAccessDb Dim Dim Dim Dim Dim Dim

oConnection As New ODBCConnection nIsConnected As Integer oConnection As New ODBCConnection oQuery As New ODBCQuery oResultSet As ODBCResultSet nExecuteResult As Integer

Set oQuery.Connection = oConnection

Die LS:DO-Klassen

313

oConnection.SilentMode = False nIsConnected = oConnection.ConnectTo("Kontakte", _ "Administrator", "password") If Not nIsConnected Then Error nERR_NO_ODBC_CONNECTION, _ "Die ODBC-Verbindung zur Datenquelle Kontakte " & _ "konnte nicht aufgebaut werden." oQuery.Query = "SELECT * FROM Kontakte" Set oResultSet.Query = oQuery nExecuteResult = oResultSet.Execute End Function

Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

CacheLimit

Long

(Read-Write) Die maximale Anzahl der im Cache zu haltenden Zeilen

CurrentRow

Long

(Read-Write) Die Nummer des aktiven Datensatzes im ResultSet (Standort des Cursors)

FetchBatchSize

Long

(Read-Write) Die Anzahl der Datensätze, die bei Anfragen an einem Stück geladen werden

MaxRows

Long

(Read-Write) Die maximale Anzahl der Datensätze, die vom ResultSet geladen werden

Query

ODBCQuery

(Write-Only) Ordnet eine ODBCQuery einem ODBCResultSet zu. Dabei wird die Syntax der SQLAbfrage des ODBCQuery-Objektes auf Korrektheit geprüft.

ReadOnly

Integer Flag

(Read-Write) Gibt an, ob ein ResultSet im ReadOnlyModus arbeitet

Mit den Eigenschaften der ODBCResultSet-Klasse kann ansonsten das Verhalten bei der Ausführung von Abfragen gesteuert werden. Über die Eigenschaft ReadOnly wird das ResultSet vor ungewollten Schreibzugriffen geschützt. Syntax ReadOnly : flag% = odbcResultSet.ReadOnly odbcResultSet.ReadOnly = flag%

314

ODBC-Schnittstelle

Will man ein SQL-Statement an das RDBMS absetzen, so muss der Eigenschaft Query ein Objekt vom Typ ODBCQuery zugewiesen werden. Sobald dies geschieht, wird die Syntax des SQL-Statements gegen das Remote-RDBMS geprüft (mit Einschränkungen, siehe Notes-Hilfe). Die Ausführung des SQL-Statements wird mit der Methode Execute gestartet. Möchten Sie Stored-Procedures ausführen, so dient dazu die Methode ExecProcedure. Natürlich muss das RDBMS Stored-Procedures unterstützen. Haben Sie mit Execute erfolgreich eine SQL-Abfrage getätigt, dann ist der nächste durchzuführende Schritt, zu prüfen, ob die Abfrage Ergebnisse geliefert hat. Dazu dient die Eigenschaft IsResultSetAvailable. Syntax IsResultSetAvailable : flag% = odbcResultSet.IsResultSetAvailable Sodann können Sie durch die Datensätze, die im ResultSet gespeichert sind, navigieren. Dazu wird ein Cursor verschoben, dessen Position zu jeder Zeit über die Eigenschaft CurrentRow abgefragt werden kann. Syntax CurrentRow : RowNumber& = odbcResultSet.ReadOnly odbcResultSet.ReadOnly = rowNumber& Der Parameter rowNumber& bezeichnet die Position der gewünschten Zeile. Die Navigation kann zeilenweise in jeder beliebigen Richtung per NextRow oder PrevRow durchgeführt werden. Möchten Sie zum Anfang zurückkehren oder auch an das Ende springen, stehen Ihnen die Methoden FirstRow und LastRow zur Verfügung. Syntax FirstRow, NextRow, LastRow, PrevRow : flag% = odbcResultSet.FirstRow flag% = odbcResultSet.NextRow flag% = odbcResultSet.LastRow flag% = odbcResultSet.PrevRow Der Parameter flag% gibt Auskunft darüber, ob der entsprechende Datensatz mit Erfolg geladen werden konnte.

Die LS:DO-Klassen

315

Ob Sie am Anfang oder am Ende angekommen sind, erfahren Sie über die Eigenschaften IsBeginOfData und IsEndOfData. Syntax IsBeginOfData, IsEndOfData: : flag% = odbcResultSet.IsBeginOfData flag% = odbcResultSet.IsEndOfData Der Parameter flag% gibt Auskunft darüber, ob der Datensatz, auf dem der Cursor momentan steht, der erste oder der letzte des ResultSets ist. Zu bestimmten Datensätzen können Sie springen, indem Sie die gewünschte Zeile durch die Zeilennummer angeben (die Nummer der Eigenschaft CurrentRow zuweisen) oder durch ein Suchkriterium (LocateRow). Syntax LocateRow : flag% = odbcResultSet.LocateRow( column_id% or column_Name$, value, [ column_id2% | column_Name2$, value2, [column_id3% | column_Name3$, value3 ] ] ) Der Parameter flag% gibt Auskunft darüber, ob ein entsprechender Datensatz gefunden werden konnte. Der gewünschte Datensatz wird über den Suchwert value in derjenigen Spalte gesucht, die an der Position column_id% liegt oder den Namen column_Name$ trägt. Es können gleichzeitig bis zu drei Suchbegriffe verwendet werden. Die jeweils aktuelle Zeile, also diejenige, auf der der Cursor gerade steht, kann feldweise bearbeitet werden. Mit GetValue erhalten Sie den Wert eines Feldes und per SetValue verändern Sie ihn. Syntax GetValue : variable = odbcResultSet.GetValue( { column_id% | column_Name$} [, variable ] ) Call odbcResultSet.GetValue( { column_id% | column_Name$}, variable ) Es gibt zwei Formen von GetValue. In beiden bestimmt der Datentyp der LotusScript-Variable variable, wie der erhaltene Wert zurückgegeben wird. Dazu muss diese Variable in der runden Klammer stehen. Sie kann in der ersten Form weggelassen werden. Dann würde der Wert in der Form zurückgegeben, die durch die ODBCResultSet-Eigenschaft FieldExpectedDataType vorgegeben ist. Die auszulesende Spalte wird über die Position der Spalte oder deren Name (column_id% | column_name$) bestimmt.

316

ODBC-Schnittstelle

Syntax SetValue : flag% = odbcResultSetSetValue( { column_id% | column_Name$ }, value ) Der Parameter flag% gibt Auskunft darüber, ob der Wert in dem spezifizierten Feld geändert werden konnte. Das Feld, in das der Wert value geschrieben werden soll, wird über die Position column_id% oder den Namen column_Name$ bestimmt. Mit der Methode UpdateRow werden die Änderungen temporär in die Tabellen des RDBMS geschrieben. Syntax UpdateRow : flag% = odbcResultSet.UpdateRow Der Parameter flag% gibt Auskunft darüber, ob der Datensatz geschrieben werden konnte. Wenn er den Wert FALSE hat, dann war der Datensatz durch einen anderen Benutzer gesperrt oder die Datenbank lässt nur Lesen zu oder der Datensatz ist mittlerweile von einem anderen Benutzer bearbeitet worden. Neue Zeilen können Sie per AddRow hinzufügen und alte mit DeleteRow löschen. Syntax AddRow : flag% = odbcResultSet.AddRow Der Parameter flag% gibt Auskunft darüber, ob der neue Datensatz erzeugt werden konnte. Er wird mit AddRow lediglich temporär im AddRow-Arbeitsbereich angelegt, nicht im ResultSet selbst. Daher können Sie nicht mit Methoden wie FirstRow, NextRow usw. zwischen diesem temporären Datensatz und den übrigen im ResultSet hin- und hernavigieren. Um auf den temporären Datensatz zu gelangen, verwenden Sie odbcResultSet.CurrentRow = DB_ADDROW Zurück ins ResultSet springen Sie mit CurrentRow, LocateRow, FirstRow oder LastRow. Es kann immer nur einen temporären Datensatz im AddRow-Arbeitsbereich geben. Mit UpdateRow wird dieser ins ResultSet geschrieben und der Arbeitsbereich geschlossen. Syntax DeleteRow : flag% = odbcResultSet.DeleteRow( tableName$ )

Die LS:DO-Klassen

317

Der Parameter flag% gibt Auskunft darüber, ob der Datensatz gelöscht werden konnte. Der Parameter tableName$ verhindert Zweideutigkeiten, die sonst durch eine vorherige SQL-Abfrage entstehen könnten. Da es sein kann, dass sich die Werte im RDBMS während einer Bearbeitung im ResultSet ändern, lässt sich dieser Sachverhalt mit der Methode HasRowChanged klären, bevor Sie ihre Änderungen zurückschreiben, die auf diese Remote-Änderungen treffen würden. Syntax HasRowChanged : flag% = odbcResultSet.HasRowChanged Der Parameter flag% gibt Auskunft darüber, ob der Datensatz seit der letzten Abfrage geändert worden ist. Wenn die ODBCConnection entsprechend eingestellt ist, können Sie viele Änderungen vornehmen, bevor alle auf einen Schlag per Commit festgeschrieben werden. Auch können Sie mit vielen ODBCQueries und vielen ODBCResultSets über eine einzige ODBCConnection arbeiten, so dass alle zusammen über eine einzige Transaktion kontrolliert werden. Syntax CommitTransactions, RollbackTransactions : flag% = odbcConnection.CommitTransactions flag% = odbcConnection.RollbackTransactions Der Parameter flag% gibt Auskunft darüber, ob die Transaktion erfolgreich beendet bzw. im zweiten Fall erfolgreich zurückgesetzt werden konnte. Method en Name

Datentyp

R5

Beschreibung

AddRow

Integer Flag

Fügt dem ResultSet eine neue leere Zeile hinzu.

Close

Integer Flag

Schließt das ResultSet oder nur die mit AddRow angehängte neue Zeile. (Wenn eine solche neue Zeile noch keine Daten enthält, wird sie aus dem ResultSet entfernt.)

DeleteRow

Integer Flag

Löscht die aktuelle Zeile des ResultSets in der zugeordneten Datenbanktabelle.

ExecProcedure

Integer Flag

Führt eine Stored Procedure im Datenbank-System aus.

318

ODBC-Schnittstelle

Name

Datentyp

R5

Beschreibung

Execute

Integer Flag

Führt das SQL-Statement der ODBCQuery aus.

FieldExpectedDataType

Integer

Setzt den Datentyp einer ResultSetSpalte oder gibt ihn zurück. Hat Auswirkungen auf die Typumwandlung vom nativen Datentyp auf den hier angegebenen.

FieldID

Integer

Gibt die Position der Spalte zurück. Ein Feld kann statt über den Namen auch über diese Positions-Nummer angesprochen werden.

FieldInfo

Integer Array

Gibt ein Array mit allen verfügbaren Informationen über ein Feld (Spalte) zurück.

FieldName

String

Gibt den Namen einer über die Positions-Nummer spezifizierten Spalte zurück.

FieldNativeDataType

Integer

Gibt den Datentyp aus der Datenbanktabelle zurück.

FieldSize

Integer

Die maximale Größe der Felddaten.

FirstRow

Integer Flag

Macht die erste Zeile im ResultSet zur aktuellen.

GetError

Integer

Gibt die Nummer des zuletzt aufgetretenen Fehlers zurück.

GetErrorMessage

String

Gibt die Fehlermeldung zurück, die zu der übergebenen Fehlernummer gehört.

GetExtendedErrorMessage

String

Gibt eine erweiterte Fehlermeldung zu der übergebenen Fehlernummer zurück.

GetParameter

Variant

Gibt den Wert zurück, der für einen Parameter gesetzt ist.

GetParameterName

String

Gibt den Namen eines über eine Indexnummer spezifizierten Parameters zurück.

GetRowStatus

Integer

Gibt den Änderungszustand der aktuellen Zeile zurück.

GetValue

Hängt vom zu erwartenden Datentyp und den Umwandlungsmöglichkeiten ab.

Gibt den Wert der durch die Positionsnummer spezifizierten Spalte zurück.

HasRowChanged

Integer Flag

Zeigt an, ob sich die Daten in der Datenbanktabelle gegenüber den vorher ins ResultSet geladenen geändert haben.

Die LS:DO-Klassen

319

Name

Datentyp

R5

Beschreibung

IsBeginOfData

Integer Flag

Zeigt an, ob die aktuelle Zeile die erste des ResultSets ist.

IsEndOfData

Integer Flag

Zeigt an, ob die aktuelle Zeile die letzte des ResultSets ist.

IsResultSetAvailable

Integer Flag

Zeigt an, ob das ResultSet durch die letzte Anfrage Daten aus der Datenbank erhalten hat.

IsValueAltered

Integer Flag

Zeigt an, ob der Wert einer ResultSet-Spalte mittels SetValue geändert worden ist.

IsValueNull

Integer Flag

Prüft, ob der Wert einer Spalte NULL ist.

LastRow

Integer Flag

Macht die letzte Zeile des ResultSets zur aktuellen.

LocateRow

Integer Flag

Sucht eine Zeile des ResultSets und macht sie zur aktuellen.

NextRow

Integer Flag

Macht die nächste Zeile zur aktuellen.

NumColumns

Integer

Gibt die Anzahl der Spalten im ResultSet zurück.

NumParameters

Integer

Gibt die Anzahl der Parameter des SQL-Statements im mit dem ResultSet verbundenen ODBCQuery Objekt zurück.

NumRows

Integer

Gibt die Anzahl der Zeilen im ResultSet zurück.

PrevRow

Integer Flag

Macht die vorherige Zeile des ResultSets zur aktuellen.

SetParameter

Integer Flag

Setzt einen neuen Wert für einen Parameter.

SetValue

Integer Flag

Setzt in der spezifizierten Spalte einen neuen Wert.

UpdateRow

Integer Flag

Schreibt die Änderungen einer aktuellen Zeile in die Datenbanktabelle.

Wollen Sie ermitteln, ob die durchgeführte Abfrage überhaupt ein Ergebnis zurückgeliefert hat, fragen Sie die Eigenschaft IsResultSetAvailable ab: nHasResults = oResultSet.IsResultSetAvailable

Unsere Erkenntnisse können wir nutzen, um vor dem Einfügen neuer Datensätze festzustellen, ob es den gleichen Eintrag bereits gibt. Falls also nHasResults = TRUE, dann prüfen wir auf diesen Tatbestand:

320

ODBC-Schnittstelle

If nHasResults Then If Not oResultSet.LocateRow(2, "Anton Müller", _ 3, "Besuch", 4, "04.07.2000") Then 'Datensatz noch nicht vorhanden. Wie ein neuer 'eingefügt wird, wird weiter unten gezeigt End If End If

Warum haben wir die Spaltennummerierung bei 2 und nicht bei 1 beginnen lassen? Weil in der Tabelle Kontakte eine zusätzliche Spalte ID für den Primärschlüssel existiert. Dieser wird beim Erstellen neuer Datensätze automatisch generiert. Die Spaltennummer für diesen Schlüssel ist gerade die übersprungene 1. Ei n f ü ge n ne n e ue r D at e n s ät ze Über die Methoden AddRow und SetValue Datensätze, die noch nicht vorhanden sind, sollen eingefügt werden. Dazu verwenden wir die Methoden AddRow und SetValue. oResultSet.AddRow oResultSet.SetValue "Person", "Anton Müller" oResultSet.SetValue "Art", "Besuch" oResultSet.SetValue "Zeitpunkt", "10.10.1999" oResultSet.UpdateRow oConnection.CommitTransactions

Mit AddRow wird im ResultSet zunächst »Platz geschaffen« und mit SetValue füllen Sie dann die einzelnen Feldwerte auf. Anschließend müssen die eingetragenen Daten in die Tabelle im RDBMS geschrieben werden. Dies übernimmt die Methode UpdateRow. Zum Schluss sorgt CommitTransactions dafür, dass sämtliche aufgelaufenen Veränderungen festgeschrieben werden. Über ein SQL-Statement Wenn Sie die Daten lieber per SQL-Statement einfügen

möchten, können Sie dies wie folgt erledigen: oQuery.SQL = "INSERT INTO Kontakte (Person, Art, Zeitpunkt) _ VALUES ('Susanne Becker', 'Telefonat', '11.10.1999')" oResultSet.Execute oConnection.CommitTransactions

Diese Form kann ihre Vorteile haben, wenn Sie beispielsweise vom RDBMS während der Eingabe gewisse Berechnungen und Typumwandlungen durchführen lassen wollen. Der Nachteil ist, dass Sie in diesem Fall über Kenntnisse in SQL verfügen müssen.

Die LS:DO-Klassen

Das gesamte Script zum Einfügen neuer Kontakte: Function TransferiereKontakte As Integer Dim oConnection As New ODBCConnection Dim oQuery As New ODBCQuery Dim oResultSet As New ODBCResultSet Dim oKontakte As NotesDocumentCollection Dim oKontaktNote As NotesDocument Dim Dim Dim Dim Dim Dim

nIsConnected As Integer nHasResults As Integer nError As Integer sError As String vTables As Variant i%

Dim sPerson As String Dim sArt As String Dim sZeitpunkt As String 'Verbindung aufbauen nIsConnected = oConnection.ConnectTo("Kontakte", _ "Administrator", "password") If Not nIsConnected Then Error nERR_NO_ODBC_CONNECTION, _ "Die ODBC-Verbindung zur Datenquelle Kontakte " & _ "konnte nicht aufgebaut werden." 'Prüfen, ob die zu füllende Tabelle vorhanden ist vTables = oConnection.ListTables If Isnull(Arraygetindex(vTables, "Kontakte")) Then _ Error nERR_TABLE_MISSING, "Tabelle Kontakte nicht gefunden." 'Bereits übergebene Datensätze abfragen oQuery.SQL = "SELECT * FROM Kontakte" Set oQuery.Connection = oConnection Set oResultSet.Query = oQuery If Not oResultSet.Execute = True Then Exit Function nHasResults = oResultSet.IsResultSetAvailable 'Neue Kontakte aus Notes zusammenstellen Set oKontakte = GetKontakte

321

322

ODBC-Schnittstelle

For i% = 0 To oKontakte.Count Set oKontaktNote = oKontakte.GetNthDocument(i%) sPerson = oKontaktNote.Person(0) sArt = oKontaktNote.Art(0) sZeitpunkt = oKontaktNote.Zeitpunkt(0) If nHasResults Then 'Es gab schon Datensätze. If Not oResultSet.LocateRow(2, sPerson, _ 3, sArt, 4, sZeitpunkt) Then 'Aber diesen Datensatz gibt es noch nicht If Not oResultSet.AddRow = True Then _ Exit Function oResultSet.SetValue "Person", sPerson oResultSet.SetValue "Art", sArt oResultSet.SetValue "Zeitpunkt", sZeitpunkt If Not oResultSet.UpdateRow = True Then _ Exit Function End If End If Next i% 'Festschreiben der Veränderungen im RDBMS If Not oConnection.CommitTransactions = True Then Exit Function 'Alle Kontakte konnten erfolgreich verarbeitet werden TransferiereKontakte = True 'Übergebene Kontakte in Notes löschen NotesKontakteLöschen oKontakte End Function Function NotesKontakteLöschen(oKontakte As NotesDocumentCollection) 'Entfernt alle Dokumente einer Collection aus der Notes-Datenbank Dim note As NotesDocument Dim i% For i% = 0 To oKontakte.Count Set note = oKontakte.GetNthDocument(i%)

Der praktische Einsatz von LS:DO

323

note.Remove True Next End Function Function GetKontakte As Variant Dim Dim Dim Dim

session As New NotesSession db As NotesDatabase view As NotesView collection As NotesDocumentCollection

Set db = session.CurrentDatabase Set view = db.GetView("(Kontakte nach Datum)") Set collection = view.GetAllDocumentsByKey(Format(Now, _ "yyyy.mm.dd")) Set GetKontakte = collection End Function

22.7 Der praktische Einsatz von LS:DO LS:DO bietet sich immer an, wenn ein Benutzer einzelne Datensätze im Zusammenhang mit externen Datenquellen bearbeiten möchte. Die einzige Ausnahme bildet im Grunde der Transport oder die Bearbeitung von Massendaten, da LS:DO dafür nicht performant genug arbeitet.

22.8 Fehler Unter Windows 98 scheint es in Verbindung mit Lotus Domino Designer 5.0 verschiedentlich Probleme bei der Einbindung der LS:DO-Bibliothek zu geben. Der Eintrag der Zeile UseLSX "*LSXODBC" wurde bei der Autoreninstallation beim Speichern mit einem Totalabsturz von Domino quittiert. Eine Überprüfung des Registry-Eintrags ergab keinen Fehler. Abhilfe schafft eine komplette Pfadangabe, etwa wie folgt: Uselsx "C:\Programme\Lotus\Notes\nlsxodbc.dll" Dabei ist »nlsxodbc.dll« der Name der Datei, durch die unter Windows die LS:DOKlassen zur Verfügung gestellt werden.

324

ODBC-Schnittstelle

Allerdings kann dies keine Dauerlösung sein, da dieser Dateiname nicht über alle Betriebssysteme hinweg gültig ist. Außerdem liegt diese Datei standardmäßig beim Server in einem anderen Verzeichnis (...\Lotus\Domino) als beim Client (...\Lotus\Notes). Von daher ist zu hoffen, dass Lotus hier in Kürze Abhilfe schafft.

22.9 Fragen 1. Was verstehen Sie unter ODBC? 2. Was ist LS:DO? 3. Wofür kann man LS:DO sinnvollerweise einsetzen? 4. Wie ist die ODBC-Programmierschnittstelle in Notes/Domino aufgebaut? 5. Welchen Funktionen dient ODBCConnection? 6. Welchen Funktionen dient ODBCResultSet? 7. Wozu nutzen Sie die Klasse ODBCQuery? 8. Worauf sollten Sie bei der ODBC-Programmierung unter Notes/Domino besonders achten und auch Ihre Kunden hinweisen?

32

23

Kurzreferenz der Notes/Domino-Klassen

23.1 Zum Gebrauch dieser Referenz Die Referenz zu den Notes/Dominoklassen ist als komprimiertes Werk zum schnellen Nachschlagen gedacht. Sie bietet einen guten Überblick über das vorhandene Angebot an unter LotusScript einsetzbaren Klassen, die mit Notes standardmäßig mitgeliefert werden. Sie kann sowohl demjenigen, der sich in die Dominoklassen einarbeiten möchte, als auch demjenigen, der täglich mit Dominoklassen operiert, eine gute Hilfe zur Orientierung sein. Sie stellt gewissermaßen ein Mittelding zwischen den umfangreichen Texten in der Notes-Hilfedatenbank und der Referenz in der Notes-IDE dar. Sie ist so kurz wie möglich gefasst, bietet dennoch Erläuterungen zu den wesentlichen Aspekten jeder Klasse und der Eigenschaften und Methoden. Diese Referenz ist keineswegs als Ersatz für die umfangreichen Darlegungen in der Notes-Hilfedatenbank gedacht. Die Hilfedatenbank und diese Kurzreferenz ergänzen sich gegenseitig und werden dem Entwickler erst in ihrer Kombination die optimale Hilfestellung bieten. Aus den dargelegten Gründen wurde in den Tabellen auf die Darstellung der zu verwendenden Parameter verzichtet. Lediglich am Anfang jedes Klassenabschnitts werden in den Hinweisen zur Erzeugung bzw. zum Zugriff auf die Objekte der beschriebenen Klassen i. A. die Parameter aufgeführt. Sie werden auch nicht näher erläutert, da sie nach kurzer Übung selbsterklärend sind. Auf diese Weise wollen wir unnötigen Ballast so weit wie möglich vermeiden. Wenn Sie mittels der Kurzreferenz eine Methode oder Eigenschaft gefunden haben, die Ihren Zwecken nützlich sein könnte, nutzen Sie anschließend die Hilfedatenbank, um die Sie interessierenden Details zu erfahren. In der Spalte »R5« wird mit einem Kreuzchen X angezeigt, dass dieses Element erstmals in der Version R5 auftaucht. Ist das Kreuzchen in runde Klammern gesetzt, dann ist die Eigenschaft an sich älter, aber Teilaspekte haben sich gändert. Dies kann beispielsweise ein neuer Parameter sein.

326

Kurzreferenz der Notes/Domino-Klassen

23.2 Button Repräsentiert eine Aktion, einen Hotspot oder eine Schaltfläche. Der Zugriff wird über den Eventhandler gewährt, der auf einen der Events der Button-Klasse hin angestoßen wird, z. B.: Click ( source As Button ) Events Name

Datentyp

R5

Beschreibung

Click

Tritt auf, wenn der Benutzer die Aktion, den Hotspot oder auch die Schaltfläche anklickt bzw. aktiviert.

ObjectExecute

Tritt auf, wenn eine Aktion, ein Hotspot oder auch eine Schaltfläche durch einen OLE2-Server aktiviert wird. Der OLE2-Server muss FX/Notesflow-aktiviert sein.

23.3 Field Repräsentiert ein Maskenfeld. Der Zugriff wird über den Eventhandler gewährt, der auf einen der Events der FieldKlasse hin angestoßen wird, z. B.: Entering ( source As Field ) Events Name

Datentyp

R5

Beschreibung

Entering

Tritt auf, wenn der Cursor in ein Feld springt (funktioniert nur im Edit-Mode des Dokuments).

Exiting

Tritt auf, wenn der Cursor ein Feld verlässt (funktioniert nur im Edit-Mode des Dokuments).

23.4 Navigator Repräsentiert einen Hotspot, eine Schaltfläche oder ein anderes Objekt auf einem Navigator. Der Zugriff wird über den Eventhandler gewährt, der auf den Click-Event hin angestoßen wird: Click ( source As Navigator )

NotesACL

327

Ev en t s Name

Datentyp

R5

Beschreibung

Click

Tritt auf, wenn der Benutzer den Hotspot, die Schaltfläche oder auch ein anderes Objekt anklickt bzw. aktiviert.

23.5 NotesACL Bietet Zugriff auf die Zugriffskontrollliste (ACL) einer Notes-Datenbank. Ein NotesACL-Objekt erhält man über die ACL-Eigenschaft einer Datenbank. Grundsätzlich gilt: Sollen Änderungen, die an dem Objekt vorgenommen werden, in der Datenbank-ACL festgeschrieben werden, so muss nach den Änderungen die Methode Save ausgeführt werden. Dim notesACL As NotesACL Dim notesDatabase As New NotesDatabase( server$, database$ ) Set notesACL = notesDatabase.ACL Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

InternetLevel

Integer

X

(Read-Write) Der eingestellte maximale Internet-Zugriffslevel.

Parent

NotesDatabase

Roles

String Array

UniformAccess

Integer Flag

Die Datenbank, die die ACL beherbergt. Alle Funktionen, die in der ACL definiert sind. X

(Read-Write) TRUE, wenn in der ACL die Option "Konsistente ACL über alle Repliken erzwingen" gesetzt ist.

Method en Name

Datentyp

R5

Beschreibung

AddRole

Fügt der ACL eine Funktion hinzu.

CreateACLEntry

Erstellt in der ACL einen Eintrag. In Verbindung mit OLE-Automation kann ein Objekt vom Typ NotesACLEntry ohne den New-Konstruktor erzeugt werden.

DeleteRole

Löscht eine Funktion aus der ACL.

328

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

GetEntry

NotesEntry

Findet die NotesEntry einer Funktion in der ACL. Die Suche wird auf exakte Übereinstimmung hin geführt. Groß-/Kleinschreibung wird berücksichtigt. Es können nur direkte Einträge in der ACL gefunden werden, also keine Mitglieder von Gruppen, die in der ACL eingetragen sein mögen.

GetFirstEntry

NotesEntry

Gibt den ersten ACL-Eintrag aus.

GetNextEntry

NotesEntry

Gibt den ACL-Eintrag aus, der dem übergebenen Eintrag folgt. Folgt keiner mehr, so gibt die Methode NOTHING zurück.

RenameRole

Ändert den Namen einer ACL-Funktion.

Save

Schreibt die Änderungen, die über das NotesACLObjekt an der ACL durchgeführt worden sind, in die Datenbank.

23.6 NotesACLEntry Ein einzelner Eintrag in einer ACL. Den Zugriff auf einen Eintrag erhält man über die GetXXXEntry-Methoden der Klasse NotesACL. Die Buchstaben »XXX« stehen für die Teilwörter »First«, »Next« usw. Ein neues NotesACLEntry-Objekt wird über den New-Operator oder die CreateACLEntry-Methode von NotesACL erzeugt. Dim notesACLEntry As New NotesACLEntry ( notesACL, name$, level% ) oder Dim notesACLEntry As NotesACLEntry Set notesACLEntry As New NotesACLEntry (notesACL, name$, level% ) Eigenschaften Name

Datentyp

R5

Beschreibung

CanCreateDocuments

Integer Flag

(Read-Write) Zeigt das Recht an, Dokumente zu erstellen. Kann nur in Verbindung mit dem Zugriffslevel Autor verändert werden.

CanCreateLSOrJavaAgent

Integer Flag

(Read-Write) Zeigt das Recht an, LotusScript- oder Java-Agents zu erstellen. Kann nur in Verbindung mit dem Zugriffslevel Reader verändert werden.

NotesACLEntry

329

Name

Datentyp

CanCreatePersonalAgent

Integer Flag

R5

Beschreibung (Read-Write) Zeigt das Recht an, Persönliche Agenten zu erstellen. Kann nur in Verbindung mit dem Zugriffslevel Leser verändert werden.

CanCreatePersonalFolder

(Read-Write) Zeigt das Recht an, Persönliche Ordner zu erstellen. Kann nur in Verbindung mit Zugriffsleveln unterhalb Designer verändert werden.

CanCreateSharedFolder

Integer Flag

X

(Read-Write) Zeigt das Recht an, Gemeinsame Ordner zu erstellen. Kann nur in Verbindung mit dem Zugriffslevel Editor verändert werden.

CanDeleteDocuments

Integer Flag

IsAdminReaderAuthor

Integer Flag

X

(Read-Write) Zeigt das Recht an, Dokumente zu administrieren, zu lesen und zu erstellen.

IsAdminServer

Integer Flag

X

(Read-Write) Zeigt das Recht an, den Server zu administrieren.

IsGroup

Integer Flag

X

(Read-Write) Zeigt an, ob der Eintrag eine Gruppe darstellt.

IsPerson

Integer Flag

X

(Read-Write) Zeigt an, ob der Eintrag eine Person darstellt.

IsPublicReader

Integer Flag

(Read-Write) Zeigt an, ob der Eintrag öffentliche Dokumente lesen kann. Kann nur bei den Zugriffsleveln Kein Zugriff und Archivar verändert werden.

IsPublicWriter

Integer Flag

(Read-Write) Zeigt an, ob der Eintrag öffentliche Dokumente erstellen kann. Kann nur bei den Zugriffsleveln Kein Zugriff, Archivar, Leser und Autor verändert werden.

IsServer

Integer Flag

Level

Integer

(Read-Write) Zugriffslevel des Eintrags.

Name

String

(Read-Write) Name des Eintrags. Darf nicht leer sein.

Parent

NotesAcl

Nur-Lesen. Die ACL, die den Eintrag beherbergt.

(Read-Write) Zeigt das Recht an, Dokumente zu löschen. Kann nur in Verbindung mit dem Zugriffslevel Author verändert werden.

X

(Read-Write) Zeigt an, ob der Eintrag einen Server darstellt.

330

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

Roles

String Array

Nur-Lesen. Die Funktionen, die für den Eintrag aktiviert sind. Jede Funktion ist in eckige Klammern eingeschlossen.

UserType

Integer

(Read-Write) Benutzertyp des Eintrags.

Method en Name

Datentyp

R5

Beschreibung

DisableRole

Deaktiviert eine Funktion.

EnableRole

Aktiviert eine Funktion.

IsRoleEnabled

Integer Flag

Remove

Zeigt an, ob die übergebene Funktion aktiviert ist. Entfernt eine Funktion.

23.7 NotesAgent NotesAgent repräsentiert einen persönlichen oder gemeinsamen Agenten. Es kann nur auf bestehende Agenten zugegriffen werden. Neue Agenten müssen über die IDE erzeugt werden. Die Klasse NotesAgent dient lediglich dazu, einen Agenten laufen zu lassen. Ein NotesAgent-Objekt, das den Agenten repräsentiert, in dem das ablaufende Script liegt, wird über die NotesSession erzeugt: Dim notesAgent As NotesAgent Set notesAgent = notesSession.CurrentAgent Über eine Methode der NotesDatabase-Klasse kann auch auf einen beliebigen darin befindlichen Agenten zugegriffen werden: Dim notesAgent As NotesAgent Set notesAgent = notesSession.GetAgent ( name$ ) Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

Comment

String

Die Beschreibung, die im Agenten eingetragen ist.

CommonOwner

String

Der Name der Person, der der Agent »gehört«. Das ist die Person, die den Agenten zuletzt geändert und anschließend gespeichert hat. Bei einem hierarchischen Namen wird nur der Common-Teil ausgegeben.

NotesAgent

331

Name

Datentyp

R5

Beschreibung

HasRunSinceModified

Integer Flag

X

Zeigt an, ob der Agent seit der Erstellung bzw. der letzten Änderung gelaufen ist.

IsEnabled

Integer Flag

IsNotesAgent

Integer Flag

IsPublic

Integer Flag

IsWebAgent

Integer Flag

LastRun

DateTime-Variant

Gibt das Datum zurück, an dem der Agent das letzte Mal gelaufen ist. Liefert 12:00:00 AM, falls der Agent noch nie gelaufen ist.

Name

String

Der Name des Agenten. Verschiedene Agenten einer Datenbank können den gleichen Namen tragen.

Owner

String

Der Name der Person, der der Agent »gehört«. Das ist die Person, die den Agenten zuletzt geändert und anschließend gespeichert hat. Bei einem hierarchischen Namen wird dieser im Ganzen zurückgegeben.

Parent

NotesDatabase

Die Datenbank, die den Agenten beherbergt.

Query

String

Die Auswahlformel des Agenten, wie sie mit dem Button Suche Hinzufügen... erstellt worden ist. Wurde keine auf diese Weise hinzugefügt, so ist die Query-Eigenschaft leer. Das gilt selbst dann, wenn in der Formel, die der Agent ausführt, Auswahlkriterien angegeben sind.

ServerName

String

(Read-Write) Der Name des Servers, auf dem der Agent läuft. »*« bedeutet: läuft auf allen Servern.

Target

Integer

Trigger

Integer

(Read-Write) Zeigt an, ob der Agent aktiviert ist. Diese Eigenschaft ist für periodische (Hintergrund)-Agenten gedacht. Für andere Agenten liefert sie immer TRUE und kann auch nicht verändert werden. X

Zeigt an, ob der Agent im Notes Client laufen kann. Zeigt an, ob der Agent ein gemeinsamer oder ein persönlicher ist.

X

X

Zeigt an, ob der Agent im Browser laufen kann.

Zeigt an, auf welchen Dokumenten der Agent arbeitet. Zeigt an, auf welches Event oder welchen Anstoß hin der Agent startet.

332

Kurzreferenz der Notes/Domino-Klassen

Method en Name

Datentyp

R5

Beschreibung

Remove

Entfernt einen Agenten dauerhaft aus einer Datenbank. Dies geschieht ohne weitere Maßnahmen, wie z. B. ein nachfolgendes Speichern. Ein nachfolgendes Speichern würde ohnehin einen Fehler ergeben, da das NotesAgent-Objekt nach Ausführung von Remove auf NOTHING gesetzt ist.

Run

Startet den Agenten lokal. Wenn er mit dieser Methode gestartet wird, darf er keine UI-Klassen enthalten.

RunOnServer

Startet den Agenten auf dem Server, auf dem die Datenbank liegt, die den Agenten beherbergt. Wenn er mit dieser Methode gestartet wird, darf er keine UIKlassen enthalten.

Save

Speichert den Agenten.

23.8 NotesDatabase NotesDatabase repräsentiert eine einzelne Notes-Datenbank. Es kann auf bestehende Datenbanken zugegriffen werden und es können neue Datenbanken erzeugt werden. Neue Datenbanken werden nicht mit der New-Methode der Klasse NotesDatabase erzeugt, sondern mit den zugehörigen Methoden Create, CreateCopy, CreateFromTemplate oder CreateReplica. Es gibt viele Möglichkeiten, auf eine Datenbank zuzugreifen. Eine davon ist die New-Methode, die wir hier stellvertretend für die anderen vorstellen: Dim notesDatabase As New NotesDatabase ( server$, file$ ) oder Dim notesDatabase As NotesDatabase Set notesDatabase As New NotesDatabase ( server$, file$ ) Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

ACL

NotesACL

Agents

NotesAgent Array

Alle Agents einer Datenbank

AllDocuments

NotesDocumentCollection

Alle Dokumente einer Datenbank

Zugriffskontrollliste der Notes-Datenbank

NotesDatabase

333

Name

Datentyp

R5

Categories

String

(Read-Write) Die Kategorien, unter denen die Datenbank im Datenbankverzeichnis geführt wird

Created

DateTime

Zeitpunkt der Erstellung

CurrentAccessLevel

Integer

Der Zugriffslevel des Benutzers, unter dem auf die Datenbank zugegriffen wurde

DelayUpdates

Integer Flag

DesignTemplateName

String

Name, den die Datenbank als Schablone trägt.

FileName

String

Name der Datenbank

FilePath

String

Pfad und Name der Datenbank

FolderReferencesEnabled

Integer Flag

Forms

NotesForm Array

IsDirectoryCatalog

Integer Flag

IsFTIndexed

Integer Flag

Ist die Datenbank volltextindiziert?

IsMultiDbSearch

Integer Flag

Gibt an, ob die Datenbank einen Index für die Mehrfach-Datenbanksuche darstellt.

IsOpen

Integer Flag

Ist die Datenbank geöffnet?

IsPrivateAddressBook

Integer Flag

Handelt es sich um ein privates Adressbuch?

IsPublicAddressBook

Integer Flag

Handelt es sich um ein öffentliches Adressbuch?

LastFTIndexed

DateTime

Zeitpunkt, zu dem der Volltextindex das letzte Mal angelegt oder überarbeitet wurde

LastModified

DateTime

Zeitpunkt, zu dem die Datenbank das letzte Mal geändert wurde

Managers

String Array

MaxSize

Double

X

X

Beschreibung

(Read-Write) Gibt an, ob Veränderungen an Dokumenten sofort oder verzögert auf die Platte geschrieben werden (steigert die Performance).

(Read-Write) Gibt an, ob die Datenbank in ihre Notes-Dokumente Ordnerverweise einträgt und verwaltet. Alle in der Datenbank gespeicherten Masken

X

X

Gibt an, ob die Datenbank einen Verzeichniskatalog darstellt.

Array mit den Namen aller Benutzer, die Manager-Zugriff auf die Datenbank haben. Die maximal mögliche Größe der Datenbank

334

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Parent

NotesSession

Die Arbeitssitzung, in der das Script abläuft

PercentUsed

Double

Auslastung der Datenbank in Prozent.

ReplicaID

String

Replik-ID der Datenbank.

ReplicationInfo

NotesReplication

Server

String

Name des Servers, auf dem die Datenbank liegt.

Size

Double

Die aktuelle Größe der Datenbank.

SizeQuota

Long

(Read-Write) Größenbeschränkung der Datenbank

TemplateName

String

Name der Schablone, von der Designveränderungen bezogen werden

Title

String

(Read-Write) Titel der Datenbank

UnprocessedDocuments

NotesDocumentCollection

Die Dokumente, die vom ausgeführten Script als noch nicht bearbeitet gewertet werden. Es sind nur solche Dokumente eingeschlossen, die von diesem Script noch bearbeitet werden.

Views

NotesView Array

Sämtliche Ansichten einer Datenbank als Array.

X

Beschreibung

Replikationseinstellungen. Neu in R5

Method en Name

Datentyp

R5

Compact

Beschreibung Verdichtet eine lokale Datenbank.

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.

CreateDocument

NotesDocument

CreateFromTemplate

NotesDatabase

(X)

Erzeugt ein neues Dokument. Erzeugt eine Datenbankkopie. Der optionale Parameter maxSize% ist neu. Er steht für die Größenbeschränkung von R4-Datenbanken.

CreateOutline

NotesOutline

X

Erzeugt eine neue Gliederung.

CreateReplica

NotesDatabase

Erzeugt eine Datenbankreplik.

NotesDatabase

Name

335

Datentyp

EnableFolder FTDomainSearch

NotesDocument

FTSearch

NotesDocumentCollection

R5

Beschreibung

X

Aktiviert einen Ordner. Falls noch nicht vorhanden, so wird er erstellt.

X

Volltextsuche über alle im Domänenkatalog eingetragenen Datenbanken, die für die Mehrfach-Datenbanksuche markiert sind. Das zurückgegebene Dokument enthält eine formatierte Liste aller gefundenen Dokumente. Führt eine Volltextsuche über alle Dokumente der Datenbank durch.

GetAgent

NotesAgent

Gibt einen Agent zurück.

GetDocumentByID

NotesDocument

Sucht ein Dokument anhand der NoteID.

GetDocumentByUNID

NotesDocument

Sucht ein Dokument anhand der UniversalID.

GetDocumentByURL

NotesDocument

Sucht ein Dokument anhand einer URL.

GetForm

NotesForm

Gibt eine Maske zurück.

GetOutline

NotesOutline

X

Gibt eine Gliederung zurück.

GetProfileDocCollection

NotesDocumentCollection

X

Gibt alle Dokumente eines bestimmten Profils zurück.

GetProfileDocument

NotesDocument

GetURLHeaderInfo

String

GetView

NotesView

GrantAccess

Sucht das angegebene Profildokument. Wenn es gefunden werden kann, wird ein neues angelegt. (X)

Gibt die Headerinformation des HTTPProtokolls der Webressource an der spezifizierten URL zurück. Neu in R5: im URL enthaltene Gedankenstriche werden automatisch zu Unterstrichen konvertiert. Gibt eine Ansicht oder einen Ordner zurück. Richtet eine Zugriffsberechtigung ein.

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 seit einem bestimmten Zeitpunkt geändert wurde.

336

Name

Kurzreferenz der Notes/Domino-Klassen

Datentyp

R5

Beschreibung

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 gehört, dann wird im Fehlerfall versucht, eine Replik auf einem anderen Clusterserver zu öffnen.

QueryAccess

Integer

Remove Replicate

Ermittelt den Zugriffslevel eines bestimmten Benutzers, einer Gruppe oder eines Servers bezüglich der Datenbank. Löscht die Datenbank von der Platte (ohne weitere Nachfrage!).

Integer Flag

RevokeAccess

Stößt eine Replikation an. Das Script hält an, bis die Replikation abgeschlossen ist, und meldet über das Flag das Ergebnis. Eine bestimmte Zugriffsberechtigung widerrufen.

Search

NotesDocumentCollection

Führt eine Suche nach Dokumenten über die ganze Datenbank durch. Die Auswahl wird durch eine Makroformel festgelegt.

UnprocessedFTSearch

NotesDocumentCollection

Wie FTSearch mit dem Unterschied, dass nur solche Dokumente eingeschlossen werden, die für das Script als noch unbearbeitet gelten.

UnprocessedSearch

NotesDocumentCollection

Wie Search mit dem Unterschied, dass nur solche Dokumente eingeschlossen werden, die für das Script als noch unbearbeitet gelten.

UpdateFTIndex

Führt ein Update auf den Volltextindex durch.

23.9 NotesDateRange NotesDataRange steht für einen Zeitabschnitt. Ein Objekt dieser Klasse wird über die Methode CreateDateRange in der NotesSession-Klasse erstellt: Dim notesDateRange As NotesDateRange Set notesDateRange = NotesSession.CreateDateRange ()

NotesDateTime

337

Ei g en s ch af t en Name

Datentyp

EndDateTime

NotesDateTime

R5

(Read-Write) Ende des Zeitabschnitts

Beschreibung

StartDateTime

NotesDateTime

(Read-Write) Beginn des Zeitabschnitts

Text

String

(Read-Write) Zeitabschnitt in Textform

23.10 NotesDateTime Nimmt Datum und Zeit auf. Erlaubt verschiedenste Umformungen und Zeitausgaben. Stellt insbesondere auch eine Möglichkeit zur Verfügung, zwischen dem LotusScript- und dem Domino-Format zu konvertieren. Ein neues NotesDateTime-Objekt können Sie über eine Methode der NotesSessionKlasse erzeugen oder auch über New: Dim notesDateTime As New NotesDateTime ( dateTime$ ) oder Dim notesDateTime As NotesDateTime Set notesDateTime = notesSession.CreateDateTime ( dateTime$ ) Die Klasse NotesDateTime speichert im Unterschied zum LotusScript-Datentyp Variant (Typ DateTime) auch eine Zeitzone und Hunderstel-Sekunden. Ei g en s ch af t en Name

Datentyp

DateOnly

String

R5

Datumsteil des Zeitwertes

GMTTime

String

Zeitwert, umgerechnet auf die Zone 0 (Greenwich Mean Time)

IsDST

Integer Flag

Gibt an, ob der Zeitwert eine Sommerzeitverschiebung enthält

IsValidDate

Integer Flag

LocalTime

String

(Read-Write) Zeitwert gemäß lokaler Zeitzone

LSGMTTime

DateTime-Variant

GMTTime als LotusScript-Zeitwert (DateTimeVariant-Format)

LSLocalTime

DateTime-Variant

(Read-Write) LocalTime als LotusScript-Zeitwert (DateTime-Variant-Format)

TimeOnly

String

Zeitteil des Zeitwertes

TimeZone

Integer

Positiver oder negativer Integer-Wert, der die Zeitzone repräsentiert, der der Angabe LocalTime zugrunde liegt

X

Beschreibung

Gibt an, ob der Zeitwert gültig ist

338

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

ZoneTime

String

R5

Beschreibung Anfänglich derselbe Wert wie LocalTime. Zeigt das Ergebnis von Konvertierungen an, die mit der Methode ConvertToZone durchgeführt werden (andere Zeitzone und/oder Sommerzeitumstellung).

Method en Name

Datentyp

R5

Beschreibung

AdjustDay

Verändert den Zeitwert um die gewählte Anzahl Tage

AdjustHour

Verändert den Zeitwert um die gewählte Anzahl Stunden

AdjustMinute

Verändert den Zeitwert um die gewählte Anzahl Minuten

AdjustMonth

Verändert den Zeitwert um die gewählte Anzahl Monate

AdjustSecond

Verändert den Zeitwert um die gewählte Anzahl Sekunden

AdjustYear

Verändert den Zeitwert um die gewählte Anzahl Jahre

ConvertToZone

Konvertiert die Zeitzone und/oder die Sommerzeitumstellung

SetAnyDate

Setzt den Datumsteil eines Zeitwertes auf »irgendeinen Tag«. Dies bedeutet, dass der Datumsteil sich wie ein Wildcard-Wert verhält, also zu irgendeinem Vergleichsdatum passt.

SetAnyTime

Setzt den Zeitanteil eines Zeitwertes auf »irgendeine Zeit«. Dies bedeutet, dass der Zeitanteil sich wie ein Wildcard-Wert verhält, also zu irgendeiner Vergleichszeit passt.

SetNow

Setzt den Zeitwert auf den momentanen Wert.

TimeDifference

Long

TimeDifferenceDouble

Double

Gibt den Unterschied zwischen zwei Zeitwerten in Sekunden zurück. X

Gibt den Unterschied zwischen zwei Zeitwerten in Hundertstel-Sekunden zurück.

NotesDbDirectory

339

23.11 NotesDbDirectory Repräsentiert ein Verzeichnis der Datenbanken auf einem Server oder einem lokalen Computer. Ein neues NotesDbDirectory-Objekt können Sie über die Methode der NotesSession-Klasse erzeugen oder auch über New: Dim notesDbDirectory As New NotesDbDirectory ( server$ ) oder Dim notesDbDirectory As NotesDbDirectory Set notesDbDirectory As notesSession.GetDbDirectory ( server$ ) Eigenschaften Name

Datentyp

Name

String

R5

Beschreibung Server, dessen Datenbankverzeichnis durch NotesDbDirectory repräsentiert wird.

Methoden Name

Datentyp

R5

Beschreibung

GetFirstDatabase

NotesDatabase

Gibt die erste Datenbank im Datenbankverzeichnis zurück. Über einen Parameter kann der Typ der zu berücksichtigenden Datenbanken gewählt werden.

GetNextDatabase

NotesDatabase

Gibt jeweils die nächste Datenbank zurück. Der Typ wird vom vorherigen Aufruf von GetFirstDatabase bestimmt.

23.12 NotesDocument Notes-Dokumente stellen die Datensätze der Notes-Datenbanken dar. Dokumente werden durch Zugriff auf einzelne Notes-Items bearbeitet. Ein neues NotesDocument-Objekt können Sie über eine entsprechende Methode der NotesDatabase-Klasse erzeugen oder auch über New: Dim notesDocument As New NotesDocument ( notesDatabase ) oder Dim notesDocument As NotesDocument Set notesDocument As notesDatabase.CreateDocument

340

Kurzreferenz der Notes/Domino-Klassen

Ei g en s ch af t en Name

Datentyp

Authors

String Array

R5

Namen der Benutzer, die das Dokument gespeichert haben. Nicht zu verwechseln mit den Benutzern, die Autor-Zugriffsberechtigung haben!

ColumnValues

Variant Array

Spaltenwerte eines Dokuments in einer Ansicht. Diese Eigenschaft ist nur gesetzt, wenn das Dokument über die Ansicht gefunden wurde.

Created

DateTime-Variant

Zeitpunkt der Erstellung des Dokuments.

EmbeddedObjects

NotesEmbeddedObject Array

Die im Dokument eingebetteten OLEObjekte. Nicht unterstützt unter OS/2, Unix, Macintosh!

EncryptionKeys

String oder String Array

(Read-Write) Schlüssel, mit denen das Dokument verschlüsselt werden soll.

EncryptOnSend

Integer Flag

(Read-Write) Gibt an, ob das Dokument beim Mailversand verschlüsselt wird.

FolderReferences

String Array

FTSearchScore

Integer

Relevanz hinsichtlich einer Volltextsuche, über die das Dokument erhalten wurde.

HasEmbedded

Integer Flag

Gibt an, ob eingebettete Objekte, Links oder Dateianhänge enthalten sind.

IsDeleted

Integer Flag

IsNewNote

Integer Flag

Zeigt an, ob das Dokument neu erstellt und noch nicht gespeichert wurde.

IsProfile

Integer Flag

Handelt es sich um ein Profil-Dokument?

IsResponse

Integer Flag

Handelt es sich um ein Antwort-Dokument?

IsSigned

Integer Flag

Wurde das Dokument unterzeichnet?

IsUlDocOpen

Integer Flag

Ist TRUE, wenn auf das Dokument über das UI-Dokument (NotesUIDocument) zugegriffen wurde.

IsValid

Integer Flag

Ist das Dokument vorhanden oder handelt es sich um einen Lösch-Stumpf?

Items

NotesItem Array

Alle Dokumenten-Items (Felder)

X

X

Beschreibung

Gibt an, in welchen Ordnern das Dokument abgelegt wurde. Die Datebank muss die versteckten Ansichten $FolderRef und $FolderRefInfo beinhalten und die Datenbank-Eigenschaft FolderRefsEnabled muss TRUE sein.

Zeigt an, ob das Dokument gelöscht worden ist.

NotesDocument

341

Name

Datentyp

R5

Beschreibung

Key

String

Falls es sich um ein Profildokument handelt, ist hier der Benutzername (= Schlüssel) für das Profildokument abgelegt.

LastAccessed

DateTime-Variant

Zeitpunkt, zu dem das Dokument das letzte Mal gelesen oder verändert wurde.

LastModified

DateTime-Variant

Zeitpunkt, zu dem das Dokument das letzte Mal verändert wurde.

NameOfProfile

String

Falls es sich um ein Profildokument handelt, ist hier der Name des Profils abgelegt.

NoteID properly

String

NoteID des Dokuments.

ParentDatabase

NotesDatabase

Datenbank, in der das Dokument enthalten ist.

ParentDocumentUNlD

String

Die UniversalID des Vaterdokuments. Leer, wenn dieses nicht existiert.

ParentView

NotesView

Ansicht, über die auf das Dokument zugegriffen wurde.

Responses

NotesDocumentCollection

Die direkten Antwortdokumente.

SaveMessageOnSend

Integer Flag

(Read-Write) Wenn TRUE, dann wird ein neues Dokument beim Mailversand abgespeichert.

SentByAgent

Integer Flag

Gibt an, ob das Dokument durch ein Script versendet wurde.

Signer

String

Name des Unterschriftsleistenden, falls das Dokument signiert wurde.

SignOnSend

Integer Flag

(Read-Write) Gibt an, ob das Dokument beim Mailversand unterschrieben wird.

Size

Long

Die Größe des gesamten Dokuments inklusive Anhänge.

UniversalID

String

(Read-Write) UniversalID des Dokuments.

Verifier

String

Der Name der Zertifizierungsstelle, die den Schlüssel des Unterschriftleistenden zugelas-sen hat.

342

Kurzreferenz der Notes/Domino-Klassen

Method en Name

Datentyp

AppendItemValue

NotesItem

R5

Erzeugt ein neues Item mit dem übergebenen Inhalt. Dies ist auch der Fall, wenn es schon ein Item mit demselben Namen gibt.

ComputeWithForm

Integer Flag

Berechnet das Dokument mit der im Form-Feld angegebenen Maske. Dabei werden auch die Validierungsformeln durchlaufen.

CopyAllItems

Beschreibung

Kopiert die Items eines Dokuments auf ein anderes Dokument.

CopyItem

NotesItem

Wie CopyAllItems für nur ein einzelnes Item.

CopyToDatabase

NotesDocument

Kopiert das gesamte Dokument in eine Datenbank.

CreateReplyMessage

NotesDocument

Erzeugt eine Antwortmail.

CreateRichTextItem

NotesRichTextItem

Erzeugt ein neues RichTextItem auf dem Dokument.

Encrypt

Verschlüsselt das Dokument.

FTDomainSearch

NotesDocument

X

Volltextsuche über alle im Domänenkatalog eingetragenen Datenbanken, die für die Mehrfachdatenbanksuche markiert sind. Das zurückgegebene Dokument enthält eine formatierte Liste aller gefundenen Dokumente.

FTSearch

NotesDocumentCollection

Führt eine Volltextsuche über alle Dokumente der Datenbank durch.

GetAttachment

NotesEmbeddedObject

Gibt einen spezifizierten Anhang zurück.

GetFirstltem

NotesItem

Gibt das erste Item mit dem spezifizierten Namen zurück. Will man auch die übrigen des gleichen Namens erhalten, verwendet man die Dokument-Eigenschaft Items.

GetItemValue

Variant Array

Gibt die Werte des Items zurück.

HasItem

Integer Flag

Überprüft, ob das Item auf dem Dokument existiert.

MakeResponse

Verwandelt ein unabhängiges Dokument in ein Antwortdokument.

PutInFolder

Legt das Dokument in einem Ordner ab. Falls dieser noch nicht existiert, wird er erzeugt.

NotesDocumentCollection

343

Name

Datentyp

Remove

Integer Flag

R5

Beschreibung Löscht das Dokument von der Platte (ohne weitere Nachfrage!).

RemoveFromFolder

Nimmt das Dokument aus einem Ordner.

RemoveItem

Entfernt ein Item. Die Löschung wird erst dann auf die Platte geschrieben, wenn die Save-Methode aufgerufen wird.

RenderToRTItem

Integer Flag

Legt ein Bild des Dokuments in einem RichTextItem ab. Dabei werden Maskenformeln ausgeführt!

ReplaceItemValue

NotesItem

Ersetzt alle Items gleichen Namens durch ein neues. Falls es noch keines gibt, wird ein neues Item angelegt.

Save

Integer Flag

Speichert Dokumentänderungen auf die Platte.

Send

Versendet das Dokument per Mail.

Sign

Unterschreibt das Dokument.

23.13 NotesDocumentCollection Repräsentiert eine Sammlung von Dokumenten. Ein Objekt vom Typ NotesDocumentCollection wird von vielen Methoden zurückgeben, die zur Suche und Auswahl mehrerer Dokumente dienen. Beispiel: Dim notesDocumentCollection As NotesDocumentCollection Set notesDocumentCollection = notesDatabase.AllDocuments Eigenschaften Name

Datentyp

R5

Beschreibung

Count

Long

Anzahl der enthaltenen Dokumente.

IsSorted

Integer Flag

Gibt an, ob die Dokumente sortiert sind.

Parent

NotesDatabase

Die Datenbank, in der die Dokumente enthalten sind.

Query

String

Formel, die bei einer Suche verwendet wurde. Ansonsten Leerstring ("")

344

Kurzreferenz der Notes/Domino-Klassen

Method en R5

Beschreibung

AddDocument

Name

Datentyp

X

Fügt ein Dokument hinzu.

DeleteDocument

X

Entfernt ein Dokument (nicht auf der Platte).

FTSearch

NotesDocumentCollection

GetDocument

NotesDocument

GetFirstDocument

NotesDocument

Gibt das erste Dokument zurück.

GetLastDocument

NotesDocument

Gibt das letzte Dokument aus.

GetNextDocument

NotesDocument

Gibt das nächste Dokument der Collection zurück. Der Ausdruck »nächste« bezieht sich dabei auf das Dokument, das der Methode zur Suche übergeben wird.

GetNthDocument

NotesDocument

Gibt das Dokument zurück, das sich an der mit einer Ordnungsnummer bezeichneten Stelle befindet.

GetPrevDocument

NotesDocument

Analog zu GetNextDocument, nur dass das vorhergehende Dokument ausgegeben wird.

PutAllInFolder

Reduziert die in der Collection enthaltenen Dokumente auf diejenigen, die bei der Volltextsuche über die Collection gefunden werden. X

(X)

Gibt das übergebene Dokument zurück, wenn es sich in der Collection befindet. Ansonsten wird NOTHING zurückgegeben.

Legt alle Dokumente der Collection in dem spezifizierten Ordner ab. Falls er noch nicht existiert, wird er neu angelegt. Unter R5 gibt es den neuen (optionalen) Parameter createOnFail, mit dem man verhindern kann, dass ein Ordner neu angelegt wird.

RemoveAll

Entfernt alle Dokumente von der Collection.

RemoveAllFromFolder

Entfernt alle Dokumente der Collection vom angegebenen Ordner.

StampAll

Erzeugt bzw. überschreibt ein spezifiziertes Item mit einem angegebenen Wert.

UpdateAll

Alle Dokumente der Collection werden als vom Agenten bearbeitet markiert.

NotesEmbeddedObject

345

23.14 NotesEmbeddedObject Repräsentiert ein eingebettetes Objekt, einen Link auf ein Objekt oder einen DateiAnhang. Steht nicht unter jedem Betriebssystem zur Verfügung. Es gibt mehrere Wege, ein NotesEmbeddedObject-Objekt zu erzeugen. Einer davon ist der Gebrauch der EmbedObject-Methode in der Klasse NotesRichTextItem: Dim notesEmbeddedObject As NotesEmbeddedObject Set notesEmbeddedObject = notesRichTextItem.EmbedObject ( type%, class$, source$, [name$] ) Eigenschaften Name

Datentyp

R5

Beschreibung

Class

String

Name der Anwendung, von der das Objekt stammt. Bei Datei-Anhängen leer ("").

FileSize

Long

Größe des Datei-Anhangs in Bytes.

FitBelowFields

Integer Flag

(Read-Write) Passt die Größe eines aktivierten eingebetteten Objektes so an, dass es unterhalb der ersten Layout-Region des Dokuments erscheint.

FitToWindow

Integer Flag

(Read-Write) Passt die Größe eines aktivierten eingebetteten Objekts so an, dass es den gesamten Bereich des Fensters einnimmt.

Name

String

Der Name des eingebetteten Objekts oder Objekt-Links. Kann leer sein.

Object

Variant

OLE-Handle

Parent

NotesRichTextItem

Das RichText-Item, in dem sich das NotesEmbeddedObject befindet.

RunReadOnly

Integer Flag

(Read-Write) TRUE bedeutet, dass das Objekt bearbeitet werden kann, wenn das Dokument im Lese-Modus geöffnet ist. Nur gültig für OLE Controls.

Source

String

Gibt beim eingebetteten Objekt und ObjektLinks den Namen des Quelldokuments an. Bei Datei-Anhängen gibt Source den Namen an und je nach Herkunft des NotesEmbeddedObject auch ihren Pfad.

Type

Integer

Zeigt an, ob das Objekt ein eingebettetes Objekt, ein Objekt-Link oder ein Datei-Anhang ist.

Verbs

String Array

Gibt die Anweisungen zurück, die das Objekt unterstützt. Wird nur von OLE/2-Objekten unterstützt.

346

Kurzreferenz der Notes/Domino-Klassen

Method en Name

Datentyp

Activate

Variant

DoVerb

Variant

R5

Beschreibung Aktiviert das eingebettete oder das durch den Link verbundene Objekt. Gibt den Objekt-Handle zurück. Gibt die Anweisung an das OLE-Objekt weiter.

ExtractFile

Legt eine Kopie des Datei-Anhangs auf der Platte ab.

Remove

Entfernt das eingebettete Objekt, den Objekt-Link oder auch den Datei-Anhang von dem Dokument.

23.15 NotesForm Repräsentiert eine Maske in einer Notes-Datenbank. Es kann nur auf bestehende Masken zugegriffen werden. Neue Masken müssen über die IDE erzeugt werden. Es gibt zwei Wege, um auf Masken zuzugreifen: die Forms-Eigenschaft und die Methode GetForm in der NotesDatabase-Klasse: Dim notesForm As NotesForm Set notesForm = notesDatabase.GetForm ( name$ ) oder Dim vForms As Variant vForms = notesDatabase.Forms Ei g en s ch af t en Name

Datentyp

Aliases

String Array

R5

Gibt alle Alias-Bezeichnungen der Maske zurück.

Beschreibung

Fields

String Array

Gibt die Namen der Felder in der Maske zurück.

FormUsers

String Array

(Read-Write) Die Namen der Benutzer, die mit dieser Maske Dokumente erzeugen können. Diese Namen werden im Feld $FormUsers gespeichert.

IsSubForm

Integer Flag

Zeigt an, ob es sich um eine Teilmaske handelt.

Name

String

Der Maskenname

ProtectReaders

Integer Flag

(Read-Write) Bestimmt, ob das Feld $Readers durch Replikation überschrieben werden kann.

ProtectUsers

Integer Flag

(Read-Write) Bestimmt, ob das Feld $FormUsers durch Replikation überschrieben werden kann.

Readers

String Array

(Read-Write) Die Namen in dem Feld $Readers.

NotesInternational

347

Method en Name

Datentyp

R5

Remove

Beschreibung Entfernt die Maske aus der Datenbank. Die Methode arbeitet ohne weitere Nachfrage!

23.16 NotesInternational Stellt die internationalen Einstellungen des Betriebssystems dar. Werden dort Einstellungsänderungen vorgenommen, so werden diese von Domino sofort übernommen. Dient der Abfrage der internationalen Einstellungen des Betriebssystems. Ein Objekt vom Typ NotesInternational erhält man durch die International-Eigenschaft der Klasse NotesSession: Dim notesInternational As NotesInternational Set notesInternational = notesSession. International Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

AMString

Nur-Lesen. Der Text, mit dem angezeigt wird, dass die Systemzeit im AM-Bereich liegt (Englisch: »AM«).

CurrencyDigits

Nur-Lesen. Die Anzahl der Nachkommastellen des eingestellten Währungsformats.

CurrencySymbol

Nur-Lesen. Das Währungssymbol (DM, $ usw.)

DateSep

Nur-Lesen. Das Zeichen, mit dem die Angaben für Tag, Monat und Jahr in Zeitwerten getrennt werden.

DecimalSep

Nur-Lesen. Der Dezimaltrenner für numerische Datentypen.

IsCurrencySpace

Nur-Lesen. TRUE, wenn im eingestellten Währungsformat die Zahl vom Währungssymbol durch ein Leerzeichen abgesetzt ist.

IsCurrencySuffix

Nur-Lesen. TRUE, wenn das eingestellte Währungsformat ein Währungssymbol besitzt.

IsCurrencyZero

Nur-Lesen. TRUE, wenn gebrochene Zahlen, die keinen Ganzzahlteil besitzen, im Vorkommateil eine NULL anzeigen.

IsDateDMY

Nur-Lesen. TRUE, wenn das Datum in der Reihenfolge Tag, Monat, Jahr angezeigt wird.

IsDateMDY

Nur-Lesen. TRUE, wenn das Datum in der Reihenfolge Monat, Tag, Jahr angezeigt wird.

348

Name

Kurzreferenz der Notes/Domino-Klassen

Datentyp

R5

Beschreibung

IsYMD

Nur-Lesen. TRUE, wenn das Datum in der Reihenfolge Jahr, Monat, Tag angezeigt wird.

IsDST

Nur-Lesen. TRUE, wenn das Betriebssystem eine Umschaltung zwischen Sommer- und Winterzeit berücksichtigt.

IsTime24Hour

Nur-Lesen. TRUE, wenn die Zeit im 24-Stunden-Format angezeigt wird.

PMString

Nur-Lesen. Der Text, mit dem angezeigt wird, dass die Systemzeit im PM-Bereich liegt (Englisch: »PM«).

ThousandsSep

Nur-Lesen. Der Tausendertrenner für numerische Datentypen.

TimeSep

Nur-Lesen. Das Zeichen, das die Bestandteile eines Zeitwertes (Stunden, Minuten, Sekunden) trennt.

TimeZone

Nur-Lesen. Die eingestellte Zeitzone als numerischer Wert.

Today

Nur-Lesen. Das heutige Datum als String.

Tomorrow

Nur-Lesen. Der String, mit dem das morgige Datum angegeben werden kann.

Yesterday

Nur-Lesen. Der String, mit dem das gestrige Datum angegeben werden kann.

23.17 NotesItem Repräsentiert die kleinste Einheit von Daten in einer Notes-Datenbank. Ist Bestandteil eines Dokuments. Ein Objekt vom Typ NotesItem kann man sowohl beim Anlegen neuer Items mit diversen Methoden als auch mittels Zugriff auf bestehende Items erhalten. Es kann auch die New-Methode eingesetzt werden: Dim notesItem As New NotesItem ( notesDocument, name$, value [, specialType%] ) oder Dim notesItem As NotesItem Set notesItem = notesDocument.ReplaceItemValue ( name$, value )

NotesItem

349

Ei g en s ch af t en Name

Datentyp

DateTimeValue

NotesDateTime

R5

(Read-Write) Gibt bei einem Item vom Typ Zeit ein NotesDateTime-Objekt zurück, sonst NOTHING.

Beschreibung

IsAuthors

Integer Flag

(Read-Write) Gibt an, ob das Item vom Typ Autoren ist.

IsEncrypted

Integer Flag

(Read-Write) Gibt an, ob das Item verschlüsselt wird. Die Verschlüsselung wird auf alle so markierten Items angewendet, wenn die Methode Encrypt im Elterndokument ausgeführt wird.

IsNames

Integer Flag

(Read-Write) Gibt an, ob das Item vom Typ Namen ist.

IsProtected

Integer Flag

(Read-Write) Wenn diese Eigenschaft TRUE ist, dann benötigt der Benutzer für einen Zugriff mindestens das Recht Editor.

IsReaders

Integer Flag

(Read-Write) Gibt an, ob das Item vom Typ Leser ist.

IsSigned

Integer Flag

(Read-Write) Gibt an, ob das Item unterschrieben wird bzw. unterschrieben wurde.

IsSummery

Integer Flag

(Read-Write) Nur ein Item, bei dem diese Eigenschaft auf TRUE gesetzt ist, kann in Ansichten angezeigt werden.

LastModified

DateTime-Variant

Der Zeitpunkt, zu dem das Item das letzte Mal bearbeitet wurde.

Name

String

Der Name des Items.

Parent

NotesDocument

Das Dokument, in dem sich das Item befindet.

SaveToDisk

Integer Flag

(Read-Write) Gibt an, ob das Item mit dem Elterndokument mit abgespeichert wird.

Text

String

Der Wert des Items als Text.

Type

Long-Constant

Der Datentyp des Items. Es gibt wesentlich mehr Datentypen als in der zugehörigen Eigenschaftenbox auswählbar sind.

ValueLength

Long

Die Anzahl der Bytes, die das Item beim Speichern verwendet. Diese Anzahl ist im Allgemeinen höher als der Itemwert vermuten lässt, weil noch interner Overhead dazugerechnet wird.

Values

Variant Array

(Read-Write) Der bzw. die Werte des Items.

350

Kurzreferenz der Notes/Domino-Klassen

Method en Name

Datentyp

Abstract

Text

R5

Beschreibung Gibt eine verkürzte Form des Itemwerts zurück. Es werden Selbstlaute entfernt und Abkürzungen aus einer entsprechenden Liste eingesetzt. Danach wird der verbleibende Text auf eine anzugebende Länge gekürzt.

AppendToTextList

Fügt neue Werte zu einem Item hinzu. Dadurch nimmt die Anzahl der Wertelemente zu.

Contains

Integer Flag

Überprüft, ob eines der Wertelemente genau dem angegebenen Wert entspricht.

CopyItemToDocument

NotesItem

Fügt ein Item auf einem anzugebenden Dokument ein.

Remove

Entfernt ein Item von einem Dokument. Die Löschung wird erst mit dem Speichern des Dokuments auf die Platte geschrieben.

23.18 NotesLog Stellt ein allgemeines Objekt dar, mit dem Fehler in einem von vier verschiedenen Zielen mitgeschnitten werden können: Notes-Datenbank, Notes-Mail, Textdatei, Agent-Loggingbereich. Ein neues NotesLog-Objekt kann per New oder auch mittels der CreateLogMethode in der Klasse NotesSession erzeugt werden: Dim notesLog As New NotesLog ( name$ ) oder Dim notesLog As NotesLog Set notesLog = notesSession.CreateLog ( name$ ) Ei g en s ch af t en Name

Datentyp

LogActions

Integer Flag

R5

(Read-Write) Zeigt an, ob Aktionen mitgeschnitten werden sollen.

Beschreibung

LogErrors

Integer Flag

(Read-Write) Zeigt an, ob Fehler mitgeschnitten werden sollen.

NumActions

Integer

Die Anzahl der mitgeschnittenen Aktionen.

NumErrors

Integer

Die Anzahl der mitgeschnittenen Fehler.

NotesName

351

Name

Datentyp

R5

Beschreibung

OverwriteFile

Integer Flag

(Read-Write) Zeigt an, ob eine bereits bestehende LogDatei überschrieben werden soll. Wirkt nur im Zusammenhang mit Textdateien als Loggingziel.

ProgramName

String

(Read-Write) Ein Name, mit dem die Herkunft der Logging-Einträge identifiziert werden kann.

Method en Name

Datentyp

R5

Beschreibung

Close

Schließt das Logging-Objekt.

LogAction

Erzeugt einen Aktionseintrag.

LogError

Erzeugt einen Fehlereintrag.

LogEvent

Löst auf dem angeschlossenen Netzwerk ein Ereignis aus. Kann nur auf Servern eingesetzt werden.

OpenAgentLog

Öffnet den Logging-Bereich des Agenten, in dem das Script läuft.

OpenFileLog

Öffnet eine Textdatei als Logging-Ziel.

OpenMailLog

Erzeugt eine neue Mail als Logging-Ziel. Die Mail wird versendet, wenn das Logging-Objekt explizit oder durch Löschung implizit geschlossen wird.

OpenNotesLog

Öffnet eine Notes-Datenbank als Loggingziel.

23.19 NotesName Die Klasse NotesName nimmt einen Notes-Namen oder auch eine Internet-Adresse auf und erlaubt den einfachen Zugriff auf bestimmte Bestandteile und auch die Umwandlung in verschiedene Formen. Ein neues NotesName-Objekt kann per New oder auch mittels der CreateNameMethode in der Klasse NotesSession erzeugt werden: Dim notesName As New NotesName ( name$ ) oder Dim notesName As NotesName Set notesName = notesSession.CreateName ( name$ )

352

Kurzreferenz der Notes/Domino-Klassen

Ei g en s ch af t en Name

Datentyp

Abbreviated

String

R5

Beschreibung

Addr821

String

X

Eine Internetadresse gemäß dem RFC821-Format

Addr822Comment1

String

X

Der Comment1-Bestandteil einer Internetadresse im RFC822-Format.

Addr822Comment2

String

X

Der Comment2-Bestandteil einer Internetadresse im RFC822-Format.

Addr822Comment3

String

X

Der Comment3-Bestandteil einer Internetadresse im RFC822-Format.

Addr822LocalPart

String

X

Der LocalPart-Bestandteil einer Internetadresse im RFC822-Format.

Addr822Phrase

String

X

Der Phrase-Bestandteil einer Internetadresse im RFC822-Format.

Der hierarchische Name in abgekürzter Form.

ADMD

String

Name der ADMINISTRATIONS-DOMÄNE.

Canonical

String

Der hierarchische Name in kanonischer Form.

Common

String

Der Common-Teil des hierarchischen Namens. Wenn der Name flach ist, dann wird der ganze Name zurückgegeben.

Country

String

Der Country-Teil des hierarchischen Namens.

Generation

String

Der Generation-Teil des Namens.

Given

String

Der Given-Teil des Namens.

Initials

String

Die Initialen des Namens.

IsHierarchical

Integer Flag

Zeigt an, ob der Name hierarchisch oder flach ist.

Keyword

String

Die Schlüsselbestandteile des hierarchischen Namens. Sie werden in der folgenden Form zurückgegeben: Country \ Organisation\ Organisations-Einheit 1\ Organisations-Einheit 2\ Organisations-Einheit 3\ Organisations-Einheit 4

Language

String

X

Sprachcode, der dem Namen zugeordnet ist.

Organization

String

Die Organisation im hierarchischen Namen.

OrgUnit1

String

Die Organisations-Einheit 1 im hierarchischen Namen.

OrgUnit2

String

Die Organisations-Einheit 2 im hierarchischen Namen.

OrgUnit3

String

Die Organisations-Einheit 3 im hierarchischen Namen.

OrgUnit4

String

Die Organisations-Einheit 4 im hierarchischen Namen.

NotesNewsletter

Name

353

Datentyp

R5

Beschreibung

PRMD

String

Der Name der PRIVATEN MANAGEMENTDOMÄNE.

Surname

String

Der Nachnamens-Bestandteil im Namen.

23.20 NotesNewsletter Ein Dokument, in dem Informationen oder Links zu anderen Dokumenten zusammengefasst sind. Ein neues NotesNewsletter-Objekt kann per New oder auch mittels der CreateNewsletter-Methode in der Klasse NotesSession erzeugt werden: Dim notesNewsletter As New NotesNewsletter ( notesDocumentCollection ) oder Dim notesNewsletter As NotesNewsletter Set notesNewsletter = notesSession.CreateNewsletter ( notesDocumentCollection ) Eigenschaften Name

Datentyp

R5

Beschreibung

DoScore

Integer Flag

(Read-Write) Gibt an, ob die Relevanzen mit angegeben werden. Steht nur zur Verfügung, wenn das Dokument zum Newsletter durch die Methode FormatMsgWithDoclinks erzeugt wurde.

DoSubject

Integer Flag

(Read-Write) Gibt an, ob das Subject der Dokumente jeweils angegeben wird. Steht nur zur Verfügung, wenn das Dokument zum Newsletter durch die Methode FormatMsgWithDoc-links erzeugt wurde. Die Eigenschaft SubjectItemName muss spezifiziert sein.

SubjectItemName

String

(Read-Write) Zeigt an, welchem Feld der dem Newsletter zugrunde liegenden Dokumente das Subject zugeordnet sein soll.

Methoden Name

Datentyp

FormatDocument

String

R5

Beschreibung Erstellt in der angegebenen Datenbank ein neues Dokument. In diesem ist jedes Dokument, das in dem Newsletter aufgezählt ist, abgebildet.

354

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

FormatMsgWithDoclinks

Long

R5

Beschreibung Erstellt in der angegebenen Datenbank ein neues Dokument. In diesem befindet sich für jedes Dokument, das in dem Newsletter aufgezählt ist, ein Link.

23.21 NotesOutline NotesOutline dient der Gliederung. Es stellt Möglichkeiten zur dynamischen Navigation zur Verfügung. Das Objekt wurde in R5 neu eingeführt. Ein neues NotesOutline-Objekt kann mittels der CreateOutline-Methode in der Klasse NotesDatabase erzeugt werden (dadurch wird gleichzeitig eine neue Gliederung in der Datenbank erzeugt). Wahlweise kann man durch die Methode GetOutline auch Zugriff auf eine bestehende Gliederung erhalten: Dim notesOutline As NotesOutline Set notesOutline = NotesDatabase.CreateOutline ( name$ ) oder Dim notesOutline As NotesOutline Set notesOutline = notesDatabase.GetOutline ( name$ ) Eigenschaften Name

Datentyp

R5

Beschreibung

Alias

String

X

(Read-Write) Aliasname der Gliederung

Comment

String

X

(Read-Write) Beschreibung der Gliederung

Name

String

X

(Read-Write) Name der Gliederung

Methoden Name

Datentyp

AddEntry

R5

Beschreibung

X

Fügt der Gliederung einen neuen Eintrag hinzu.

CreateEntry

NotesOutlineEntry

X

Erzeugt einen neuen Eintrag. Dieser muss mit AddEntry der Gliederung noch hinzugefügt werden.

GetFirst

NotesOutlineEntry

X

Gibt den ersten Eintrag zurück.

GetLast

NotesOutlineEntry

X

Gibt den letzten Eintrag zurück.

GetNext

NotesOutlineEntry

X

Gibt den Eintrag zurück, der dem übergebenen Eintrag folgt.

NotesOutlineEntry

355

Name

Datentyp

R5

Beschreibung

GetNextSibling

NotesOutlineEntry

X

Gibt den nächsten Bruder-Eintrag zurück, das ist der Eintrag, der dem übergebenen Eintrag auf derselben Hierarchie-Ebene folgt.

GetParent

NotesOutlineEntry

X

Gibt den Eltern-Eintrag zu einem übergebenen Antwort-Eintrag zurück.

GetPrev

NotesOutlineEntry

X

Gibt den Eintrag zurück, der dem übergebenen Eintrag vorausgeht.

GetPrevSibling

NotesOutlineEntry

X

Gibt den vorhergehenden Bruder-Eintrag zurück, das ist der Eintrag, der dem übergebenen Eintrag auf derselben Hierarchie-Ebene vorhergeht.

MoveEntry

X

Verschiebt einen Eintrag innerhalb einer Gliederung.

RemoveEntry

X

Entfernt einen Gliederungs-Eintrag und alle seine Nachfolger.

Save

X

Speichert die Änderungen, die an der Gliederung vorgenommen wurden.

23.22 NotesOutlineEntry Die Klasse NotesOutlineEntry stellt Einträge einer Gliederung dar. Das Objekt wurde in R5 neu eingeführt. Neue Einträge werden über die Methode CreateEntry in der Klasse NotesOutline erzeugt. Sie müssen anschließend mit der Methode AddEntry (in der gleichen Klasse) in die Gliederung eingefügt werden. Ein neues NotesOutlineEntry-Objekt kann mittels der CreateEntry-Methode in der Klasse NotesOutline erzeugt werden. Dim notesOutlineEntry As NotesOutlineEntry Set notesOutlineEntry = notesOutline.CreateEntry ( name$ ) Des Weiteren gibt es in der Klasse NotesOutline verschiedene Methoden, mit denen Zugriff auf bestehende Einträge in der Gliederung erlangt werden kann, beispielsweise: Dim notesOutlineEntry As NotesOutlineEntry Set notesOutlineEntry = notesOutline.GetFirst

356

Kurzreferenz der Notes/Domino-Klassen

Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

Alias

String

X

(Read-Write) Aliasname des Eintrages.

Database

NotesDatabase

X

Gibt die mit dem Eintrag verknüpfte Datenbank zurück.

Document

NotesDocument

X

Gibt das mit dem Eintrag verknüpfte Dokument zurück.

EntryClass

Integer

X

Klasse des Eintrags.

Formula

String

X

Formelmakro eines Aktions-Eintrages, ansonsten Leerstring ("").

FrameText

String

X

(Read-Write) Name des Zielrahmens, in dem der Eintrag erscheinen soll.

HasChildren

Integer Flag

X

Zeigt an, ob der Eintrag über Unter-Einträge verfügt.

ImagesText

String

X

(Read-Write) Name einer Bilddatei, die als Icon eingebunden werden soll.

IsHidden

Integer Flag

X

Gibt an, ob der Eintrag versteckt ist.

IsInThisDb

Integer Flag

X

Zeigt an, ob sich das mit dem Eintrag verknüpfte Element in derselben Datenbank befindet.

IsPrivate

Integer Flag

X

Zeigt an, ob es sich um einen persönlichen Eintrag handelt.

Label

String

X

(Read-Write) Aufschrift des Eintrags.

Level

Long

X

Hierarchieebene des Eintrags.

NamedElement

String

X

Gibt das benannte Element zurück, auf das sich der Eintrag bezieht. Ansonsten leer ("").

Type

Long

X

(Read-Write) Typ des Eintrags.

URL

String

X

Die URL des Eintrags, falls vorhanden.

View

NotesView

X

Ansicht, auf die der Eintrag verweist.

Method en Name

Datentyp

R5

Beschreibung

SetAction

Integer Flag

X

Weist dem Eintrag eine Makroformel zu.

SetNamedElement

Integer Flag

X

Weist dem Eintrag ein benanntes Element zu.

SetNoteLink

Integer Flag

X

Weist dem Eintrag einen Link auf eine Ressource zu.

SetURL

Integer Flag

X

Weist dem Eintrag einen URL-Link zu.

NotesRegistration

357

23.23 NotesRegistration Mit dieser unter R4.6 eingeführten Klasse kann die Erzeugung und Administration von Notes-Ids per Script durchgeführt werden. Ein neues NotesRegistration-Objekt wird per New erzeugt: Dim notesRegistration As New NotesRegistration Eigenschaften Name

Datentyp

CertifierIDFile

String

R5

(Read-Write) Pfad und Name der ID der Zulassungsstelle, auf die die ID zugelassen werden soll.

Beschreibung

CreatE-MailDb

Integer Flag

(Read-Write) Gibt an, ob mit der Registrierung der neuen ID auch eine MailDatenbank erstellt wird.

Expiration

DateTime-Variant

(Read-Write) Das Ablaufdatum der neuen ID.

IDType

Integer

(Read-Write) Die Art der ID (flach, hierarchisch oder so wie die ID der Zulassungsstelle)

IsNorthAmerican

Integer Flag

(Read-Write) Ist dies eine ID für den nordamerikanischen Raum?

MinPasswordLength

Integer

(Read-Write) Die einzuhaltende minimale Passwortlänge.

OrgUnit

String

(Read-Write) Die Organisationseinheit für die neue ID.

RegistrationLog

String

(Read-Write) Die Logdatei, die während der ID-Registrierung verwendet wird.

RegistrationServer

String

(Read-Write) Der Server, auf dem die Mail-Datenbank erstellt werden soll oder auf dem das Adressbuch liegt, in der die ID gespeichert werden soll beziehungsweise beides.

StoreIDInAddressbook

Integer Flag

(Read-Write) Gibt an, ob die ID im Adressbuch gespeichert werden soll.

UpdateAddressbook

Integer Flag

(Read-Write) Gibt an, ob das Serverdokument im Adressbuch aktualisiert werden soll.

358

Kurzreferenz der Notes/Domino-Klassen

Method en Name

Datentyp

R5

Beschreibung

AddCertifierToAddressbook

Legt die Zulassungs-ID im öffentlichen Adressbuch ab.

AddServerToAddressbook

Fügt ein Server-Dokument zum öffentlichen Adressbuch hinzu.

AddUserProfile

Trägt im Personen-Dokument einen Setup-Profilnamen ein.

AddUserToAddressbook

Fügt ein Personen-Dokument zum öffentlichen Adressbuch hinzu.

CrossCertify

Integer Flag

Erstellt für die ID eine Querzulassung.

DeleteIDOnServer

Löscht die ID-Datei vom Server.

GetIDFromServer

Holt die ID-Datei von dem mittels der Eigenschaft RegistrationServer angegebenen Server.

GetUserInfo

Gibt Informationen über den angegebenen Benutzer zurück.

Recertify

Erneuert die Registrierung einer ID.

RegisterNewCertifier

Registriert eine neue Zulassungsstelle.

RegisterNewServer

Registriert einen neuen Server.

RegisterNewUser

Registriert einen weiteren Benutzer.

SwitchToID

Wechselt zu einer anderen Notes-ID.

23.24 NotesReplication Diese neue Klasse ermöglicht die Kontrolle über die Einstellungen der Replikation. Das Objekt wurde in R5 neu eingeführt. Ein Objekt vom Typ NotesReplication bezieht sich immer auf eine einzelne Datenbank. Deshalb wird ein Objekt der Klasse NotesReplication als Eigenschaft ReplicationInfo von NotesDatabase gewonnen: Dim notesReplication As NotesReplication Set notesReplication = New notesDatabase.Replication Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

Abstract

Integer Flag

X

(Read-Write) Gibt an, ob eine auszugsweise Replikation durchgeführt wird, das heißt ob lange Dokumente abgeschnitten und Anhänge entfernt werden.

NotesRichTextItem

359

Name

Datentyp

R5

Beschreibung

CutoffDate

DateTime-Variant

X

Das heutige Datum minus dem in der Eigenschaft angegebenen CutoffInterval-Zeitraum.

CutoffDelete

Integer Flag

X

(Read-Write) Gibt an, dass Dokumente, die älter sind als das in der Eigenschaft CutoffDate angegebene Datum, gelöscht werden.

CutoffInterval

Long

X

(Read-Write) Anzahl der Tage, nach denen Dokumente automatisch gelöscht werden. (Dazu muss die Eigenschaft CutoffDelete auf TRUE gesetzt sein.)

Disabled

Integer Flag

X

(Read-Write) Gibt an, ob die Replikation deaktiviert wurde.

IgnoreDeletes

Integer Flag

X

(Read-Write) Gibt an, ob Löschungen bei der Replikation übergangen werden.

IgnoreDestDeletes

Integer Flag

X

(Read-Write) Gibt an, ob Löschungen nicht an die Zieldatenbank weitergegeben werden sollen.

Priority

Long

X

(Read-Write) Prioritätsstufe der Replikation.

Method en Name

Datentyp

R5

Beschreibung

ClearHistory

Löscht die Replikations-Historie.

Reset

Setzt die Replikations-Einstellungen auf die zuletzt gespeicherten Werte zurück.

Save

Speichert die Replikations-Einstellungen.

23.25 NotesRichTextItem Repräsentiert ein RichText-Item. Ein neues NotesRichTextItem-Objekt können Sie über New oder die CreateRichTextItem-Methode der NotesDocument-Klasse erzeugen: Dim notesRichTextItem As New NotesRichTextItem ( notesDocument, name$ ) oder Dim notesRichTextItem As NotesRichTextItem Set notesRichTextItem = notesDocument.CreateRichTextItem ( name$ ) Zugriff auf ein bestehendes RichText-Item erhalten Sie über die Methode GetFirstItem in der NotesDocument-Klasse. Allerdings müssen Sie eine Besonderheit beachten: die Methode GetFirstItem liefert i. A. ein Objekt vom Typ NotesItem

360

Kurzreferenz der Notes/Domino-Klassen

zurück. Würden Sie versuchen, diesen Rückgabewert an eine Objektvariable vom Typ NotesRichTextItem zuzuweisen, würde der Compiler einen Fehler melden. Denn der Compiler kann nicht wissen, ob zur Laufzeit tatsächlich ein Objekt vom Typ NotesRichTextItem zurückgegeben wird. Es könnte genauso ein NotesItem sein. Die Lösung liegt im Einsatz einer Variablen vom Typ Variant: Dim vRTItem As Variant Set vRTItem = notesDocument.GetFirstItem ( name$ ) Ei g en s ch af t en Name

Datentyp

EmbeddedObjects

NotesEmbeddedObject Array

R5

Beschreibung Alle eingebetteten Objekte, Objekt-Links und Datei-Anhänge des RichText-Items

Method en Name

Datentyp

R5

AddNewLine

Beschreibung Hängt einen oder mehrere Zeilenumbrüche an den Inhalt des RichText-Items an.

AddPageBreak

X

AddTab

Fügt einen harten Seitenumbruch ein. Hängt einen oder mehrere Tabstops an den Inhalt des RichText-Items an.

AppendDocLink

X

Hängt einen Link zu der übergebenen Datenbank, View oder dem übergebenen Dokument an den Inhalt des RichText-Items an.

AppendParagraphStyle

X

Hängt ein neues Absatzformat an den Inhalt des RichText-Items an.

AppendRTItem

Hängt den Inhalt eines RichText-Items an denjenigen eines anderen an.

AppendStyle

Hängt einen Stil an das Ende des RichText-Items an.

AppendText

Fügt Text an das Ende des RichTextItems an.

EmbedObject

NotesEmbeddedObject

Fügt ein eingebettetes Objekt, einen Objekt-Link oder einen Datei-Anhang in das RichText-Item ein.

Get EmbeddedObject

NotesEmbeddedObject

Gibt ein eingebettetes Objekt als NotesEmbeddedObject zurück.

GetFormattedText

String

Gibt den Inhalt des RichTextItems als reinen Text zurück.

NotesRichTextParagraphStyle

361

23.26 NotesRichTextParagraphStyle Repräsentiert die Attribute eines Absatzes in einem RichTextItem. Das Objekt wurde in R5 neu eingeführt. Ein neues NotesRichTextParagraphStyle-Objekt können Sie mittels der Methode CreateRichTextParagraphStyle der NotesSession-Klasse erzeugen: Dim notesRichTextParagraphStyle As NotesRichTextParagraphStyle Set notesRichTextParagraphStyle = notesSession.CreateRichTextParagraphStyle Eigenschaften Name

Datentyp

R5

Beschreibung

Alignment

Integer

X

(Read-Write) Ausrichtung des Absatzes

FirstLineLeftMargin

Long

X

(Read-Write) Linkseitiger Einzug der ersten Zeile

InterLineSpacing

Integer

X

(Read-Write) Zeilenabstand

LeftMargin

Long

X

(Read-Write) Linker Rand

Pagination

Integer

X

(Read-Write) Seitenumbruch

RightMargin

Long

X

(Read-Write) Rechter Rand

SpacingAbove

Integer

X

(Read-Write) Oberer Abstand zum nächsten Absatz

SpacingBelow

Integer

X

(Read-Write) Unterer Abstand zum nächsten Absatz

Tabs

Variant

X

Tabstops im Absatz

Methoden Name ClearAllTabs

Datentyp

R5

Beschreibung

X

Entfernt sämtliche Tabstops im Absatz.

SetTab

X

Setzt einen Tabstop.

SetTabs

X

Setzt mehrere Tabstops mit gleichen Abständen.

23.27 NotesRichTextStyle NotesRichTextStyle repräsentiert die Attribute eines RichTextItems. Das Objekt wurde in R4.6 neu eingeführt. Ein neues NotesRichTextStyle-Objekt können Sie mittels der CreateRichTextStyleMethode der NotesSession-Klasse erzeugen: Dim notesRichTextStyle As NotesRichTextStyle Set notesRichTextStyle = notesSession.CreateRichTextStyle

362

Kurzreferenz der Notes/Domino-Klassen

Ei g en s ch af t en Name

Datentyp

Bold

Integer (Flag)

R5

(Read-Write) Attribut »Fett«

Beschreibung

Effects

Integer

(Read-Write) Schrifteffekt

FontSize

Integer

(Read-Write) Schriftgröße

Italic

Integer (Flag)

(Read-Write) Attribut »Kursiv«

NotesColor

Integer

(Read-Write) Textfarbe

NotesFont

Integer

(Read-Write) Schrifttype

PassThruHTML

Integer (Flag)

(Read-Write) Soll der Text als HTML behandelt werden?

Strikethrough

Integer (Flag)

(Read-Write) Attribut »Durchgestrichen«

Underline

Integer (Flag)

(Read-Write) Attribut »Unterstrichen«

23.28 NotesRichTextTab NotesRichTextTab repräsentiert einen Tabulator in einem RichtTextItem. Das Objekt wurde in R5 neu eingeführt. Neue Tabulatoren werden mit den Methoden SetTab und SetTabs der NotesRichTextParagraphStyle-Klasse erzeugt, z. B.: Dim notesRichTextTab As NotesRichTextTab Set notesRichTextTab = NotesRichTextParagraphStyle.SetTab ( position#, type% ) Auf bestehende Tabulatoren kann über die Eigenschaft Tabs der NotesRichTextParagraphStyle-Klasse zugegriffen werden: Dim vTabs As Variant vTabs = NotesRichTextParagraphStyle.Tabs Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

Position

Long

X

Position des Tabstops

Type

Integer

X

Art des Tabstops

Method en Name Clear

Datentyp

R5

Beschreibung

X

Entfernt einen Tabstop

NotesSession

363

23.29 NotesSession NotesSession repräsentiert die Arbeitsumgebung der aktuellen Sitzung. Dazu gehören die Umgebungsvariablen und andere Informationen aus der notes.ini-Datei, Informationen aus den Adressbüchern, über die aktuell geöffnete Datenbank, den aktuell ablaufenden Agenten und anderes. Ein Objekt der Klasse NotesSession erhält man ausschließlich über die NewMethode: Dim notesSession As New NotesSession Eigenschaften Name

Datentyp

R5

AddressBooks

NotesDatabase Array

Alle Adressbücher, die zur Umgebung des Scriptes gehören.

CommonUserName

String

Der CommonName-Teil des Benutzers.

CurrentAgent

NotesAgent

Der Agent, in dem das Script läuft.

CurrentDatabase

NotesDatabase

Die Datenbank, in der das Script läuft.

DocumentContext

NotesDocument

Ein Dokument, das von einem externen Programm durch die NotesAPI im Arbeitsspeicher abgelegt wird. Ein Agent, der von dem externen Programm gestartet wurde, kann auf dieses Dokument zugreifen. Web-Agenten finden in ihm die Werte der CGI-Variablen.

EffectiveUserName

String

Der Name, unter dem das Script tatsächlich läuft.

International

NotesInternational

Die internationalen Einstellungen der Betriebssystemumgebung.

IsOnServer

Integer Flag

Zeigt an, ob das Script auf einem Server läuft.

LastExitStatus

Long

Gibt den Exit-Status zurück, den der Agentmanager bei der Ausführung des letzten Agenten ausgegeben hat.

LastRun

DateTime-Variant

Die Zeit, zu der der Agent, in dem das Script läuft, das letzte Mal gelaufen war.

NotesBuildVersion

Long

NotesVersion

String

Die Release-Versionsnummer der Notesumgebung, in der das Script läuft.

Platform

String

Name der Betriebssystemumgebung, in der das Script läuft.

X

Beschreibung

Die Build-Versionsnummer der Notesumgebung, in der das Script läuft.

364

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

SavedData

NotesDocument

Notes-Dokument, das von Scriptagenten bei jedem Speichern neu erzeugt wird. Dieses steht beim nächsten Aufruf des Agenten wieder zur Verfügung.

UserName

String

Name des Benutzers des Scripts. Läuft es auf einem Server, so wird dessen Name zurückgegeben.

UserNameList

NotesName Array

X

Gibt sämtliche Benutzernamen einer NotesSession zurück.

Method en Name

Datentyp

R5

CreateDateRange

NotesDateRange

Erzeugt ein neues Objekt vom Typ NotesDateRange.

CreateDateTime

NotesDateTime

Erzeugt ein neues Objekt vom Typ NotesDateTime. Dieses wird mit dem übergebenen Wert initialisiert.

CreateLog

NotesLog

Erzeugt ein neues Objekt vom Typ NotesLog. Dieses wird auf den übergebenen Namen ausgestellt.

CreateName

NotesName

Erzeugt ein neues NotesNameObjekt. Dieses wird auf den übergebenen Namen initialisiert.

CreateNewsletter

NotesNewsletter

Erzeugt ein neues Notes-NewsletterObjekt auf Grundlage der Dokumente, die in einer NotesCollection übergeben werden.

CreateRichTextParagraphStyle

NotesRichText-ParagraphStyle

CreateRichTextStyle

NotesRichTextStyle

Erzeugt ein neues Objekt vom Typ NotesRichTextStyle.

CreateTimer

NotesTimer

Erzeugt ein neues Objekt vom Typ NotesTimer.

FreeTimeSearch

NotesDateRange

Sucht im Kalender (mehrerer Personen) nach freien Zeiträumen.

GetDatabase

NotesDatabase

Gibt eine spezifizierte Notes-Datenbank zurück.

GetDbDirectory

NotesDbDirectory

Gibt alle Notes-Datenbanken zurück, die im ausgezeichneten Notes-Datenverzeichnis liegen.

GetEnvironmentString

Variant (String)

Gibt den Wert einer (Notes)-Umgebungsvariablen als String zurück.

X

Beschreibung

Erzeugt ein neues Objekt vom Typ NotesRichTextParagraph-Style.

NotesTimer

365

Name

Datentyp

GetEnvironmentValue

Variant (Numerischer Wert)

R5

Beschreibung Gibt den Wert einer numerischen (Notes)-Umgebungsvariablen zurück.

SetEnvironmentVar

Setzt den Wert einer (Notes)-Umgebungsvariablen.

UpdateProcessedDoc

Setzt ein Kennzeichen, dass ein Dokument von dem Agenten bearbeitet wurde, zu dem das laufende Script gehört.

23.30 NotesTimer NotesTimer dient zum Auslösen eines Events innerhalb von vorgegebenen Sekunden-Intervallen. Man erzeugt ein neues NotesTimer-Objekt mit der New-Methode oder mit der CreateTimer-Methode der Klasse NotesSession. Beispiel: Dim notesTimer As New NotesTimer ( interval% [, comment$] ) Eigenschaften Name

Datentyp

R5

Beschreibung

Comment

String

(Read-Write) Bemerkungen

Enabled

Integer Flag

(Read-Write) Gibt an, ob der Timer aktiviert ist.

Interval

Integer

Intervall, nach dem das Alarm-Event ausgelöst wird. Angabe in Sekunden.

Events Name Alarm

Datentyp

R5

Beschreibung Wird jeweils nach Verstreichen eines über die Eigenschaft Interval festgelegten Zeitraums ausgelöst.

23.31 NotesUIDatabase NotesUIDatabase repräsentiert die im Frontend geöffnete Datenbank. Der Zugriff wird über den Eventhandler gewährt, der auf einen der Events der Klasse NotesUIDatabase hin angestoßen wird, z. B.: PostOpen ( source As NotesUIDatabase )

366

Kurzreferenz der Notes/Domino-Klassen

Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

Database Documents

Die Backend-Datenbank zu der geöffneten Frontend-Datenbank. NotesDocumentCollection

Alle Backend-Dokumente, die vom gerade ablaufenden Event berührt werden.

Method en Name

Datentyp

R5

Beschreibung

OpenNavigator

X

Öffnet einen Navigator.

OpenView

(X)

Öffnet eine Ansicht. R5: neuer optionaler Parameter key (String). Beim Öffnen stellt sich der Zeilencursor auf das Dokument, das durch den Schlüssel repräsentiert wird. R5: neuer optionaler Parameter newinstance (Integer Flag). Dieser Wert gibt an, ob die Ansicht in einem neuen Fenster angezeigt werden soll.

Ev en t s Name

Datentyp

R5

PostDocumentDelete PostDragDrop

Beschreibung Das Ereignis, nachdem ein Dokument gelöscht wurde.

X

Das Ereignis nach dem Ausführen einer Dragand-drop-Operation.

PostOpen

Das Ereignis nach dem Öffnen der FrontendAnsicht und der Frontend-Datenbank.

QueryClose

Das Ereignis, bevor die Datenbank geschlossen wird.

QueryDocumentDelete

Das Ereignis, bevor ein Dokument gelöscht wird.

QueryDocumentUndelete

Das Ereignis, bevor die Löschung eines Dokuments zurückgenommen wird.

QueryDragDrop

X

Das Ereignis unmittelbar vor dem Ausführen einer Drag-and-drop-Operation.

23.32 NotesUIDocument NotesUIDocument repräsentiert das aktuell im Frontend geöffnete Dokument. Dieses Dokument wird im aktivierten Fenster angezeigt.

NotesUIDocument

367

Der Zugriff wird über den Eventhandler gewährt, der auf einen der Events der Klasse NotesUIDocument hin angestoßen wird, z. B.: PostOpen ( source As NotesUIDocument ) Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

AutoReload

Integer Flag

(Read-Write) Gibt an, ob am Backend durchgeführte Änderungen sofort im Frontend zu sehen sein sollen.

CurrentField

String

Der Name des Feldes, in dem der Cursor steht.

DialogBoxCanceled

Integer Flag

Gibt an, ob die Dialogbox per Cancel-Button geschlossen wurde.

Document

NotesDocument

Das Backend-Dokument

EditMode

Integer Flag

(Read-Write) Zeigt an, ob sich das FrontendDokument im Bearbeiten-Modus befindet.

FieldHelp

Integer Flag

(Read-Write) Gibt an, ob die Hilfetexte der Felder angezeigt werden.

HiddenChars

Integer Flag

(Read-Write) Gibt an, ob die versteckten Zeichen des Dokuments angezeigt werden.

HorzScrollBar

Integer Flag

(Read-Write) Gibt an, ob der horizontale Scrollbalken angezeigt wird.

InPreviewPane

Integer Flag

Zeigt an, dass auf das Dokument durch die Vorschauansicht zugegriffen wurde.

IsNewDoc

Integer Flag

Zeigt an, ob es sich um ein neues und noch nicht gespeichertes Dokument handelt.

PreviewDocLink

Integer Flag

(Read-Write) Gibt an, ob die Dokumentenvorschau angezeigt wird.

PreviewParentDoc

Integer Flag

(Read-Write) Gibt an, dass das Elterndokument in der Vorschau angezeigt wird.

Ruler

Integer Flag

(Read-Write) Gibt an, dass das Lineal angezeigt wird.

WindowTitle

String

Der Fenstertitel

Method en Name Categorize

Datentyp

R5

Beschreibung Fügt das Dokument in die angegebene Kategorie ein.

Clear

Löscht den markierten Bereich in einem Feld.

Close

Schließt das Dokument.

CollapseAllSections

Schließt alle Abschnitte im Dokument.

368

Name

Kurzreferenz der Notes/Domino-Klassen

Datentyp

R5

Beschreibung

Copy

Kopiert den markierten Bereich eines Feldes in die Zwischenablage.

CreateObject

Erzeugt ein OLE-Objekt in dem RichText-Feld an der Stelle, an der der Cursor steht.

Cut

Schneidet den markierten Bereich eines Feldes aus und legt ihn in die Zwischenablage.

DeleteDocument

Schließt das Dokument und markiert es zum Löschen.

DeselectAll

Deaktiviert alle eventuell vorgenommenen Auswahlen im Dokument.

ExpandAllSections

Öffnet alle Abschnitte des Dokuments.

FieldAppendText

Hängt einen String an den Text in einem Feld an.

FieldClear

Löscht den Inhalt eines Feldes.

FieldContains

Integer Flag

Prüft, ob ein Feld einen bestimmten Wert enthält.

FieldGetText

String

Gibt den Inhalt eines Feldes als String zurück.

FieldSetText FindFreeTimeDialog

Setzt den Inhalt eines Feldes. Integer Flag

(X)

Öffnet die Free-Time-Suche (Suche nach einer gemeinsamen freien Zeitscheibe für mehrere Benutzer). R5: Der Rückgabewert ist neu. Er zeigt an, ob die Box mit OK (TRUE) oder Cancel (FALSE) geschlossen wurde.

FindFreeTimeDialogEx

Integer Flag

FindString

X

Dieselbe Methode wie FindFreeTimeDialog. Der einzige Unterschied besteht darin, dass statt Strings String-Arrays als Parameter übergeben werden.

X

Sucht einen bestimmten Text innerhalb eines Feldes.

Forward

Leitet eine Mail weiter.

GetObject

Variant

GetSelectedText

String

GotoBottom

Gibt einen Handle auf ein spezifiziertes OLEObjekt zurück. X

Ergreift den im Dokument markierten Text. Setzt den Cursor auf das unterste aktivierbare Element im Frontend-Dokument. Das ist entweder das unterste editierbare Feld oder der unterste Button.

GotoField

Stellt den Cursor auf das spezifizierte Feld.

GotoNextField

Setzt den Cursor auf das nächste Feld.

GotoPrevField

Setzt den Cursor auf das vorangehende Feld.

NotesUIDocument

Name

369

Datentyp

R5

GotoTop

Beschreibung Setzt den Cursor auf das oberste aktivierbare Element im Frontend-Dokument. Das ist entweder das oberste editierbare Feld oder der oberste Button.

Import

X

Importiert eine Datei.

InsertText

Fügt einen Text an der Stelle ein, wo der Cursor steht.

NavBarSetText

Fügt den spezifizierten Text in das URL-Feld ein.

NavBarSpinnerStart

Startet die Suche nach der mit der URL verknüpften Ressource.

NavBarSpinnerStop

Beendet die Suche nach der mit der URL verknüpften Ressource.

Paste

Fügt den Inhalt der Zwischenablage an die Stelle eines Feldes ein, an der der Cursor steht.

Print

Druckt das Dokument.

Refresh

Berechnet das Dokument neu.

RefreshHideFormulas

Berechnet die Hide-When-Formeln neu.

Reload

Lädt Änderungen des Backend-Dokuments neu und zeigt sie im Frontend an.

Save

Speichert das Dokument.

SaveNewVersion

Speichert das Dokument als neue Version.

SelectAll

Markiert den ganzen Inhalt eines Dokuments im Lesemodus. Befindet es sich dagegen im Editiermodus, so wird der Inhalt aller editierbaren Felder ausgewählt.

Send

Versendet das Dokument als Mail.

SpellCheck

X

Führt eine Rechtschreibprüfung über das Frontend-Dokument aus.

Ev en t s Name

Datentyp

R5

Beschreibung

PostModeChange

Das Ereignis, das unmittelbar nach einer Änderung des Anzeigemodus des Dokuments auftritt.

PostOpen

Das Ereignis, das nach dem Öffnen des Dokuments auftritt.

PostRecalc

Das Ereignis, das nach der Neuberechnung des Dokuments auftritt.

PostSave

Das Ereignis, das nach dem Speichern des Dokuments auftritt.

QueryClose

Das Ereignis, das vor dem Schließen des Dokuments auftritt.

370

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

QueryModeChange

Das Ereignis, das vor der Neuberechnung des Dokuments auftritt.

QueryOpen

Das Ereignis, das vor dem Öffnen des Dokuments auftritt.

QuerySave

Das Ereignis, das vor dem Speichern des Dokuments auftritt.

23.33 NotesUIView NotesUIView repräsentiert die aktuell im Frontend geöffnete Ansicht. Diese Ansicht wird im aktivierten Fenster angezeigt. Der Zugriff wird über den Eventhandler gewährt, der auf einen der Events der Klasse NotesUIView hin angestoßen wird, z. B.: PostOpen ( source As NotesUIView ) Eigenschaften Name

Datentyp

R5

CalendarDateTime

DateTime-Variant

Beschreibung Momentane Zeit der eingestellten Zeitzone in einer Kalenderansicht.

CaretCategory

X

Gibt die Kategorie zurück, zu der das im Frontend aktive bzw. in der Ansicht selektierte Dokument gehört.

Documents

NotesDocumentCollection

Die Dokumente, die von einem Event der NotesUIView berührt werden.

View

NotesView

Die Ansicht im Backend.

Viewname

X

Name der Ansicht.

Methoden Name Print

Datentyp

R5

Beschreibung

X

Druckt die ausgewählten Dokumente der Ansicht.

SelectDocument

Setzt den Zeilen-Cursor auf das Frontend-Dokument zu dem angegebenen Backend-Dokument.

Events Name PostDragDrop

Datentyp

R5

Beschreibung Das Ereignis nach dem Ausführen einer Dragand-drop-Operation in einer Kalenderansicht .

NotesUIWorkspace

371

Name

Datentyp

R5

Beschreibung

PostOpen

Das Ereignis nach dem Öffnen der FrontendAnsicht.

PostPaste

Das Ereignis unmittelbar nach dem Einfügen eines Dokuments per Paste.

QueryAddToFolder

Das Ereignis, bevor ein Dokument zu einem Ordner hinzugefügt wird.

QueryClose

Das Ereignis vor dem Öffnen der FrontendAnsicht.

QueryDragDrop

Das Ereignis vor dem Ausführen einer Drag-anddrop-Operation in einer Kalenderansicht.

QueryOpen

Das Ereignis vor dem Öffnen der FrontendAnsicht.

QueryOpenDocument

Das Ereignis vor dem Öffnen eines Dokuments in der Frontend-Ansicht.

QueryPaste

Das Ereignis unmittelbar vor dem Einfügen eines Dokuments per Paste.

QueryRecalc

Das Ereignis, bevor ein Recalc auf der Ansicht ausgeführt wird.

RegionDoubleClick

Das Ereignis unmittelbar nachdem ein freier Teil in einer KalenderAnsicht doppelt angeklickt wurde.

23.34 NotesUIWorkspace NotesUIWorkspace repräsentiert den Arbeitsbereich des Benutzers, der mit dem im Frontend aktivierten Fenster verknüpft ist. Der Zugriff wird über ein mit New neu erzeugtes Objekt gewährt: Dim notesUIWorkspace As New NotesUIWorkspace Eigenschaften Name

Datentyp

CurrentCalendarDateTime

DateTime-Variant

CurrentDatabase

NotesUIDatabase

CurrentDocument

NotesUIDocument

CurrentView

NotesUIView

R5

Beschreibung Datum und Zeit des ausgewählten Bereichs einer Kalenderansicht.

X

Frontend-Repräsentation der Datenbank, die dem aktiven Fenster zugeordnet ist. Das Dokument, das der Benutzer im Frontend bearbeitet.

X

Frontend-Repräsentation der Ansicht, die dem aktiven Fenster zugeordnet ist.

372

Kurzreferenz der Notes/Domino-Klassen

Method en Name

Datentyp

R5

Beschreibung

AddDatabase

Fügt eine Datenbankkachel zum Arbeitsblatt hinzu.

CheckAlarms

Stößt den Alarm-Task an. Dieser fragt die Mail-Datenbank nach neuen AlarmEreignissen ab.

ComposeDocument

Erzeugt ein neues Dokument mittels der angegebenen Maske und zeigt es im aktivierten Fenster an.

DialogBox

(X)

Öffnet ein Dokument in einer DialogBox, wobei das Aussehen der Box durch eine anzugebende Maske gesteuert wird. R5: Neuer optionaler Parameter »sizeToTable« (Integer Flag). Dieser gibt an, ob die Boxgröße einer in der Maske enthaltenen Tabelle angepasst werden soll. R5: Neuer optionaler Parameter »noOKCancel« (Integer Flag). Dieser gibt an, ob die Buttons »OK« und »Cancel« nicht angezeigt werden sollen.

EditDocument

Öffnet das aktuelle oder ein anderweitig spezifiziertes Dokument in dem Anzeigemodus, der über den Parameter »editMode« angegeben wurde. Das aktuelle Dokument ist dasjenige, das in einer Ansicht ausgewählt wurde, oder dasjenige, das im aktivierten Fenster geöffnet ist.

EditProfile

Öffnet ein Profildokument im Editiermodus. Wenn es noch nicht existiert, so wird es neu angelegt.

EnableAlarms

Startet oder beendet den Alarm-Task.

Folder

GetListOfTunes

Variant Array

X

Zeigt eine Dialogbox an, mit der bestimmt werden kann, in welchen Ordner das aktuelle Dokument verschoben wird.

X

Gibt eine Liste der auf dem System verfügbaren Sounds zurück.

OpenDatabase

Öffnet eine Datenbank. Die Ansicht, die beim Start angezeigt wird, kann angegeben werden.

OpenFileDialog

X

Zeigt die Dialogbox zum Auswählen einer Datei an.

OpenFrameSet

X

Öffnet eine Rahmengruppe und springt dabei in einen anzugebenden Zielrahmen.

NotesView

Name

373

Datentyp

OpenPage

R5

Beschreibung

X

Öffnet eine Seite im angegebenen Zielrahmen.

PickListCollection

NotesDocumentCollection

X

Öffnet eine Dialogbox mit einer Pickliste. Gibt die ausgewählten Notes-Dokumente zurück.

PickListStrings

String Array

X

Öffnet eine Dialogbox mit einer Pickliste. Gibt die Werte einer anzugebenden Spalte in einem Array zurück.

X

Spielt eine Klangdatei ab.

Variant (Integer, String oder String Array)

X

Öffnet eine Dialobox, wie sie in der Formelsprache per @Prompt aufgerufen wird.

RefreshParentNote

X

Führt ein Refresh über das Dokument aus, das sich im Zugriff einer Dialogbox befindet.

ReloadWindow

X

Führt ein Reload für das aktive Fenster aus.

X

Öffnet die Dialogbox, mit der Dateien abgespeichert werden.

SetCurrentLocation

X

Stellt die Arbeitsumgebung ein.

SetTargetFrame

X

Wählt den Zielrahmen aus, der beim Öffnen gewählt wird. Diese Methode wird gestartet, bevor OpenFrameSet, OpenPage, OpenView, ComposeDocument oder EditDocument ausgeführt wird.

PlayTune Prompt

SaveFileDialog

String Array

URLOpen

Öffnet eine Web-Seite per URL.

UseLSX

Lädt eine LSX-Datei.

ViewRefresh

Führt ein Refresh auf der aktiven View im Frontend aus.

23.35 NotesView NotesView repräsentiert eine Ansicht in einer Notes-Datenbank. Über diese Klasse erhält man Zugriff auf die in der Ansicht ausgewählten Dokumente. Man erhält Zugriff auf bereits bestehende Ansichten. Dazu gibt es die GetViewMethode und die Views-Eigenschaft der Klasse NotesDatabase: Dim notesView As NotesView Set notesView = NotesDatabase.GetView ( name$ )

374

Kurzreferenz der Notes/Domino-Klassen

oder Dim vViews As Variant vViews = notesDatabase.Views Außerdem lässt sich ein NotesView-Objekt aus der NotesUIView-Klasse gewinnen: Dim notesView As NotesView Set notesView = notesUIView.View Ei g en s ch af t en Name

Datentyp

Aliases

String Array

R5

Beschreibung

AllEntries

NotesViewEntry-Collection

AutoUpdate

Integer Flag

BackgroundColor

Integer

X

Die Hintergrundfarbe der Ansicht.

ColumnCount

Integer

X

Anzahl der Spalten

Columns

NotesViewColumn Array

Alle Spalten der Ansicht

Created

DateTime

Zeitpunkt, zu dem die Ansicht erstellt wurde.

Alle Aliase der Ansicht X

Alle Einträge einer Ansicht (Read-Write) Gibt an, ob die UI-Ansicht (NotesUIView) jedesmal mit den Änderungen der Ansicht im Back-End (NotesView) aktualisiert wird. Die Aktualisierung bezieht sich nur auf die Suchreihenfolge, nicht auf die Sicht des Benutzers.

HeaderLines

Integer

IsCalendar

Integer Flag

X

Anzahl der Zeilen im Spaltenkopf.

IsCategorized

Integer Flag

X

Gibt an, ob die Ansicht kategorisiert ist.

IsConflict

Integer Flag

X

Gibt an, ob die Ansicht Konflikte registriert.

IsDefaultView

Integer Flag

IsFolder

Integer Flag

IsHierarchical

Integer Flag

X

Zeigt die Ansicht Antwortdokumente in hierarchischer Form an?

IsModified

Integer Flag

X

Wurde die Ansicht verändert?

IsPrivate

Integer Flag

X

Zeigt an, ob ein Eintrag einem Individuum zuzuordnen ist.

LastModified

DateTime

Gibt an, ob die Ansicht im Kalenderformat vorliegt.

Gibt an, ob dies die Vorgabe-Ansicht der Datenbank ist. Gibt an, ob dies ein Ordner ist.

Zeitpunkt, zu dem die Ansicht das letzte Mal geändert wurde.

NotesView

375

Name

Datentyp

R5

Beschreibung

Name

String

Name der Ansicht. Zeigt keine Aliase an.

Parent

NotesDatabase

Die Datenbank, zu der diese Ansicht gehört.

ProtectReaders

Integer Flag

(Read-Write) Sorgt dafür, dass das Feld $Readers bei Replikationen nicht überschrieben wird.

Readers

String Array

(Read-Write) Array mit den Namen, die im Feld $Readers eingetragen sind. Wenn ein Leerstring ("") übergeben wird, wird das Feld geleert.

RowLines

Integer

X

Die Anzahl der Zeilen pro Ansichtszeile.

Spacing

Integer

X

Der Abstand zwischen den Ansichtszeilen.

TopLevelEntryCount

Integer

X

Anzahl der Einträge auf der höchsten Hierarchiestufe.

UniversalID

String

Die UniversalID der Ansicht.

Method en Name

Datentyp

R5

Clear

Beschreibung Löscht den Filter einer vorherigen Volltextsuche.

CreateViewNav

NotesViewNavigator

X

Erstellt einen Ansichtsnavigator für alle Einträge, die in der Ansicht vorhanden sind (auch die Einträge, die durch einen Volltextfilter ausgeblendet sind, sind eingeschlossen).

CreateViewNavFrom

NotesViewNavigator

X

Wie CreateViewNav, mit dem Unterschied, dass die Ansichtseinträge ab einem bestimmten Eintrag berücksichtigt werden.

CreateViewNavFrom-Category

NotesViewNavigator

X

Wie CreateViewNav, mit dem Unterschied, dass nur die Ansichtseinträge berücksichtigt werden, die zu einer bestimmten Kategorie gehören.

CreateViewNavFrom-Children

NotesViewNavigator

X

Wie CreateViewNav, mit dem Unterschied, dass nur die Ansichtseinträge berücksichtigt werden, die die direkten Nachkommen des betrachteten Eintrags darstellen.

CreateViewNavFrom-Descendants

NotesViewNavigator

X

Wie CreateViewNavFromChildren, mit dem Unterschied, dass alle Nachkommen berücksichtigt werden.

376

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

FTSearch

Integer

Führt auf der Ansicht eine Volltextsuche durch. Die Ansicht zeigt anschließend nur noch die gefilterten Dokumente an. Der Rückgabewert zeigt die Anzahl der gefundenen Dokumente an.

GetAllDocumentsByKey

NotesDocumentCollection

Gibt sämtliche Dokumente aus, die über einen Schlüssel in der Ansicht gefunden werden. Die Suche wird über die erste sortierte Spalte der Ansicht geführt.

GetAllEntriesByKey

NotesViewEntryCollection

GetChild

NotesDocument

Gibt das Kind-Dokument zu dem übergebenen Dokument zurück (falls vorhanden).

GetDocumentByKey

NotesDocument

Analog zur Methode GetAll-DocumentsByKey. Im Unterschied zu dieser wird hier nur das jeweils erste Trefferdokument zurückgegeben.

GetEntryByKey

NotesViewEntry

GetFirstDocument

NotesDocument

Gibt das erste Dokument zurück.

GetLastDocument

NotesDocument

Gibt das letzte Dokument aus.

GetNextDocument

NotesDocument

Gibt das nächste Dokument der Collection zurück. Der Ausdruck »nächste« bezieht sich dabei auf das Dokument, das der Methode zur Suche übergeben wird.

GetNextSibling

NotesDocument

Gibt das nächste Bruder-Dokument zurück. Näheres dazu siehe Notes-Hilfe.

GetNthDocument

NotesDocument

Gibt das Dokument zurück, das sich an der mit einer Ordnungsnummer bezeichneten Stelle befindet.

GetParentDocument

NotesDocument

Gibt das Eltern-Dokument zu dem übergebenen Dokument zurück (falls vorhanden).

GetPrevDocument

NotesDocument

Analog zu GetNextDocument, nur dass das vorhergehende Dokument ausgegeben wird.

GetPrevSibling

NotesDocument

Gibt das vorhergehende Bruder-Dokument zurück. Näheres dazu siehe NotesHilfe.

X

X

Beschreibung

Analog zur Methode GetAll-DocumentsByKey, allerdings für NotesViewEntryObjekte.

Analog zur Methode Get-DocumentByKey, allerdings für NotesViewEntryObjekte.

NotesViewColumn

Name

377

Datentyp

R5

Beschreibung

Refresh

Aktualisiert die Ansicht mit den Änderungen, die an den Dokumenten in der Datenbank vollzogen wurden.

Remove

Entfernt die Ansicht von der Platte (ohne weitere Nachfrage!).

23.36 NotesViewColumn NotesViewColumn repräsentiert eine Spalte einer Ansicht oder auch eines Ordners. Man erlangt Zugriff auf das NotesViewColumn-Objekt durch die Columns-Eigenschaft der NotesView-Klasse: Dim vViewColumns As Variant Set vViewColumns = NotesView.Columns Um eine einzelne NotesViewColumn auszuwählen, verwenden Sie den Index-Operator: Dim notesViewColumn As NotesViewColumn Set notesViewColumn = NotesView.Columns ( index% ) Eigenschaften Name

Datentyp

R5

Beschreibung

Alignment

Integer

X

Spaltenausrichtung der Daten

DateFmt

Integer

X

Datumsformat in der Spalte

FontColor

Integer

X

Farbe der Schrift in der Spalte

FontFace

String

X

Schriftart

FontPointSize

Integer

X

Schiftgröße in Punkt

FontStyle

Integer

X

Schriftstil

Formula

String

HeaderAlignment

Integer

X

Ausrichtung der Schrift im Spaltenkopf

IsAccentSensitiveSort

Integer Flag

X

Gibt an, ob die Spalte unter Berücksichtigung von Accents sortiert ist.

IsCaseSensitiveSort

Integer Flag

X

Gibt an, ob die Spalte unter Berücksichtigung der Groß-/Kleinschreibung sortiert ist.

IsCategory

Integer Flag

IsField

Integer Flag

Die Spaltenformel (sofern eine existiert)

Gibt an, ob die Spalte kategorisiert ist. X

Gibt an, ob der Spaltenwert auf einem Feldwert beruht.

378

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

IsFormula

Integer Flag

X

Gibt an, ob die Spaltenwerte auf einer Formel beruhen.

IsHidden

Integer Flag

IsHideDetail

Integer Flag

X

Gibt an, ob in einer Summenspalte die Zwischensummen der Kategorien versteckt werden.

IsIcon

Integer Flag

X

Gibt an, ob die Spaltenwerte als Icons angezeigt werden.

IsResize

Integer Flag

X

Gibt an, ob die Spaltenbreite veränderbar ist.

IsResortAscending

Integer Flag

X

Zeigt an, ob die Spalte, deren Sortierung veränderbar ist, aufsteigend sortiert werden kann.

IsResortDescending

Integer Flag

X

Zeigt an, ob die Spalte, deren Sortierung veränderbar ist, absteigend sortiert werden kann.

IsResortToView

Integer Flag

X

Zeigt an, ob die Sortierung der Spalte verändert werden kann.

IsResponse

Integer Flag

IsSecondaryResort

Integer Flag

X

Zeigt an, ob die Spalte eine SekundärSortierspalte darstellt.

IsSecondaryResortDescending

Integer Flag

X

Zeigt an, ob die Sekundär-Sortierspalte in absteigender Reihenfolge sortiert werden kann.

IsShowTwistie

Integer Flag

X

Zeigt an, ob die Spalte ein Pfeilsymbol (grünes Dreieck) anzeigt, falls die Zeile erweiterbar ist.

IsSortDescending

Integer Flag

X

Gibt an, ob die Spalte in absteigender Reihenfolge sortiert ist.

IsSorted

Integer Flag

Gibt an, ob die Spalte sortiert ist.

ItemName

String

Gibt den Namen eines Feldes an, dessen Wert in der Spalte angezeigt wird.

ListSep

Integer

X

Trennzeichen für Mehrfachwerte in der Spalte.

NumberAttrib

Integer

X

Anzeigeattribute für numerische Werte in der Spalte.

NumberDigits

Integer

X

Anzahl der Nachkommastellen für numerische Werte.

NumberFormat

Integer

X

Format für die Anzeige numerischer Werte.

Zeigt an, ob die Spalte versteckt ist.

Zeigt an, ob die Spalte nur Antwortdokumente enthält.

NotesViewEntry

379

Name

Datentyp

R5

Beschreibung

Position

Integer

TimeDateFmt

Integer

X

Anzeigeformat für Zeit-/Datumswerte.

TimeFmt

Integer

X

Anzeigeformat für Zeitwerte.

TimeZoneFmt

Integer

X

Anzeigeformat für Zeitzonen.

Title

String

Spaltentitel

Width

Integer

Breite der Spalte

Ordnungsnummer der Spalte bezüglich der übrigen Spalten (von links nach rechts gezählt).

23.37 NotesViewEntry NotesViewEntry repräsentiert einen Eintrag bzw. eine Zeile in der NotesView. Dazu zählen auch Summen- und Kategoriezeilen. Das Objekt wurde in R5 neu eingeführt. Man erhält Zugriff auf ein NotesViewEntry-Objekt durch die NotesView-Methode GetEntryByKey oder die Get-Methoden der Klassen NotesViewNavigator und NotesViewEntryCollection. Beispiel: Dim notesViewEntry As NotesViewEntry Set notesViewEntry = notesView.GetEntryByKey ( key$ ) (Der Stringparameter key$ stellt nur eine Möglichkeit der Parametrisierung dieser Methode dar.) Eigenschaften Name

Datentyp

R5

Beschreibung

ChildCount

Integer

X

Anzahl der unmittelbaren Kinddokumente, bezogen auf das Dokument, auf das sich der NotesViewEntry bezieht.

ColumnIndentLevel

Integer

X

Der Grad der Spalteneinrückung. Hiermit wird angezeigt, die wievielte Generation das betreffende Dokument in Bezug auf das Hauptdokument darstellt.

ColumnValues

Variant Array

X

Anzahl der Spalten.

DescendantCount

Integer

X

Anzahl der Nachfolger zu dem durch den NotesViewEntry repräsentierten Dokument.

Document

NotesDocument

X

Das Dokument, das dem NotesViewEntry zugeordnet ist.

380

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

FTSearchScore

Integer

X

Falls der NotesViewEntry das Ergebnis einer Volltextsuche ist, gibt diese Eigenschaft den Trefferquotienten an.

IndentLevel

Integer

X

Der Einrückungslevel. Deckt sich mit der Notes-Positionsangabe.

IsCategory

Integer Flag

X

Gibt an, ob der Eintrag eine Kategorie ist.

IsConflict

Integer Flag

X

Gibt an, ob das dem Eintrag zugeordnete Dokument ein Konfliktdokument ist.

IsDocument

Integer Flag

X

Zeigt, ob dem Eintrag ein Dokument zugeordnet ist.

IsTotal

Integer Flag

X

Gibt an, ob es sich um einen Summeneintrag handelt.

IsValid

Integer Flag

X

Gibt an, ob es sich um einen gültigen Eintrag handelt.

NoteID

String

X

Die NoteID mit vorangestelltem »NT«.

Parent

NotesView

X

Das Elternobjekt des Eintrags. Kann ein Objekt vom Typ NotesViewEntryCollection, NotesViewNavigator oder NotesView sein.

SiblingCount

Integer

X

Die Anzahl der Nachfolger, die diesem Eintrag zugeordnet sind.

UniversalID

String

X

Die UniversalID des Dokuments, das dem Eintrag zugeordnet ist.

Method en Name

Datentyp

R5

Beschreibung

GetPosition

String

X

Gibt die Position des Eintrags innerhalb der Hierarchie der Einträge zurück.

23.38 NotesViewEntryCollection NotesViewEntryCollection ist eine Collection von NotesView-Einträgen. Die Einträge sind in der gleichen Reihenfolge sortiert, wie sie in der Ansicht vorliegen. Das Objekt wurde in R5 neu eingeführt. Man erhält Zugriff auf ein NotesViewEntryCollection-Objekt durch die NotesViewEigenschaft AllEntries Methode GetAllEntriesByKey. Beispiel: Dim notesViewEntryCollection As NotesViewEntryCollection Set notesViewEntryCollection = notesView.GetAllEntriesByKey ( key$ )

NotesViewNavigator

381

(Der Stringparameter key$ stellt nur eine Möglichkeit der Parametrisierung dieser Methode dar.) Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

Count

Long

Parent

NotesView

Die Ansicht, über die die Collection erhalten wurde.

Query

String

Die Selectionsformel, über die die Collection erhalten wurde.

Die Anzahl der NotesViewEntries in der Collection.

Method en Name

Datentyp

R5

Beschreibung

AddEntry

Fügt der Collection einen weiteren Eintrag hinzu.

DeleteEntry

Entfernt einen Eintrag aus der Collection.

FTSearch

Führt eine Volltextsuche über die Collection aus und entfernt alle Einträge, die von der Suche nicht gefunden werden.

GetEntry

NotesViewEntry

Gibt einen bestimmten Eintrag zurück.

GetFirstEntry

Gibt den ersten Eintrag zurück.

GetLastEntry

Gibt den letzten Eintrag zurück.

GetNextEntry

Gibt den nächsten Eintrag zurück.

GetNthEntry

Gibt einen bestimmten Eintrag zurück (Auswahl über die Ordnungsnummer).

GetPrevEntry

Gibt den vorhergehenden Eintrag zurück.

PutAllInFolder

Fügt alle Einträge in einen Ordner ein.

RemoveAll

Entfernt alle Einträge aus der Collection.

RemoveAllFromFolder

Entfernt alle Einträge aus einem Ordner.

StampAll

Überschreibt den Wert eines bestimmten Feldes in allen Dokumenten der Collection. Die Änderung erfolgt dauerhaft, ohne dass Save aufgerufen werden muss. Nicht existierende Felder werden neu angelegt.

UpdateAll

Markiert alle Dokumente der Collection mit einem Bearbeitungskennzeichen eines Agenten.

23.39 NotesViewNavigator Ein Objekt dieser Klasse dient zur Navigation in einer Menge von Ansichtseinträgen. Darin sind auch Summen- und Kategoriezeilen eingeschlossen.

382

Kurzreferenz der Notes/Domino-Klassen

Das Objekt wurde in R5 neu eingeführt. Es wird durch eine der folgenden Methoden der NotesView erzeugt: CreateViewNav, CreateViewNavFrom, CreateViewNavFromCategory, CreateViewNavFromDescendants. Beispiel: Dim notesViewNavigator As NotesViewNavigator Set notesViewNavigator = notesView.GetViewNav Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

MaxLevel

Long

X

(Read-Write) Die maximale Hierarchie-Tiefe, die in einer Ansicht verfolgt wird. Sie kann nicht kleiner sein als die bereits durch den Typ des Navigators vorgegebene minimale Tiefe.

ParentView

NotesView

X

Die Ansicht, aus der der Navigator gewonnen wurde.

Method en Name

Datentyp

R5

Beschreibung

GetChild

NotesViewEntry

X

Gibt den ersten Kindeintrag zu einem Eintrag des Navigators.

GetEntry

NotesViewEntry

X

Gibt den spezifizierten Eintrag zurück.

GetFirst

NotesViewEntry

X

Gibt den ersten Eintrag zurück.

GetFirstDocument

NotesViewEntry

X

Gibt das erste Dokument zurück, wobei eventuell vorhandene Kategorien übergangen werden.

GetLast

NotesViewEntry

X

Gibt den letzten Eintrag zurück.

GetLastDocument

NotesViewEntry

X

Gibt das erste Dokument zurück, wobei eventuell vorhandene Kategorien und Summenzeilen übergangen werden.

GetNext

NotesViewEntry

X

Gib den nächsten Eintrag zurück.

GetNextCategory

NotesViewEntry

X

Gibt die nächste Kategorie zurück.

GetNextDocument

NotesViewEntry

X

Gibt das nächste Dokument zurück, wobei eventuell vorhandene Kategorien übergangen werden.

GetNextSibling

NotesViewEntry

X

Gibt den nächsten Brudereintrag zurück.

GetNth

NotesViewEntry

X

Gibt den mit einer Ordnungsnummer spezifizierten Eintrag zurück.

GetParent

NotesViewEntry

X

Gibt den Elterneintrag zu einem bestimmten Eintrag zurück.

GetPos

NotesViewEntry

X

Gibt den Eintrag an einer spezifizierten Position zurück.

GetPrev

NotesViewEntry

X

Gibt den vorhergehenden Eintrag zurück.

ODBCConnection

383

Name

Datentyp

R5

Beschreibung

GetPrevCategory

NotesViewEntry

X

Gibt die vorhergehende Kategorie zurück.

GetPrevDocument

NotesViewEntry

X

Gibt das vorhergehende Dokument zurück, wobei eventuell vorhandene Kategorien übergangen werden.

GetPrevSibling

NotesViewEntry

X

Gibt den vorhergehenden Brudereintrag zurück.

23.40 ODBCConnection ODBCConnection repräsentiert eine ODBC-Sitzung. Es verwaltet die zugehörige Verbindung und bietet die Möglichkeit, alle über ODBCResultSet ausgeführten Aktionen durch ein Transaktionsverfahren zu sichern. Ein Objekt der Klasse ODBCConnection wird durch den New-Operator erzeugt: Dim odbcConnection As New ODBCConnection Eigenschaften Name

Datentyp

R5

Beschreibung

AutoCommit

Integer Flag

(Read-Write) Zeigt an, ob der AutocommitModus aktiv ist. Dazu muss die Datenbank diesen Modus unterstützen.

CommitOnDisconnect

Integer Flag

(Read-Write) Gibt an, ob eingeleitete Transaktionen beim Verbindungsabbau automatisch abgeschlossen oder zurückgefahren werden.

DataSourceName

String

Name der Datenquelle.

GetLSDOMasterRevision

String

Die Revisionsnummer der ODBC-LSX-Datei.

SilentMode

Integer Flag

(Read-Write) Verhindert, dass die Login-Dialogbox gezeigt wird.

Methoden Name

Datentyp

R5

Beschreibung

CommitTransactions

Integer Flag

Schließt alle aufgelaufenen Transaktionen ab.

ConnectTo

Integer Flag

Baut eine Verbindung zur ODBC-Datenquelle auf.

Disconnect

Integer Flag

Schließt die ODBC-Verbindung.

GetError

Integer

Gibt die Nummer des zuletzt aufgetretenen Fehlers zurück.

GetErrorMessage

String

Gibt die Fehlermeldung zurück, die zu der übergebenen Fehlernummer gehört.

384

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

GetExtendedError-Message

String

Gibt eine erweiterte Fehlermeldung zu der übergebenen Fehlernummer zurück.

IsConnected

Integer Flag

Zeigt an, ob die Verbindung noch steht.

IsSupported

Integer Flag

Gibt an, ob eine bestimmte Eigenschaft von der Datenquelle unterstützt wird.

ListDataSources

String Array

Gibt alle Namen der registrierten ODBCDatenquellen zurück.

ListFields

String Array

Gibt alle Feldnamen einer Tabelle zurück.

ListProcedures

String Array

Gibt die Namen aller in der Datenquelle gespeicherten Prozeduren (Stored Procedures) zurück.

ListTables

String Array

Gibt die Namen aller Tabellen der Datenquelle zurück.

RollbackTransactions

Integer Flag

Führt alle eingeleiteten und noch nicht per CommitTransactions abgeschlossenen Transaktionen zurück.

23.41 ODBCQuery ODBCQuery steht für eine SQL-Abfrage. Sobald eine Abfrage übergeben wird, wird sie hinsichtlich Tabellennamen, Parametern und anderen verfügbaren Einzelheiten geprüft. Eine komplette Syntaxüberprüfung wird allerdings erst bei der Ausführung durch das Datenbank-Managementsystem durchgeführt. Ein Objekt der Klasse ODBCQuery wird durch den New-Operator erzeugt: Dim odbcQuery As New ODBCQuery Eigenschaften Name

Datentyp

R5

Beschreibung

Connection

ODBCConnection

(Write-Only) Ordnet die SQL-Abfrage einer Verbindung zu.

QueryExecuteTimeOut

Integer

(Read-Write) Legt die Zeitspanne in Sekunden fest, nach der ein Timeout für eine SQL-Abfrage festgestellt wird.

SQL

String

(Read-Write) Ein SQL-Statement

UseRowID

Integer Flag

(Read-Write) Legt fest, ob auf die Tabellen der ODBC-Datenquelle per Zeilennummer zugegriffen wird.

ODBCResultSet

385

Method en Name

Datentyp

R5

Beschreibung

GetError

Gibt die Nummer des zuletzt aufgetretenen Fehlers zurück.

GetErrorMessage

Gibt die Fehlermeldung zurück, die zu der übergebenen Fehlernummer gehört.

GetExtendedError-Message

Gibt eine erweiterte Fehlermeldung zu der übergebenen Fehlernummer zurück.

23.42 ODBCResultSet ODBCResultSet steht für das Ergebnis einer SQL-Abfrage oder auch einer Aktion, die durch die Klasse selbst definiert ist. Ein Objekt der Klasse ODBCResultSet wird durch den New-Operator erzeugt: Dim odbcResultSet As New ODBCResultSet Ei g en s ch af t en Name

Datentyp

R5

Beschreibung

CacheLimit

Long

(Read-Write) Die maximale Anzahl der im Cache zu haltenden Zeilen.

CurrentRow

Long

(Read-Write) Die Nummer des aktiven Datensatzes im ResultSet.

FetchBatchSize

Long

(Read-Write) Die Anzahl der Datensätze, die bei Anfragen geladen werden.

MaxRows

ODBCQuery

(Read-Write) Die maximale Anzahl der Datensätze, die vom ResultSet geladen werden.

Query

Long

(Write-Only) Ordnet eine ODBCQuery einem ODBCResultSet zu. Dabei wird die Syntax der SQL-Abfrage des ODBCQuery-Objektes auf Korrektheit geprüft.

ReadOnly

Integer Flag

(Read-Write) Gibt an, ob ein ResultSet im ReadOnlyModus arbeitet.

Method en Name

Datentyp

R5

Beschreibung

AddRow

Integer Flag

Fügt dem ResultSet eine neue leere Zeile hinzu.

Close

Integer Flag

Schließt das ResultSet oder nur die mit AddRow angehängte neue Zeile.

386

Kurzreferenz der Notes/Domino-Klassen

Name

Datentyp

R5

Beschreibung

DeleteRow

Integer Flag

Löscht die aktuelle Zeile des ResultSets in der zugeordneten Datenbanktabelle.

ExecProcedure

Integer Flag

Führt eine Stored Procedure im Datenbanksystem aus.

Execute

Integer Flag

Führt das SQL-Statement der ODBCQuery aus.

FieldExpectedDataType

Integer

Setzt den Datentyp einer ResultSetSpalte oder gibt ihn zurück. Hat Auswirkungen auf die Typumwandlung vom nativen Datentyp auf den hier angegebenen.

FieldID

Integer

Gibt die Position der Spalte zurück. Ein Feld kann statt über den Namen auch über diese Positionsnummer angesprochen werden.

FieldInfo

Integer Array

Gibt ein Array mit allen verfügbaren Informationen über ein Feld (Spalte) zurück.

FieldName

String

Gibt den Namen einer über die Positionsnummer spezifizierten Spalte zurück.

FieldNativeDataType

Integer

Gibt den Datentyp aus der Datenbanktabelle zurück.

FieldSize

Integer

Die maximale Größe der Felddaten.

FirstRow

Integer Flag

Macht die erste Zeile im ResultSet zur aktuellen.

GetError

Integer

Gibt die Nummer des zuletzt aufgetretenen Fehlers zurück.

GetErrorMessage

String

Gibt die Fehlermeldung zurück, die zu der übergebenen Fehlernummer gehört.

GetExtendedErrorMessage

String

Gibt eine erweiterte Fehlermeldung zu der übergebenen Fehlernummer zurück.

GetParameter

Variant

Gibt den Wert zurück, der für einen Parameter gesetzt ist.

GetParameterName

String

Gibt den Namen eines über eine Indexnummer spezifizierten Parameters zurück.

GetRowStatus

Integer

Gibt den Änderungszustand der aktuellen Zeile zurück.

ODBCResultSet

387

Name

Datentyp

R5

Beschreibung

GetValue

Hängt vom zu erwartenden Datentyp und den Umwandlungsmöglichkeiten ab.

Gibt den Wert der durch die Positionsnummer spezifizierten Spalte zurück.

HasRowChanged

Integer Flag

Zeigt an, ob sich die Daten in der Datenbanktabelle gegenüber den vorher ins ResultSet geladenen geändert haben.

IsBeginOfData

Integer Flag

Zeigt an, ob die aktuelle Zeile die erste des ResultSets ist.

IsEndOfData

Integer Flag

Zeigt an, ob die aktuelle Zeile die letzte des ResultSets ist.

IsResultSetAvailable

Integer Flag

Zeigt an, ob das ResultSet durch die letzte Anfrage Daten aus der Datenbank erhalten hat.

IsValueAltered

Integer Flag

Zeigt an, ob der Wert einer ResultSet-Spalte mittels SetValue geändert worden ist.

IsValueNull

Integer Flag

Prüft, ob der Wert einer Spalte NULL ist.

LastRow

Integer Flag

Macht die letzte Zeile des ResultSets zur aktuellen.

LocateRow

Integer Flag

Sucht eine Zeile des ResultSets und macht sie zur aktuellen.

NextRow

Integer Flag

Macht die nächste Zeile zur aktuellen.

NumColumns

Integer

Gibt die Anzahl der Spalten im ResultSet zurück.

NumParameters

Integer

Gibt die Anzahl der Parameter des SQL-Statements im mit dem ResultSet verbundenen ODBCQuery-Objekt zurück.

NumRows

Integer

Gibt die Anzahl der Zeilen im ResultSet zurück.

PrevRow

Integer Flag

Macht die vorherige Zeile des ResultSets zur aktuellen.

SetParameter

Integer Flag

Setzt einen neuen Wert für einen Parameter.

SetValue

Integer Flag

Setzt in der spezifizierten Spalte einen neuen Wert.

UpdateRow

Integer Flag

Schreibt die Änderungen einer aktuellen Zeile in die Datenbanktabelle.

42

24

Die Befehls-Referenz

24.1 Aufbau der Referenz Besondere Anweisungen bzw. Funktionen In der Referenz sind Anweisungen und Funktionen aufgeführt, die eine besondere Rolle innerhalb von Lotus Script haben. Es sind Funktionen, wie z.B. Dim oder Typedef, die Variablen deklarieren oder benutzerdefinierte Datentypen definieren. Obwohl es formal nicht ganz korrekt ist, werden bei diesen Anweisungen die zu übergebenden Daten in der Referenz wie Parameter aufgeführt. Zwei verschiedene Rückgabewerte bei Funktionen Bei einigen Funktionen existieren zwei Varianten, eine Variante hat dabei den Zusatz $. Bei diesen Funktionen liefert die Variante ohne $ einen Variant-Datentyp und die Variante mit $ einen String-Datentyp zurück. Invalid Use of Null Sollte bei einem Parameter, der nicht den Wert NULL haben darf, dieser trotzdem mit NULL übergeben werden, so wird der Fehler Invalid Use of Null erzeugt. Type Mismatch Sollte bei der Parameterübergabe trotz der automatischen Typumwandelung kein passender Datentyp erzeugt werden können, so wird der Fehler Type Mismatch erzeugt.

24.2 Typumwandlung Wenn als Datentyp eines numerischen Ausdrucks Variant angegeben ist, gilt auch eine Zeichenkette, die in einen numerischen Wert umgewandelt werden kann, als numerischer Ausdruck. Wenn als Datentyp einer Zeichenkette Variant angegeben ist, gilt jeder Ausdruck, der in eine Zeichenkette umgewandelt werden kann, als Zeichenkette. Der Wert EMPTY wird bei numerischen Ausdrücken immer als Wert 0 interpretiert.

390

Die Befehls-Referenz

24.3 Verdeckte Typumwandlung LotusScript versucht bei Operationen immer auf einen zulässigen Datentyp zu casten (umzuwandeln). Dieses erzeugt manchmal recht obskure Ergebnisse wie beispielsweise die folgenden: Kette$ = "1.2" + "3.4" Wert% = "1.2" + "3.4"

=> =>

Kette$ = "1.23.4" Wert% = 1234

24.3.1 Das automatische Casting In LotusScript wird bei allen Operationen und Prozedur-Aufrufen bei Bedarf ein automatisches Casting durchgeführt. Bei dem automatischen Casting versucht der Script-Interpreter den gegebenen Wert in den geforderten Datentyp umzuwandeln. Wenn dabei, bei einer zweistelligen Operation, ein numerischer Datentyp und ein alphanumerischer Datentyp aufeinandertreffen, ist der resultierende Datentyp ein Double. Es wird der numerische Datentyp immer dem alphanumerischen Datentyp vorgezogen. Und wenn zwei numerische Datentypen aufeinandertreffen, dominiert der Datentyp mit dem größten Wertebereich. Beim Casten ist es egal, in welcher Reihenfolge die Datentypen verknüpft werden.

24.3.2 Beispiele für automatisches Casting Hier einige Beispiele für das Casten von Datentypen: A

B

A + B bzw. A - B

INTEGER

INTEGER

INTEGER

LONG

INTEGER

LONG

SINGLE

INTEGER

SINGLE

DOUBLE

INTEGER

DOUBLE

CURRENCY

INTEGER

CURRENCY

STRING

INTEGER

DOUBLE

Einige Beispiele für die Grundoperationen bei verschiedenen Datentypen: A

B

Ergebnis bei Addition bzw. Subtraktion

Ergebnis bei Multiplikation bzw. Division

numerisch alphanumerisch

numerisch

numerisch

numerisch

alphanumerisch

alphanumerisch (Konkatenation)

numerisch

alphanumerisch

numerisch

numerisch

numerisch

Befehlsgruppen

391

24.4 Befehlsgruppen 24.4.1 Konvertierung Befehl

Beschreibung

CSng

Wandelt Ausdruck in Single-Datentyp

CInt

Wandelt Ausdruck in Integer-Datentyp

CLng

Wandelt Ausdruck in Long-Datentyp

CDbl

Wandelt Ausdruck in Double-Datentyp

CCur

Wandelt Ausdruck in Currency-Datentyp

CStr

Wandelt Ausdruck in String-Datentyp

CVar

Wandelt Ausdruck in Variant-Datentyp

24.4.2 Typenprüfung Befehl

Beschreibung

IsArray

Überprüft, ob der Ausdruck ein Array ist

IsDate

Überprüft, ob der Ausdruck ein Datum ist

IsEmpty

Überprüft, ob der Ausdruck den Wert EMPTY hat

IsNull

Überprüft, ob der Ausdruck den Wert NULL hat

IsNumeric

Überprüft, ob der Ausdruck numerisch ist

IsA

Überprüft, ob der Ausdruck einen angegebenen Datentyp hat

IsList

Überprüft, ob der Ausdruck eine Liste ist

IsElement

Überprüft, ob der Ausdruck ein Element der angegebenen Liste ist

IsObject

Überprüft, ob der Ausdruck ein Objekt ist

IsScalar

Überprüft, ob der Ausdruck ein einfacher Datentyp ist

IsDefined

Überprüft, ob der Ausdruck definiert ist

IsUnknown

Überprüft, ob der Ausdruck unbekannt ist

24.4.3 Datumsfunktionen I Befehl

Beschreibung

Year

Liefert die Jahreszahl eines Datums

Month

Liefert den Monat eines Datums

Day

Liefert den Tag eines Datums

Weekday

Liefert den Wochentag eines Datums

Hour

Liefert die Stunden eines Zeitwertes

Minute

Liefert die Minuten eines Zeitwertes

Second

Liefert die Sekunden eines Zeitwertes

392

Die Befehls-Referenz

24.4.4 Mathematische Funktionen Befehl

Beschreibung

Abs

Liefert den Absolutwert eines Ausdrucks

Sgn

Liefert das Vorzeichen eines Ausdrucks

Sin

Liefert den Sinus eines Winkels

Cos

Liefert den Kosinus eines Winkels

Tan

Liefert den Tangens eines Winkels

ASin

Liefert den Arkussinus eines Ausdrucks

ACos

Liefert den Arkuskosinus eines Ausdrucks

ATn

Liefert den Arkustangens eines Ausdrucks

ATn2

Liefert den Winkel der Polarkoordinaten von einem Punkt in der kartesischen Ebene im Bogenmaß

Log

Liefert den Logarithmus eines Ausdrucks

Exp

Liefert die Potenz der Zahl e

Sqr

Liefert die Quadratwurzel

24.4.5 Zufallszahlen Befehl

Beschreibung

Rnd

Liefert eine Zufallszahl

Randomize

Initialisiert den Zufallsgenerator

24.4.6 Zeichenkette I Befehl

Beschreibung

Len

Liefert die Länge einer Zeichenkette oder den Speicherbedarf einer Variable

Left

Liefert die linke Teilzeichenkette

Right

Liefert die rechte Teilzeichenkette

Mid

Liefert eine Teilzeichenkette

InStr

Sucht eine Zeichenkette in einer Zeichenkette

LCase

Wandelt alle Buchstaben einer Zeichenkette in Kleinbuchstaben

UCase

Wandelt alle Buchstaben einer Zeichenkette in Großbuchstaben

LTrim

Entfernt alle führenden Leerzeichen

RTrim

Entfernt alle abschließenden Leerzeichen

Trim

Entfernt alle führenden und abschließenden Leerzeichen

Befehlsgruppen

393

24.4.7 Zeichenketten II Befehl

Beschreibung

Val

Wandelt eine Zeichenkette zu einem numerischen Datentyp

Str

Wandelt einen numerischen Ausdruck in eine Zeichenkette

Uni

Liefert den Unicode eines Zeichens

Chr

Liefert ein Zeichen entsprechend seinem ASCII-Code

Asc

Liefert den ASCII-Code eines Zeichens

UChr

Liefert ein Zeichen entsprechend seinem Unicode

Oct

Liefert die Octaldarstellung eines numerischen Wertes als Zeichenkette

Hex

Liefert die Hexdarstellung eines numerischen Wertes als Zeichenkette

Bin

Liefert die Binärdarstellung eines numerischen Wertes als Zeichenkette

UString

Liefert eine Zeichenkette mit der angegebenen Anzahl eines Unicode-Zeichens

String

Liefert eine Zeichenkette mit der angegebenen Anzahl eines ASCII-Code-Zeichens

24.4.8 Zeichenketten III Befehl

Beschreibung

StrComp

Vergleicht Zeichenketten

StrCompare

Vergleicht Zeichenketten

StrLeft

Sucht einen Teilstring und gibt den Teil links davon aus

StrleftBack

wie StrLeft mit umgekehrter Suchrichtung

StrRight

Sucht einen Teilstring und gibt den Teil rechts davon aus

StrRightBack

wie StrRight mit umgekehrter Suchrichtung

24.4.9 Schleifen Befehl

Beschreibung

For

For Schleife

ForAll

ForAll Schleife für den Einsatz bei Arrays und Listen

GoSub

Sprunganweisung mit Rückkehrmöglichkeit

GoTo

Sprunganweisung

If...GoTo

Bedingter Sprung

If...Then Else

Bedingte Verzweigung

On Error

Sprung bei Fehler

Select Case

Auswahlverzweigung

394

Die Befehls-Referenz

24.4.10 Rundung Befehl

Beschreibung

Int

Rundet auf Ganzzahl ab

Fix

Schneidet Nachkommastellen ab

Fraction

Liefert Nachkommastellen

Round

Rundet mathematisch

24.4.11 Datumsfunktionen II Befehl

Beschreibung

Now

Aktuelles Datum und Zeit

Date

Aktuelles Datum

DateNumber

Liefert das Datum das dem angegebenen Tag, Monat und Jahr entspricht.

DateValue

Wandelt die übergebene Zeichenkette in einen Datumswert um.

24.4.12 Array Befehl

Beschreibung

LBound

Liefert untere Indexgrenze eines Arrays

UBound

Liefert obere Indexgrenze eines Arrays

ArrayAppend

Zusammenfügen zweier Arrays

ArrayGetIndex

Index eines Arrayeintrags ermitteln

ArrayReplace

Durchsuchen und Ersetzen in einem Array

24.4.13 Threadhandling und Locking Befehl

Beschreibung

CodeLock

Sperrt ein Lockobjekt

CodeLockCheck

Überprüft die Sperrung eines Lockobjektes

CodeUnlock

Hebt die Sperrung eines Lockobjektes auf

DestroyLock

Löscht ein Lockobjekt

CreateLock

Erzeugt ein Lockobjekt

GetThreadInfo

Liefert Informationen über aktuellen Thread

Befehlsgruppen

395

24.4.14 Dateien Befehl

Beschreibung

CurDir

Aktuelles Verzeichnis eines Laufwerks

CurDrive

Aktuelles Laufwerk

MkDir

Legt ein Verzeichnis an

Kill

Löscht eine Datei

RmDir

Entfernt ein Verzeichnis

FileAttr

Gibt den Zugriffsmodus oder den Betriebssystem-Filehandle zu einer geöffneten Datei zurück

FileCopy

Kopiert eine Datei

FileDateTime

Liefert das Datum des letzten Schreibzugriffs

FileLen

Liefert die Dateigröße

GetFileAttr

Liefert die Attribute der Datei

ChDrive(ChDir)

Ändert das aktuelle Laufwerk (Verzeichnis)

24.4.15 Standardtypen-Deklaration Befehl

Beschreibung

DefSng

Definiert für eine Gruppe von Variablen den Standarddatentyp Single

DefInt

Definiert für eine Gruppe von Variablen den Standarddatentyp Integer

DefLng

Definiert für eine Gruppe von Variablen den Standarddatentyp Long

DefDbl

Definiert für eine Gruppe von Variablen den Standarddatentyp Double

DefCur

Definiert für eine Gruppe von Variablen den Standarddatentyp Currency

DefStr

Definiert für eine Gruppe von Variablen den Standarddatentyp String

DefVar

Definiert für eine Gruppe von Variablen den Standarddatentyp Variant

24.4.16 Operatoren Befehl

Beschreibung

Not

Logische oder binäre Not-Operation

Or

Logische oder binäre Oder-Operation

And

Logische oder binäre And-Operation

Xor

Logische oder binäre Exklusiv-Oder-Operation

Mod

Liefert Divisionsrest

Like

Vergleicht Zeichenkette mit einem Suchmuster

396

Die Befehls-Referenz

24.5 Die Befehle 24.5.1 Abs Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Die Funktion liefert den Absolutbetrag des übergebenen numerischen Ausdrucks. Syntax Abs ( value# ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value#

Double

+

-

-

Der Ausdruck, dessen Absolutbetrag ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

value#

Der Absolutwert von value#

Double

Numerisch

NULL

NULL

NULL

Beispiel Print Print Print Print Print

Abs(-3) Abs(3) Abs(0) Abs("-3") Abs(Null)

'liefert 'liefert 'liefert 'liefert 'liefert

3 3 0 3 NULL und den Datentyp Variant

Siehe auch Sgn

24.5.2 Acos Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

alle

4/5

Die Befehle

397

Beschreibung Liefert den Arkuskosinus eines numerischen Ausdrucks. Syntax Acos ( value# ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value#

Integer

+

-

-

Der Ausdruck, dessen Arkuskosinus ermittelt werden soll. Im Wertebereich –1 bis 1.

Rückgabewert Rückgabewert

Rückgabetyp

value#

Arkuskosinus von value#. Der Rückgabewert liegt im Bereich von 0 bis Pi.

Double

Numerisch und im Wertebereich

Fehler Nr.

Bezeichnung

Situation

5

Illegal Function Call

value# liegt außerhalb von –1 bis 1

Beispiel Print Print Print Print

ACos(1) ACos(0) ACos(-1) ACos(2)

'liefert 'liefert 'liefert 'erzeugt

0 ½ Pi Pi einen Fehler: Illegal Function Call

Siehe auch Sin, Tan, Asin, Acos, Atn, Atn2

24.5.3 ActivateApp Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Windowssystem

Windows

4/5

Beschreibung Die Anweisung gibt dem angegebenen Fenster den Eingabefokus.

398

Die Befehls-Referenz

Syntax ActivateApp windowName$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

windowName$

String

-

-

-

Der Name des Fensters, das den Eingabefokus bekommen soll.

Beschreibung Bei dem Parameter windowName$ wird die Groß-/Kleinschreibung nicht berücksichtigt. Der angegebene Name muss dem Anfang des Fenstertitels entsprechen. Wenn mehr als ein Fenstertitel dem angegebenen Fensternamen entspricht, wird eins der Fenster ausgewählt. Die Anweisung kann ein minimiertes Fenster aktivieren, dieses aber nicht wiederherstellen oder maximieren. Fehler Nr.

Bezeichnung

Situation

5

Illegal Function Call

Ein Fenster mit dem angegebenen Namen existiert nicht.

Beispiel Würde ein bereits geöffnetes leeres Fenster des Notepads aktivieren. ActivateApp ("Unbenannt - Editor")

Siehe auch SendKey

24.5.4 And Art

Kategorie

Betriebssysteme

Notesversionen

Operator

Logisch

Alle

V2 / V3

Beschreibung Ist die Logische/Binäre And-Operation Syntax value1# And value2#

Die Befehle

399

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value1#

Long

-

-

-

Erster Ausdruck für die And-Verknüpfung

value2#

Long

-

-

-

Zweiter Ausdruck für die And-Verknüpfung

Rückgabewert Rückgabewert

Rückgabetyp

value1#

value2#

TRUE

Long

TRUE

TRUE

FALSE

Long

TRUE

FALSE

FALSE

Long

FALSE

TRUE

FALSE

Long

FALSE

FALSE

Binäre And-Verknüpfung von value1# und value2#

Long

Numerisch

Numerisch

Beispiel Print True And True Print &b10011111 And &b01101111

'Logisches And: liefert True 'Binäres And: liefert %1111

Siehe auch Or

24.5.5 ArrayAppend Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Array

Alle

5

Beschreibung Gibt den aus dem Zusammenfügen zweier eindimensionaler Arrays entstehenden neuen Array zurück. Syntax ArrayAppend ( array1, array2 )

400

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

array1

Variant

-

-

-

Ein Variant-Ausdruck, der einen Array beinhaltet

array2

Variant

-

-

-

Ein beliebiger Variant-Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Der Rückgabewert ist ein Array als Variant-Datentyp. Dieser beinhaltet den neuen zusammengefügten Array.

Array

Beschreibung Die Inhalte von array1 und array2 werden nicht verändert. Wenn die Elemente der beiden Arrays array1 und array2 den gleichen Datentyp haben, so hat der Rückgabewert ebenfalls diesen Datentyp. Wenn die Elemente von array1 und array2 unterschiedliche Datentypen haben, so hat das zurückgegebene Array den Datentyp Variant. Und ein Element vom zurückgegebenen Array hat dann denselben Datentyp wie die Elemente von array1 bzw. von array2. Die untere Arraygrenze des zurückgegebenen Arrays ist gleich der unteren Arraygrenze von array1. Fehler Fehlernr.

Fehlerbeschreibung

Situation

9

Subscription out of range

Die Grenzen des zurückgegebenen Arrays sind nicht zulässig.

13

Type Mismatch

Es wurden Arrays mit mehr als einer Dimension verwendet.

Beispiel Dim A(2) As Integer Dim B(2) As Integer A(0) = 1 A(1) = 2 A(2) = 3 B(0) = 4 B(1) = 5 B(2) = 6 C = ArrayAppend(A, B) For Index = 0 To 5 Print C(Index) Next Index

'Gibt 1 bis 6 aus

Die Befehle

401

Siehe auch ArrayGetIndex

24.5.6 ArrayGetIndex Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Array

Alle

5

Beschreibung Durchsucht einen Array nach dem ersten Element mit dem angegebenen Inhalt und gibt dessen Index zurück. Syntax ArrayGetIndex ( array , value [, optCompare% ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

array

Array

-

-

-

Ein Array oder ein Variant-Datentyp, welcher einen Array beinhaltet.

value

Variant

-

-

-

Der Wert, der in dem Array gesucht werden soll.

optCompare%

Integer

-

-

-

Ein Flag, welcher das Vergleichsverfahren bei der Suche bestimmt.

Rückgabewert Rückgabewert

Rückgabetyp

Situation

Der Index des gesuchten Wertes im Array

Variant / Long

Der Wert wurde in dem Array gefunden

NULL

NULL

Der Wert wurde in dem Array nicht gefunden

Bemerkung Es wird vor dem Vergleich der Inhalt des jeweiligen Datenelements in eine Zeichenkette umgewandelt. Durch den Flag kann bestimmt werden, ob beim Vergleich Case Sensitive oder Pitch Sensitive eine Rolle spielt. Wenn der Flag nicht angegeben wird, wird die Einstellung mit der Option Compare-Anweisung berücksichtigt. Elemente des Arrays, welche nicht in eine Zeichenkette umgewandelt werden können, werden nicht verglichen. Der Wert von optCompare% entspricht dem Wert, welcher bei instr definiert ist.

402

Die Befehls-Referenz

Beispiel Dim A(2) As Integer A(0) = 1 A(1) = 2 A(2) = 3 Print ArrayGetIndex(A, 2)

'Liefert den Index 1

Siehe auch ArrayAppend, ArrayReplace

24.5.7 ArrayReplace Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Array

Alle

5

Beschreibung Kopiert Elemente eines Arrays in einen anderen Syntax ArrayReplace array1, array2, array3 Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

array1

Array

-

-

-

Eine Variantvariable mit einem Array

array2

Array

-

-

-

Eine Variantvariable mit einem Array (welcher die Dimension 1 hat)

array3

Array

-

-

-

Eine Variantvariable mit einem Array (welcher die Dimension 1 hat)

Rückgabewert Rückgabewert

Rückgabetyp

Kopierter Array

Array

Bemerkung Bei Aufruf von ArrayReplace wird array1 kopiert und dabei der Array array2 durchsucht. Wenn ein Element in array2 gleich einem Element von array1 ist, wird anstelle des Wertes aus array1 der Index des ersten Vorkommens des Wertes in array2 ermittelt und aus array3 das Element an der entsprechenden Stelle kopiert.

Die Befehle

403

Wenn der Index des Elementes in array2 außerhalb des Indexbereichs von array3 liegt, wird ein leerer Wert kopiert, also entweder 0 oder ein Leerstring. Der zurückgegebene Array hat dieselbe Größe wie der Array in array1. Der Index aus array2 für die Positionsbestimmung in array3 wird relativ zur unteren Indexgrenze der jeweiligen Arrays berrechnet. Wenn die Elemente der beiden Arrays array1 und array3 denselben Datentyp haben, so haben die Elemente des zurückgegebenen Arrays ebenfalls diesen Datentyp, ansonsten den Datentyp Variant. Die Datentypen von array1 und array2 müssen gleich sein, es wird keine Umwandlung vorgenommen. Beispiel Dim A(2) As Integer Dim B(2) As Integer Dim C(2) As Integer A(0)=1 A(1)=2 A(2)=3 B(0)=4 B(1)=3 B(2)=5 C(0)=9 C(1)=8 C(2)=7 D = ArrayReplace(A, B, C) For Index = 0 To 2 Print D(Index) Next Index

'Liefert die Folge 1,2,8

Siehe auch ArrayGetIndex, ArrayAppend

24.5.8 Asc Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichenkette

Alle

4/5

Beschreibung Liefert den plattformspezifischen Zeichencode Syntax Asc ( char$ )

404

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

char$

String

-

-

-

Eine beliebige Zeichenkette mit mindestens einem Zeichen

Rückgabewert Rückgabewert

Rückgabetyp

char$

ASCII-Code des ersten Zeichens

Long

<> ""

Fehler

Fehler

""

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

char$ ist Leerstring ""

Beispiel Print Asc("A") Print Asc("") Print Asc("0")

'liefert 65 'liefert einen Fehler 'liefert 48

Siehe auch Chr, Uni

24.5.9 ASin Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den Arkussinus des numerischen Ausdrucks. Syntax Asin ( value! ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value!

Single

+

-

-

Der Ausdruck, dessen Arkussinus ermittelt werden soll. Der Wert darf maximal 1 und minimal –1 betragen.

Die Befehle

405

Rückgabewert Rückgabewert

Rückgabetyp

value!

Arkussinus vom übergebenen Ausdruck. Liegt im Bereich von -Pi/2 bis Pi/2.

Double

Numerisch und im Wertebereich

Fehler

Nicht im Wertebereich

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

value! liegt außerhalb von –1 bis 1

Beispiel Print Print Print Print

Asin(-1) Asin(0) Asin(1) Asin(2)

'liefert 'liefert 'liefert 'liefert

- Pi / 2 0 Pi / 2 einen Fehler

Siehe auch Sin, Cos, Tan, ACos, Atn, Atn2

24.5.10 ATn Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den Arkustangens des numerischen Ausdrucks. Syntax Atn ( value& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Double

-

-

-

Der Wert, dessen Arkustangens berechnet werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Der Arkustangens von value&. Der Rückgabewert liegt zwischen -Pi/2 und Pi/2.

Double

406

Die Befehls-Referenz

Beispiel Print Atn(0) Print Atn(-1000) Print Atn(1000)

'liefert 0 'liefert ungefäht -1,569 'liefert ungefähr 1,569

Siehe auch ACos, Tan, ATn2, Cos, Sin, ASin

24.5.11 ATn2 Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert die Polar-Koordinaten Syntax ATn2 ( xValue&, yValue& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

xValue&

Double

-

-

-

Die X-Koordinate eines Punktes in der kartesischen Ebene.

yValue&

Double

-

-

-

Die Y-Koordinate eines Punktes in der kartesischen Ebene.

Bemerkung Mindestens einer dieser Ausdrücke muss einen von 0 ungleichen Wert haben. Rückgabewert Rückgabewert

Rückgabetyp

xvalue&

yvalue&

yValue& / xValue& (Winkel der Polarkoordinaten)

Double

Numerisch und <> 0

Numerisch

Pi/2

Double

0

Numerisch und > 0

-Pi/2

Double

Fehler

0

Numerisch und < 0

0

0

Die Befehle

407

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

xValue& = 0 und yValu&e = 0

6

Overflow

Eine oder beide Parameter liegen außerhalb des zulässigen Wertebereichs

Beispiel Print Print Print Print

Atn2(0, Atn2(0, Atn2(2, Atn2(0,

5) -4) 1) 0)

'liefert 'liefert 'liefert 'liefert

Pi / 2 –Pi / 2 ½ einen Illegal Function Call-Fehler

Siehe auch ACos, Tan, ATn, Cos, Sin, ASin

24.5.12 Beep Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Sonstige

Alle

4/5

Beschreibung Tonerzeugung Syntax Beep Parameter keine Beschreibung Erzeugt einen Ton am Lautsprecher des Computers Beispiel Beep Beep Beep

Erzeugt drei Töne hintereinander Siehe auch MessageBox

408

Die Befehls-Referenz

24.5.13 Bin Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Liefert den Binärcode eines numerischen Ausdrucks als Zeichenkette. Syntax Bin[$] ( value# ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value#

Long

-

-

-

Ein numerischer Ausdruck, von dem eine Binärdarstellung ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Binärcode des übergebenen Wertes als Zeichenkette. Nachkommastellen des übergebenen Ausdrucks werden vorher gerundet. Die maximale Länge der zurückgegebenen Zeichenkette beträgt 32 Stellen.

String Variant

Beispiel Messagebox(Bin$(255)) Messagebox(Bin$(2.1))

'liefert "11111111" 'liefert "10"

Siehe auch Hex, Oct

24.5.14 Call Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Mathe

Alle

4/5

Beschreibung Ruft eine LotusScript-Prozedur oder Funktion auf.

Die Befehle

409

Syntax 1. Call subOrFunction [ ( [ argList ] ) ] 2. subOrFunction [ argList ] 3. subOrFunction ( argPassedByVal ) 4. returnVal = function [ ( [ argList ] ) ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

subOrFunction

-

-

-

Der Name der Funktion oder der Prozedur, welche aufgerufen werden soll

argList

-

-

-

Die Liste von Argumenten durch Kommas getrennt, welche der Prozedur oder Funktion übergeben werden soll

agPassedByVal

-

-

-

Ein einzelnes Argument, welches als Wert an die Prozedur oder Funktion übergeben werden soll

function

-

-

-

Der Name der Funktion, welche aufgerufen werden soll

returnVal

-

-

-

Eine Variable zur Aufnahme des Rückgabewertes der Funktion

Bemerkung Wenn das Schlüsselwort Call verwendet wird, müssen die Parameter in einem Paar von runden Klammern eingeschlossen sein. Sollten keine Parameter übergeben werden, kann ein leeres Paar von runden Klammern folgen. Wenn das Schlüsselwort Call nicht verwendet wird, müssen folgende Regeln beachtet werden:

X X

X X

Bei einer Funktion oder Prozedur wird keine Klammer verwendet, es sei denn ein einzelnes Argument soll als Wert übergeben werden. Für einen Aufruf einer Funktion innerhalb eines Ausdrucks werden die Parameter in Klammern gesetzt. Bei Lotus-internen Funktionen wird der Rückgabewert immer verwendet und diese Funktionen können nicht mit der Call-Anweisung aufgerufen werden. Funktionen, die mit der Call-Anweisung aufgerufen werden, liefern keinen Rückgabewert zurück.

Prozeduren können keine Werte zurückliefern. Wenn eine Funktion einen Array, eine Liste oder eine Kollektion zurückgibt, kann eine Referenz zu dieser Funktion einen Index für den Rückgabewert beinhalten, der folgende Regeln einhält:

410

X

X X

Die Befehls-Referenz

Wenn die Funktion Parameter besitzt, muss die erste Liste, die in Klammern dem Funktionsnamen folgt, die Liste mit den Prozedur-Parametern sein. Die zweite Liste in Klammern ist dann die Indexliste. Ein Beispiel wäre f1(1,2)(3,4), welches die Funktion f1 mit den Parametern(1,2) aufruft und bei der Rückgabe das Element an der Stelle 3,4 aus dem Array herausliest. Wenn die Funktion keine Parameter besitzt, muss die erste Liste in Klammern leer sein. In der zweiten Klammer können dann die Indizes folgen. Die erste (leere) Liste muss vorhanden sein. Wenn die Funktion keine Parameter besitzt und auch keinen Container zurückgibt, erzeugt eine Liste hinter dem Funktionsnamen einen Fehler. Die Ausnahme davon ist nur eine einzelne Liste bestehend aus einem Paar Klammern ohne Inhalt.

Beispiel Call TestFunction(1,2)

Ruft eine Funktion namens TestFunction mit den Parameterwerten 1 und 2 auf. Siehe auch Function, Sub

24.5.15 CCur Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Wandelt einen Ausdruck in den Datentyp Currency. Syntax CCur ( value@ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value@

Currency

-

-

-

Ein beliebiger numerischer Ausdruck, welcher in einen Wert vom Typ Currency gewandelt werden soll.

Die Befehle

411

Rückgabewert Rückgabewert

Rückgabetyp

value@

Der Wert von value@

Currency

Numerischer Wert

0

Currency

EMPTY

Beispiel Dim B As Variant Dim C As Variant A% = 100 B = CCur(A%) C = A% Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert CURRENCY 'Liefert INTEGER

Siehe auch CCur, CDat, CDbl, CInt, CLng, CStr, CVar, Round

24.5.16 CDat Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Konvertiert einen numerischen Wert oder eine Zeichenkette in einen Datumswert. Syntax CDat ( datetime ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

datetime

String / Datum

-

-

-

Ein numerischer Ausdruck oder eine Zeichenkette, welche in einen numerischen Ausdruck umgewandelt werden kann, oder eine Zeichenkette, die in einen Datumswert umgewandelt werden kann.

412

Die Befehls-Referenz

Rückgabewert Rückgabewert

Rückgabetyp

datetime

Der Wert von datetime als Datum

Variant

Kann als Datum interpretiert werden

00:00:00

Variant

EMPTY

Fehler Fehlernr.

Fehlerbeschreibung

Situation

6

Overflow-Fehler

datetime liegt außerhalb des Wertebereichs eines DateDatentyps (von –657434 und 2958465)

9

Type Mismatch

datetime kann nicht in ein Datum umgewandelt werden

Beispiel Dim B As Variant Dim C As Variant A% = 100 B = CDat(A%) C = A% Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert DATE 'Liefert INTEGER

Siehe auch CVDate

24.5.17 CDbl CdblArt

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Wandelt einen Ausdruck in einen Datentyp Double. Syntax CDbl ( value& )

Die Befehle

413

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Double

-

-

-

Ein beliebiger numerischer Ausdruck, welcher in einen Wert vom Typ Double gewandelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

value&

Den Wert von value&

Double

sonst

0

Double

EMPTY

Beispiel Dim B As Variant Dim C As Variant A% = 100 B = CDbl(A%) C = A% Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert DOUBLE 'Liefert INTEGER

Siehe auch CCur, CDat, CDbl, CInt, CLng, CStr, CVar, Round

24.5.18 ChDir Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle*

4/5

Beschreibung Setzt das aktuelle Verzeichnis. Syntax ChDir path$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Path$

String

-

-

-

Eine Zeichenkette, welche ein existierendes Verzeichnis repräsentiert.

414

Die Befehls-Referenz

Beschreibung Die Anweisung setzt das übergebene Verzeichnis als aktuelles Verzeichnis. Wenn kein Laufwerksbuchstabe angegeben wird, wird das Verzeichnis des aktuellen Laufwerks gesetzt. Das Format und die maximale Länge der übergebenen Zeichenkette hängen von den plattformspezifischen Grenzen ab. Fehler Fehlernr.

Fehlerbeschreibung

Situation

76

Path Not Found

path$ existiert nicht als Pfad

Beispiel Chdir("C:\")

'Wechselt in das Root-Verzeichnis von C:

Siehe auch ChDrive

24.5.19 ChDrive Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle*

4/5

Beschreibung Setzt das aktuelle Laufwerk. Syntax ChDrive drive$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

drive$

String

-

-

-

Ein Ausdruck, welcher ein existierendes Laufwerk repräsentiert.

Beschreibung Die Anweisung ChDrive setzt das aktuelle Laufwerk _drive$ entsprechend. Wenn der Leerstring angegeben wird, wird das aktuelle Laufwerk nicht gewechselt. Es wird nur das erste Zeichen des übergebenen Ausdrucks verwendet. Das angegebene Laufwerk muss in dem Bereich von A bis zum LASTDRIVE-Eintrag in der Config.Sys liegen. Sollte ein anderes Betriebssystem als Windows verwendet werden, so muss drive$ leer sein. Der Befehl kann dann aus Kompatibilitätsgründen verwendet werden, ohne dass er eine Wirkung hat.

Die Befehle

415

Fehler Fehlernr.

Fehlerbeschreibung

Situation

Device unavailable

drive$ existiert nicht oder es kann nicht darauf zugegriffen werden.

Beispiel Chdrive("D:\")

'Wechselt, falls vorhanden, auf das Laufwerk D:

Siehe auch ChDir

24.5.20 Chr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichenkette

Alle

4/5

Beschreibung Liefert ein plattformabhängiges Zeichen. Syntax Chr[$] ( code& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

code&

Integer

-

-

-

Der numerische Ausdruck, welcher das Zeichen bestimmt.

Rückgabewert Rückgabewert

Rückgabetyp

code&

Plattformabhängiges ASCII-Zeichen

Long

Zwischen 0 und 255

Fehler

außerhalb von 0 und 255

Fehlermeldung Nummer

Bezeichnung

Situation

5

Illegal Function Call

code& liegt außerhalb von 0 bis 255

Beispiel Print Chr$(65)

'Liefert ein "A"

416

Die Befehls-Referenz

Siehe auch String, UChr, Uni, Asc

24.5.21 CInt Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Umwandlung in den Datentyp Integer. Syntax CInt ( value% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value%

Integer

-

-

-

Ein numerischer Ausdruck, welcher in einen Wert vom Typ Integer gewandelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Der numerische Wert von value%

Integer

Beispiel Dim B As Variant Dim C As Variant A# = 100 B = CInt(A#) C = A# Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert INTEGER 'Liefert DOUBLE

Siehe auch CCur, CDat, CDbl, CLng, CSng, CStr, CVar, Round

24.5.22 Class Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Deklaration

Alle

4/5

Die Befehle

417

Beschreibung Definiert eine Klasse und legt ihre Eigenschaften und Methoden fest. Syntax [ Public | Private ] Class className [ As baseClass ] classBody End Class Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Public

Konstant

-

Ja

Private

Deklariert die Klasse als Public

Private

Konstant

-

Ja

Private

Deklariert die Klasse als Private

className

-

-

-

Der Name der Klasse

baseClass

-

Ja

-

Der Name der Vaterklasse

classBody

-

-

-

Deklaration und Definition der Klassen Eigenschaften und Methoden

Bemerkung Das Schlüsselwort Public kann nicht in einem Include File verwendet werden. Regeln bei der Klassendefinition:

X X X

Definieren einer Klasse ist nur in der Modulumgebung möglich. Es ist keine Klassendefinition in Prozeduren oder innerhalb anderer Klassendefinitionen erlaubt. Das Schlüsselwort Object darf nicht als Klassenname verwendet werden.

Regeln bei der Deklaration von Eigenschaften:

X X X X X

Schlüsselwörter wie Dim sind bei der Deklaration von Eigenschaftsvariablen zu vermeiden. Es wird eine separate Deklaration für jede Eigenschaft benötigt. Es ist nicht möglich, mehrere Eigenschaften in einer Deklaration zu definieren. Man kann die Schlüsselwörter Public und Private für die Deklaration der Eigenschaften verwenden. Eine Eigenschaftsvariable ist standardmäßig Private. Die Eigenschaftsvariablen können nicht als statisch definiert werden. Eine Klasse kann eine Instanz von sich selbst beinhalten, aber die Variablendeklaration darf nicht das Schlüsselwort new beinhalten. Das heißt, die Deklaration darf kein Objekt der Klasse anlegen.

418

X

Die Befehls-Referenz

Folgende Schlüsselwörter dürfen als Variablennamen nicht verwendet werden: Public, Private, Static, Sub, Function, Property, Get, Set, New, Delete und Rem.

Regeln für die Deklaration von Methoden:

X X X

Es können die Schlüsselwörter Public oder Private für Methodendeklaration verwendet werden. Eine Methode ist standardmäßig Public. Methoden können nicht als statisch definiert werden. Alle Schlüsselwörter sind gültige Methodennamen. Der Name New sollte nur für Konstruktoren und der Name Delete nur für Destruktoren verwendet werden.

Beispiel Class Cpoint X As Integer Y AS Integer Sub Paint() Plot(X, Y) End Sub End Class

'Definiert eine Klasse CPoint 'mit den Eigenschaften X, Y 'und der Methode Paint 'bedient sich einer Methode "Plot"

Siehe auch Dim, Type

24.5.23 CLng Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Wandelt einen Ausdruck in den Datentyp Long um. Syntax CLng ( value# ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value#

Long

-

-

-

Ein numerischer Ausdruck, welcher in einen Wert vom Typ Long umgewandelt werden soll.

Die Befehle

419

Rückgabewert Rückgabewert

Rückgabetyp

Der Wert von value#

Long

Beispiel Dim B As Variant Dim C As Variant A# = 100 B = CLng(A#) C = A# Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert LONG 'Liefert DOUBLE

Siehe auch CCur, CDat, CDbl, CInt, CSng, CStr, CVar, Round

24.5.24 Close Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Schließt eine Datei oder alle Dateien. Syntax Close [ [ # ] fileNumber% [ , [ # ] fileNumber% ] ... ] Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

fileNumber%

Integer

Ja

-

Liste von Dateinummern der zu schließenden Dateien.

Beschreibung Aktion

filenum%

Die Datei mit der angegebenen fileNumber# wird geschlossen

Angegeben

Alle geöffneten Dateien werden geschlossen

Nicht angegeben

420

Die Befehls-Referenz

Beispiel Open "C:\AUTOEXEC.BAT" For Input As #1 Close #1

Öffnet und schließt die angegebene Datei. Siehe auch On Error , Open, Reset

24.5.25 CodeLock Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Thread

Alle

5

Beschreibung Setzt eine Sperre auf das angegebene Lockobjekt. Syntax CodeLock ( id% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

id%

Integer

-

-

-

ID des Lockobjektes, welches gesperrt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

TRUE

Integer

Das Sperren war erfolgreich

FALSE

Integer

Das Sperren war nicht erfolgreich

Beschreibung Reserviert das angegebene Lockobjekt. Wenn das Lockobjekt bereits von einem anderen Agenten reserviert ist, wartet der Thread, bis das Lockobjekt wieder freigegeben wurde. Die Anweisungen CodeLock und CodeUnlock sollten immer paarweise verwendet werden. Fehler Nummer

Bezeichnung

Situation

235

Lock ID has not been created

Das Lockobjekt wurde noch nicht mit dem Befehl CreateLock angelegt.

Die Befehle

421

Beispiel A = Createlock(100) B = Codelock(A) C = Codeunlock(A)

'Erstellt das Lock-Objekt 'Sperrt das Lock-Objekt 'Gibt das Lock-Objekt wieder frei

Siehe auch CreateLock, CodeUnLock

24.5.26 CodeLockCheck Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Thread

Alle

5

Beschreibung Liefert die Anzahl der Agenten, die auf das angegebene Lockobjekt warten, um 1 erhöht. Syntax CodeLockCheck ( id% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

id%

Integer

-

-

-

Die ID des Lockobjektes, welches überprüft werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Lockobjekt mit der ID ID%

0

Long

ist nicht gelockt

N

Long

n Agenten warten und einer hat gesperrt

Fehler Nummer

Bezeichnung

Situation

235

Lock ID has not been created

Das Lockobjekt wurde noch nicht mit dem Befehl CreateLock angelegt.

Beispiel A = CodeLockCheck(ID%)

Wenn A = 0 ist das Lock-Objekt nicht gesperrt. Wenn A = n und n > 0 hat 1 Threads das Objekt gesperrt und n-1 Threads warten.

422

Die Befehls-Referenz

Siehe auch CreateLock, CodeLock, CodeUnLock

24.5.27 CodeUnlock Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Thread

Alle

5

Beschreibung Gibt das Lockobjekt mit der angegebenen ID frei. Syntax CodeUnlock ( id% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

id%

Integer

-

-

-

Die ID des Lockobjektes, welches freigegeben werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Freigabe Lockobjekt

TRUE

Integer

Erfolgreich

FALSE

Integer

Nicht erfolgreich

Fehler Nummer

Bezeichnung

Situation

235

Lock ID has not been created

Das Lockobjekt wurde noch nicht mit dem Befehl CreateLock angelegt.

Beispiel A = Createlock(100) B = Codelock(A) C = Codeunlock(A)

Siehe auch CreateLock, CodeLock

'Erstellt das Lock-Objekt 'Sperrt das Lock-Objekt 'Gibt das Lock-Objekt wieder frei

Die Befehle

423

24.5.28 Const Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Mathe

Alle

4/5

Beschreibung Definiert eine Konstante. Syntax [ Public | Private ] Const constName = expr [ , constName = expr ]... Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Public

Konstant

-

Ja

Private

Definiert die Konstante als Public

Private

Konstant

-

Ja

Private

Definiert die Konstante als Private

constName

Referenz

-

-

-

Der Name der Konstanten

expr

Variant

-

-

-

Ein Ausdruck, welcher den gewünschten Wert der Konstante festlegt.

Als Ausdruck für die Konstante können numerische oder alphanumerische Literale, andere Konstanten, arithmetische oder logische Operatoren oder einige interne Funktionen verwendet werden. Funktionen, die bei der Konstantendefinition verwendet werden dürfen: Abs, ACos, ASin, ATn, ATn2, Bin, Cos, DataType, DateNumber, Exp, Fix, Fraction, Hex, InStr, InStrB, Int, LCase, Left, LeftB, Len, LenB, Log, LTrim, Mid, MidB, Oct, Right, RightB, Round, RTrim, Sgn, Sin, Sqr, Str, Tan, TimeNumber, Trim, TypeName, UCase, Val. Beschreibung Das Schlüsselwort Public kann innerhalb von Include Files verwendet werden. Eine Konstante ist eine Variable mit einem Wert, welcher nicht verändert werden kann. Eine Konstante kann innerhalb eines Moduls oder einer Prozedur, aber nicht innerhalb einer Typendefinition oder Klassendefinition verwendet werden. Der Datentyp der Konstanten kann durch ein Suffix hinter dem Konstantennamen festgelegt werden. Wenn kein Datentyp angegeben wird, wird er anhand des Wertes festgelegt. Für eine Fließkommazahl wird der Datentyp Double gewählt. Bei einem ganzzahligen Wert wird entweder Integer oder Long als Datentyp gewählt.

424

Die Befehls-Referenz

Beispiel Const XWert = 100

'Definiert XWert als Integer-Konstante 'mit dem Wert 100 'Definiert YWert als Double-Konstante 'mit dem Wert 1.5

Const YWert = 1.5

Const A = 2 Const B = 3 Const C = A * B

'Legt für die Konstante A den Wert 2 'und für die Konstante B den Wert 3 fest. 'Danach wird für C der Wert 6 festgelegt.

Siehe auch Dim

24.5.29 Command Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

System

Alle

4/5

Beschreibung Liefert die Kommandozeilenargumente, welche beim Programmstart der Lotusanwendung übergeben wurden. Syntax Command[$] Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

Kommandozeile vom Aufruf des Notes-Programmes ohne Programmname

Variant / String

Wenn Parameter bei dem Programmaufruf angegeben wurden

""

Variant / String

Sonst

Beispiel MsgBox Command$

Gibt die Parameter aus, welche beim Starten des Notesprogramms angegeben worden sind.

Die Befehle

425

Siehe auch Environ

24.5.30 Cos Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den Kosinus eines numerischen Ausdrucks. Syntax Cos ( value! ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value!

Single

-

-

-

Der Winkel, dessen Kosinus ermittelt werden soll, im Bogenmaß

Rückgabewert Rückgabewert

Rückgabetyp

value!

Kosinus von value!. Rückgabewert liegt innerhalb von –1 bis 1

Double

Im zulässigen Wertebereich

Beispiel Print Print Print Print

Cos(0) Cos(-Pi) Cos(Pi) Cos("A")

'liefert 'liefert 'liefert 'liefert

1 –1 –1 einen Type Mismatch-Fehler

Siehe auch ACos, Tan, ATn, ATn2, Sin, ASin

24.5.31 CreateLock Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Thread

Alle

5

426

Die Befehls-Referenz

Beschreibung Findet ein bereits angelegtes Lockobjekt mit dem angegebenen Namen oder legt dieses neu an. Syntax CreateUnlock ( name$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

name$

String

-

-

-

Bezeichner des Lockobjektes

Rückgabewert Rückgabewert

Rückgabetyp

name$

ID des Lockobjektes

Integer

Erstellen erfolgreich

Fehler

Erstellen nicht erfolgreich

Bemerkung Das Lockobjekt wird automatisch entfernt, wenn der Thread beendet wird oder DestroyLock mit der ID aufgerufen wird. Fehler Systembedingt Beispiel Print A = Createlock(100) Print B = Codelock(A) Print C = Codeunlock(A)

'Erstellt das Lock-Objekt 'Sperrt das Lock-Objekt 'Gibt das Lock-Objekt wieder frei

Siehe auch CodeLock, CodeUnLock

24.5.32 CreateObject Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

OLE

nicht unter OS/2, UNIX oder Mac

4/5

Beschreibung Erzeugt ein OLE-Objekt der spezifizierten Klasse

Die Befehle

427

Syntax CreateObject ( className$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

className$

String

-

-

-

Eine Zeichenkette der Form appName.appClass, welche das zu erzeugende Objekt festlegt.

appName

String

-

-

-

Der Name der Applikation, welche das Objekt erzeugen soll.

appClass

String

-

-

-

Der Name der zu erzeugenden OLEKlasse

Rückgabewert Rückgabewert

Rückgabetyp

Erzeugt OLE-Objekt

OBJECT

Erstellen erfolgreich

Fehler

Fehler

Erstellen nicht erfolgreich

Bemerkung Um die zurückgegebene Referenz des neu erzeugten Objektes einer Variable zuzuweisen, wird die Set-Anweisung verwendet. Wenn die Anwendung nicht bereits gestartet wurde, startet die Anweisung CreateObjekt diese. Die Referenz auf das OLE-Objekt hat nur solange Gültigkeit, wie die Anwendung läuft. Wenn während der Benutzung des Objektes die Anwendung beendet wird, erzeugt LotusScript einen Laufzeitfehler. Fehler Fehlernr.

Fehlerbeschreibung

Situation

208

Cannot create automation object

Das angegebene Objekt kann nicht erzeugt werden (z. B. ist die Klasse unbekannt)

Beispiel Set Temp = CreateObject("Excel.Sheet.8")

Siehe auch GetObject

'Erzeugt eine Excel-Tabelle

428

Die Befehls-Referenz

24.5.33 CSng Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Umwandlung nach Datentyp Single. Syntax CSng ( value! ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value!

Single

-

-

-

Ein numerischer Ausdruck, welcher in einen Wert vom Typ Single gewandelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Wert von value!

Single

Beispiel Dim B As Variant Dim C As Variant A# = 100 B = CSng(A#) C = A# Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert SINGLE 'Liefert DOUBLE

Siehe auch CCur, CDat, CDbl, CInt, CLng, CStr, CVar, Round

24.5.34 CStr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Umwandeln in Zeichenkette.

Die Befehle

429

Syntax CStr ( value$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value$

String

-

-

-

Ein Ausdruck, welcher in einer Zeichenkette gewandelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

value$

Wert von value$

String

Alphanumerisch

Das interpretierte Datum als Zeichenkette

String

Datum

""

String

EMPTY

Beispiel Dim B As Variant Dim C As Variant A# = 100 B = CSng(A#) C = A# Msgbox(Typename(B)) Msgbox(Typename(C))

'Liefert SINGLE 'Liefert DOUBLE

Siehe auch CCur, CDat, CDbl, CInt, CLng, CSng, CVar, Round

24.5.35 CurDir Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Gibt das aktuelle Verzeichnis zurück. Syntax CurDir[$] [ ( drive$ ) ]

430

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

drive$

String

-

+

akt. Laufw.

Eine Zeichenkette mit einem Laufwerksbuchstaben

Rückgabewert Rückgabewert

Rückgabetyp

drive$

Das aktuelle Verzeichnis des durch das erste Zeichen im Ausdruck angegebenen Laufwerks

String / Variant

Beliebiger alphanumerischer Ausdruck

Das aktuelle Verzeichnis des aktuellen Laufwerks

String / Variant

Kein Ausdruck

Fehler Fehlernr.

Fehlerbeschreibung

Situation

68

Device unavailable

drive$ existiert nicht

5

Illegal Function

drive$ beinhaltet nicht als erstes Zeichen einen Buchstaben

Beispiel Print CurDir("C")

'kann z. B. C:\DOS liefern.

Siehe auch ChrDir, ChDrive, CurDrive

24.5.36 CurDrive Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert das aktuelle Laufwerk zurück. Syntax CurDrive[$] Parameter Keine

Die Befehle

431

Rückgabewert Rückgabewert

Rückgabetyp

Liefert das aktuelle Laufwerk zurück.

String / Variant

Beispiel MsgBox CurDrive$ 'Liefert das aktuelle Laufwerk in 'einer Messagebox.

Siehe auch ChrDir, ChDrive, CurDrive

24.5.37 CVar Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Umwandlung in Variant. Syntax CVar ( value ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value

Variant

-

-

-

Ein Ausdruck, welcher in einen Variant-Datentyp gewandelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

value

Der übergebene Ausdruck als VariantDatentyp

Variant

beliebig ungleich NULL

Siehe auch CCur, CDat, CDbl, CInt, CLng, CSng, CStr, Round

432

Die Befehls-Referenz

24.5.38 CVdate Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Typen

Alle

4/5

Beschreibung siehe CDat

24.5.39 Date

Beschreibung Liefert das aktuelle Datum des Systems. Syntax Date[$] Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

Aktuelles Systemdatum

Variant / String

Beispiel Msgbox Date$

Gibt das aktuelle Datum aus Siehe auch Today

24.5.40 DateNumber Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Die Befehle

433

Beschreibung Liefert den seriellen Wert für die übergebenen Parameter für Tag, Monat und Jahr. Syntax DateNumber ( year# , month# , day# ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

year#

Long

-

-

-

Ein numerischer Ausdruck. Wenn die Jahreszahl zweistellig angegeben wird, werden Werte von 50 bis 99 als 1950 bis 1999 interpretiert. Alle anderen Werte von 0 bis 49 werden hingegen als 2000 bis 2049 ausgewertet. Bei einer negativen Zahl wird ein Illegal Function Call-Fehler erzeugt.

month#

Long

-

-

-

Ein numerischer Ausdruck für den Monat. Bei negativen Werten oder Werten über 12 wird der Wert für das Jahr entsprechend erhöht oder vermindert.

day#

Long

-

-

-

Ein numerischer Ausdruck für den Tag. Bei negativen Werten oder Werten über der Anzahl der Tage des jeweiligen Monats wird der entsprechede Monat erhöht oder vermindert.

Rückgabewert Rückgabewert

Rückgabetyp

year#

month#

day#

Serieller Datumswert für das Datum mit Jahr, Monat und Tag, wobei das Jahr als 1950 – 1999 gewertet wird

Variant DATE

Numerisch 50 - 99

Numerisch

Numerisch

Serieller Datumswert für das Datum mit Jahr, Monat und Tag, wobei das Jahr als 2000 – 2049 gewertet wird

Variant DATE

Numerisch 00 – 49

Numerisch

Numerisch

Serieller Datumswert für das Datum aus Jahr, Monat und Tag

Variant DATE

Numerisch > 99

Numerisch

Numerisch

434

Die Befehls-Referenz

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Jahreszahl ist nicht innerhalb 0-9999 oder ein übergebener Parameter hat keinen numerischen Ausdruck

6

Overflow

Einer der übergebenen Parameter ist nicht im Wertebereich des Datentyps Integer

Beispiel Print Print Print Print

DateNumber(1999, 12, 31) DateNumber(99, 12, 30) DateNumber(00, 1, 1) DateNumber(-1, 1, 1)

'liefert 'liefert 'liefert 'liefert 'Illegal 'liefert

Print DateNumber(99, -1, 1)

31.12.1999 30.12.1999 01.01.2000 den Laufzeitfehler: Function Call Call 01.11.1998

Siehe auch CDat, Date, DateValue, Day, Format, Month, TimeNumber, Today, Year

24.5.41 DateSerial Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung siehe DateNumber

24.5.42 DataType Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Typen

Alle

4/5

Beschreibung Liefert den Datentyp des übergebenen Ausdrucks. VarType ist ein Alias für DataTyp, der genauso gut verwendet werden kann. Syntax DataType ( expression )

Die Befehle

435

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Datentyp von expression

0 (V_EMPTY)

Integer

EMPTY

1 (V_NULL)

Integer

NULL

2 (V_Integer)

Integer

Integer

3 (V_Long)

Long

4 (V_Single)

Single

5 (V_Double)

Double

6 (V_Currency)

Currency

7 (V_DATE)

Date/Time

8 (V_String)

String

9 (V_DISPATCH)

OLE-Objekt oder Nothing

10 (V_ERROR)

OLE-Fehler

11 (V_Integer)

Integer

12 (V_Variant)

Variant, List oder Array

13 (V_UNKNOWN)

Unknown OLE

34 (V_LSOBJ)

Benutzerdefiniertes Objekt

35 (V_PRODOBJ)

Produkt-Objekt

2048

List

8192

statischer Array

8704

dynamischer Array

Beispiel Dim A As Integer Msgbox Datatype(A)

Gibt 2 für Integer aus

24.5.43 DateValue Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

436

Die Befehls-Referenz

Beschreibung Datumsumwandlung von Zeichenkette zu Datumswert. Syntax DateValue ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Ein Ausdruck, welcher als Datum interpretiert werden kann. Im Format (Tag-Monat-Jahr).

Rückgabewert Rückgabewert

Rückgabetyp

string$

Die übergebene Zeichenkette wird als Datum interpretiert und als Datumswert zurückgegeben

Variant DATE

Zeichenkette mit Datumswert

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

string$ kann nicht als Datum interpretiert werden.

Beispiel A = DateValue("1.1.2000")

Die Variable A enthält nach dieser Zuweisung den Datumswert für das Datum 1.1.2000 Siehe auch CDat, Date, DateNumber, Format, Time, TimeValue

24.5.44 Day Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert den Tagesanteil. Syntax Day ( datetime )

Die Befehle

437

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

datetime

Variant

+

-

-

Ein numerischer oder DatumsWert, dessen Tagesanteil ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

datetime

Der Tagesanteil des übergebenen Wertes

Variant

Datumswert

NULL

NULL

NULL

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Datum interpretieren oder liegt außerhalb von 1.1.100 bis 31.12.9999

Beispiel Print Day("1.1.1999") Print Day(NULL) Print Day("29.1.1999")

'liefert 1 'liefert NULL 'liefert 29

Siehe auch Hour, Minute, Month, Now, Second, Today, Weekday, Year

24.5.45 Declare (external C) C Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Deklaration

nicht unter OS/2

4/5

Beschreibung Deklariert eine LotusScript-Funktion oder -Prozedur als Zugriff auf eine externe C-Funktion in einer Shared Library. Syntax Declare [ Public | Private ] { Function | Sub } LSname Lib libName [ Alias aliasName ] ([ argList ]) [ As returnType ]

438

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Public

Konstant

-

Ja

Private

Deklariert als Public

Private

Konstant

Ja

Private

Deklariert als Private

Function

Konstant

-

-

-

Deklariert eine Funktion

Sub

Konstant

-

-

-

Deklariert eine Prozedur

LSname

-

-

Der Funktions- oder Prozedurenname, welcher im weiteren LotusScript-Programm verwendet wird. Wenn die Alias-Anweisung nicht angegeben wird, muss dieser Name mit dem Namen in der Bibliothek übereinstimmen. Wenn eine Funktion deklariert wird, kann ein Typensuffix dem Rückgabetyp entsprechend angehängt werden.

libName

-

-

Eine konstante Zeichenkette, die die Bibliothek bestimmt. Wobei die Angabe einer Dateierweiterung im Namen optional ist. Es kann ein kompletter Pfad angegeben werden. Dabei werden der Pfad und der Dateiname immer in Großbuchstaben konvertiert.

aliasName

-

Ja

-

Eine konstante Zeichenkette, die folgende Formate haben kann: Den Namen der Funktion oder Prozedur, wie er in der Bibliothek definiert ist, wobei Groß-/Kleinschreibung relevant ist. Oder ein Nummernzeichen (#) gefolgt von der Ordinalzahl, welche die Position der Funktion in der Bibliothek angibt. Dieser Parameter ist zu empfehlen, wenn der Funktionsname kein gültiger Name für eine Prozedur oder Funktion in LotusScript ist oder bei dem Namen die Groß/Kleinschreibung relevant ist.

Die Befehle

Bezeichnung argList

439

Datentyp

Null

Opt.

Default

Inhalt

-

Ja

-

Die Argumentenliste für die externe Funktion. Sollte die Funktion oder Prozedur keine Parameter besitzen, so sind mindestens die Klammern anzugeben. Wobei ein Eintrag für ein Argument in der Liste folgende Form hat: [ ByVal ] name As [ LMBCS | Unicode ] [ dataType | Any ] Die Schlüsselwörter LMBCS und Unicode, welche optional bei Parametern vom Datentyp String angegeben werden können, spezifizieren den Zeichensatz.

returnType

-

-

Der Datentyp des Rückgabewertes. Die Angabe eines Datentyps für den Rückgabewert ist bei einer Prozedur nicht erlaubt. Bei einer Funktion ist es auch möglich, den Datentyp des Rückgabewertes mit einem Typsuffix hinter dem Funktionsnamen zu definieren. Nicht verwendet werden kann der Datentyp Variant, Currency oder statische Zeichenketten.

Beispiel Declare Function MyProc Lib "MyLib.dll"(Param1 As String) As String 'Deklariert eine Funktion MyProc aus der Datei MyLib.dll 'als Funktion mit einem Parameter vom Typ String und einem 'Rückgabewert vom Typ String

Siehe auch Declare forward

24.5.46 Declare forward Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Deklaration

Alle

4/5

Beschreibung Erzeugt eine vorläufige Deklaration einer Prozedur oder Funktion.

440

Die Befehls-Referenz

Syntax Declare [ Static ] [ Public | Private ] procType procName [ ( [ argList ] ) ] [ As returnType ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Static

Konstant

-

Ja

-

Deklariert die Funktion oder Prozedur als Static

Public

Konstant

-

Ja

-

Deklariert die Funktion oder Prozedur als Public

Private

Konstant

-

Ja

-

Deklariert die Funktion oder Prozedur als Private

procType

Legt die Art der Funktion oder Prozedur fest. Kann eins der folgenden Schlüsselwörter sein: Function, Sub, Property, Get, Property Set

procName

Name der Prozedur oder Funktion

argList

Liste der Parameter

returnType

Bei einer Funktion bzw. bei einer Property Get-Eigenschaft der Rückgabedatentyp

Beschreibung Eine Forward-Deklaration wird eingesetzt, um auf eine Prozedur oder Funktion vor der eigentlichen Definition zuzugreifen.

24.5.47 DefCur Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttypen

Alle

4/5

Beschreibung Definiert Currency als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefCur range [ , range ] ...

Die Befehle

441

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Beschreibung Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Klasseneigenschaften. Die Def-Anweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefCur A-C

Alle Variablen mit den Anfangsbuchstaben A bis C werden standardmäßig als Currency-Variablen deklariert. Siehe auch Dim

24.5.48 DefDbl Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttyp

Alle

4/5

Beschreibung Definiert Double als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefDbl range [ , range ] ...

442

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Beschreibung Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Property-Klasseneigenschaften. Die DefAnweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefDbl A-C

Deklariert alle Variablen mit den Anfangsbuchstaben A bis C standardmäßig als Double-Variablen Siehe auch Dim

24.5.49 DefInt Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttyp

Alle

4/5

Beschreibung Definiert Integer als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefInt range [ , range ] ...

Die Befehle

443

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Beschreibung Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Klasseneigenschaften. Die Def-Anweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefInt A-C

Alle Variablen mit den Anfangsbuchstaben A bis C werden standardmäßig als Integer-Variablen deklariert. Siehe auch Dim

24.5.50 DefLng Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttyp

Alle

4/5

Beschreibung Definiert Long als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefLng range [ , range ] ...

444

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Aktion Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Klasseneigenschaften. Die Def-Anweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefLng A-C

Alle Variablen mit den Anfangsbuchstaben A bis C werden standardmäßig als Long-Variablen deklariert. Siehe auch Dim

24.5.51 DefSng Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttyp

Alle

4/5

Beschreibung Definiert Single als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefSng Bereich range [ , Bereich range ] ...

Die Befehle

445

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Beschreibung Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Klasseneigenschaften. Die Def-Anweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefSgn A-C

Alle Variablen mit den Anfangsbuchstaben A bis C werden standardmäßig als Single-Variablen deklariert. Siehe auch Dim

24.5.52 DefStr Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttyp

Alle

4/5

Beschreibung Definiert String als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefStr Bereich range [ , Bereich range ] ...

446

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Beschreibung Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Klasseneigenschaften. Die Def-Anweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefStr A-C

Alle Variablen mit den Anfangsbuchstaben A bis C werden standardmäßig als String-Variablen deklariert. Siehe auch Dim

24.5.53 DefVar Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Defaulttyp

Alle

4/5

Beschreibung Definiert Variant als Standarddatentyp von Variablen, deren Bezeichnung in dem angegebenen Bereich liegt. Syntax DefVar range [ ,range ] ...

Die Befehle

447

Parameter Bezeichnung

Datentyp

range

Null

Opt.

Default

Inhalt

-

-

-

Ein einzelner Anfangsbuchstabe oder ein Buchstabenbereich, abgegrenzt durch zwei Anfangsbuchstaben.

Beschreibung Die Anweisung kann nur auf Modulebene verwendet werden. Innerhalb der Programmumgebung werden alle Variablen mit den angegebenen Anfangsbuchstaben standardmäßig als Variant definiert. Diese Definition gilt nicht für Elemente von Klassen oder Strukturdefinitionen. Diese Anweisung wird aber berücksichtigt bei Parametern von Funktionen und bei Klasseneigenschaften. Die Def-Anweisung muss vor jeder anderen Variablendefinition stehen. Ausgenommen sind nur Konstanten. Wenn der Bereich von A-Z angegeben wird, erstreckt sich die Deklaration auf alle Zeichen, auch alle länderspezifischen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Duplicate range specifier

Die deklarierten Bereiche zweier Def-Anweisungen überschneiden sich

Beispiel DefVar A-C

Alle Variablen mit den Anfangsbuchstaben A bis C werden standardmäßig als Variant-Variablen deklariert. Siehe auch Dim

24.5.54 Delete Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Objekte

Alle

4/5

Beschreibung Führt den Destruktor der jeweiligen Klasse aus und gibt den Speicherbereich des Objektes frei. Syntax Delete objRef

448

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

objRef

Null

Opt.

Default

Inhalt

-

-

-

Eine Objektreferenz oder eine Variantvariable, die eine Objektreferenz beinhaltet.

Beschreibung Die Delete-Anweisung ruft den Destruktor des Objektes auf und setzt danach die Referenz des Objektes auf NOTHING. Wenn das Objekt auf einer Klasse mit einer Elternklasse basiert, wird zuerst der Destruktor der Elternklasse aufgerufen. Fehler Fehlernr.

Fehlerbeschreibung

Situation

193

Illegal Delete

Es wurde keine gültige Referenz übergeben.

Beispiel Set A = New UserObjekt Delete A

'Legt ein neues UserObjekt an 'und löscht es danach mit dem Aufruf 'des Destruktors.

Siehe auch New

24.5.55 DestroyLock Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Thread

Alle

5

Beschreibung Entfernt die Verknüpfung zu dem angegebenen Lockobjekt. Wenn keine Verknüpfung mehr zu dem Lockobjekt existiert, wird das Lockobjekt aus dem Speicher entfernt. Syntax DestroyLock ( id% )

Die Befehle

449

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

id%

Integer

-

-

-

ID, welche durch den Aufruf von CreateLock erzeugt wurde

Bemerkung Die DestroyLock-Anweisung dient der Freigabe des Speichers eines Lockobjektes. Rückgabewert Rückgabewert

Rückgabetyp

TRUE

Integer

Das Erzeugen des Lockobjektes war erfolgreich

FALSE

Integer

Das Erzeugen des Lockobjektes war nicht erfolgreich

Beispiel A = CreateLock("Locking") DestroyLock(A)

'Legt ein Lock-Object an 'und löscht dieses auch wieder

Siehe auch CodeLock, CodeUnLock, CreateLock

24.5.56 Dim Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Deklaration

Alle

4/5

Beschreibung Deklariert Variablen Syntax { Dim | Static | Public | Private } varDeclaration [ , varDeclaration ]... Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Dim

Konstant

-

+

-

Dim definiert die Variable als nicht Statisch und Private.

Static

Konstant

-

+

-

Deklariert die Variable als Statisch

Public

Konstant

-

+

-

Deklariert die Variable als Public

450

Die Befehls-Referenz

Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Private

Konstant

-

+

-

Deklariert die Variable als Private

-

-

-

Die Variablendeklaration:

varDeclaration

Einfache Variablen: variableName [ dtSuffix ] [ As type ] Objektreferenz Variable: variableName As [ New ] type [ argList ] List-Variable: variableName [ dtSuffix ] List [ As type ] Array-Variable: variableName [ dtSuffix ] ( [ bounds ] ) [ As type ]

variableName

-

-

-

Der Name der Variable

dtSuffix

-

+

-

Ein Typsuffix für die Variable

type

-

-

-

Der Datentyp der Variable

-

-

-

Wird bei Objekten verwendet, um den Konstruktor aufzurufen

-

-

-

Liste der Argumente für den Konstruktor

New

Konstant

argList

Beispiel Dim A As Integer Dim B& Dim C(10) As Integer

'Deklariert A als Integer-Variable 'Deklariert B als Long-Variable 'Deklariert C als Array mit 'Integer-Variablen

Siehe auch Const

24.5.57 Dir Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert einen Dateinamen, Verzeichnisnamen oder den Volumennamen, welcher durch den übergebenen Parameter spezifiziert wird. Syntax Dir[$] [ ( fileSpec$ [ , attribute% ] ) ]

Die Befehle

451

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileSpec$

String

-

+

-

Spezifiziert die Dateiauswahl für die Suche. Dieser Parameter muss nur bei dem ersten Aufruf der Funktion übergeben werden. Die Konvention der Wildcards entspricht der Konvention vom Betriebssystem.

attribute%

Integer

-

+

-

Definiert die Art der gesuchten Dateien, Verzeichnisse oder Volumes. Sollte der Parameter nicht angegeben werden, so werden normale Dateien gesucht. Dir$ liefert immer normale Dateien zurück.

Die Bitmaske für die Attribute Wert

Konstante

Attribut

0

Normal file

ATTR_NORMAL

2

Hidden file

ATTR_HIDDEN

4

System file

ATTR_SYSTEM

8

Volume label

ATTR_VOLUME. If this is specified, then the presence (or absence) of 2, 4, and 16 is irrelevant. The hidden, system, or directory attributes are not meaningful for a volume label.

16

Directory

ATTR_DIRECTORY

Rückgabewert Rückgabewert

Rückgabetyp

Die gefundene Datei

Variant / String

Datei vorhanden

""

Variant / String

Datei nicht vorhanden

Bemerkung Bei dem ersten Aufruf der Funktion muss die entsprechende Spezifikation angegeben werden. Dieser erste Aufruf liefert dann die erste Datei (das erste Verzeichnis / Volume) zurück, auf das die Spezifikation zutrifft. Weitere Aufrufe ohne Spezifikation liefern weitere Dateien (Verzeichnisse / Volumes). Wenn ein Aufruf einen Leerstring zurückgibt, dann wurde keine weitere Datei (Verzeichnis / Volume) gefunden. Der Aufruf mit Leerstring ist unzulässig und führt zu einem Fehler.

452

Die Befehls-Referenz

Beispiel MsgBox Dir$("C:\*.*")

'Liefert die erste Datei aus dem 'Root-Verzeichnis von Laufwerk C:

Siehe auch ChDir, ChDrive

24.5.58 Do Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Wiederholt die Ausführung eines Blocks von Anweisungen, solange eine gegebene Bedingung TRUE ist oder bis eine gegebene Bedingung TRUE wird. Syntax Variante 1: Do [ While | Until condition ] [ statements ] Loop Variante 2: Do [ statements ] Loop [ While | Until condition ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

condition

+

Ja

-

Ein numerischer Ausdruck, bei dem die 0 als FALSE und jeder andere Wert als TRUE interpretiert wird.

statements

-

-

-

Befehlsblock

Die Befehle

453

Beschreibung In der Variante 1 wird die Bedingung vor jedem Schleifendurchlauf geprüft. Bei der Variante 2 wird die Bedingung nach jedem Schleifendurchlauf geprüft. Bei der Verwendung des Schlüsselwortes WHILE wird der Anweisungsblock solange durchlaufen, wie die gegebene Bedingung TRUE ist. Durch die Verwendung des Schlüsselwortes UNTIL wird der Anweisungsblock durchlaufen, bis die Bedingung TRUE ist. Die Schleife kann jederzeit mit der EXIT DO- oder mit der GOTO-Anweisung verlassen werden. Bei EXIT DO wird die Programmausführung mit der Anweisung fortgesetzt, die der Schleife folgt. Bei der GOTO-Anweisung wird die Progammausführung an der angegebenen Programmstelle fortgesetzt. Bei fehlender Schleifenbedingung erfolgt die Wiederholung der Schleife endlos oft. Beispiel Wert = 1 Do Wert = Wert + 1 Print Wert Loop While Wert < 100

24.5.59 DoEvents siehe Yield

24.5.60 End Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Beendet die Ausführung des aktuellen Scripts. Syntax End [ returnCode% ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

returnCode%

Integer

-

Ja

-

Rückgabecode für das aufrufende Modul

454

Die Befehls-Referenz

Beispiel Sub myFunc Print "Hallo" End Print "Auf Wiedersehen" End Sub

Diese Prozedur gibt »Hallo« aus, wird vorzeitig verlassen und »verabschiedet« sich NICHT mehr. Siehe auch Exit

24.5.61 Environ Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Programmumgebung

Alle

4/5

Beschreibung Liefert Informationen über die Variablen der Systemumgebung. Syntax Environ[$] ( { environName$ | environNr% }) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

environ Name$

String

-

-

-

Der Name einer Umgebungsvariable.

environNr%

Integer

-

-

-

Wert zwischen 1 und 255, welcher die Position einer Umgebungsvariable angibt.

Rückgabewert Rückgabewert

Rückgabetyp

Der Wert der Umgebungsvariable

Variant/String

Durch environName$ wurde eine gültige Umgebungsvariable ausgewählt.

Der Wert und der Name der Umgebungsvariable

Variant/String

Durch environNr% wurde eine gültige Umgebungsvariable ausgewählt.

""

Variant/String

Durch environNr% wurde eine Position gewählt, die über der Anzahl der vorhandenen Umgebungsvariablen liegt.

Die Befehle

455

Rückgabewert

Rückgabetyp

Fehler

Variant/String

environNr% liegt außerhalb von 1 bis 255 oder ist EMPTY.

Fehler

Variant/String

environName$ ist EMPTY

""

Variant/String

Die in environName$ angegebene Variable existiert nicht.

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

environNr% liegt außerhalb von 1 und 255 oder ist EMPTY.

5

Illegal Function Call

environName$ ist EMPTY.

Beispiel Print Environ(1)

'Liefert den Inhalt von der ersten 'Umgebungsvariable 'Liefert den Inhalt von der 'Umgebungsvariable TMP

Print Environ("TMP")

Siehe auch Command$

24.5.62 Erase Art

Kategorie

Anweisung

Arrays/Liste

Betriebssysteme

Notesversionen

Beschreibung Löscht einen Array, eine Liste oder ein Listenelement. Syntax Erase { arrayName | listName | listName ( listtag ) } [,{ arrayName | listName | listName ( listtag ) } ]... Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

arrayName

Referenz

-

-

-

Referenz eines Arrays

listName

-

-

-

Referenz einer Liste

Listtag

-

-

-

Ein Listenelement

456

Die Befehls-Referenz

Beschreibung Die Funktion löscht entweder den angegebenen Array, die angegebene Liste oder das Listenelement. Das bedeutet bei einem statischen Array, dass die Elemente initialisiert werden, und bei einem dynamischen Array, dass der Speicher wieder freigegeben wird. Beispiel Dim A(1) As Integer A(0) = 1 A(1) = 2 Erase A Print A(0), A(1) Dim A List As Integer A("Alpha") = 100 A("Beta") = 200 A("Gamma") = 300 Erase A("Beta") ForAll x in A Print x End ForAll

'Löscht den Array A 'Liefert dann wieder 0, 0

'Liefert 100 und 300

Siehe auch Dim, ArrayAppend, ArrayReplace, ArrayGetIndex

24.5.63 Erl Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Fehlerbehandlung

Alle

4/5

Beschreibung Liefert die Zeilennummer im Quelltext, an welcher der letzte Fehler aufgetreten ist. Allerdings ist diese Nummer zur Zeit kaum mit einer Code-Zeile im LotusScript-Editor in Deckung zu bringen und daher für den normalen Notes-Entwickler praktisch unbrauchbar. Weitere Informationen dazu kann man mitunter in den Foren unter www.notes.net erfahren. Syntax Erl Parameter keine

Die Befehle

457

Rückgabewert Rückgabewert

Rückgabetyp

0

Long

Es ist kein Fehler aufgetreten

Zeilennummer des letzten Fehlers

Long

Es ist ein Fehler aufgetreten

Beispiel MsgBox Erl

Liefert die Zeilennummer des letzten Fehlers zurück Siehe auch Err

24.5.64 Err-Funktion Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Fehlerbehandlung

Alle

4/5

Beschreibung Liefert den letzten Fehlercode. Syntax Err Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

0

Long

Es ist kein Fehler aufgetreten

Fehlercode des letzten Fehlers

Long

Es ist ein Fehler aufgetreten

Beispiel Msgbox Err

Liefert den Fehlercode des letzten aufgetretenen Fehlers Siehe auch Erl

458

Die Befehls-Referenz

24.5.65 Err Statement Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Setzt den aktuellen Fehlercode Syntax Err = errNumber% Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

errNumber%

Integer

-

-

-

Der neue Fehlercode

Beschreibung Die Anweisung Err setzt den aktuellen Fehlercode. Der Fehlercode muss dabei in dem Bereich von 0 bis 32767 liegen. Siehe auch Erl

24.5.66 Error-Funktion Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Fehlerbehandlung

Alle

4/5

Beschreibung Liefert die Fehlermeldung eines Fehlercodes oder die aktuelle Fehlermeldung. Syntax Error[$] [ ( errNumber% ) ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

errNumber%

Integer

-

Ja

-

Fehlercode

Die Befehle

459

Rückgabewert Rückgabewert

Rückgabetyp

Fehlermeldung zum Fehlercode errNumber%

Variant/String

Es ist ein Fehlercode angegeben

Aktuelle Fehlermeldung

Variant/String

Es ist ein Fehler aufgetreten und es ist kein Fehlercode angegeben

""

Variant/String

Es ist kein Fehler aufgetreten und es ist kein Fehlercode angegeben

Beispiel Msgbox Error(13)

'Liefert Type Mismatch Error

Siehe auch Err, Erl

24.5.67 Error Statement Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Fehlerbehandlung

Alle

4/5

Beschreibung Erzeugt einen Fehler Syntax Error errNumber% [ , msgExpr$ ] Parameter Bezeichnung

Datentyp

Null

errNumber%

Integer

-

msgExpr$

String

-

Opt.

Default

Inhalt Fehlercode des gewünschten Fehlers

Ja

Zeichenkette mit der gewünschten Fehlermeldung

Beschreibung Gibt die Fehlermeldung, die dem angegebenen Fehlercode entspricht, oder die angegebene Fehlermeldung aus. Beispiel Error 32000, "Fehler"

'Gibt den Fehler 32000 mit der 'Meldung Fehler aus.

460

Die Befehls-Referenz

Siehe auch Error, Erl, Err

24.5.68 Eof Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert einen Integer-Ausdruck, welcher angibt, ob das Dateiende erreicht wurde. Syntax Eof ( fileNumber% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Die Dateinummer der geöffneten Datei.

Rückgabewert a) Bei einem Binaryfile: Rückgabewert

Rückgabetyp

TRUE

Integer

Die zuletzt ausgeführte Get-Anweisung konnte nicht alle geforderten Daten lesen.

FALSE

Integer

Die zuletzt ausgeführte Get-Anweisung konnte alle geforderten Daten lesen

b) Bei einem Randomfile: Rückgabewert

Rückgabetyp

TRUE

Integer

Die letzte Get-Anweisung konnte nicht einen kompletten Record lesen

FALSE

Integer

Die letzte Get-Anweisung konnte einen kompletten Record lesen

c) Bei einem Sequentialfile: Rückgabewert

Rückgabetyp

TRUE

Integer

Das Ende der Datei wurde erreicht

FALSE

Integer

Das Ende der Datei wurde nicht erreicht

Die Befehle

461

Fehler Fehlernr.

Fehlerbeschreibung

Situation

99

File not open

Es wurde auf eine geschlossene Datei zugegriffen

Beispiel Open "C:\Autoexec.bat" For Input As #1 Msgbox(Eof(1))

24.5.69 Exp Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Exponentialfunktion (zur Basis e). Syntax Exp ( expression! ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression!

Single

-

-

-

Numerischer Wert, welcher den Exponent für die Zahl e bildet. Der Wertebereich liegt zwischen 0 bis < 709,78.

Rückgabewert Rückgabewert

Rückgabetyp

expression!

Basis e potenziert mit dem übergebenen Ausdruck

Double

zwischen 0 und 709,78

Fehler

außerhalb von 0 und 709,78

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

expression! liegt nicht zwischen 0 und 709,78

462

Die Befehls-Referenz

Beispiel Print Exp(0) Print Exp(2) Print Exp(810)

'liefert 1 'liefert ungefähr 7,389 'liefert Overflow-Fehler

Siehe auch Log

24.5.70 Exit Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Beendet die Ausführung des aktuellen Programmblocks. Syntax Exit blockType Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

blockType

Konstant

-

-

-

Definiert, welche Schleife verlassen wird. Folgende Schlüsselwörter sind zulässig: Do, For, ForAll, Function, Sub, Property.

Bemerkung Diese Anweisung veranlasst LotusScript, die Programmausführung mit aufrufendem Programmsegment fortzusetzen. Sollte mit der Anweisung eine Funktion oder eine Property Get-Methode verlassen werden, so wird der Rückgabewert initialisiert und leer zurückgeliefert. Beispiel For Index = 1 To 10 Print Index If Index = 5 Then Exit For Next Index

Diese Schleife wird nur bis zum Wert 5 des Index ausgeführt. Siehe auch Exit

Die Befehle

463

24.5.71 Evaluate Art

Kategorie

Betriebssysteme

Notesversionen

Funktion Anweisung

Programmausführung

Alle

4/5

Beschreibung Führt ein Lotus-Produktmakro aus. Syntax Evaluate ( macroName$ [ , objectName ] ) Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

macroName$

String

-

-

Das Makro, das ausgeführt werden soll.

objectName

Referenz

Ja

-

Referenz auf ein ggf. benötigtes Objekt.

Rückgabewert Rückgabewert

Rückgabetyp

Rückgabewert des Makros

Variant

Kein Rückgabewert

Makro liefert einen Rückgabewert Makro liefert keinen Rückgabewert

Bemerkung Beispiel A = Evaluate("@Sum(1;2;3)") Msgbox A(0)

Liefert den Wert 6, da das Makro die Werte in der Klammer aufsummiert und als Variant zurückgibt. Siehe auch Shell, Execute

24.5.72 Execute Art

Kategorie

Betriebssysteme

Notesversionen

Funktion Anweisung

Programmausführung

Alle

4/5

464

Die Befehls-Referenz

Beschreibung Kompiliert und führt den angegebenen Prorammcode aus. Syntax Execute program$ Execute ( program$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

program$

String

-

-

-

Text, der compiliert und ausgeführt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Returncode der END-Anweisung

Integer

Programmcode liefert einen Rückgabewert

0

Integer

Programmcode liefert keinen Rückgabewert

Bemerkung Die Anweisung führt das übergebene Programmsegment aus. Etwaige Compilerfehler werden während der Programmausführung ausgegeben. Das Programmsegment verhält sich wie ein eigenständiges Modul. Es kann auf öffentlich deklarierte Variablen anderer geladener Module zugreifen. Beispiel Execute("Sub Initialize" + Chr$(10) + "Print 123" + _ Chr$(10) + "End Sub")

Führt das angegebene Programm aus und gibt 123 aus. Siehe auch Evaluate, Shell

24.5.73 FileAttr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert entweder den systemeigenen Dateihandle oder die Zugriffsart zurück.

Die Befehle

465

Syntax FileAttr ( fileNumber%, flag% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, mit welcher die zu behandelnde Datei geöffnet wurde.

flag%

Integer

-

-

-

1 oder ATTR_MODE 2 oder ATTR_HANDLE

Rückgabewert Rückgabewert

Rückgabetyp

flag%

Zugriffsmodus der Datei

1 (ATTR_INPUT)

1 oder ATTR_MODE

INPUT

2 (ATTR_OUTPUT)

1 oder ATTR_MODE

OUTPUT

4 (ATTR_RANDOM)

1 oder ATTR_MODE

RANDOM

8 (ATTR_APPEN)

1 oder ATTR_MODE

APPEND

32 (ATTR_BINARY)

1 oder ATTR_MODE

BINARY

Der BetriebssystemHandle der Datei

2 oder ATTR_HANDLE

-

Fehler Nummer

Bezeichnung

Situation

99

File not open

Datei ist nicht geöffnet

104

Bad attribute

Der Wert von flag% ist nicht 1 und nicht 2

Beispiel filenr% = Freefile Open "C:\AUTOEXEC.BAT" For Input As filenr% Msgbox Fileattr(filenr%, 1) Close filenr%

Diese Anweisungen liefern ATTR_INPUT bzw. den Wert 1 zurück Siehe auch Open

466

Die Befehls-Referenz

24.5.74 FileCopy Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Kopiert eine Datei Syntax FileCopy source$, target$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

source$

String

-

-

-

Alphanumerischer Ausdruck mit dem Dateinamen und dem Pfad der Datei, die kopiert werden soll.

target$

String

-

-

-

Alphanumerischer Ausdruck mit dem Dateinamen und dem Pfad der Zieldatei.

Aktion Die Anweisung kopiert die Quelldatei von source$ an die durch den Ausdruck target$ angegebene Stelle. Die angegebenen Parameter dürfen keine Wildcardzeichen enthalten. Sollte die Zieldatei bereits bestehen, wird diese überschrieben. Die Zieldatei darf nicht geöffnet sein. Fehler Nummer

Bezeichnung

Situation

70

Permission denied

Der Zugriff auf die Quell- oder Zieldatei wurde verwehrt.

Beispiel Filecopy "C:\AUTOEXEC.BAT", "C:\AUTOEXEC2.BAT"

Kopiert die Datei AUTOEXEC.BAT und gibt der Kopie den Namen AUTOEXEC2. BAT Siehe auch Dir, Kill, Name, Open, SetFileAttr

Die Befehle

467

24.5.75 FileDateTime Art

Kategorie

Funktion

Datei

Betriebssysteme

Notesversionen 4/5

Beschreibung Liefert die Zeit der letzten Änderung der Datei. Syntax FileDateTime ( fileName$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Der Dateiname und Pfad der Datei, deren Erstellungsdatum ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Erstelldatum der Datei

String

filename$ Datei vorhanden

Fehler

Datei nicht vorhanden

Fehler Nummer

Bezeichnung

Situation

53

File Not Found

Die angegebene Datei existiert nicht

Beispiel Print Filedatetime("C:\AUTOEXEC.BAT")

Liefert das letzte Änderungsdatum der Datei AUTOEXEC.BAT Siehe auch FileLen, GetFileAttr

24.5.76 FileLen Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

468

Die Befehls-Referenz

Beschreibung Liefert die Länge einer Datei zurück. Syntax FileLen ( fileName$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Eine Zeichenkette, welche den Dateinamen ggf. mit Pfad einer existierenden Datei beinhaltet.

Rückgabewert Rückgabewert

Rückgabetyp

Die Dateilänge in Byte

Long

Datei vorhanden

Fehler

Datei nicht vorhanden

Fehler Nummer

Bezeichnung

Situation

53

File Not Found

Die angegebene Datei existiert nicht

Beispiel Msgbox Filelen("C:\AUTOEXEC.BAT")

Liefert die Länge der Datei AUTOEXEC.BAT zurück. Siehe auch FileAttr

24.5.77 Fix Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert die ganzzahligen Anteile eines numerischen Ausdrucks. Syntax Fix ( value )

Die Befehle

469

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value

Double / DATE

+

-

-

Der numerische Ausdruck, welcher auf eine Ganzzahl abgerundet werden soll, oder ein Datumswert.

Rückgabewert Rückgabewert

Rückgabetyp

NULL

NULL

Ist NULL

value gerundet auf die nächstkleinere ganze Zahl.

Double

Numerisch

Fehler

value

Nicht Numerisch

Der Tagesanteil des Datumswertes

Variant

Datumswert

Beispiel Print Print Print Print

Fix(3.2) Fix(4.7) Fix(-5.1) Fix(NULL)

'liefert 'liefert 'liefert 'liefert

3 4 –5 NULL

Siehe auch Int, Fraction

24.5.78 Fraction Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert Nachkommastellen eines numerischen Wertes. Syntax Fraction ( value )

470

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value

Double / DATE

+

Nein

-

Der numerische Ausdruck, dessen Nachkommastellen ermittelt werden sollen, oder ein Datumswert.

Rückgabewert Rückgabewert

Rückgabetyp

value

Der Nachkommaanteil von value

Datentyp des Ausdrucks

Ist numerisch

NULL

NULL

NULL

Zeitanteil von value

DATE

Ist Date-Datentyp

Fehler keine Beispiel Print Fraction ( 1.2 )

'Liefert .2

Siehe auch Fix, Int

24.5.79 FreeFile Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert die nächste freie Referenznummer für eine zu öffnende Datei. Syntax Freefile Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

Die nächste freie Referenznummer für Dateien

Integer

Die Befehle

471

Bemerkung Die Funktion FreeFile wird verwendet, um eine freie Dateireferenznummer für die Verwendung z. B. im Open-Befehl zu ermitteln. Fehler Nummer

Bezeichnung

Situation

98

Illegal filenumber

Es sind keine Dateinummern mehr frei.

Beispiel filenr% = Freefile Open "C:\AUTOEXEC.BAT" For Input As filenr% Close filenr%

Holt sich eine freie Dateinummer und öffnet dann mit dieser die Datei. Siehe auch Open, Close

24.5.80 For Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Wiederholt die Ausführung eines Programmblocks so oft wie angegeben. Syntax For counterVar = start# To last# [ Step increment# ] [ statements ] Next [ counterVar ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

counterVar

Long

-

-

-

Eine Zählervariable

first#

Long

-

-

-

Startwert für die Zählvariable

last#

Long

-

-

-

Zielwert für die Zählvariable, der den Abbruch der Schleife veranlasst.

472

Die Befehls-Referenz

Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

increment#

Long

-

+

1

Schrittweite, um die die Zählvariable bei jedem Durchlauf erhöht wird.

Bemerkung Der Block mit den Programmbefehlen wird entsprechend der Zählvariable wiederholt. Bei jedem Schleifendurchlauf wird die Zählvariable um den angegebenen Inkrementwert erhöht. Begonnen wird der Durchlauf bei dem Startwert und beendet beim Zielwert. Die Wiederholung der Zählervariablen am Fußstatement »End For« dient lediglich der besseren Lesbarkeit. Beispiel For Index = 1 To 100 Print Index Next Index Durchläuft die Schleife 100 Mal und gibt die Zahlen von 1 bis 100 aus.

Siehe auch ForAll

24.5.81 ForAll Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Wiederholt die Ausführung eines Programmblocks für jedes Element eines Arrays, einer Liste oder einer Kollektion. Syntax ForAll refVar In container [ statements ] End ForAll

Die Befehle

473

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

refVar

Referenz

-

-

-

Eine Referenzvariable, die bei jedem Schleifendurchlauf das jeweilige Element beinhaltet.

container

Referenz

-

-

-

Die Referenz eines Arrays, einer Liste oder einer Kollektion, für deren Elemente der Programmblock jeweils ausgeführt werden soll.

statements

Programmblock

-

-

-

Der Anweisungsblock, der wiederholt ausgeführt werden soll.

Bemerkung Diese Schleife dient dazu, eine Menge von Elementen in einem Container zu durchlaufen. Dazu durchläuft die Referenzvariable alle Werte, die in der Menge enthalten sind. Für jeden Wert wird der Schleifenblock einmal durchlaufen. Beispiel Dim A List As Integer A("A")= 1 A("B")= 2 A("C") = 3 Forall x In A Print x End ForAll

'Gibt 1,2,3 aus

Siehe auch For

24.5.82 Format Art

Kategorie

Funktion

Programmablauf

Betriebssysteme

Notesversionen

Beschreibung Formatiert einen angegebenen Wert in ein gewünschtes Format. Syntax Format[$] ( expression [ , formatMask$ ] )

474

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

expression formatMask$

String

Null

Opt.

Default

Inhalt

+

-

-

Ein Ausdruck, der formatiert werden soll

-

Ja

-

Eine Zeichenkette, die angibt, wie der Ausdruck formatiert werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Der formatierte Ausdruck

String / Variant

Beispiel Msgbox Format(Now(), "DD-MMM-YYYY")

Gibt das aktuelle Datum mit zweistelliger Angabe des Tages, dem ausgeschriebenen Monatsnamen sowie der vierstelligen Jahreszahl aus.

24.5.83 FullTrim Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichenkette

Alle

5

Beschreibung Entfernt aus einem Array alle leeren Einträge oder entfernt Leerzeichen aus Zeichenketten. Bei Zeichenketten bezeichnet man diesen Vorgang auch als »Bereinigen«. Syntax FullTrim ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

-

-

-

Ein Array oder ein String bzw. ein Variant, der einen String beinhaltet.

Die Befehle

475

Rückgabewert Rückgabewert

Rückgabetyp

Situation

Der bereinigte String

String

Als Parameter wurde ein String oder ein Variant übergeben

Der bereinigte Array

Array

Als Parameter wurde ein Array übergeben

Bemerkung Ein bereinigter String ist eine Zeichenkette ohne führende oder abschließende Whitespaces sowie ohne doppelte Whitespaces. Whitespaces sind Zeichen wie SPACE, TAB oder NEWLINE. Ein bereinigter Array ist ein Array, aus dem alle leeren Elemente entfernt wurden. Sollte der Array nur noch ein leeres Element besitzen, bleibt dieses erhalten. Als leeres Element gilt ein Leerstring, der Wert 0 oder NULL sowie EMPTY, je nach Datentyp des Arrays.. Beispiel Print FullTrim(" Hallo

Du

Da

")

'Liefert "Hallo Du Da"

Dim A(5) As Integer A(0) = 1 A(1) = 2 A(4) = 3 B = Fulltrim (A) Forall x In B Msgbox x End Forall

Liefert 1, 2, 3 nacheinander (es gibt keine Leerelemente mehr) Siehe auch LTrim, RTrim, Trim, Erase

24.5.84 Function Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Deklaration

Alle

3/5

Beschreibung Deklariert eine Funktion.

476

Die Befehls-Referenz

Syntax [ Static ] [ Public | Private ] Function functionName [ ( [ paramList ] ) ] [ As returnType ] [ statements ] End Function Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Static

Konstant

-

+

-

Definiert die Funktion als Static

Public

Konstant

-

+

Public

Definiert die Funktion als Public

Private

Konstant

-

+

Public

Definiert die Funktion als Private

functionName

-

-

-

Der Funktionsname der neuen Funktion

paramList

-

+

-

Liste der Parameter

-

+

.

Der Anweisungsblock

returnType statements

Inhalt

Type des Rückgabewertes Programmblock

Bemerkung Diese Anweisung dient der Deklaration von Funktionen. Beispiel Function Quad(A As Integer)As Integer MyFunc = A * A End Function

Deklariert eine Funktion, die das Quadrat des Parameters zurückgibt. Siehe auch Sub, Class

24.5.85 Get Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liest Daten aus einer Binärdatei oder einer Randomdatei in eine Variable.

Die Befehle

477

Syntax Get [#]fileNumber% , [ recNumber% ] , varName Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Die Dateinummer, welche bei der Open-Anweisung gewählt wurde.

recNumber%

Integer

-

+

-

Die Byteposition in einer Binärdatei oder der Datensatz in einer Randomdatei. Wenn nichts angegeben wird, erfolgt das Einlesen von der aktuellen Position in der Datei.

varName

Referenz

-

-

-

Variable, in welche die Daten eingelesen werden sollen. Ein dynamischer Array ist hier nicht erlaubt. Ein statischer Array allerdings ist möglich.

Bemerkung Aus der Datei wird ab der angegebenen Position der Wert entsprechend der Variable varname eingelesen. Fehler Nr.

Bezeichnung

Situation

62

Input past end of file

Das Dateiende wurde erreicht

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\Daten.dat" For Input As #1 Get #1, 1, Buffer% Print Buffer% Close #1

'Liest einen Integer 'Gibt Integer aus

Siehe auch Input#

24.5.86 GetAttr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

478

Die Befehls-Referenz

Beschreibung siehe GetFileAttr

24.5.87 GetFileAttr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Ermittelt die Datei-Attribute einer Datei oder eines Verzeichnisses. Syntax GetFileAttr ( fileName$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Der Name der Datei oder des Verzeichnisses. Der kann bei Bedarf auch einen Pfad enthalten.

Rückgabewert Rückgabewert

Rückgabetyp

Situation

Attribute der Datei / des Verzeichnisses

Integer

Datei / Verzeichnis ist vorhanden

Fehler

fileName$ existiert nicht

Tabelle mit der Bitmaske der Attribute Wert

Attribute

Konstante

0

Normal file

ATTR_NORMAL

1

Read-only file

ATTR_READONLY

2

Hidden file

ATTR_HIDDEN

4

System file

ATTR_SYSTEM

16

Directory

ATTR_DIRECTORY

32

Archivflag

ATTR_ARCHIVE

Fehler Nummer

Bezeichnung

Situation

53

File Not Found

Die angegebene Datei existiert nicht

Die Befehle

479

Beispiel Msgbox Getfileattr("C:\AUTOEXEC.BAT")

'Liefert die Attribute der 'Datei AUTOEXEC.BAT zurück

Siehe auch GetAttr

24.5.88 GetObject Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Ole

Nicht unter OS/2, UNIX oder Mac

4/5

Beschreibung Liefert eine Referenz auf ein OLE Objekt. Syntax GetObject ( pathName$ [ , className$ ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

pathName$

String

-

-

-

Dateiname der Applikation (inklusive Pfad)

className$

String

-

-

-

Eine Zeichenkette der Form Applikation.Class, welche die Applikation und Klasse definiert.

Rückgabewert Rückgabewert

Rückgabetyp

OLE Automation Objekt-Referenz

OBJECT

Bemerkung Diese Funktion liefert eine Referenz auf ein OLE-Objekt aus einer existierenden Datei, welche mit Hilfe der Set-Anweisung einer Objektvariable zugewiesen werden muss. Beispiel Set A = GetObject("C:\mydoc.doc") ' Liefert eine Referenz auf die Datei mydoc.doc in der ' Word-Programmumgebung.

480

Die Befehls-Referenz

Siehe auch CreateObject

24.5.89 GetThreadInfo Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Thread

Alle

5

Beschreibung

Liefert Informationen über den Thread. Syntax GetThreadInfo ( infoID% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

infoID%

Integer

-

-

-

Flag für die Art der Information, welche zurückgegeben werden soll

Rückgabewert Rückgabewert

Rückgabetyp

InfoID%

Aktuelle Zeilennummer

Integer

LSI_THREAD_LINE

Name der aktuellen Prozedur

String

LSI_THREAD_PROC

Name des aktuellen Moduls

String

LSI_THREAD_MODULE

LotusScript-Versionsnummer

String

LSI_THREAD_VERSION

Anwendersprache

String

LSI_THREAD_LANGUAGE

Landeseinstellung

Long

LSI_THREAD_COUNTRY

Clock ticks

Long

LSI_THREAD_TICKS

Clock ticks per second

Long

LSI_THREAD_TICKS_PER_SEC

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

infoID% hat einen ungültigen Wert.

Die Befehle

481

Beispiel Sub Initialize Msgbox GetThreadInfo(LSI_THREAD_MODULE) End Sub

Liefert den Namen der aktuellen Prozedur, also Initialize. ( LSI_THREAD_MODULE =1)

24.5.90 GoSub Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Übergibt die Kontrolle an das angegebene Unterprogramm. Dieses ist per Label in derselben Prozedur-/ Funktionsebene definiert. Mit der Return-Anweisung kann zurückgesprungen werden. Syntax GoSub label Parameter Bezeichnung label

Datentyp

Null

Opt.

Default

Inhalt

-

-

-

Label des Unterprogramms.

Bemerkung Die Gosub-Anweisung darf nur auf Prozedurenebene genutzt werden. Der GosubAufruf und das Label müssen sich in derselben Prozedur befinden. Beispiel Sub MyProc Print "Hallo" Gosub Unter Print "Auf Wiedersehen" Exit Sub Unter: Print "Ich heiße Notes" Return End Sub

Dieses Programm gibt alle drei Ausgaben aus.

482

Die Befehls-Referenz

Siehe auch GoTo, On...GoSub

24.5.91 GoTo Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Fährt mit der Programmausführung an dem angegebenen Programmpunkt fort. Syntax GoTo label Parameter Bezeichnung

Datentyp

label

Null

Opt.

Default

Inhalt

-

-

-

Programmlabel, an dem die Programmausführung fortgesetzt werden soll.

Bemerkung Die Goto-Anweisung darf nur in Prozedurenebene verwendet werden. Es ist nicht zulässig, die Goto-Anweisung zu nutzen, um in oder aus einem With...End WithBlock zu springen. Beispiel Sub MyProc Print "Hallo" Goto Sprung Print "Auf Wiedersehen" Sprung: Print "Ich heiße Notes" End Sub

Dieses Programm gibt nur "Hallo" und "Ich heiße Notes" aus. Siehe auch On...GoTo, GoSub

Die Befehle

483

24.5.92 Hex Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Gibt eine Zahl in Hexadezimal-Darstellung zurück. Syntax Hex[$] ( value& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Long

-

-

-

Ein beliebiger numerischer Ausdruck, von dem eine Hexdarstellung ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Hexcode vom gerundeten Wert von value&. Die maximale Länge der zurückgegebenen Zeichenkette beträgt 8 Stellen

String / Variant

Beispiel Msgbox Hex(15)

'Liefert F als Ausgabe

Siehe auch Bin, Oct

24.5.93 Hour Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert den Stundenanteil Syntax Hour ( dateValue )

484

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

dateValue

DATE

+

-

-

Ein numerischer oder ein Zeitwert, dessen Stundenanteil ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

datevalue

Den Stundenanteil von dateValue

Variant

Beliebiger Zeitwert

NULL

NULL

NULL

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Zeit interpretieren oder liegt außerhalb von 1.1.100 bis 31.12.9999

Beispiel Print Hour("10:00 31.01.1999") Print Hour(NULL)

'liefert 10 'liefert NULL

Siehe auch Day, Minute, Month, Now, Second, Today, Weekday, Year

24.5.94 If...Goto Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Fährt bedingt durch einen Ausdruck an einer bestimmten Stelle mit der Programmausführung fort. Syntax If condition% GoTo label [ Else [ statements ] ]

Die Befehle

485

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

condition%

Integer

-

-

-

Bedingung, die bestimmt, ob die Programmausführung an der durch das Label bestimmten Stelle fortgesetzt wird.

label

-

-

-

Name des Labels, welches bestimmt, wo die Programmausführung fortgesetzt wird, wenn die Bedingung zutrifft.

statements

-

+

-

Programmblock, welcher ausgeführt wird, wenn die Bedingung nicht erfüllt wird.

Bemerkung Diese Anweisung dient zur bedingten Ausführung eines Sprungs zu einem Programmlabel. Beispiel Sub MyProc For Index = 1 To 10 If Index = 5 Goto Label Next Index Label: Print Index End Sub

Dieses Programm verlässt die For Next-Schleife bei einem Wert von 5 im Index. Siehe auch If...Then...Else

24.5.95 If...Then...Else Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Führt bedingt durch einen Ausdruck einen von zwei Programmblöcken aus. Syntax If condition% Then [ statementsA ] [ Else [ statementsB ] ]

486

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

condition%

Integer (TRUE / FALSE)

-

-

-

Bedingung, die bestimmt, ob die Programmausführung mit dem einen oder dem anderen Programmblock fortgesetzt wird.

statementsA

Programmblock

-

+

-

Ein Anweisungsblock, der ausgeführt wird, wenn die Bedingung erfüllt ist.

statementsB

Programmblock

-

+

-

Ein Anweisungsblock, der ausgeführt wird, wenn die Bedingung nicht erfüllt ist.

Bemerkung Diese Anweisung dient zum bedingten Ausführen von zwei verschiedenen Programmblöcken. Sollte die Bedingung den Wert TRUE haben, wird der Programmblock statementsA ausgeführt, sonst statementsB. Beispiel For Index = 1 To 10 If Index Mod 2 = 0 Then Print Index, "ist gerade" Else Print Index, "ist ungerade" End If Next Index

In diesem Beispiel wird bei den Zahlen von 1 bis 10 jeweils ausgegeben, ob sie gerade oder ungerade sind. Siehe auch If...Then...ElseIf

24.5.96 If...Then...ElseIf Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Führt bedingt durch einen oder mehrere Ausdrücke einen von mehreren Programmblöcken aus.

Die Befehle

487

Syntax If condition Then statements [ ElseIf condition Then statements ] ... [ Else statements ] End If Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

condition%

Integer (TRUE / FALSE)

-

-

Bedingung, die erfüllt sein muss, damit der folgende Anweisungsblock ausgeführt wird

statements

Programmblock

+

-

Anweisungsblock, der ausgeführt wird, wenn die davor stehende Bedingung erfüllt ist

Beispiel If A = 1 Then Print "Der Elseif A = 2 Then Print "Der Elseif A = 3 Then Print "Der Else Print "Der End If

Wert ist eins" Wert ist zwei" Wert ist drei" Wert ist unbekannt"

Dieser Block gibt den Wert für 1,2,3 in A mit Worten aus, sonst wird der Wert als unbekannt angesehen. Siehe auch If...Then, If...Then...Else

488

Die Befehls-Referenz

24.5.97 IMEStatus Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Windowssystem

nur Windows

5

Beschreibung Liefert den Status des aktuellen Input Mode for Extended Character Sets (IME). Syntax IMEStatus Parameter Keine Rückgabewert Rückgabewert

Rückgabetyp

Country

Beschreibung

0 (IME_NOT_INSTALLED)

Integer

All

IME is not installed

1 (IME_ON)

Integer

IME is on

2 (IME_OFF)

Integer

IME is off

4 (IME_HIRAGANA)

Integer

5 (IME_KATAKANA_DBCS)

Integer

Double-byte Katakana

6 (IME_KATAKANA_SBCS)

Integer

Single-byte Katakana

7 (IME_ALPHA_DBCS)

Integer

Double-byte alphanumeric

8 (IME_ALPHA_SBCS)

Integer

4 (IME_NATIVE_MODE)

Integer

7 (IME_ALPHA_DBCS)

Integer

Japan

Double-byte Hiragana

Single-byte alphanumeric Taiwan

Taiwan native mode Double-byte alphanumeric

8 (IME_ALPHA_SBCS)

Integer

4 (IME_HANGEUL)

Integer

5 (IME_HANJACONVERT)

Integer

Hanja conversion

7 (IME_ALPLHA_DBCS)

Integer

Double-byte alphanumeric

8 (IME_ALPHA_SBCS)

Integer

Single-byte alphanumeric

4 (IME_NATIVE_MODE)

Integer

7 (IME_ALPHA_DBCS)

Integer

8 (IME_ALPHA_SBCS)

Integer

0

Integer

Single-byte alphanumeric Korea

PRC

Hangeul DBC

PRC native mode Double-byte alphanumeric Single-byte alphanumeric

sonst

sonst

Die Befehle

489

Siehe auch IMESetMode

24.5.98 IMESetMode Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Windowssystem

Nur Windows

5

Beschreibung Setzt den IME (Input Mode for Extended Character Sets). Syntax IMESetMode ( imeMode% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

imeMode%

Integer

-

-

-

Der Input Mode

Wert für den Input Mode Wert

Country

Beschreibung

1 (IME_ON)

Set IME on

2 (IME_OFF)

Set IME off

4 (IME_HIRAGANA)

Japan

Double-byte Hiragana

5 (IME_KATAKANA_DBCS)

Double-byte Katakana

6 (IME_KATAKANA_SBCS)

Single-byte Katakana

7 (IME_ALPHA_DBCS)

Double-byte alphanumeric

8 (IME_ALPHA_SBCS)

Single-byte alphanumeric

4 (IME_NATIVE_MODE)

Taiwan

7 (IME_ALPHA_DBCS)

Double-byte alphanumeric

8 (IME_ALPHA_SBCS) 4 (IME_HANGEUL)

Taiwan native mode Single-byte alphanumeric

Korea

Hangeul DBC

5 (IME_HANJACONVERT)

Hanja conversion

7 (IME_ALPHA_DBCS)

Double-byte alphanumeric

8 (IME_ALPHA_SBCS)

Single-byte alphanumeric

4 (IME_NATIVE_MODE)

PRC

7 (IME_ALPHA_DBCS)

Double-byte alphanumeric

8 (IME_ALPHA_SBCS) 0

PRC native mode Single-byte alphanumeric

sonst

sonst

490

Die Befehls-Referenz

Rückgabewert Rückgabewert

Rückgabetyp

TRUE

Integer

Setzen war erfolgreich

FALSE

Integer

Setzen war nicht erfolgreich

Siehe auch IMEStatus

24.5.99 InputBox Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Benutzerinteraktion

Alle

4/5

Beschreibung Zeigt eine Eingabemaske für Benutzereingaben an. Syntax InputBox[$] ( prompt$ [ , [ title$ ] [ , [ default$ ] [ , xPos% , yPos% ] ] ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

prompt$

String

-

-

-

Die Eingabeaufforderung, welche angezeigt werden soll

title$

String

-

Ja

""

Der Text, welcher in der Titelzeile angezeigt werden soll

default$

String

-

Ja

Ein Vorgabewert für die Eingabe

xPos%

Integer

-

Ja

Die x-Position der Eingabemaske in Pixel

yPos%

Integer

-

Ja

Die y-Position der Eingabemaske in Pixel

Rückgabewert Der vom Anwender eingegebene Text. Bemerkung Vorsicht bei der Verwendung in Agents, welche auf dem Server laufen.

Die Befehle

491

Beispiel A = Inputbox("Bitte Text eingeben")

Dieses Beispiel fragt den Anwender nach einem Text und speichert diesen dann in A. Siehe auch MessageBox

24.5.100 Input# Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Liest Daten aus einer sequentiellen Datei in eine Variable. Syntax Input # fileNumber% , expressions Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Die Dateinummer, welche bei der Open-Anweisung gewählt wurde.

-

-

-

Kommaseparierte Liste von Variablen, in die gelesen werden soll.

expressions

Fehler Nr.

Bezeichnung

Situation

62

Input past end of file

Das Dateiende wurde erreicht

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\Daten.dat" For Input As #1 Input #1, A% Print A% Close #1

Dieses Programmsegement öffnet eine Datei und liest einen Integer-Wert ein. Der eingelesene Wert wird dann ausgegeben.

492

Die Befehls-Referenz

24.5.101 Input Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liest eine Sequenz von Zeichen aus einer sequentiellen oder binären Datei. Syntax Input[$] ( count %, [#] fileNumber% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

count%

Integer

-

-

-

Anzahl der Zeichen

fileNumber%

Integer

-

-

-

Dateinummer, die bei der OpenAnweisung gewählt wurde

Rückgabewert Rückgabewert

Rückgabetyp

Die angegebene Anzahl von Zeichen aus der Datei

String / Variant

count% > 0 und es sind genügend Zeichen in der Datei vorhanden

""

String / Variant

count% = 0

Fehler Nr.

Bezeichnung

Situation

62

Input past end of file

Das Dateiende wurde erreicht

Beispiel Open "C:\Daten.dat" For Input As #1 A$ = Input(5,1) Print A$ Close #1

Dieses Programmsegement öffnet eine Datei und liest 5 Zeichen in eine String-Variable. Der eingelesene Wert wird dann ausgegeben. Siehe auch Input#

Die Befehle

493

24.5.102 InputB Beschreibung Diese Funktion verhält sich identisch zu der Funktion Input, nur dass hier der Zugriff auf Byteebene erfolgt.

24.5.103 InputBP Beschreibung Diese Funktion verhält sich identisch zu der Funktion InputB, nur dass hier der plattformspezifische Zeichensatz verwendet wird.

24.5.104 InStr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichenkette

Alle

4/5

Beschreibung Sucht eine Zeichenkette in einer Zeichenkette. Syntax InStr ( [ start& , ] string1$, string2$ [, compareFlag% ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

start&

Double

-

+

0

Optional. Ein numerischer positiver Ausdruck, welcher die Stelle bestimmt, ab der der Teilstring gesucht wird.

string1$

String

+

-

-

Zeichenkette, in der gesucht wird

string2$

String

+

-

-

Die Zeichenkette, nach der gesucht wird

494

Die Befehls-Referenz

Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

compareFlag%

Integer

-

+

-

Vergleichsmethode 0: Case Sensitive und Pitch Sensitive 1: Case Insensitive und Pitch Sensitive 4: Case Sensitive und Pitch Insensitive 5: Case Insensitive und Pitch Insensitive Als Standard gilt die Einstellung mit Option Compare Wenn keine Option Compare verwendet wird, gelten Case und Pitch Sensitive

Rückgabewert Rückgabewert

Rückgabetyp

0

Integer

string1$ ist ""

0

Integer

string2$ nicht in string1$ nach der start& Stelle enthalten

0

Integer

start& ist größer als die Länge von string1$

1

Integer

string2$ ist ""

NULL

NULL

string1$ ist NULL

NULL

NULL

string2$ ist NULL

Beispiel Msgbox Instr("Hallo ich bin drin", "ich")

'Liefert 7.

Siehe auch InStrB, InStrBP, InStrC, Option Compare, StrCompare

24.5.105 InStrB Beschreibung Diese Funktion verhält sich identisch zu der Funktion InStr, nur dass hier die Position eines Bytes ermittelt wird.

Die Befehle

495

24.5.106 InStrBP Beschreibung Diese Funktion verhält sich identisch zu der Funktion InStrB, nur dass hier der plattformspezifische Zeichensatz verwendet wird.

24.5.107 InStrC Beschreibung Diese Anweisung verhält sich identisch zu der Anweisung InStr, nur dass hier besondere fernöstliche Zeichensätze beachtet werden.

24.5.108 Int Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert die abgerundete Ganzzahl eines numerischen Ausdrucks. Syntax Int ( value& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Double

+

-

-

Der numerische Ausdruck, welcher auf die nächstkleinere Ganzzahl abgerundet werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

value&

NULL

NULL

NULL

Der numerische Wert von value& gerundet auf die nächstkleinere ganze Zahl.

Double

Numerisch

Fehler

Nicht Numerisch

496

Die Befehls-Referenz

Beispiel Print Print Print Print

Int(3.2) Int(4.7) Int(-5.1) Int(NULL)

'liefert 'liefert 'liefert 'liefert

3 4 –6 NULL

Siehe auch Fix, Fraction

24.5.109 IsA Art

Kategorie

Betriebssysteme

Notesversionen

Operator

Datentypen

Alle

4/5

Beschreibung Dieser Operator dient zur Ermittlung des Datentyps eines Objektes. Syntax object IsA objectTyp$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

object

Objekt

-

-

-

Eine Objektreferenz eines Notesobjektes, Produktobjektes oder OLE-Objektes

objectTyp$

String

-

-

-

Ein Objekttyp als Zeichenkette

Rückgabewert Rückgabewert

Rückgabetyp

TRUE

Integer

object ist vom angegebenen Objekttyp oder hat einen Datentyp, welcher von dem angegebenen abgeleitet ist

FALSE

Integer

Sonst

Fehler Fehlernr.

Fehlerbeschreibung

Situation

183

Variant does not contain an object

object beinhaltet kein Objekt

Die Befehle

497

Beispiel Class ClassA End Class DIM Obj AS ClassA Print Obj IsA "ClassA" Print Obj IsA "ClassB"

'liefert TRUE 'liefert FALSE

Siehe auch Is

24.5.110 IsArray Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Testet, ob der angegebene Ausdruck vom Datentyp Array ist. Syntax IsArray ( expression ) Parameter Bezeichnung

Datentyp

expression

Null

Opt.

Default

Inhalt

+

-

-

Ein beliebiger Ausdruck

Rückgabewerte Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

Ausdruck ist ein Array

FALSE

Integer

Ausdruck ist kein Array

Beispiel Dim A(100) As Integer Msgbox Isarray(A)

'Liefert True

Dim B As Integer Msgbox Isarray(B)

'Liefert False

Siehe auch IsList, IsObject, IsScalar

498

Die Befehls-Referenz

24.5.111 IsDate Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Prüft, ob der angegebene Ausdruck vom Typ Date ist. Syntax IsDate ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Ein beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

erxpression ist ein Variant oder String-Datentyp, der als Datum interpretiert werden kann

FALSE

Integer

expression ist kein Variant oder String-Datentyp oder kann nicht als Datum interpretiert werden

Beispiel Msgbox Isdate("01.01.2000")

'Liefert True

A = Now() Msgbox Isdate(A)

'Liefert True

Siehe auch CDat, IsNumeric, IsScalar

24.5.112 IsDefined Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Überprüft, ob die angegebene Produktkonstante definiert ist.

Die Befehle

499

Syntax IsDefined ( name$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

name$

String

-

-

-

Der Name der Produktkonstanten

Rückgabewert Rückgabewert

Rückgabetyp

name$

TRUE

Integer

ist definiert

FALSE

Integer

ist nicht definiert

Beispiel Msgbox IsDefined("WIN32")

'liefert in einer Windows 32Bit 'Umgebung -1 ( True )

24.5.113 IsElement Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Überprüft, ob die angegebene Zeichenkette ein Listtag der angegebenen Liste ist. Syntax IsElement ( listName ( listtag$ ) ) Parameter Bezeichnung

Datentyp

listName listtag$

String

Null

Opt.

Default

Inhalt

-

-

-

Der Name einer beliebigen Liste

-

-

-

Eine beliebige Zeichenkette

Rückgabewert Rückgabewert

Rückgabetyp

TRUE

Integer

Die übergebene Zeichenkette ist als Schlüsselwert in der Liste enthalten

FALSE

Integer

Sonst

500

Die Befehls-Referenz

Fehler Fehlernr.

Fehlerbeschreibung

Situation

184

Variant does not contain a container

listName ist keine gültige Liste

Bemerkung Wenn der Listentag ein numerischer Ausdruck ist, wird dieser erst in eine Zeichenkette umgewandelt. Beispiel Dim MeineListe List As Integer MeineListe("A")= 100 MeineListe("B")= 200 MeineListe("C")= 300 Msgbox IsElement(MeineListe("B")) Msgbox IsElement(MeineListe("D"))

'Liefert True 'Liefert False

Siehe auch ForAll, ListTag

24.5.114 IsEmpty Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Liefert TRUE zurück, wenn der übergebene Ausdruck den Wert EMPTY hat. Syntax IsEmpty ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Ein beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

EMPTY

FALSE

Integer

Sonst

Die Befehle

501

Beispiel A = EMPTY Msgbox Isempty(A)

'Liefert True

Siehe auch IsUnknown, IsNull, IsNumeric

24.5.115 IsList Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Überprüft den Datentyp des übergebenen Ausdrucks auf den Datentyp List. Syntax IsList ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Ein beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

Ist vom Datentyp List

FALSE

Integer

Sonst

Beispiel Dim A List As Integer Dim B As Integer Msgbox Islist(A) Msgbox Islist(B)

'Liefert True 'Liefert False

Siehe auch IsArray, IsElement, IsObject, IsScalar

502

Die Befehls-Referenz

24.5.116 IsNull Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Diese Funktion überprüft den Ausdruck auf den Wert NULL. Syntax IsNull ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Ein beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

NULL

FALSE

Integer

Sonst

Beispiel A = NULL B = 100 Msgbox Isnull(A) Msgbox Isnull(B)

'Liefert True 'Liefert False

Siehe auch IsEmpty, IsUnkown

24.5.117 IsNumeric Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Diese Funktion überprüft, ob der übergebene Ausdruck entweder einen numerischen Datentyp besitzt oder in einen numerischen Wert umgewandelt werden kann. Syntax IsNumeric ( expression )

Die Befehle

503

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

Nein

-

Ein beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

Hat Datentyp Integer, Long, Single, Double, Currency, Date/Time, Integer oder OLEError oder lässt sich in einen der Datentypen umwandeln

FALSE

Integer

Hat Datentyp Array, List oder Objekt

FALSE

Integer

Hat den Wert NULL oder NOTHING

Beispiel A = 123 B = "Hallo" Msgbox Isnumeric(A) Msgbox Isnumeric(B)

'Liefert True 'Liefert False

Siehe auch IsDate, IsEmpty, IsNull, IsScalar

24.5.118 IsObject Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

nicht unter OS/2, UNIX oder Mac

4/5

Beschreibung Diese Funktion überprüft, ob der übergebene Ausdruck ein Objekt ist. Wobei es ein benutzerdefiniertes, ein produktspezifisches oder ein OLE-Objekt sein kann. Syntax IsObject ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Ein beliebiger Ausdruck

504

Die Befehls-Referenz

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

Ist ein Notes-Objekt, benutzerdefinertes Objekt oder OLE-Objekt

FALSE

Integer

Sonst

TRUE

Integer

NOTHING

Beispiel Set B = Createobject("Word.Document.8") Set C = Nothing Msgbox Isobject(B) 'Liefert True Msgbox Isobject(C) 'Liefert True

Siehe auch Is, IsArray, IsList, IsScalar

24.5.119 IsScalar Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Es wird überprüft, ob der angegebene Ausdruck einen einfachen Datentyp wie z. B. Integer, Long, Single, Double, Currency, Date/Time, String, Integer oder OLE Error hat. Syntax IsScalar ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Variant

+

-

-

Ein beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Expression

TRUE

Integer

Ist vom Datentyp Integer, Long, Single, Double, Currency, DATE/TIME, String, Integer oder OLEError

FALSE

Integer

Sonst

TRUE

Integer

EMPTY

Die Befehle

505

Rückgabewert

Rückgabetyp

Expression

FALSE

Integer

NOTHING

FALSE

Integer

NULL

Beispiel Dim A List As Integer Dim B(100) As Integer Dim C As Integer Msgbox Isscalar(A) Msgbox Isscalar(B) Msgbox Isscalar(C)

'Liefert False 'Liefert False 'Liefert True

Siehe auch IsArray, IsList, IsObject, IsNumeric, IsDate

24.5.120 IsUnknown Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Test, ob es sich bei dem übergebenen Ausdruck um ein bekanntes Objekt handelt. Syntax IsUnknown ( expression ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Beliebig

+

-

-

Beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

TRUE

Integer

expression ist ein unbekanntes OLE-Objekt

FALSE

Integer

Sonst

Siehe auch IsEmpty, IsScalar

Expression

506

Die Befehls-Referenz

24.5.121 Kill Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Löscht eine Datei. Syntax Kill fileName$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Eine Zeichenkette, deren Wert eine Datei repräsentiert. Es sind keine Wildcards zulässig. Gegebenenfalls kann ein Dateipfad enthalten sein.

Beschreibung Löscht die angegebene Datei. Fehler Fehlernr.

Fehlerbeschreibung

75

Path/file access

Die Datei kann nicht gefunden werden

55

File already open

Der zu löschende File ist geöffnet

Beispiel Kill "C:\Daten.dat"

'Löscht die Datei Daten.dat

Siehe auch FileCopy

24.5.122 LBound Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Array

Alle

4/5

Beschreibung Untere Indexgrenze eines Arrays.

Die Befehle

507

Syntax LBound ( arrayName [ , dimension% ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

arrayName

Array

-

-

-

Eine Referenz auf einen Array

dimension%

Integer

-

Ja

1

Dimension, deren Untergrenze ermittelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Arrayname

Untere Indexgrenze des Arrays für die angegebene Dimension

Long

Ist ein statischer Array und hat mindestens so viele Dimensionen wie dimension%

Untere Indexgrenze des Arrays für die angegebene Dimension

Long

Ist ein initialisierter dynamischer Array und hat mindestens so viele Dimensionen wie dimension%

Fehler

Sonst

Fehler Fehlernr.

Fehlerbeschreibung

Situation

200

Attempt to access uninitialized dynamic Array

Der angegebene Array ist ein dynamischer Array und ist nicht initialisiert worden.

Beispiel Dim A(5 To 10) As Integer Msgbox Lbound(A)

'Liefert 5

Siehe auch IsArray, UBound, Option Base

24.5.123 LCase Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Wandelt eine Zeichenkette in Kleinbuchstaben.

508

Die Befehls-Referenz

Syntax LCase[$] ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Beliebiger Ausdruck, der in eine Zeichenkette gewandelt werden kann

Rückgabewert Rückgabewert

Rückgabetyp

string$

string$ gewandelt in Kleinbuchstaben

Variant/String

Beliebige Zeichenkette

Beispiel Msgbox Lcase("Hallo")

'Liefert "hallo"

Siehe auch UCase

24.5.124 Left Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Linker Teilstring Syntax Left[$] ( string$, count% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

Variant

-

-

-

Quellzeichenkette

count%

Integer

-

-

-

Anzahl der Zeichen

Die Befehle

509

Rückgabewert Rückgabewert

Rückgabetyp

count%

count%- Zeichen aus string$, von links

Variant/ String

Numerischer Wert >= 0 und kleiner der Länge von string$

""

Variant/ String

0

string$

Variant/ String

Numerischer Wert >= 0 und größer gleich der Länge von string$

Fehler Fehlernr.

Fehlerbeschreibung

5

Illegal Function Call

count% ist negativ

Beispiel Print Left("Hallo", 2) Print Left(NULL, 2) Print Left$(NULL, 2)

'liefert Ha 'liefert NULL 'liefert einen Fehler

Siehe auch LeftB, LeftBP, LeftC, Len, Mid, Right

24.5.125 LeftB Beschreibung Diese Funktion verhält sich identisch zu der Funktion Left, nur dass hier die Anzahl nach Bytes gerechnet wird. Diese Funktion sollte unter den aktuellen LotusScript-Versionen nicht mehr verwendet werden. Stattdessen sollte die Funktion Left verwendet werden.

24.5.126 LeftBP Beschreibung Diese Funktion verhält sich identisch zu der Funktion LeftB, nur dass hier der plattformspezifische Zeichensatz verwendet wird.

510

Die Befehls-Referenz

24.5.127 LeftC Beschreibung Diese Anweisung verhält sich identisch zu der Anweisung Left, nur dass hier besondere fernöstliche Zeichensätze beachtet werden.

24.5.128 Len Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Liefert die Länge einer Zeichenkette oder den Speicherbedarf für eine Variable. Syntax Len ( { string$ | varName | typeName } ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Die Zeichenkette, deren Länge ermittelt werden soll

-

-

-

varName typeName

Der Name einer Variable Die Instanz eines benutzerdefinierten Datentyps

Rückgabewert Rückgabewert

Rückgabetyp

Anzahl der Zeichen von string$

Variant

Beliebige Zeichenkette

Speicherbedarf für varName

Variant

varName

Speicherbedarf für typeName

Variant

typeName

0

Variant

EMPTY

Beispiel Msgbox Len("Hallo") Msgbox Len(A%)

Siehe auch LenB, LenBP

'Liefert 5 'Liefert 2

Die Befehle

511

24.5.129 LenBP Beschreibung Diese Funktion verhält sich identisch zu der Funktion LenB, nur dass hier der plattformspezifische Zeichensatz verwendet wird.

24.5.130 LenB Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Länge einer Zeichenkette in Byte oder Speicherbedarf einer Variable in Byte. Syntax LenB ( { string$ | varName | typeName } ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Die Zeichenkette, deren Länge ermittelt werden soll

varName

Referenz

-

-

-

Eine Variable

typeName

Referenz

-

-

-

Die Instanz eines benutzerdefinierten Datentyps

Rückgabewert Rückgabewert

Rückgabetyp

Angegeben ist

Länge der Zeichenkette in Byte

Long

string$

Speicherbedarf für den Datentyp

Long

typeName

Speicherbedarf für die Variable

Long

varName

Beispiel Msgbox LenB("Hallo") Msgbox LenB(A%)

Siehe auch Len, LenBP

'Liefert 10 'Liefert 2

512

Die Befehls-Referenz

24.5.131 LenC Beschreibung Diese Anweisung verhält sich identisch zu der Anweisung Len, nur dass hier besondere fernöstliche Zeichensätze beachtet werden.

24.5.132 Let Art

Kategorie

Anweisung

Betriebssysteme

Notesversionen

Alle

4/5

Beschreibung Weist einer Variable einen Wert zu. Wird im Allgemeinen weggelassen. Syntax [ Let ] variableID = expr Beschreibung Steht für eine einfache Wertzuweisung.

24.5.133 ListTag Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Liste

Alle

4/5

Beschreibung Liefert den Listtag eines Listenelementes zurück, welches durch eine Referenz von einer ForAll-Schleife bestimmt wird. Syntax Listtag ( refVar ) Parameter Bezeichnung refVar

Datentyp

Null

Opt.

Default

Inhalt

-

-

-

Eine Referenzvariable einer ForAllSchleife

Die Befehle

513

Rückgabewert Rückgabewert

Rückgabetyp

Name des Listenelementes, welches durch die Referenz gewählt wird

String

Bemerkung Wenn die Option Compare NoCase gewählt wurde, wird der Name des Listenelements in Großbuchstaben zurückgeliefert. Fehler Ein Compilerfehler wird erzeugt, wenn refVar keine Forall-Referenzvariable ist. Beispiel Dim A List As Integer A("A")= 100 A("B")= 200 A("C")= 300 Forall x in A Print Listtag(x) End Forall

'Liefert A, B, C

24.5.134 Loc Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert die aktuelle Position eines Dateizeigers in einer geöffneten Datei zurück. Syntax Loc ( fileNumber% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Die Dateireferenznummer der Datei, von der die Position des Dateizeigers ermittelt werden soll.

514

Die Befehls-Referenz

Rückgabewert Rückgabewert

Rückgabetyp

Dateityp

Die Position des zuletzt gelesenen oder geschriebenen Datensatzes.

Long

Randomdatei

Die Byte-Position des letzten Zugriffs dividiert durch 128 und gerundet.

Long

Sequentialdatei

Die Byte-Position des letzten Zugriffs.

Long

Binärdatei

Fehler Nummer

Bezeichnung

Situation

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\Daten.Dat" For Binary As #1 Msgbox Loc(1) 'Liefert 0 A$ = Input(5, 1) Msgbox Loc(1) 'Liefert 5 Close #1

Siehe auch Seek

24.5.135 Lock Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Steuert das Sperren von Dateien. Syntax Lock [#] fileNumber% [ , recordNumber% | { [ start% ] To end% } ] Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

Die Dateinummer, welche bei der OpenAnweisung angegeben wurde

Die Befehle

515

Bezeichnung

Datentyp

Opt.

Default

Inhalt

recordNumber%

Integer

+

-

In einer Randomdatei die Nummer des Datensatzes, welcher gesperrt werden soll. In einer Binärdatei die Position des Bytes, welches gesperrt werden soll. In einer sequentiellen Datei wird dieser Parameter nicht berücksichtigt.

start%

Integer

+

-

In einer Randomdatei der Beginn eines Bereiches von Datensätzen, die gesperrt werden sollen. In einer Binärdatei der Beginn des Bereiches von Bytes. Bei einer sequentiellen Datei wird immer die gesamte Datei ohne Rücksicht auf diesen Parameter gesperrt.

end%

Integer

+

-

Ende des zu sperrenden Bereiches

Bemerkung In Windows 3.1 muss das Programm SHARE.EXE gestartet worden sein, um einen gemeinsamen Zugriff auf eine Datei zu ermöglichen. Beispiel Open "C:\Daten.dat" For Input As #1 Lock #1 'Sperrt die Datei für andere Prozesse Unlock #1 'Entsperrt die Datei für andere Prozesse Close #1

Siehe auch Unlock

24.5.136 Lof Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Liefert die Länge einer geöffneten Datei in Bytes. Syntax Lof ( fileNumber% )

516

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Die Dateireferenznummer der Datei, von der die Länge ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Größe der Datei

Long

Fehler Nummer

Bezeichnung

Situation

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\daten.dat" For Input As #1 Msgbox Lof(1) Close #1

'Liefert die Länge der Datei

Siehe auch Loc

24.5.137 Log Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den natürlichen Logarithmus eines numerischen Ausdrucks. Syntax Log ( expression& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression&

Double

-

-

-

Der numerische Wert, dessen Logarithmus ermittelt werden soll.

Die Befehle

517

Rückgabewert Rückgabewert

Rückgabetyp

expression&

Natürlicher Logarithmus von expression&

Double

Numerisch

Fehler

0

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

expression& ist 0

Beispiele Print Log(1)

'Liefert 0

Siehe auch Exp

24.5.138 LSet Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Zeichen

Alle

4/5

Beschreibung Weist die angegebene Zeichenkette einer Zeichenkettenvariablen zu und richtet diese dabei wenn möglich am linken Rand der Variable aus. Syntax LSet stringVar = string$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

stringVar

Referenz

-

-

-

Name einer Variable vom Datentyp String oder Variant

string$

String

-

-

-

Die Zeichenkette, die zugewiesen werden soll

Beispiel A$ = "ABC" Lset A$ = "Hallo" Msgbox A$

'Liefert "Hal"

518

Die Befehls-Referenz

Siehe auch RSet

24.5.139 LTrim Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Entfernung aller führenden Leerzeichen. Syntax LTrim ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Ein alphanumerischer Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Übergebene Zeichenkette ohne die führenden Leerzeichen

Variant / String

Beispiel Msgbox Ltrim("

Hallo

")

'Liefert "Hallo

"

Siehe auch FullTrim, LSet, RSet, RTrim, Trim

24.5.140 Like Art

Kategorie

Betriebssysteme

Notesversionen

Operator

Zeichen

Alle

4/5

Beschreibung Prüft, ob eine gegebene Zeichenkette einer angegebenen Suchmaske entspricht. Syntax string$ Like mask$

Die Befehle

519

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

+

-

-

Zu überprüfende Zeichenkette

mask$

String

+

-

-

Suchmaske

Suchmaskenzeichen Wildcard

Matches

?

Beliebiges Zeichen

#

Beliebige Ziffer

*

Eine beliebige Anzahl von alphanumerischen Zeichen

[Zeichen]

Ein beliebiges der angegebenen Zeichen

[!Zeichen]

Ein beliebiges nicht angegebenes Zeichen

Rückgabewert Rückgabewert

Rückgabetyp

string$

mask$

TRUE

Integer

Entspricht der Suchmaske

Beliebig

FALSE

Integer

Entspricht nicht der Suchmaske

Beliebig

NULL

NULL

NULL

Beliebig

NULL

NULL

Beliebig

NULL

Beispiel Msgbox "ABC" Like "A*" Msgbox "A1A2B" Like "??#??"

'Liefert TRUE 'Liefert FALSE

Siehe auch StrCompare

24.5.141 Line Input# Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Liest eine Zeile aus einer sequentiellen Datei in eine String- oder Variant-Variable.

520

Die Befehls-Referenz

Syntax Line Input # fileNumber% , varName Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, welche bei der Open-Anweisung gewählt wurde.

-

-

-

Variable, in der die Textzeile gespeichert werden soll.

varName

Beispiel Open "C:\Autoexec.bat" For Input As #1 Line Input #1, Kette$ Msgbox Kette$ Close #1 ' Liest die erste Zeile der Autoexec.bat-Datei

Siehe auch Input#

24.5.142 MessageBox Art

Kategorie

Betriebssysteme

Notesversionen

Funktion Anweisung

Benutzerinteraktion

Alle

4/5

Beschreibung Zeigt eine Nachricht in einer Messagebox an und wartet auf Bestätigung vom Benutzer. Bei Aufruf als Funktion wird ein Wert entsprechend der Benutzerantwort zurückgeliefert. Syntax Function Syntax MessageBox ( message$ [ , [ buttons% + icon% + default% + mode% ] [ , boxTitle$ ] ] ) Statement Syntax MessageBox message$ [ , [ buttons% + icon% + default% + mode% ] [ , boxTitle$ ] ]

Die Befehle

521

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

message$

String

-

-

-

Die Nachricht, die angezeigt werden soll. Bis zu 512 Zeichen sind zulässig.

buttons%

Integer

-

+

0

Flag für die Auswahl der Buttons, die angezeigt werden.

icon%

Integer

-

+

64

Flag für die Auswahl des Symbols, welches angezeigt werden soll.

default%

Integer

-

+

0

Definiert, welcher Knopf per Voreinstellung ausgewählt ist.

mode%

Integer

-

+

0

Definiert die Art des Aufrufes der Messagebox. Entweder systemmodal oder applikationsmodal.

boxTitle$

String

-

+

""

Der Titel, der in der MessageBox angezeigt werden soll. Er kann bis zu 128 Zeichen lang sein.

Flag für die Auswahl der Knöpfe: Buttons

Konstante

Wert

OK

MB_OK

0

OK und Cancel

MB_OKCANCEL

1

Abort, Retry und Ignore

MB_ABORTRETRYIGNOR

2

Yes, No und Cancel

MB_YESNOCANCEL

3

Yes und No

MB_YESNO

4

Retry und Cancel

MB_RETRYCANCEL

5

Flag für die Auswahl des Symbols: Buttons

Konstante

Wert

Stop sign

MB_ICONSTOP

16

Question mark

MB_ICONQUESTION

32

Exclamation point

MB_ICONEXCLAMATION

48

Information

MB_ICONINFORMATION

64

Flag für die Auswahl des vorausgewählten Knopfes: Buttons

Konstante

Wert

First button

MB_DEFBUTTON1

0

Second button

MB_DEFBUTTON2

256

Third button

MB_DEFBUTTON3

512

522

Die Befehls-Referenz

Flag für die Auswahl der Aufrufart: Buttons

Konstante

Wert

Applikationsmodaler Aufruf. Anwendung wird angehalten.

MB_APPLMODAL

0

Systemmodaler Aufruf. System wird angehalten.

MB_SYSTEMMODAL

4096

Rückgabewert Rückgabewert

Rückgabetyp

Ausgewählter Knopf

1 (IDOK)

Integer

OK

2 (IDCANCEL)

Integer

Cancel

3 (IDABORT)

Integer

Abort

4 (IDRETRY)

Integer

Retry

5 (IDIGNORE)

Integer

Ignore

6 (IDYES)

Integer

Yes

7 (IDNO)

Integer

No

Beispiel A = Msgbox("Hallo", MB_YESNO + MB_ICONSTOP) If A = IDYES Then Msgbox "Es wurde Yes gewählt" Else Msgbox "Es wurde No gewählt" End If 'Es wird eine Messagebox angezeigt und ausgegeben, welcher Knopf 'gewählt wurde.

Siehe auch Print

24.5.143 Mid-Funktion Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Liefert einen Teilstring eines Strings. Syntax Mid[$] ( string$ , start% [ , length% ] )

Die Befehle

523

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Quellstring

start%

Integer

-

-

-

Anfangsposition

length%

Integer

-

-

-

Länge

Rückgabewert Rückgabewert

Rückgabetyp

Teilstring an der Startposition beginnend und die angegebene Länge lang

String / Variant

Beispiel Msgbox Mid$("Hallo", 3, 2)

'Liefert "ll"

Siehe auch Left, Len, Mid, Right

24.5.144 Mid Statement Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Zeichen

Alle

4/5

Beschreibung Ersetzt einen Teilstring. Syntax Mid[$] ( destination$, start% [ , length% ] ) = source% Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

destination$

String

-

-

Zielstring

start%

Integer

-

-

Anfangsposition für die Ersetzung

length%

Integer

+

-

Länge der Ersetzung

source$

String

-

-

Quellstring

524

Die Befehls-Referenz

Beschreibung In dem Zielstring wird ab der angegebenen Position der Inhalt durch den Inhalt vom Quellstring ersetzt. Sollte eine Länge angegeben sein, wird nur die entsprechende Anzahl von Zeichen ersetzt. Beispiel A$ = "Hallo" Mid(A$, 3, 2)= "tt" Msgbox A$

'Liefert "Hatto"

Siehe auch Left, Len, Mid, Right

24.5.145 MidB Beschreibung Diese Funktion verhält sich identisch mit Mid, nur dass die Positionen Byte-weise bestimmt werden. Diese Funktion sollte unter den aktuellen LotusScript-Versionen nicht mehr verwendet werden. Stattdessen sollte die Funktion Mid verwendet werden.

24.5.146 MidBP Beschreibung Diese Funktion verhält sich identisch wie MidB, nur dass die Berechnungen auf dem Zeichensatz des Betriebssystems beruhen.

24.5.147 MidC Beschreibung Diese Anweisung verhält sich identisch zu der Anweisung Mid, nur dass hier besondere fernöstliche Zeichensätze beachtet werden.

24.5.148 Minute Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert den Minutenanteil.

Die Befehle

525

Syntax Minute ( datevalue ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

datevalue

DATE

+

-

-

Ein numerischer oder Datumswert, dessen Minutenanteil ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

datevalue

Der Minutenanteil des übergebenen Wertes

Variant

sonst

NULL

NULL

NULL

Bemerkung Der Rückgabewert liegt zwischen 0 bis 59. Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Zeit interpretieren oder liegt außerhalb von 1.1.100 bis 31.12.9999

Type Mismatch

Datum liegt außerhalb von 1.1.100 und 31.12.9999

Beispiel Print Minute("10:12 31.01.1999") Print Minute(NULL)

'liefert 12 'liefert NULL

Siehe auch Day, Hour, Month, Now, Second, Today, Weekday, Year

24.5.149 MkDir Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Erstellt ein Verzeichnis.

526

Die Befehls-Referenz

Syntax MkDir path$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

path$

String

-

-

-

Verzeichnis, welches erstellt werden soll.

Fehler Fehlernr.

Fehlerbeschreibung

Situation

75

Path/file access

Das angegebene Verzeichnis kann nicht angelegt werden (z. B. existiert es schon)

Beispiel Mkdir "C:\TempDat"

'Erzeugt das Unterverzeichnis C:\TempDat

Siehe auch RmDir

24.5.150 Month Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert den Monatsanteil. Syntax Month ( datevalue ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

datevalue

DATE

+

-

-

Ein numerischer oder Datumswert, dessen Monatsanteil ermittelt werden soll.

Die Befehle

527

Rückgabewert Rückgabewert

Rückgabetyp

Ausdruck

Der Monatsanteil des übergebenen Wertes

Variant

Beliebiger Datumswert

NULL

NULL

NULL

Bemerkung Der Rückgabewert liegt zwischen 1 und 12. Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Datum interpretieren oder liegt außerhalb von 1.1.100 bis 31.12.9999

Type Mismatch

Datum liegt außerhalb von 1.1.100 und 31.12.9999

Beispiel Print Month(Datenumber(1999,2,1)) Print Month(NULL)

'liefert 2 'liefert NULL

Siehe auch Day, Hour, Minute, Now, Second, Today, Weekday, Year

24.5.151 Mod Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den Divisionsrest. Syntax value1& Mod value2& Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value1&

Long

+

-

-

Der Ausdruck, der dividiert werden soll.

value2&

Long

+

-

-

Der Ausdruck, durch den dividiert werden soll.

528

Die Befehls-Referenz

Bemerkung Statt ganzzahligen können auch Single- und Double-Werte für die Parameter eingesetzt werden. Rückgabewert Rückgabewert

Rückgabetyp

value1&

value2&

NULL

NULL

NULL

NULL

NULL

NULL

Beliebig numerisch

NULL

NULL

NULL

NULL

Beliebig numerisch

Der Rest der Divison von value1& / value2&, wobei vorher die Ausdrücke auf Ganzzahl gerundet werden

Long

Beliebig numerisch

Numerisch und <> 0

Fehler Nummer

Bezeichnung

Situation

11

Division by Zero

Wenn value2& den Wert 0 hat

Beispiel Print Print Print Print

4 Mod 2 5.2 Mod 3 0 Mod 1 1 Mod 0

'liefert 'liefert 'liefert 'liefert

0 2 0 Division by Zero-Fehler

24.5.152 MsgBox siehe MessageBox

24.5.153 Name Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Benennt eine Datei oder ein Verzeichnis um. Syntax Name oldName$ As newName$

Die Befehle

529

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

oldName$

String

-

-

-

Alter Datei- oder Verzeichnisname

newName$

String

-

-

-

Neuer Datei- oder Verzeichnisname

Fehler Nummer

Bezeichnung

Situation

53

File not found

Die Datei wurde nicht gefunden

Beispiel Name "C:\Temp.dat" As " C:\Temp2.dat"

Siehe auch FileCopy

24.5.154 Not Art

Kategorie

Betriebssysteme

Notesversionen

Operator

Logisch

Alle

4/5

Beschreibung Logische Negation Syntax Not value& Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Long

-

-

-

Ausdruck, der negiert werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Ausdruck

FALSE

TRUE

TRUE

FALSE

Binäre Negation

Numerischer Wert

530

Die Befehls-Referenz

Beispiel Print Not TRUE Print Not FALSE Print Not 13

'liefert False 'liefert True 'liefert -14

Siehe auch Or, And

24.5.155 Now Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert das aktuelle Datum und die aktuelle Zeit. Syntax Now [ () ] Parameter keine Rückgabewert Liefert das aktuelle Datum und die aktuelle Zeit als Variant-Datumswert zurück. Beispiel Msgbox Now()

'Gibt die aktuelle Zeit aus

Siehe auch Date, Day, Hour, Minute, Month, Second, Time, Today, Weekday, Year

24.5.156 Oct Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Octaldarstellung eines Zahlwertes.

Die Befehle

531

Syntax Oct[$] ( value& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Long

-

-

-

Ein beliebiger numerischer Ausdruck, von dem eine Octaldarstellung ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Octalcode des übergebenen Wertes als Zeichenkette. Nachkommastellen des übergebenen Ausdrucks werden vorher gerundet.

String/ Variant

Bemerkung Die maximale Länge der zurückgegebenen Zeichenkette beträgt 11 Stellen. Fehler Nummer

Bezeichnung

Situation

5

Overflow

Der Ausdruck liegt außerhalb des Wertebereichs

Beispiel Msgbox Oct(88)

'Liefert 130

Siehe auch Hex

24.5.157 On Error Art

Kategorie

Betriebssysteme

Notesversionen

Schleife

Programmausführung

Alle

4/5

Beschreibung Diese Anweisung definiert, wie Fehler in der aktuellen Umgebung behandelt werden. Syntax On Error [ errNumber% ] { Goto label | Resume Next | GoTo 0 }

532

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

errNumber%

Integer

-

+

-

Die Fehlernummer, die den Fehler spezifiziert, auf den reagiert werden soll. Wird keine Fehlernummer angegeben, wird auf jeden Fehler reagiert.

label

Label

-

-

-

Definiert ein Label, an dem die Programmausführung im Fehlerfall fortgesetzt werden soll.

Resume Next

Konstant

-

-

-

Definiert, dass im Fehlerfall die Programmausführung mit der nächsten Anweisung hinter der Stelle, wo der Fehler aufgetreten ist, fortgesetzt werden soll.

Goto 0

Konstant

-

-

-

Definiert, dass im Fehlerfall der Fehler an die übergeordnete Instanz abzugeben ist.

Beispiel On Error Resume Next B = 0 A = 1 / A Msgbox A+1

Liefert trotz des Fehlers Division by Zero den Wert 1. Siehe auch On...Goto, On...Gosub

24.5.158 On...GoSub Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Setzt die Programmausführung bedingt durch einen Wert in einem Unterprogramm fort. Syntax On value% GoSub label [ , label, ... ]

Die Befehle

533

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value%

Integer

-

-

-

Ein Wert, welcher bestimmt, mit dem wievielten Unterprogrammlabel in der angegebenen Liste die Programmausführung fortgesetzt werden soll. Bis zu 255 Labels sind zulässig.

label

Label

-

-

-

Eine Liste mit Unterprogrammlabels

Beispiel Sub MyProc(Index As Integer) On Index Gosub Label1, Label2 Exit Sub Label1: Msgbox "Wert 1"

'Liefert für Index=1 die 'Ausgabe Wert 1

Return Label2: Msgbox "Wert 2"

'Liefert für Index=2 die 'Ausgabe Wert 2

Return End Sub

Siehe auch On...GoTo

24.5.159 On...GoTo Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Setzt die Programmausführung, abhängig von dem angegebenen Index, an der Stelle eines Labels aus der Liste fort. Syntax On value% GoTo label [ , label ]...

534

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value%

Integer

-

-

-

Ein Wert, welcher bestimmt, mit dem wievielten Label in der angegebenen Liste die Programmausführung fortgesetzt werden soll. Bis zu 255 Labels sind zulässig.

label

Label

-

-

-

Eine komma-getrennte Liste mit Labels

Beispiel Sub MyProc(Index As Integer) On Index Goto Label1, Label2 Exit Sub Label1: Msgbox "Wert 1"

'Liefert für Index=1 die 'Ausgabe Wert1

Goto Ende Label2: Msgbox "Wert 2"

'Liefert für Index=2 die 'Ausgabe Wert2

Goto Ende Ende: End Sub

Siehe auch On...GoSub

24.5.160 On Event Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Bindet eine Prozedur oder Funktion an ein Ereignis eines Produktobjektes. Syntax On Event eventName From prodObject { Call handleName | Remove [ handleName ] }

Die Befehle

535

Parameter Null

Opt.

Default

Inhalt

eventName

Bezeichnung

-

-

-

Name des Ereignisses

prodObject

-

-

-

Name des Objektes

handleName

-

-

-

Name der Prozedur oder der Funktion, welche aufgerufen werden soll, wenn das Ereignis eintritt.

-

+

-

Mit diesem Zusatz werden die Zuordnungen, die gemacht wurden, wieder entfernt. Sollte bei Remove kein Handlename angegeben werden, werden alle Zuordnungen entfernt.

Remove

Datentyp

Konstante

Siehe auch On...Error

24.5.161 Option Base Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Voreinstellung

Alle

4/5

Beschreibung Setzt den Standardwert für die untere Grenze eines Arrays. Syntax Option Base base% Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

base%

Integer

-

-

-

Der Standardwert für die untere Arraygrenze. Entweder 0 oder 1.

Bemerkung Die Anweisung Option Base kann nur einmal in der Modulebene verwendet werden. Dabei muss die Anweisung vor allen Array-Deklarationen mit Dim sowie allen ReDim-Anweisungen stehen. Sollte die Anweisung nicht verwendet werden, so liegt der Standardwert für die untere Arraygrenze bei 0.

536

Die Befehls-Referenz

Beispiel Option Base 0

'Setzt die untere Grenze eines Arrays auf 0

Option Base 1

'Setzt die untere Grenze eines Arrays auf 1

Siehe auch Option Compare

24.5.162 Option Compare Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Voreinstellung

Alle

4/5

Beschreibung Definiert die Zeichenketten-Vergleichsmethode. Syntax Option Compare option [ , option ] Parameter Bezeichnung

Datentyp

option

Null

Opt.

Default

Inhalt

-

-

-

Optionen für das Vergleichsverfahren

Filgende Optionen stehen zur Verfügung: Bezeichnung

Bedeutung

Binary

Vergleich ist auf Byteebene. Keine andere Option kann zusätzlich gewählt werden.

Case

Groß-/Kleinschreibung wird beim Vergleich berücksichtigt.

Nocase

Groß-/Kleinschreibung wird beim Vergleich nicht berücksichtigt.

Pitch

Zwischen den zwei Ebenen des asiatischen Alphabets wird unterschieden

Nopitch

Zwischen den zwei Ebenen des asiatischen Alphabets wird nicht unterschieden

Bemerkung Sollte die Option Compare-Anweisung nicht angegeben werden, wird Case- und Pitch-Sensitive verglichen. Die Option Compare-Anweisung darf mehrmals auf Modulebene verwendet werden, sich dabei aber nicht widersprechen.

Die Befehle

537

Beispiel Option Compare Binary

'Setzt die Vergleichsmethode auf den 'Binärmodus

Option Compare Nocase

'Setzt die Vergleichsmethode auf das 'Ignorieren von Groß- und Kleinschreibung

Siehe auch Option Base, Option Declare

24.5.163 Option Declare Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Voreinstellung

Alle

4/5

Beschreibung Verbietet das implizite Deklarieren von Variablen. Syntax Option Declare | Explicit Parameter keine Bemerkung Option Declare kann einmal auf Modulebene spezifiziert werden. Sollte die Option Declare verwendet werden, so erzeugen nicht deklarierte Variablen einen Syntax Error. Beispiel Option Declare

'Definiert, dass ein explizites Deklarieren 'jeder Variable notwendig ist.

Siehe auch Option Base, Option Compare

24.5.164 Option Public Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Voreinstellung

Alle

4/5

538

Die Befehls-Referenz

Beschreibung Definiert, dass Deklarationen standardmäßig als Public angesehen werden. Syntax Option Public Parameter keine Bemerkung Option Public kann einmal auf Modulebene definiert werden. Die Option PublicAnweisung muss vor jeglicher Variablendeklaration stehen. Beispiel Option Public

'Definiert, dass alle Deklarationen 'standardmäßig Public sind

Siehe auch Option Compare, Option Base, Option Declare

24.5.165 Open Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Öffnet eine Datei und ermöglicht den Zugriff durch Lese- und Schreiboperationen. Syntax Open fileName$ [ For { Random | Input | Output | Append | Binary } ] [ Access { Read | Read Write | Write } ] [ { Shared | Lock Read | Lock Read Write | Lock Write } ] As [#]fileNumber% [ Len = length% ]

Die Befehle

539

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Der Dateiname der Datei

For Random

Konstante

-

+

Random

Die Datei wird als Randomdatei mit wahlfreiem Zugriff über Datensätze geöffnet

For Input

Konstante

-

+

Random

Die Datei wird als sequentielle Datei zum Lesen geöffnet

For Output

Konstante

-

+

Random

Die Datei wird als sequentielle Datei zum Schreiben geöffnet

For Append

Konstante

-

+

Random

Die Datei wird als sequentielle Datei zum Anhängen geöffnet

For Binary

Konstante

-

+

Random

Die Datei wird als Binärdatei für Ein- und Ausgaben geöffnet.

Access Read

Konstante

-

+

Read

Datei darf gelesen werden

Access Read Write

Konstante

-

+

Read

Datei darf geschrieben und gelesen werden

Access Write

Konstante

-

+

Read

Datei darf nur geschrieben werden

Shared

Konstante

-

+

Shared

Keine Sperrung der Datei

Lock Read

Konstante

-

+

Shared

Das Lesen der Datei von anderen Prozessen wird verhindert

Lock Read Write

Konstante

-

+

Shared

Das Lesen oder Schreiben der Datei von anderen Prozessen wird verhindert

Lock Write

Konstante

-

+

Shared

Das Schreiben der Datei von anderen Prozessen wird verhindert

fileNumber%

Integer

-

-

-

Dateinummer für die Datei. Mit dieser Dateinummer erfolgt der spätere Zugriff auf diese Datei mit Lotus Script-Anweisungen.

length%

Integer

-

+

128

Für Randomdateien die Datensatzlänge

Fehler Nummer

Bezeichnung

Situation

101

Unable to open file

Die Datei kann nicht geöffnet werden

Beispiel Open "C:\Autoexec.bat" For Input As #1 Close #1

'Öffnet die Datei 'Autoexec.bat 'und schließt diese wieder

540

Die Befehls-Referenz

Siehe auch Close

24.5.166 Or Art

Kategorie

Betriebssysteme

Notesversionen

Operator

Logisch

Alle

4/5

Beschreibung Logische/Binäre Oder-Operation Syntax value1& Or value2& Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value1&

Long

-

-

-

Beliebiger Ausdruck

value2&

Long

-

-

-

Beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

value1&

value2&

TRUE

Long

TRUE

TRUE

TRUE

Long

TRUE

FALSE

TRUE

Long

FALSE

TRUE

FALSE

Long

FALSE

FALSE

Binäre Oder-Operation

Long

Numerisch

Numerisch

Beispiel Msgbox TRUE Or FALSE Msgbox &b100 Or &b10

'Liefert True 'Liefert &b110 entspricht 6

Siehe auch And

24.5.167 Print Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Benutzerinteraktion

Alle

4/5

Die Befehle

541

Beschreibung Gibt Daten auf dem Bildschirm aus. Syntax Print [ expressions ] Parameter Bezeichnung

Datentyp

expressions

Null

Opt.

Default

Inhalt

-

-

-

Ausdrücke, die ausgegeben werden sollen. Sollten keine Ausdrücke angegeben werden, wird eine Leerzeile ausgegeben. Die Ausdrücke werden durch Komma, Semikolon oder Leerzeichen getrennt.

Beispiel Print "Hallo"

'Gibt Hallo aus

Siehe auch Print#

24.5.168 Print# Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Schreibt Daten in eine sequentielle Datei. Syntax: Print # fileNumber%, [ expressions ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, welche bei der Open-Anweisung gewählt wurde

-

-

-

Ausdrücke, welche geschrieben werden sollen. Die Ausdrücke werden durch Komma, Semikolon oder Leerzeichen getrennt.

expressions

542

Die Befehls-Referenz

Fehler Nummer

Bezeichnung

Situation

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\Daten.txt" For Output As #1 Print #1, "Hallo" Close #1

'Öffnet die Datei Daten.txt 'gibt den Text "Hallo" darin 'aus und schließt sie wieder

Siehe auch Print

24.5.169 Property Get / Property Set Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Objekt

Alle

4/5

Beschreibung Definiert eine Eigenschaft für ein Objekt, die mit der Property Set geschrieben und mit der Property Get gelesen werden kann. Syntax [ Static ] [ Public | Private ] Property { Get | Set } propertyName [ ( [ paramList ] ) ] [ As type ] [ statements ] End Property Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Static

Konstant

-

+

-

Deklariert die Eigenschaft als Statisch

Public

Konstant

-

+

-

Deklariert die Eigenschaft als Öffentlich

Private

Konstant

-

+

-

Deklariert die Eigenschaft als Privat

propertyName

-

-

-

Name der Eigenschaft

paramList

-

+

-

Parameterliste

type

-

+

-

Typ der Eigenschaft

Die Befehle

Bezeichnung

543

Datentyp

statments

Null

Opt.

Default

Inhalt

-

+

-

Die Anweisungen, welche für das Setzen und Auslesen der Eigenschaft ausgeführt werden.

Beispiel Property Get Attribut Attribut = Now() End Property Property Set Attribut Msgbox "Setzen nicht erlaubt" End Property Msgbox Attribut Attribut = 100

'Liefert die aktuelle Zeit 'Führt zur Ausgabe von "Setzen nicht erlaubt"

Siehe auch Sub, Function

24.5.170 Put Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Schreibt Daten in eine Binärdatei oder in eine Randomdatei. Syntax Put [#]fileNumber%, [ recordNumber% ] , varName Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, welche bei der Open-Anweisung gewählt wurde.

recordNumber%

Integer

-

+

-

Die Dateiposition, ab der geschrieben werden soll. In einer Randomdatei die Datensatznummer und in einer Binärdatei die Byteposition. Wenn kein Wert angegeben ist, wird an die aktuelle Position geschrieben.

544

Die Befehls-Referenz

Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

varName

Referenz

-

-

-

Variable mit den Daten, die geschrieben werden sollen. Ein dynamischer Array ist an dieser Stelle nicht zulässig.

Fehler Nummer

Bezeichnung

Situation

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\Daten.Dat" For Output As #1 Put #1, 1, A% Close #1 ' Schreibt den Inhalt von A% in die Datei Daten.Dat

Siehe auch Get

24.5.171 Randomize Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Mathe

Alle

4/5

Beschreibung Initialisiert den Zufallszahlengenerator. Wird die Zahl weggelassen, so wird der Wert von Timer verwendet. Syntax Randomize [ expression& ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression&

Double

-

Ja

aktuelle Uhrzeit

Ausdruck zum Initialisieren des Generators

Beispiel Randomize

Die Befehle

545

Siehe auch Rnd

24.5.172 ReDim Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Array

Alle

4/5

Beschreibung Dient der Deklaration von dynamischen Arrays. Syntax ReDim [ Preserve ] arrayName ( bounds ) [ As type ] [ , arrayName ( bounds ) [ As type ] ] ... Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Preserve

Konstant

-

+

-

Durch Angabe dieses Schlüsselwortes wird das Initialisieren der Elemente des Arrays verhindert.

arrayName

-

-

-

Name des Arrays.

bounds

-

+

-

Größe des Arrays.

type

-

+

-

Typ der Elemente des Arrays.

Beispiel Dim A() As Integer Redim A(1 To 3) As Integer A(1) = 1 A(2) = 2 A(3) = 3 Redim Preserve A(1 To 5) As Integer A(4) = 4 A(5) = 5 Forall X in A Print X ' Liefert die Zahlen von 1 bis 5 End Forall

Siehe auch Dim

546

Die Befehls-Referenz

24.5.173 Rem Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Kommentar

Alle

4/5

Beschreibung Die Anweisung leitet einen einzeiligen Kommentar ein. Syntax Rem text Parameter Bezeichnung

Datentyp

Null

Opt.

Default

text

Inhalt Eine Kommentarzeile mit beliebigem Format

Bemerkung Diese Anweisung dient der Kommentierung von Programmen. Alles, was hinter Rem folgt, wird von LotusScript ignoriert. Das Apostrophzeichen hat die gleiche Bedeutung wie die Rem-Anweisung. Der Unterschied besteht darin, dass Kommentare mit Apostroph auch hinter einer Anweisung in der gleichen Zeile stehen können. Kommentare, die mit Rem eingeleitet werden, müssen hingegen in einer eigenen Zeile stehen. Siehe auch %REM

24.5.174 Reset Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Schließt alle geöffneten Dateien. Syntax Reset Parameter keine

Die Befehle

547

Bemerkung Schließt alle geöffneten Dateien und schreibt vorher die ggf. gepufferten Daten in die Datei. Siehe auch Close

24.5.175 Resume Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Resume

Alle

4/5

Beschreibung Bestimmt, wie die Programmausführung nach dem Auftreten eines Fehlers fortgesetzt wird. Syntax Resume [ 0 | Next | label ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

0

Konstant

-

-

-

Setzt die Programmausführung mit der Programmzeile fort, in der der Fehler aufgetreten ist.

Next

Konstant

-

-

-

Setzt die Programmausführung mit der Anweisung fort, die der Fehler verursachenden Anweisung folgt.

label

Bezeichner

-

-

-

Die Programmausführung wird mit der durch das angegebene Label definierten Programmzeile fortgesetzt.

Bemerkung Durch die Ausführung von Resume werden die Inhalte von Err, Erl und Error gelöscht. Beispiel Resume 0 Resume Next

548

Die Befehls-Referenz

Siehe auch On...Error

24.5.176 Return Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Setzt die Programmausführung bei der Anweisung, die der On...GoSub- oder GoSub-Anweisung folgt, fort. Syntax Return Parameter keine Fehler Fehlernr.

Fehlerbeschreibung

Situation

3

Return without GoSub

Return ohne GoSub-Befehl

Beispiel Sub MyProc Gosub Label Exit Sub Label: Msgbox "Hallo" Return End Sub

Siehe auch GoSub, On...GoSub

24.5.177 Right Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Die Befehle

549

Beschreibung Liefert eine linke Teilzeichenkette. Syntax Right[$] ( string$, count% ) Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

string$

String

Quellzeichenkette

count%

Integer

Anzahl der gewünschten Zeichen

Rückgabewert Rückgabewert

Rückgabetyp

string$

count%

Die der Anzahl entsprechenden Anfangszeichen der Zeichenkette (von rechts gerechnet)

String / Variant

Beliebig

Numerisch

Die übergebene Zeichenkette

String / Variant

Beliebig

Größer als die Länge von string$

""

String / Variant

Beliebig

0

Beispiel Msgbox Right$("Hallo", 2)

'Liefert "lo"

Siehe auch Left, Len, Mid

24.5.178 RightBP Beschreibung Diese Funktion verhält sich identisch zu der Funktion RightB, nur dass hier der plattformspezifische Zeichensatz verwendet wird.

24.5.179 RightB Beschreibung Diese Funktion verhält sich identisch zu der Funktion Right, nur dass hier nach Bytes gerechnet wird.

550

Die Befehls-Referenz

Diese Funktion sollte unter den aktuellen LotusScript-Versionen nicht mehr verwendet werden. Stattdessen sollte die Funktion Right verwendet werden.

24.5.180 RightC Beschreibung Diese Anweisung verhält sich identisch zu der Anweisung Right, nur dass hier besondere fernöstliche Zeichensätze beachtet werden.

24.5.181 Round Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den gerundeten Wert Syntax Round ( value&, count% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Double

-

-

-

Numerischer Wert, welcher gerundet werden soll

count%

Integer

-

-

-

Numerischer Wert als Stellenanzahl, auf die zu runden ist

Rückgabewert Rückgabewert

Rückgabetyp

count%

Der auf die angegebenen Nachkommastellen gerundete Wert des übergebenen numerischen Ausdrucks

Double

numerischer Wert >= 0

Der auf 0 Nachkommastellen gerundete Wert des übergebenen numerischen Ausdrucks

Double

numerischer Wert <0

Fehler keine Beispiel Print Round(3.12345, 2)

'liefert 3.12

Die Befehle

551

Siehe auch CInt, Fix, Fraction, Int

24.5.182 RmDir Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Entfernt ein Verzeichnis aus einem Dateisystem. Syntax RmDir path$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

path$

String

-

-

-

Verzeichnis, welches gelöscht werden soll.

Fehler Fehlernr.

Fehlerbeschreibung

Situation

75

Path/file access

Das angegebene Verzeichnis existiert nicht oder ist nicht leer.

Beispiel RmDir "C:\DOS2"

'Löscht das Verzeichnis C:\DOS2

Siehe auch MkDir

24.5.183 Rnd Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert eine Zufallszahl zwischen 0 und 1.

552

Die Befehls-Referenz

Syntax Rnd [ ( expression ) ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

expression

Long

-

-

-

Ausdruck, der angibt, ob neu Zufallszahlen erzeugt werden sollen

Rückgabewert Rückgabewert

Rückgabetyp

Expression

Liefert die nächste Zufallszahl

Single

Positiv

Liefert dieselbe Zufallszahl wie beim letzten Aufruf

Single

0

Liefert die nächste Zufallszahl

Single

Negativ

Siehe auch Randomize

24.5.184 RSet Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Zeichen

Alle

4/5

Beschreibung Weist einer Stringvariablen eine Zeichenkette zu und richtet diese rechts aus. Syntax RSet stringVar = string$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

stringVar

Referenz

-

-

-

Name einer Variable vom Datentyp String oder Variant

string$

String

-

-

-

Die Zeichenkette, die zugewiesen werden soll

Beispiel A$ = "XX" Rset A$ = "Hallo" Msgbox A$

'Liefert "Ha"

Die Befehle

553

Siehe auch LSet

24.5.185 RTrim Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Entfernung aller abschließenden Leerzeichen. Syntax RTrim[$] ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Die Zeichenkette, welche rechts ausgerichtet werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Liefert die übergebene Zeichenkette ohne die führenden Leerzeichen

String / Variant

Beispiel Msgbox "-" + Rtrim("

Hallo

") + "-"

'Liefert "-

Hallo"

Siehe auch FullTrim, LSet, LTrim, RSet, Trim

24.5.186 Run Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

3

Beschreibung Diese alte LotusScript-Funktion wird nicht mehr unterstützt und sollte durch die Evaluate-Funktion ersetzt werden.

554

Die Befehls-Referenz

24.5.187 Second Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Sekundenanteil Syntax Second ( datevalue ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

datevalue

DATE

+

-

-

Ein Datums- oder numerischer Wert, dessen Sekundenanteil ermittelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

datevalue

Der Sekundenanteil der übergebenen Zeit. Der Rückgabewert liegt zwischen 0 und 59.

Integer

sonst

NULL

NULL

NULL

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Datum oder Zeit interpretieren oder liegt außerhalb von 1.1.100 bis 31.12.9999

Beispiel Print Second(Now()) Print Second(NULL)

'Liefert den Sekundenanteil der aktuellen Uhrzeit 'Liefert NULL

Siehe auch Day, Hour, Minute, Now, Weekday, Today, Year, Month

24.5.188 Seek-Funktion Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Die Befehle

555

Beschreibung Liefert die Position des Dateizeigers in einer Datei. Syntax Seek ( fileNumber% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, welche beim OPEN-Befehl gewählt wurde.

Rückgabewert Rückgabewert

Rückgabetyp

Dateiposition als positiver Wert. Bei Binärdateien die Byteposition und bei Randomdateien die Datensatznummer.

Long

Position liegt zwischen 1 und 2.0E31-1

Dateiposition als negativer Wert. Bei Binärdateien die Byteposition und bei Randomdateien die Datensatznummer.

Long

sonst

Fehler Nummer

Bezeichnung

Situation

99

File not open

Die Datei ist nicht geöffnet

Beispiel Open "C:\Daten.dat" For Output As #1 Print #1, A% Msgbox Seek(1) Close #1

'Liefert 6

Siehe auch Loc

24.5.189 Seek-Anweisung Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Setzt die Dateiposition in einer geöffneten Datei.

556

Die Befehls-Referenz

Syntax Seek [#] fileNumber% , position& Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, welche beim OPEN-Befehl gewählt wurde.

position&

Long

-

-

-

Die gewünschte neue Dateiposition. In einer Binärdatei oder einer sequentiellen Datei die Byte-Position. In einer Randomdatei die Datensatznummer.

Fehler Nummer

Bezeichnung

Situation

99

File not open

Die Datei ist nicht geöffnet

63

Bad record number

position& ist 0

Beispiel Open "C:\Daten.dat" For Output As #1 Seek #1, 6 Input #1, A% Msgbox A% Close #1

Liest den Integerwert ab der Byteposition 6 in eine Variable und gibt diese aus. Siehe auch Seek-Funktion, Loc

24.5.190 Select Case Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Führt einen Anweisungsblock aufgrund einer Auswahl mit Hilfe eines Ausdrucks aus.

Die Befehle

557

Syntax Select Case selectExpr [ Case condList [ statements ] ] [ Case condList [ statements ] ] ... [ Case Else [ statements ] ] End Select Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

selectExpr

-

-

-

Ausdruck, der bestimmt, mit welchem Anweisungsblock die Programmausführung fortgesetzt wird.

condList

-

-

-

Eine Liste von Ausdrücken. Sollte der Wert von selectExpr in dieser Liste vorhanden sein, wird der folgende Anweisungsblock ausgeführt.

statements

-

-

-

Anweisungsblock, welcher ausgeführt wird, wenn ein Wert der condList dem selectExpr entspricht.

Beispiel Select Case Index Case 1 Msgbox "A" Case 2 Msgbox "B" Case 3 Msgbox "C" Case Else Msgbox "?" End Select

' Für Index = 1 wird "A" ausgegeben. ' Für Index = 2 wird "B" ausgegeben. ' Für Index = 3 wird "C" ausgegeben. ' sonst wird "?" ausgegeben.

Gibt eine Meldung aus, die dem Index entspricht. Siehe auch On...GoTo, On...GoSub

558

Die Befehls-Referenz

24.5.191 SendKey Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Benutzerinteraktion

Nicht unter Mac und Unix

Nicht in Lotus Domino und Notes

Beschreibung Sendet Tastatur-Anschläge an das aktive Fenster. Syntax SendKeys string$ [ , processNow%] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Tasten, die gesendet werden sollen

processNow%

BOOL

-

+

FALSE

Wenn TRUE angegeben wird, wird mit der Programmausführung gewartet, bis alle Tasten von der Anwendung bearbeitet worden sind. Bei FALSE wird ohne zu warten mit der weiteren Programmausführung fortgefahren.

Siehe auch Shell

24.5.192 SetAttr Beschreibung siehe SetFileAttr

24.5.193 SetFileAttr Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Setzt die Attribute einer Datei. Es können mehrere Attribute mit einem Mal gesetzt werden, indem die Einzelwerte für die Attribute addiert werden. SetAttr ist ein Alias für SetFileAttr und kann genauso gut verwendet werden.

Die Befehle

559

Syntax SetFileAttr fileName$, attributes% Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Name der Datei

attributes%

Integer

-

-

-

Bitmaske der Attribute, welche gesetzt werden sollen

Die Werte für attributes%: attributes%

Konstante

Beschreibung

0

ATTR_NORMAL

Normal

1

ATTR_READONLY

Read-only

2

ATTR_HIDDEN

Hidden

4

ATTR_SYSTEM

System

32

ATTR_ARCHIVE

Geändert seit letzter Sicherung

Fehler Löst bei geöffneter Datei eine Fehlermeldung aus. Beispiel SetFileAttr "C:\Daten.dat", ATTR_READONLY

Setzt das Attribut der Datei Daten.dat auf Schreibgeschützt. Siehe auch GetFileAttr

24.5.194 Sgn Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Vorzeichen eines numerischen Ausdrucks. Syntax Sgn ( value& )

560

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Double

-

-

-

Der Ausdruck, dessen Vorzeichen ermittelt werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

value&

0

Integer

0

0

Integer

EMPTY

1

Integer

Numerisch und positiv

-1

Integer

Numerisch und negativ

Fehler Nummer

Bezeichnung

Situation

6

Overflow

Der Ausdruck liegt außerhalb des zulässigen Wertebereichs

Beispiel Print Print Print Print

Sgn(-3) Sgn(4) Sgn(0) Sgn(EMPTY)

'liefert 'liefert 'liefert 'liefert

–1 1 0 0

Siehe auch Abs

24.5.195 Shell Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Programmablauf

Alle

4/5

Beschreibung Startet ein anderes Programm. Syntax Shell ( program$ [ , style% ] )

Die Befehle

561

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

program$

String

-

-

-

Programmname des auszuführenden Programms

style%

Integer

-

+

-

Flag für das Aussehen des Fensters der neuen Anwendung

Die Werte für style% Style

Konstante

Beschreibung

1, 5 oder 9

Normal with focus

SHELL_NORMAL_FOCUS

2

Minimized with focus (default)

SHELL_MIN_FOCUS

3

Maximized with focus

SHELL_MAX_FOCUS

4 oder 8

Normal without focus

SHELL_NORMAL_NO_FOCUS

6 oder 7

Minimized without focus

SHELL_MIN_NO_FOCUS

Rückgabewert Rückgabewert

Rückgabetyp

System

taskID

Windows 3.1

33

Windows NT

33

OS/2

Bemerkung Nachdem der Start des externen Programms initiiert wurde, wird das LotusScriptProgramm weiter ausgeführt, ohne auf die externe Applikation zu warten. Fehler Nr.

Bezeichnung

Situation

53

File not found

Die angegebene Datei wurde nicht gefunden

Beispiel A = Shell("Notepad.exe")

Siehe auch SendKeys

'Ruft Notepad auf

562

Die Befehls-Referenz

24.5.196 Sin Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den Sinus eines numerischen Ausdrucks. Syntax Sin ( angle! ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

angle!

Single

-

-

-

Der Winkel, dessen Sinus ermittelt werden soll, im Bogenmaß

Rückgabewert Rückgabewert

Rückgabetyp

Sinus von angle!. Der Rückgabewert liegt innerhalb von –1 bis 1

Double

Beispiel Print Print Print Print

Sin(0) Sin(- Pi / 2) Sin( Pi / 2) Sin("A")

'liefert 'liefert 'liefert 'liefert

0 -1 1 einen Type Mismatch-Fehler

Siehe auch ACos, Tan, ATn, ATn2, Cos, ASin

24.5.197 Sleep Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Die Ausführung des Scripts wird für mindestens die angegebene Zeit unterbrochen. Syntax Sleep ( seconds# )

Die Befehle

563

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

seconds#

Double

-

-

-

Anzahl der Sekunden, die pausiert werden soll

Beispiel Sleep(100)

'Versetzt das aktuelle Programm für '100 Sekunden in Ruhezustand

Siehe auch Yield

24.5.198 Space Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Liefert die angegebene Anzahl von Leerzeichen in einer Zeichenkette zurück. Syntax Space[$] ( count& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

count&

Long

-

-

-

Anzahl der Leerzeichen

Rückgabewert Rückgabewert

Rückgabetyp

Zeichenkette mit der gewünschten Anzahl von Leerzeichen

String/ Variant

Beispiel Msgbox Len(Space(10))

Siehe auch Spc

'Liefert 10

564

Die Befehls-Referenz

24.5.199 Spc Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datei

Alle

4/5

Beschreibung Fügt an der aktuellen Position einer Print-Anweisung Leerzeichen ein. Syntax Spc ( count% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

count%

Integer

-

-

-

Anzahl der Leerzeichen (0 – 32000)

Beschreibung Auswirkung

Bedingung

Die Ausgabe wird mit der angegebenen Anzahl von Leerzeichen aufgefüllt

Die Zeilenbreite, die durch die Width-Anweisung definiert wurde, wird nicht erreicht.

Die Ausgabe wird mit Leerzeichen bis zum Zeilenende aufgefüllt. Danach wird eine Leerzeile eingefügt.

Die Zeilenbreite, die durch die Width-Anweisung definiert wurde, wird überschritten.

Siehe auch Space

24.5.200 Sqr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert die Quadratwurzel. Syntax Sqr ( value& )

Die Befehle

565

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Double

-

-

-

Ein positiver Ausdruck, dessen Quadratwurzel ermittelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

value&

Wurzel des numerischen Ausdrucks

Double

>0

Fehler

<= 0

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

Ausdruck ist negativ

Beispiel Print Print Print Print

Sqr(0) Sqr(1) Sqr(9) Sqr(-1)

'liefert 'liefert 'liefert 'liefert

0 1 3 einen Fehler

Siehe auch Exp

24.5.201 Stop Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Simuliert einen Breakpoint bei der Programmausführung. Syntax Stop Parameter Keine

566

Die Befehls-Referenz

Bemerkung Die Stop-Anweisung darf nur auf Prozedurenebene und nicht auf Modulebene verwendet werden.

24.5.202 Str Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichenkette

Alle

4/5

Beschreibung Wandelt einen numerischen Wert in eine Zeichenkette um. Syntax Str[$] ( value& ) Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

value&

Long

Nein

-

Beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

Der Textstring mit dem angegebenen Wert als Text.

String / Variant

Bemerkung Bei einer positiven Zahl wird eine Leerstelle vorangestellt. Beispiel Msgbox "-" + Str$(100)+ "-"

' Liefert "- 100-"

Siehe auch CStr, Format, Val

24.5.203 StrLeft Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Die Befehle

567

Beschreibung Durchsucht einen String nach einem gegebenen Teilstring von links nach rechts und liefert die Zeichenkette, welche links von dem gefundenen Teilstring steht. Syntax StrLeft ( string1$, string2$ [, compareFlag% [, occurrences# ] ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string1$

String

-

-

-

Zeichenkette, in der gesucht wird

string2$

String

-

-

-

Zeichenkette, die gesucht wird

compareFlag%

Integer

-

-

-

Vergleichsmethodenflag: 0 Case und Pitch Sensitive 1 Nur Pitch Sensitive 4 Nur Case Sensitive 5 Case und Pitch Insensitive

occurrences#

Long

-

-

-

Wert, der angibt, wie oft der gesuchte Teilstring gefunden werden soll, bevor ausgewertet werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Die Zeichenkette, die links von dem Auftreten von string2$ in string1$ steht.

String / Variant

Beispiel Msgbox Strleft("Hallo ich bin da", "ich")

Liefert "Hallo " Siehe auch StrLeftBack

24.5.204 StrLeftBack Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Durchsucht einen String nach einem gegebenen Teilstring von rechts nach links und liefert die Zeichenkette, welche links von dem gefundenen Teilstring steht.

568

Die Befehls-Referenz

Syntax StrleftBack ( string1$, string2$ [, compareFlag% [, occurrences# ] ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string1$

String

-

-

-

Zeichenkette, in der gesucht wird

string2$

String

-

-

-

Zeichenkette, die gesucht wird

compareFlag%

Integer

-

-

-

Vergleichsmethodenflag: 0 Case und Pitch Sensitive 1 Nur Pitch Sensitive 4 Nur Case Sensitive 5 Case und Pitch Insensitive

occurrences#

Long

-

-

-

Wert, der angibt, wie oft der gesuchte Teilstring gefunden werden soll, bevor ausgewertet werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Die Zeichenkette, die links von dem occurrences#-Auftreten von string2$ in string1$ steht.

String / Variant

Beispiel Msgbox Strleftback("Hallo ich bin da", "i")

Liefert "Hallo ich b" Siehe auch StrLeft

24.5.205 StrRight Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Durchsucht einen String nach einem gegebenen Teilstring von rechts nach links und liefert die Zeichenkette, welche rechts von dem gefundenen Teilstring steht. Syntax StrRight ( string1$, string2$ [, compareFlag% [, occurrences# ] ] )

Die Befehle

569

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string1$

String

-

-

-

Zeichenkette, in der gesucht wird

string2$

String

-

-

-

Zeichenkette, die gesucht wird

compareFlag%

Integer

-

-

-

Vergleichsmethodenflag: 0 Case und Pitch Sensitive 1 Nur Pitch Sensitive 4 Nur Case Sensitive 5 Case und Pitch Insensitive

occurrences#

Long

-

-

-

Wert, der angibt, wie oft der gesuchte Teilstring gefunden werden soll, bevor ausgewertet werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Die Zeichenkette, die rechts von dem occurrences#-Auftreten von string2$ in string1$ steht.

String / Variant

Beispiel Msgbox Strright("Hallo ich bin da", "ich")

'Liefert " bin da"

Siehe auch StrRightBack

24.5.206 StrRightBack Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Durchsucht einen String nach einem gegebenen Teilstring von links nach rechts und liefert die Zeichenkette, welche rechts von dem gefundenen Teilstring steht. Syntax StrRightBack ( string1$, string2$ [, compareFlag% [, occurrences# ] ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string1$

String

-

-

-

Zeichenkette, in der gesucht wird

570

Die Befehls-Referenz

Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string2$

String

-

-

-

Zeichenkette, die gesucht wird

compareFlag%

Integer

-

-

-

Vergleichsmethodenflag: 0 Case und Pitch Sensitive 1 Nur Pitch Sensitive 4 Nur Case Sensitive 5 Case und Pitch Insensitive

occurrences#

Long

-

-

-

Wert, der angibt, wie oft der gesuchte Teilstring gefunden werden soll, bevor ausgewertet werden soll.

Rückgabewert Rückgabewert

Rückgabetyp

Die Zeichenkette, die rechts von dem occurrences#-Auftreten von string2$ in string1$ steht.

String / Variant

Beispiel Msgbox Strrightback("Hallo ich bin da", "i")

'Liefert "n da"

Siehe auch StrRight

24.5.207 StrCompare Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Vergleicht zwei Zeichenketten. StrComp ist ein Alias für StrCompare, der genauso gut verwendet werden kann. Syntax StrCompare ( string1$ , string2$ [ , compareFlag% ] ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string1$

String

+

-

-

1. Zeichenkette

string2$

String

+

-

-

2. Zeichenkette

Die Befehle

571

Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

compareFlag%

Integer

-

-

-

Vergleichsmethodenflag: 0 Case und Pitch Sensitive 1 Nur Pitch Sensitive 4 Nur Case Sensitive 5 Case und Pitch Insensitive

Rückgabewert Rückgabewert

Rückgabetyp

NULL

Integer

string1$ oder string2$ ist NULL

-1

Integer

string1$ ist kleiner string2$

0

Integer

string1$ ist gleich string2$

1

Integer

string1$ ist größer string2$

Beispiel Msgbox Strcompare("Hallo", "hallo", 5)

'Liefert 0

Siehe auch Like

24.5.208 StrComp siehe StrCompare

24.5.209 StrConv Beschreibung Diese Anweisung wird bei der Konvertierung verschiedener fernöstlicher Zeichensätze verwendet.

24.5.210 String-Funktion Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Liefert eine Zeichenkette aus mehreren identischen Zeichen. Syntax String[$] ( length% , { code% | char$ } )

572

Die Befehls-Referenz

Parameter Bezeichnung

Datentyp

Null

Opt

Default

Inhalt

length%

Integer

-

-

-

Die gewünschte Anzahl der Zeichen

code%

Integer

-

-

-

Ein numerischer plattformabhängiger Zeichencode

char$

String

-

-

-

Eine Zeichenkette mit mindestens einem Zeichen

Rückgabewert Rückgabewert

Rückgabetyp

Liefert eine Zeichenkette mit dem angegebenen Zeichen in der angegebenen Anzahl.

String / Variant

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

Der Parameter Zeichen ist "" oder der Zeichencode liegt nicht innerhalb des zulässigen Bereiches

Beispiel Msgbox String(10, "A")

'Liefert "AAAAAAAAAA"

Siehe auch String, UChr, Uni

24.5.211 Sub Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Deklaration

Alle

4/5

Beschreibung Definiert eine Prozedur. Syntax [ Static ] [ Public | Private ] Sub subName [ ( [ argList ] ) ] [ statements ] End Sub

Die Befehle

573

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Static

Konstant

-

+

-

Definiert die Prozedur als Static

Public

Konstant

-

+

Public

Definiert die Prozedur als Public

Private

Konstant

-

+

Public

Definiert die Prozedur als Private

subName

-

-

-

Der Prozedurenname der neuen Prozedur

argList

-

+

-

Liste der Parameter

-

+

.

Der Anweisungsblock

statements

Programmblock

Beispiel Sub MyProc(A As Integer) Msgbox("Hallo") End Sub

Definiert die Prozedur MyProc Siehe auch Function

24.5.212 Tab Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Interaktion

Alle

4/5

Beschreibung Definiert, an welcher Spalte die nächste Ausgabe einer Print- oder Print#-Anweisung erfolgt. Syntax Tab ( column% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

column%

Integer

-

-

-

Ausdruck zwischen 1 und 32000, welcher angibt, wo die nächste Ausgabe erfolgt.

574

Die Befehls-Referenz

Beschreibung Neue Position

column%

column% Mod width

> width

1

<1

column% - aktuelle Position in der neuen Zeile

< aktuelle Position in der Print-Anweisung

column% - aktuelle Position in derselben Zeile

> aktuelle Position in der Print-Anweisung

Siehe auch Spc

24.5.213 Tan Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Mathe

Alle

4/5

Beschreibung Liefert den Tangens des numerischen Ausdrucks. Syntax Tan ( angel& ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

angel&

Long

+

-

-

Der Winkel im Bogenmaß, dessen Tangens berechnet werden soll

Rückgabewert Rückgabewert

Rückgabetyp

angel&

NULL

NULL

NULL

Der Tan des übergebenen Winkels

Double

sonst

Fehler keine Beispiel Print Tan(0) Print Tan(1000)

'liefert 0 'liefert ungefähr 1,4703

Die Befehle

575

Siehe auch ACos, ASin, ATn, ATn2, Cos, Sin

24.5.214 Time-Anweisung Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datum

nicht unter UNIX

4/5

Beschreibung Diese Anweisung setzt die aktuelle Uhrzeit. Syntax Time[$] = dateValue Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

dateValue

DATE

-

-

-

Zeit, welche als aktuelle Systemzeit gesetzt werden soll.

Siehe auch Time-Funktion

24.5.215 Time-Funktion Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert die aktuelle Systemuhrzeit. Syntax Time[$] Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

Liefert die auf Sekunden gerundete aktuelle Systemuhrzeit zurück.

DATE / String

576

Die Befehls-Referenz

Siehe auch Time-Anweisung

24.5.216 TimeNumber Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert eine durch Stunden, Minuten und Sekunden definierte Zeit. Syntax TimeNumber ( hour% , minute% , second% ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

hour%

Integer

-

-

-

Der Wert für die Stunden (0-23)

minute%

Integer

-

-

-

Der Wert für die Minuten (0-59)

second%

Integer

-

-

-

Der Wert für die Sekunden (0-59)

Rückgabewert Rückgabewert

Rückgabetyp

Die Uhrzeit, welche durch die Parameter bestimmt wird.

DATE

Beispiel Msgbox TimeNumber(18, 0, 0)

'Liefert 18:00.00 Uhr

Siehe auch CVDat

24.5.217 Timer Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert die Anzahl von Sekunden, die seit Mitternacht verstrichen sind.

Die Befehle

577

Syntax Timer Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

Die Sekunden, die seit Mitternacht vergangen sind

Single

Siehe auch TimeValue

24.5.218 TimeValue Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert die Uhrzeit, welche durch die übergebene Zeichenkette repräsentiert wird. Syntax TimeValue ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Zeichenkette mit Uhrzeit. Entweder im 12-Stunden-Format mit PM oder AM oder im 24-Stunden-Format.

Rückgabewert Rückgabewert

Rückgabetyp

Uhrzeit, die string$ entspricht

DATE

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der Inhalt von string$ kann nicht als Uhrzeit interpretiert werden.

578

Die Befehls-Referenz

Siehe auch TimeNumber

24.5.219 Today Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert das aktuelle Datum und die aktuelle Zeit. Syntax Today Parameter keine Rückgabewert Rückgabewert

Rückgabetyp

Liefert das aktuelle Datum und die aktuelle Zeit

DATE

Siehe auch Date, Minute, Second, Day, Month, Weekday, Hour, Now, Year

24.5.220 Trim Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Entfernt führende und abschließende Leerzeichen. Syntax Trim[$] ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Ein alphanumerischer Ausdruck

Die Befehle

579

Rückgabewert Rückgabewert

Rückgabetyp

string$ ohne führende oder abschließende Leerzeichen

Variant / String

Beispiel Msgbox Len(Trim("

Hallo

"))

'Liefert 5

Siehe auch RSet, LSet, RTrim, LTrim

24.5.221 Type Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datentypen

Alle

4/5

Beschreibung Definiert einen benutzerdefinierten Datentyp mit einer oder mehreren Elementen. Syntax [ Public | Private ] Type typeName member declarations End Type Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

Private

Konstant

-

+

Private

Definiert den Typ als Private

Public

Konstant

-

+

Private

typeName

-

member declarations

Beispiel Type Testtyp X As Integer Y As Integer End Type

Deklariert den Datentyp Testtyp

Definiert den Typ als Public Name des Typs Die Deklaration der Eigenschaften des Typs

580

Die Befehls-Referenz

Siehe auch Dim

24.5.222 TypeName Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentypen

Alle

4/5

Beschreibung Liefert den Namen des Datentyps eines Ausdrucks. Syntax TypeName ( expression ) Parameter Bezeichnung

Datentyp

expression

Null

Opt.

Default

Inhalt

-

-

-

Ausdruck, dessen Datentyp gesucht wird.

Rückgabewert Rückgabewert

Rückgabetyp

Expression

"EMPTY"

String

Wert ist EMPTY

"NULL"

String

Wert ist NULL

"Integer"

String

Typ ist Integer

"Long"

String

Typ ist Long

"Single"

String

Typ ist Single

"Double"

String

Typ ist Double

"Currency"

String

Typ ist Currency

"DATE"

String

Typ ist Date

"String"

String

Typ ist String

"OBJECT"

String

Inhalt ist NOTHING

"OBJECT"

String

Inhalt ist ein OLE-Objekt

"ERROR"

String

Inhalt ist OLE Error

"Integer"

String

Typ ist Integer

"UNKNOWN"

String

Inhalt ist V_UNKNOWN

Name der benutzerdefinierten Klasse

String

Typ ist eine benutzerdefinierte Klasse

"List" plus Listenname

String

Typ ist eine Liste

Elementtyp plus "()"

String

Typ ist ein Array

Die Befehle

581

Beispiel Msgbox Typename(A%)

'Liefert INTEGER

Siehe auch Type

24.5.223 UBound Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Array

Alle

4/5

Beschreibung Liefert die obere Indexgrenze eines Arrays. Syntax UBound ( arrayName [ , dimension% ] ) Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

arrayName

Array

-

-

Name einer Array-Variable

dimension%

Integer

Ja

1

Dimension, deren Obergrenze ermittelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

Liefert die obere Indexgrenze des Arrays für die angegebene Dimension.

Integer

Fehler Fehlernr.

Fehlerbeschreibung

Situation

200

Attempt to access uninitialized dynamic Array

Der angegebene Array ist ein dynamischer Array und ist nicht initialisiert worden.

Beispiel Dim A(5)As Integer Msgbox Ubound(A)

Siehe auch IsArray, LBound, Option Base

'Liefert 5

582

Die Befehls-Referenz

24.5.224 UCase Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Wandelt eine Zeichenkette in Großbuchstaben. Syntax UCase[$] ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Beliebiger Ausdruck, der in eine Zeichenkette gewandelt werden kann

Rückgabewert Rückgabewert

Rückgabetyp

string$ in Großbuchstaben

Variant / String

Beispiel Msgbox UCase("hallo")

'Liefert "HALLO"

Siehe auch LCase

24.5.225 UChr Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Liefert ein Zeichen gemäß dem Uni-Zeichencodesatz. Syntax UChr[$] ( value& )

Die Befehle

583

Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value&

Long

-

-

-

Ein numerischer Wert zwischen 0 und 65535

Rückgabewert Rückgabewert

Rückgabetyp

Unicode-Zeichen, das dem Wert von value& entspricht.

String / Variant

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

value& liegt außerhalb von 0 bis 65535

Beispiel Msgbox UChr(65)

'Liefert A

Siehe auch Chr, Uni, UString

24.5.226 Uni Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Der Unicode des ersten Zeichens der übergebenen Zeichenkette. Syntax Uni ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Zeichenkette mit mindestens einem Zeichen.

584

Die Befehls-Referenz

Rückgabewert Rückgabewert

Rückgabetyp

Ausdruck

UNICODE-Code des ersten Zeichens in der Zeichenkette

Long

Beliebig alphanumerisch

Fehler

""

Fehler Nummer

Bezeichnung

Situation

5

Illegal Function Call

Die Zeichenkette ist ein Leerstring

Beispiel Print Uni("Hallo") Print Uni("") Print Uni("1")

'liefert 72 'liefert einen Fehler 'liefert 49

Siehe auch UChar, UString

24.5.227 UnLock Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Thread

Alle

4/5

Beschreibung Gibt eine zuvor mit Lock gesperrte Datei frei. Syntax UnLock [#]fileNumber% [ , recordNumber% | { [ start ] To end } ] Parameter Bezeichnung

Datentyp

Opt.

Default

Inhalt

fileNumber

Die Dateinummer, welche bei der OpenAnweisung angegeben wurde

recordNumber

In einer Randomdatei die Nummer des Datensatzes, welcher entsperrt werden soll. In einer Binärdatei die Position des Bytes, welches entsperrt werden soll. In einer sequentiellen Datei wird dieser Parameter nicht berücksichtigt

Die Befehle

Bezeichnung

585

Datentyp

Opt.

Default

start

Inhalt In einer Randomdatei der Bereich von Datensätzen, die entsperrt werden sollen. In einer Binärdatei der Bereich der Bytes. Bei einer sequentiellen Datei wird immer die gesamte Datei ohne Rücksicht auf diesen Parameter entsperrt.

end

Bemerkung In Windows 3.1 muss das Programm SHARE.EXE gestartet worden sein, um einen gemeinsamen Zugriff auf eine Datei zu ermöglichen. Beispiel Open "C:\Daten.dat" For Input As #1 Lock #1 'Sperrt die Datei für andere Prozesse Unlock #1 'Entsperrt die Datei für andere Prozesse Close #1

Siehe auch Lock

24.5.228 Use Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmausführung

Alle

4/5

Beschreibung Lädt eine Script-Bibliothek und macht deren Ressourcen im Script-Code nutzbar. Syntax Use libName$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

libName$

String

-

-

-

Name der zu ladenden Bibliothek.

Bemerkung Die Use-Anweisung kann nur auf Modulebene verwendet werden.

586

Die Befehls-Referenz

Siehe auch UseLSX

24.5.229 UseLSX Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmausführung

Alle

4/5

Beschreibung Lädt eine LSX-Bibliothek und macht deren Ressourcen im Script-Code nutzbar. Syntax Uselsx libName$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

libName$

String

-

-

-

Name der zu ladenden Bibliothek.

Bemerkung Die Anweisung lädt eine LSX-Bibliothek. Verwendet werden kann die Anweisung auf Modulebene. Siehe auch Use

24.5.230 UString Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Zeichen

Alle

4/5

Beschreibung Liefert eine Zeichenkette mit mehreren identischen Zeichen, gemäß Unicode- oder Zeichen-Angabe. Syntax UString[$] ( length% , { code% | char$ } )

Die Befehle

587

Parameter Null

Opt.

Default

Inhalt

length%

Bezeichnung

Datentyp

-

-

-

Länge

code%

-

-

-

Ein Unicode-Ausdruck zwischen 0 und 65535

char$

-

-

-

Eine Zeichenkette mit mindestens einem Zeichen

Rückgabewert Liefert eine Zeichenkette mit dem angegebenen Zeichen in der angegebenen Anzahl. Beispiel Msgbox Ustring(5, "B")

'Liefert "BBBBB"

Siehe auch String, UChr, Uni

24.5.231 Val Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Umwandlung

Alle

4/5

Beschreibung Wandelt eine Zeichenkette in einen numerischen Ausdruck um. Syntax Val ( string$ ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

string$

String

-

-

-

Eine Zeichenkette, die als numerischer Wert interpretiert werden kann

Rückgabewert Rückgabewert

Rückgabetyp

Numerischer Wert von string$

Double

588

Die Befehls-Referenz

Beispiel Msgbox Val("10") + 1

'Liefert 11

Siehe auch Str

24.5.232 VarType Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datentyp

Alle

4/5

Beschreibung siehe DataType

24.5.233 Weekday Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Wochentag eines Datumswertes Syntax Weekday ( dateValue ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

dateValue

DATE

+

-

-

Ein Datums- oder numerischer Wert, dessen Wochentag ermittelt werden soll

Rückgabewert Rückgabewert

Rückgabetyp

datevalue

Der Wochentag des übergebenen Datums

Variant

Beliebiger Datumswert

NULL

NULL

NULL

Bemerkung Der Rückgabewert liegt zwischen 1 und 7.

Die Befehle

589

Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Datum interpretieren oder liegt außerhalb des Bereichs von 1.1.100 bis 31.12.9999

Beispiel Print Weekday("27.12.1999")

Liefert 2, also Montag (je nach Benutzereinstellung für den ersten Tag der Woche Print Weekday(NULL)

Liefert NULL Siehe auch Day, Hour, Minute, Now, Second, Today, Year, Month

24.5.234 While Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmablauf

Alle

4/5

Beschreibung Wiederholt die Ausführung eines Programmblocks, solange eine gegebene Bedingung wahr ist. Syntax While condition% [ statements ] Wend Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

condition%

BOOL

-

-

-

Die Bedingung, die bestimmt, ob der Programmblock ausgeführt wird.

statements

Programmblock

-

-

-

Der Programmblock, der wiederholt wird, solange die Bedingung TRUE ist.

590

Die Befehls-Referenz

Beispiel Index = 1 While Index < 10 Print Index Index = Index + 1 Wend

'Zählt von 1 bis 9

Siehe auch Loop

24.5.235 Width# Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Weist einer sequentiellen Datei eine Breite zu. Syntax Width # fileNumber% , width% Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Die Dateinummer, welche durch den Open-Befehl der Datei beim Öffnen zugewiesen wurde. Die Datei muss geöffnet sein. Das #-Zeichen muss angegeben werden.

width%

Integer

-

-

-

Ein ganzzahliger Wert im Bereich von 0 bis 255, welcher die Anzahl der Zeichen angibt, die in einer Zeile geschrieben werden, bevor eine neue Zeile begonnen wird. Eine 0 steht für unbegrenzte Zeilenlänge.

Bemerkung Wenn Zeichen in eine Datei geschrieben werden und die durch diesen Befehl gesetzte Anzahl von Zeichen in einer Zeile erreicht wird, wird das Schreiben in der Datei in einer neuen Zeile fortgesetzt. Diese Angabe wird nur von der Print#Anweisung beachtet, die Write-Anweisung ignoriert die Einstellung.

Die Befehle

591

Siehe auch Spc

24.5.236 Write# Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Datei

Alle

4/5

Beschreibung Schreibt Daten in eine sequentielle Datei. Syntax Write # fileNumber% [ , expression ] Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileNumber%

Integer

-

-

-

Dateinummer, die bei der OpenAnweisung gewählt wurde

expression

Variant

-

Ja

-

Liste der Ausdrücke, die in die Datei geschrieben werden sollen. Sollten keine Ausdrücke angegeben sein, wird eine Leerzeile geschrieben.

Beispiel Open "C:\Daten.dat" For Output As #1 Write #1, "Hallo" Close #1

'Öffnet die Datei Daten.dat 'schreibt das Wort "HallO"

Siehe auch Print#

24.5.237 With Art

Kategorie

Betriebssysteme

Notesversionen

Anweisung

Programmausführung

Alle

4/5

Beschreibung Dient zur verkürzten Schreibweise für den Zugriff auf Elemente einer Klasse.

592

Die Befehls-Referenz

Syntax With object [ statements ] End With Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

object

Referenz

-

-

-

Ein Ausdruck, dessen Wert einem benutzerdefinierten Objekt, einem Produktobjekt oder einem OLE-Objekt entspricht.

-

-

-

Ein Anweisungsblock

statements

Beschreibung Innerhalb des Anweisungsblocks kann bei der Referenz auf ein Mitglied des angegebenen Objektes der Objektname entfallen. Beispiel Class Punkt X As Integer Y As Integer End Type Sub Proc Dim A As Punkt With A Print X, Y End With End Sub

Gibt den Inhalt von X, Y des Punktes aus. Siehe auch Type

24.5.238 Xor Art

Kategorie

Betriebssysteme

Notesversionen

Operator

Logisch

Alle

4/5

Beschreibung Logische/Binäre XOR-Operation (»exklusives« Oder).

Die Befehle

593

Syntax value1& Xor value2& Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

value1&

Long

-

-

-

Beliebiger Ausdruck

value2&

Long

-

-

-

Beliebiger Ausdruck

Rückgabewert Rückgabewert

Rückgabetyp

value1&

value2&

FALSE

Long

TRUE

TRUE

TRUE

Long

TRUE

FALSE

TRUE

Long

FALSE

TRUE

FALSE

Long

FALSE

FALSE

Binäre Exklusiv-Oder-Operation

Long

Numerisch

Numerisch

Beispiel Msgbox TRUE Xor TRUE Msgbox &b101 Xor &b110

'Liefert FALSE 'Liefert &b011

Siehe auch And, Or

24.5.239 Year Art

Kategorie

Betriebssysteme

Notesversionen

Funktion

Datum

Alle

4/5

Beschreibung Liefert den Jahresanteil Syntax Year ( dateValue ) Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

dateValue

DATE

+

-

-

Ein Datums- oder numerischer Wert, dessen Jahresanteil ermittelt werden soll

594

Die Befehls-Referenz

Rückgabewert Rückgabewert

Rückgabetyp

datevalue

Der Jahresanteil des übergebenen Wertes

Variant

<> NULL

NULL

NULL

NULL

Bemerkung Der Rückgabewert liegt zwischen 100 und 9999. Fehler Fehlernr.

Fehlerbeschreibung

Situation

5

Illegal Function Call

Der übergebene Ausdruck lässt sich nicht als Datum interpretieren oder liegt außerhalb von 1.1.100 bis 31.12.9999

Type Mismatch

Der übergebene Datumswert liegt außerhalb von (1.1.100 bis 31.12.9999)

Beispiel Print Year(Now()) Print Year(NULL)

'liefert das Jahr des aktuellen Datums 'liefert NULL

Siehe auch Day, Hour, Minute, Now, Second, Today, Weekday, Month

24.5.240 Yield Art

Kategorie

Betriebssysteme

Notesversionen

Funktion Anweisung

Programmablauf

Nicht unter OS/2

4/5

Beschreibung Übergibt die Kontrolle während der Scriptausführung an das Betriebssystem. Syntax Yield Parameter keine Rückgabewert Die Funktion liefert eine 0 als Integer-Datentyp zurück.

Die Befehle

595

Bemerkung Die Yield-Funktion und -Anweisung übergibt die Kontrolle an das Betriebssystem, so dass es auf anstehende Ereignisse in seiner Warteschlange reagieren kann. Das Betriebssystem gibt die Kontrolle zurück, wenn alle anstehenden Ereignisse bearbeitet worden sind. Dieses schließt auch alle Ereignisse aufgrund einer SendKeyAnweisung ein. Die Yield-Funktion und -Anweisung kann innerhalb einer Prozedur, Funktion oder Klasse verwendet werden. Nicht zulässig ist sie dagegen auf Modulebene.

24.5.241 %If Art

Kategorie

Betriebssysteme

Notesversionen

Compileranweisung

Programmausführung

Alle

4/5

Beschreibung Diese Anweisung ermöglicht das bedingte Kompilieren von Code. Diese Anweisung muss in einer Textdatei stehen, die mittels der %Include-Anweisung beim Kompilieren geladen wird. Syntax %If productConst statements [ %ElseIf productConst statements ] [ %Else statements ] %End If Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

productConst

-

-

-

Eine Compilerkonstante, wie z. B. die Angabe der aktuellen Plattform

statements

-

-

-

Das Programmsegement, welches kompiliert werden soll, wenn die Kompilerkonstante definiert ist.

596

Die Befehls-Referenz

Einige Produktkonstanten Konstante

Bedeutung

WIN16

Windows mit 16 Bit API (Windows 3.1)

WIN32

Windows mit 32 Bit API (Windows NT oder Windows® 95)

WINNT

Windows NT

WIN95

Windows 95

WIN40

Windows 95 oder Windows NT 4.0

WINDOWS

Jede Windows-Plattform

HPUX

HP®/UNIX 9.X oder höher

SOLARIS

Sun™/OS 5.0 oder höher

UNIX

Sonstige UNIX-Art (HP_UX® oder Solaris®)

OS2

OS/2, Version 2.0 oder höher

MAC

Macintosh System 7

OLE

OLE-2 ist verfügbar

MAC68K

Macintosh Motorola® 68000 Version (entweder auf einem 68xxx Macintosh oder dem PowerPC™ ausgeführt)

MACPPC

Macintosh PowerPC Version

Beispiel %If WIN32 Msgbox "Programmblock für WIN32" %Else Msgbox "Programmblock wenn nicht Win32" %End If

Kompiliert einen der Programmblöcke in Abhängigkeit von der Plattform. Dieser Code muss in einer Textdatei stehen, die mittels der %Include-Anweisung beim Kompilieren geladen wird. Siehe auch If, %Include

24.5.242 %Include Art

Kategorie

Betriebssysteme

Notesversionen

Compileranweisung

Programmausführung

Alle

4/5

Beschreibung Fügt bei der Kompilierung eine Textdatei an der betreffenden Stelle ein. In dieser Textdatei kann weiterer Script-Code stehen. Lotus liefert für Notes mehrere .lss-

Die Befehle

597

Dateien mit, in denen Konstanten definiert sind und die mittels %Include geladen werden können (siehe die Tabelle am Ende dieser Befehlsreferenz). Syntax %Include fileName$ Parameter Bezeichnung

Datentyp

Null

Opt.

Default

Inhalt

fileName$

String

-

-

-

Name der Datei, die eingefügt werden soll.

Bemerkung Die angegebene Textdatei wird an der aktuellen Stelle eingefügt. Es sind bis zu 16 verschachtelte Include-Anweisungen möglich.

24.5.243 %Rem Art

Kategorie

Betriebssysteme

Notesversionen

Direktive

Programmausführung

Alle

4/5

Beschreibung Leitet einen mehrzeiligen Kommentar ein. Syntax %Rem text %End Rem Parameter Bezeichnung text

Datentyp

Null

Opt.

Default

Inhalt Eine beliebige Anzahl von Kommentarzeilen mit beliebigem Format

Bemerkung Diese Anweisung dient zur Kommentierung von Programmen. Alles, was zwischen %Rem und %End Rem steht, wird bei der Ausführung von LotusScript ignoriert. Siehe auch Rem

598

Die Befehls-Referenz

24.6 Datentypen Die Tabellen mit den Datentypen besitzen folgende Spalten: Datentyp: Diese Spalte beinhaltet den Namen des Datentyps, wie er z.B. bei der Dim Anweisung verwendet wird. Literal: Mit dem Literal kann eine implzite Deklaration der Variable erfolgen. Bereich: Der Bereich bestimmt bei einem numerischen Datentyp den Wertebereich. Größe: Die Größe gibt an, wie groß der benötigte Speicher für diesen Datentyp ist. Bound: Der Wert bei Bound gibt an, in welchem Raster die Speicherblöcke für den jeweiligen Datentyp reserviert werden.

24.6.1 Numerische Datentypen Datentypen

Literal

Bereich

Größe

Bound.

Integer

%

-32,768 bis 32,767

2 Byte

2 Byte

Long

#

2,147,483,648 bis 2,147,483,647

4 Byte

4 Byte

Singel

!

3.402823E+38 bis 3.402823E+38

4 Byte

4 Byte

Double

&

-1.7976931348623158+308 bis 1.7976931348623158+308

8 Byte

4 Byte

Currency

@

-922,337,203,685,477.5807 bis 922,337,203,685,477.5807

8 Byte

4 Byte

24.6.2 Alphanumerische Datentypen Datentypen

Beschreibung

Bound

Statische Strings

2 Byte pro Zeichen, die bei der Deklaration reserviert werden.

4 Byte

Dynamische Strings

2 Byte pro Zeichen, die während der Laufzeit reserviert werden.

4 Byte

24.6.3 Sonstige Datentypen Datentypen

Beschreibung

Array

Arraydatentyp mit statischer oder dynamischer Größe

List

Liste von Datenelementen

Variant

Kann alle Datentypen beinhalten

Object

Eine OLE Object-Referenz

Konstanten

599

24.6.4 Prefix der Zahlensysteme Prefix

Beschreibung

&B

Binärzahl z.B. &B0110 für die Zahl 6

&O

Octalzahl z.B. &O10 für die Zahl 8

&H

Hexadiezimal z.B. &H0FF für die Zahl 255

24.7 Konstanten Bezeichnung

Beschreibung

NULL

Definiert z. B. einen leeren Variant-Datentyp

EMPTY

Empty ist der Wert einer nicht initialisierten Variante

NOTHING

Definiert z. B. eine leere Referenz auf ein Objekt

TRUE

<> 0

FALSE

0

PI

Der Wert von Pi

24.8 Includedateien Bibliothek

Beschreibung

lsconst.lss

Datei mit globalen Konstanten

lserr.lss

Datei mit allen Lotus Notes-Fehlernummern

lsprcval.lss

Datei mit Konstanten für Threadinformation

lsxberr.lss

Datei mit Konstanten von LSX-Fehlern

lsxuierr.lss

Datei mit Konstanten von LSX-Fehlern

orgconst.lss

Konstanten für das Handling von Mail und anderen vorgefertigten Datenbanken

52

25

Die Anwendung aus dem Kapitel 17

Const nERR_MÄHER_PROBLEM = 10000

Class Grashalm Public Höhe As Integer Private Breite As Integer Sub New(in_AktuelleHöhe As Integer) Höhe = in_AktuelleHöhe Breite = 1 End Sub Sub Wachsen(in_GewachseneLänge As Integer) Höhe = Höhe + in_GewachseneLänge End Sub End Class

Class Rasenstück Länge As Integer Single As Integer Public Grashalme List As Grashalm Sub Schneiden(in_SchnittHöhe As Integer) Forall halm In Grashalme halm.Höhe = in_SchnittHöhe End Forall End Sub Private Zähler As Long Sub New(in_Länge As Single, in_Breite As Single, _ nMenge As Long,_nHöhe As Integer) Dim i% Dim Höhe As Integer Dim Breite As Integer Höhe = in_Länge

602

Die Anwendung aus dem Kapitel 17

Breite = in_Breite For i% = 1 To nMenge Dim oHalm As New Grashalm(nHöhe) Set Grashalme(i%) = oHalm Next End Sub Sub AddGrashalm (in_Grashalm As Grashalm) Zähler = Zähler + 1 Set Grashalme(Zähler) = in_Grashalm End Sub Function Höhe Höhe = grashalme(1).Höhe End Function End Class

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 nHatMesser As Integer Class Fahrgestell AnzahlRäder As Integer AnzahlAchsen As String Sub New(in_AnzahlRäder As Integer, in_AnzahlAchsen As Integer) AnzahlRäder = in_AnzahlRäder AnzahlAchsen = in_AnzahlAchsen End Sub

603

End Class Class Rasenmäher As Fahrgestell nSchnittbreite As Integer Schnitthöhe As Integer IstAmLaufen As Integer Sub New(in_Schnittbreite As Integer), Fahrgestell(4,2) IstAmLaufen = False nSchnittbreite = in_Schnittbreite End Sub Sub Print Print "Ich bin ein Rasenmäher." End Sub Property Get HatMesser As Integer HatMesser = nHatMesser End Property Function Anlassen 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 Property Get Schnittbreite As Integer Schnittbreite = nSchnittbreite End Property End Class

Class LuftkissenMäher As Fahrgestell nSchnittbreite As Integer Schnitthöhe As Integer IstAmLaufen As Integer Sub New(in_Schnittbreite As Integer), IstAmLaufen = False End Sub

Fahrgestell(0,0)

604

Die Anwendung aus dem Kapitel 17

End Class

Class Benzinmäher As Rasenmäher IstTankLeer As Integer Sub New(in_Schnittbreite As Integer), Rasenmäher (in_Schnittbreite) End Sub Sub AnStrippeZiehen IstAmLaufen = Not IstTankLeer End Sub Sub Print Print "Ich bin ein Luftkissenmäher." End Sub Function Anlassen If Not Rasenmäher..Anlassen Then Exit Function AnStrippeZiehen Anlassen = IstAmLaufen End Function End Class

Class Elektromäher As Rasenmäher nHatStrom As Integer IstKabelAnStrom As Integer Property Get IstKabelGebrochen As Integer IstKabelGebrochen = _ (IstKabelAnStrom And Not nHatStrom) End Property Sub Print Print "Ich bin ein Elektromäher." If IstKabelGebrochen Then Print "Mein Kabel ist gebrochen." Else Print "Mein Kabel ist OK." End If End Sub Property Set IstKabelGebrochen As Integer If IstKabelGebrochen Then

605

nHatStrom = False Else If IstKabelAnStrom Then nHatStrom = True End If End Property Sub New(in_Schnittbreite As Integer), Rasenmäher(in_Schnittbreite) nHatStrom = False IstKabelAnStrom = False End Sub Sub AnStrippeZiehen nHatStrom = False End Sub Function Anlassen Anlassen = Rasenmäher..Anlassen End Function End Class

Class Gärtner Name As String SchrittGeschwindigkeit As Single Schuhgröße As Integer MassEinheit As String Sprache As String Kleidung As String Sub New MassEinheit = "km/h" End Sub 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 oMäher.Anlassen If Not oMäher.IstAmLaufen Then Error nERR_MÄHER_PROBLEM, "Mäher läuft nicht" Dim i% For i% = 1 To nMähStrecke

606

Die Anwendung aus dem Kapitel 17

oMäher.Schneiden oRasen.Stücke(i%) Next End Sub End Class

Class DeutscherGärtner As Gärtner Sub New Sprache = "Deutsch" End Sub End Class

Class BritischerGärtner As Gärtner Sub New MassEinheit = "miles/h" Sprache = "Englisch" End Sub End Class

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

Stichwortverzeichnis XSymbole

%Include 179, 596 %REM...%ENDREM 46 & 75 ' 46 + 75 .. 206 = 75 => 75 > 75 >= 75 _ 46 {} 76 | 76

XA

Abbreviated 352 Abs 396 Abstract 350, 358 ACL 231, 246–247, 254, 287–289, 297, 327–329, 332

siehe auch: Zugriffskontrollliste 231, 287–289, 327–328, 332 ACLLEVEL_AUTHOR 288 ACLLEVEL_DEPOSITOR 288 ACLLEVEL_DESIGNER 288 ACLLEVEL_EDITOR 288 ACLLEVEL_MANAGER 288 ACLLEVEL_NOACCESS 288 ACLLEVEL_READER 288 Acos 396 Activate 151–152, 346 ActivateApp 397 ActiveX 145 AddCertifierToAddressbook 358 AddDatabase 372 AddDocument 344 AddEntry 354–355, 381 AddNewLine 360 AddPageBreak 360 Addr821 352 Addr822Comment1 352 Addr822Comment2 352 Addr822Comment3 352 Addr822LocalPart 352 Addr822Phrase 352 AddressBooks 363 AddRole 288, 327

AddRow 316–317, 320, 322, 385 AddServerToAddressbook 358 AddTab 360 AddUserProfile 358 AddUserToAddressbook 358 AdjustDay 338 AdjustHour 338 AdjustMinute 338 AdjustMonth 338 AdjustSecond 338 AdjustYear 338 ADMD 352 Administrator 129 Agenten 134, 137, 141, 332 CodeLock 138 CodeUnLock 138 CreateLock 138 DestroyLock 138 Hintergrund-Agent 137 Im Hintergrund keine FrontendKlassen 141 Informationen aus dem Web 236 Probleme bei ModulSchachtelung 185 Server-Agent 137 Sleep 139 Starten 237 Synchronisieren 137 Webagents 139 Web-Ereignis 236 AgentLog 134 Aktuelle Uhrzeit 83 Aktuelles Datum 82 Alarm 365, 372 Alias 354, 356 Aliases 346, 374 Alignment 361, 377 AllDocuments 267, 332, 343 AllEntries 262, 374, 380 ALOG4.NTF 132 AMString 347 And 398 Aneinanderhängen von Arrays 92, 97 Aneinanderhängen von Strings 75 Ansicht Spaltenformel 32, 38, 377 Textzeilen pro Zeile 36 Zeilenhöhe_anpassen 36

608

Anweisung 575 Append 157 AppendDocLink 360 AppendItemValue 27, 44, 270, 272–273, 342 AppendParagraphStyle 360 AppendRTItem 360 AppendStyle 360 AppendText 360 AppendToTextList 350 Array 89 Aneinanderhängen 92, 97 Deklaration 90 Dimensionen 89 Elemente löschen 91 Elementzugriff 91 Ersetzen von Elementen 92–93, 97 ForAll 114 Größenveränderung 90 Indizes bestimmen 92 Laufzeitverhalten 96–97 Option Base 94 Statische und dynamische A. 90 Suchen eines Eintrags 93 Überprüfung auf Arrayreferenz 95 Verbotene Zuweisung 95 Verbotene Zuweisung umgehen 97 ArrayAppend 92, 97, 399 ArrayGetIndex 93, 401 ArrayReplace 92–93, 97, 402 Asc 74, 403 ASin 404 Atn 405 Atn2 406 Aufrufe verfolgen 50 Ausnahme 119 Ausrichtung eines statischen Strings 69 Authors 340 AutoCommit 302, 383 AutoReload 367 Autorenfelder 291 AutoUpdate 374

XB

Backend-Klassen 231 BackgroundColor 374 Base 535 Beep 407 Benutzerinteraktion 34, 171, 176 DialogBox 172 Inputbox 172 MessageBox 171 PickList 173 Print 34, 171, 176

Stichwortverzeichnis

Statuszeile 34, 171, 176 Benutzerprofildokumente 281 Bin 408 Binär-Datei 162 Bold 362 Button 231

XC

C++-API 219 CacheLimit 311, 313, 385 CalendarDateTime 370 Call 408 CanCreateDocuments 328 CanCreateLSOrJavaAgent 328 CanCreatePersonalAgent 329 CanCreatePersonalFolder 329 CanCreateSharedFolder 329 CanDeleteDocuments 289, 329 Canonical 352 C-API 219 CaretCategory 370 Case 109 Case Else 109 Categories 253, 333 Categorize 367 CCur 410 CDat 80, 411 CDbl 412 CertifierIDFile 357 C-Funktionen 76 CGI-Variablen 139, 236 ChDir 168, 413 ChDrive 414 CheckAlarms 372 ChildCount 379 Chr 74, 415 CInt 416 Class 416 Class ... End Class 194 Clear 362, 367, 375 ClearAllTabs 361 ClearHistory 359 Click 174, 182, 274–278, 280, 326–327 CLng 418 Close 126, 131, 133–135, 158–159, 161–162, 165–166, 317, 351, 367, 385, 419

Close # 159, 161 CodeLock 138, 420 CodeLockCheck 421 CodeUnLock 138 CodeUnlock 422 CollapseAllSections 367 ColumnCount 374

Stichwortverzeichnis

ColumnIndentLevel 379 Columns 374, 377 ColumnValues 340, 379 Command 424 Comment 330, 354, 365 CommitOnDisconnect 302, 304, 383 CommitTransactions 303–304, 317, 320, 322, 383–384

Common 352 CommonOwner 330 CommonUserName 285, 363 Compact 254, 334 Compare 536 ComposeDocument 237, 372–373 ComputeWithForm 270, 342 Connection 309–310, 312, 321, 384 ConnectTo 303, 308–309, 313, 321, 383 Const 423 Contains 350 ConvertToZone 338 Copy 368 CopyAllItems 270, 342 CopyItem 270, 342 CopyItemToDocument 238, 350 CopyToDatabase 237, 271, 342 Cos 425 Count 242, 259, 266, 322, 343, 381 Country 352 Create 235–236, 246, 254, 332, 334 CreateACLEntry 288, 327 CreateCopy 246–247, 254, 332, 334 Created 277, 333, 340, 374 CreateDateRange 336, 364 CreateDateTime 337, 364 CreateDocument 148–149, 237–238, 272, 274–275, 278, 334, 339

CreateEntry 354–355 CreateFromTemplate 246–248, 250, 254, 332, 334

CreateLock 138, 425 CreateLog 350, 364 CreatE-MailDb 357 CreateName 351, 364 CreateNewsletter 279, 353, 364 CreateObject 368, 426 CreateOutline 334, 354 CreateReplica 247, 254, 332, 334 CreateReplyMessage 271, 342 CreateRichTextItem 271, 342, 359 CreateRichTextParagraphStyle 361, 364 CreateRichTextStyle 361, 364 CreateTimer 364 CreateViewNav 375, 382

609

CreateViewNavFrom 375, 382 CreateViewNavFrom-Category 375 CreateViewNavFrom-Children 375 CreateViewNavFrom-Descendants 375 CrossCertify 358 CSng 428 CStr 428 CurDir 168, 429 CurDrive 168, 430 Currency 60 CurrencyDigits 347 CurrencySymbol 347 CurrentAccessLevel 333 CurrentAgent 236, 330, 363 CurrentCalendarDateTime 371 CurrentDatabase 141, 148–149, 173–174, 248–249, 259, 266–267, 274, 277–278, 283–285, 323, 363, 371 CurrentDocument 149–153, 172, 174, 234–235, 237, 239–240, 371 CurrentField 367 CurrentRow 313–316, 385 CurrentView 371 Cut 368 CutoffDate 359 CutoffDelete 359 CutoffInterval 359 CVar 431 CVDate 432

XD

Database 356, 366 DataSourceName 302, 383 DataType 62, 434 Date 82, 432 DateFmt 377 Datei-Anhang erstellen 147 Datei-Anhang extrahieren 152 Datei-Anhang verwenden 149 Dateien Aktuelle Dateilänge 166 Aktuelle Position 165 Append 157 Attribute 166 Attribute von D. abfragen 169 Attribute von D. setzen 169 Binär-Datei 162 ChDir 168 Close # 159, 161 CurDir 168 CurDrive 168 Dateien löschen 168 Dateien umbenennen 168

610

Dateien kopieren 167 Dir 167 Eof 158 FileAttr 166 FileCopy 167 FileLen 166–167 FreeFile 159 Get # 161–162 GetFileAttr 169 Input # 157 Kill 168 Länge 166–167 Loc 165 Lock 164 Locking 163 Lof 166 Multitasking 163 Name 168 Open 160, 162, 164 Positionieren 157 Print # 157 Put # 160, 162 Random-Datei 159 Read 157 Read Write 157 Seek 157, 161, 163 Sequentielle Datei 156 Sequentielle Datei öffnen 156 SetFileAttr 169 Shared-Modus 163 UnLock 164 Datenbank (öffnen und) darauf zugreifen 248 (Replik) erstellen 247 anlegen 246 kopieren 247 leer anlegen 246 löschen 251 öffnen 249 von Gestaltungsschablone erstellen 247 Datenbankereignis (Beispiel) 252 Datenbankereignisse 252 Datenbank-Profildokument 282 Datenstrukturen Stack 224 Verkettete Liste 223 Datentyen Variant 222 Datentypen Array 89 Currency 60 Datumsformatierung 86

Stichwortverzeichnis

DefCur 60 DefDbl 59, 102 DefInt 56 DefLng 57 DefSng 58 Double 59, 102 Integer 56, 58, 196 List 99 Listen 102 Long 57, 102, 196 Numerische 56 Prüfung 82 Single 58 String 65 Umwandlung 74 Variant 61, 79, 90, 99, 102 Wandel numerischer Datentypen 61 Zeit- und Datumswerte 79 DateNumber 80, 347, 432 DateOnly 337 DateSep 347 DateSerial 434 DateTimeValue 349 DateValue 81, 435 Datum 82 Jahresanteil 84 Monatsanteil 84 Tagesanteil 85 Wochentag 85 Datumsformatierung 86 Day 85, 436 Debugger Aufrufe verfolgen 50 Bedingte Haltepunkte 47, 50, 53 Debug-Lauf starten 47 Eckige Klammern 51 Fortfahren 49 Globale Variable 184 Haltepunkt aktivieren/ deaktivieren 50 Haltepunkt löschen 50 Haltepunkt suchen 49 Haltepunkte 47, 49–51 In Funktion springen 49 Navigationsmöglichkeiten 51 Nichtprogrammierte Haltepunkte 49 Objekte betrachten 198 Programmierte Haltepunkte 50 Schritt ausführen 49 Schritt beenden 49 Schritt überspringen 49

Stichwortverzeichnis

Stoppen 49 Stoppen mit Script-Anweisung 50 Text mit Zeilenumbrüchen 52 Variablen-Gültigkeitsbereich 47, 51, 177

Werte zur Laufzeit verändern 47 DecimalSep 347 Declare external 437 Declare forward 439 DefCur 60, 440 DefDbl 59, 102, 441 DefInt 56, 442 DefLng 57, 443 DefSng 58, 444 DefStr 445 DefType 102 DefVar 446 DelayUpdates 253, 333 Delete 447 DeleteDocument 344, 368 DeleteEntry 381 DeleteIDOnServer 358 DeleteRole 327 DeleteRow 316–317, 386 DescendantCount 379 DeselectAll 368 DesignTemplateName 333 DestroyLock 138, 448 DialogBox 171–172, 372 DialogBoxCanceled 367 Dim 90, 449 Dir 167, 450 Disabled 359 DisableRole 330 Disconnect 303, 383 DLL-Dateien 143 Administrationsprobleme 144 Kompatibilitätsprobleme 144 LSX-Klassen 146 Do_..._Loop 113 Do_..._Until 112 Do_..._While 111–112 Document 149–153, 172–174, 234–235, 237, 239–240, 262, 356, 367, 379

DocumentContext 139, 236, 363 Documents 366, 370 Dokumente finden 256 Domino-Klassen Ableitung 243 Agenten starten 237 Backend-Dokument 234 Containerklassen 256 Datenbank anlegen 246

611

Datenbank öffnen 239 Dokument versenden 238 Dokumente finden 238, 256 Dokumente über Ansicht finden 239 Extended Syntax 273–274 Frontend-Dokument 234 Geöffnete Datenbank finden 239 Neue Funktionalitäten unter Domino R5 242 NotesACL 287 NotesACLEntry 287 NotesDatabase 267 NotesDocument 269, 272 NotesDocumentCollection 256 NotesNewsLetter 279 NotesSession 235, 275 NotesUIWorkspace 234 NotesView 262 NotesViewEntry 262 NotesViewEntryCollection 262 DoScore 353 DoSubject 353 Double 59, 102 DoVerb 346 Dynamische Zeichenkette 66

XE

EditDocument 372–373 EditMode 367 Editor Kommentare 46 Tabulator 46 Zeilenumbrüche 46 EditProfile 372 EffectiveUserName 363 Effects 362 Eigenschaften 195 Einfache Aktion 44–45 Einstellungen 282 Elektronisch unterschreiben 297 EMBED_ATTACHMENT 279 EMBED_OBJECT 279 EMBED_OBJECTLINK 279 EmbeddedObjects 150, 269, 340, 360 EmbedObject 148–149, 153, 278–279, 345, 360 Empty 61 EnableAlarms 372 Enabled 365 EnableFolder 254, 335 EnableRole 289, 330 Encrypt 271, 295–296, 342, 349 EncryptionKeys 296, 340

612

Stichwortverzeichnis

EncryptOnSend 269, 295, 340 End 453 EndDateTime 337 Endlosschleife 113 Entering 326 EntryClass 356 Entwicklungsumgebung 41, 119, 198 Anzeige der Objektstruktur 43 Codestück übernehmen 44 Debugger 47–49, 51–53, 182–184, 198– 199, 203, 208, 213

Domino-Klassen 25, 44, 137, 219, 231, 245, 257, 269

Domino-spezifische Erweiterunge 44 Doppelklick auf Codestück 44 Einfache Aktionen 44–45 Ereignisse 44, 129–130, 232 Eventhandler 43, 180, 186, 251, 326, 365, 367, 370

Events 44, 251–252, 326–327, 365–367, 369–370

Farbdarstellung 45 Fehler-Kennzeichnung 45 Formatierung 45 Formelsprache 44–45, 177, 373 Gestaltungselemente 42, 246, 249 Hilfe 44 Initialize 43, 139, 177–180, 186, 198, 210, 234

Java 25, 44, 219 JavaScript 25, 44 Kommentar-Darstellung 45–46 Konstanten-Darstellung 45 kontextsensitive Referenz 43 Kugel-Symbol 44 Lesezeichen 42–43 LotusScript-Sprache 44 LSX-Module 44 Methods 44 Navigator 42–43, 232, 326, 366, 382 Notes-Systembefehle 44 Programmierbereich 44 Programmierfenster 42–45 Properties 44, 207, 209, 212, 243 Quadrat-Symbol 44 Raute-Symbol 44 Schlüsselwort-Darstellung 45, 69 Schriftrollen-Symbol 44 Schrifttyp 45 Symbole 43–44, 75 Syntax 44 Terminate 43, 139, 178–180, 186

Würfel-Symbol 44 Environ 454 EOF 460 Eof 158 Erase 91, 103, 455 Erl 124, 456 Err 124 Err-Funktion 457 Err Statement 458 Error 124 Error Anweisung 459 Ersetzen von Arrayelementen 92–93, 97 Evaluate 463 Event 534 Events Click 174, 182, 274–278, 280, 326–327 Entering 326 Exiting 326 ObjectExecute 326 ExecProcedure 314, 317, 386 Execute 312–314, 318, 320–321, 386, 463 Exit 462 Exit Do 116 Exit For 116 Exit Forall 116 Exit Function 116 Exit Property 116 Exit Sub 116 Exit Sub/Exit Function 121 Exiting 326 Exp 461 ExpandAllSections 368 Expiration 357 Extended Syntax 272–274 Externe Programme 143 ExtractFile 152–153, 346

XF

Farbdarstellung 45 Fehler Kompilierfehler 47, 119 Laufzeitfehler 119 Laufzeitfehler abfangen 119 Overflow-Fehler 57–60, 121 Type Mismatch-Fehler 57–61, 93 Fehlerbehandlung Analyse von Laufzeitfehlern 129 Close-Statement 126 effektive Ausnahmebehandlung 126 Erl 124 Err 124 Error 124

Stichwortverzeichnis

Exit Sub/Exit Function 121 Fehlernummer 120 Fehlerroutine 124 Fehlertyp bestimmen 120 Gültigkeitsbereich 121 Label 121 On_Error_GoTo 119 On_Error_GoTo_0 119 On_Error_Resume_Next 119 OnError 119 Ressourcen freigeben 125 Resume 0 124 Resume Label 124 Resume next 124 Weiterer Fehler in der F. 123 Fehler-Kennzeichnung 45 Fehlermeldungen 47, 52, 58, 120, 122–125, 129–130, 132, 135, 183, 201, 222, 250, 301, 303, 310, 318, 383–386 Fehlerquellen einkreisen 53 Fehlerroutine 124 FetchBatchSize 311–313, 385 Field 231 FieldAppendText 368 FieldClear 368 FieldContains 368 FieldExpectedDataType 315, 318, 386 FieldGetText 368 FieldHelp 367 FieldID 318, 386 FieldInfo 318, 386 FieldName 318, 386 FieldNativeDataType 318, 386 Fields 346 FieldSetText 234, 368 FieldSize 318, 386 FileAttr 166, 464 FileCopy 167, 466 FileDateTime 467 FileLen 166–167, 467 FileName 333 FilePath 174, 333 FileSize 151, 345 FindFreeTimeDialog 368 FindFreeTimeDialogEx 368 FindString 368 FirstLineLeftMargin 361 FirstRow 314, 316, 318, 386 FitBelowFields 345 FitToWindow 345 Fix 468 Folder 372 FolderReferences 340

613

FolderReferencesEnabled 253, 333 FontColor 377 FontFace 377 FontPointSize 377 FontSize 362 FontStyle 377 For 471 For_..._Next 110 ForAll 114, 150, 472 Forall 103 Format 473 FormatDocument 279–280, 353 FormatMsgWithDoclinks 280, 353–354 Forms 333, 346 Formula 356, 377 FormUsers 346 Forward 368 Fraction 469 FrameText 356 FreeFile 159, 470 FreeTimeSearch 364 FTDomainSearch 268, 270, 335, 342 FTSearch 257–258, 262, 266–268, 270, 335–336, 342, 344, 376, 381

FTSearchScore 269, 340, 380 FullTrim 474 Function 181, 475 Funktion 458, 575 Funktionale Analyse 190 Funktionale Zerlegung 188 Funktionen 181, 287, 293, 327, 330 Fußgesteuerte Schleifen 112

XG

Generation 352, 379 Get 476 Get # 161–162 Get EmbeddedObject 360 GetAgent 141, 237, 330, 335 GetAllDocumentsByKey 263, 266, 323, 376 GetAllEntriesByKey 263, 376, 380 GetAttachment 149, 271, 342 GetChild 263, 376, 382 GetDatabase 141, 364 GetDbDirectory 339, 364 GetDocument 257, 344 GetDocumentByID 268, 335 GetDocumentByKey 263, 275–276, 376 GetDocumentByUNID 268, 335 GetDocumentByURL 268, 335 GetEntry 289, 328, 381–382 GetEntryByKey 263, 376, 379 GetEnvironmentString 364

614

GetEnvironmentValue 365 GetError 303, 305, 310, 318, 383, 385–386 GetErrorMessage 303, 305, 310, 318, 383, 385– 386

GetExtendedError-Message 303, 310, 318, 384–386

GetFileAttr 169, 477–478 GetFirst 354–355, 382 GetFirstDatabase 339 GetFirstDocument 173, 241–242, 257, 277, 284, 344, 376, 382

GetFirstEntry 328, 381 GetFirstltem 271, 342 GetForm 335, 346 GetFormattedText 360 GetIDFromServer 358 GetItemValue 238, 271, 283–285, 342 GetLast 354, 382 GetLastDocument 257, 344, 376, 382 GetLastEntry 381 GetListOfTunes 372 GetLSDOMasterRevision 302, 383 GetNext 354, 382 GetNextCategory 382 GetNextDatabase 339 GetNextDocument 173, 241–242, 257–258, 269, 284, 344, 376, 382

GetNextEntry 328, 381 GetNextSibling 355, 376, 382 GetNth 382 GetNthDocument 242, 257, 322, 344, 376 GetNthEntry 381 GetObject 215–216, 368, 479 GetOutline 335, 354 GetParameter 318, 386 GetParameterName 318, 386 GetParent 355, 382 GetParentDocument 263, 376 GetPos 382 GetPosition 380 GetPrev 355, 382 GetPrevCategory 383 GetPrevDocument 257–258, 344, 376, 383 GetPrevEntry 381 GetPrevSibling 263, 355, 376, 383 GetProfileDocCollection 268, 281, 284, 335 GetProfileDocument 268, 281–285, 335 GetRowStatus 318, 386 GetSelectedText 368 GetThreadInfo 480 GetURLHeaderInfo 335 GetUserInfo 358 GetValue 315, 318, 387

Stichwortverzeichnis

GetView 173, 235, 241, 266–267, 275–276, 323, 335, 373

Given 352 Globale Variable 184 GMTTime 337 GoSub 115–116, 481, 532 GoTo 107, 114, 482, 533 GotoBottom 368 GotoField 368 GotoNextField 368 GotoPrevField 368 GotoTop 369 GrantAccess 254, 335 Groß-/Kleinschreibung umwandeln 69 Grünes Häkchen 52 Gültigkeitsbereich 177

XH

Haltepunkte siehe auch Debugger 47, 49–51 Harter Absturz 52 HasChildren 356 HasEmbedded 269, 340 HasItem 271, 342 HasRowChanged 317–318, 387 HasRunSinceModified 331 HeaderAlignment 377 HeaderLines 374 Heute 83 Hex 483 HiddenChars 367 Hilfe 44, 325 Hintereinanderhängen von Befehlen 46 Hintergrund-Agent 137, 185 HorzScrollBar 367 Hour 85, 483

XI

IDE 41, 53, 119, 198, 330, 346 IDType 357 If Goto 484 If_..._Goto 108 If_..._Then_..._Else 108, 485 IgnoreDeletes 359 IgnoreDestDeletes 359 ImagesText 356 IMESetMode 489 IMEStatus 488 Import 369 IndentLevel 380 Initialize 177, 180 Initials 352 InPreviewPane 367

Stichwortverzeichnis

Input 492 Input # 157, 491 InputB 493 InputBox 172, 490 InsertText 369 InStr 73, 493 InstrB 73 InstrBP 73 InstrC 73 Int 495 Integer 56, 58, 196 InterLineSpacing 361 International 347, 363 InternetLevel 327 Interval 365 Iris 53 IsA 496 IsAccentSensitiveSort 377 IsAdminReaderAuthor 329 IsAdminServer 329 IsArray 95, 497 IsAuthors 292, 349 IsBeginOfData 315, 319, 387 IsCalendar 374 IsCaseSensitiveSort 377 IsCategorized 374 IsCategory 377, 380 IsConflict 374, 380 IsConnected 303–304, 384 IsCurrencySpace 347 IsCurrencySuffix 347 IsCurrencyZero 347 IsDate 82, 498 IsDateDMY 347 IsDateMDY 347 IsDefaultView 374 IsDefined 498 IsDeleted 340 IsDirectoryCatalog 333 IsDocument 380 IsDST 337, 348 IsElement 104, 499 IsEmpty 500 IsEnabled 331 IsEncrypted 296, 349 IsEndOfData 315, 319, 387 IsField 377 IsFolder 374 IsFormula 378 IsFTIndexed 333 IsGroup 329 IsHidden 356, 378 IsHideDetail 378

615

IsHierarchical 352, 374 IsIcon 378 IsInThisDb 356 IsList 104, 501 IsModified 374 IsMultiDbSearch 333 IsNames 349 IsNewDoc 367 IsNewNote 340 IsNorthAmerican 357 IsNotesAgent 331 IsNull 502 IsNumeric 502 IsObject 503 IsOnServer 363 IsOpen 50, 249–250, 253–254, 333 IsPerson 329 IsPrivate 356, 374 IsPrivateAddressBook 333 IsProfile 269, 340 IsProtected 349 IsPublic 331 IsPublicAddressBook 333 IsPublicReader 329 IsPublicWriter 329 IsReaders 292, 349 IsResize 378 IsResortAscending 378 IsResortDescending 378 IsResortToView 378 IsResponse 269, 340, 378 IsResultSetAvailable 314, 319, 321, 387 IsRoleEnabled 330 IsScalar 504 IsSecondaryResort 378 IsSecondaryResortDescending 378 IsServer 329 IsShowTwistie 378 IsSigned 340, 349 IsSortDescending 378 IsSorted 343, 378 IsSubForm 346 IsSummery 349 IsSupported 303, 305, 384 IsTime24Hour 348 IsTotal 380 IsUlDocOpen 340 IsUnknown 505 IsValid 340, 380 IsValidDate 337 IsValueAltered 319, 387 IsValueNull 319, 387 IsWebAgent 331

616

Stichwortverzeichnis

IsYMD 348 Italic 362 ItemName 378 Items 132, 150, 238, 269–273, 275–279, 292, 296, 340, 342–343, 348–349

XJ

Jahresanteil 84 Java 210, 219

XK

Key 270, 341 Keyword 352 Kill 168, 506 Klammern Debugger 51 Klasse 193–194 Kommentare 46 Kompilieren 47 Konkatenationsoperatoren 75 Konstanten Zeichenketten 76 Konstruktor 197 Kontaktmanagement 29 Adress-Datenbank 30 Firmen-Maske 34 Konfigurations-Datenbank 29, 34– 35

Konfigurations-Maske 36 Kontakt-Datenbank 37–38, 225–227, 259–261, 266

Personen-Dokumente 33–34 Spaltenformel 32, 38, 377 Kopfgesteuerte Schleifen 111–112 Kurzreferenz 325 Gebrauch der K. 325 Parameter 325

XL

Label 31, 107–108, 114–115, 119, 121–122, 124, 356

Language 352 LastAccessed 341 LastExitStatus 363 LastFTIndexed 333 LastModified 333, 341, 349, 374 LastRow 314, 316, 319, 387 LastRun 331, 363 Laufzeitfehler abfangen 119 Lbound 92, 506 LCase 69, 507 Leerstring 62 Leerzeichen entfernen 69

Leerzeichen-Kette 73 Left 67, 508 LeftB 67 LeftBP 67 LeftC 67 LeftMargin 361 Len 67, 510 LenB 67, 511 LenBP 67 LenC 67 Leserfelder 291 Let 512 Level 290, 329, 356 Like 75, 518 Line Input# 519 List 99 ListDataSources 303, 384 Listen 99 Datentypen 102 DefType 102 Deklaration 99 Elemente löschen 103 Element-Zugriff 100 Forall 103 IsElement 104 IsList 104 ListTables 303, 309, 321, 384 ListTag 100, 104, 512 Löschen 103 Option Compare 100 Schlüssel 100 Wert-Auslesen 101 Wertzuweisung 101 ListFields 303, 384 ListProcedures 303, 384 ListSep 378 LOC 513 Loc 165 LocalTime 337–338 LocateRow 315–316, 319–320, 322, 387 Lock 164, 514 Locking 163 LOF 515 Lof 166 Log 516 LogAction 135, 350, 351 LogError 135, 350, 351 LogEvent 351 Log-Level 130 Long 57, 102, 196 LSet 69, 517 LSGMTTime 337 LSLocalTime 337

Stichwortverzeichnis

LSX-Klassen 146, 243 LSX-Technologie 243 LTrim 69, 518

XM

MakeResponse 271, 342 Managers 333 Manipulation der Variablenwerte 51 Maske 273 MaxLevel 382 MaxRows 311–313, 385 MaxSize 333 MessageBox 171, 520 Methoden 195 Mid 68 Mid-Funktion 522 MidB 68 MidBP 68 MidC 68 Mid-Statement 523 MinPasswordLength 357 Minute 86, 524 Minutenanteil 86 MkDir 525 Mod 527 Modul 177 %Include 179 (Options) 179 Deklaration von Variablen, Typen und Klassen 180 Funktionen 181 Globale Variable 184 Initialize 177, 180 Option Base 179 Option Compare 179 Option Declare 179 Option Public 179–180 Prozeduren 181 Sichtbarkeit 177 Terminate 177, 180 Use 179 Uselsx 179 Module verschachteln 185 Monatsanteil 84 Month 84, 526 MoveEntry 355 MsgBox 528 Multitasking 163

XN

Name 168, 181, 528 NamedElement 356 NameOfProfile 270, 341

617

NavBarSetText 369 NavBarSpinnerStart 369 NavBarSpinnerStop 369 Navigator 231 New 197 Newsletter 279 NextRow 314, 316, 319, 387 Not 529 NoteID 268, 335, 341, 380 NoteID properly 341 Notes als OLE-Server 153 NotesACL 231, 254, 287 NotesACLEntry 231, 287 Zugriffslevel 290 Zusammenspiel mehrerer Einträge 290 NotesAgent 231 NotesBuildVersion 363 NotesColor 362 NotesDatabase 231, 249, 256, 267, 282 NotesDateRange 231 NotesDateTime 231 NotesDbDirectory 231 NotesDocument 231, 269, 272 NotesDocumentCollection 231, 256, 279 NotesEmbeddedObject 231 Notes-Entwicklerteam 53 NotesFont 362 NotesForm 231 NotesInternational 87, 231 NotesItem 231 NotesLog 130, 231 NotesName 231 NotesNewsLetter 231, 279 NotesOutline 231 NotesOutlineEntry 231 NotesRegistration 231 NotesReplication 231 NotesRichTextItem 231 NotesRichTextParagraph-Style 231 NotesRichTextStyle 231 NotesRichTextTab 231 NotesSession 231, 275 Notes-Systembefehle 44 NotesTimer 231 NotesUIDatabase 231 NotesUIDocument 231 NotesUIWorkspace 172–173, 231 NotesVersion 363 NotesView 231, 256, 262 NotesViewColumn 231 NotesViewEntry 231, 262 NotesViewEntryCollection 231, 262

618

Stichwortverzeichnis

NotesViewNavigator 231 NOTHING 241 Now 83, 530 NULL 62 NumActions 350 NumberAttrib 378 NumberDigits 378 NumberFormat 378 NumColumns 319, 387 Numerische Datentypen 56 NumErrors 350 NumParameters 319, 387 NumRows 319, 387

XO

Object 147, 216, 345 ObjectExecute 326 Objekt 193–194 Objekt definieren 194 Objekthandle 52 Objektorientierte Analyse 192–193 Objektorientierte Programmierung 187 Objektorientierte Sprache 187 Oct 530 ODBC Anzahl abgesetzter SQLStatements 304 Begriffserklärung 299 Datendefinition 311 Datenmanipulation 311 DO 300 ODBCConnection 301 ODBC-Manager 302, 304 ODBCQuery 309 ODBCResultSet 311 Spaltennummerierung 320 ODBCConnection 231, 300–301, 304, 308–310, 312, 317, 321, 324, 383–384

ODBCQuery 231, 300, 309–310, 312–314, 318– 319, 321, 324, 384–386

ODBCResultSet 231, 300, 311–313, 321, 324, 383, 385

OLE Begriffserklärung 147 Datei-Anhang 147, 149 Datei-Anhang extrahieren 152 Eigenschaften auslesen 151 Eingebettetes Objekt 150 EMBED_ATTACHMENT 279 EMBED_OBJECT 279 EMBED_OBJECTLINK 279 ForAll 150 Notes als OLE-Server 153

Object-Embedding 147 Object-Linking 147 Objekt bearbeiten 151 Objekt entfernen 152 OLE1 153 OLE2 153 Verknüpftes Objekt 150 On Error 119, 531 On_..._GoTo 115 On_Error_GoTo 119 On_Error_Resume_Next 119 OOA 192 OOD 192 Basisklasse 200 Containerklassen 213 Hat-Beziehung 215 Klassenbeziehung 200 Klassenvariable 210 Objektvariable 210 Polymorphismus 219, 222 Pseudopolymorphismus 222 Standardmethoden in Containerklassen 216 Subklasse 200 Superklasse 200 Vererbung 200 Vererbungshierarchie 200, 202 Zusätzliche Eigenschaften in abgeleiteten Klassen 202 Zustandsvariablen 205 OOP 187–188 Abfrage von Eigenschaften 196 Ablauf des Vererbungsmechanismus 203 Bezeichner von Eigenschaftsvariablen 196 Datenstrukturen 223 Eigenschaften 195 Eigenschaftsvariable 207 Gleichheit von Methoden 204 Initialisierung 198 Klasse 193–194 Konstruktor 197 Methode einer Basisklasse aufrufen 206 Methode überschreiben 204 Methoden 195 New mit vielen Parametern 199 New-Methode 197 New-Methoden mit unterschiedlichen Parameterlisten 211 Objekt 193–194 Objekt definieren 194

Stichwortverzeichnis

Objekte unterschiedlich initialisieren 198 Property 207, 209 Property Get 207 Property Set 207 Setzen von Eigenschaften 196–197 Validierungsfunktion (als Beispiel) 227 Vererbungsebenen überspringen 206 Virtuelle Funktionen 219 Zugänglichkeit Private-deklarierter Eigenschaften 212, 216 Open 125–126, 156, 158–162, 164–166, 239, 249, 255, 275–276, 335–336, 538

OpenAgentLog 134, 351 OpenByReplicaID 248–249, 255, 335 OpenDatabase 372 OpenFileDialog 372 OpenFileLog 133, 351 OpenFrameSet 372–373 OpenIfModified 255, 335 OpenMail 134, 248–249, 255, 336 OpenMailLog 134, 351 OpenNavigator 366 OpenNotesLog 132–133, 351 OpenPage 373 OpenURLDb 255, 336 OpenView 366, 373 OpenWithFailover 255, 336 Option Base 94, 179 Option Compare 73, 75, 100, 179 Option Declare 179 Option Public 179–180 Or 540 Organization 352 OrgUnit 357 OrgUnit1 352 OrgUnit2 352 OrgUnit3 352 OrgUnit4 352 Overflow-Fehler 57–60, 121 OverwriteFile 133, 351 Owner 331

XP

Pagination 361 Parent 151, 235, 239–240, 249, 270, 327, 329, 331, 334, 341, 343, 345, 349, 375, 380–382

ParentDatabase 235, 270, 341 ParentDocumentUNlD 341 ParentView 270, 341, 382 PassThruHTML 362

619

Paste 369, 371 PercentUsed 334 PickList 173 PickListCollection 174, 373 PickListStrings 174, 373 Platform 363 Platzhalter 167 PlayTune 373 PMString 348 Polymorphismus 219, 222 PostDocumentDelete 366 PostDragDrop 366, 370 PostModeChange 369 PostOpen 252, 260–261, 266, 365–367, 369–371 PostPaste 371 PostRecalc 369 PostSave 369 PreviewDocLink 367 PreviewParentDoc 367 PrevRow 314, 319, 387 Print 34, 67, 69–75, 78, 91, 94, 105, 125, 139–141, 150–151, 157, 171, 176, 220–222, 227, 275–278, 369–370, 540, 603 Print # 157 Priority 359 Private 209 PRMD 353 Profildokumente 281

Benutzerprofil-Dokument erstellen 284 Benutzerprofil-Dokument öffnen 284 Benutzerprofildokumente 281 Datenbank-Profildokument 282 Datenbankprofil-Dokument erstellen 282 Datenbankprofil-Dokument löschen 283 Datenbankprofil-Dokument öffnen 282 Programm verlassen 116 Programmierbereich 44 Programmierfenster 42–45 Programmlesbarkeit 107 Programmsprung 114–116 Programmverzweigung 107–109 ProgramName 351 Prompt 373 ProtectReaders 346, 375 ProtectUsers 346 Protokollierung AgentLog 134 Agent-Protokoll 130

620

ALOG4.NTF 132 Archivierung 130 Ausgabe-Medien 130 Detaillierungsgrad 130 E-Mail 130 Gefahr der Endlos-Schleife 130 Laufzeitfehler 129 Notes-Databank 130 NotesLog 130 Protokolldokument 132 Textdatei 130 Prozedurale Zerlegung 188 Prozeduren 181 Pseudopolymorphismus 222 public 537 Put 543 Put # 160, 162 PutAllInFolder 344, 381 PutInFolder 271, 342

XQ

Query 140, 236, 310–314, 321, 331, 343, 381, 385 QueryAccess 254–255, 336 QueryAddToFolder 371 QueryClose 366, 369, 371 QueryDocumentDelete 366 QueryDocumentUndelete 366 QueryDragDrop 366, 371 QueryExecuteTimeOut 310, 384 QueryModeChange 370 QueryOpen 370–371 QueryOpenDocument 371 QueryPaste 371 QueryRecalc 371 QuerySave 370

XR

Random-Datei 159 Randomize 544 Read 157 Read Write 157 Readerfelder 291 Readers 346, 375 ReadOnly 313–314, 385 Recertify 358 ReDim 90, 97, 545 Referenzübergabe 76 Refresh 369, 373, 377 RefreshHideFormulas 369 RefreshParentNote 373 RegionDoubleClick 371 RegisterNewCertifier 358 RegisterNewServer 358

Stichwortverzeichnis

RegisterNewUser 358 RegistrationLog 357 RegistrationServer 357–358 Reload 369, 373 ReloadWindow 373 REM 46 Rem 546, 597 Remove 152, 251, 255, 271, 277, 283, 323, 330, 332, 336, 343, 346–347, 350, 377

RemoveAll 344, 381 RemoveAllFromFolder 344, 381 RemoveEntry 355 RemoveFromFolder 271, 343 RemoveItem 271, 343 RenameRole 328 RenderToRTItem 271, 343 ReplaceItemValue 87, 173–174, 234, 238, 271–274, 276, 283, 296, 343, 348

ReplicaID 334 Replicate 255, 336 ReplicationInfo 334, 358 Replik erstellen 247 Replikationskonflikt 272 Reset 359, 546 Responses 270, 341 Ressourcen freigeben 125 Resume 547 Resume 0 124 Resume Label 124 Resume Next 124 Return 548 RevokeAccess 254–255, 336 Right 67, 548 RightB 67 RightBP 67 RightC 67 RightMargin 361 RmDir 551 Rnd 551 Roles 327, 330 RollbackTransactions 303–304, 317, 384 Rollen 287, 293 Rotes Fenster 52 Rotes Kreuzchen 52 Round 550 RowLines 375 RSet 69, 552 RTrim 69 Rtrim 553 Ruler 367 Run 332, 553 RunOnServer 141, 332 RunReadOnly 345

Stichwortverzeichnis

XS

Save 148–149, 173, 234, 242, 271–272, 274, 276– 278, 283, 292, 296–297, 327–328, 332, 343, 355, 359, 369, 381 SavedData 364 SaveFileDialog 373 SaveMessageOnSend 270, 341 SaveNewVersion 369 SaveToDisk 349

Schleifen Do_..._Loop 113 Do_..._Until 112 Do_..._While 111 Endlosschleife 113 For_..._Next 110 ForAll 114 Fußgesteuerte 112 Kopfgesteuerte 111–112 Verlassen 116 While ... Wend 112 Script-Bibliothek 178 Name 181 Verschachteln 185 Search 258–259, 263, 268, 277, 336 Second 86, 554 Seek 157, 161, 163 Seek Anweisung 555 Seek Funktion 554 Sekundenanteil 86 Select Case 556 Select_Case 109 SelectAll 369 SelectDocument 370 Send 238, 271, 277, 280, 295, 343, 369 SendKey 558 SentByAgent 341 Sequentielle Datei 156 Server 42, 132, 137, 140–141, 144, 171, 174–175, 231, 233, 235, 239, 245, 247–250, 253, 255, 287, 289, 291, 324, 329, 332, 334–336, 339, 357–358, 363–364 Server-Agent 137 ServerName 331 SetAction 356 SetAnyDate 338 SetAnyTime 338 SetCurrentLocation 373 SetEnvironmentVar 365 SetFileAttr 169, 558 SetNamedElement 356 SetNoteLink 356 SetNow 338 SetParameter 319, 387

621

SetTab 361–362 SetTargetFrame 373 SetURL 356 SetValue 315–316, 319–320, 322, 387 Sgn 559 Shared-Modus 163 Shell 560 SiblingCount 380 Sichtbarkeit 177 Sign 297, 343 Signer 341 SignOnSend 270, 341 SilentMode 302, 308, 313, 383 Sin 562 Single 58 Size 334, 341 SizeQuota 253, 334 Sleep 139, 562 Source 151, 173–174, 182, 237, 252, 261, 266, 274–278, 326, 345, 365, 367, 370

Space 73, 563 Spacing 375 SpacingAbove 361 SpacingBelow 361 Spaltennummerierung 320 Speicherkonflikt 272 Speichern 148–149, 173, 234, 242, 271–272, 274, 276–278, 283, 292, 296–297, 327–328, 332, 343, 355, 359, 369, 381

Speicherplatz In Bytes 67 In Bytes bei plattformabhängigem Format 67 Länge in Zeichen 67 Länge in Zeichen bei spaltenorientierten Sprachen 67 SpellCheck 369 Sprungmarken 107 SQL 310–311, 320–321, 384 Sqr 564 StampAll 344, 381 Standardanfang der Indexbereiche 94 StartDateTime 337 Statische Zeichenkette 66 Statuszeile 34, 171, 176 Step 110 Stop 565 StoreIDInAddressbook 357 Str 70–73, 566 StrComp 571 StrCompare 570 StrCompare und StrComp 70 Strikethrough 362

622

String 65 Aneinanderhängen 75 Ausrichtung 69 Dynamische und statische Zeichenketten 66 Grenzen 77 Konkatenationsoperatoren 75 Längenermittlung 78 Referenzübergabe 76 Standardvergleichsmethode 73 statische und dynamische Zeichenketten 77 Teilstring extrahieren 68, 71, 73 Typumwandlung 74 Umwandlung Groß-/ Kleinschreibung 69 Umwandlung in String 70–73 Umwandlung Zeichensatz 71 Unicode 75 Vergleich 70 Vergleichsmethoden 70 Wertübergabe 76 Wertzuweisung 77 Zeichen 74 Zeichencode 74 String aus Zeichen erzeugen 73 String Funktion 571 StrLeft 71–72, 566 StrLeftBack 72, 567 StrRight 71–72, 568 StrRightBack 72, 569 Stundenanteil 85 Sub 181, 572 SubjectItemName 353 Suchen eines Array-Eintrags 93 Surname 353 SwitchToID 358 Syntaxüberprüfung 44

XT

Tab 573 Tabs 361–362 Tabulator 46 Tag, Monat und Jahr 80, 347 Tagesanteil 85 Tan 574 Target 331 Teilstring extrahieren 68 TemplateName 334 Terminate 177, 180 Text 27, 44, 46, 52, 87, 109, 125, 171–172, 221, 227, 246, 264–265, 274, 337, 347–350, 360, 362, 368–369

Stichwortverzeichnis

ThousandsSep 348 Time 83 TimeDateFmt 379 TimeDifference 338 TimeDifferenceDouble 338 TimeFmt 379 TimeNumber 576 TimeOnly 337 Timer 84, 576 TimeSep 348 TimeValue 81, 577 TimeZone 337, 348 TimeZoneFmt 379 Title 253–254, 334, 379 Today 83, 259–260, 266–267, 277, 348, 578 Tomorrow 348 TopLevelEntryCount 375 Trigger 331 Trim 69, 578 Type 57–61, 93, 140, 150–151, 159–161, 185, 190, 345, 349, 356, 362, 579

Type Mismatch-Fehler 57–61, 93 TypeName 62, 580

XU

Ubound 92, 581 UCase 69, 582 Uchr 582 Uhrzeit 83 UI-Klassen 231 Umwandlung Datentypen 74 Zeit- und Datumswerte 80–81 Umwandlung Groß-/Kleinschreibung 69 Umwandlung in String 70–73 Umwandlung Zeichensatz 71 Underline 362 Uni 75, 583 Unicode 65, 75 UniformAccess 288, 327 UniversalID 268, 335, 341, 375, 380 UnLock 164 Unlock 584 UnprocessedDocuments 239, 267, 334 UnprocessedFTSearch 268, 336 UnprocessedSearch 268, 336 UpdateAddressbook 357 UpdateAll 344, 381 UpdateFTIndex 255, 336 UpdateProcessedDoc 365 UpdateRow 316, 319–320, 322, 387 URL 140, 268, 335, 356, 369, 373 URLOpen 373

Stichwortverzeichnis

Use 179, 585 UseLSX 179–180, 243–244, 300, 323, 373 UserName 364 UserNameList 364 UseRowID 310, 384 UserType 330 UString 75, 586

XV

Val 74, 587 ValueLength 349 Values 349 Variablenwerte ansehen 51 Variant 61, 79, 90, 99, 102, 222 DataType 62 Empty 61 Leerstring 62 NULL 62 TypeName 62 VarType 588 Verbs 345 Vergleich zweier Zeichenketten 70 Vergleichsmethode 73 Vergleichsmethoden 70 Vergleichsoperatoren 75 Verifier 341 Verschlüsselung Datenbanken 295 Elektronisch unterschreiben 297 Felder 295 Geheimer Schlüssel 294 Mails 295 Public-Private-Schlüsselpaar 295 Verzeichnis Aktuelles Laufwerk 168 Arbeitsverzeichnis 168 Dateien eines V. 167 V. umbenennen 168 Verzeichnis wechseln 168 View 262, 356, 360, 370, 373–374 Viewname 370 ViewRefresh 373 Views 334, 374

623

XW

Währung 60 Web-Zugriff 290 Weekday 85, 588 Wert-Auslesen bei Listen 101 Wertübergabe 76 Wertzuweisung bei Listen 101 While 589 While ... Wend 112 Width 379 Width# 590 WindowTitle 367 With 591 Wochentag 85 Workflow-Status 273

XX

Xor 592

XY

Year 84, 593 Yesterday 348

XZ

Zeichen 74 Zeichencode 65, 73–75 Zeichensatz Umwandlung 71 Zeilenumbrüche 46 Zeit Fallen 86 Minutenanteil 86 Sekundenanteil 86 Stundenanteil 85 Zeitdifferenz bestimmen 84 Zeitformate 86 ZoneTime 338 Zugriffskontrollliste 231, 287–289, 327–328, 332

Zugriffslevel 290 Zugriffsrechte Autorenfelder 291 Leserfelder 291 Readerfelder 291