IBM Lotus Symphony


Add-in para programar en Lotus Symphony Spreadsheets

Icono de advertencia El método para ampliar Lotus® Symphony™ Spreadsheets con add-ins que se describe a continuación es obsoleto. Las interfaces aún son válidas y se admiten, para garantizar la compatibilidad con los add-ins existentes, pero para programar nuevos add-ins debe utilizar las nuevas funciones de API.

Lotus Symphony Spreadsheets puede ampliarse con add-ins, que son módulos de programación externos que proporcionan funciones adicionales para trabajar con hojas de cálculo. Se listan en el Asistente de funciones en la categoría Add In. Si desea programar personalmente un add-in, puede obtener aquí información sobre las funciones que debe exportar la DLL externa para que el add-in se pueda adjuntar correctamente.

Lotus Symphony busca en la carpeta de add-ins definida en la configuración la DLL adecuada. Para que Lotus Symphony la reconozca, la DLL debe tener ciertas propiedades, como se explica a continuación. Esta información permite programar un add-in propio para el Asistente de funciones de Lotus Symphony Spreadsheets.

Concepto de add-in

Cada biblioteca de add-ins proporciona varias funciones. Algunas funciones se utilizan con fines administrativos. Puede seleccionar prácticamente cualquier nombre para sus funciones. Deben seguir, no obstante, reglas concretas en cuanto al paso de parámetros. La denominación exacta y los convenios de denominación varían para las distintas plataformas.

Funciones de la DLL de add-ins

Como mínimo, deben existir las funciones administrativas GetFunctionCount y GetFunctionData. Con estas funciones, se pueden determinar las funciones, así como los tipos de parámetros y los valores de retorno. Como valores de retorno, se admiten los tipos Double y String. Como parámetros, se admiten las áreas de celdas Double Array, String Array y Cell Array.

Los parámetros se pasan mediante referencias. Por lo tanto, un cambio en estos valores básicamente es posible. No obstante, esto no se admite en Lotus Symphony Spreadsheets porque no tiene sentido dentro de las hojas de cálculo.

Las bibliotecas se pueden volver a cargar en tiempo de ejecución y su contenido se puede analizar mediante las funciones administrativas. Para cada función, hay información disponible sobre el recuento y el tipo de parámetros, los nombres de funciones internas y externas y un número administrativo.

Se llama a las funciones de forma síncrona y devuelven sus resultados de inmediato. Las funciones en tiempo real (funciones asíncronas) también son posibles; sin embargo, no se explican detalladamente a causa de su complejidad.

Información general acerca de la interfaz

El número máximo de parámetros en una función de add-in adjuntada a Lotus Symphony Spreadsheets es 16: un valor de retorno y un máximo de 15 parámetros de entrada.

Los tipos de datos se definen de la manera siguiente:

Tabla 1. Definiciones de tipo de datos
Tipo de datos Definición
CALLTYPE

En Windows: FAR PASCAL (_far _pascal)

Otros: valor predeterminado (valor predeterminado específico del sistema operativo)

USHORT Entero sin signo de 2 bytes
DOUBLE Formato dependiente de la plataforma de 8 bytes
Paramtype

Enter de tipo dependiente de la plataforma

PTR_DOUBLE =puntero 0 a un doble

PTR_STRING =puntero 1 a una cadena terminada en cero

PTR_DOUBLE_ARR =puntero 2 a una matriz doble

PTR_STRING_ARR =puntero 3 a una matriz de cadenas

PTR_CELL_ARR =puntero 4 a una matriz de celdas

NONE =5

Funciones de DLL

A continuación encontrará una descripción de estas funciones, a las que se llama en la DLL externa.

Se aplica lo siguiente para todas las funciones de DLL:

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

Salida: valor resultante

Entrada: cualquier número de tipos (double&, char*, double*, char**, área de celda), donde el área de celda es una matriz de tipos double array, string array o cell array.

GetFunctionCount()

Devuelve el número de funciones sin las funciones de gestión del parámetro de referencia. Cada función tiene un número exclusivo entre 0 y nCount-1. Este número será necesario para las funciones GetFunctionData y GetParameterDescription más adelante.

Sintaxis

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parámetro

USHORT &nCount:

Salida: referencia a una variable, que se supone que contiene el número de funciones de add-ins. Por ejemplo: si el add-in proporciona 5 funciones para Lotus Symphony Spreadsheets, nCount=5.

GetFunctionData()

Determina toda la información importante acerca de una función de add-in.

Sintaxis

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

Parámetro

USHORT& nNo:

Entrada: número de función entre 0 y nCount-1, ambos incluidos.

char* pFuncName:

Salida: nombre de función según lo ve el programador, tal como se denomina en la DLL. Este nombre no determina el nombre que se utiliza en el Asistente de funciones.

USHORT& nParamCount:

Salida: nombre de parámetros en la función de add-in. Este número debe ser superior a 0, porque siempre hay un valor de resultado; el valor máximo es 16.

Paramtype* peType:

Salida: puntero a una matriz de exactamente 16 variables de tipo Paramtype. Las primeras entradas cuyo número indica nParamCount se llenan con el tipo adecuado de parámetro.

char* pInternalName:

Salida: nombre de función según lo ve el usuario, tal como aparece en el Asistente de funciones. Puede contener diéresis.

Los parámetros pFuncName y pInternalName son matrices de caracteres, que se implementan con el tamaño 256 en Lotus Symphony Spreadsheets.

GetParameterDescription()

Proporciona una breve descripción de la función de add-in y sus parámetros. Como opción, esta función se puede utilizar para mostrar una descripción de la función y el parámetro en el Asistente de funciones.

Sintaxis

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

Parámetro

USHORT& nNo:

Entrada: número de la función en la biblioteca; entre 0 y nCount-1.

USHORT& nParam:

Entrada: indica para qué parámetro se proporciona la descripción; los parámetros empiezan en 1. Si nParam es 0, se supone que se proporciona la propia descripción en pDesc; en tal caso, pName no tiene ningún significado.

char* pName:

Salida: acepta el nombre o el tipo de parámetro, por ejemplo, la palabra "Número" o "Cadena" o "Fecha", etc. Se implementa en Lotus Symphony Spreadsheets como char[256].

char* pDesc:

Salida: acepta la descripción del parámetro, por ejemplo "Valor en el que se debe calcular el universo". Se implementa en Lotus Symphony Spreadsheets como char[256].

pName y pDesc son matrices de caracteres; se implementan en Lotus Symphony Spreadsheets con el tamaño 256. Tenga en cuenta que el espacio disponible en el Asistente de funciones es limitado y que los caracteres de 256 no se pueden utilizar completamente.

Áreas de celdas

Las tablas siguientes contienen información acerca de las estructuras de datos que debe proporcionar un módulo de programa externo para pasar áreas de celdas. Lotus Symphony Spreadsheets distingue entre tres matrices distintas, en función del tipo de datos.

Matriz doble

Como parámetro, se puede pasar un área de celdas con valores del tipo Number/Double. Una matriz doble en Lotus Symphony Spreadsheets se define de la manera siguiente:

Tabla 2. Definición de una matriz doble
Desplazamiento Nombre Descripción
0 Col1 Número de columna en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
2 Row1 Número de fila en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
4 Tab1 Número de tabla en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
6 Col2 Número de columna en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
8 Row2 Número de fila en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
10 Tab2 Número de tabla en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
12 Contar Número de los elementos siguientes. Las celdas vacías no se cuentan ni se pasan.
14 Col Número de columna del elemento; la numeración empieza en 0.
16 Fila Número de fila del elemento; la numeración empieza en 0.
18 Tabulador Número de tabla del elemento; la numeración empieza en 0.
20 Error Número de error, donde el valor 0 se definirá como "sin error". Si el elemento procede de una celda de fórmula, el valor de error lo determina la fórmula.
22 Valor Variable IEEE de 8 bytes de tipo doble/coma flotante
30 ... Siguiente elemento

Matriz de cadenas

Área de celdas, que contiene los valores de tipo de datos Texto y se pasa como matriz de cadenas. Una matriz de cadenas en Lotus Symphony Lotus Symphony Spreadsheets se define como se indica a continuación:

Tabla 3. Definición de una matriz de series
Desplazamiento Nombre Descripción
0 Col1 Número de columna en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
2 Row1 Número de fila en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
4 Tab1 Número de tabla en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
6 Col2 Número de columna en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
8 Row2 Número de fila en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
10 Tab2 Número de tabla en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
12 Contar Número de los elementos siguientes. Las celdas vacías no se cuentan ni se pasan.
14 Col Número de columna del elemento; la numeración empieza en 0.
16 Fila Número de fila del elemento; la numeración empieza en 0.
18 Tabulador Número de tabla del elemento; la numeración empieza en 0.
20 Error Número de error, donde el valor 0 se definirá como "sin error". Si el elemento procede de una celda de fórmula, el valor de error lo determina la fórmula.
22 Len Longitud de la cadena siguiente, incluido el byte cero de cierre. Si la longitud, incluido el byte zero de cierre, equivale a un valor impar, se agrega un segundo cero a la cadena para conseguir un valor par. Por lo tanto, Len se calcula mediante ((StrLen+2)&~1).
24 Cadena Cadena con byte cero de cierre
24+Len ... Siguiente elemento

Matriz de celdas

Las matrices de celdas se utilizan para llamar a áreas de celdas que contienen texto, así como números. Una matriz de celdas en Lotus Symphony Spreadsheets se define de la manera siguiente:

Tabla 4. Definición de una matriz de celdas
Desplazamiento Nombre Descripción
0 Col1 Número de columna en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
2 Row1 Número de fila en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
4 Tab1 Número de tabla en la esquina superior izquierda del área de celdas; la numeración empieza en 0.
6 Col2 Número de columna en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
8 Row2 Número de fila en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
10 Tab2 Número de tabla en la esquina inferior derecha del área de celdas; la numeración empieza en 0.
12 Contar Número de los elementos siguientes. Las celdas vacías no se cuentan ni se pasan.
14 Col Número de columna del elemento. La numeración empieza en 0.
16 Fila Número de fila del elemento; la numeración empieza en 0.
18 Tabulador Número de tabla del elemento; la numeración empieza en 0.
20 Error Número de error, donde el valor 0 se definirá como "sin error". Si el elemento procede de una celda de fórmula, el valor de error lo determina la fórmula.
22 Tipo Tipo de contenido de la celda, 0 == Double, 1 == String
24 Valor o Len

Si tipo == 0: variable IEEE de 8 bytes de tipo doble/coma flotante.

Si tipo == 1: longitud de la cadena siguiente, incluido el byte cero de cierre. Si la longitud, incluido el byte zero de cierre, equivale a un valor impar, se agrega un segundo cero a la cadena para conseguir un valor par. Por lo tanto, Len se calcula mediante ((StrLen+2)&~1).

26 si tipo==1 Cadena Si tipo == 1: cadena con byte cero de cierre
32 o 26+Len ... Siguiente elemento

Comentarios del producto | Documentación adicional | Marcas registradas