From: Adam Dickmeiss Date: Mon, 3 Jul 1995 12:58:17 +0000 (+0000) Subject: More documentation in sgml. X-Git-Url: http://lists.indexdata.dk/?a=commitdiff_plain;h=ec950c9aca0cdb121f344b7a27b6015f8c1c9cab;p=egate.git More documentation in sgml. --- diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..fba62fc --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,22 @@ +# $Id: Makefile,v 1.1 1995/07/03 12:58:17 adam Exp $ +all: egate.ps egate.txt egate.html + +egate.txt: egate.sgml + sgml-format -T nroff egate| qroff >egate.txt + +egate.dvi: egate.sgml + sgml-format egate| qtex -d >egate.dvi + +egate.ps: egate.sgml + sgml-format egate| qtex -x + mv out.ps egate.ps + +egate.html: egate.sgml + sgml-format -T html egate | prehtml | fixref >tmp.html + sgml-format -T html egate | prehtml >>tmp.html + html2html egate egate.html + rm tmp.html + +clean: + rm -f [0-9]* *.bak + diff --git a/doc/egate.sgml b/doc/egate.sgml new file mode 100644 index 0000000..fcadabe --- /dev/null +++ b/doc/egate.sgml @@ -0,0 +1,267 @@ + + + + +
+Email/Z39.50 gateway guide +<author>Europagate, 1995 +<date>$Revision: 1.1 $ +<abstract> +This document describes a Email server that provides access to the +Z39.50 protocol. +</abstract> + +<toc> + +<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. + +<sect>Before you begin + +<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 +Index Data to interface the Z39.50 protocol. So you need to obtain +either of these first. + +The Zdist package can be found in: + +<url url="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/zdist102b1-1.tar.Z" > + +The zdist doesn't support result-set references. Also, it has a few +bugs — see the file zdist.es.patch for details. + +YAZ can be found in: + +<url url="ftp://ftp.algonet.se/pub/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. + +<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 +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/. + +Now, type <tt/make/. + +<sect>Installation + +<p> +If the compilation was successful, you should install the software. +Edit the <tt/Makefile/ and set the LIBDIR 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/. + +Three executables are installed in LIBDIR: +<descrip> +<tag/eti/ The email transport interface. This program receives +incoming mail, identifies the user, and delivers the mail request +to the monitor or kernel (depending on configuration). +<tag/monitor/ The monitor + is optional component. The main objective +of the monitor is to limit the number of simultanous running kernel +processes. +<tag/kernel/ The kernel process is the core of the ES. It parses +the user's requests and interfaces the Z39.50 protocols. +</descrip> + +The <tt/sendmail/ or a similar program delivers the mail to the +<tt/eti/ program. The <tt/sendmail/ program usually runs as user +<tt/mail/ or some other special user name. We strongly suggest that +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. + +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>usr/lib/aliases</tt>). Now add the following line: + +<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 +<tt>/usr/local/lib/es</tt>. + +The ES system can operate with or without the monitor. When using +the monitor the number of simultanous running kernels can be +controlled. If the <tt>eti</tt> program is started with option +<tt>--</tt> it will operate without the monitor. + +<sect1>With the monitor + +<p> +The monitor must be running at all times in this mode. You should +start the monitor in one of your boot scripts (rc). For example this +might be put in a boot script: + +<tscreen><verb> +(cd /usr/local/lib/es; ./monitor -d -l mon.log -- -d -l kernel.log &) +</verb></tscreen> + +Here the monitor is started with the options <tt>-d -l mon.log</tt> +and the options after the two dashes are transferred to the +kernel. In this mode, the eti should contact the monitor (and not +the kernel), so the following might be put in the aliases file: + +<tscreen><verb> +es:"|/usr/local/lib/es/eti -c /usr/local/lib/es" +</verb></tscreen> + +The eti sets current directory to the path specified by option <tt>-c</tt>. + +<sect1>Without the monitor + +<p> +In this mode you should never start the monitor. +The eti will contact the kernel directly. The following line could +be put in your aliases file: + +<tscreen><verb> +es:"|/usr/local/lib/es/eti -c /usr/local/lib/es -- -d -l kernel.log" +</verb></tscreen> + +<sect1>eti + +<p> +The eti program accepts the following options: +<descrip> +<tag><tt>-l </tt>log</tag> The log file. If absent stderr is used. +<tag><tt>-d</tt></tag> Turns on debugging. +<tag><tt>-c </tt>dir</tag> Sets current directory to dir. +<tag><tt>--</tt></tag> Indicates that the eti program should contact the +kernel (and not the monitor. All options are this one are transferred +to the kernel +<tag><tt>-H</tt></tag> Help message. +</descrip> + +<sect1>monitor + +<p> +The monitor program accepts the following command line options: +<descrip> +<tag><tt>-l </tt>log</tag> The log file. If absent stderr is used. +<tag><tt>-d</tt></tag> Turns on debugging. +<tag><tt>-H</tt></tag> Help message. +<tag><tt>--</tt></tag> Precedes options that are transferred to the kernel +</descrip> + +The monitor normally reads the resource <tt>default.res</tt> in +current directory. You can change this behaviour by specifying an +alternate file on the command line. + +<sect1>kernel + +<p> +List of options observed by the kernel: +<descrip> +<tag><tt>-d</tt></tag> Turns on debugging. +<tag><tt>-t </tt>target</tag> Opens connection to target (for testing only). +<tag><tt>-g </tt>lang</tag> Set language name. +<tag><tt>-o </tt>res</tag> Overriding resource file name. These +resources override both <tt>default.res</tt> and all user resources. +<tag><tt>-h </tt>host</tag> Override host name (for testing only). +<tag><tt>-p </tt>port</tag> Override port no (for testing only). +<tag><tt>-l </tt>log</tag> Specify log file. +<tag><tt>-H</tt></tag> Help message. +</descrip> + +The kernel normally reads the resource <tt>default.res</tt> in +current directory. You can change this behaviour by specifying an +alternate file on the command line. + +<sect>Managing the system + +<p> + +<sect1>Files + +<p> +To maintain the ES you need to know the files it uses. These are: +<descrip> +<tag>*.res</tag> Resource files with several settings that control + how the system operates, such as definition of targets, messages, etc. +<tag>lang.*.res</tag> Resource file for a particular langauge. +<tag>*.bib</tag> Bib-1 attribute mapping files. These files describe + the mapping between CCL and the RPN query. +<tag>user.db</tag> Database of users. Only the eti process access + this file. +<tag>user.*.r</tag> Resource file for a user — accessed by the kernel + — only created when the user uses the <tt>def</tt> command. +<tag>user.*.p</tag> Persistency file for a user — accessed by + the kernel + process. +</descrip> + +The ES system is mostly managed by resource files. The following +resource files are enclosed with the ES: +<descrip> +<tag><tt>default.res</tt></tag> General resource with reasonable defaults. + This file is read by the monitor and the kernel. +<tag><tt>loc.res</tt></tag> Resource file for Library of Congress test + server. +<tag><tt>drewdb.res</tt></tag> Resource file for Data Research's test + server. +<tag><tt>lang.uk.res</tt></tag> Resource file for english conversation. +<tag><tt>lang.dk.res</tt></tag> Resource file for danish conversation. +</descrip> + +<sect1>General resources + +<p> +Most general resources can be found in default.res. Some of the +resources may be changed (overridden) by the user, while others may be +overriden by individual target defintions. + +<p> +The following table lists general resources: +<descrip> +<tag>gw.reply.mta</tag> Name of MTA program. +<tag>gw.reply.tmp.prefix</tag> Prefix of temporary files used by the ES. +<tag>gw.reply.tmp.dir</tag> Name of directory with temporary files. +<tag>gw.marc.log</tag> If this resource is specified, retrieved MARC + records will be appended to this file. +<tag>gw.timeout</tag> Idle time before the kernel exists. When the + kernel exists, the Z39.50 persistency layer will reconnect when + necessary. +<tag>gw.resultset</tag> If this setting is 1, the Z39.50 client will + use named result sets. If 0, the Z39.50 will always use Default as + result-set name. +<tag>gw.persist</tag> If this setting 1, the persistency is enabled; + disabled otherwise. +<tag>gw.max.process</tag> This settings is the maximum number of + simultaneous kernel processes — only used by the monitor. +<tag>gw.ignore.which</tag> Some targets doesn't indicate whether + a record is a diagnostic messaage or a database record. If this + setting is 1, the ES will always try to interpret the record as a + database record in ISO2709 format. If 0, the ES will use the + record type. +<tag>gw.default.show</tag> Default number of records to retrieve and display + when using the show command. This setting may be changed by the user. +<tag>gw.max.show</tag> This setting specifies the maximum number of + records the user may retrieve in one show command — default 100. +<tag>gw.autoshow</tag> Number of records to retrieve in a find + command — default 0. This setting may be changed by the user. +<tag>gw.display.format</tag> Default display format. This setting may + be changed by the user. +<tag>gw.language</tag> Current language. This setting may be +changed by the user. +</descrip> + +</article>