API WebS8DLL para SIABUC8

Guía de referencia
técnica de la
API WebS8DLL
para SIABUC8
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
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.
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
CONTENIDO
Introducción
¿Qué es la API WebS8DLL?
El componente de búsqueda de SIABUC con CGI
CGI versus DLL
2
2
2
2
Descripción de la API WebS8DLL
Requerimientos para utilizar la WebS8DLL
Ejemplo de uso de la WebS8DLL con ASP
Pasos mínimos para el uso de la WebS8DLL
4
4
5
8
Métodos y propiedades de la WebS8DLL
InicializarBD
CerrarBD
HacerBusqueda
DespliegaVResultados
DespliegaFicha
ObtenerTag
ResaltaPalabra
Version
AsignaStyle
9
9
10
10
12
14
15
16
17
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
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 1
Guía de Referencia Técnica 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 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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 2
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
•
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 3
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 4
Guía de Referencia Técnica 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 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
\bases
Descripción del contenido
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 5
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 6
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 7
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 8
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 9
Guía de Referencia Técnica 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 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>"
end if
'liberar componente DLL
set s8DLL = nothing
'mensaje de error
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 10
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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
...
..
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 11
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 12
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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>"
response.write " <td>"
response.write " <td>"
response.write " <td>"
response.write "</tr>"
rMostrar = rMostrar + 1
&
&
&
&
elNumFicha & "</td>"
titulo & "</td>"
autor & "</td>"
clasDewey & "</td>"
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
...
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 13
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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ó.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 14
Guía de Referencia Técnica 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 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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 15
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 16
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 17
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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
...
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 18
Guía de Referencia Técnica 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 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.
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 19
Guía de Referencia Técnica 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 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\"
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 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
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 20
Guía de Referencia Técnica 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
Página 21
Guía de Referencia Técnica 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 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
© 2006. Departamento de SIABUC. DGSB. Universidad de Colima
Página 22
Guía de Referencia Técnica 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
Página 23
Guía de Referencia Técnica de la API WebS8DLL para SIABUC8
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”
'-------------------------------------------------------------------'---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 ' también para Lugar y Año de publicación
6
7
8
9 ' Fecha de publicación 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
Página 24