IBM Lotus Symphony


Fórmulas de suplemento para Programação no Lotus Symphony Spreadsheets

ícone de Aviso O método de expandir o Lotus® Symphony™ Spreadsheets através de Suplementos descrito a seguir está, neste momento, obsoleto. As interfaces ainda são válidas e suportadas, de modo a assegurar a compatibilidade com Suplementos existentes, mas para programar novos suplementos deverá utilizar as novas Funções da API.

O Lotus Symphony Spreadsheets pode ser expandido por Suplementos, que consistem em módulos de programação internos que fornecem funções adicionais para trabalhar com folhas de cálculo. Estas encontram-se apresentadas no Assistente de funções, na categoria de Suplementos. Se pretender programar um Suplemento, pode aprender aqui quais as funções que têm de ser exportadas pelo DLL externo, para que o Suplemento seja anexado com êxito.

O Lotus Symphony procura a pasta de Suplementos definida na configuração por um DLL adequado. Para que seja reconhecido pelo Lotus Symphony, o DLL tem de possuir determinadas propriedades, conforme explicado nas informações que se seguem. Estas informações permitem-lhe programar o seu próprio Suplemento para o Assistente de funções do Lotus Symphony Spreadsheets.

O conceito do Suplemento

Cada biblioteca de Suplementos permite a utilização de várias funções. Algumas destas funções são utilizadas para finalidades administrativas. Pode seleccionar virtualmente qualquer nome para as suas funções. No entanto, é necessário que algumas regras sejam seguidas, relativamente à passagem de parâmetros. As convenções de nome e chamada exactas variam consoante a plataforma.

Funções de DLL de suplemento

No mínimo, as funções administrativas GetFunctionCount e GetFunctionData têm de existir. Utilizando estas funções, é possível determinar as funções bem como os tipos de parâmetro e os valores de retorno. Como valores de retorno, são suportados os tipos Double e String. Como parâmetros, são também suportadas as áreas de célula Matriz dupla, Matriz de cadeia e Matriz de célula.

Os parâmetros são passados utilizando referências. Por este motivo, é possível uma alteração destes valores. No entanto, isto não é suportado no Lotus Symphony Spreadsheets uma vez que esta situação não faz sentido em folhas de cálculo.

As bibliotecas podem ser carregadas durante o tempo de execução e o respectivo conteúdo pode ser analisado pelas funções administrativas. Para cada função, as informações estão disponíveis acerca da contagem e tipo de parâmetros, nomes de funções internas ou externas e um número administrativo.

As funções são activadas de forma síncrona e devolvem os respectivos resultados imediatamente. As funções em tempo real (funções assíncronas) são também possíveis. No entanto, não são explicadas em detalhe devido à respectiva complexidade.

Informações gerais acerca da interface

O número máximo de parâmetros numa função de Suplemento anexada ao Lotus Symphony Spreadsheets é de 16: um valor de retorno e um máximo de 15 parâmetros de entrada de funções.

Os tipos de dados são definidos da seguinte forma:

Tabela 1. Definições de tipo de dados
Tipo de dados Definição
CALLTYPE

Em Windows: FAR PASCAL (_far _pascal)

Outro: predefinição (predefinição específica do sistema operativo)

USHORT Valor inteiro não assinado de 2 bytes
DOUBLE Formato dependente da plataforma de 8 bytes
Paramtype

Dependente da plataforma, tal como int

PTR_DOUBLE =0 ponteiro relativo a um valor duplo

PTR_STRING =1 ponteiro relativo a uma cadeia terminada em zero

PTR_DOUBLE_ARR =2 ponteiro relativo a uma matriz dupla

PTR_STRING_ARR =3 ponteiro relativo a uma matriz de cadeia

PTR_CELL_ARR =4 ponteiro relativo a uma matriz de célula

NONE =5

Funções DLL

Em seguida, poderá encontrar uma descrição destas funções, activadas no DLL externo.

Para todas as funções DLL, aplicam-se os seguintes valores:

void CALLTYPE fn(out, in1, in2, ...)

Saída: Valores resultantes

Entrada: Qualquer número de tipos (double&, char*, double*, char**, área de célula), em que a Área de célula corresponda a uma matriz de tipos de matriz dupla, matriz de cadeia ou matriz de célula.

GetFunctionCount()

Devolve o número de funções sem as funções de gestão do parâmetro de referência. Cada função possui um número exclusivo entre 0 e nCount-1. Este número será necessário num momento posterior para as funções GetFunctionData e GetParameterDescription.

Sintaxe

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parâmetro

USHORT &nCount:

Saída: Referência a uma variável, que supostamente contém o número de funções de Suplemento. Por exemplo, se o Suplemento fornecer 5 funções para o Lotus Symphony Spreadsheets, então o resultado é nCount=5.

GetFunctionData()

Determina as todas informações importantes acerca de uma função de Suplemento.

Sintaxe

void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)

Parâmetro

USHORT& nNo:

Entrada: Número de função entre 0 e nCount-1, inclusive.

char* pFuncName:

Saída: Nome de função, tal como visualizada pelo programador, conforme denominação no DLL. Este nome não determina o nome utilizado no Assistente de funções.

USHORT& nParamCount:

Saída: Número de parâmetros na função de Suplemento. Este número tem de ser superior a 0, uma vez que existe sempre um valor de resultado. O valor máximo é de 16.

Paramtype* peType:

Saída: Ponteiro numa matriz com exactamente 16 variáveis do tipo Paramtype. As primeiras entradas nParamCount são preenchidas com o tipo adequado de parâmetro.

char* pInternalName:

Saída: Nome da função, tal como visualizada pelo utilizador, conforme denominação no Assistente de funções. Poderá conter tremas.

Os parâmetros pFuncName e pInternalName são matrizes "char", implementadas com tamanho 256 no Lotus Symphony Spreadsheets.

GetParameterDescription()

Fornece uma breve descrição da função de Suplemento e respectivos parâmetros. Como opção, esta função pode ser utilizada para apresentar uma função e correspondente descrição de parâmetros no Assistente de funções.

Sintaxe

void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

Parâmetro

USHORT& nNo:

Entrada: Número da função na biblioteca, entre 0 e nCount-1.

USHORT& nParam:

Entrada: Indica o parâmetro a que diz respeito a descrição apresentada. Os parâmetros começam no número 1. Se nParam corresponder a 0, assume-se que a descrição é fornecida em pDesc. Neste caso, pName não tem qualquer significado.

char* pName:

Saída: Assume o parâmetro, nome ou tipo, por exemplo, a palavra "Número" ou "Cadeia" ou "Data", e assim sucessivamente. Implementado no Lotus Symphony Spreadsheets como char[256].

char* pDesc:

Saída: Assume a descrição do parâmetro, por exemplo, "Valor em relação ao qual se pretende calcular o universo". Implementado no Lotus Symphony Spreadsheets como char[256].

pName e pDesc são matrizes char; implementado no Lotus Symphony Spreadsheets com o tamanho 256. Tenha em atenção que o espaço disponível no Assistente de funções está limitado e que os 256 caracteres não podem ser utilizados na sua totalidade.

Áreas de célula

As tabelas que se seguem contêm informações acerca das estruturas de dados que têm de ser fornecidas por um módulo de programa externo, de modo a transferir áreas de células. O Lotus Symphony Spreadsheets distingue entre três matrizes diferentes, dependendo do tipo de dados.

Matriz dupla

É possível transferir uma área de célula com valores do tipo Number/Double. Uma matriz dupla no Lotus Symphony Spreadsheets é definida da seguinte forma:

Tabela 2. Definição de uma matriz dupla
Deslocamento Nome Descrição
0 Col1 Número da coluna no canto superior esquerdo da área de célula; a numeração tem início no 0.
2 Linha1 Número da linha no canto superior esquerdo da área de célula; a numeração inicia-se no 0.
4 Tab1 Número da tabela no canto superior esquerdo da área de célula; a numeração tem início no 0.
6 Col2 Número da coluna no canto inferior direito da área de célula; a numeração tem início no 0.
8 Linha2 Número da linha no canto inferior direito da área de célula; a numeração tem início no 0.
10 Tab2 O número da tabela no canto inferior direito da área da célula; a numeração tem início no 0.
12 Contar O número dos seguintes elementos. As células vazias não são contadas ou transferidas.
14 Col O número da coluna do elemento; a numeração tem início no 0.
16 Linha O número da linha do elemento; a numeração tem início no 0.
18 Tab O número da tabela do elemento; a numeração tem início no 0.
20 Erro O número do erro, em que o valor de 0 é definido como "sem erros". Se o elemento for proveniente de uma célula de fórmulas, o valor do erro é determinado por uma fórmula.
22 Valor Variável IEEE de 8 bytes do tipo duplo/vírgula flutuante
30 ... Elemento seguinte

Matriz de cadeia

Uma área de célula, a qual contém os valores do tipo de dados Text e que é transferida como uma matriz de cadeia. Uma matriz de cadeia no Lotus Symphony Lotus Symphony Spreadsheets é definida da seguinte forma:

Tabela 3. Definição de uma matriz de cadeia
Deslocamento Nome Descrição
0 Col1 Número da coluna no canto superior esquerdo da área de célula; a numeração tem início no 0.
2 Linha1 Número da linha no canto superior esquerdo da área de célula; a numeração inicia-se no 0.
4 Tab1 Número da tabela no canto superior esquerdo da área de célula; a numeração tem início no 0.
6 Col2 Número da coluna no canto inferior direito da área de célula; a numeração tem início no 0.
8 Linha2 Número da linha no canto inferior direito da área de célula; a numeração tem início no 0.
10 Tab2 O número da tabela no canto inferior direito da área da célula; a numeração tem início no 0.
12 Contar O número dos seguintes elementos. As células vazias não são contadas ou transferidas.
14 Col O número da coluna do elemento; a numeração tem início no 0.
16 Linha O número da linha do elemento; a numeração tem início no 0.
18 Tab O número da tabela do elemento; a numeração tem início no 0.
20 Erro O número do erro, em que o valor de 0 é definido como "sem erros". Se o elemento for proveniente de uma célula de fórmulas, o valor do erro é determinado por uma fórmula.
22 Len Comprimento da cadeia seguinte, incluindo o byte zero final. Se o comprimento, incluindo o byte zero final, for igual a um valor ímpar, é adicionado um segundo byte zero à cadeia para obter um valor par. Por este motivo, Len é calculado através de ((StrLen+2)&~1).
24 String Cadeia com byte zero final
24+Len ... Elemento seguinte

Matriz de célula

As matrizes de célula são utilizadas para activar áreas de célula que contêm texto bem como números. Uma matriz de célula no Lotus Symphony Spreadsheets é definida da seguinte forma:

Tabela 4. Definição de uma matriz de células
Deslocamento Nome Descrição
0 Col1 Número da coluna no canto superior esquerdo da área de célula; a numeração tem início no 0.
2 Linha1 Número da linha no canto superior esquerdo da área de célula; a numeração inicia-se no 0.
4 Tab1 Número da tabela no canto superior esquerdo da área de célula; a numeração tem início no 0.
6 Col2 Número da coluna no canto inferior direito da área de célula; a numeração tem início no 0.
8 Linha2 Número da linha no canto inferior direito da área de célula; a numeração tem início no 0.
10 Tab2 O número da tabela no canto inferior direito da área da célula; a numeração tem início no 0.
12 Contar O número dos seguintes elementos. As células vazias não são contadas ou transferidas.
14 Col Número de coluna do elemento. A numeração tem início no 0.
16 Linha O número da linha do elemento; a numeração tem início no 0.
18 Tab O número da tabela do elemento; a numeração tem início no 0.
20 Erro O número do erro, em que o valor de 0 é definido como "sem erros". Se o elemento for proveniente de uma célula de fórmulas, o valor do erro é determinado por uma fórmula.
22 Tipo Tipo do conteúdo da célula, 0 == Duplo, 1 == Cadeia
24 Valor ou Len

Se type == 0: variável IEEE de 8 bytes de tipo duplo/vírgula flutuante

Se type == 1: Comprimento da cadeia seguinte, incluindo o byte zero final. Se o comprimento, incluindo o byte zero final, for igual a um valor ímpar, é adicionado um segundo byte zero à cadeia para obter um valor par. Por este motivo, Len é calculado através de ((StrLen+2)&~1).

26 se type==1 String Se type == 1: Cadeia com byte zero final
32 ou 26+Len ... Elemento seguinte

Comentários sobre o produto | Documentação adicional | Marcas comerciais