<!doctype linuxdoc system>
<!--
- $Id: egate.sgml,v 1.5 1995/07/10 10:28:22 adam Exp $
+ $Id: egate.sgml,v 1.9 1996/04/25 10:21:53 adam Exp $
-->
<article>
<title>Email/Z39.50 gateway guide
<author>Europagate, 1995
-<date>$Revision: 1.5 $
+<date>$Revision: 1.9 $
<abstract>
This document describes a Email server that provides access to the
Z39.50 protocol.
serves as an administrators guide, while the second part is a
follow-up on the Design deliverable (WP4.1) that outline 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
<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/zdist102b1-1.tar.Z"
+ name="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/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/:
$ patch <zdist.patch
</verb></tscreen>
-YAZ can be found in:
+The ES server only depends on <tt>libz3950.a</tt> so you only need
+to build the zdist software in the directory <tt/libz3950/.
-<url url="ftp://ftp.algonet.se/pub/index/yaz/">.
+YAZ can be found at the FTP host:
+
+<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 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.
-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/.
+The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the
+<tt/Makefile/ so you may modify these before compiling.
-Now, type <tt/make/.
+Now, type <tt/make email/.
<sect>Installation
<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
+system 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
<item>query
</itemize>
+A persistency file is removed each time a new target is selected.
+It is our experiences that the persistency files are very small.
+
<sect1>CCL
<p>
<sect1>FML
<p>
+The FML system is used to handle the presentation of MARC
+records. There are some deviations to the design report, however.
+The most important changes are:
+<itemize>
+<item>The <tt/expr/ function is not implemented. Instead arithmetic
+operators <tt/plus/, <tt/minus/, <tt/mult/ and <tt/div/ are
+implemented. Also relational operators <tt/gt/, <tt/lt/ ... are
+implemented.
+<item>The <tt/lindex/ function is called <tt/index/ and it is a binary
+operator where the left operand is the list and the right operand is
+the index integer.
+<item>The MARC extraction routines are not implemented.
+Instead, a MARC record is transferred as an argument
+to a formatting-routine (in list notation). The formatting
+routine then extracts fields from the list by list/string
+manipulation functions.
+<item>A new statement, <tt/bin/, is implemented to define
+binary operators (functions).
+</itemize>
<sect1>IPC
<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 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
+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
+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.
+
+<sect1>Source
+
+<p>
+In this section a short description of each source module is
+given. Each module is implemented in a separate sub directory.
+Any public headers are located in the <tt/include/ directory.
+
+<descrip>
+<tag/res+log/ is an implementation of the logging system
+and the resource management sub system. Note that the
+resource module depends on the logging facility. Logging
+is implemented in <tt>gw-log.c</tt> and <tt/gw-log.h/. The
+file <tt>gw-log-test.c</tt> is small test program for the
+logging system. The core of the resource management is implemented
+in <tt>gw-res.c</tt>. The files <tt>gw-res-bool.c</tt> and
+<tt>gw-res-int.c</tt> implement two utility routines &mdash
+on top of the resource management. The header file
+<tt>gw-resp.h</tt> is a private header file and <tt>gw-res.h</tt>
+is a public header file.
+
+<tag/ccl/ implements CCL to RPN mapping and a tokenization
+ utility for other CCL commands. The mapping function is
+ implemented in <tt>cclfind.c</tt>. Qualifiers are handled in
+ <tt>cclqual.c</tt> while reading of qualifier mappings from a
+ file is implemented in <tt>cclqfile.c</tt>. Scanning is implemented
+ in <tt>ccltoken.c</tt>. String utilities, which might be changed if
+ other character sets are needed, is implemented in
+ <tt>cclstr.c</tt>. Table of error messages is implemented in
+ <tt>cclerrms.c</tt>.
+
+<tag/util/ implements various utilities:
+ <descrip>
+ <tag>MARC utility</tag> implemented in <tt>iso2709</tt>...
+ <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.
+ <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.
+ </descrip>
+
+<tag/fml/ implements FML. The top level functions are implemented
+ in <tt>fml.c</tt>, <tt>fmlcall.c</tt> and <tt>fmlcalls.c</tt>.
+ Scanning is implemented in <tt>fmltoken.c</tt>.
+ Memory management is implemented in <tt>fmlmem.c</tt>.
+ Arithmetic operators are implemented in <tt>fmlarit.c</tt>.
+ String manipulation functions are implemented in <tt>fmlstr.c</tt>.
+ Relational operators are implemented in <tt>fmlrel.c</tt>.
+ List maniuplations are performed in <tt>fmllist.c</tt>.
+ FML symbol table management is implemented in <tt>fmlsym.c</tt>.
+ Conversion from ISO2709 to list notation is implemented in
+ <tt>fmlmarc.c</tt>.
+
+<tag/zlayer-zdist/ implements the high-level Z39.50 API on top
+ of Zdist. This task is implemented in <tt>zaccess.c</tt>. The
+ public header file is called <tt>zaccess.h</tt>.
+
+<tag/zlayer-yaz/ implements the high-level Z39.50 API on top
+ 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
+ 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>.
+</descrip>
<sect>LICENSE
projects / egate.git / blobdiff