doc/web.sgml

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