--- /dev/null
+<!doctype linuxdoc system>
+
+<!--
+ $Id: web.sgml,v 1.1 1996/06/06 10:24:58 adam Exp $
+-->
+
+<article>
+<title>Web/Z39.50 gateway guide
+<author>Europagate, 1996
+<date>$Revision: 1.1 $
+<abstract>
+This document describes a Web server that provides access to the
+Z39.50 protocol.
+</abstract>
+
+<toc>
+
+<sect>Introduction
+
+<p>
+The EUROPAGATE project developed two Z39.50 gatways that served as
+Z39.50 clients: an email gateway and a web gateway. This document
+describes how to compile and install the web gateway. For information
+about the email gateway see the document egate.txt.
+
+<sect>Installation
+
+<p>
+An ANSI C compiler is required in order to compile the software.
+
+The gateway uses IrTcl and YAZ from Index Data to interface the
+Z39.50 protocol.
+
+YAZ and IrTcl can be found at the FTP host:
+
+<htmlurl url="ftp://ftp.indexdata.dk/index/yaz"
+ name="ftp://ftp.indexdata.dk/index/yaz">
+
+You also need the Tcl package which can be found at:
+
+<htmlurl url="ftp://ftp.sunlabs.com/pub/tcl"
+ name="ftp://ftp.sunlabs.com/pub/tcl">
+
+Unpack <tt>egate.tar.gz</tt> and edit the top level
+<tt/Makefile/. Specify where the YAZ package can be found by setting
+the the include path <tt/ZINC/, and the YAZ library <tt/ZLIB/.
+Some systems need extra socket libraries - in this case set the
+<tt/ELIB/ variable. You need also to define the location of Tcl:
+<tt/TCLLIB/ and <tt/TCLINC/ - and the location of IrTcl:
+<tt/IRTCLLIB/ and <tt/IRTCLINC/.
+
+The gateway scripts and the Z39.50 communication tools are located
+in the <tt/EGWDIR/ directory. This setting is hardcoded in the
+CGI program (<tt/egwcgi/) and therefore it must be defined before
+compiling. The CGI program, <tt/egwcgi/, will be installed in the
+<tt/CGIDIR/ directory. HTML - and images files are installed in
+the <tt/HTDOCS/ and the <tt/GIFDIR/ directories respectively.
+
+The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the
+<tt/Makefile/ so you may modify these in your shell before compiling.
+
+Now, type <tt/make web/
+
+If the compilation succeeds, you should install the software in target
+directories, by issuing: <tt/make install.web/.
+
+A HTML file called <tt/egwindex.html/ should be installed in your
+<tt/HTDOCS/ directory. Read it with your browser and click on the
+<it>single target</it> button to test it out.
+
+<sect>Overview of the system
+<p>
+
+<sect1>The <tt/egwcgi/ program.
+<p>
+The <tt/egwcgi/ program uses the CGI interface to communicate with
+your HTTP server. It is the only program that communicates with your
+server and it needs to be installed in your CGI binaries directory
+(<tt/CGIDIR/).
+
+The program inspects the URL and contacts a shell server
+specified after the name of the CGI program.
+The URL takes the form:
+
+http://host/cgi-bin/egwcgi/shell/argument
+
+where <it/shell/ is the name of the shell server to invoke. The
+<it/argument/ is transferred to the <it/shell/ program.
+
+When the <tt/egwcgi/ program is started by a URL as above, it will
+assign a unique session-ID. If the shell wishes to be stateful it
+should return a page that includes references with the newly
+assigned session-ID.
+In this case all subsequent URLs should contain this session-ID
+with the following form:
+
+http://host/cgi-bin/egwcgi/sessionID/argument
+
+The only difference from the initial URL is that the shell part is
+substituted with a numeric session-ID. If the <tt/egwcgi/ program
+gets a reference to this kind of URL, it will try to contact a running
+shell. If that fails, it will restart it. To communicate with the
+shell the <tt/egwcgi/ program uses FIFOs (names pipes) whose names
+include the session-ID.
+
+The <tt/egwcgi/ program will initially change its current directory
+to <tt/EGWDIR/ as specified in the <tt/Makefile/.
+
+<sect1>The shell system.
+
+<p>
+The shell system is, basically, a shell program, a few maintenance
+files, and a set of scripts. All files in the shell system are stored
+in the <tt/EGWDIR/ directory.
+
+The files are summarized below:
+
+<descrip>
+<tag/egwtcl/ A Tcl shell server - reads HTML with embedded Tcl and
+commands to inspect CGI variables. Note: this shell is currently
+unused because this shell doesn't support Z39.50.
+
+<tag/egwirtcl/ The IrTcl shell server. The IrTcl shell reads HTML
+files with embedded Tcl scripts as well as Z39.50 extensions added by the
+IrTcl library.
+
+<tag/*.tcl/ Tcl scripts - located in the <tt/EGWDIR/ directory.
+The <tt/z39util.tcl/ file declares a lot of Tcl functions to
+facilitate Z39.50 communication as well as other utilities.
+
+<tag/*.egw/ Web scripts with embedded Tcl - located in the <tt/EGWDIR/
+directory. Normally, each script correspond to one type of Web
+page. For example, the <tt/query.egw/ script contacts a single
+target and displays a search form; the <tt/search.egw/ script
+makes a Z39.50 search/present and displays the result.
+
+<tag/ztargets.conf/ Target configuration file. A sort of profile is
+defined for each target: the name of the target, record syntax,
+search fields and mapping to bib-1, etc.
+
+<tag/egw.res/ Small configuration file; defines a shell's idle time,
+the log-level, and the directory for FIFOs used by the gateway.
+</descrip>
+
+When the system is running a number of files are created:
+<descrip>
+<tag/www.db/ Database that maps from session-IDs to shells.
+
+<tag/tcl.state.*/ User session states; these are stored as Tcl
+variables.
+
+<tag/egwcgi_log/ Log file for the <tt/egwcgi/ program.
+
+<tag/egwsh_log/ Log file for the shells <tt/egwtcl/, <tt/egwirtcl/, etc.
+
+<tag/irtcl_log/ YAZ log file created by the IrTcl library. The file
+only includes information about Z39.50 communication.
+</descrip>
+
+<sect>LICENSE
+
+<p>
+ Copyright © 1995-1996, the EUROPAGATE consortium (see below).
+
+ The EUROPAGATE consortium members are:
+
+<itemize>
+<item>University College Dublin
+<item>Danmarks Teknologiske Videnscenter
+<item>An Chomhairle Leabharlanna
+<item>Consejo Superior de Investigaciones Cientificas
+</itemize>
+
+ Permission to use, copy, modify, distribute, and sell this software and
+ its documentation, in whole or in part, for any purpose, is hereby granted,
+ provided that:
+
+ 1. This copyright and permission notice appear in all copies of the
+ software and its documentation. Notices of copyright or attribution
+ which appear at the beginning of any file must remain unchanged.
+
+ 2. The names of EUROPAGATE or the project partners may not be used to
+ endorse or promote products derived from this software without specific
+ prior written permission.
+
+ 3. Users of this software (implementors and gateway operators) agree to
+ inform the EUROPAGATE consortium of their use of the software. This
+ information will be used to evaluate the EUROPAGATE project and the
+ software, and to plan further developments. The consortium may use
+ the information in later publications.
+
+ 4. Users of this software agree to make their best efforts, when
+ documenting their use of the software, to acknowledge the EUROPAGATE
+ consortium, and the role played by the software in their work.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
+ WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+ IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE
+ FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF
+ ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
+ OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND
+ ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
+ USE OR PERFORMANCE OF THIS SOFTWARE.
+
+</article>
projects / egate.git / blobdiff