X-Git-Url: http://git.indexdata.com/?p=idzebra-moved-to-github.git;a=blobdiff_plain;f=doc%2Fgils.sgml;h=265233c18f329d387e929dc082a0e2c144883668;hp=7e33351e3354ccadc300ab6900f0f23ecae29439;hb=6c5467571389a21c91196ce1608945633c1cf92a;hpb=09638ed93bcc8c8b385d899232bec0b007158dd7 diff --git a/doc/gils.sgml b/doc/gils.sgml index 7e33351..265233c 100644 --- a/doc/gils.sgml +++ b/doc/gils.sgml @@ -1,24 +1,21 @@ - -
Serving GILS Records with Zebra <author><htmlurl url="http://www.indexdata.dk/" name="Index Data">, <tt><htmlurl url="mailto:info@index.ping.dk" name="info@index.ping.dk"></> -<date>$Revision: 1.1 $ +<date>$Revision: 1.5 $ <abstract> This document explains how to set up a simple database of Government Information Locator Records using the Zebra retrieval engine and -Z39.50 server (version 1.0b1 or later). +Z39.50 server (version 1.0a6 or later). </abstract> <sect>Introduction <p> -Zebra is a powerful and versatile information management system, -allowing you to construct arbitrarily record structures and managing +Zebra is a powerful and versatile information management system +which allows you to construct arbitrarily complex record structures +and manage efficient, robust databases. Since the internal data modeling tools of Zebra are based on the @@ -40,8 +37,8 @@ GILS-compliant database service. <p> The first step is to download the software. If you are using a WWW browser, you can point it at the Zebra distribution archive at -<htmlurl url="http://www.indexdata.dk/zebra.html" -name="http://www.indexdata.dk/zebra.html">, and follow the link named +<tt><<htmlurl url="http://www.indexdata.dk/zebra.html" +name="http://www.indexdata.dk/zebra.html">></tt>, and follow the link named <it/Download the latest version of the software (xxx)/, where <it/xxx/ is the current version of Zebra. @@ -50,18 +47,19 @@ to the host <tt/ftp.indexdata.dk/, log in as <tt/ftp/, and give your Email-address as the password. Then type <tt>cd index/yaz</tt>, and use the <tt/dir/ command to locate the current version of Zebra. The file will be named <tt/zebra-xxx/, where <tt/xxx/ is the current -version of the software. Remember to use the <it/bin/ command, before +version of the software. Remember to use the <tt/bin/ command before using <tt/get/ to download the software. Once the distribution archive has been dowloaded, it must be -decompressed. For this, use the command <tt/gunzip/ command (if your +decompressed. To do this, use the command <tt/gunzip/ command (if your system doesn't have the <tt/gunzip/ program, you will need to acquire this separately). Finally, use the command <tt>tar xvf ->file<</tt> to unpack the archive. +<file></tt> to unpack the archive. -If you dosnloaded the source version of the software (this is the only +If you downloaded the source version of the software (this is the only option today, although we expect to release binary versions for Linux, -SunOS, and Digital Unix shortly). +SunOS, and Digital Unix shortly), you will have to compile Zebra +before you can use it. On many of the major version of the Unix operating system, compiling Zebra is a simple matter of typing <tt/make/ in the top-level @@ -69,8 +67,8 @@ distribution directory (this is the directory that was created when you executed <tt/tar/). Normally, Zebra compiles cleanly at least on Linux, Digital Unix (DEC OSF/1), and IBM AIX. On certain platforms (such as SunOS), you will need to edit the top-level <tt/Makefile/ to -set the <tt/NETLIB/ variable to include the &dquot;Berkeley Socket -Libraries&dquot;. On other Unix platforms, you <it/may/ need to modify +set the <tt/ELIBS/ variable to include the Berkeley Socket +Libraries. On other Unix platforms, you <it/may/ need to modify Makefiles or header files, but in general, we have found Zebra to be easily portable across modern Unix-versions. You do need an ANSI-C compliant compiler (you'll see a long list of Syntax-errors during the @@ -93,17 +91,20 @@ held responsible for their contents.</it> If you <tt/cd/ to the <tt/test/ directory, the first thing to notice is the file <tt/zebra.cfg/. There has to be a file like this present -whenever you use Zebra - it establishes various settings and default, +whenever you run Zebra - it establishes various settings and defaults, and we'll return to its contents below (a detailed description is found in the general Zebra documentation file). -The subdirectory <tt/records/ contain the sample records. We'll get +The subdirectory <tt/records/ contains the sample records. We'll get back to them, too. The first order of business is to index the sample records, and create the access files required by the Z39.50 server. To do this, position yourself in the <tt/test/ directory, and type the command -<tt>../index/zebraidx update records</tt>. + +<tscreen><verb> +$ ../index/zebraidx update records +</verb></tscreen> The indexing program will respond with a stream of control information, and when it completes, the database is ready. To start @@ -121,7 +122,10 @@ also use the simple demonstration client which is included with Zebra itself. To do this, start a new session on your machine (or put the server in the background). Change to the directory <tt>yaz/client</tt> under the main Zebra distribution directory. Now execute the command -<tt>./client tcp:localhost:9999</tt>. + +<tscreen><verb> +$ ./client tcp:localhost:9999 +</verb></tscreen> If all went well, the client will tell you that it has established an association with your test server. To test it, try out these commands: @@ -182,8 +186,7 @@ dashes (-). Hence, <tt/local-subject-index/ is equivalent to It is useful to look at the records in the <tt>test/records</tt> as examples of how SGML-formatted GILS record can look. Note that whitespace is generally ignored, so you can choose whatever layout of -your records suits you best. Note also that in some cases, the records -are generated automatically rather than typed in by a human. +your records that suits you best. <sect>The Zebra Configuration File @@ -192,16 +195,16 @@ As mentioned, the Zebra indexer and server always look for the file <tt/zebra.cfg/ in their current working directory (unless they are told to look for it elsewhere with the <tt/-c/ option). The example file in the <tt/test/ directory represents all but the bare minimum -for such a file. While it may seem daunting at first, we find the +for such a file. We find the following to be a powerful setup for a GILS-like database (everything -preceded by (#) is ignored by the software): +preceded by (#) is ignored by the software): <tscreen><verb> # # Sample configuration file for GILS database # -# Where are the configuration tables located? +# Where are the configuration files located? profilePath: /usr/local/lib/zebra # Load attribute sets for searching @@ -274,7 +277,7 @@ path of the directory followed by a colon (:), followed by the maximum amounts of megabytes (M) or kilobytes (K) of disk space that Zebra is allowed to use in the given directory. If you specify more than one directory:size combination <it/on the same line/, Zebra will fill up -each directory, one at a time. This feature is essential if your +each directory from left to right. This feature is essential if your database is so large that the registers cannot fit into a single partition of your disk. @@ -302,8 +305,46 @@ throughout the update and commit procedures - Zebra will ensure that the parts of the register accessed by the server are always consistent. +</descrip> + <sect>Creating Your Own Database <p> +Whenever we create a new database with Zebra, we find it useful to +first set up a new, empty directory. This directory will contain the +configuration file, the lock files maintained by Zebra (unless you +specify a different location for these), and any logs of updates and +server runs that you may wish to keep around. The first thing to do is +set up the <tt/zebra.cfg/ file for your database. You can copy the one +from the <tt/test/ directory, or you can create a new one using the +example settings described in the previous section. Once you get your +server up and running, you may want to read the description of the +<tt/zebra.cfg/ file in the general documentation, to set up additional +defaults for database names, etc. + +If you copy one of these files, you should be careful to update the +pathnames to reflect the setup of your own database. In particular, if +you want to specify one or more directories for the register files +and/or the shadow files, you should make sure that these directories +exist and are accessible to the user ID which will run the Zebra +processes. + +You need to make sure that your GILS records are available, too. For +small to medium-sized (say, less than 100,000 records) databases, it +is sometimes preferable to maintain the records as individual files +somewhere in the file system. Zebra will, by default, access these +files directly whenever the user requests to see a specific record. +However, you can set up Zebra to maintain the database records in +other ways, too. Consult the general documentation for details. + +Finally, you need to run <tt/zebraidx/ to create the index files, and +start up the server, <tt/zebrasrv/ (the server can be run from the +<tt/inetd/ if required), and you are in business. + +To access the data, you can use a dedicated Z39.50 client, or you can +set up a WWW/Z39.50 gateway to allow common WWW browsers to search +your data. CNIDR's +Isite +package includes a good, free gateway that you can experiment with. </article>