1 <!doctype linuxdoc system>
4 $Id: web.sgml,v 1.6 2001/02/26 14:32:36 adam Exp $
8 <title>Web/Z39.50 gateway guide
9 <author>Europagate, 1996 <htmlurl url="http://europagate.dtv.dk"
10 name="http://europagate.dtv.dk">
11 <date>$Revision: 1.6 $
13 This document describes a Web server that provides access to the
22 The <htmlurl url="http://europagate.dtv.dk" name="EUROPAGATE">
23 project developed two Z39.50 gatways that served as
24 Z39.50 clients: an email gateway and a web gateway. This document
25 describes how to compile and install the web gateway.
30 An ANSI C compiler is required in order to compile the software.
32 The gateway uses IrTcl and YAZ from Index Data to interface the
35 YAZ and IrTcl can be found at the FTP host:
37 <htmlurl url="ftp://ftp.indexdata.dk/pub/yaz/"
38 name="ftp://ftp.indexdata.dk/pub/yaz/">
42 <htmlurl url="http://ftp.indexdata.dk/pub/yaz/"
43 name="http://ftp.indexdata.dk/pub/yaz/">
45 You also need the Tcl package which can be found at:
47 <htmlurl url="ftp://ftp.sunlabs.com/pub/tcl"
48 name="http://dev.scriptics.com/">
50 Unpack <tt>web-z39-...tar.gz</tt> and edit the top level
51 <tt/Makefile/. Specify where the YAZ package can be found by setting
52 the the include path <tt/ZINC/, and the YAZ library <tt/ZLIB/.
53 Some systems need extra socket libraries - in this case set the
54 <tt/ELIBS/ variable. You need also to define the location of Tcl:
55 <tt/TCLLIB/ and <tt/TCLINC/ - and the location of IrTcl:
56 <tt/IRTCLLIB/ and <tt/IRTCLINC/.
58 The gateway scripts and the Z39.50 communication tools are located
59 in the <tt/EGWDIR/ directory. This setting is hardcoded in the
60 CGI program (<tt/egwcgi/) and therefore it must be defined before
61 compiling. The CGI program, <tt/egwcgi/, will be installed in the
62 <tt/CGIDIR/ directory. HTML - and images files are installed in
63 the <tt/HTDOCS/ and the <tt/GIFDIR/ directories respectively.
65 You may wish to define the <tt/CC/ or <tt/CFLAGS/ variables in the
66 <tt/Makefile/ or set them in your shell.
70 If the compilation succeeds, you should install the software in target
71 directories, by issuing: <tt/make install/.
73 A HTML file called <tt/egwindex.html/ should be installed in your
74 <tt/HTDOCS/ directory. The page contains miscellaneous starting links
75 to the Z39.50 gateway. Read it with your browser and click on the
76 <it>single target</it> button to test it out.
78 <sect>Overview of the system
81 <sect1>The <tt/egwcgi/ program.
83 The <tt/egwcgi/ program uses the CGI interface to communicate with
84 your HTTP server. It is the only program that communicates with your
85 server and it needs to be installed in your CGI binaries directory
88 The program inspects the URL and contacts a shell server
89 specified after the name of the CGI program.
90 The URL takes the form:
92 http://host/cgi-bin/egwcgi/shell/argument
94 where <it/shell/ is the name of the shell server to invoke. The
95 <it/argument/ is transferred to the <it/shell/ program.
97 When the <tt/egwcgi/ program is started by a URL as above, it will
98 assign a unique session-ID. If the shell wishes to be stateful it
99 should return a page that includes references with the newly
101 In this case all subsequent URLs should contain this session-ID
102 with the following form:
104 http://host/cgi-bin/egwcgi/sessionID/argument
106 The only difference from the initial URL is that the shell part is
107 substituted with a numeric session-ID. If the <tt/egwcgi/ program
108 gets a reference to this kind of URL, it will try to contact a running
109 shell. If that fails, it will restart it. To communicate with the
110 shell the <tt/egwcgi/ program uses FIFOs (names pipes) whose names
111 include the session-ID.
113 The <tt/egwcgi/ program will initially change its current directory
114 to <tt/EGWDIR/ as specified in the <tt/Makefile/.
116 <sect1>The shell system.
119 The shell system is, basically, a shell program, a few maintenance
120 files, and a set of scripts. All files in the shell system are stored
121 in the <tt/EGWDIR/ directory.
123 The files are summarized below:
126 <tag/egwtcl/ A Tcl shell server - reads HTML with embedded Tcl and
127 commands to inspect CGI variables. Note: this shell is currently
128 unused because this shell doesn't support Z39.50.
130 <tag/egwirtcl/ The IrTcl shell server. The IrTcl shell reads HTML
131 files with embedded Tcl scripts as well as Z39.50 extensions added by the
134 <tag/*.tcl/ Tcl scripts - located in the <tt/EGWDIR/ directory.
135 The <tt/z39util.tcl/ file declares a lot of Tcl functions to
136 facilitate Z39.50 communication as well as other utilities.
138 <tag/*.egw/ HTML files with embedded Tcl - located in the <tt/EGWDIR/
139 directory. Normally, each file corresponds to one type of Web
140 page. For example, the <tt/query.egw/ file contacts a single
141 target and displays a search form; the <tt/search.egw/ file
142 makes a Z39.50 search/present and displays the result.
144 <tag/ztargets.conf/ Target configuration file. A sort of profile is
145 defined for each target: the name of the target, record syntax,
146 search fields and mapping to bib-1, etc.
148 <tag/egw.res/ Small configuration file; defines a shell's idle time,
149 the log-level, and the directory for FIFOs used by the gateway.
152 When the system is running a number of files are created:
154 <tag/www.db/ Database that maps from session-IDs to shells.
156 <tag/tcl.state.*/ User session states; these are stored as Tcl
159 <tag/egwcgi_log/ Log file for the <tt/egwcgi/ program.
161 <tag/egwsh_log/ Log file for the shells <tt/egwtcl/, <tt/egwirtcl/, etc.
163 <tag/irtcl_log/ YAZ log file created by the IrTcl library. The file
164 only includes information about Z39.50 communication.
171 The scripts with the extension <tt/egw/ are HTML files with embedded Tcl.
172 Tcl code is initiated with a left curly brace <tt/{/ and is terminated
173 with a right curly brace <tt/}/. The Tcl code is executed on the
174 top level, i.e. variables are accessed in the global scope.
175 Standard Tcl commands, IrTcl commands to access the Z39.50
176 communication layer, and
177 an extra set of "gateway" commands are available in the embedded Tcl code.
178 The extra set of commands are used to communicate with the Europagate
182 <tag/html/ Concatenates the arguments and transfers them to the HTTP server.
183 The data may be cached. They are not written until the <tt/egw_flush/ is
185 <tag/egw_form/ Inspects CGI form variables.
186 <tag/egw_parms/ Inspects URL variables.
187 <tag/egw_flush/ Flushes all HTML output.
188 <tag/egw_log/ Logs messages.
189 <tag/egw_enc/ Encodes URL data.
190 <tag/egw_wait/ Waits for events. One of the following events
191 will terminate this command: data from a Z39.50 server,
192 data from the CGI module, or timeout.
195 Note, that except from the <tt/html/ command all commands have a
197 Apart from the new commands, the following global variables are set:
199 <tag/sessionId/ ID of the current user session (integer).
200 <tag/env/ Array of environment variables - this is standard Tcl, really.
206 Copyright © 1995-1996, the EUROPAGATE consortium (see below).
208 The EUROPAGATE consortium members are:
211 <item>University College Dublin
212 <item>Danmarks Teknologiske Videnscenter
213 <item>An Chomhairle Leabharlanna
214 <item>Consejo Superior de Investigaciones Cientificas
217 Permission to use, copy, modify, distribute, and sell this software and
218 its documentation, in whole or in part, for any purpose, is hereby granted,
221 1. This copyright and permission notice appear in all copies of the
222 software and its documentation. Notices of copyright or attribution
223 which appear at the beginning of any file must remain unchanged.
225 2. The names of EUROPAGATE or the project partners may not be used to
226 endorse or promote products derived from this software without specific
227 prior written permission.
229 3. Users of this software (implementors and gateway operators) agree to
230 inform the EUROPAGATE consortium of their use of the software. This
231 information will be used to evaluate the EUROPAGATE project and the
232 software, and to plan further developments. The consortium may use
233 the information in later publications.
235 4. Users of this software agree to make their best efforts, when
236 documenting their use of the software, to acknowledge the EUROPAGATE
237 consortium, and the role played by the software in their work.
239 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
240 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
241 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
242 IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE
243 FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF
244 ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
245 OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND
246 ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
247 USE OR PERFORMANCE OF THIS SOFTWARE.