Gua de referencia tcnica de la API WebS8DLL

para SIABUC8

API

WebS8DLL

INTERFAZ DE PROGRAMACIN DE APLICACIONES PARA EL MOTOR DE BSQUEDAS DE SIABUC8 BASADA EN COMPONENTE DLL. WEBS8_DLL 1.0

Gua de referencia tcnica de la API WebS8DLL para SIABUC8

Preparado por J. Romn Herrera M. Diciembre de 2006 Departamento de SIABUC Direccin 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 institucin interesada. Queda prohibido el uso y /o modificacin de los smbolos distintivos de SIABUC as como la explotacin, comercializacin o prestacin de servicios, materiales y/o documentacin relacionados a este software, sin la previa autorizacin 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.

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

CONTENIDO
Introduccin Qu es la API WebS8DLL? El componente de bsqueda de SIABUC con CGI CGI versus DLL Descripcin de la API WebS8DLL Requerimientos para utilizar la WebS8DLL Ejemplo de uso de la WebS8DLL con ASP Pasos mnimos para el uso de la WebS8DLL Mtodos y propiedades de la WebS8DLL InicializarBD CerrarBD HacerBusqueda DespliegaVResultados DespliegaFicha ObtenerTag ResaltaPalabra Version AsignaStyle Derechos y Licenciamiento 2 2 2 2 4 4 5 8 9 9 10 10 12 14 15 16 17 17 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

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 1

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 mdulos de SIABUC, por ejemplo, la implementacin de los catlogos de consulta al acervo por web utilizando tecnologas ASP o PHP. Esta API WebS8DLL con el paso del tiempo vendr a sustituir la implementacin anterior que tena el SIABUC para desarrollar los catlogos en web la cual est basada en un componente CGI llamado WebS8.exe

El componente de bsqueda de SIABUC con CGI Desde la versin SIABUC Win de 1995, se incorpor la posibilidad de montar los catlogos en web, la primera implementacin 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 liberacin de SIABUC Siglo XXI en 1999 se incluy la nueva versin del componente CGI de bsqueda para 32 bits el cual se llam webXXI.exe. Y la ltima versin basada en CGI es el actual web_S8.exe incluido desde la primera edicin de SIABUC8 a partir del 2003.

CGI versus DLL Sin duda fue de gran utilidad el poder incorporar la bsqueda de informacin bibliogrfica desde internet basada en los componentes CGI de SIABUC, sin embargo al ser una tecnologa CGI, siempre se tuvieron ciertas desventajas si se compara con las tecnologas 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 operacin de consulta ha concluido. Si se tienen 50 usuarios haciendo bsquedas en ese momento, en el servidor habr 50 procesos CGI. Con la nueva WebS8DLL solo se genera un nico proceso para cualquier peticin compartiendo recursos en el servidor, con lo que se optimiza e incrementa su desempeo.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 2

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

Relacionadas con la seguridad. Para la utilizacin de aplicaciones CGI hay que otorgar permisos explcitos de ejecucin o de escritura para ciertos recursos del servidor, esta situacin en muchas instituciones es inaceptable debido a sus polticas de seguridad interna, ya que las aplicaciones CGI exponen de manera notable al servidor. Una aplicacin CGI diseada con mala intencin, 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 implementacin. La aplicaciones CGI de SIABUC son cdigo compilado y encapsulado que no permite a nuestros usuarios realizar modificaciones y proporciona un mecanismo de presentacin de resultados basado en archivos de configuracin externos (archivos CFG), esta lgica de implementacin en muchos casos ha resultado confusa y de difcil personalizacin. Con el nuevo modelo basado en la webS8DLL, los webmasters de cada institucin podrn disear previamente sus plantillas web para mostrar la opcin de consultas y despliegue de los resultados, stas plantillas simplemente se incorporarn a la programacin web con ASP y PHP donde se instanciar el componente webS8DLL para utilizar sus funciones predefinidas de bsqueda y recuperacin de datos.

En resumen, con la distribucin 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 tendrn ahora mayores posibilidades de personalizacin y de integracin del sistema de consultas en sus aplicaciones nuevas o ya existentes, as como mayores facilidades de implementacin y de mantenimiento, potenciando con ello su imaginacin y creatividad.

* Obviamente las aplicaciones CGI de SIABUC no contienen ningn cdigo malicioso y se disearon para auxiliar y prestar mejores servicios de informacin bibliogrfica, por lo que agradecemos a las instituciones que confan en nuestros desarrollos y han implementado sus catlogos web con SIABUC.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 3

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

DESCRIPCION DE LA API WEBS8DLL

La API WebS8DLL est representada por un conjunto de cdigo encapsulado que contiene funciones y propiedades que posibilitan la conexin a la base de datos del SIABUC, permiten realizar bsquedas en el acervo bibliogrfico y visualizar la informacin seleccionada en diferentes formatos preestablecidos. La API est compuesta por el archivo webS8DLL.dll, el cual es una librera de enlace dinmico (llamadas comnmente DLL), una referencia tcnica para su uso y unos archivos de ejemplo con cdigo en ASP para ejemplificar su implementacin en servidores IIS de Microsoft. Esta API se obtiene al descargar el archivo API_webS8DLL.rar de la pgina 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 cmputo que soporte la creacin o instanciacin de componentes activeX debido a que la librera webS8DLL es una librera desarrollada con tecnologa activeX de Microsoft. En consecuencia, se podra 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. Tambin es posible utilizar tecnologa PHP, ya que permite instanciar objetos COM y por consiguiente utilizar la librera WebS8DLL, as para instituciones que no utilicen tecnologa 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 implementacin, debido a que en esta gua no se ha incluido ningn cdigo de ejemplo con PHP.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 4

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 implementacin bsica de catlogos web con SIABUC8, adems de esta documentacin de referencia. La estructura de directorios y contenido de archivos es la siguiente:
directorio \bases Descripcin del contenido En esta carpeta se deben colocar las bases de datos de SIABUC (siabuc8.mdb, estadisticas.mdb e indizado.mdb). Esta ubicacin es sugerida y para fines de ejemplificacin, en una situacin real la ruta de las bases de datos puede ser en cualquier otra ubicacin siempre y cuando el componente webS8DLL tuviera acceso y permisos de lectura y escritura. En esta carpeta encontrar este documento de referencia tcnica de la API webS8DLL y en un futuro cualquier otra informacin adicional. Esta carpeta servir como directorio raz de su aplicacin web, aqu se incluyen los archivos de la librera webS8DLL.dll, un archivo de prueba llamado testDLL.asp y otros archivos ASP auxiliares, adems de los archivos de ejemplo desarrollados con cdigo en ASP. Se incluyen tambin unas subcarpetas \images, donde se ubicaran las imgenes 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 tambin son sugeridas y para fines de ejemplificacin. Un webmaster con experiencia puede cambiar la ubicacin de los archivos y ponerlos donde los necesite, pero tendr que realizar varios cambios en la configuracin preestablecida de los mismos y tambin en la consola de administracin del IIS, por ejemplo, tendr que hacer uso de la definicin de directorios virtuales, asignacin de los permisos correspondientes y redireccionamiento de los hipervnculos de los archivos de ejemplo, para lograr una implementacin exitosa.

\docs \wwwroot

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 annimo 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 estadstico de la misma.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 5

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

Despus, con la consola de administracin del IIS hay que configurar las propiedades del Sitio Web Predeterminado para seleccionar a la subcarpeta
\API_webS8DLL\wwwroot\

como directorio raz o directorio principal del IIS.

Tambin, se debe registrar la librera 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 raz del ejemplo, podr utilizarlo escribiendo en el navegador la siguiente direccin: http://localhost/test.asp, tambin es recomendable sustituir el localhost por el nombre del servidor o la direccin IP de esa computadora. Si TestDLL.asp se ejecuta adecuadamente le indicar que tuvo xito en los diferentes pasos crticos 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 bsqueda 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 pgina principal y punto de inicio para el sistema de consultas se llama catalogo.htm, en su navegador escriba la siguiente direccin http://localhost/catalogo.htm Al realizar las bsquedas, el sistema le mostrar en primera instancia una lista de resultados rpidos agrupados de 10 en 10, al igual que en los ejemplos del CGI de SIABUC8, se permite la navegacin entre pginas de resultados y el despliegue de informacin detallada para una ficha seleccionada. Una de las diferencias ms interesantes de esta implementacin basada en el componente webS8DLL es que ya no se utilizarn los archivos CFG, en su lugar se usan plantillas web. Estas plantillas web son en realidad una pgina web previamente diseada y que fue dividida en secciones. Con los archivos de ejemplo con cdigo de ASP y algunas funciones auxiliares se logra la inclusin 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.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 6

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

Revise los cdigos 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 prediseadas. Entendiendo el funcionamiento bsico de esta nueva implementacin con la webS8DLL, posteriormente podr modificar y adaptar los archivos y plantillas de ejemplo, para que desplieguen en pantalla sus catlogos web ya personalizados de una manera muy sencilla. Sin duda, en poco tiempo podr crear sus propios archivos de cdigo con ASP o con PHP y desarrollar nuevas funciones y formas de visualizar e interactuar con los datos recuperados desde SIABUC. Se vale compartir cdigo para la implementacin de los OPACs y el foro de SIABUC ( http://siabuc.ucol.mx/?opc=9.foro ) puede ser el medio ms apropiado de comunicacin.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 7

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

Pasos mnimos para el uso de la WebS8DLL

Si desea probar la DLL con otros archivos que nos sean los de ejemplo pero que utilizan cdigo de ASP, asegrese 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 aplicacin, por ejemplo, c:\inetpub\wwwroot\ por ejemplo:
c:\API_webS8DLL\wwwroot\

3. Registrar la DLL con el comando "regsvr32.exe" ,

regsvr32 webS8DLL.dll

4. Asignar permisos de acceso y modificacin 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 librera como se describi en el punto 3. Adems, verificar que el usuario de Windows con el que utilizar la aplicacin tenga acceso de escritura a la carpeta donde estn las bases de datos de SIABUC.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 8

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

MTODOS Y PROPIEDADES DE LA WEBS8DLL

La librera WebS8DLL versin 1.0 incluye 7 mtodos, 2 propiedades y 4 enumeraciones de datos disponibles para el usuario programador, a continuacin se describen las funciones y propiedades y se incluyen pequeos fragmentos de cdigo para ejemplificar su uso. Funciones

InicializarBusqueda( rutaBD, [queAcervo] ) InicializarBusqueda es el mtodo para establecer un vnculo con la base de datos de SIABUC, es indispensable su uso antes de poder realizar cualquiera de las tareas del componente de bsqueda. Al ejecutarse retornar una cadena vaca si la inicializacin tuvo xito, o un mensaje de error si no se pudo establecer la conexin a la base de datos. rutaBD es un parmetro 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 parmetro opcional de entrada de tipo entero, que sirve para definir el acervo sobre el cual se van a realizar las bsquedas, 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 informacin sobre la enumeracin AcervoBusqueda con la lista de todos los valores posibles que pueden tomar y que podran ser usados para este parmetro.
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 conexin: & sError end if

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 9

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 conexin: & sError end if

CierraBD() CierraBD es una funcin boolena sin parmetros, que retorna verdadero si la conexin 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>" end if 'liberar componente DLL set s8DLL = nothing

'mensaje de error

HacerBusqueda( expresion1, [campoBusqueda1], [opBooleano1], [expresion2], [campoBusqueda2], [opBooleano2], [expresion3], [campoBusqueda3], [cadenaResultante] ) HacerBusqueda es la funcin que nos permite hacer bsquedas en el acervo previamente seleccionado, retorna un valor entero que indica la cantidad de registros encontrados. Se puede utilizar para realizar bsquedas booleanas avanzadas combinando el valor textual de la expresin de bsqueda, el campo donde se har la bsqueda y el operador booleano a utilizar. Se pueden combinar hasta 3 expresiones booleanas con sus parmetros opcionales de entrada. expresion1..3 Son parmetros de entrada de tipo texto usados para indicar una expresin de bsqueda. Slo el primer parmetro es requerido.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 10

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

CampoBusqueda1..3 Con estos parmetros se pueden hacer bsquedas muy precisas en el acervo ya que permiten indicar el campo de la base de datos sobre el que se realizar la bsqueda, por ejemplo, si se har en todos los campos (bsqueda libre), o si ser por ttulo, por autor, etc.. Estos parmetros son de entrada y opcionales, cuando se omiten, su valor predeterminado es 0, que indica que se usar la bsqueda libre. Revisar en el Anexo C la enumeracin de datos CamposBusqueda para conocer todas las posibilidades. OpBooleano1..2 Son parmetros opcionales de entrada de tipo entero, que sirven para indicar el tipo de operador booleano que se debe utilizar para combinar las expresiones de bsqueda, si omiten su valor por default ser 0 que representa la operacin de AND. Sus posibles valores son 0 para AND, 1 para OR y 2 para NOT. Tambin existe la enumeracin de datos operadorBooleano con la definicin de estos valores. CadenaResultante Es un parmetro de retorno opcional de tipo texto que regresa la expresin de bsqueda resultante de la combinacin de expresiones.

Ejemplos con ASP: '-- Hacer busqueda con el campo Libre de un formulario .... '-- 1er parametro se lee de la coleccin 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 ... ..

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 11

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

DespliegaVResultados ( regInicialMostrar, TotalEncontrados, formatoSalida, [outNumFichaObtenido], [ParOimpar] ) La funcin 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 funcin HacerBusqueda, es decir, esta funcin es complementaria a la funcin de HacerBusqueda y se utiliza para recuperar de uno en uno cada registro encontrado. Esta funcin no debe usarse sin la funcin HacerBusqueda. RegInicialMostrar es un parmetro entero de entrada que indica el nmero del resultado a mostrar, es importante diferenciar que se refiere al nmero de resultado encontrado y no al nmero de la ficha a visualizar. Este parmetro y la invocacin de esta funcin dentro de un ciclo son muy tiles para formar de manera rpida y sencilla las pginas de resultados rpidos de una consulta. TotalEncontrados es un parmetro de entrada de tipo entero que se utiliza como referencia a la funcin complementaria HacerBusqueda FormatoSalida en un parmetro entero de entrada que sirve para indicar el formato de visualizacin que tendr el registro solicitado, puede tomar valores definidos en la enumeracin formatosDespliegue, pero para la versin 1.0 slo 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 parmetro entero opcional de salida que proporcionar el nmero de ficha correspondiente para el resultado que se estar desplegando con esta funcin. OutNumFichaObtenido puede ser muy til para desencadenar con este valor la visualizacin en detalle del registro seleccionado mediante la funcin DespliegaFicha. ParOimpar Es un parmetro opcional de entrada, cuando existe solo debe tomar 2 valores, o es 1 o es 0. Este prametro aplica cuando se utiliza el formato vFichaBDL y se utiliza en combinacin con la propiedad asignaStyle. Su funcin es

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 12

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

proporcionar un mecanismo para identificar a un rengln 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 clasificacin usando tambin la funcin 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>" response.write " <td>" response.write " <td>" response.write " <td>" response.write "</tr>" rMostrar = rMostrar + 1 Next

& & & &

elNumFicha & "</td>" titulo & "</td>" autor & "</td>" clasDewey & "</td>"

Ejemplo con ASP para asignacin 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 ...

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 13

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

DespliegaFicha( queFormato,[queFicha],[queNumAdqui],[messageError] ) DespliegaFicha es una funcin de tipo texto que al invocarse con los parametros apropiados nos regresa el contenido formateado de una ficha en particular. Este mtodo puede ser utilizado para solicitar el contenido de una cierta ficha cuando el dato que se conoce es el nmero de esa ficha o bien cuando se conoce el nmero del ejemplar, tambin llamado numadqui en SIABUC. queFormato Este parmetro es de entrada de tipo entero y es requerido. Puede tomar cualquiera de los valores definidos en la enumeracin de datos formatosDespliegue, pero para la versin 1.0 solo estn implementados los valores de vCatalografica (1), vTabla (2), vPersonalizado (3), vfichaTipoAPA (10) y vFichaBDL (11). queFicha Es un parmetro opcional de tipo entero largo, se usa para recuperar con este valor el contenido de la ficha deseada cuando se conoce su nmero de ficha. Si se omite este dato, la funcin esperara que el parmetro queNumAdqui tuviera el dato faltante para poder recuperar el contenido de cierta ficha. queNumAdqui Es un parmetro 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 nmero de adquisicin. Si este dato es proporcionado pero a la vez se proporciona el nmero de una ficha mediante el parmetro queFicha, la funcin DespliegaFicha le dar prioridad al nmero de la ficha. MessageError Este es un parmetro opcional de retorno de tipo texto, y se utiliza para poder recuperar el mensaje de error que hubiera ocurrido cuando por alguna razn no se pudo recuperar el contenido de una ficha. Cuando ocurre un error, la funcin DespliegaFicha regresar una cadena vaca y en el argumento messageError estara la informacin descriptiva del error que se present.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 14

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 funcin auxiliar para retornar el valor individual de las etiquetas MARC de una ficha dada una lista etiquetas y el nmero de la ficha en cuestin. 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 parmetro de entrada requerido de tipo entero, y se utiliza para indicar la ficha sobre la cual se recuperarn los valores de las etiquetas MARC ListNumMARC Es un parmetro 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 dgitos de la etiqueta MARC. Si se requieren recuperar ms de una etiqueta MARC, sus dgitos se escriben seguidos separados por una simple coma. Separador La funcin ObtenerTag por default utiliza los caracteres "||" como separadores, utilice este parmetro opcional para cuando se necesite otro caracterer o combinacin de caracteres como separador.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 15

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

Ejemplos de ObtenerTag: a = S8DLL.ObtenerTag(13,"100,245,600") '-- La variable a tomara los valores del autor, ttulo 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 tendra el contenido de la etiqueta clasificacin LC ' de la ficha 150

a = '-' '

S8DLL.ObtenerTag(123,"300,500","###") La variable a tomara los valores de los campos de descripcin fsica y de notas de la ficha 123, pero separados por los caracteres ### Algo como "314 pg.###Incluye ndice"

ResaltaPalabra( txtFuente, txtPalabra, sColor,[bNegrita],[bCursiva] ) ResaltaPalabra es una funcin auxiliar que se utiliza para resaltar dentro de una ficha la palabra que se ha utilizado como criterio de bsqueda utilizando para ello atributos de color y estilo. El formato de resalte para la palabra se aplicar mediante cdigo HTML ya que esta funcin se ha diseado para visualizar la informacin en pginas web. txtFuente Representa la cadena de texto sobre la cual se hara la bsqueda del trmino a resaltar, generalmente ser el contenido de una ficha en formato HTML. txtPalabra Es un parmetro de tipo texto para indicar la palabra o frase que se desea resaltar. sColor Es un parmetro de entrada de tipo texto que sirve para aplicar un formato de color en cdigo HTML con el cual se resaltara la palabra deseada. Para asignar un valor con este argumento, debe utilizarse la forma tradicional para asignar colores en HTML, ya sea #RRGGBB que sera asignar el valor de color en formato hexadecimal usando 6 dgitos, o directamente usando el nombre de una constante de color de las conocidas y que han sido definidas en la especificacin de HTML. bNegrita Es un parmetro opcional de tipo falso/verdadero, empleado para indicar si se aplicara un formato de negrita a la palabra resaltada.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 16

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

bCursiva Es un parmetro opcional de tipo falso/verdadero, empleado para indicar si se aplicara un formato de cursiva a la palabra resaltada.
Ejemplos de la funcin 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 versin de la librera WebS8DLL. La informacin que se consider para esta gua corresponde a la versin 1.0.21 del 7 de diciembre de 2006 y es la primera versin pblica para los usuarios registrados de SIABUC8. Se recomienda visitar de manera frecuente la pgina de SIABUC http://siabuc.ucol.mx/ donde se estarn liberando nuevas actualizaciones de esta API.
Ejemplo con ASP: ... ' se visualizan los datos de la versin del componente DLL laVersion= s8DLL.version response.write "La versin del webS8DLL es: " & laVersion

asignaStyle Es una propiedad de solo escritura de tipo texto, la cual permite agregar una seccin de estilos CSS para que el componente WebS8DLL personalice el despliegue de los resultados en pantalla. AsignaStyle solamente se utilizar en combinacin con la funcin DespliegaVresultados cuando el formato de despliegue es el de vFichaBDL y usando el parmetro ParOimpar. Como valor de esta propiedad se debe incluir una seccin de estilos CSS donde debern estar definidos las clases tblColor0 y tblColor1, estos estilos proporcionados de manera externa al componente DLL permitirn una

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 17

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

combinacin 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 ...

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 18

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 institucin interesada tenga una licencia de uso del software SIABUC otorgada por la Universidad de Colima. La API WebS8DLL consiste en la librera WebS8DLL.dll, documentacin tcnica, archivos auxiliares y archivos con ejemplos. Esta API se distribuye de manera gratuita a nuestros usuarios registrados de SIABUC8 y se permite igualmente su distribucin libre y gratuita, siempre y cuando se conserven todos los componentes, se incluya la documentacin tcnica junto con esta licencia de uso. Se permite a nuestros usuarios registrados utilizar la informacin contenida en esta documentacin junto con sus ejemplos, para tomarlas como base para sus implementaciones. No se permite la decodificacin, descompilacin, ingeniera inversa ni cualquier otro medio conocido o por conocer para extraer el cdigo 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 econmicos, comerciales o de cualquier otra ndole, sin la previa autorizacin de la Universidad de Colima y bajo la firma de un convenio especial de colaboracin y desarrollo.

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 19

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

ANEXO A TestDLL.asp. Archivo de prueba para uso con ASP

<!--#include file=webS8.inc --> <% ' Archivo: TestDLL.asp ' webS8DLL ' Copyright (c) 2006 DGSB. Universidad de Colima. ' ' Archivo bsico de prueba de la librera WebS8DLL '------------------------------------------------------------------'Antes de ejecutar este archivo de prueba, asegrese '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 aplicacin, ' 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 modificacin 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\" rInicial = 1 Cantidad = 5 strBuscar="mexico" elNumFicha = 0 '<-- poner aqui la ruta de las bds de SIABUC8

Dim s8DLL ' con S8DLL se crea una instancia del componente WebS8DLL Set S8DLL = Server.CreateObject("webs8dll.searchS8") ' se trata de abrir la conexin 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

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 20

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 %>

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 21

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 aplicacin ' 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

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 22

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

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 %>

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 23

Gua de Referencia Tcnica de la API WebS8DLL para SIABUC8

ANEXO C Definicin de constantes auxiliares al WebS8DLL para implementacin 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 aplicacin ' ASP junto con el archivo auxiliares.asp '-------------------------------------------------------------------'---Const Const Const Const Const Const Const Const Const Const Constantes para busqLibre = busqTitulo = busqAutor = busqTemas = busqISBN = busqEditorial = busqSeries = busqClasifica = busqNotas = busqFechas = Campos de Busqueda ---0 ' cualquier campo 1 2 3 4 5 ' tambin para Lugar y Ao de publicacin 6 7 8 9 ' Fecha de publicacin y fecha de copyright

'---Const Const Const Const Const

Constantes para seleccionar el Acervo de Busqueda ---acervoLibros = 0 ' unica implementada para ver 1.0 acervoRevistas = 1 acervoUsuarios = 2 acervoBibliotecas = 3 acervoEscuelas = 4

'---Const Const Const Const Const Const Const Const

Constantes para tipos de Formatos de Visualizacion ---vListadoRapido = 0 vCatalografica = 1 vTabla = 2 vPersonalizado = 3 ' para cuando se usa plantilla \XSLs\fichaWeb.XSL vISO2709 = 5 vSBC = 6 vfichaTipoAPA = 10 vfichaBDL = 11

'---Const Const Const %>

definicion de valores para operadores booleanos opAnd = 0 opOr = 1 opNot = 2

2006. Departamento de SIABUC. DGSB. Universidad de Colima

Pgina 24