IBM Lotus Symphony


Suplemento para Programação no Lotus Symphony Spreadsheets

Ícone de Aviso O método de estender o Lotus® Symphony™ Spreadsheets por Suplementos que é descrito a seguir está desatualizado. As interfaces ainda são válidas e suportadas para assegurar compatibilidade com Suplementos existentes mas, para programar novos Suplementos, você deve usar as novas funções da API.

O Lotus Symphony Spreadsheets pode ser expandido por Suplementos, que são módulos de programação externos que fornecem funções adicionais para o trabalho com planilhas. Eles estão listados no Assistente de Função na categoria Suplemento. Se você mesmo desejar programar um Suplemento, poderá aprender aqui quais funções devem ser exportadas pela DLL externa para que o Suplemento possa ser anexado com êxito.

O Lotus Symphony pesquisa a pasta do Suplemento definida na configuração para uma DLL apropriada. Para ser reconhecida pelo Lotus Symphony, a DLL deve ter algumas propriedades, conforme explicado a seguir. Estas informações permitem programar seu próprio Suplemento para o Assistente de Função do Lotus Symphony Spreadsheets.

O Conceito de Suplemento

Cada biblioteca do Suplemento fornece várias funções. Algumas funções são usadas para propósitos administrativos. É possível escolher entre qualquer nome para suas próprias funções. No entanto, elas também devem seguir algumas regras em relação à passagem de parâmetros. As convenções de nomenclatura e de chamada exatas variam para diferentes plataformas.

Funções da DLL do Suplemento

No mínimo, as funções administrativas GetFunctionCount e GetFunctionData devem existir. Ao usá-las, as funções e tipos de parâmetros e valores de retorno podem ser determinados. Como valores de retorno, os tipos Duplo e Sequência são suportados. Além disso, como parâmetros, as áreas de célula Matriz Dupla, Matriz de Sequência e Matriz de Célula são suportadas.

Os parâmetros são passados usando referências. Portanto, é basicamente possível uma mudança destes valores. No entanto, isto não é suportado no Lotus Symphony Spreadsheets porque não faz sentido em planilhas.

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

As funções são chamadas de forma síncrona e retornam seus resultados imediatamente. As funções em tempo real (funções assíncronas) também são possíveis; no entanto, elas não são explicadas detalhadamente devido à sua complexidade.

Informações Gerais sobre a Interface

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

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

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

No Windows: FAR PASCAL (_far _pascal)

Outro: padrão (padrão específico do sistema operacional)

USHORT Número inteiro de 2 bytes sem sinal
DOUBLE Formato de 8 bytes dependente da plataforma
Paramtype

Dependente da plataforma como int

PTR_DOUBLE =0 ponteiro para um duplo

PTR_STRING =1 ponteiro para uma sequência terminada em zero

PTR_DOUBLE_ARR =2 ponteiro para uma matriz dupla

PTR_STRING_ARR =3 ponteiro para uma matriz de sequência

PTR_CELL_ARR =4 ponteiro para uma matriz de célula

NONE =5

Funções da DLL

A seguir você encontrará uma descrição dessas funções, que são chamadas na DLL externa.

Para todas as funções da DLL, o seguinte se aplica:

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

Saída: Valor resultante

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

GetFunctionCount()

Retorna o número de funções sem as funções de gerenciamento do parâmetro de referência. Cada função tem um número exclusivo entre 0 e nCount-1. Posteriormente, este número será necessário 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 deve conter o número de funções de Suplemento. Por exemplo: Se o Suplemento fornecer 5 funções para o Lotus Symphony Spreadsheets, nCount=5.

GetFunctionData()

Determina todas as informações importantes sobre 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 da função conforme visto pelo programador, como é denominada na DLL. Este nome não determina o nome usado no Assistente de Função.

USHORT& nParamCount:

Saída: Número de parâmetros na função de Suplemento. Este número deve ser maior que 0, porque sempre há um valor de resultado; o valor máximo é 16.

Paramtype* peType:

Saída: Ponteiro para uma matriz de exatamente 16 variáveis de tipo Paramtype. As primeiras entradas nParamCount são preenchidas com o tipo de parâmetro apropriado.

char* pInternalName:

Saída: Nome da função conforme visto pelo usuário, como ele aparece no Assistente de Função. Pode conter tremas.

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

GetParameterDescription()

Fornece uma breve descrição da função de Suplemento e de seus parâmetros. Como uma opção, esta função pode ser usada para mostrar uma descrição de função e de parâmetro no Assistente de Função.

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 para qual parâmetro a descrição é fornecida; os parâmetros começam em 1. Se nParam for 0, a própria descrição deverá ser fornecida em pDesc; neste caso, pName não possui nenhum significado.

char* pName:

Saída: Aceita o nome ou tipo do parâmetro, por exemplo, a palavra "Número", ou "Sequência" ou "Data", e assim por diante. Implementado no Lotus Symphony Spreadsheets como char[256].

char* pDesc:

Saída: Aceita a descrição do parâmetro, por exemplo, "Valor, no qual o universo deve ser calculado." Implementado no Lotus Symphony Spreadsheets como char[256].

pName e pDesc são matrizes de caracteres; implementados no Lotus Symphony Spreadsheets com o tamanho 256. Observe que o espaço disponível no Assistente de Função é limitado e que os 256 caracteres não podem ser totalmente usados.

Áreas de Célula

As tabelas a seguir contêm informações sobre quais estruturas de dados devem ser fornecidas por um módulo de programa externo para passar áreas de célula. O Lotus Symphony Spreadsheets distingue entre três diferentes matrizes, dependendo do tipo de dado.

Matriz Dupla

Como um parâmetro, uma área de célula do tipo Número/Duplo pode ser passada. 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 começa em 0.
2 Linha1 Número da linha no canto superior esquerdo da área de célula; a numeração começa em 0.
4 Tab1 Número da tabela no canto superior esquerdo da área de célula; a numeração começa em 0.
6 Col2 Número da coluna no canto inferior direito da área de célula; a numeração começa em 0.
8 Linha2 Número da linha no canto inferior direito da área de célula; a numeração começa em 0.
10 Tab2 Número da tabela no canto inferior direito da área de célula; a numeração começa em 0.
12 Contagem Número dos seguintes elementos. Células vazias não são contadas ou passadas.
14 Col Número da coluna do elemento; a numeração começa em 0.
16 Linha Número da linha do elemento; a numeração começa em 0.
18 Tab Número da tabela do elemento; a numeração começa em 0.
20 Erro Número do erro, em que o valor 0 é definido como "nenhum erro." Se o elemento vier de uma célula de fórmula, o valor de erro será determinado pela fórmula.
22 Valor Variável IEEE de 8 bytes do tipo duplo/ponto flutuante
30 ... Próximo elemento

Matriz de Sequência

Uma área de célula, que contém valores de tipo de dado Text e é passada como uma matriz de sequência. Uma matriz de sequência no Lotus Symphony Lotus Symphony Spreadsheets é definida da seguinte forma:

Tabela 3. Definição de uma matriz de sequência
Deslocamento Nome Descrição
0 Col1 Número da coluna no canto superior esquerdo da área de célula; a numeração começa em 0.
2 Linha1 Número da linha no canto superior esquerdo da área de célula; a numeração começa em 0.
4 Tab1 Número da tabela no canto superior esquerdo da área de célula; a numeração começa em 0.
6 Col2 Número da coluna no canto inferior direito da área de célula; a numeração começa em 0.
8 Linha2 Número da linha no canto inferior direito da área de célula; a numeração começa em 0.
10 Tab2 Número da tabela no canto inferior direito da área de célula; a numeração começa em 0.
12 Contagem Número dos seguintes elementos. Células vazias não são contadas ou passadas.
14 Col Número da coluna do elemento; a numeração começa em 0.
16 Linha Número da linha do elemento; a numeração começa em 0.
18 Tab Número da tabela do elemento; a numeração começa em 0.
20 Erro Número do erro, em que o valor 0 é definido como "nenhum erro." Se o elemento vier de uma célula de fórmula, o valor de erro será determinado pela fórmula.
22 Len Comprimento da seguinte sequência, incluindo o byte zero de fechamento. Se o comprimento, incluindo o byte zero de fechamento, for igual a um valor ímpar, um segundo byte zero será adicionado à sequência para que seja obtido um valor par. Portanto, Len é calculado usando ((StrLen+2)&~1).
24 Sequência Sequência com byte zero de fechamento
24+Len ... Próximo elemento

Matriz de Célula

As matrizes de célula são usadas para chamar áreas de célula contendo texto e números. Uma matriz de célula no Lotus Symphony Spreadsheets é definida da seguinte forma:

Tabela 4. Definição de uma matriz de célula
Deslocamento Nome Descrição
0 Col1 Número da coluna no canto superior esquerdo da área de célula; a numeração começa em 0.
2 Linha1 Número da linha no canto superior esquerdo da área de célula; a numeração começa em 0.
4 Tab1 Número da tabela no canto superior esquerdo da área de célula; a numeração começa em 0.
6 Col2 Número da coluna no canto inferior direito da área de célula; a numeração começa em 0.
8 Linha2 Número da linha no canto inferior direito da área de célula; a numeração começa em 0.
10 Tab2 Número da tabela no canto inferior direito da área de célula; a numeração começa em 0.
12 Contagem Número dos seguintes elementos. Células vazias não são contadas ou passadas.
14 Col Número da coluna do elemento. A numeração começa em 0.
16 Linha Número da linha do elemento; a numeração começa em 0.
18 Tab Número da tabela do elemento; a numeração começa em 0.
20 Erro Número do erro, em que o valor 0 é definido como "nenhum erro." Se o elemento vier de uma célula de fórmula, o valor de erro será determinado pela fórmula.
22 Tipo Tipo de conteúdo da célula, 0 == Duplo, 1 == Sequência
24 Valor ou Len

Se tipo == 0: variável IEEE de 8 bytes de tipo duplo/ponto flutuante

Se tipo == 1: Comprimento da seguinte sequência, incluindo o byte zero de fechamento. Se o comprimento, incluindo o byte zero de fechamento, for igual a um valor ímpar, um segundo byte zero será adicionado à sequência para que seja obtido um valor par. Portanto, Len é calculado usando ((StrLen+2)&~1).

26 se tipo==1 Sequência Se tipo == 1: Cadeia com byte zero de fechamento
32 ou 26+Len ... Próximo elemento

Feedback do Produto | Documentação Adicional | Marcas Registradas