<!doctype linuxdoc system>
<!--
- $Id: egate.sgml,v 1.9 1996/04/25 10:21:53 adam Exp $
+ $Id: egate.sgml,v 1.10 1996/06/06 10:24:57 adam Exp $
-->
<article>
<title>Email/Z39.50 gateway guide
-<author>Europagate, 1995
-<date>$Revision: 1.9 $
+<author>Europagate, 1996
+<date>$Revision: 1.10 $
<abstract>
This document describes a Email server that provides access to the
Z39.50 protocol.
<sect>Introduction
<p>
-This document describes an email server subsystem developed
+This document describes an email server (ES) system developed
within the EUROPAGATE project. The first part of this document
serves as an administrators guide, while the second part is a
-follow-up on the Design deliverable (WP4.1) that outline the
+follow-up on the Design deliverable (WP4.1) that outlines the
deviations from the design. Also, the second part contains
a quick overview of the source code.
-<sect>Compilation
+The software distribution also includes a Web to Z39.50 gateway. Refer
+to the web.txt documentation about installation on this gateway.
+
+<sect>Installation
<p>
An ANSI C compiler is required in order to compile the ES software.
bugs. Therefore we've included a patch <tt/zdist.patch/ which fixes
some of these bugs.
Run patch in the directory above <tt/zdist102b1-1/:
-<tscreen><verb>
-$ patch <zdist.patch
-</verb></tscreen>
-
+<verb>patch <zdist.path</verb>
The ES server only depends on <tt>libz3950.a</tt> so you only need
to build the zdist software in the directory <tt/libz3950/.
<htmlurl url="ftp://ftp.indexdata.dk/index/yaz"
name="ftp://ftp.indexdata.dk/index/yaz">
-The ES also use GNU's regex package to parse regular expressions.
+The ES also uses GNU's regex package to parse regular expressions.
The ES has been tested with regex-0.12. Some systems, such as Linux,
come with the regex package preinstalled.
Unpack <tt>egate.tar.gz</tt> and edit the top level <tt/Makefile/. Specify
-where the GNU regex package is located and specify whether you use
-YAZ or zdist. One some systems, you may have to set the <tt/NETLIB/ as
-well.
+where the GNU regex package is located by setting the variables <tt/REGEXOBJ/
+and <tt/REGXINC/.
+
+A little further down the <tt/Makefile/ you find a section called
+<tt/Common settings/ where you specify the location of either YAZ or zdist.
+On some systems, you may have to set the <tt/ELIB/ as well to link with
+BSD socket libraries.
+
+If you intend only to compile the Email server and not the Web server
+you don't have to worry about the section entitled <tt/WWW gateway settings/.
The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the
-<tt/Makefile/ so you may modify these before compiling.
+<tt/Makefile/ so you may set these in your shell before you start
+compiling.
Now, type <tt/make email/.
-<sect>Installation
-
<p>
If the compilation succeeds, you should install the software in some
-system location.
+standard location.
Edit the <tt/Makefile/ and set EMAILLIBDIR to the installation
directory. Since, the ES is executed by the mail system, and not by a
user, this directory shouldn't be globally executable.
<sect>LICENSE
<p>
- Copyright © 1995, the EUROPAGATE consortium (see below).
+ Copyright © 1995-1996, the EUROPAGATE consortium (see below).
The EUROPAGATE consortium members are:
--- /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 / commitdiff