27 de febrero de 1997
Introducción
Debido a la necesidad expuesta por los desarrolladores de bases de datos paramétricas de ampliar las posibilidades del lenguaje de descripción paramétrica, poder compilar éste por eficiencia y protección de datos y posibilitar la protección contra copia de bases de datos paramétricas, se establece la siguiente especificación.
En este documento se definen los componentes necesarios para el desarrollo de descripciones paramétricas en cualquier lenguaje de aplicaciones para Windows (C, C++, Pascal, Fortran, etc.) y sin ninguna limitación. Se incluye la definición de un API estándar en C, un ejemplo de base de datos en formato DLL de 32 bits desarrollado en C++ y un ejemplo de aplicación con la implementación del interfaz con el API en C, definidos ambos en Microsoft Visual C++. Se podría implementar el interfaz con el API para otros compiladores y lenguajes para acceder a las mismas DLL.
Es decir; es posible construir una base de datos que cumpla este API utilizando para ello cualquier lenguaje de programación que permita desarrollar librerías de enlace dinámico Windows (DLL). Asimismo, es posible construir un programa que lea cualquier base de datos de estas características utilizando lenguajes de aplicaciones para Windows.
Archivos que debe contener una Base de datos
Una base de datos que se desee distribuir con las definiciones paramétricas compiladas en DLL, debe contener los siguientes archivos:
base.dll En este archivo, único para cada base de datos y de nombre cualquiera pero extensión ‘..DLL’, se encuentran las funciones del API que la base de datos ofrece a las aplicaciones para que éstas obtengan la información que contiene la base.
base.bc3 Archivo o archivos ASCII de la base de datos en formato FIEBDC-3/98. Los registros '~P' de los conceptos cuya descripción paramétrica se acceda a través del archivo ‘base.dll’, tendrán el campo ‘DESCRIPCIÓN_PARAMÉTRICA’ vacío. Ejemplo:
~P|ABCD12$| |
El registro '~P' correspondiente al paramétrico global, tendrá el campo ‘DESCRIPCIÓN_PARAMÉTRICA’ vacío, y tendrá un tercer campo con el nombre del archivo DLL en el que se encuentren las funciones del API de la base. Ejemplo:
~P| | | BASE.DLL |
La definición paramétrica de los conceptos implementados de esta forma podrá estar en el mismo archivo que las funciones del API (el archivo ‘base.dll’) o situado en otro u otros archivos cualesquiera, conforme desee el desarrollador de la base de datos. Las aplicaciones sólo accederán a las funciones del API incluidas en el archivo ‘base.dll’, y éstas serán las encargadas de acceder a la información en la forma que el desarrollador de la base implemente.
Definición del API: fiebdc.h
Único archivo que define el estándar. En este archivo se define el API en C, que las descripciones paramétricas en DLL ofrecen a las aplicaciones. Este interfaz permite definiciones paramétricas de ilimitado número de parámetros e ilimitadas opciones por parámetro. Se soportan dos modelos de codificaciones:
Un modelo de codificación independiente de parámetros, en el que el código de un concepto paramétrico es completamente libre y el número de caracteres del código es independiente del número de parámetros.
Un modelo dependiente de los mismos. Es el modelo que definía FIEBDC-3/95 y en el que el código de un concepto paramétrico debe tener un símbolo ‘$’ en su séptima posición y en el que se asigna de la 'a' a la 'z' las opciones 0 a 25 de cada parámetro, ampliándose en esta versión con los rangos 'A' a 'Z' y '0' a '9' para que el número de opciones por parámetro en este modelo codificación pase a 62 (de 0 a 61).
Para que los programas puedan determinar si una base de datos responde a uno u otro modelo, se ha definido la función BdcCodificacion(), que se especifica más adelante y que indica si el sistema de codificación usado en la base de datos es dependiente o independiente.
Si se adopta el primer modelo, no es posible averiguar ‘a priori’, a partir de un código ‘ABCDEFGHIJ’ de concepto, si éste es un derivado paramétrico ni de que concepto paramétrico procede o con qué valores de sus parámetros. Por ello, es establece el siguiente criterio de búsqueda:
Si el concepto existe con este código en la base, se escogerá dicho concepto.
En caso de no existir, se intentará localizarlo en la base de datos como perteneciente a un concepto paramétrico ‘al estilo’ FIEBDC-3/95. En el ejemplo, se intentará buscar el concepto paramétrico ‘ABCDEF$’ y pasarle los parámetros ‘GHIJ’ (que implica pasarle a sus cuatro parámetros valores ‘31’, ‘32’, ‘33’ y ‘34’ respectivamente).
En caso de no existir, se intentará localizarlo en la DLL. Si ésta posee un modelo de codificación dependiente, se utilizará el mismo criterio que en el punto anterior: en el ejemplo, buscar el concepto paramétrico ‘ABCDEF$’ y pasarle los parámetros ‘GHIJ’. Si la base posee un modelo independiente, se utilizará la función ‘BdcDecodifica()’, tal como se especifica más adelante.
Si no se cumplen ninguna de las condiciones anteriores, se supone que el concepto no existe en la base.
El archivo ‘fiebdc.h’ tiene el siguiente contenido:
/* FORMATO DE INTERCAMBIO ESTÁNDAR DE PARAMÉTRICOS EN DLL */
/* FIEBDC-3/98 */
#include <windows.h>
#ifndef FIEBDC_H
#define FIEBDC_H
#ifdef BASE /* definido si se desea construir la DLL */
/****************************************************************************/
/* PARTE DEL ARCHIVO NECESARIA PARA LOS DESARROLLADORES DE BASE DE DATOS */
/****************************************************************************/
/****************************************************************************/
/* MACROS DEPENDIENTES DEL COMPILADOR */
#if defined (__BORLANDC__) /* Borland C++ */
#define EXPORTA FAR _export
#elif defined (_MSC_VER) /* Microsoft C */
#define EXPORTA
#else /* Otros */
#define EXPORTA
#endif
#ifdef __cplusplus
extern "C" {
#endif
/* 0 FUNCIONES GENERALES *************************************************/
LONG EXPORTA BdcCodificacion (VOID);
/* 1 FUNCIONES REFERENTES AL PARAMÉTRICO GLOBAL *************************/
/* 1.1 Accesibles en cualquier momento */
/* 1.1.1 Obtención de sus parámetros */
LONG EXPORTA BdcGloParNumero (VOID);
LONG EXPORTA BdcGloOpcNumero (LONG par);
LPCSTR EXPORTA BdcGloParRotulo (LONG par);
LPCSTR EXPORTA BdcGloOpcRotulo (LONG par, LONG opc);
/* 2.1.3 Mensajes / códigos de error */
BOOL EXPORTA BdcGloError (LPCSTR *err);
/* 1.1.2 Asignación de opciones a los parámetros */
BOOL EXPORTA BdcGloCalcula (LPLONG opcl);
/* 2 FUNCIONES REFERENTES AL RESTO DE PARAMÉTRICOS ***********************/
/* 2.1 Accesibles en cualquier momento */
/* 2.1.1 Lectura de un concepto paramétrico */
HANDLE EXPORTA BdcLee (LPCSTR cod);
/* 2.1.2 Lectura de un concepto paramétrico a partir del código del derivado */
HANDLE EXPORTA BdcDecodifica (LPCSTR cod, LPLONG opcl);
/* 2.1.3 Mensajes / códigos de error */
BOOL EXPORTA BdcError (HANDLE h, LPCSTR *err);
/* 2.2 Accesibles después de BdcLee */
/* 2.2.1 Obtención de sus parámetros */
LONG EXPORTA BdcParNumero (HANDLE h);
LONG EXPORTA BdcOpcNumero (HANDLE h, LONG par);
LPCSTR EXPORTA BdcParRotulo (HANDLE h, LONG par);
LPCSTR EXPORTA BdcOpcRotulo (HANDLE h, LONG par, LONG opc);
/* 2.2.2 Obtención de un comentario */
LPCSTR EXPORTA BdcComentario (HANDLE h);
/* 2.2.3 Asignación de opciones de los parámetros y cálculo/chequeo del derivado */
BOOL EXPORTA BdcValida (HANDLE h, LPLONG opcl);
BOOL EXPORTA BdcCalcula (HANDLE h, LPLONG opcl);
/* 2.2.4 Liberación de memoria */
BOOL EXPORTA BdcCierra (HANDLE h);
/* 2.3 Accesibles después de BdcCalcula */
/* 2.3.1 Obtención del derivado paramétrico */
LONG EXPORTA BdcDesNumero (HANDLE h);
LPCSTR EXPORTA BdcDesCodigo (HANDLE h, LONG des);
BOOL EXPORTA BdcRendimiento (HANDLE h, LONG des, double FAR *ren);
BOOL EXPORTA BdcPrecio (HANDLE h, double FAR *pre);
LPCSTR EXPORTA BdcCodigo (HANDLE h);
LPCSTR EXPORTA BdcResumen (HANDLE h);
LPCSTR EXPORTA BdcTexto (HANDLE h);
LPCSTR EXPORTA BdcPliego (HANDLE h);
LPCSTR EXPORTA BdcClaves (HANDLE h);
#ifdef __cplusplus
}
#endif
#else /* BASE no definido */
/****************************************************************************/
/* PARTE DEL ARCHIVO NECESARIA PARA LOS DESARROLLADORES DE PROGRAMAS */
/****************************************************************************/
/****************************************************************************/
/* MACROS DEPENDIENTES DEL COMPILADOR */
#if defined (__BORLANDC__) /* Borland C++ */
#define IMPORTA FAR _import
#elif defined (_MSC_VER) /* Microsoft C */
#define IMPORTA
#else /* Otros */
#define IMPORTA
#endif
/* FUNCIONES GENERALES *****************************************************/
typedef LONG (IMPORTA * BDCCODIFICACION) (VOID);
/* FUNCIONES REFERENTES AL PARAMÉTRICO GLOBAL *****************************/
typedef LONG (IMPORTA * BDCGLOPARNUMERO) (VOID);
typedef LONG (IMPORTA * BDCGLOOPCNUMERO) (LONG par);
typedef LPCSTR (IMPORTA * BDCGLOPARROTULO) (LONG par);
typedef LPCSTR (IMPORTA * BDCGLOOPCROTULO) (LONG par, LONG opc);
typedef BOOL (IMPORTA * BDCGLOERROR) (LPCSTR *err);
typedef BOOL (IMPORTA * BDCGLOCALCULA) LPLONG opcl);
/* FUNCIONES REFERENTES AL RESTO DE PARAMÉTRICOS *************************/
typedef HANDLE (IMPORTA * BDCLEE) (LPCSTR cod);
typedef HANDLE (IMPORTA * BDCDECODIFICA) (LPCSTR cod, LPLONG opcl);
typedef BOOL (IMPORTA * BDCERROR) (HANDLE h, LPCSTR *err);
typedef LONG (IMPORTA * BDCPARNUMERO) (HANDLE h);
typedef LONG (IMPORTA * BDCOPCNUMERO) (HANDLE h, LONG par);
typedef LPCSTR (IMPORTA * BDCPARROTULO) (HANDLE h, LONG par);
typedef LPCSTR (IMPORTA * BDCOPCROTULO) (HANDLE h, LONG par, LONG opc);
typedef LPCSTR (IMPORTA * BDCCOMENTARIO) (HANDLE h);
typedef BOOL (IMPORTA * BDCVALIDA) (HANDLE h, LPLONG opcl);
typedef BOOL (IMPORTA * BDCCALCULA) (HANDLE h, LPLONG opcl);
typedef BOOL (IMPORTA * BDCCIERRA) (HANDLE h);
typedef LONG (IMPORTA * BDCDESNUMERO) (HANDLE h);
typedef LPCSTR (IMPORTA * BDCDESCODIGO) (HANDLE h, LONG des);
typedef BOOL (IMPORTA * BDCRENDIMIENTO) (HANDLE h, LONG des, double FAR *ren);
typedef BOOL (IMPORTA * BDCPRECIO) (HANDLE h, double FAR *pre);
typedef LPCSTR (IMPORTA * BDCCODIGO) (HANDLE h);
typedef LPCSTR (IMPORTA * BDCRESUMEN) (HANDLE h);
typedef LPCSTR (IMPORTA * BDCTEXTO) (HANDLE h);
typedef LPCSTR (IMPORTA * BDCPLIEGO) (HANDLE h);
typedef LPCSTR (IMPORTA * BDCCLAVES) (HANDLE h);
#endif /* de #ifdef BASE */
/****************************************************************************/
/* PARTE COMÚN DEL ARCHIVO: CÓDIGOS DE LOS MENSAJES DE ERROR */
/* SE ALMACENAN COMO BITS DE UN LONG, DE MANERA QUE EXISTAN HASTA 32 */
/****************************************************************************/
#define BDCERR_CORRECTO 0x0000 /* No hay error */
#define BDCERR_BASE_DATOS 0x0001 /* Existe un mensaje de error definido por el redactor de la base*/
#define BDCERR_PARAMETRO 0x0002 /* Se pasó a BdcCalcula o BdcGloCalcula un parámetro inexistente */
#define BDCERR_OPCION 0x0004 /* Se pasó a BdcCalcula o BdcGloCalcula una opción inexistente */
#define BDCERR_MAX_OPCIONES 0x0008 /* Se definieron más de 62 opciones */
#define BDCERR_NO_LEIDO 0x0010 /* Se intentó calcular un concepto sin leer */
#define BDCERR_NO_CALCULADO 0x0020 /* Se intentó acceder a datos de un derivado no calculado */
#define BDCERR_DESCOMPOSICION 0x0040 /* Se intentó acceder a un ele. de la descomposición inexistente */
#define BDCERR_SIN_CODIGO 0x0080 /* No existe código definido */
#define BDCERR_SIN_MEMORIA 0x0100 /* Memoria insuficiente */
#define BDCERR_CONCEPTO_NULO 0x0200 /* Se pasó un HANDLE nulo */
#endif /* FIEBDC_H */
Addenda a la especificación FIEBDC-3/98
Modificación de la función BdcPliego
Se amplia en un parámetro la función BdcPliego para permitir utilizar a través del API distintos formatos de texto (ASCII, RTF...).
La especificación de la función modificada es como sigue:
LPCSTR EXPORTA BdcPliego (
HANDLE h, // identificador del concepto
LONG formato // identificador del formato
) ;
Propósito
Obtiene el texto del pliego del derivado paramétrico.
Parámetros
h: Identificador (HANDLE) del concepto paramétrico, que debe ser obtenido en una llamada anterior a la función BdcLee().
formato: Identificador del formato de texto (ASCII, RTF...).
Valor devuelto
Devuelve el texto del pliego del derivado paramétrico en el formato solicitado, como puntero constante 'far' a una cadena de caracteres. La propia función es responsable de asignar memoria al puntero. Si no existe definido un texto de pliego, la función devuelve la cadena vacía " ". En caso de error (por ejemplo, de formato no soportado por la BDC), la función devuelve NULL. Para obtener más información sobre el error producido, llame a la función BdcError ().
Se definen, por el momento, los siguientes formatos:
#define BDCFMT_ASCII 0
#define BDCFMT_RTF 1
Se define el siguiente (nuevo) código de error:
#define BDCERR_FMT_NO_SOPORTADO 0x0400
/* El formato de texto solicitado no está soportado por la BDC */
Nueva función BdcUnidad
Función que permite que un concepto paramétrico pueda generar elementos derivados con distintas unidades de medición.
Para que dicha función actúe, el registro ~C debe contener el caracter especial * dentro del campo unidad de medida. Dicho caracter indica que la unidad de medida de los conceptos derivados los debe proporcionar el API.
Si se utiliza dicha función y es interesante para el redactor de la BD que la unidad de medida sea un valor a escoger por parte del usuario, deberá añadirse la unidad de medida como una propiedad más del concepto paramétrico.
La especificación de la función, accesibles después de BdcCalcula, es como sigue:
LPCSTR EXPORTA BdcUnidad (
HANDLE h // Identificador del concepto
);
Propósito
Obtiene la unidad de medida del concepto.
Parámetros
h: Identificador (HANDLE) del concepto paramétrico, que debe ser obtenido en una llamada anterior a la función BdcLee().
Valor devuelto
Devuelve el texto correspondiente a la unidad de medida del derivado paramétrico, como puntero constante 'far' a una cadena de caracteres. La propia función es responsable de asignar memoria al puntero. En caso de error, la función devuelve NULL. Para obtener más información sobre el error producido, llame a la función BdcError()