<!doctype linuxdoc system>
<!--
- $Id: egate.sgml,v 1.6 1995/07/10 13:55:25 adam Exp $
+ $Id: egate.sgml,v 1.12 1996/08/28 08:03:48 adam Exp $
-->
<article>
-<title>Email/Z39.50 gateway guide
-<author>Europagate, 1995
-<date>$Revision: 1.6 $
+<title>Email/Z39.50 gateway guide
+<author>Europagate, 1996 <htmlurl url="http://europagate.dtv.dk"
+ name="http://europagate.dtv.dk">
+<date>$Revision: 1.12 $
<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
-within the EUROPAGATE project. The first part of this document
+This document describes an email server (ES) system developed
+within the <htmlurl url="http://europagate.dtv.dk" name="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
-an overview of the source code.
+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.
-The ES can use either CNIDR's zdist package or the YAZ package from
+The ES can use either CNIDR's Zdist package or the YAZ package from
Index Data to interface the Z39.50 protocol. So you need to obtain
-either of these first.
+one of these first.
-The Zdist package can be found in:
+The zdist package can be found in:
-<url url="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/zdist102b1-1.tar.Z" >
+<htmlurl
+url="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/archive/1.02/zdist102b1-1.tar.Z"
+name="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/archive/1.02/zdist102b1-1.tar.Z">
-The Zdist package doesn't support result-set references. Also, it has a few
+The zdist package doesn't support result-set references. Also, it has a few
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/.
-YAZ can be found in:
+YAZ can be found at the FTP host:
-<url url="ftp://ftp.algonet.se/pub/index/yaz/">.
+<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,
-comes with the regex package preinstalled.
+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/.
-You may wish to set <tt/CC/ and <tt/CFLAGS/ in your shell, since these
-will affect the compilation — these are not set in the <tt/Makefile/.
+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.
-Now, type <tt/make/.
+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/.
-<sect>Installation
+The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the
+<tt/Makefile/ so you may set these in your shell before you start
+compiling.
+
+Now, type <tt/make email/.
<p>
-If the compilation was successful, you should install the software.
-Edit the <tt/Makefile/ and set the LIBDIR to the installation
+If the compilation succeeds, you should install the software in some
+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.
-When satisfied, type <tt/make install/.
+When satisfied, type <tt/make install.email/.
-Three executables are installed in LIBDIR:
+Three executables are installed in EMAILLIBDIR:
<descrip>
<tag/eti/ The email transport interface. This program receives
incoming mail, identifies the user, and delivers the mail request
you create a special user and group for the ES software. In this case
you should use <tt/chmod/ to and set the 'set user ID on execution'
bits on the executable files and give that user read/write/execute
-permissions in LIBDIR.
+permissions in EMAILLIBDIR.
The mail system needs to know about the ES. Pick some name that serves
as the ES user and edit <tt/aliases/ used by your mail system (usually
<tt>es:"|/usr/local/lib/es/eti </tt><em>options</em><tt>"</tt>
-In this example the mail user name was <tt/es/ and the LIBDIR was
+In this example the mail user name is <tt/es/ and the EMAILLIBDIR is
<tt>/usr/local/lib/es</tt>.
The ES system can operate with or without the monitor. When using
implemented which maps a email username to a unique integer (email userid).
<item>The protocol persistency was implemented and more CCL commands
were added.
-<item>The MONITOR program was implemented.
+<item>The monitor program was implemented.
</enum>
The following sections cover the most important modules in the ES and
<p>
As described in the design, FIFOs are used to communicate between
-the ETI, MONITOR and KERNEL. The ES can run without the MONITOR,
-however. The primary reason for the presence of the MONITOR was
-to assure that the KERNELs would release the resources used by the
+the ETI, monitor and kernel. The ES can run without the monitor,
+however. The primary reason for the presence of the monitor was
+to assure that the kernel releases the resources used by the
persistency layer. But, since the persistency layer did turn out to
use virtually no disk space at all, there was no point in starting
-a KERNEL process to remove its files — hence this facility
-was not implemented. The only purpose of the MONITOR is to keep the
-number of running KERNELs at a maximum level and even that
-is probably useless since most unices will swap KERNEL processes
+a kernel process to remove its files — hence this facility
+was not implemented. The only purpose of the monitor is to keep the
+number of running kernels at a maximum level and even that
+is probably useless since most unices will swap kernel processes
out anyway.
The idle time
-before a KERNEL exits and saves its persistency file is not
-controlled by the MONITOR. Saving the persistency file and
+before a kernel exits and saves its persistency file is not
+controlled by the monitor. Saving the persistency file and
keeping it is usually a good approach — even when a
user doesn't reference/show old result-sets since the user
has a notion of <em/current target/ and database.
<tag>Database utility</tag> implemented in <tt>gw-db.[ch]</tt>. This
utility is used to map a user (email) to an integer.
<tag>String queue utility</tag> implemented in <tt>strqueue.[ch]</tt>. This
- utiltiy is used to queue incoming mail in the ETI, KERNEL and
- the MONITOR.
+ utiltiy is used to queue incoming mail in the ETI, kernel and
+ the monitor.
<tag>Pretty printer</tag> implemented in <tt>ttyemit.[ch]</tt>
— used by the URP.
<tag>FIFO IPC utiltiy</tag> implemented in <tt>gip*.[ch]</tt> —
- used by the ETI, KERNEL and MONITOR.
+ used by the ETI, kernel and monitor.
</descrip>
<tag/fml/ implements FML. The top level functions are implemented
of YAZ. This task is implemented in <tt>zaccess.c</tt>. The
public header file is called <tt>zaccess.h</tt>.
-<tag/kernel/ implements the ETI, KERNEL and MONITOR. The kernel
+<tag/kernel/ implements the ETI, kernel and monitor. The kernel
itself is implemented in <tt>main.c</tt>, <tt>urp.c</tt> and
<tt>persist.c</tt>. The ETI is implemented in <tt>eti.c</tt> and
- the MONITOR is implemented <tt>monitor.c</tt>.
+ the monitor is implemented <tt>monitor.c</tt>.
</descrip>
<sect>LICENSE
<p>
- Copyright © 1995, the EUROPAGATE consortium (see below).
+ Copyright © 1995-1996, the EUROPAGATE consortium (see below).
The EUROPAGATE consortium members are:
projects / egate.git / blobdiff