NAME

zSQLgate - Generic Z39.50-to-Relational Database gateway server

SYNOPSIS

zSQLgate [ -n ] configFile [ YAZ-options ... ]

DESCRIPTION

zSQLgate provides an Z39.50 interface to your relational databases. That is, it provides a generic gateway between the Z39.50 Information Retrieval protocol and pretty much any relational database you care to mention.

Please be aware the zSQLgate is not Free Software (although the licence is fairly permissive). See Net::Z3950::DBIServer::LICENCE for details.

OPTIONS

-n

No-op mode: zSQLgate parses its configuration, accepts queries and generates logs, but does not attempt to connect to the back-end database or do any searching or retrieval. This can be useful for debugging a configuration that you don't locally have access to the back-end database for. If that sounds to you like a dumb situation to be in then I could tell you some scary stories.

DOCUMENTATION ROADMAP

Configuring and Using zSQLgate

The documents in this section are of general interest to anyone using zSQLgate. Everyone should read the licence; also the introduction, to understand what zSQLgate is, and what it can and can't do. The next steps would normally be the installation guide and then the tutorial.

• Net::Z3950::DBIServer::LICENCE - READ THIS FIRST

• Net::Z3950::DBIServer::Intro

  An Introduction to zSQLgate is a gentle walk through what zSQLgate is, why it's useful, who might need it, where it's headed and the terms under which it is available.

• Net::Z3950::DBIServer::Install

  The zSQLgate Installation Guide provides a certain amount of hand-holding for people trying to install zSQLgate and its prerequisites. It attempts to address some of the more common problems that may be encountered.

• Net::Z3950::DBIServer::Tutorial [not finished]

  The zSQLgate Tutorial explains, with extensive examples, how to build zSQLgate configurations for both simple and complex relational databases, conforming to a variety of Z39.50 profiles and using a selection of RDBMSs.

Those wishing for more technical detail than those documents provide should proceed to the invocation manual and the configuration-file specification; although for most purposes, the tutorial should provide enough information on these subjects.

• Net::Z3950::DBIServer::Run

  Invoking the zSQLgate Server describes in detail the command-line options available for controlling the behaviour of the zSQLgate server.

• Net::Z3950::DBIServer::Spec [not finished]

  The zSQLgate Configuration File Format is a rigorous and definitive description of the format of the configuration files which drive zSQLgate, and the semantics implied by the various configuration elements.

API Documentation

These documents describe the internal programming interfaces to the various modules that make up the guts of zSQLgate. They are probably of interest only to developers wishing to work on zSQLgate internals. (I wrote them primarily for my own benefit.)

• Net::Z3950::DBIServer is the Perl module which forms the guts of the gateway.

  This is the top-level module of zSQLgate: it calls freely into those described hereafter. With the possible exception of the Exception module, its unlikely that any of them will have any life of their own away from from Net::Z3950::DBIServer.

• Net::Z3950::DBIServer::Config provides the routine that parses the configuration files which drive the zSQLgate server. It also provides a few trivial access functions for elements of the Config structure and its sub-structures. These are not individually documented, as the code is utterly trivial. Really. Read it, you'll agree.

• Net::Z3950::DBIServer::ResultSet represents a result set in the process of being evaluated, caching some of the records returned from the RDBMS back-end, and discarding them when it thinks they've outlived their usefulness.

• Net::Z3950::DBIServer::GRS1 provides a single routine, format(), to build a set of fieldname=value pairs into a string containing an GRS1 record.

• Net::Z3950::DBIServer::XML provides a single routine, format(), to build a set of fieldname=value pairs into a string containing an XML record.

• Net::Z3950::DBIServer::MARC provides a single routine, format(), to build a set of fieldname=value pairs into a string containing a MARC record.

• Net::Z3950::DBIServer::Exception represents a Bib-1 diagnostic to be returned to the client. They are designed to be thrown as exceptions by the low-level code, then picked up and transformed into diagnostic structures higher up.

AUTHOR

Mike Taylor <mike@miketaylor.org.uk>

First version Saturday 2nd February 2002.

SEE ALSO

Apart from the documents included in this distribution, which are all described above, you may find useful information from the following sources:

• The zSQLgate web site is at http://sql.z3950.org/ The documents referenced from here are all on that site, so you can find them there if for some reason they were not included in your zSQLgate distribution. You can also download newer versions, find out about support contracts and the mailing list, etc.

• Net::Z3950 is another Perl module by the same author as this one; but whereas DBIServer is for building servers, Net::Z3950 is for building Z39.50 clients. It does not share any code with this module, but addresses similar issues. You can download it from CPAN or from its own site, http://perl.z3950.org/

• Net::Z3950::SimpleServer is Index Data's fine generic Z39.50 server module. The DBIServer module is built on top of this: it provides code which talks to a relational database, and waits for SimpleServer to call it. If you're successfully running zSQLgate then you must already have SimpleServer installed, but if not you can find it on CPAN or at http://www.indexdata.com/simpleserver/

• Index Data's YAZ (Yet Another Z39.50) toolkit forms the basis of the SimpleServer module, which is essentially a re-casting of YAZ's backend server interface from C into Perl. YAZ is an excellent piece of software, freely available at http://www.indexdata.com/yaz/

• DBI is the DataBase Independent layer for Perl - the standard way of accessing pretty much any relational database system you care to mention, in a uniform way. That's what zSQLgate's callbacks are using. You can find it on CPAN at http://www.cpan.org/