Referencia técnica de la API WebS8DLL

Guía de referencia técnica de la

API WebS8DLL para SIABUC8

Guía de referencia técnica de la API WebS8DLL para SIABUC8 Preparado por J. Román Herrera M. © Diciembre de 2006 Departamento de SIABUC Dirección General de Servicios Bibliotecarios Universidad de Colima http://siabuc.ucol.mx/ AVISO LEGAL: El nombre SIABUC ® y el logo son marca registrada de la Universidad de Colima, así como los derechos de propiedad intelectual del software. La Universidad de Colima mediante la firma de un convenio especial concede la licencia de uso del software a la institución interesada. Queda prohibido el uso y /o modificación de los símbolos distintivos de SIABUC así como la explotación, comercialización o prestación de servicios, materiales y/o documentación relacionados a este software, sin la previa autorización y permiso por escrito de la Universidad de Colima. Las marcas y nombres comerciales de productos de software mencionados en este documento, tienen derechos registrados de sus respectivos propietarios o fabricantes.

API

WebS8DLL

INTERFAZ DE PROGRAMACIÓN DE APLICACIONES PARA EL MOTOR DE BÚSQUEDAS DE SIABUC8 BASADA EN COMPONENTE DLL. WEBS8_DLL 1.0

Guía de Referencia Técnica de la API WebS8DLL para SIABUC8

© 2006. Departamento de SIABUC. DGSB. Universidad de Colima Página 1

CONTENIDO Introducción 2

¿Qué es la API WebS8DLL? 2 El componente de búsqueda de SIABUC con CGI 2 CGI versus DLL 2

Descripción de la API WebS8DLL 4

Requerimientos para utilizar la WebS8DLL 4 Ejemplo de uso de la WebS8DLL con ASP 5 Pasos mínimos para el uso de la WebS8DLL 8

Métodos y propiedades de la WebS8DLL 9 InicializarBD 9 CerrarBD 10 HacerBusqueda 10 DespliegaVResultados 12 DespliegaFicha 14 ObtenerTag 15

ResaltaPalabra 16 Version 17

AsignaStyle 17 Derechos y Licenciamiento 19 ANEXOS Anexo A. TestDLL.asp. Archivo de prueba para uso con ASP 20 Anexo B. Funciones auxiliares para uso con ASP 22 Anexo C. Constantes auxiliares para uso con ASP 24



INTRODUCCION

¿Qué es la API WebS8DLL?

La API WebS8DLL es un interfaz de software desarrollada por el Departamento de SIABUC que permite programar aplicaciones complementarias a los módulos de SIABUC, por ejemplo, la implementación de los catálogos de consulta al acervo por web utilizando tecnologías ASP o PHP. Esta API WebS8DLL con el paso del tiempo vendrá a sustituir la implementación anterior que tenía el SIABUC para desarrollar los catálogos en web la cual está basada en un componente CGI llamado WebS8.exe

El componente de búsqueda de SIABUC con CGI

Desde la versión SIABUC Win de 1995, se incorporó la posibilidad de montar los catálogos en web, la primera implementación se llamaba busWeb.exe que era un componente CGI pero que trabajaba a 16 bits (SIABUC Win se diseñó para plataformas Windows 3.X) . Con la liberación de SIABUC Siglo XXI en 1999 se incluyó la nueva versión del componente CGI de búsqueda para 32 bits el cual se llamó webXXI.exe. Y la última versión basada en CGI es el actual web_S8.exe incluido desde la primera edición de SIABUC8 a partir del 2003.

CGI versus DLL

Sin duda fue de gran utilidad el poder incorporar la búsqueda de información bibliográfica desde internet basada en los componentes CGI de SIABUC, sin embargo al ser una tecnología CGI, siempre se tuvieron ciertas desventajas si se compara con las tecnologías modernas basadas en aplicaciones PHP, ASP, JSP u otras implementadas con componentes COM. Estas desventajas podemos agruparlas en:

• Relacionadas con la eficiencia. Con el CGI, para cada solicitud de consulta se crea un proceso independiente que consume recursos en el servidor mismo que finaliza hasta que la operación de consulta ha concluido. Si se tienen 50 usuarios haciendo búsquedas en ese momento, en el servidor habrá 50 procesos CGI. Con la nueva WebS8DLL solo se genera un único proceso para cualquier petición compartiendo recursos en el servidor, con lo que se optimiza e incrementa su desempeño.



• Relacionadas con la seguridad. Para la utilización de aplicaciones CGI hay que otorgar permisos explícitos de ejecución o de escritura para ciertos recursos del servidor, esta situación en muchas instituciones es inaceptable debido a sus políticas de seguridad interna, ya que las aplicaciones CGI exponen de manera notable al servidor. Una aplicación CGI diseñada con mala intención, puede incluso formatear el disco duro del servidor obedeciendo a comandos remotos enviados desde una computadora conectada en cualquier lugar mediante el internet*. Con la WebS8DLL simplemente se registra como un componente DLL el cual es controlado y administrado por el servidor de web, minimizando en gran medida los riesgos potenciales para el servidor.

• Relacionadas con la facilidad y flexibilidad de implementación. La aplicaciones CGI de SIABUC son código compilado y encapsulado que no permite a nuestros usuarios realizar modificaciones y proporciona un mecanismo de presentación de resultados basado en archivos de configuración externos (archivos CFG), esta lógica de implementación en muchos casos ha resultado confusa y de difícil personalización. Con el nuevo modelo basado en la webS8DLL, los webmasters de cada institución podrán diseñar previamente sus plantillas web para mostrar la opción de consultas y despliegue de los resultados, éstas plantillas simplemente se incorporarán a la programación web con ASP y PHP donde se instanciará el componente webS8DLL para utilizar sus funciones predefinidas de búsqueda y recuperación de datos.

En resumen, con la distribución de la API webS8DLL pretendemos brindar mejores herramientas para nuestra instituciones usuarias de SIABUC, para que sus aplicaciones de consulta tengan un mejor rendimiento, mejor seguridad y menos problemas para encontrar servicios externos de hosting para sus OPACs. Asimismo, los desarrolladores y webmasters tendrán ahora mayores posibilidades de personalización y de integración del sistema de consultas en sus aplicaciones nuevas o ya existentes, así como mayores facilidades de implementación y de mantenimiento, potenciando con ello su imaginación y creatividad.

* Obviamente las aplicaciones CGI de SIABUC no contienen ningún código malicioso y se diseñaron para auxiliar y prestar mejores servicios de información bibliográfica, por lo que agradecemos a las instituciones que confían en nuestros desarrollos y han implementado sus catálogos web con SIABUC.



DESCRIPCION DE LA API WEBS8DLL

La API WebS8DLL está representada por un conjunto de código encapsulado que contiene funciones y propiedades que posibilitan la conexión a la base de datos del SIABUC, permiten realizar búsquedas en el acervo bibliográfico y visualizar la información seleccionada en diferentes formatos preestablecidos.

La API está compuesta por el archivo webS8DLL.dll, el cual es una librería de enlace dinámico (llamadas comúnmente DLL), una referencia técnica para su uso y unos archivos de ejemplo con código en ASP para ejemplificar su implementación en servidores IIS de Microsoft. Esta API se obtiene al descargar el archivo API_webS8DLL.rar de la página web de SIABUC en http://siabuc.ucol.mx/

Requerimientos para utilizar la WebS8DLL

Para utilizar la funcionalidad de esta API WebS8DLL es necesario contar con una plataforma de cómputo que soporte la creación o instanciación de componentes activeX debido a que la librería webS8DLL es una librería desarrollada con tecnología activeX de Microsoft. En consecuencia, se podría generalizar que únicamente trabaja sobre plataformas de servidor Windows, salvo que bajo alguna otra plataforma se utilice un emulador de Windows y se puedan emplear este tipo de componentes.

Generalmente se utilizará la webS8DLL para incluirla en aplicaciones ASP donde el componente central es el servidor web Internet Information Services (IIS) de Microsoft por lo que es un requisito indispensable contar con este software y sus licencias correspondientes para el desarrollo de sus aplicaciones web.

También es posible utilizar tecnología PHP, ya que permite instanciar objetos COM y por consiguiente utilizar la librería WebS8DLL, así para instituciones que no utilicen tecnología Microsoft en sus servidores web, será posible utilizar un servidor web que no sea el IIS sino cualquier otro que funcione para plataformas win32 como el popular servidor Apache. Sin embargo, queda a la creatividad y experiencia de nuestros usuarios dicha implementación, debido a que en esta guía no se ha incluido ningún código de ejemplo con PHP.



Ejemplo de uso de la WebS8DLL con ASP

Al descomprimir el paquete API_webS8DLL.rar, se genera un subdirectorio llamado “API_WebS8DLL” en su disco duro, en esta carpeta se incluyen todos los archivos necesarios para una implementación básica de catálogos web con SIABUC8, además de esta documentación de referencia.

La estructura de directorios y contenido de archivos es la siguiente:

directorio Descripción del contenido \bases En esta carpeta se deben colocar las bases de datos de SIABUC

(siabuc8.mdb, estadisticas.mdb e indizado.mdb). Esta ubicación es sugerida y para fines de ejemplificación, en una situación real la ruta de las bases de datos puede ser en cualquier otra ubicación siempre y cuando el componente webS8DLL tuviera acceso y permisos de lectura y escritura.

\docs En esta carpeta encontrará este documento de referencia técnica de la API webS8DLL y en un futuro cualquier otra información adicional.

\wwwroot Esta carpeta servirá como directorio raíz de su aplicación web, aquí se incluyen los archivos de la librería webS8DLL.dll, un archivo de prueba llamado testDLL.asp y otros archivos ASP auxiliares, además de los archivos de ejemplo desarrollados con código en ASP. Se incluyen también unas subcarpetas \images, donde se ubicarían las imágenes necesarias \plantillas, otra subcarpeta para una serie de plantillas HTML que se utilizan para el ejemplo con ASP \XSLs, que contiene la plantilla XSL utilizada para generar el formato de ficha personalizado. Estas ubicaciones también son sugeridas y para fines de ejemplificación. Un webmaster con experiencia puede cambiar la ubicación de los archivos y ponerlos donde los necesite, pero tendrá que realizar varios cambios en la configuración preestablecida de los mismos y también en la consola de administración del IIS, por ejemplo, tendrá que hacer uso de la definición de directorios virtuales, asignación de los permisos correspondientes y redireccionamiento de los hipervínculos de los archivos de ejemplo, para lograr una implementación exitosa.

Una vez que se tienen los archivos descomprimidos en las carpetas descritas, se procede a copiar las bases de datos de SIABUC8 previamente indizadas en la carpeta \bases. Sobre la carpeta de la base de datos hay que asignar permisos de lectura y escritura para el usuario anónimo de internet (IUSR_nombrePC) debido a que éste es el usuario de Windows con el que trabaja sus sesiones el IIS y el componente webS8DLL requiere de estos permisos para realizar las operaciones de consulta y generar un registro estadístico de la misma.



Después, con la consola de administración del IIS hay que configurar las propiedades del Sitio Web Predeterminado para seleccionar a la subcarpeta \API_webS8DLL\wwwroot\ como directorio raíz o directorio principal del IIS.

También, se debe registrar la librería WebS8DLL.dll utilizando el comando regsvr32.exe y refrescar el servidor IIS.

Para realizar una primera prueba de funcionamiento utilice el archivo TestDLL.asp que está ubicado en el directorio raíz del ejemplo, podrá utilizarlo escribiendo en el navegador la siguiente dirección: http://localhost/test.asp, también es recomendable sustituir el localhost por el nombre del servidor o la dirección IP de esa computadora.

Si TestDLL.asp se ejecuta adecuadamente le indicará que tuvo éxito en los diferentes pasos críticos requeridos para usar la API, éstos son:

• El componente DLL fue debidamente registrado y puede ser utilizado con ASP,

• El componente DLL pudo conectarse a la base de datos y trabajar con ella,

• Es posible realizar operaciones de búsqueda y recuperar registros de la base de datos.

Si la prueba tuvo éxito y está utilizando las configuraciones predefinidas ya podrá utilizar el ejemplo prefabricado* que se incluye como parte de esta API. La página principal y punto de inicio para el sistema de consultas se llama catalogo.htm, en su navegador escriba la siguiente dirección http://localhost/catalogo.htm

Al realizar las búsquedas, el sistema le mostrará en primera instancia una lista de resultados rápidos agrupados de 10 en 10, al igual que en los ejemplos del CGI de SIABUC8, se permite la navegación entre páginas de resultados y el despliegue de información detallada para una ficha seleccionada.

Una de las diferencias más interesantes de esta implementación basada en el componente webS8DLL es que ya no se utilizarán los archivos CFG, en su lugar se usan plantillas web. Estas plantillas web son en realidad una página web previamente diseñada y que fue dividida en secciones. Con los archivos de ejemplo con código de ASP y algunas funciones auxiliares se logra la inclusión de estas plantillas para que sean utilizadas para visualizar los resultados en el formato deseado.

* El look de este ejemplo se debe en gran medida a unas plantillas HTML y CSS, que amablemente nos compartió Ernesto Romero de la Universidad La Salle Pachuca.



Revise los códigos de ejemplo en ASP, los archivos principales son busquedaAV.asp y mostrarFicha.asp, en ellos se usan varias funciones para realizar tareas rutinarias las cuales se incluyen en un archivo externo llamado auxiliares.asp. Para generar la respuesta para el usuario se utilizan las plantillas web prediseñadas. Entendiendo el funcionamiento básico de esta nueva implementación con la webS8DLL, posteriormente podrá modificar y adaptar los archivos y plantillas de ejemplo, para que desplieguen en pantalla sus catálogos web ya personalizados de una manera muy sencilla.

Sin duda, en poco tiempo podrá crear sus propios archivos de código con ASP o con PHP y desarrollar nuevas funciones y formas de visualizar e interactuar con los datos recuperados desde SIABUC. Se vale compartir código para la implementación de los OPACs y el foro de SIABUC ( http://siabuc.ucol.mx/?opc=9.foro ) puede ser el medio más apropiado de comunicación.



Pasos mínimos para el uso de la WebS8DLL

Si desea probar la DLL con otros archivos que nos sean los de ejemplo pero que utilizan código de ASP, asegúrese de realizar previamente los siguientes pasos:

1. Tener instalado y configurado su servidor IIS

2. Copiar la DLL y los archivos auxiliares (webS8.DLL, webS8.inc, auxiliares.asp) en el directorio base de la aplicación, por ejemplo, c:\inetpub\wwwroot\ ó c:\API_webS8DLL\wwwroot\

3. Registrar la DLL con el comando "regsvr32.exe" , por ejemplo: regsvr32 webS8DLL.dll

4. Asignar permisos de acceso y modificación sobre la carpeta de la base de datos al usuario de internet ( IUSR_nombremaquina )

Para desarrollar aplicaciones win32 que utilicen la DLL:

Bastará con copiar la DLL al directorio system32 de Windows y registrar manualmente la librería como se describió en el punto 3. Además, verificar que el usuario de Windows con el que utilizará la aplicación tenga acceso de escritura a la carpeta donde están las bases de datos de SIABUC.



MÉTODOS Y PROPIEDADES DE LA WEBS8DLL

La librería WebS8DLL versión 1.0 incluye 7 métodos, 2 propiedades y 4 enumeraciones de datos disponibles para el usuario programador, a continuación se describen las funciones y propiedades y se incluyen pequeños fragmentos de código para ejemplificar su uso.

Funciones

InicializarBusqueda( rutaBD, [queAcervo] )

InicializarBusqueda es el método para establecer un vínculo con la base de datos de SIABUC, es indispensable su uso antes de poder realizar cualquiera de las tareas del componente de búsqueda. Al ejecutarse retornará una cadena vacía si la inicialización tuvo éxito, o un mensaje de error si no se pudo establecer la conexión a la base de datos.

rutaBD es un parámetro de entrada de tipo cadena, que debe contener la ruta donde se encuentran ubicados los archivos de datos de SIABUC8 (siabuc8.mdb, estadisticas.mdb e indizado.mdb).

queAcervo en un parámetro opcional de entrada de tipo entero, que sirve para definir el acervo sobre el cual se van a realizar las búsquedas, por default su valor es 0 el cual indica que el acervo a utilizarse es el de Libros (por el momento es el único acervo implementado para la version 1.0 de la webS8DLL). En el Anexo C de este documento, se incluye información sobre la enumeración AcervoBusqueda con la lista de todos los valores posibles que pueden tomar y que podrían ser usados para este parámetro.

Ejemplo con VB6: '-- Crear una instancia de la clase de busqueda del componente WebS8DLL Set s8DLL = New webS8DLL.searchS8 RutaBase=”C:\Archivos de programa\SIABUC8” AcervoLibros=0 ' valor para busqueda en libros '-- inicializar motor de busqueda sError = s8DLL.InicializarBusqueda(rutaBase, acervoLibros) if sError=”” then msgbox “conexion establecida con exito” else msgbox “Error en conexión: ” & sError end if



Ejemplo con ASP: '-- instanciar componente DLL de SIABUC mediante el objeto SERVER de ASP Set S8DLL = Server.CreateObject("webs8dll.searchS8") rutaBase = " C:\Archivos de programa\SIABUC8" '-- inicializar motor de busqueda elError=s8DLL.InicializarBusqueda(cstr(rutaBase), 0) If elError="" Then Response.write “conexion establecida con exito” else response.write “Error en conexión: ” & sError end if

CierraBD()

CierraBD es una función boolena sin parámetros, que retorna verdadero si la conexión a la base de datos se ha cerrado con éxito, o retorna falso en caso contrario.

Ejemplo con ASP: 'cerrar motor de busqueda if S8DLL.cierraBD then response.write "<h5>BD cerrada...</h5>" else response.write "<h5>Error al cerrar BD</h5>" 'mensaje de error end if 'liberar componente DLL set s8DLL = nothing

HacerBusqueda( expresion1, [campoBusqueda1], [opBooleano1], [expresion2], [campoBusqueda2], [opBooleano2], [expresion3], [campoBusqueda3], [cadenaResultante] )

HacerBusqueda es la función que nos permite hacer búsquedas en el acervo previamente seleccionado, retorna un valor entero que indica la cantidad de registros encontrados. Se puede utilizar para realizar búsquedas booleanas avanzadas combinando el valor textual de la expresión de búsqueda, el campo donde se hará la búsqueda y el operador booleano a utilizar. Se pueden combinar hasta 3 expresiones booleanas con sus parámetros opcionales de entrada.

expresion1..3 Son parámetros de entrada de tipo texto usados para indicar una expresión de búsqueda. Sólo el primer parámetro es requerido.



CampoBusqueda1..3 Con estos parámetros se pueden hacer búsquedas muy precisas en el acervo ya que permiten indicar el campo de la base de datos sobre el que se realizará la búsqueda, por ejemplo, si se hará en todos los campos (búsqueda libre), o si será por título, por autor, etc.. Estos parámetros son de entrada y opcionales, cuando se omiten, su valor predeterminado es 0, que indica que se usará la búsqueda libre. Revisar en el Anexo C la enumeración de datos CamposBusqueda para conocer todas las posibilidades.

OpBooleano1..2 Son parámetros opcionales de entrada de tipo entero, que sirven para indicar el tipo de operador booleano que se debe utilizar para combinar las expresiones de búsqueda, si omiten su valor por default será 0 que representa la operación de AND. Sus posibles valores son 0 para AND, 1 para OR y 2 para NOT. También existe la enumeración de datos operadorBooleano con la definición de estos valores.

CadenaResultante Es un parámetro de retorno opcional de tipo texto que regresa la expresión de búsqueda resultante de la combinación de expresiones.

Ejemplos con ASP: '-- Hacer busqueda con el campo Libre de un formulario .... '-- 1er parametro se lee de la colección Request, el 2do es 0 => busqLibre Total = s8DLL.HacerBusqueda(request("txtLIB"),0,,,,,,,cadFinal) '-- si hubo resultados, enviar respuesta If Total > 0 Then Response.write “se encontraron ” & Total & “resultados de “ & cadFinal '-- Busqueda de MEXICO en campo libre AND CHINA en campo de titulo, '-- busqLibre=0 y busqTitulo=1, definidos previamente como constantes, '-- el operador AND aparece como el 0 en el tercer parametro... Total = s8DLL.HacerBusqueda("mexico",busqLibre,0,"china",busqTitulo, ,,,cadFinal) If Total > 0 Then Response.write “se encontraron ” & Total & “resultados de “ & cadFinal ... ..



DespliegaVResultados ( regInicialMostrar, TotalEncontrados, formatoSalida, [outNumFichaObtenido], [ParOimpar] )

La función DespiegaVResultados sirve para recuperar el contenido de una ficha en cualquiera de los diferentes formatos preestablecidos. Se basa en el acceso al vector de resultados de SIABUC que fue generado previamente por la función HacerBusqueda, es decir, esta función es complementaria a la función de HacerBusqueda y se utiliza para recuperar de uno en uno cada registro encontrado. Esta función no debe usarse sin la función HacerBusqueda.

RegInicialMostrar es un parámetro entero de entrada que indica el número del resultado a mostrar, es importante diferenciar que se refiere al número de resultado encontrado y no al número de la ficha a visualizar. Este parámetro y la invocación de esta función dentro de un ciclo son muy útiles para formar de manera rápida y sencilla las páginas de resultados rápidos de una consulta.

TotalEncontrados es un parámetro de entrada de tipo entero que se utiliza como referencia a la función complementaria HacerBusqueda

FormatoSalida en un parámetro entero de entrada que sirve para indicar el formato de visualización que tendrá el registro solicitado, puede tomar valores definidos en la enumeración formatosDespliegue, pero para la versión 1.0 sólo está disponible el formato estilo APA al que le corresponde el valor de 10 y el formato de ficha BDL con un valor de 11.

OutNumFichaObtenido es un parámetro entero opcional de salida que proporcionará el número de ficha correspondiente para el resultado que se estará desplegando con esta función. OutNumFichaObtenido puede ser muy útil para desencadenar con este valor la visualización en detalle del registro seleccionado mediante la función DespliegaFicha.

ParOimpar Es un parámetro opcional de entrada, cuando existe solo debe tomar 2 valores, o es 1 o es 0. Este párametro aplica cuando se utiliza el formato vFichaBDL y se utiliza en combinación con la propiedad asignaStyle. Su función es



proporcionar un mecanismo para identificar a un renglón como par o impar, para mostrarlos con estilos que los diferencien en pantalla.

Ejemplo con ASP: '-- Despliega n registros unicamente con el Num.ficha y la ficha en formato APA Cantidad = 10 rMostrar = 1 For m = 1 To Cantidad elNumFicha=0 textoFicha= s8DLL.DespliegaVResultados(rMostrar, Total, vfichaTipoAPA, elNumFicha) If elNumFicha = - 1 Then Exit For response.write "<tr>" response.write " <td>" & elNumFicha & "</td>" response.write " <td>" & textoFicha & "</td>" response.write "</tr>" rMostrar = rMostrar + 1 Next Ejemplo de DespliegaVResultados con ASP: '-- Despliega n registros formando las celdas de una tabla con el Num.ficha, ' titulo, autor y clasificación usando también la función ObtenerTag Cantidad = 10 rMostrar = 1 For m = 1 To Cantidad elNumFicha=0 textoFicha= s8DLL.DespliegaVResultados(rMostrar, Total, vfichaTipoAPA, elNumFicha) If elNumFicha = - 1 Then Exit For titulo=S8DLL.obtenerTag(clng(elNumFicha),"245") autor=S8DLL.obtenerTag(clng(elNumFicha),"100") clasDewey=S8DLL.obtenerTag(clng(elNumFicha),"082") response.write "<tr>" response.write " <td>" & elNumFicha & "</td>" response.write " <td>" & titulo & "</td>" response.write " <td>" & autor & "</td>" response.write " <td>" & clasDewey & "</td>" response.write "</tr>" rMostrar = rMostrar + 1 Next Ejemplo con ASP para asignación de estilos diferentes para cada resultado: ... ' se asigna estilos con la propiedad asignaStyle s8DLL.asignaStyle="tblColor0 {font-size:9pt;background-color:F7F7F7;} tblColor1 {font-size:9pt;background-color:EEF6FB;}" For m = 1 To Cantidad esParOimpar=(m mod 2) ' se obtiene el valor 0 o 1 para ParOimpar textoFicha= s8DLL.DespliegaVResultados(rMostrar, Total, vfichaBDL, elNumFicha,esParoImpar) ' se obtiene una ficha formateada estilo APA con estilos diferenciados... response.write textoFicha next ...



DespliegaFicha( queFormato,[queFicha],[queNumAdqui],[messageError] )

DespliegaFicha es una función de tipo texto que al invocarse con los parametros apropiados nos regresa el contenido formateado de una ficha en particular. Este método puede ser utilizado para solicitar el contenido de una cierta ficha cuando el dato que se conoce es el número de esa ficha o bien cuando se conoce el número del ejemplar, también llamado numadqui en SIABUC.

queFormato Este parámetro es de entrada de tipo entero y es requerido. Puede tomar cualquiera de los valores definidos en la enumeración de datos formatosDespliegue, pero para la versión 1.0 solo están implementados los valores de vCatalografica (1), vTabla (2), vPersonalizado (3), vfichaTipoAPA (10) y vFichaBDL (11).

queFicha Es un parámetro opcional de tipo entero largo, se usa para recuperar con este valor el contenido de la ficha deseada cuando se conoce su número de ficha. Si se omite este dato, la función esperaría que el parámetro queNumAdqui tuviera el dato faltante para poder recuperar el contenido de cierta ficha.

queNumAdqui Es un parámetro opcional de tipo texto, representa el identificador de un ejemplar, y es utilizado para solicitar el contenido de la ficha a la que le pertenece este número de adquisición. Si este dato es proporcionado pero a la vez se proporciona el número de una ficha mediante el parámetro queFicha, la función DespliegaFicha le dará prioridad al número de la ficha.

MessageError Este es un parámetro opcional de retorno de tipo texto, y se utiliza para poder recuperar el mensaje de error que hubiera ocurrido cuando por alguna razón no se pudo recuperar el contenido de una ficha.

Cuando ocurre un error, la función DespliegaFicha regresará una cadena vacía y en el argumento messageError estaría la información descriptiva del error que se presentó.



Ejemplos de DespliegaFicha con ASP: '-- Despliega una ficha en formato personalizable, dado un num.de ficha elError = "" textoFicha = s8DLL.DespliegaFicha(vPersonalizado, cint(elnumFicha), "", cstr(elError) ) If textoFicha = "" Then Response.write " Alerta: " & elError Else Reponse.write textoFicha End if '-- Despliega una ficha en formato APA, dado un num. de ejemplar elError = "" textoFicha = s8DLL.DespliegaFicha(vfichaTipoAPA,,cstr(queNumAdqui), cstr(elError) ) If textoFicha = "" Then Response.write " Alerta: " & elError Else Reponse.write textoFicha End if

ObtenerTag(queFicha, listNumMARC, [Separador])

ObtenerTag es una función auxiliar para retornar el valor individual de las etiquetas MARC de una ficha dada una lista etiquetas y el número de la ficha en cuestión. Se puede utilizar para recuperar una sola etiqueta o una lista de etiquetas MARC, si fueran varias etiquetas retornará una cadena de texto formateada con los valores de los campos en secuencia y separados por los caracteres "||" (doble pipe).

QueFicha Es un parámetro de entrada requerido de tipo entero, y se utiliza para indicar la ficha sobre la cual se recuperarán los valores de las etiquetas MARC

ListNumMARC Es un parámetro de entrada de tipo texto, utilizado para indicar cual o cuales etiquetas MARC son las que se requieren para obtener su contenido. Cada valor de etiqueta MARC se representa por 3 caracteres que representan los dígitos de la etiqueta MARC. Si se requieren recuperar más de una etiqueta MARC, sus dígitos se escriben seguidos separados por una simple coma.

Separador La función ObtenerTag por default utiliza los caracteres "||" como separadores, utilice este parámetro opcional para cuando se necesite otro caracterer o combinación de caracteres como separador.



Ejemplos de ObtenerTag: a = S8DLL.ObtenerTag(13,"100,245,600") '-- La variable a tomaría los valores del autor, título y encabezamientos ' de la ficha 13 ' Algo como "El autor||El titulo de la obra / autor||valor del tema 600" a = S8DLL.ObtenerTag(150,"050") '-- La variable a tendría el contenido de la etiqueta clasificación LC ' de la ficha 150 a = S8DLL.ObtenerTag(123,"300,500","###") '-- La variable a tomaría los valores de los campos de descripción física ' y de notas de la ficha 123, pero separados por los caracteres ### ' Algo como "314 pág.###Incluye índice"

ResaltaPalabra( txtFuente, txtPalabra, sColor,[bNegrita],[bCursiva] )

ResaltaPalabra es una función auxiliar que se utiliza para resaltar dentro de una ficha la palabra que se ha utilizado como criterio de búsqueda utilizando para ello atributos de color y estilo. El formato de resalte para la palabra se aplicará mediante código HTML ya que esta función se ha diseñado para visualizar la información en páginas web.

txtFuente Representa la cadena de texto sobre la cual se haría la búsqueda del término a resaltar, generalmente será el contenido de una ficha en formato HTML.

txtPalabra Es un parámetro de tipo texto para indicar la palabra o frase que se desea resaltar.

sColor Es un parámetro de entrada de tipo texto que sirve para aplicar un formato de color en código HTML con el cual se resaltaría la palabra deseada. Para asignar un valor con este argumento, debe utilizarse la forma tradicional para asignar colores en HTML, ya sea #RRGGBB que sería asignar el valor de color en formato hexadecimal usando 6 dígitos, o directamente usando el nombre de una constante de color de las conocidas y que han sido definidas en la especificación de HTML.

bNegrita Es un parámetro opcional de tipo falso/verdadero, empleado para indicar si se aplicaría un formato de negrita a la palabra resaltada.



bCursiva Es un parámetro opcional de tipo falso/verdadero, empleado para indicar si se aplicaría un formato de cursiva a la palabra resaltada.

Ejemplos de la función ResaltaPalabra: '—Se resalta la palabra “mexico” con color rojo Salida=s8DLL.resaltaPalabra(cstr(laFicha),"mexico","red") '—Se resalta la palabra “mexico” con color diferente y letra en negrita Salida=s8DLL.resaltaPalabra(cstr(laFicha),"mexico","#006699",true,false) '—Se destaca “mexico” en azul marino y letra en negrita y cursiva Salida=s8DLL.resaltaPalabra(cstr(laFicha),"mexico","navy",true,true)

Propiedades

Version

Propiedad de solo lectura de tipo texto, regresa la valor de la versión de la librería WebS8DLL. La información que se consideró para esta guía corresponde a la versión 1.0.21 del 7 de diciembre de 2006 y es la primera versión pública para los usuarios registrados de SIABUC8. Se recomienda visitar de manera frecuente la página de SIABUC http://siabuc.ucol.mx/ donde se estarán liberando nuevas actualizaciones de esta API.

Ejemplo con ASP: ... ' se visualizan los datos de la versión del componente DLL laVersion= s8DLL.version response.write "La versión del webS8DLL es: " & laVersion

asignaStyle

Es una propiedad de solo escritura de tipo texto, la cual permite agregar una sección de estilos CSS para que el componente WebS8DLL personalice el despliegue de los resultados en pantalla. AsignaStyle solamente se utilizará en combinación con la función DespliegaVresultados cuando el formato de despliegue es el de vFichaBDL y usando el parámetro ParOimpar. Como valor de esta propiedad se debe incluir una sección de estilos CSS donde deberán estar definidos las clases tblColor0 y tblColor1, estos estilos proporcionados de manera externa al componente DLL permitirán una



combinación de colores y estilos distintos para diferenciar cuando varios resultados se muestran de manera consecutiva.

Ejemplo con ASP: ... ' se asigna estilos con la propiedad asignaStyle s8DLL.asignaStyle="tblColor0 {font-size:9pt;background-color:F7F7F7;} tblColor1 {font-size:9pt;background-color:EEF6FB;}" rMostrar=request(fichaINI) For m = 1 To Cantidad esParOimpar=(m mod 2) ' se obtiene el valor 0 o 1 para ParOimpar textoFicha= s8DLL.DespliegaVResultados(rMostrar, Total, vfichaBDL, elNumFicha,esParoImpar) ' se obtiene una ficha formateada estilo APA con estilos diferenciados... ' cuando sea impar se utilizará el estilo tblColor1 y para pares el tblColor0 response.write textoFicha rMostrar= rMostrar + 1 next ...



DERECHOS Y LICENCIAMIENTO

La Universidad de Colima es propietaria de los derechos de propiedad intelectual sobre el software SIABUC y de todos los componentes de la API WebS8DLL. Para poder utilizar la API WebS8DLL es un requisito indispensable que el particular o institución interesada tenga una licencia de uso del software SIABUC otorgada por la Universidad de Colima.

La API WebS8DLL consiste en la librería WebS8DLL.dll, documentación técnica, archivos auxiliares y archivos con ejemplos. Esta API se distribuye de manera gratuita a nuestros usuarios registrados de SIABUC8 y se permite igualmente su distribución libre y gratuita, siempre y cuando se conserven todos los componentes, se incluya la documentación técnica junto con esta licencia de uso.

Se permite a nuestros usuarios registrados utilizar la información contenida en esta documentación junto con sus ejemplos, para tomarlas como base para sus implementaciones. No se permite la decodificación, descompilación, ingeniería inversa ni cualquier otro medio conocido o por conocer para extraer el código fuente del componente DLL o de cualquier otro componente de SIABUC.

Asimismo, no se permite a ninguna persona, empresa o entidad realizar aplicaciones basadas en esta API para lucrar u obtener beneficios económicos, comerciales o de cualquier otra índole, sin la previa autorización de la Universidad de Colima y bajo la firma de un convenio especial de colaboración y desarrollo.



ANEXO A

TestDLL.asp. Archivo de prueba para uso con ASP  <% ' Archivo: TestDLL.asp ' webS8DLL ' Copyright (c) 2006 DGSB. Universidad de Colima. ' ' Archivo básico de prueba de la librería WebS8DLL '------------------------------------------------------------------- 'Antes de ejecutar este archivo de prueba, asegúrese 'de haber realizado los siguientes pasos: ' 0. Tener instalado y configurado su servidor IIS ' 1. Copiar la DLL y los archivos auxiliares (webS8.DLL,webS8.inc) ' en el directorio base de la aplicación, ' por ejemplo, c:\inetpub\wwwroot\ ' 2. Registrar la DLL con el comando "regsvr32.exe" ' p.ejem: regsvr32 webS8.dll ' 3. Asignar permisos de acceso y modificación sobre la carpeta ' de la base de datos al usuario de internet (IUSR_nombremaquina) ' Dim Total 'As Long Dim rInicial 'As Long Dim Cantidad 'As Long Dim rutaBase 'As String Dim strBuscar 'As String Dim elError 'As String Dim rMostrar 'As Long Dim m 'As Long Dim textoFicha 'As String Dim elNumFicha 'As Long Dim cadenaFinal 'As String rutaBase = "C:\temp\bases\" '<-- poner aqui la ruta de las bds de SIABUC8 rInicial = 1 Cantidad = 5 strBuscar="mexico" elNumFicha = 0 Dim s8DLL ' con S8DLL se crea una instancia del componente WebS8DLL Set S8DLL = Server.CreateObject("webs8dll.searchS8") ' se trata de abrir la conexión a la BD de SIABUC elError=s8DLL.InicializarBusqueda(cstr(rutaBase), acervoLibros) If elError="" Then ' no hubo error, entonces continuar a la busqueda response.write "<h5>busqueda inicializada</h5>" If elNumFicha = 0 Then ' se realizará busqueda por palabras ... Total = s8DLL.HacerBusqueda(strBuscar, busqLibre, 0,,,,,,cadenaFinal) If Total > 0 Then ' si hubo resultados mostrar totales y desplegar resultados Response.Write "<b>Busqueda realizada:</b> " & cadenaFinal & ", <b>Regs:</b> " & Total & ", <b>Mostrando: </b>" & Cantidad & " regs, <b>Offset: </b>" & rInicial & "<br/>" rMostrar = rInicial ' con este ciclo se despliegan los resultados rapidos de la consulta For m = 1 To Cantidad ' se despliega cada registro en formato APA textoFicha= s8DLL.DespliegaVResultados(rMostrar, Total, vfichaTipoAPA, elNumFicha) If elNumFicha = - 1 Then Exit For ' criterio del último reg. Response.write "(" & m & ") " & elNumFicha & " - " & textoFicha & "<br/>" rMostrar = rMostrar + 1 Next Else ' si no hubo resultados se manda mensaje de error



Response.write "<h5>No se encontraron registros sobre: " & cadenaFinal & "</h5>" End If Else ' Si numFicha > 0, se despliega directamente una ficha elError = "" textoFicha = s8DLL.DespliegaFicha(vPersonalizado, cint(elnumFicha),"", cstr(elError)) If textoFicha = "" Then Response.write " --------- " & elError Else Response.write textoFicha End If End If Else response.write "<h3>Error al inicializar busqueda</h3>" response.write elError & ", " & rutabase & "," & acervoLibros End If 'cerrar la conexion a la BD if S8DLL.cierraBD then response.write "<h5>BD cerrada...</h5>" else response.write "<h5>Error al cerrar BD</h5>" end if 'liberar de memoria el componente set s8DLL = nothing %>



ANEXO B Funciones auxiliares para uso con ASP <% '-------------------------------------------------------------------- ' Archivo: auxiliares.asp ' webS8DLL ' Copyright (c) 2006 DGSB. Universidad de Colima. ' ' Archivo con definicion de rutinas auxiliares para el procesamiento ' y generacion de las paginas de resultados del sistema de consultas ' de SIABUC8 basado en el componente DLL ' Este archivo se recomienda ubicar en el directorio base de la aplicación ' ASP junto con el archivo “webS8.inc” '-------------------------------------------------------------------- '--- Definicion de Ruta para Ubicacion de archivos HTML de salida --- Const rutaArchivos = "C:\temp\webS8DLL\" public function ReemplazaTag(LaCadena,queTag,NuevoValor) '-- funcion para reemplazar una cadena dentro de otra, ' dise;ada para reemplazar las etiquetas personalizadas ' de SIABUC por su valor correspondiente dim posx, cadInicio, cadReemplazar, cadFinal if LaCadena="" OR queTag="" then ReemplazaTag=LaCadena exit function end if posx=instr(LaCadena,queTag) Do while posx>0 If posx>0 then cadInicio=mid(LaCadena,1,posx-1) cadReemplazar=NuevoValor cadFinal=mid(LaCadena,posx+len(queTag)) LaCadena=cadInicio & cadReemplazar & cadFinal posx=0 posx=instr(LaCadena,queTag) End if Loop ReemplazaTag=Lacadena end function public function LeerArchivo(queArchivo) '-- funcion para leer un archivo de plantilla ' y regresar su contenido como una cadena set fso = Server.Createobject("Scripting.FileSystemObject") dim cadTemp set file = fso.opentextfile(queArchivo, 1) '<-- Se abre de modo lectura do until file.AtEndOfStream cadtemp= cadtemp & file.ReadLine & chr(10) '<--- "& chr(10)" ' para que le ponga un salto de linea loop 'retorna la funcion con el contenido del archivo LeerArchivo=cadtemp end function public sub ProcesaHead(queRuta) '------ se Lee y se envia el encabezado de la pag HTML de respuesta dim cadHEAD if queRuta<>"" then ruta=queRuta else ruta=rutaArchivos end if cadHEAD=LeerArchivo(ruta & "seccionHEAD.htm") response.write cadHEAD end sub



public sub ProcesaMembrete(nombreBiblioteca,queRuta) '------ se Lee la seccion de Identidad de la pag HTML de respuesta ' se reemplazan las etiquetas personalizadas de SIABUC dim cadMembrete if queRuta<>"" then ruta=queRuta else ruta=rutaArchivos end if cadMembrete=LeerArchivo(ruta & "seccionMEMBRETE.htm") 'Se procesan reemplazando las marcas de SIABUC, por el valor de las variables cadMembrete=ReemplazaTag(cadMembrete,"<!NOMBREBIB!>",nombreBiblioteca) cadMembrete=ReemplazaTag(cadMembrete,"<!txtEXPR!>",cadenaFinal) cadMembrete=ReemplazaTag(cadMembrete,"<!TOTAL!>",Total) cadMembrete=ReemplazaTag(cadMembrete,"<!DESDE!>",rInicial) cadMembrete=ReemplazaTag(cadMembrete,"<!DESDESIGUIENTE!>",cint(rInicial) + cint(Cantidad)) cadMembrete=ReemplazaTag(cadMembrete,"<!HASTA!>",rInicial+(Cantidad-1)) if (rInicial=1) then rDesdeAnterior=1 else rDesdeAnterior=(rInicial-Cantidad) end if cadMembrete=ReemplazaTag(cadMembrete,"<!DESDEANTERIOR!>",rDesdeAnterior) cadMembrete=ReemplazaTag(cadMembrete,"<!CANTIDAD!>",cantidad) cadMembrete=ReemplazaTag(cadMembrete,"<!BaseDTA!>",baseDTA) cadMembrete=ReemplazaTag(cadMembrete,"<!txtEXPR1!>",request("txtEXPR1")) cadMembrete=ReemplazaTag(cadMembrete,"<!txtEXPR2!>",request("txtEXPR2")) cadMembrete=ReemplazaTag(cadMembrete,"<!txtEXPR3!>",request("txtEXPR3")) cadMembrete=ReemplazaTag(cadMembrete,"<!opCAMPO1!>",request("opCAMPO1")) cadMembrete=ReemplazaTag(cadMembrete,"<!opCAMPO2!>",request("opCAMPO2")) cadMembrete=ReemplazaTag(cadMembrete,"<!opCAMPO3!>",request("opCAMPO3")) cadMembrete=ReemplazaTag(cadMembrete,"<!opBOOLEAN1!>",request("opBOOLEAN1")) cadMembrete=ReemplazaTag(cadMembrete,"<!opBOOLEAN2!>",request("opBOOLEAN2")) response.write cadMembrete end sub public sub procesaFinal(queRuta) '----- se lee y se envia la seccion final de la pag. de resultados dim cadFinal if queRuta<>"" then ruta=queRuta else ruta=rutaArchivos end if cadFinal=LeerArchivo(ruta & "seccionFINAL.htm") response.write cadFinal end sub %>



ANEXO C

Definición de constantes auxiliares al WebS8DLL para implementación con ASP <% '-------------------------------------------------------------------- ' Archivo: webS8.inc ' webS8DLL ' Copyright (c) 2006 DGSB. Universidad de Colima. ' ' Archivo de Declaracion de constantes para el componente de Busqueda ' de SIABUC8 basado en componente DLL ' Este archivo se recomienda ubicar en el directorio base de la aplicación ' ASP junto con el archivo “auxiliares.asp” '-------------------------------------------------------------------- '---- Constantes para Campos de Busqueda ---- Const busqLibre = 0 ' cualquier campo Const busqTitulo = 1 Const busqAutor = 2 Const busqTemas = 3 Const busqISBN = 4 Const busqEditorial = 5 ' también para Lugar y Año de publicación Const busqSeries = 6 Const busqClasifica = 7 Const busqNotas = 8 Const busqFechas = 9 ' Fecha de publicación y fecha de copyright '---- Constantes para seleccionar el Acervo de Busqueda ---- Const acervoLibros = 0 ' unica implementada para ver 1.0 Const acervoRevistas = 1 Const acervoUsuarios = 2 Const acervoBibliotecas = 3 Const acervoEscuelas = 4 '---- Constantes para tipos de Formatos de Visualizacion ---- Const vListadoRapido = 0 Const vCatalografica = 1 Const vTabla = 2 Const vPersonalizado = 3 ' para cuando se usa plantilla \XSLs\fichaWeb.XSL Const vISO2709 = 5 Const vSBC = 6 Const vfichaTipoAPA = 10 Const vfichaBDL = 11 '---- definicion de valores para operadores booleanos Const opAnd = 0 Const opOr = 1 Const opNot = 2 %>

Documents

Referencia técnica de la API WebS8DLL