IBM Lotus Symphony


Add-in für Programmierung in Lotus Symphony Spreadsheets

Symbol für Warnung 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.

Add-in-Konzept

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.

Funktionen der Add-in-DLL

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.

Allgemeine Informationen zur Schnittstelle

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:

Tabelle 1. Datentypdefinitionen
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

DLL-Funktionen

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.

GetFunctionCount()

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.

GetFunctionData()

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.

GetParameterDescription()

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.

Zellenbereiche

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.

Double-Matrix

Als Parameter kann ein Zellenbereich mit Werten vom Typ Zahl/Double übergeben werden. Eine Double-Matrix ist in Lotus Symphony Spreadsheets wie folgt definiert:

Tabelle 2. Definition einer Double-Matrix
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

Zeichenfolgematrix

Ein Zellenbereich, der Werte vom Datentyp "Text" enthält und als Zeichenfolgematrix übergeben wird. Eine Zeichenfolgematrix ist in Lotus Symphony Spreadsheets wie folgt definiert:

Tabelle 3. Definition einer Zeichenfolgematrix
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

Zellenmatrix

Mithilfe von Zellenmatrizen können Sie Zellenbereiche aufrufen, die Text und Zahlen enthalten. In Lotus Symphony Spreadsheets ist eine Zellenmatrix wie folgt definiert:

Tabelle 4. Definition einer Zellenmatrix
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

Produktfeedback | Zusätzliche Dokumentation | Marken