Web/Z39.50 gateway guide <author>Europagate, 1996 <date>$Revision: 1.2 $ <abstract> This document describes a Web server that provides access to the Z39.50 protocol. </abstract> <toc> <sect>Introduction The EUROPAGATE project developed two Z39.50 gatways that served as Z39.50 clients: an email gateway and a web gateway. This document describes how to compile and install the web gateway. For information about the email gateway see the document egate.txt. <sect>Installation An ANSI C compiler is required in order to compile the software. The gateway uses IrTcl and YAZ from Index Data to interface the Z39.50 protocol. YAZ and IrTcl can be found at the FTP host: <htmlurl url="ftp://ftp.indexdata.dk/index/yaz" name="ftp://ftp.indexdata.dk/index/yaz"> You also need the Tcl package which can be found at: <htmlurl url="ftp://ftp.sunlabs.com/pub/tcl" name="ftp://ftp.sunlabs.com/pub/tcl"> Unpack <tt>egate.tar.gz</tt> and edit the top level <tt/Makefile/. Specify where the YAZ package can be found by setting the the include path <tt/ZINC/, and the YAZ library <tt/ZLIB/. Some systems need extra socket libraries - in this case set the <tt/ELIB/ variable. You need also to define the location of Tcl: <tt/TCLLIB/ and <tt/TCLINC/ - and the location of IrTcl: <tt/IRTCLLIB/ and <tt/IRTCLINC/. The gateway scripts and the Z39.50 communication tools are located in the <tt/EGWDIR/ directory. This setting is hardcoded in the CGI program (<tt/egwcgi/) and therefore it must be defined before compiling. The CGI program, <tt/egwcgi/, will be installed in the <tt/CGIDIR/ directory. HTML - and images files are installed in the <tt/HTDOCS/ and the <tt/GIFDIR/ directories respectively. The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the <tt/Makefile/ so you may modify these in your shell before compiling. Now, type <tt/make web/ If the compilation succeeds, you should install the software in target directories, by issuing: <tt/make install.web/. A HTML file called <tt/egwindex.html/ should be installed in your <tt/HTDOCS/ directory. The page contains miscellaneous starting links to the Z39.50 gateway. Read it with your browser and click on the <it>single target</it> button to test it out. <sect>Overview of the system <sect1>The <tt/egwcgi/ program. The <tt/egwcgi/ program uses the CGI interface to communicate with your HTTP server. It is the only program that communicates with your server and it needs to be installed in your CGI binaries directory (<tt/CGIDIR/). The program inspects the URL and contacts a shell server specified after the name of the CGI program. The URL takes the form: http://host/cgi-bin/egwcgi/shell/argument where <it/shell/ is the name of the shell server to invoke. The <it/argument/ is transferred to the <it/shell/ program. When the <tt/egwcgi/ program is started by a URL as above, it will assign a unique session-ID. If the shell wishes to be stateful it should return a page that includes references with the newly assigned session-ID. In this case all subsequent URLs should contain this session-ID with the following form: http://host/cgi-bin/egwcgi/sessionID/argument The only difference from the initial URL is that the shell part is substituted with a numeric session-ID. If the <tt/egwcgi/ program gets a reference to this kind of URL, it will try to contact a running shell. If that fails, it will restart it. To communicate with the shell the <tt/egwcgi/ program uses FIFOs (names pipes) whose names include the session-ID. The <tt/egwcgi/ program will initially change its current directory to <tt/EGWDIR/ as specified in the <tt/Makefile/. <sect1>The shell system. The shell system is, basically, a shell program, a few maintenance files, and a set of scripts. All files in the shell system are stored in the <tt/EGWDIR/ directory. The files are summarized below: <descrip> <tag/egwtcl/ A Tcl shell server - reads HTML with embedded Tcl and commands to inspect CGI variables. Note: this shell is currently unused because this shell doesn't support Z39.50. <tag/egwirtcl/ The IrTcl shell server. The IrTcl shell reads HTML files with embedded Tcl scripts as well as Z39.50 extensions added by the IrTcl library. <tag/*.tcl/ Tcl scripts - located in the <tt/EGWDIR/ directory. The <tt/z39util.tcl/ file declares a lot of Tcl functions to facilitate Z39.50 communication as well as other utilities. <tag/*.egw/ Web scripts with embedded Tcl - located in the <tt/EGWDIR/ directory. Normally, each script correspond to one type of Web page. For example, the <tt/query.egw/ script contacts a single target and displays a search form; the <tt/search.egw/ script makes a Z39.50 search/present and displays the result. <tag/ztargets.conf/ Target configuration file. A sort of profile is defined for each target: the name of the target, record syntax, search fields and mapping to bib-1, etc. <tag/egw.res/ Small configuration file; defines a shell's idle time, the log-level, and the directory for FIFOs used by the gateway. </descrip> When the system is running a number of files are created: <descrip> <tag/www.db/ Database that maps from session-IDs to shells. <tag/tcl.state.*/ User session states; these are stored as Tcl variables. <tag/egwcgi_log/ Log file for the <tt/egwcgi/ program. <tag/egwsh_log/ Log file for the shells <tt/egwtcl/, <tt/egwirtcl/, etc. <tag/irtcl_log/ YAZ log file created by the IrTcl library. The file only includes information about Z39.50 communication. </descrip> <sect>LICENSE Copyright © 1995-1996, the EUROPAGATE consortium (see below). The EUROPAGATE consortium members are: <itemize> <item>University College Dublin <item>Danmarks Teknologiske Videnscenter <item>An Chomhairle Leabharlanna <item>Consejo Superior de Investigaciones Cientificas </itemize> Permission to use, copy, modify, distribute, and sell this software and its documentation, in whole or in part, for any purpose, is hereby granted, provided that: 1. This copyright and permission notice appear in all copies of the software and its documentation. Notices of copyright or attribution which appear at the beginning of any file must remain unchanged. 2. The names of EUROPAGATE or the project partners may not be used to endorse or promote products derived from this software without specific prior written permission. 3. Users of this software (implementors and gateway operators) agree to inform the EUROPAGATE consortium of their use of the software. This information will be used to evaluate the EUROPAGATE project and the software, and to plan further developments. The consortium may use the information in later publications. 4. Users of this software agree to make their best efforts, when documenting their use of the software, to acknowledge the EUROPAGATE consortium, and the role played by the software in their work. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. </article>