X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fegate.sgml;h=72963b66d0469f53d5c821446813771364f6d2de;hb=31c11342a54c8bf4eb004199d23a173343dfcecc;hp=9805f261be58699a1d47d8281d3a950ec036f60d;hpb=6f51f512e5273629d0c8cb603999d2d43e45cf71;p=egate.git diff --git a/doc/egate.sgml b/doc/egate.sgml index 9805f26..72963b6 100644 --- a/doc/egate.sgml +++ b/doc/egate.sgml @@ -1,13 +1,13 @@
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. @@ -23,22 +23,24 @@ 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 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/: @@ -46,35 +48,40 @@ 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 @@ -93,7 +100,7 @@ The <tt/sendmail/ or a similar program delivers the mail to the 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 @@ -101,7 +108,7 @@ 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 @@ -445,7 +452,7 @@ The work was roughly carried out as follows: 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 @@ -506,6 +513,9 @@ Information about each result set includes: <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> @@ -526,10 +536,117 @@ CCL parser itself is not tied to Bib-1. <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