From: Adam Dickmeiss Date: Mon, 10 Jul 1995 10:28:22 +0000 (+0000) Subject: More documentation. X-Git-Url: http://lists.indexdata.com/cgi-bin?a=commitdiff_plain;h=6f51f512e5273629d0c8cb603999d2d43e45cf71;p=egate.git More documentation. --- diff --git a/doc/egate.sgml b/doc/egate.sgml index d891eca..9805f26 100644 --- a/doc/egate.sgml +++ b/doc/egate.sgml @@ -1,13 +1,13 @@
Email/Z39.50 gateway guide <author>Europagate, 1995 -<date>$Revision: 1.4 $ +<date>$Revision: 1.5 $ <abstract> This document describes a Email server that provides access to the Z39.50 protocol. @@ -18,11 +18,14 @@ Z39.50 protocol. <sect>Introduction <p> -This document describes how to compile, install and setup the -Email server (ES) software. It does not address the internal design of -the software. +This document describes an email server subsystem 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 +deviations from the design. Also, the second part contains +an overview of the source code. -<sect>Before you begin +<sect>Compilation <p> An ANSI C compiler is required in order to compile the ES software. @@ -36,7 +39,7 @@ The Zdist package can be found in: <url url="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 -bugs. Therefore we've included a patch <tt/<zdist.patch/ which fixes +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> @@ -51,9 +54,6 @@ 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. -<sect>Compilation - -<p> 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 @@ -111,7 +111,7 @@ two dashes (<tt>--</tt>) it will operate without the monitor and the options specified after the two dashes are transferred to the kernel. -<sect1>With the monitor +<sect1>Running with the monitor <p> The monitor must be running at all times in this mode. You should @@ -133,7 +133,7 @@ es:"|/usr/local/lib/es/eti -c /usr/local/lib/es" The eti sets current directory to the path specified by option <tt>-c</tt>. -<sect1>Without the monitor +<sect1>Running without the monitor <p> In this mode you should never start the monitor. @@ -382,7 +382,7 @@ The type is simply one of the six Bib-1 attribute query types: both left and right (3) truncation indicated by a <tt/?/ on both left and right side of a term. <tag/n/ This character indicates that the CCL parser should announce - no truncation (100) if no truncation was indicated. + no truncation (100) if no truncation was specified. </descrip> <tag/p/ Position attribute. Valus is an integer. <tag/s/ Structure attribute. Value is an integer; or the @@ -421,6 +421,116 @@ find date>1990 </verb></tscreen> where the use attribute is <em/date/ and the relation is <em/greater than/. +<sect>Implementation + +<p> +The implementation of the email server includes all the modules described +in the design deliverable. + +The work was roughly carried out as follows: +<enum> +<item>The logging facilities and resource management utilities were + implemented — virtually all other modules depend on these + modules. +<item>A minimal ES was implemented — including a high-level + API to the Z39.50 sub-system and a CCL parser with a few + commands, such as FIND and SHOW. This version displayed MARC + records in a raw format. This version served as base for the URP. +<item>The first version of the MARC display formatting tool, FML, + was implemented and included in the ES. +<item>The ETI program was implemented along with the IPC + (interprocess communication) utilities based on FIFOs. Facilities + to keep connections alive (to Z39.50 targets) was implemented. + To identify a user, a file-resident symbol table (small database) was + 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. +</enum> + +The following sections cover the most important modules in the ES and +deviations from the design. + +<sect1>Z39.50 Interface layer + +<p> +The design report specified that the Zdist toolkit from CNIDR would +be used in the ES to provide access to the Z39.50 protocol. The package +was choosen bacause it is easy to use and, more important, we felt +that the API would be reasonably stable and supported. + +Nevertheless it turned out that CNIDR choose to change the API +completely around January 1995 and announced a new version +called zdist102b1-1. + +<em>Note: As of this date the newest version of Zdist is still +zdist102b1-1. CNIDR seems to concentracte on their Isite package +which also includes a Zdist package presumably similar to the +standalone Zdist package</em> + +During the work with the Zdist package a few bugs were discovered. +Fortunately, they could be solved within a few days. We also +discovered that the package lacks result-set references. +We posted the bug fixes to Kevin Gamiel who is responsible for +the package but we didn't get responses. So, eventually, we weren't +satisfied with the package after all. + +In February some of us began the development of a new Z39.50 package +called YAZ — in retrospect somewhat motivated by the +experiences with existing Z39.50/SR toolkits. + +To support result-set references we chose to incorporate a YAZ +interface in the ES also. And we designed and implemented a +simple high-level Z39.50 origin API that supported both Zdist and YAZ. + +The protocol persistency module was implemented on top of +the high-level API and not on top of Zdist. The obvious +advantage is that the persistency module is not tied to one +particular Z39.50/SR package. + +Persistency information stored for each user is simply: +<itemize> +<item>hostname and port number. +<item>authentication string +<item>selected database(s) +<item>next result set number +<item>next result set position +<item>result set information +</itemize> + +Information about each result set includes: +<itemize> +<item>name +<item>size (number of hits) +<item>database(s) +<item>query +</itemize> + +<sect1>CCL + +<p> +The CCL was implemented as described in the design. A CCL utility +was made as a separate module which implements a tokenization +package and a parser which translates from FIND to RPN. The +data structure used to represent the RPN query is also used in +Z39.50 search API on top of YAZ or Zdist. + +The CCL parser is quite configurable. Token names can be redefined to +one or more names (aliases). Also, the specification of mapping +between CCL field names (qualifiers) and Bib-1 attributes can be +specified in either the C API or a file. + +Although the Z39.50 system in the ES uses the Bib-1 attribute set, the +CCL parser itself is not tied to Bib-1. + +<sect1>FML + +<p> + +<sect1>IPC + +<p> + <sect>LICENSE <p>