IBM Lotus Symphony


Programy dodatkowe i programowanie w komponencie Lotus Symphony Spreadsheets

Ikona Ostrzeżenie Opisana w tym dokumencie metoda rozszerzania funkcjonalności komponentu Lotus® Symphony™ Spreadsheets za pomocą programów dodatkowych jest przestarzała. Interfejsy są wciąż poprawne i obsługiwane, co zapewnia kompatybilność z istniejącymi programami dodatkowymi, ale do tworzenia nowych programów dodatkowych należy używać nowych funkcji API.

Komponent Lotus Symphony Spreadsheets można rozszerzać przy użyciu programów dodatkowych, które są zewnętrznymi modułami programistycznymi udostępniającymi dodatkowe funkcje na potrzeby pracy z arkuszami kalkulacyjnymi. Są one wyświetlane w kreatorze funkcji w kategorii Program dodatkowy. Jeśli chcesz samodzielnie napisać program dodatkowy, warto przeczytać zawarte w tym dokumencie informacje o tym, które funkcje muszą zostać wyeksportowane przez zewnętrzną bibliotekę DLL w celu umożliwienia pomyślnego przyłączenia programu dodatkowego.

Produkt Lotus Symphony wyszukuje odpowiednie biblioteki DLL w folderze programów dodatkowych zdefiniowanym w konfiguracji. Rozpoznanie biblioteki DLL przez produkt Lotus Symphony umożliwiają określone właściwości opisane w dalszej części tego dokumentu. Podane informacje pozwalają na tworzenie własnych programów dodatkowych dla kreatora funkcji komponentu Lotus Symphony Spreadsheets.

Pojęcia dotyczące programów dodatkowych

Każda biblioteka programu dodatkowego udostępnia kilka funkcji. Niektóre z nich służą do celów administracyjnych. Dla własnych funkcji można wybrać prawie dowolną nazwę. Jednak muszą być one zgodne z pewnymi regułami dotyczącymi przekazywania parametrów. Konwencje nazewnictwa i wywoływania są różne dla poszczególnych platform.

Funkcje biblioteki DLL programu dodatkowego

Minimalny wymagany zestaw funkcji to funkcje administracyjne GetFunctionCount i GetFunctionData. Umożliwiają one określenie typów funkcji i parametrów oraz wartości zwracanych. Dla wartości zwracanych obsługiwane są typy Double i String. Dla parametrów obsługiwane są także obszary komórek typu Double Array, String Array i Cell Array.

Parametry są przekazywane przez referencje. Oznacza to, że ogólnie zmiana ich wartości jest możliwa. Komponent Lotus Symphony Spreadsheets nie obsługuje jednak takiej operacji, ponieważ nie ma ona sensu w odniesieniu do arkuszy kalkulacyjnych.

Biblioteki można przeładować w czasie wykonywania, a ich zawartość można analizować przy użyciu funkcji administracyjnych. Dla każdej funkcji jest dostępna informacja o liczbie i typach parametrów, zewnętrzna i wewnętrzna nazwa funkcji oraz liczba administracyjna.

Funkcje są wywoływane synchronicznie i natychmiast zwracają wyniki. Stosowanie funkcji czasu rzeczywistego (funkcji asynchronicznych) jest także możliwe, jednak nie są one opisane szczegółowo ze względu na ich złożoność.

Informacje ogólne o interfejsie

Maksymalna liczba parametrów funkcji programu dodatkowego przyłączonego do komponentu Lotus Symphony Spreadsheets to 16, w tym jedna wartość zwracana i maksymalnie 15 parametrów wejściowych funkcji.

Typy danych są zdefiniowane w następujący sposób:

Tabela 1. Definicje typów danych
Typ danych Definicja
CALLTYPE

W systemie Windows: FAR PASCAL (_far _pascal)

Inne: domyślnie (wartość domyślna specyficzna dla systemu operacyjnego)

USHORT 2-bajtowa liczba całkowita bez znaku typu Byte
DOUBLE 8-bajtowy format zależny od platformy
Paramtype

Format zależny od platformy, taki jak int

PTR_DOUBLE =0 wskaźnik do typu double

PTR_STRING =1 wskaźnik do łańcucha zakończonego wartością zerową

PTR_DOUBLE_ARR =2 wskaźnik do typu double array

PTR_STRING_ARR =3 wskaźnik do typu string array

PTR_CELL_ARR =4 wskaźnik do typu cell array

NONE =5

Funkcje biblioteki DLL

Poniżej znajdują się opisy funkcji wywoływanych w zewnętrznej bibliotece DLL.

Dla wszystkich funkcji biblioteki DLL stosuje się następujący opis:

void CALLTYPE fn(wy, we1, we2, ...)

Dane wyjściowe: Wartość wynikowa

Dane wejściowe: Dowolna liczba wartości typów (double&, char*, double*, char**, Obszar komórek), gdzie Obszar komórek to tablica typu double array, string array lub cell array.

GetFunctionCount()

Powoduje zwrócenie liczby funkcji bez uwzględniania funkcji zarządzających parametru referencji. Każda funkcja ma unikalny numer z zakresu od 0 do nLicznik-1. Ten numer jest później wymagany przez funkcje GetFunctionData oraz GetParameterDescription.

Składnia

void CALLTYPE GetFunctionCount(USHORT& nLicznik)

Parametr

USHORT &nLicznik:

Dane wyjściowe: Referencja do zmiennej, która zawiera informację o liczbie funkcji programu dodatkowego. Jeśli na przykład program dodatkowy udostępnia 5 funkcji komponentowi Lotus Symphony Spreadsheets, zwracana jest wartość nLicznik=5.

GetFunctionData()

Określa wszystkie ważne informacje dotyczące funkcji programu dodatkowego.

Składnia

void CALLTYPE GetFunctionData(USHORT& nNr, char* pNazwaFunkcji, USHORT& nLicznikParametrow, Paramtype* peTyp, char* pNazwaWewnetrzna)

Parametr

USHORT& nNr:

Dane wejściowe: Numer funkcji z domkniętego przedziału od 0 do nLicznik -1.

char* pNazwaFunkcji:

Dane wyjściowe: Nazwa funkcji widziana przez programistę, określona w bibliotece DLL. Ta nazwa nie określa nazwy używanej w kreatorze funkcji.

USHORT& nLicznikParametrow:

Wyjście: Liczba parametrów funkcji programu dodatkowego. Ta liczba musi być większa od 0, ponieważ wartość wynikowa występuje zawsze. Wartość maksymalna to 16.

Paramtype* peTyp:

Wyjście: Wskaźnik do tablicy dokładnie 16 zmiennych typu Paramtype. Na pierwszych nLicznikParametrow pozycjach znajdują się odpowiednie typy parametrów.

char* pNazwaWewnetrzna:

Wyjście: Nazwa funkcji widziana przez użytkownika, widoczna w kreatorze funkcji. Może zawierać znaki umlaut.

Parametry pNazwaFunkcji i pNazwaWewnetrzna są tablicami znaków. Wielkość ich implementacji w komponencie Lotus Symphony Spreadsheets wynosi 256.

GetParameterDescription()

Udostępnia krótki opis funkcji programu dodatkowego i jej parametrów. Opcjonalnie można tej funkcji użyć do wyświetlenia opisu funkcji i parametrów w kreatorze funkcji.

Składnia

void CALLTYPE GetParameterDescription(USHORT& nNr, USHORT& nParametr, char* pNazwa, char* pOpis)

Parametr

USHORT& nNr:

Dane wejściowe: Liczba funkcji w bibliotece z zakresu od 0 do nLicznik-1.

USHORT& nParametr:

Dane wejściowe: Określa parametr, którego opis jest udostępniany. Parametry numerowane są od 1. Jeśli wartość nParametr jest równa 0, sam opis jest podawany w parametrze pOpis. W takim przypadku parametr pNazwa nie ma znaczenia.

char* pNazwa:

Dane wyjściowe: Przyjmuje nazwę lub typ parametru, na przykład słowo "Number", "String" lub "Date" itd. Typ tego parametru zaimplementowanego w komponencie Lotus Symphony Spreadsheets to char[256].

char* pOpis:

Dane wyjściowe: Przyjmuje wartość opisu parametru, na przykład „Wartość, dla której zostanie obliczony wszechświat”. Typ tego parametru zaimplementowanego w komponencie Lotus Symphony Spreadsheets to char[256].

Parametry pNazwa i pOpis są tablicami znaków. Ich implementacja w komponencie Lotus Symphony Spreadsheets ma wielkość 256. Należy zwrócić uwagę na ograniczoną dostępność miejsca w kreatorze funkcji, która uniemożliwia pełne wykorzystanie 256 znaków.

Obszary komórek

Następująca tabela zawiera informacje o strukturach danych, które musi udostępnić zewnętrzny moduł programu w celu przekazania obszarów komórek. Komponent Lotus Symphony Spreadsheets rozróżnia trzy typy tablic w zależności od typu danych.

Tablica wartości podwójnej precyzji

Jako parametr można przekazać obszar komórek zawierający wartości typu Number/Double. Tablica wartości podwójnej precyzji jest zdefiniowana w komponencie Lotus Symphony Spreadsheets następująco:

Tabela 2. Definicja tablicy liczb zmiennopozycyjnych o podwójnej precyzji
Przesunięcie Nazwa Opis
0 Col1 Numer kolumny w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
2 Row1 Numer wiersza w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
4 Tab1 Numer tabeli w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
6 Col2 Numer kolumny w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
8 Row2 Numer wiersza w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
10 Tab2 Numer tabeli w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
12 Count Liczba następujących elementów. Puste komórki nie są zliczane ani przekazywane.
14 Col Numer kolumny elementu. Numeracja rozpoczyna się od 0.
16 Row Numer wiersza elementu. Numeracja rozpoczyna się od 0.
18 Tab Numer tabeli elementu. Numeracja rozpoczyna się od 0.
20 Error Numer błędu, przy czym wartość 0 oznacza brak błędu. Jeśli element pochodzi z komórki formuły, wartość błędu jest określona przez formułę.
22 Value Zmienna 8-bajtowa zgodna ze standardem IEEE, podwójnej precyzji/zmiennopozycyjna.
30 ... Następny element

Tablica łańcuchów

Obszar komórek zawierający wartości typu Text, przekazywany jako tablica łańcuchów. Tablica łańcuchów jest zdefiniowana w komponencie Lotus Symphony Spreadsheets produktu Lotus Symphony następująco:

Tabela 3. Definicja tablicy łańcuchów
Przesunięcie Nazwa Opis
0 Col1 Numer kolumny w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
2 Row1 Numer wiersza w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
4 Tab1 Numer tabeli w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
6 Col2 Numer kolumny w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
8 Row2 Numer wiersza w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
10 Tab2 Numer tabeli w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
12 Count Liczba następujących elementów. Puste komórki nie są zliczane ani przekazywane.
14 Col Numer kolumny elementu. Numeracja rozpoczyna się od 0.
16 Row Numer wiersza elementu. Numeracja rozpoczyna się od 0.
18 Tab Numer tabeli elementu. Numeracja rozpoczyna się od 0.
20 Error Numer błędu, przy czym wartość 0 oznacza brak błędu. Jeśli element pochodzi z komórki formuły, wartość błędu jest określona przez formułę.
22 Len Długość następującego łańcucha, włącznie z kończącym bajtem o wartości zero. Jeśli długość uwzględniająca kończący bajt o wartości zero jest nieparzysta, do łańcucha jest dodawany kolejny bajt o wartości zero, aby otrzymać długość parzystą. Z tego powodu wartość Len jest obliczana jako ((StrLen+2)&~1).
24 String Łańcuch z kończącym bajtem zerowym
24+Len ... Następny element

Tablica komórek

Tablice komórek umożliwiają wywoływanie obszarów komórek zawierających tekst oraz liczby. Tablica komórek jest zdefiniowana w komponencie Lotus Symphony Spreadsheets następująco:

Tabela 4. Definicja tablicy komórek
Przesunięcie Nazwa Opis
0 Col1 Numer kolumny w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
2 Row1 Numer wiersza w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
4 Tab1 Numer tabeli w górnym lewym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
6 Col2 Numer kolumny w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
8 Row2 Numer wiersza w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
10 Tab2 Numer tabeli w dolnym prawym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
12 Count Liczba następujących elementów. Puste komórki nie są zliczane ani przekazywane.
14 Col Numer kolumny elementu. Numerowanie rozpoczyna się od 0.
16 Row Numer wiersza elementu. Numeracja rozpoczyna się od 0.
18 Tab Numer tabeli elementu. Numeracja rozpoczyna się od 0.
20 Error Numer błędu, przy czym wartość 0 oznacza brak błędu. Jeśli element pochodzi z komórki formuły, wartość błędu jest określona przez formułę.
22 Type Typ zawartości komórki, 0 == Double, 1 == String.
24 Value lub Len

Jeśli Type == 0: Zmienna 8-bajtowa zgodna ze standardem IEEE, podwójnej precyzji/zmiennopozycyjna.

Jeśli Type == 1: Długość następującego łańcucha, włącznie z kończącym bajtem o wartości zero. Jeśli długość uwzględniająca kończący bajt o wartości zero jest nieparzysta, do łańcucha jest dodawany kolejny bajt o wartości zero, aby otrzymać długość parzystą. Z tego powodu wartość Len jest obliczana jako ((StrLen+2)&~1).

26 jeśli Typ==1 String Jeśli Type == 1: Łańcuch z kończącym bajtem zerowym
32 lub 26+Len ... Następny element

Opinia na temat produktu | Dodatkowa dokumentacja | Znaki towarowe