1 <!doctype linuxdoc system>
4 $Id: web.sgml,v 1.1 1996/06/06 10:24:58 adam Exp $
8 <title>Web/Z39.50 gateway guide
9 <author>Europagate, 1996
10 <date>$Revision: 1.1 $
12 This document describes a Web server that provides access to the
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.
29 An ANSI C compiler is required in order to compile the software.
31 The gateway uses IrTcl and YAZ from Index Data to interface the
34 YAZ and IrTcl can be found at the FTP host:
36 <htmlurl url="ftp://ftp.indexdata.dk/index/yaz"
37 name="ftp://ftp.indexdata.dk/index/yaz">
39 You also need the Tcl package which can be found at:
41 <htmlurl url="ftp://ftp.sunlabs.com/pub/tcl"
42 name="ftp://ftp.sunlabs.com/pub/tcl">
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/.
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.
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.
62 Now, type <tt/make web/
64 If the compilation succeeds, you should install the software in target
65 directories, by issuing: <tt/make install.web/.
67 A HTML file called <tt/egwindex.html/ should be installed in your
68 <tt/HTDOCS/ directory. Read it with your browser and click on the
69 <it>single target</it> button to test it out.
71 <sect>Overview of the system
74 <sect1>The <tt/egwcgi/ program.
76 The <tt/egwcgi/ program uses the CGI interface to communicate with
77 your HTTP server. It is the only program that communicates with your
78 server and it needs to be installed in your CGI binaries directory
81 The program inspects the URL and contacts a shell server
82 specified after the name of the CGI program.
83 The URL takes the form:
85 http://host/cgi-bin/egwcgi/shell/argument
87 where <it/shell/ is the name of the shell server to invoke. The
88 <it/argument/ is transferred to the <it/shell/ program.
90 When the <tt/egwcgi/ program is started by a URL as above, it will
91 assign a unique session-ID. If the shell wishes to be stateful it
92 should return a page that includes references with the newly
94 In this case all subsequent URLs should contain this session-ID
95 with the following form:
97 http://host/cgi-bin/egwcgi/sessionID/argument
99 The only difference from the initial URL is that the shell part is
100 substituted with a numeric session-ID. If the <tt/egwcgi/ program
101 gets a reference to this kind of URL, it will try to contact a running
102 shell. If that fails, it will restart it. To communicate with the
103 shell the <tt/egwcgi/ program uses FIFOs (names pipes) whose names
104 include the session-ID.
106 The <tt/egwcgi/ program will initially change its current directory
107 to <tt/EGWDIR/ as specified in the <tt/Makefile/.
109 <sect1>The shell system.
112 The shell system is, basically, a shell program, a few maintenance
113 files, and a set of scripts. All files in the shell system are stored
114 in the <tt/EGWDIR/ directory.
116 The files are summarized below:
119 <tag/egwtcl/ A Tcl shell server - reads HTML with embedded Tcl and
120 commands to inspect CGI variables. Note: this shell is currently
121 unused because this shell doesn't support Z39.50.
123 <tag/egwirtcl/ The IrTcl shell server. The IrTcl shell reads HTML
124 files with embedded Tcl scripts as well as Z39.50 extensions added by the
127 <tag/*.tcl/ Tcl scripts - located in the <tt/EGWDIR/ directory.
128 The <tt/z39util.tcl/ file declares a lot of Tcl functions to
129 facilitate Z39.50 communication as well as other utilities.
131 <tag/*.egw/ Web scripts with embedded Tcl - located in the <tt/EGWDIR/
132 directory. Normally, each script correspond to one type of Web
133 page. For example, the <tt/query.egw/ script contacts a single
134 target and displays a search form; the <tt/search.egw/ script
135 makes a Z39.50 search/present and displays the result.
137 <tag/ztargets.conf/ Target configuration file. A sort of profile is
138 defined for each target: the name of the target, record syntax,
139 search fields and mapping to bib-1, etc.
141 <tag/egw.res/ Small configuration file; defines a shell's idle time,
142 the log-level, and the directory for FIFOs used by the gateway.
145 When the system is running a number of files are created:
147 <tag/www.db/ Database that maps from session-IDs to shells.
149 <tag/tcl.state.*/ User session states; these are stored as Tcl
152 <tag/egwcgi_log/ Log file for the <tt/egwcgi/ program.
154 <tag/egwsh_log/ Log file for the shells <tt/egwtcl/, <tt/egwirtcl/, etc.
156 <tag/irtcl_log/ YAZ log file created by the IrTcl library. The file
157 only includes information about Z39.50 communication.
163 Copyright © 1995-1996, the EUROPAGATE consortium (see below).
165 The EUROPAGATE consortium members are:
168 <item>University College Dublin
169 <item>Danmarks Teknologiske Videnscenter
170 <item>An Chomhairle Leabharlanna
171 <item>Consejo Superior de Investigaciones Cientificas
174 Permission to use, copy, modify, distribute, and sell this software and
175 its documentation, in whole or in part, for any purpose, is hereby granted,
178 1. This copyright and permission notice appear in all copies of the
179 software and its documentation. Notices of copyright or attribution
180 which appear at the beginning of any file must remain unchanged.
182 2. The names of EUROPAGATE or the project partners may not be used to
183 endorse or promote products derived from this software without specific
184 prior written permission.
186 3. Users of this software (implementors and gateway operators) agree to
187 inform the EUROPAGATE consortium of their use of the software. This
188 information will be used to evaluate the EUROPAGATE project and the
189 software, and to plan further developments. The consortium may use
190 the information in later publications.
192 4. Users of this software agree to make their best efforts, when
193 documenting their use of the software, to acknowledge the EUROPAGATE
194 consortium, and the role played by the software in their work.
196 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
197 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
198 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
199 IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE
200 FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF
201 ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
202 OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND
203 ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
204 USE OR PERFORMANCE OF THIS SOFTWARE.