IBM Lotus Symphony
|
![]() |
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.
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.
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.
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:
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 |
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.
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.
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.
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.
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.
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:
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 |
Á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:
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 |
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:
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 |