JScript: extensión COM para programar informes

En este apartado se recoge parte de la información actualmente disponible sobre programación de informes, de forma muy sucinta pero completa. La parte correspondiente a formato de campos, modificadores y, en general, construcción de las páginas, la encontrará en objetos para imprimir.

En la guía paso a paso, hay un capítulo dedicado sólo a la creación y modificación de informes, ejemplos de las personalizaciones más comunes, así como multitud de informes de ejemplo impresos para que le sirvan como catálogo de muestra.

TODAS las explicaciones dadas en este anexo se refieren a las AMPLIACIONES que el programa hace sobre el lenguaje estándar JavaScript (nuevos objetos, métodos y propiedades). La sintaxis, funciones, métodos y utilización del propio lenguaje no se toca en ningún momento, y hay un archivo de ayuda en línea que puede consultar para ese fin.

En primer lugar, vamos a ver un conjunto de variables globales definidas en la ventana informes y procedimientos, que nos ofrecen el contenido de ciertos campos:

Código Raíz, se almacena en la variable raíz. Cuando recorremos la estructura de la B.D., por defecto se hace completamente desde el concepto raíz (.) hacia abajo. Este campo permite comenzar el recorrido a un nivel inferior, para recorrer sólo una parte de la estructura.

Máscara de códigos, se almacena en la variable mascara. Excepto en informes muy particulares que se refieren sólo a ciertos grupos de conceptos por su código, no se suele filtrar por códigos. Poniendo una máscara en este campo, los recorridos por estructura pueden mostrar sólo los conceptos que cumplan la máscara. Por supuesto, no todos los informes y procedimientos admiten este filtro (por ejemplo si el informe ya tenía otro filtro, prevalece aquel), y no en todos tiene sentido este filtro.

Fecha Inicial, se almacena en la variable fecini. Permite establecer la fecha o el periodo a considerar en los informes que trabajen con fechas. La introducción de datos en este campo, pone los datos más previsibles en el siguiente, para establecer el periodo a considerar de la forma más cómoda. En cambio, al modificar fecfin, no se vuelve a proponer la de inicio.

Fecha Final, se almacena en la variable fecfin. Establece el final del periodo a considerar para el informe, desde la fecha de fecini. Al introducir un valor en Fecha Inicial, siempre se propone este otro.

En caso de no introducir ningún dato en fecini, los informes que funcionan con fechas suelen asignar una fecha de defecto (normalmente la del día actual). Pero si se introduce cualquier número en la fecha inicial, se rellena la fecha comenzando por la izquierda para poner una fecha completa, también en fecfin:

Tecleado en F. INI	Fecha inicial	Fecha Final
	12/10/2003 (*)	12/10/2003
3	01/01/2003	01/01/2004
1103	01/01/1103	01/01/1104
2/04	01/02/2004	01/03/2004
131190	13/11/1990	14/11/1990
110204	11/02/2004	12/02/2004

Número primera página, se almacena en la variable pagact y representa el número que llevará impreso (en caso de que se imprima) la primera página del informe, en vez de "1".

Páginas a imprimir (n-n), es un rango que se almacena en las variables pagpri y pagult, que indica las páginas que se van a imprimir, basados ambos en la numeración de pagact, por lo que normalmente, el primer número del rango (pagpri) siempre debería ser mayor o igual que pagact. Por ejemplo:

Nº primera página	Páginas a imprimir	Resultado, imprime:
	3-	de la página 3 a la última, comenzando en 1
	3-6	de la página 3 a la 6 (incluidas), comenzando en 1
	-8	hasta la página 8 (incluida), comenzando en 1
4	1-2	todas las páginas (ignora el rango), comenzando con el nº 4
4	1-4	sólo la pág. 4, con el nº 4
10	15-	desde la quinta pág. del informe, comenzando con el nº 10

Como nomenclatura de la documentación de métodos, objetos, funciones, modificadores, etc. utilizaremos el siguiente convenio:

fecha - El argumento fecha debe corresponder a un número de la forma AAAAMMDD (año con cuatro dígitos, mes del año con dos dígitos, y día del mes con dos dígitos), por ejemplo el veinte de abril del 2003 se expresa con el número 20030420.

camino y archivo - nombre de camino de directorio relativo o absoluto y nombre de archivo (a veces con extensión o no, según se explique). Tenga en cuenta que el carácter barra ' \' es un carácter especial por lo que debe figurar dos veces. Por ejemplo "c:\\Documentos\\archivo.txt"

Otra variable relacionada con el número de páginas es pagtotal, que calcula una primera vez el informe entero, para obtener el número de páginas que tiene, y lo almacena en esta variable global.

ingra: Es el objeto motor por defecto. De él parten los demás objetos, pero no hace falta especificarlo, ya que es el de defecto, y no aparecerá en ninguna de nuestras sentencias.

Cmapi - asignado a una variable, crea un objeto de tipo correo electrónico, que permite enviar, recibir y recuperar datos de correos electrónicos. Vea los métodos de estos objetos en Objetos y métodos de ingra.

Chor - asignado a una variable, crea un objeto de tipo fecha-hora, que permite gestionar operaciones complejas con fechas (como calcular periodos, restar o sumar días a fechas, calcular fechas sumando horas,etc.). Vea los métodos de estos objetos en Objetos y métodos de ingra

erro - es una cadena de caracteres que almacena el último mensaje de error que se ha producido en la ejecución el programa xjs.

hoy - almacena un número que representa la fecha actual del sistema en el que se ejecuta el programa, en formato aaaammdd. Esta propiedad puede utilizarse como argumento de los métodos de manejo de fechas. Por ejemplo, si hoy es viernes 10 de agosto del 2001, el método fecha (hoy, "dd-mm-aaaa") devolverá 10-08-2001.

debug - esta sentencia detiene la ejecución del programa y abre el diálogo de depuración. En la línea Comando o variable se pueden especificar: un sentencia válida de JavaScript incluyendo las extensiones, o bien un nombre de variable. Al hacer clic en Acepta se ejecutará la sentencia, y su valor de retorno si lo hubiera se mostrará en el visor del diálogo, si se teclea un nombre de variable aparecerá en el visor el valor actual de esa variable.

Si teclea por ejemplo Math.E, al hacer clic en Acepta aparecerá en el visor el número 2.71828182845905 que es el número de Euler.

El depurador guarda un histórico de los comandos ejecutados, pudiendo acceder a ellos con los botones Anterior y Siguiente.

debugger - si se tiene instalado el entorno de desarrollo Visual Studio .NET, con herramientas para depuración JavaScript, al producirse un error, podemos depurarlo bajo el entorno, lo que nos permite establecer puntos de parada, examinar variables, recorre librerías...

diaavisa (título, texto) - abre un diálogo con el icono de AVISO, título es la cadena de texto que figurará en el título del diálogo, y texto el mensaje. Al hacer clic en el botón Acepta continuará la ejecución del programa. Vea también el método inter()

diaedita (título, texto[, defecto]) - abre un diálogo con un campo editable, título es la cadena de texto que figurará en el título del diálogo, y texto es la cadena de texto que figura como mensaje del diálogo, defecto es el contenido que por defecto tendrá el campo de edición. Retorna el valor del campo de edición cuando se pulsa el botón Acepta, y retorna el valor NULL (nulo) al pulsar Cancela.

diaerror (texto) - muestra un diálogo de error con el mensaje texto y el título ERROR. Al pulsar el botón Cierra continuará la ejecución del programa.

diainforma (título, texto) - abre un diálogo con el icono de INFORMACIÓN, título y texto son las cadenas de texto que figuran en el diálogo. Es análogo a diaavisa

diapregunta (título, texto) - abre un diálogo con icono de INTERROGACIÓN. Análogo a diaavisa y diainforma

director ([archivo][, extensión]) - retorna el nombre del directorio o carpeta en la que funcionan los archivos particulares del programa. Si se trata de una instalación en red, retorna el directorio de la instalación cliente o directorio privado. Si es una instalación monousuario retorna el directorio de instalación de la aplicación. Si se suministran los dos argumentos, los devolverá concatenados al nombre del directorio en la forma: "directorio\archivo.extensión".

dirmaslee (directorio, opciones)- devuelve una lista con la información seleccionada del directorio directorio, con las opciones. directorio, es una cadena de texto con el directorio donde se quieren buscar archivo o directorios. Las opciones pueden ser: (o) archivos, (1) directorios, (2) ambos

publico ([archivo][, extensión]) - retorna el nombre del directorio o carpeta de instalación de la aplicación visible en la ventana Opciones. Si se trata de una instalación en red este será el directorio de la instalación en el servidor, si es una instalación monousuario este será el directorio de instalación de la aplicación en el disco local. Si se suministran los argumentos archivo y extensión, devolverá estos dos argumentos concatenados al nombre del directorio en la forma: "directorio\archivo.extensión".

temporal ([archivo][, extensión]) - retorna el nombre del directorio o carpeta utilizado para almacenar los archivos temporales. Por defecto es un directorio llamado \TEMPORAL que se encuentra en el directorio privado de instalación (es decir el directorio de la instalación cliente o el de la instalación monousuario). Si se suministran los argumentos, los devolverá concatenados al nombre del directorio en la forma: .\Temporal\archivo.extensión. Por ejemplo: temporal ("salida.txt") retorna ...\Temporal\salida.txt, equivale a temporal ("salida", "txt")

trabajo ([archivo][, extensión]) - retorna el nombre del directorio o carpeta de trabajo. Por defecto este es el directorio privado, es decir, el de la instalación cliente o monousuario. Si se suministran los argumentos, los devolverá concatenados al nombre del directorio en la forma: directorio\archivo.extensión.

fecha (número | fecha[, formato]) - devuelve una cadena de texto representando la fecha almacenada en número. También admite como primer argumento, un número que represente una fecha, para formatear. Si no se especifica el argumento formato, la cadena de texto retornada contendrá la fecha en el formato que se especifique en la ventana Opciones, en el campo formato de fechas. Si no se especificó ninguno, se utilizará el formato de fecha por defecto, es decir dd/mm/aaaa. Los formatos reconocidos, y que se pueden combinar, para las fechas son los siguientes:

ddd - tres primeras letras del nombre del día de la semana: Lun, Mar, Mié, Jue, Vie, Sab, Dom.

fecdia ([fecha]) - devuelve el valor numérico correspondiente al día del mes de la fecha. Si no se especifica el argumento fecha, da el día del mes de la fecha del sistema.

fecdias (fechaini, fechafin[, fechaestudio]) - devuelve el número de días comprendidos entre las fechas fechaini y fechafin ambos incluidos. Si se especifica el argumento fechaestudio, retornará el número de días del intervalo entre fechaini y fechafin comprendidos en el MES de la fechaestudio. Por ejemplo: fecdias (20010101, 20010202) devuelve el valor 33, mientras que fecdias (20010101, 20010202, 20010208) devuelve 2, que son los días entre el uno de enero y el dos de febrero comprendidos en el mes de febrero.

fecdianombre ([fecha]) - devuelve el nombre del día de la semana correspondiente a fecha. Si no se especifica el argumento fecha, retorna el nombre del día de la semana correspondiente a la fecha del sistema.

fecmesnombre ([fecha]) - análoga a fecdianombre, devuelve el nombre del mes correspondiente a fecha. Si no se especifica el argumento, devuelve el nombre del mes de la fecha actual.

fecmes ([fecha]) - devuelve el número del mes correspondiente al valor de fecha fecha. Si no se especifica el argumento fecha, da el número del mes de la fecha del sistema.

fecmesdias ([fecha]) - devuelve el número de días del mes correspondiente a fecha. Si no se especifica el argumento fecha, da el número de días del mes correspondiente a la fecha del sistema.

fecano ([fecha]) - devuelve el año correspondiente a fecha. Si no se especifica fecha retorna el año correspondiente a la fecha establecida en el sistema en que se ejecuta el programa.

fecsemdia ([fecha]) - devuelve el número del día de la semana correspondiente a fecha. El 0 corresponde al lunes, el 1 al martes, etc. Si no se especifica el argumento fecha, da el número del día de la semana de la fecha del sistema.

Para utilizar estos objetos simplemente hay que inicializar sus propiedades y pasarlos como argumento del método campo del objeto Cimp. Este objeto impresor interpretará los valores asignados a Cgrf, y dibujará el gráfico en el campo actual, como si fuese una especie de "foto", aplicando los modificadores de formato que se especifiquen. Vea los métodos de estos objetos en Objetos y métodos de ingra.

Los objetos de deben crear uno por cada gráfico distinto a representar en una misma línea, (los objetos no se liberan hasta que se imprime una línea sin bloqueo), pero en cada línea o bloque de líneas se deben reutilizar los mismos objetos.

Cgrf - asignado a una variable, crea un objeto de tipo gráfico estadístico, al que se le pasan los datos a representar, y el formato. Permite mostrar gráficos de líneas, de barras y de tarta.

Cima - crea un objeto de tipo imagen o gráfico vectorial. El gráfico es independiente de base de datos (externo)

bas.Cima - crea un objeto imagen (mapa de bits) o gráfico vectorial, a partir de datos de gráficos en la base de datos (vinculados o incrustados). A través de los métodos de ese tipo de objetos podemos leer archivos de la base y grabarlos como externos o viceversa, e imprimirlos.

bas.Cmap - crea un objeto gráfico de tipo mapa, con datos de conceptos Tipo mapa.

Cuando se lanzan estos objetos a salida en archivo (formato RTF), el documento recibe un EMF como si fuese una foto para incrustar en el código RTF.

Es el objeto especializado en la creación de formularios interactivos. Una referencia a este objeto se obtiene como sigue:

Los métodos texto, opcion y campo permiten agregar controles al diálogo: etiquetas de texto, botones de opción y campos de edición respectivamente. Los controles se colocarán unos debajo de otros en el mismo orden en que son invocados los métodos que los crean.

El formulario resultante será una ventana que contiene: barra de título incluyendo el botón de control y el botón de cierre, y dos botones en la barra inferior: Acepta, Cancela. Esta ventana es redimensionable horizontalmente, al variar el ancho de la ventana variará el ancho de los controles que incorpora.

El método texto incluirá una etiqueta en el formulario. Recibe la cadena de texto a mostrar y como segundo argumento modificadores de formato aplicables al texto. La lista modificadores de formato se puede consultar en el epígrafe referencia del objeto diálogo. Por ejemplo:

El método campo añade campos de edición al formulario. Puede recibir de uno a tres argumentos: número identificador del control dentro del formulario, etiqueta de texto descriptiva que acompaña al campo de edición, ancho relativo con el que se mostrará el campo de edición. El identificador del control servirá para referenciar el control al recuperar su valor mediante el método valor. Por ejemplo:

El método campoM crea igualmente un campo de texto, pero en este caso multilínea, con una barra de desplazamiento vertical. Recibe igualmente: un identificador, una cadena de texto para la etiqueta del control, opcionalmente un número que determina el ancho del campo (por defecto es 10), y opcionalmente el número de líneas o altura del control (por defecto son 4). Por ejemplo:

El método opcion crea una casilla de verificación o un grupo de opciones representadas por botones de radio. Recibe dos argumentos: el primer argumento es un número identificador del control, el segundo es una cadena de texto.

Si la cadena de texto que recibe como segundo argumento no contiene el carácter punto y como (;), creará una casilla de verificación utilizando esta cadena de texto como etiqueta para la casilla. En caso contrario, creará un grupo de opciones de botones de radio, tomando como etiqueta de cada botón el texto comprendido hasta el carácter punto y coma.

La siguiente sentencia muestra como crear un grupo de opciones, identificado por el número 10, con cuatro botones de radio etiquetados como: Fecha de hoy, Fecha de vencimiento, Fecha de emisión, Fecha especificada en el siguiente campo.

La primera de las opciones corresponde al valor cero, la segunda al uno, etc. Es decir, el método valor retornará 0, 1, 2, etc., según la opción seleccionada.

Si en lugar de opcion se invoca opcionL se incluirá una caja combinada, éste método recibe tres o cuatro argumentos, el segundo es la etiqueta para el control, y el tercero una lista de opciones separadas por punto y coma(;), y además puede recibir un argumento para especificar su tamaño horizontal. Por ejemplo:

En este caso el método valor retorna el texto de la opción seleccionada, por ejemplo "Fecha de emisión" si ha seleccionado la tercera opción.

El método ayuda permite establecer un enlace con un tema de ayuda de los existentes en el archivo de ayuda de la aplicación. Este método añadirá en la barra de botones del diálogo el botón Ayuda, que al ser pulsado por el usuario abrirá el archivo de ayuda en el tema que recibe como argumento. Por ejemplo:

El método seleccion asocia a un campo la posibilidad de suministrar en él una máscara de búsqueda, para abrir la lista de selección de registros relacionados con el campo que se está editando. Por ejemplo:

dia.seleccion (300, "TIPASI.series") // permite abrir la lista de selección de series de asientos

dia.seleccion (300, "auxcob.cod") // selección de forma de cobro por su código

dia.seleccion (300, "auxgas.res") // selección de tipos de gasto por su resumen

Una vez invocados estos métodos, el método crea mostrará el formulario en pantalla. Recibe como argumentos el texto a mostrar en el título de la ventana, un nombre que identifica la ventana y un tercer argumento que determina si se almacenarán los datos de los controles del formulario:

Si el tercer parámetro es 1, se almacenarán en el archivo de inicio (.ini) de la aplicación lo últimos valores especificados en los controles, de forma que la siguiente vez que se ejecute el programa, el formulario aparecerá con estos valores. Si por el contrario se especifica un 0 los campos de edición aparecerán a blanco y el grupo de opciones tomará el valor cero (la primera opción será la seleccionada).

El método valor retorna el valor almacenado en el control, cuyo identificador recibe como argumento. Por ejemplo:

var fec0= dia.valor (10) // retorna en fec0 el valor del control identificado por 10

Este método puede también utilizarse para establecer valores en los controles. En este caso recibe un segundo argumento que especifica el valor que se quiere establecer.

var fec1= dia.valor (200, "01/01/2002") // establece el control de identificador 200 con el valor 01/01/2002

Los controles se irán añadiendo al diálogo uno debajo del otro, pero este comportamiento puede modificarse utilizando el método grupo. Para indicar que los controles se alinearán en horizontal o en vertical se invocará el método grupo, a continuación se invocarán los métodos de definición de los controles (texto, campo, opcion,...), y por último se invocará de nuevo el método grupo para indicar la finalización del mismo. Por ejemplo:

Para abrir un grupo de controles se invoca a grupo con uno o dos argumentos, el primero de ellos será la disposición de los controles del grupo, utilizando V y H para especificar vertical y horizontal, el segundo argumento es opcional, y se trata de modificadores de formato para determinar la anchura del borde del grupo y la distancia desde el borde a los controles (margen interno). El modificador b establece el tipo y grosor del borde, el modificador m determina el margen interno para que los controles no queden pegados al borde.

El método grupo puede también ser invocado para crear pestañas en el diálogo, consultar el epígrafe de referencia del objeto dialogo para conocer más detalles.

error ([cadena]) - finaliza la ejecución del programa con un diálogo de error. Si no se suministra el argumento cadena se muestra en el diálogo el último mensaje de error que se almacenó en la propiedad error, en caso contrario se muestra el rótulo.

formato (numero, [decimales]) - retorna una cadena de texto con el numero incluyendo separadores de miles y separador decimal si procede. Si se especifica el argumento decimales, retorna el numero redondeado a ese número de decimales

incluir (archivo) - incluye, en el momento de ejecutar el script, el contenido del archivo que recibe como argumento dentro del código en ejecución, de forma que si el contenido del archivo son sentencias JavaScript, estas serán ejecutadas en el lugar donde se encuentra la sentencia incluir. El directorio por defecto es \INFORMES, por lo que para incluir cabeceras y otros informes o librerías, no es necesario poner ningún camino al archivo.

inter ([texto]) - durante la ejecución de los programas xjs se muestra siempre un diálogo de interrupción que permite parar la ejecución del programa al pulsar el botón Interrupción. En el caso de que el programa esté ejecutando un bloque de sentencias, no se interrumpirá su ejecución hasta la finalización del bloque. Para poder interrumpir la ejecución de un bucle, es necesario preguntar por el valor de retorno de este método. Si se pulsó Interrupción el método inter retorna verdadero (=1), en caso contrario retorna falso (=0). Si se da el argumento texto, en vez del rótulo de puntos suspensivos (...), aparecerá el rótulo texto. (Vea también los métodos dia???). Esta función es muy útil asociada a salir()

lc (cadena) - Considera el texto cadena para traducir, cuando se cambia de lenguaje en la ventana opciones

lencmp (val1, val2, mapa) - Función de comparación entre 2 valores (por ejemplo para aplicar como parámetro a la función sort de JavaScript), compara val1 con val2 cuando el orden que deseamos no es el habitual ASCII, sino que por ejemplo, queremos ignorar mayúsculas y minúsculas, o ignorar acentos en la comparación, etc. Devuelve los mismos valores que la función de comparación estándar: 1 si val1 es mayor (o anterior) a val2, -1 si es menor y cero si son iguales, comparando según las distintas opciones de mapa de caracteres: (0)comparación estándar, (1)sólo minúsculas acentuadas, (2)sólo mayúsculas acentuadas, (3)en bruto: todo mayúsculas sin tildes ni diacríticos.

letra (numero) - devuelve una cadena de texto conteniendo el numero expresado en letras. Redondea a 0 decimales y no imprime ningún rótulo de moneda. Para trabajar con rótulos de monedas utilice moneda con el método letra. Por ejemplo letra (28) devuelve "VEINTIOCHO".

notepad (archivo) - ejecuta el bloc de notas de Windows abriendo el archivo que recibe como argumento. Si el archivo se encuentra en la carpeta de informes no es necesario especificar el camino completo, en caso contrario tendrá que indicar la ruta para encontrar el archivo.

prin (cadena) - Imprime la cadena en la ventana de depuración con un retorno de línea incluido, es decir, imprime cada salida en líneas separadas

red (numero, decimales) - retorna un número igual al real numero, redondeado al número de decimales indicado.

rtf2tex (textortf) - traduce el texto que recibe en formato de texto RTF (rich text format ó formato de texto rico) a texto plano (ASCII) con retornos de carro.

salir ([numero]) - finaliza la ejecución del programa. Si numero=1, en vez de terminar la ejecución del informe sin mostrar nada, mostrará lo que lleve procesado hasta el momento de salir

windatos (archivo) - abre el archivo utilizando el programa, que según su extensión, tenga asociado en el registro de Windows. Las asociaciones de extensiones de archivos con los programas pueden modificarse o consultarse en las Opciones del Explorador de Windows.

winejecuta (programa, archivo) - abre el archivo que recibe como argumento, con el programa windows especificado. Tanto el nombre del programa ejecutable como el del archivo han de especificarse por el nombre completo. Por ejemplo: winejecuta ("c:\\windows\\notepad.exe", "c:\\temp\\doc1.txt");

write (valor) - graba el valor que recibe en el archivo presenta.txt en el directorio \TEMPORAL. Todas las sentencias write de la ejecución de cada informe se añaden una a continuación de otra. Cuando finaliza la ejecución del script, se abre el archivo presenta.txt utilizando el Bloc de Notas de Windows. Esta instrucción junto con writeline permiten mostrar información en pantalla sin tener que utilizar el objeto impresor.

writeline (valor) - igual a write solo que además, graba un retorno de carro y nueva línea al final de cada valor que recibe como argumento.