doc/web.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!--
   4   $Id: web.sgml,v 1.2 1996/06/06 10:34:34 adam Exp $
   5 -->
   6
   7 <article>
   8 <title>Web/Z39.50 gateway guide
   9 <author>Europagate, 1996
  10 <date>$Revision: 1.2 $
  11 <abstract>
  12 This document describes a Web server that provides access to the
  13 Z39.50 protocol.
  14 </abstract>
  15
  16 <toc>
  17
  18 <sect>Introduction
  19
  20 <p>
  21 The EUROPAGATE project developed two Z39.50 gatways that served as
  22 Z39.50 clients: an email gateway and a web gateway. This document
  23 describes how to compile and install the web gateway. For information
  24 about the email gateway see the document egate.txt.
  25
  26 <sect>Installation
  27
  28 <p>
  29 An ANSI C compiler is required in order to compile the software.
  30
  31 The gateway uses IrTcl and YAZ from Index Data to interface the
  32 Z39.50 protocol.
  33
  34 YAZ and IrTcl can be found at the FTP host:
  35
  36 <htmlurl url="ftp://ftp.indexdata.dk/index/yaz"
  37  name="ftp://ftp.indexdata.dk/index/yaz">
  38
  39 You also need the Tcl package which can be found at:
  40
  41 <htmlurl url="ftp://ftp.sunlabs.com/pub/tcl"
  42  name="ftp://ftp.sunlabs.com/pub/tcl">
  43
  44 Unpack <tt>egate.tar.gz</tt> and edit the top level
  45 <tt/Makefile/. Specify where the YAZ package can be found by setting
  46 the the include path <tt/ZINC/, and the YAZ library <tt/ZLIB/.
  47 Some systems need extra socket libraries - in this case set the
  48 <tt/ELIB/ variable. You need also to define the location of Tcl:
  49 <tt/TCLLIB/ and <tt/TCLINC/ - and the location of IrTcl:
  50 <tt/IRTCLLIB/ and <tt/IRTCLINC/.
  51
  52 The gateway scripts and the Z39.50 communication tools are located
  53 in the <tt/EGWDIR/ directory. This setting is hardcoded in the
  54 CGI program (<tt/egwcgi/) and therefore it must be defined before
  55 compiling. The CGI program, <tt/egwcgi/, will be installed in the
  56 <tt/CGIDIR/ directory. HTML - and images files are installed in
  57 the <tt/HTDOCS/ and the <tt/GIFDIR/ directories respectively.
  58
  59 The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the
  60 <tt/Makefile/ so you may modify these in your shell before compiling.
  61
  62 Now, type <tt/make web/
  63
  64 If the compilation succeeds, you should install the software in target
  65 directories, by issuing: <tt/make install.web/.
  66
  67 A HTML file called <tt/egwindex.html/ should be installed in your
  68 <tt/HTDOCS/ directory. The page contains miscellaneous starting links
  69 to the Z39.50 gateway. Read it with your browser and click on the
  70 <it>single target</it> button to test it out.
  71
  72 <sect>Overview of the system
  73 <p>
  74
  75 <sect1>The <tt/egwcgi/ program.
  76 <p>
  77 The <tt/egwcgi/ program uses the CGI interface to communicate with
  78 your HTTP server. It is the only program that communicates with your
  79 server and it needs to be installed in your CGI binaries directory
  80 (<tt/CGIDIR/).
  81
  82 The program inspects the URL and contacts a shell server
  83 specified after the name of the CGI program.
  84 The URL takes the form:
  85
  86 http://host/cgi-bin/egwcgi/shell/argument
  87
  88 where <it/shell/ is the name of the shell server to invoke. The
  89 <it/argument/ is transferred to the <it/shell/ program.
  90
  91 When the <tt/egwcgi/ program is started by a URL as above, it will
  92 assign a unique session-ID. If the shell wishes to be stateful it
  93 should return a page that includes references with the newly
  94 assigned session-ID.
  95 In this case all subsequent URLs should contain this session-ID
  96 with the following form:
  97
  98 http://host/cgi-bin/egwcgi/sessionID/argument
  99
 100 The only difference from the initial URL is that the shell part is
 101 substituted with a numeric session-ID. If the <tt/egwcgi/ program
 102 gets a reference to this kind of URL, it will try to contact a running
 103 shell. If that fails, it will restart it. To communicate with the
 104 shell the <tt/egwcgi/ program uses FIFOs (names pipes) whose names
 105 include the session-ID.
 106
 107 The <tt/egwcgi/ program will initially change its current directory
 108 to <tt/EGWDIR/ as specified in the <tt/Makefile/.
 109
 110 <sect1>The shell system.
 111
 112 <p>
 113 The shell system is, basically, a shell program, a few maintenance
 114 files, and a set of scripts. All files in the shell system are stored
 115 in the <tt/EGWDIR/ directory.
 116
 117 The files are summarized below:
 118
 119 <descrip>
 120 <tag/egwtcl/ A Tcl shell server - reads HTML with embedded Tcl and
 121 commands to inspect CGI variables. Note: this shell is currently
 122 unused because this shell doesn't support Z39.50.
 123
 124 <tag/egwirtcl/ The IrTcl shell server. The IrTcl shell reads HTML
 125 files with embedded Tcl scripts as well as Z39.50 extensions added by the
 126 IrTcl library.
 127
 128 <tag/*.tcl/ Tcl scripts - located in the <tt/EGWDIR/ directory.
 129 The <tt/z39util.tcl/ file declares a lot of Tcl functions to
 130 facilitate Z39.50 communication as well as other utilities.
 131
 132 <tag/*.egw/ Web scripts with embedded Tcl - located in the <tt/EGWDIR/
 133 directory. Normally, each script correspond to one type of Web
 134 page. For example, the <tt/query.egw/ script contacts a single
 135 target and displays a search form; the <tt/search.egw/ script
 136 makes a Z39.50 search/present and displays the result.
 137
 138 <tag/ztargets.conf/ Target configuration file. A sort of profile is
 139 defined for each target: the name of the target, record syntax,
 140 search fields and mapping to bib-1, etc.
 141
 142 <tag/egw.res/ Small configuration file; defines a shell's idle time,
 143 the log-level, and the directory for FIFOs used by the gateway.
 144 </descrip>
 145
 146 When the system is running a number of files are created:
 147 <descrip>
 148 <tag/www.db/ Database that maps from session-IDs to shells.
 149
 150 <tag/tcl.state.*/ User session states; these are stored as Tcl
 151 variables.
 152
 153 <tag/egwcgi_log/ Log file for the <tt/egwcgi/ program.
 154
 155 <tag/egwsh_log/ Log file for the shells <tt/egwtcl/, <tt/egwirtcl/, etc.
 156
 157 <tag/irtcl_log/ YAZ log file created by the IrTcl library. The file
 158 only includes information about Z39.50 communication.
 159 </descrip>
 160
 161 <sect>LICENSE
 162
 163 <p>
 164  Copyright &copy; 1995-1996, the EUROPAGATE consortium (see below).
 165
 166  The EUROPAGATE consortium members are:
 167
 168 <itemize>
 169 <item>University College Dublin
 170 <item>Danmarks Teknologiske Videnscenter
 171 <item>An Chomhairle Leabharlanna
 172 <item>Consejo Superior de Investigaciones Cientificas
 173 </itemize>
 174
 175  Permission to use, copy, modify, distribute, and sell this software and
 176  its documentation, in whole or in part, for any purpose, is hereby granted,
 177  provided that:
 178
 179  1. This copyright and permission notice appear in all copies of the
 180  software and its documentation. Notices of copyright or attribution
 181  which appear at the beginning of any file must remain unchanged.
 182
 183  2. The names of EUROPAGATE or the project partners may not be used to
 184  endorse or promote products derived from this software without specific
 185  prior written permission.
 186
 187  3. Users of this software (implementors and gateway operators) agree to
 188  inform the EUROPAGATE consortium of their use of the software. This
 189  information will be used to evaluate the EUROPAGATE project and the
 190  software, and to plan further developments. The consortium may use
 191  the information in later publications.
 192
 193  4. Users of this software agree to make their best efforts, when
 194  documenting their use of the software, to acknowledge the EUROPAGATE
 195  consortium, and the role played by the software in their work.
 196
 197  THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
 198  EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
 199  WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 200  IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE
 201  FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF
 202  ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
 203  OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND
 204  ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
 205  USE OR PERFORMANCE OF THIS SOFTWARE.
 206
 207 </article>