doc/zebra.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!--
   4   $Id: zebra.sgml,v 1.1 1995-11-27 14:23:53 adam Exp $
   5 -->
   6
   7 <article>
   8 <title>Zebra server Administrators's Guide and Reference
   9 <author>Index Data, <tt/info@index.ping.dk/
  10 <date>$Revision: 1.1 $
  11 <abstract>
  12 This document describes Zebra &mdash; an information retrieval server
  13 that uses the Z39.50 protocol.
  14 </abstract>
  15
  16 <toc>
  17
  18 <sect>Introduction
  19
  20 <p>
  21 - gils
  22 - UNI*X (not NT yet)
  23 - goals
  24
  25 <sect>Compiling the software
  26
  27 <p>
  28
  29 Zebra uses the YAZ package in order to provide Z39.50 access. So you
  30 must compile YAZ before going further. Specifically, Zebra uses
  31 the YAZ header files in <tt>yaz/include/..</tt> and its public library
  32 <tt>yaz/lib/libyaz.a</tt>.
  33
  34 As with YAZ, an ANSI C compiler is required in order to compile the Zebra
  35 server system &mdash; GNU C works fine.
  36
  37 Unpack the Zebra software. You might put Zebra in the same directory level
  38 as YAZ, for example if YAZ is placed in ..<tt>/src/yaz-</tt>.. Zebra
  39 is placed in ..<tt>/src/zebra-</tt>.
  40
  41 Edit the top-level <tt>Makefile</tt> in the Zebra directory in which
  42 you specify the location of YAZ by setting make variables.
  43 The <tt>OSILIB</tt> should be empty if YAZ wasn't compiled with
  44 MOSI support. Some systems, such as Solaris, have separate socket
  45 libraries and for such systems you need to specify the
  46 <tt>NETLIB</tt> variable.
  47
  48 When finished with the editing of the <tt>Makefile</tt> type:
  49 <tscreen><verb>
  50 $ make
  51 </verb></tscreen>
  52
  53 If successful, two executables have been created in the sub-directory
  54 index.
  55 <descrip>
  56 <tag><tt>zebrasrv</tt></tag> The Z39.50 server and search engine.
  57 <tag><tt>zebraidx</tt></tag> The administrative tool for the search index.
  58 </descrip>
  59
  60 <sect>Administrating Zebra
  61
  62 <p>
  63
  64 Unlike many other retrieval systems, the Zebra offers incremental
  65 modifications of an existing index. Needless to say, these facilities
  66 makes the administration of Zebra somewhat more complicated.
  67
  68 Normally, when Zebra modifies the index it reads a number of records.
  69 Depending on your specifications and on the contents of each record
  70 one the following situations occur:
  71 <descrip>
  72 <tag>Insert</tag> The record is indexed as if it never occurred
  73 before. Either the Zebra system doesn't know how to identify the record or
  74 Zebra can identify the record but didn't find it to be already indexed.
  75 <tag>Update</tag> The record has already been indexed. In this case
  76 either the contents of the record or the location (file) of the record
  77 indicates that it has been indexed before.
  78 <tag>Delete</tag> The record is deleted from the index. As in the
  79 update-case it must be able to identify the record.
  80 </descrip>
  81
  82 Please note, that in both the update- and delete- case the Zebra
  83 system must be able to make a key that identifies the record in
  84 question.
  85
  86 To administrate the Zebra retrieval system, you run the
  87 <tt>zebraidx</tt> program. This program supports a number of options
  88 which are preceded by a minus, and a set of commands (not preceded by
  89 minus).
  90
  91 Both the Zebra administrative tool and the Z39.50 server share a
  92 set of indexing files and a global configuration file. The
  93 name of the configuration file defaults to <tt>zebra.cfg</tt>.
  94 The configuration file includes specifications on how to index
  95 various kinds of records and where the other configuration files
  96 are located. <tt>zebrasrv</tt> and <tt>zebraidx</tt> <em>must</em>
  97 be run in the same directory where the configuration file if you do
  98 not indicate the location of the configuration file by option <tt>-c</tt>.
  99
 100 <sect1>Indexing
 101
 102 <p>
 103 As said before, indexing is a record-per-record process, in which
 104 either insert/update/delete will occur. Before a record is indexed
 105 search keys are extracted from whatever might be the layout the
 106 original record (sgml,html,text, etc..). To specify a particular
 107 extraction process, specify either the command line option <tt>-t</tt>
 108 or specify a <tt>fileExtension</tt> line in the configuration file.
 109
 110 <sect2>Simple indexing
 111
 112 <p>
 113 In the simple case, in which you wish to index a set of files and you
 114 run the <tt>zebraidx</tt> program with the <tt>add</tt> command.
 115
 116 For example to index the files below the directory <tt>/home/grs</tt>
 117 as GRS records you would type:
 118 <tscreen><verb>
 119 $ zebraidx -t grs add /home/grs
 120 </verb></tscreen>
 121
 122 The <tt>-t</tt> options indicates that the files should be treated
 123 as GRS records. The <tt>zebra.cfg</tt> must be located in the current
 124 directory and the configuation must specify where the profile tables
 125 and attribute specification files that comes with YAZ are located.
 126 For example, if your version of YAZ is located <tt>/home/yaz</tt>
 127 the configation file should include the following:
 128 <tscreen><verb>
 129 profilePath: /home/yaz/tab
 130 attset: bib1.att
 131 attset: gils.att
 132 </verb></tscreen>
 133
 134 The <tt>attset</tt>-lines specify the locations of attribute set
 135 specification files.
 136
 137 At a later time, you can add another set of records with the
 138 <tt>add</tt> command. However, records will always be inserted
 139 and not updated because, we didn't specify a match criteria for
 140 the record(s).
 141
 142 One other property of the system just created, is that records are stored
 143 externally, i.e. the system reads the records when they are
 144 retrieved from their original location by the Z39.50 server.
 145 Therefore, you shouldn't delete files that you indexed this way.
 146
 147 <sect2>Indexing with file keys
 148
 149 <p>
 150 If you have a set of external records that you wish to index you may
 151 use the file key feature of the Zebra system. In short, the file key
 152 feature, mirrors a directory and the files below efficiently. To
 153 perform indexing of a directory with file keys you specify the top-level
 154 directory after the <tt>dir</tt> command. The command will recursively
 155 traverse the directories and compare each with whatever have been
 156 indexed before in the same directory. If a file is new (not in
 157 the previous version of the directory) it is inserted;
 158 if a file was already indexed and it has been modified
 159 since last insertion it is updated; if a file is missing since last
 160 visit it is deleted.
 161
 162 For example, to index the GRS files below <tt>/home/grs</tt> you
 163 would type:
 164 <tscreen><verb>
 165 $ zebraidx -t grs dir /home/grs
 166 </verb></tscreen>
 167
 168 <sect2>Indexing with general keys
 169
 170 <p>
 171 About the fileMatch thing.
 172
 173 <sect1>File areas
 174
 175 <p>
 176 About the register thing.
 177
 178 <sect1>The Zebra configuration file
 179
 180 <p>
 181 The Zebra configuration file, read by <tt>zebraidx</tt> and
 182 <tt>zebrasrv</tt> defaults to <tt>zebra.cfg</tt> unless specified
 183 by <tt>-c</tt> option.
 184
 185 <descrip>
 186 <tag><it>group</it>fileExtension<it>name</it></tag>
 187  Specifies how records with the file extension <it>name</it> should
 188  be handled by the indexer.
 189 <tag><it>group</it>fileMatch</tag>
 190  Specifies the key information that identifies the record.
 191 <tag><it>group</it>database</tag>
 192  Specifies the Z39.50 database of a group of records.
 193 <tag><it>group</it>storeKeys</tag>
 194  Specifies whether key information should be saved for a given
 195  group of records. If you plan to update/delete this type of
 196  record a later this should be specified as 1; otherwise it
 197  should be 0 (default).
 198 <tag><it>group</it>storeData</tag>
 199  Specifies whether original copy of record should be stored internally
 200  in the Zebra system indexes. If your externally indexed files
 201  are temporary this option should certainly be true (1); otherwise
 202  false (0).
 203 <tag>register</tag>
 204  Specifies the location of the indexes.
 205 <tag>profilePath</tag>
 206  Specifies the location of profile specification paths.
 207 <tag>attset</tag>
 208  Specifies the filename(s) of attribute specification files.
 209 </descrip>
 210
 211 <sect>The Z39.50 Server
 212
 213 <p>
 214
 215 <sect1>Running the server
 216 <p>
 217 Starting the server and how to configure the server.
 218
 219 <sect1>How the server handles queries
 220 <p>
 221 What elements of Bib-1 are supported and where are result sets
 222 stored.
 223
 224 <sect>About Index Data
 225 <p>
 226 Copyright &copy; 1995, Index Data.
 227
 228 Permission to use, copy, modify, distribute, and sell this software and
 229 its documentation, in whole or in part, for any purpose, is hereby granted,
 230 provided that:
 231
 232 1. This copyright and permission notice appear in all copies of the
 233 software and its documentation. Notices of copyright or attribution
 234 which appear at the beginning of any file must remain unchanged.
 235
 236 2. The names of Index Data or the individual authors may not be used to
 237 endorse or promote products derived from this software without specific
 238 prior written permission.
 239
 240 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
 241 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
 242 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 243 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
 244 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
 245 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
 246 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
 247 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
 248 OF THIS SOFTWARE.
 249
 250 <sect>About Index Data
 251
 252 <p>
 253 Index Data is a consulting and software-development enterprise that
 254 specialises in library and information management systems. Our
 255 interests and expertise span a broad range of related fields, and one
 256 of our primary, long-term objectives is the development of a powerful
 257 information management
 258 system with open network interfaces and hypermedia capabilities.
 259
 260 We make this software available free of charge, on a fairly unrestrictive
 261 license; as a service to the networking community, and to further the
 262 development of quality software for open network communication.
 263
 264 We'll be happy to answer questions about the software, and about ourselves
 265 in general.
 266
 267 <tscreen>
 268 Index Data&nl
 269 Ryesgade 3&nl
 270 2200 K&oslash;benhavn N&nl
 271 DENMARK
 272 </tscreen>
 273
 274 <p>
 275 <tscreen><verb>
 276 Phone: +45 3536 3672
 277 Fax  : +45 3536 0449
 278 Email: info@index.ping.dk
 279 </verb></tscreen>
 280
 281 <sect>References
 282
 283 <p>
 284
 285 <descrip>
 286 <tag>1 Ousterhout, John K.:</tag>
 287 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
 288 0-201-63337-X). Source and documentation
 289 can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
 290 and mirrors.
 291 <tag>2 Furniss, Peter:</tag>
 292 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
 293 Basic Communications Applications.
 294 </descrip>
 295
 296 </article>