IBM Lotus Symphony
|
![]() |
Die nachfolgend beschriebene Methode zum Erweitern von Lotus® Symphony™ Spreadsheets mithilfe von Add-ins ist veraltet. Die Schnittstellen sind weiterhin gültig und werden unterstützt, um die Kompatibilität mit vorhandenen Add-ins sicherzustellen, aber für die Programmierung neuer Add-ins sollten Sie die neuen API-Funktionen verwenden. |
Lotus Symphony Spreadsheets kann mithilfe von Add-ins erweitert werden, bei denen es sich um externe Programmierungsmodule handelt, die zusätzliche Funktionen für die Arbeit mit Tabellendokumenten zur Verfügung stellen. Diese werden im Funktionsassistenten in der Kategorie Add-in aufgelistet. Wenn Sie selbst ein Add-in programmieren möchten, können Sie hier erfahren, welche Funktionen von der externen DLL exportiert werden müssen, damit das Add-in erfolgreich angehängt werden kann.
Der in der Konfiguration definierte Add-in-Ordner wird von Lotus Symphony nach einer geeigneten DLL durchsucht. Damit sie von Lotus Symphony erkannt wird, muss die DLL bestimmte Eigenschaften besitzen, die nachfolgend erläutert werden. Mithilfe dieser Informationen können Sie ein eigenes Add-in für den Funktionsassistenten von Lotus Symphony Spreadsheets programmieren.
Jede Add-in-Bibliothek stellt verschiedene Funktionen zur Verfügung. Einige Funktionen werden zu Verwaltungszwecken verwendet. Sie können für Ihre eigenen Funktionen beinahe jeden Namen verwenden. Allerdings müssen auch hier bestimmte Regeln hinsichtlich der Übergabe von Parametern beachtet werden. Die genauen Benennungs- und Aufrufvereinbarungen variieren für die verschiedenen Plattformen.
Die Verwaltungsfunktionen GetFunctionCount und GetFunctionData müssen mindestens vorhanden sein. Mit diesen können die Funktionen, Parametertypen und Rückgabewerte ermittelt werden. Als Rückgabewerte werden die Typen "Double" und "String" unterstützt. Als Parameter werden außerdem die Zellenbereiche Double-Matrix, String-Matrix und Zellenmatrix unterstützt.
Parameter werden mithilfe von Verweisen übergeben. Daher ist es grundsätzlich möglich, diese Werte zu ändern. Dies wird jedoch in Lotus Symphony Spreadsheets nicht unterstützt, da es in Tabellendokumenten nicht sinnvoll ist.
Bibliotheken können während der Laufzeit geladen und ihre Inhalte von den Verwaltungsfunktionen analysiert werden. Für jede Funktion stehen Informationen zu Anzahl und Art der Parameter, internen und externen Funktionsnamen sowie einer Verwaltungsnummer zur Verfügung.
Die Funktionen werden synchron aufgerufen und geben ihre Ergebnisse unverzüglich zurück. Echtzeitfunktionen (asynchrone Funktionen) sind ebenfalls möglich. Diese werden aufgrund ihrer Komplexität nicht ausführlich erläutert.
Die maximale Anzahl von Parametern in einer Add-in-Funktion, die an Lotus Symphony Spreadsheets angehängt ist, beträgt 16: ein Rückgabewert und maximal 15 Eingabeparameter für die Funktion.
Die Datentypen sind wie folgt definiert:
Datentyp | Definition |
---|---|
CALLTYPE | Unter Windows: FAR PASCAL (_far _pascal) Andere: Standard (betriebssystemabhängiger Standardwert) |
USHORT | 2 Byte, ganze Zahl ohne Vorzeichen |
DOUBLE | 8 Byte, plattformabhängiges Format |
Paramtype | Plattformabhängig wie int PTR_DOUBLE =0 Zeiger auf Double PTR_STRING =1 Zeiger auf mit Null abgeschlossenem String PTR_DOUBLE_ARR =2 Zeiger auf Double-Matrix PTR_STRING_ARR =3 Zeiger auf String-Matrix PTR_CELL_ARR =4 Zeiger auf Zellenmatrix NONE =5 |
Nachfolgend sind diese Funktionen beschrieben, die in der externen DLL aufgerufen werden.
Für alle DLL-Funktionen gilt Folgendes:
void CALLTYPE fn(out, in1, in2, ...)
Ausgabe: Ergebniswert
Eingabe: Beliebige Zahl mit folgenden Typen (double&, char*, double*, char**, Zellenbereich), wobei der Zellenbereich eine Matrix vom Typ Double-Matrix, String-Matrix oder Zellenmatrix ist.
Gibt die Anzahl der Funktionen ohne Managementfunktionen der Referenzparameter zurück. Jede Funktion besitzt eine eindeutige Zahl zwischen 0 und nCount-1. Diese Zahl ist später für die Funktionen GetFunctionData und GetParameterDescription erforderlich.
Syntax
void CALLTYPE GetFunctionCount(USHORT& nCount)
Parameter
USHORT &nCount:
Ausgabe: Verweis auf eine Variable, die die Anzahl der Add-in-Funktionen enthalten soll. Beispiel: Wenn im Add-in fünf Funktionen für Lotus Symphony Spreadsheets bereitgestellt werden, ist nCount=5.
Ermittelt alle wichtigen Informationen zu einer Add-in-Funktion.
Syntax
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
Parameter
USHORT& nNo:
Eingabe: Funktionsnummer zwischen 0 und nCount-1, einschließlich.
char* pFuncName:
Ausgabe: Funktionsname, wie er dem Programmierer angezeigt wird und in der DLL benannt ist. Dieser Name bestimmt nicht den Namen, der im Funktionsassistenten verwendet wird.
USHORT& nParamCount:
Ausgabe: Anzahl der Parameter in der Add-in-Funktion. Diese Anzahl muss größer als 0 sein, da es immer einen Ergebniswert gibt. Der Maximalwert ist 16.
Paramtype* peType:
Ausgabe: Zeiger auf eine Matrix von genau 16 Variablen vom Typ "Paramtype". Die ersten durch nParamCount angegebenen Einträge werden mit den geeigneten Parametertypen gefüllt.
char* pInternalName:
Ausgabe: Funktionsname, wie er dem Benutzer angezeigt wird und im Funktionsassistenten enthalten ist. Der Name darf Umlaute enthalten.
Die Parameter pFuncName und pInternalName sind Zeichenmatrizen (char), die in Lotus Symphony Spreadsheets mit der Größe 256 implementiert sind.
Bietet eine Kurzbeschreibung der Add-in-Funktion und ihrer Parameter. Mithilfe dieser Funktion können Sie optional eine Funktions- und Parameterbeschreibung im Funktionsassistenten anzeigen.
Syntax
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
Parameter
USHORT& nNo:
Eingabe: Nummer der Funktion in der Bibliothek; zwischen 0 und nCount-1.
USHORT& nParam:
Eingabe: Gibt an, für welchen Parameter die Beschreibung bereitgestellt wurde. Parameter beginnen bei 1. Wenn nParam den Wert 0 ergibt, wird angenommen, dass die Beschreibung selbst in pDesc bereitgestellt wird. In diesem Fall hat pName keine Bedeutung.
char* pName:
Ausgabe: Nimmt den Parameternamen oder -typ auf, z. B. das Wort "Nummer" oder "Zeichenfolge" oder "Datum" usw. In Lotus Symphony Spreadsheets als char[256] implementiert.
char* pDesc:
Ausgabe: Nimmt die Beschreibung des Parameters auf, z. B. "Wert, bei dem das Universum berechnet wird". In Lotus Symphony Spreadsheets als char[256] implementiert.
pName und pDesc sind Zeichenmatrizen (char). In Lotus Symphony Spreadsheets mit der Größe 256 implementiert. Beachten Sie, dass der verfügbare Speicherplatz im Funktionsassistenten begrenzt ist und die 256 Zeichen nicht vollständig verwendet werden können.
In den folgenden Tabellen sind Informationen darüber enthalten, welche Datenstrukturen von einem externen Programmmodul bereitgestellt werden müssen, um Zellenbereiche zu übergeben. In Lotus Symphony Spreadsheets wird in Abhängigkeit vom Datentyp zwischen drei verschiedenen Matrizen unterschieden.
Als Parameter kann ein Zellenbereich mit Werten vom Typ Zahl/Double übergeben werden. Eine Double-Matrix ist in Lotus Symphony Spreadsheets wie folgt definiert:
Abstand | Name | Beschreibung |
---|---|---|
0 | Sp1 | Spaltennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
2 | Ze1 | Zeilennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
4 | Tab1 | Tabellennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
6 | Sp2 | Spaltennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
8 | Ze2 | Zeilennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
10 | Tab2 | Tabellennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
12 | Anzahl | Anzahl der folgenden Elemente. Leere Zellen werden nicht gezählt oder übergeben. |
14 | Sp | Spaltennummer des Elements. Die Nummerierung beginnt mit 0. |
16 | Zeile | Zeilennummer des Elements. Die Nummerierung beginnt mit 0. |
18 | Tab | Tabellennummer des Elements. Die Nummerierung beginnt mit 0. |
20 | Fehler | Fehlernummer, wobei 0 als "kein Fehler" definiert ist. Wenn das Element aus einer Formelzelle stammt, wird der Fehlerwert von der Formel ermittelt. |
22 | Wert | IEEE-Variable mit 8 Byte vom Typ Double/Gleitkomma |
30 | ... | Nächstes Element |
Ein Zellenbereich, der Werte vom Datentyp "Text" enthält und als Zeichenfolgematrix übergeben wird. Eine Zeichenfolgematrix ist in Lotus Symphony Spreadsheets wie folgt definiert:
Abstand | Name | Beschreibung |
---|---|---|
0 | Sp1 | Spaltennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
2 | Ze1 | Zeilennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
4 | Tab1 | Tabellennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
6 | Sp2 | Spaltennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
8 | Ze2 | Zeilennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
10 | Tab2 | Tabellennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
12 | Anzahl | Anzahl der folgenden Elemente. Leere Zellen werden nicht gezählt oder übergeben. |
14 | Sp | Spaltennummer des Elements. Die Nummerierung beginnt mit 0. |
16 | Zeile | Zeilennummer des Elements. Die Nummerierung beginnt mit 0. |
18 | Tab | Tabellennummer des Elements. Die Nummerierung beginnt mit 0. |
20 | Fehler | Fehlernummer, wobei 0 als "kein Fehler" definiert ist. Wenn das Element aus einer Formelzelle stammt, wird der Fehlerwert von der Formel ermittelt. |
22 | Länge | Länge der folgenden Zeichenfolge, einschließlich dem schließenden Nullbyte. Wenn die Länge einschließlich des schließenden Nullbyte einen ungeraden Wert ergibt, wird ein zweites Nullbyte zur Zeichenfolge hinzugefügt, damit ein gerader Wert erreicht wird. Daher wird die Länge mithilfe von ((StrLen+2)&~1) berechnet. |
24 | String | String mit schließendem Nullbyte. |
24+Länge | ... | Nächstes Element |
Mithilfe von Zellenmatrizen können Sie Zellenbereiche aufrufen, die Text und Zahlen enthalten. In Lotus Symphony Spreadsheets ist eine Zellenmatrix wie folgt definiert:
Abstand | Name | Beschreibung |
---|---|---|
0 | Sp1 | Spaltennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
2 | Ze1 | Zeilennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
4 | Tab1 | Tabellennummer in der oberen linken Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
6 | Sp2 | Spaltennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
8 | Ze2 | Zeilennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
10 | Tab2 | Tabellennummer in der unteren rechten Ecke des Zellenbereichs. Die Nummerierung beginnt mit 0. |
12 | Anzahl | Anzahl der folgenden Elemente. Leere Zellen werden nicht gezählt oder übergeben. |
14 | Sp | Spaltennummer des Elements. Die Nummerierung beginnt mit 0. |
16 | Zeile | Zeilennummer des Elements. Die Nummerierung beginnt mit 0. |
18 | Tab | Tabellennummer des Elements. Die Nummerierung beginnt mit 0. |
20 | Fehler | Fehlernummer, wobei 0 als "kein Fehler" definiert ist. Wenn das Element aus einer Formelzelle stammt, wird der Fehlerwert von der Formel ermittelt. |
22 | Typ | Typ des Zelleninhalts, 0 == Double, 1 == String |
24 | Wert oder Länge | Wenn Typ == 0: IEEE-Variable mit 8 Byte vom Typ Double/Gleitkomma Wenn Typ == 1: Länge der folgenden Zeichenfolge, einschließlich dem schließenden Nullbyte. Wenn die Länge einschließlich des schließenden Nullbyte einen ungeraden Wert ergibt, wird ein zweites Nullbyte zur Zeichenfolge hinzugefügt, damit ein gerader Wert erreicht wird. Daher wird die Länge mithilfe von ((StrLen+2)&~1) berechnet. |
26, wenn Typ==1 | String | Wenn Typ == 1: String mit schließendem Nullbyte. |
32 oder 26+Länge | ... | Nächstes Element |