Hci Work
[idzebra-moved-to-github.git] / doc / zebra.sgml
1 <!doctype linuxdoc system>
2
3 <!--
4   $Id: zebra.sgml,v 1.22 1996-03-20 09:20:39 adam Exp $
5 -->
6
7 <article>
8 <title>Zebra Server - Administrators's Guide and Reference
9 <author><htmlurl url="http://www.indexdata.dk/" name="Index Data">, <tt><htmlurl url="mailto:info@index.ping.dk" name="info@index.ping.dk"></>
10 <date>$Revision: 1.22 $
11 <abstract>
12 The Zebra information server combines a versatile fielded/free-text
13 search engine with a Z39.50-1995 frontend to provide a powerful and flexible
14 information management system. This document explains the procedure for
15 installing and configuring the system, and outlines the possibilities
16 for managing data and providing Z39.50
17 services with the software.
18 </abstract>
19
20 <toc>
21
22 <sect>Introduction
23
24 <sect1>Overview
25
26 <p>
27 The Zebra system is a fielded free-text indexing and retrieval engine with a
28 Z39.50 frontend. You can use any commercial or freeware Z39.50 client
29 to access data stored in Zebra.
30
31 The Zebra server is our first step towards the development of a fully
32 configurable, open information system. Eventually, it will be paired
33 off with a powerful Z39.50 client to support complex information
34 management tasks within almost any application domain. We're making
35 the server available now because it's no fun to be in the open
36 information retrieval business all by yourself. We want to allow
37 people with interesting data to make their things
38 available in interesting ways, without having to start out
39 by implementing yet another protocol stack from scratch.
40
41 This document is an introduction to the Zebra system. It will tell you
42 how to compile the software, and how to prepare your first database.
43 It also explains how the server can be configured to give you the
44 functionality that you need.
45
46 If you find the software interesting, you should join the support
47 mailing-list by sending Email to <tt/zebra-request@index.ping.dk/.
48
49 <sect1>Features
50
51 <p>
52 This is a listof some of the most important features of the
53 system.
54
55 <itemize>
56
57 <item>
58 Supports updating - records can be added and deleted without
59 rebuilding the index from scratch.
60 The update procedure is tolerant to crashes or hard interrupts
61 during register updating - registers can be reconstructed following a crash.
62 Registers can be safely updated even while users are accessing the server.
63
64 <item>
65 Supports large databases - files for indices, etc. can be
66 automatically partitioned over multiple disks.
67
68 <item>
69 Supports arbitrarily complex records - base input format is an
70 SGML-like syntax which allows nested (structured) data elements, as
71 well as variant forms of data.
72
73 <item>
74 Supports boolean queries as well as relevance-ranking (free-text)
75 searching. Right truncation and masking in terms are supported, as
76 well as full regular expressions.
77
78 <item>
79 Supports multiple concrete syntaxes
80 for record exchange (depending on the configuration): GRS-1, SUTRS,
81 ISO2709 (*MARC). Records can be mapped between record syntaxes and
82 schema on the fly.
83
84 <item>
85 Protocol support:
86
87 <itemize>
88
89 <item>
90 Protocol facilities: Init, Search, Retrieve, Browse.
91
92 <item>
93 Piggy-backed presents are honored in the search-request.
94
95 <item>
96 Named result sets are supported.
97
98 <item>
99 Easily configured to support different application profiles, with
100 tables for attribute sets, tag sets, and abstract syntaxes.
101 Additional tables control facilities such as element mappings to
102 different schema (eg., GILS-to-USMARC).
103
104 <item>
105 Complex composition specifications using Espec-1 are partially
106 supported (simple element requests only).
107
108 <item>
109 Element Set Names are defined using the Espec-1 capability of the
110 system, and are given in configuration files as simple element
111 requests (and possibly variant requests).
112
113 <item>
114 Some variant support (not fully implemented yet).
115
116 <item>
117 Using the YAZ toolkit for the protocol implementation, the
118 server can utilise a plug-in XTI/mOSI implementation (not included) to
119 provide SR services over an OSI stack, as well as Z39.50 over TCP/IP.
120
121 </itemize>
122
123 </itemize>
124
125 <sect1>Future Work
126
127 <p>
128 This is an alfa-release of the software, to allow you to look at
129 it - try it out, and assess whether it can be of use to you. We expect
130 this version to be followed by a succession of beta-releases until we
131 arrive at a stable first version.
132
133 These are some of the plans that we have for the software in the near
134 and far future, approximately ordered after their relative importance.
135 Items marked with an
136 asterisk will be implemented before the
137 last beta release.
138
139 <itemize>
140
141 <item>
142 *Allow the system to handle other input formats. Specifically
143 MARC records and general, structured ASCII records (such as mail/news
144 files) parameterized by regular expressions.
145
146 <item>
147 *Complete the support for variants. Finalize support for the WAIS
148 retrieval methodology.
149
150 <item>
151 *Finalize the data element <it/include/ facility to support multimedia
152 data elements in records.
153
154 <item>
155 *Port the system to Windows NT.
156
157 <item>
158 Add index and data compression to save disk space.
159
160 <item>
161 Add more sophisticated relevance ranking mechanisms. Add support for soundex
162 and stemming. Add relevance feedback support.
163
164 <item>
165 Add Explain support.
166
167 <item>
168 Add support for very large records by implementing segmentation and/or
169 variant pieces.
170
171 <item>
172 Support the Item Update extended service of the protocol.
173
174 <item>
175 The Zebra search engine supports approximate string matching in the
176 index. We'd like to find a way to support and control this from RPN.
177
178 <item>
179 We want to add a management system that allows you to
180 control your databases and configuration tables from a graphical
181 interface. We'll probably use Tcl/Tk to stay platform-independent.
182
183 </itemize>
184
185 Programmers thrive on user feedback. If you are interested in a facility that
186 you don't see mentioned here, or if there's something you think we
187 could do better, please drop us a mail. If you think it's all really
188 neat, you're welcome to drop us a line saying that, too. You'll find
189 contact info at the end of this file.
190
191 <sect>Compiling the software
192
193 <p>
194 Zebra uses the YAZ package to implement Z39.50, so you
195 have to compile YAZ before going further. Specifically, Zebra uses
196 the YAZ header files in <tt>yaz/include/..</tt> and its public library
197 <tt>yaz/lib/libyaz.a</tt>.
198
199 As with YAZ, an ANSI C compiler is required in order to compile the Zebra
200 server system &mdash; <tt/gcc/ works fine if your own system doesn't
201 provide an adequate compiler.
202
203 Unpack the Zebra software. You might put Zebra in the same directory level
204 as YAZ, for example if YAZ is placed in ..<tt>/src/yaz-xxx</tt>, then
205 Zebra is placed in ..<tt>/src/zebra-yyy</tt>.
206
207 Edit the top-level <tt>Makefile</tt> in the Zebra directory in which
208 you specify the location of YAZ by setting make variables.
209 The <tt>OSILIB</tt> should be empty if YAZ wasn't compiled with
210 MOSI support. Some systems, such as Solaris, have separate socket
211 libraries and for those systems you need to specify the
212 <tt>NETLIB</tt> variable.
213
214 When you are done editing the <tt>Makefile</tt> type:
215 <tscreen><verb>
216 $ make
217 </verb></tscreen>
218
219 If successful, two executables have been created in the sub-directory
220 <tt/index/.
221 <descrip>
222 <tag><tt>zebrasrv</tt></tag> The Z39.50 server and search engine.
223 <tag><tt>zebraidx</tt></tag> The administrative tool for the search index.
224 </descrip>
225
226 <sect>Quick Start
227
228 <p>
229 In this section, we will test the system by indexing a small set of sample
230 GILS records that are included with the software distribution. Go to the
231 <tt>test</tt> subdirectory of the distribution archive. There you will
232 find a configuration
233 file named <tt>zebra.cfg</tt> with the following contents:
234 <tscreen><verb>
235 # Where are the YAZ tables located.
236 profilePath: ../../yaz/tab ../tab
237
238 # Files that describe the attribute sets supported.
239 attset: bib1.att
240 attset: gils.att
241 </verb></tscreen>
242
243 Now, edit the file and set <tt>profilePath</tt> to the path of the
244 YAZ profile tables (sub directory <tt>tab</tt> of the YAZ distribution
245 archive).
246
247 The 48 test records are located in the sub directory <tt>records</tt>.
248 To index these, type:
249 <tscreen><verb>
250 $ ../index/zebraidx -t grs update records
251 </verb></tscreen>
252
253 In the command above the option <tt>-t</tt> specified the record
254 type &mdash; in this case <tt>grs</tt>. The word <tt>update</tt> followed
255 by a directory root updates all files below that directory node.
256
257 If your indexing command was successful, you are now ready to
258 fire up a server. To start a server on port 2100, type:
259 <tscreen><verb>
260 $ ../index/zebrasrv tcp:@:2100
261 </verb></tscreen>
262
263 The Zebra index that you have just created has a single database
264 named <ztt/Default/. The database contains records structured according to
265 the GILS profile, and the server will
266 return records in either either USMARC, GRS-1, or SUTRS depending
267 on what your client asks
268 for.
269
270 To test the server, you can use any Z39.50 client (1992 or later). For
271 instance, you can use the demo client that comes with YAZ: Just cd to
272 the <tt/client/ subdirectory of the YAZ distribution and type:
273
274 <tscreen><verb>
275 $ client tcp:localhost:2100
276 </verb></tscreen>
277
278 When the client has connected, you can type:
279
280 <tscreen><verb>
281 Z> find surficial
282 Z> show 1
283 </verb></tscreen>
284
285 The default retrieval syntax for the client is USMARC. To try other
286 formats for the same record, try:
287
288 <tscreen><verb>
289 Z>format sutrs
290 Z>show 1
291 Z>format grs-1
292 Z>show 1
293 Z>elements B
294 Z>show 1
295 </verb></tscreen>
296
297 <it>NOTE: You may notice that more fields are returned when your
298 client requests SUTRS or GRS-1 records. When retrieving GILS records,
299 this is normal - not all of the GILS data elements have mappings in
300 the USMARC record format.</it>
301
302 If you've made it this far, there's a good chance that
303 you've got through the compilation OK.
304
305 <sect>Administrating Zebra<label id="administrating">
306
307 <p>
308 Unlike many simpler retrieval systems, Zebra supports safe, incremental
309 updates to an existing index.
310
311 Normally, when Zebra modifies the index it reads a number of records
312 that you specify.
313 Depending on your specifications and on the contents of each record
314 one the following events take place for each record:
315 <descrip>
316 <tag>Insert</tag> The record is indexed as if it never occurred
317 before. Either the Zebra system doesn't know how to identify the record or
318 Zebra can identify the record but didn't find it to be already indexed.
319 <tag>Modify</tag> The record has already been indexed. In this case
320 either the contents of the record or the location (file) of the record
321 indicates that it has been indexed before.
322 <tag>Delete</tag> The record is deleted from the index. As in the
323 update-case it must be able to identify the record.
324 </descrip>
325
326 Please note that in both the modify- and delete- case the Zebra
327 indexer must be able to generate a unique key that identifies the record in
328 question (more on this below).
329
330 To administrate the Zebra retrieval system, you run the
331 <tt>zebraidx</tt> program. This program supports a number of options
332 which are preceded by a minus, and a few commands (not preceded by
333 minus).
334
335 Both the Zebra administrative tool and the Z39.50 server share a
336 set of index files and a global configuration file. The
337 name of the configuration file defaults to <tt>zebra.cfg</tt>.
338 The configuration file includes specifications on how to index
339 various kinds of records and where the other configuration files
340 are located. <tt>zebrasrv</tt> and <tt>zebraidx</tt> <em>must</em>
341 be run in the directory where the configuration file lives unless you
342 indicate the location of the configuration file by option
343 <tt>-c</tt>.
344
345 <sect1>Record Types<label id="record-types">
346 <p>
347 Indexing is a per-record process, in which
348 either insert/modify/delete will occur. Before a record is indexed
349 search keys are extracted from whatever might be the layout the
350 original record (sgml,html,text, etc..). The Zebra system 
351 currently only supports SGML-like, structured records and unstructured text
352 records.
353 To specify a particular extraction process, use either the
354 command line option <tt>-t</tt> or specify a
355 <tt>recordType</tt> setting in the configuration file.
356
357 <sect1>The Zebra Configuration File<label id="configuration-file">
358 <p>
359 The Zebra configuration file, read by <tt>zebraidx</tt> and
360 <tt>zebrasrv</tt> defaults to <tt>zebra.cfg</tt> unless specified
361 by <tt>-c</tt> option.
362
363 You can edit the configuration file with a normal text editor.
364 Parameter names and values are seperated by colons in the file. Lines
365 starting with a hash sign (<tt/&num;/) are treated as comments.
366
367 If you manage different sets of records that share common
368 characteristics, you can organize the configuration settings for each
369 type into &dquot;groups&dquot;.
370 When <tt>zebraidx</tt> is run and you wish to address a given group
371 you specify the group name with the <tt>-g</tt> option. In this case
372 settings that have the group name as their prefix will be used
373 by <tt>zebraidx</tt>. If no <tt/-g/ option is specified, the settings
374 with no prefix are used.
375
376 In the configuration file, the group name is placed before the option
377 name
378 itself, separated by a dot (.). For instance, to set the record type
379 for group <tt/public/ to <tt/grs/ (the common format for structured
380 records) you would write:
381
382 <tscreen><verb>
383 public.recordType: grs
384 </verb></tscreen>
385
386 To set the default value of the record type to <tt/text/ write:
387
388 <tscreen><verb>
389 recordType: text
390 </verb></tscreen>
391
392 The available configuration settings are summarized below. They will be
393 explained further in the following sections.
394
395 <descrip>
396 <tag><it>group</it>.recordType&lsqb;<it>.name</it>&rsqb;</tag>
397  Specifies how records with the file extension <it>name</it> should
398  be handled by the indexer. This option may also be specified
399  as a command line option (<tt>-t</tt>). Note that if you do not
400  specify a <it/name/, the setting applies to all files.
401 <tag><it>group</it>.recordId</tag>
402  Specifies how the records are to be identified when updated. See
403 section <ref id="locating-records" name="Locating Records">.
404 <tag><it>group</it>.database</tag>
405  Specifies the Z39.50 database name.
406 <tag><it>group</it>.storeKeys</tag>
407  Specifies whether key information should be saved for a given
408  group of records. If you plan to update/delete this type of
409  records later this should be specified as 1; otherwise it
410  should be 0 (default), to save register space. See section
411 <ref id="file-ids" name="Indexing With File Record IDs">.
412 <tag><it>group</it>.storeData</tag>
413  Specifies whether the records should be stored internally
414  in the Zebra system files. If you want to maintain the raw records yourself,
415  this option should be false (0). If you want Zebra to take care of the records
416  for you, it should be true(1).
417 <tag>register</tag> 
418  Specifies the location of the various register files that Zebra uses
419  to represent your databases. See section
420 <ref id="register-location" name="Register Location">.
421 <tag>shadow</tag>
422  Enables the <it/safe update/ facility of Zebra, and tells the system
423  where to place the required, temporary files. See section
424 <ref id="shadow-registers" name="Safe Updating - Using Shadow Registers">.
425 <tag>tempSetPath</tag>
426  Specifies the directory that the server uses for temporary result sets.
427  If not specified <tt>/tmp</tt> will be used.
428 <tag>profilePath</tag>
429  Specifies the location of profile specification files.
430 <tag>attset</tag> 
431  Specifies the filename(s) of attribute set files for use in
432  searching. At least the Bib-1 set should be loaded (<tt/bib1.att/).
433  The <tt/profilePath/ setting is used to look for the specified files.
434  See section <ref id="attset-files" name="The Attribute Set Files">
435 </descrip>
436
437 <sect1>Locating Records<label="locating-records">
438 <p>
439 The default behaviour of the Zebra system is to reference the
440 records from their original location, i.e. where they were found when you
441 ran <tt/zebraidx/. That is, when a client wishes to retrieve a record
442 following a search operation, the files are accessed from the place
443 where you originally put them - if you remove the files (without
444 running <tt/zebraidx/ again, the client will receive a diagnostic
445 message.
446
447 If your input files are not permanent - for example if you retrieve
448 your records from an outside source, or if they were temporarily
449 mounted on a CD-ROM drive,
450 you may want Zebra to make an internal copy of them. To do this,
451 you specify 1 (true) in the <tt>storeData</tt> setting. When
452 the Z39.50 server retrieves the records they will be read from the
453 internal file structures of the system.
454
455 <sect1>Indexing with no Record IDs (Simple Indexing)
456
457 <p>
458 If you have a set of records that is not expected to change over time
459 you may can build your database without record IDs.
460 This indexing method uses less space than the other methods and
461 is simple to use. 
462
463 To use this method, you simply don't provide the <tt>recordId</tt> entry
464 for the group of files that you index. To add a set of records you use
465 <tt>zebraidx</tt> with the <tt>update</tt> command. The
466 <tt>update</tt> command will always add all of the records that it
467 encounters to the index - whether they have already been indexed or
468 not. If the set of indexed files change, you should delete all of the
469 index files, and build a new index from scratch.
470
471 Consider a system in which you have a group of text files called
472 <tt>simple</tt>. That group of records should belong to a Z39.50 database
473 called <tt>textbase</tt>. The following <tt/zebra.cfg/ file will suffice:
474
475 <tscreen><verb>
476 profilePath: /usr/local/yaz
477 attset: bib1.att
478 simple.recordType: text
479 simple.database: textbase
480 </verb></tscreen>
481
482 Since the existing records in an index can not be addressed by their
483 IDs, it is impossible to delete or modify records when using this method.
484
485 <sect1>Indexing with File Record IDs<label id="file-ids">
486
487 <p>
488 If you have a set of files that regularly change over time: Old files
489 are deleted, new ones are added, or existing files are modified, you
490 can benefit from using the <it/file ID/ indexing methodology. Examples
491 of this type of database might include an index of WWW resources, or a
492 USENET news spool area. Briefly speaking, the file key methodology
493 uses the directory paths of the individual records as a unique
494 identifier for each record. To perform indexing of a directory with
495 file keys, again, you specify the top-level directory after the
496 <tt>update</tt> command. The command will recursively traverse the
497 directories and compare each one with whatever have been indexed before in
498 that same directory. If a file is new (not in the previous version of
499 the directory) it is inserted into the registers; if a file was
500 already indexed and it has been modified since the last update,
501 the index is also modified; if a file has been removed since the last
502 visit, it is deleted from the index.
503
504 The resulting system is easy to administrate. To delete a record you
505 simply have to delete the corresponding file (say, with the <tt/rm/
506 command). And to add records you create new files (or directories with
507 files). For your changes to take effect in the register you must run
508 <tt>zebraidx update</tt> with the same directory root again. This mode
509 of operation requires more disk space than simpler indexing methods,
510 but it makes it easier for you to keep the index in sync with a
511 frequently changing set of data. If you combine this system with the
512 <it/safe update/ facility (see below), you never have to take your
513 server offline for maintenance or register updating purposes.
514
515 To enable indexing with pathname IDs, you must specify <tt>file</tt> as
516 the value of <tt>recordId</tt> in the configuration file. In addition,
517 you should set <tt>storeKeys</tt> to <tt>1</tt>, since the Zebra
518 indexer must save additional information about the contents of each record
519 in order to modify the indices correctly at a later time.
520
521 For example, to update records of group <tt>esdd</tt> located below
522 <tt>/data1/records/</tt> you should type:
523 <tscreen><verb>
524 $ zebraidx -g esdd update /data1/records
525 </verb></tscreen>
526
527 The corresponding configuration file includes:
528 <tscreen><verb>
529 esdd.recordId: file
530 esdd.recordType: grs
531 esdd.storeKeys: 1
532 </verb></tscreen>
533
534 <em>Important note: You cannot start out with a group of records with simple
535 indexing (no record IDs as in the previous section) and then later
536 enable file record Ids. Zebra must know from the first time that you
537 index the group that
538 the files should be indexed with file record IDs.
539 </em>
540
541 You cannot explicitly delete records when using this method (using the
542 <bf/delete/ command to <tt/zebraidx/. Instead
543 you have to delete the files from the file system (or move them to a
544 different location)
545 and then run <tt>zebraidx</tt> with the <bf/update/ command.
546
547 <sect1>Indexing with General Record IDs
548 <p>
549 When using this method you construct an (almost) arbritrary, internal
550 record key based on the contents of the record itself and other system
551 information. If you have a group of records that explicitly associates
552 an ID with each record, this method is convenient. For example, the
553 record format may contain a title or a ID-number - unique within the group.
554 In either case you specify the Z39.50 attribute set and use-attribute
555 location in which this information is stored, and the system looks at
556 that field to determine the identity of the record.
557
558 As before, the record ID is defined by the <tt>recordId</tt> setting
559 in the configuration file. The value of the record ID specification
560 consists of one or more tokens separated by whitespace. The resulting
561 ID is
562 represented in the index by concatenating the tokens and separating them by
563 ASCII value (1).
564
565 There are three kinds of tokens:
566 <descrip>
567 <tag>Internal record info</tag> The token refers to a key that is
568 extracted from the record. The syntax of this token is
569  <tt/(/ <em/set/ <tt/,/ <em/use/ <tt/)/, where <em/set/ is the
570 attribute set ordinal number and <em/use/ is the use value of the attribute.
571 <tag>System variable</tag> The system variables are preceded by
572 <verb>$</verb> and immediately followed by the system variable name, which
573 may one of
574  <descrip>
575  <tag>group</tag> Group name.
576  <tag>database</tag> Current database specified.
577  <tag>type</tag> Record type.
578  </descrip>
579 <tag>Constant string</tag> A string used as part of the ID &mdash; surrounded
580  by single- or double quotes.
581 </descrip>
582
583 For instance, the sample GILS records that come with the Zebra
584 distribution contain a
585 unique ID
586 in the Control-Identifier field. This field is mapped to the Bib-1
587 use attribute 1007. To use this field as a record id, specify
588 <tt>(1,1007)</tt> as the value of the <tt>recordId</tt> in the
589 configuration file. If you have other record types that uses
590 the same field for a different purpose, you might add the record type (or group or database name)
591 to the record id of the gils records as well, to prevent matches
592 with other types of records. In this case the recordId might be
593 set like this:
594 <tscreen><verb>
595 gils.recordId: $type (1,1007)
596 </verb></tscreen>
597
598 (see section <ref id="data-model" name="Configuring Your Data Model">
599 for details of how the mapping between elements of your records and
600 searchable attributes is established).
601
602 As for the file record ID case described in the previous section,
603 updating your system is simply a matter of running <tt>zebraidx</tt>
604 with the <tt>update</tt> command. However, the update with general
605 keys is considerably slower than with file record IDs, since all files
606 visited must be (re)read to discover their IDs. 
607
608 As you might expect, when using the general record IDs
609 method, you can only add or modify existing records with the <tt>update</tt>
610 command. If you wish to delete records, you must use the,
611 <tt>delete</tt> command, with a directory as a parameter.
612 This will remove all records that match the files below that root
613 directory.
614
615 <sect1>Register Location<label id="register-location">
616
617 <p>
618 Normally, the index files that form dictionaries, inverted
619 files, record info, etc., are stored in the directory where you run
620 <tt>zebraidx</tt>. If you wish to store these, possibly large, files
621 somewhere else, you must add the <tt>register</tt> entry to the
622 <tt/zebra.cfg/ file. Furthermore, the Zebra system allows its file
623 structures to
624 span multiple file systems, which is useful for managing very large
625 databases. 
626
627 The value of the <tt>register</tt> setting is a sequence of tokens.
628 Each token takes the form:
629 <tscreen>
630 <em>dir</em><tt>:</tt><em>size</em>. 
631 </tscreen>
632 The <em>dir</em> specifies a directory in which index files will be
633 stored and the <em>size</em> specifies the maximum size of all
634 files in that directory. The Zebra indexer system fills each directory
635 in the order specified and use the next specified directories as needed.
636 The <em>size</em> is an integer followed by a qualifier
637 code, <tt>M</tt> for megabytes, <tt>k</tt> for kilobytes.
638
639 For instance, if you have allocated two disks for your register, and
640 the first disk is mounted
641 on <tt>/d1</tt> and has 200 Mb of free space and the
642 second, mounted on <tt>/d2</tt> has 300 Mb, you could
643 put this entry in your configuration file:
644 <tscreen><verb>
645 register: /d1:200M /d2:300M
646 </verb></tscreen>
647
648 Note that Zebra does not verify that the amount of space specified is
649 actually available on the directory (file system) specified - it is
650 your responsibility to ensure that enough space is available, and that
651 other applications do not attempt to use the free space. In a large production system,
652 it is recommended that you allocate one or more filesystem exclusively
653 to the Zebra register files.
654
655 <sect1>Safe Updating - Using Shadow Registers<label id="shadow-registers">
656
657 <sect2>Description
658
659 <p>
660 The Zebra server supports <it/updating/ of the index structures. That is,
661 you can add, modify, or remove records from databases managed by Zebra
662 without rebuilding the entire index. Since this process involves
663 modifying structured files with various references between blocks of
664 data in the files, the update process is inherently sensitive to
665 system crashes, or to process interruptions: Anything but a
666 successfully completed update process will leave the register files in
667 an unknown state, and you will essentially have no recourse but to
668 re-index everything, or to restore the register files from a backup
669 medium. Further, while the update process is active, users cannot be
670 allowed to access the system, as the contents of the register files
671 may change unpredictably.
672
673 You can solve these problems by enabling the shadow register system in
674 Zebra. During the updating procedure, <tt/zebraidx/ will temporarily
675 write changes to the involved files in a set of &dquot;shadow
676 files&dquot;, without modifying the files that are accessed by the
677 active server processes. If the update procedure is interrupted by a
678 system crash or a signal, you simply repeat the procedure - the
679 register files have not been changed or damaged, and the partially
680 written shadow files are automatically deleted before the new updating
681 procedure commences.
682
683 At the end of the updating procedure (or in a separate operation, if
684 you so desire), the system enters a &dquot;commit mode&dquot;. First,
685 any active server processes are forced to access those blocks that
686 have been changed from the shadow files rather than from the main
687 register files; the unmodified blocks are still accessed at their
688 normal location (the shadow files are not a complete copy of the
689 register files - they only contain those parts that have actually been
690 modified). If the commit process is interrupted at any point during the
691 commit process, the server processes will continue to access the
692 shadow files until you can repeat the commit procedure and complete
693 the writing of data to the main register files. You can perform
694 multiple update operations to the registers before you commit the
695 changes to the system files, or you can execute the commit operation
696 at the end of each update operation. When the commit phase has
697 completed successfully, any running server processes are instructed to
698 switch their operations to the new, operational register, and the
699 temporary shadow files are deleted.
700
701 <sect2>How to Use Shadow Register Files
702
703 <p>
704 The first step is to allocate space on your system for the shadow
705 files. You do this by adding a <tt/shadow/ entry to the <tt/zebra.cfg/
706 file. The syntax of the <tt/shadow/ entry is exactly the same as for
707 the <tt/register/ entry (see section <ref name="Register Location"
708 id="register-location">). The location of the shadow area should be
709 <it/different/ from the location of the main register area (if you
710 have specified one - remember that if you provide no <tt/register/
711 setting, the default register area is the
712 working directory of the server and indexing processes).
713
714 The following excerpt from a <tt/zebra.cfg/ file shows one example of
715 a setup that configures both the main register location and the shadow
716 file area. Note that two directories or partitions have been set aside
717 for the shadow file area. You can specify any number of directories
718 for each of the file areas, but remember that there should be no
719 overlaps between the directories used for the main registers and the
720 shadow files, respectively.
721
722 <tscreen><verb>
723 register: /d1:500M
724
725 shadow: /scratch1:100M /scratch2:200M
726 </verb></tscreen>
727
728 When shadow files are enabled, an extra command is available at the
729 <tt/zebraidx/ command line. In order to make changes to the system
730 take effect for the users, you'll have to submit a
731 &dquot;commit&dquot; command after a (sequence of) update
732 operation(s). You can ask the indexer to commit the changes
733 immediately after the update operation:
734
735 <tscreen><verb>
736 $ zebraidx update /d1/records update /d2/more-records commit
737 </verb></tscreen>
738
739 Or you can execute multiple updates before committing the changes:
740
741 <tscreen><verb>
742 $ zebraidx -g books update /d1/records update /d2/more-records
743 $ zebraidx -g fun update /d3/fun-records
744 $ zebraidx commit
745 </verb></tscreen>
746
747 If one of the update operations above had been interrupted, the commit
748 operation on the last line would fail: <tt/zebraidx/ will not let you
749 commit changes that would destroy the running register. You'll have to
750 rerun all of the update operations since your last commit operation,
751 before you can commit the new changes.
752
753 Similarly, if the commit operation fails, <tt/zebraidx/ will not let
754 you start a new update operation before you have successfully repeated
755 the commit operation. The server processes will keep accessing the
756 shadow files rather than the (possibly damaged) blocks of the main
757 register files until the commit operation has successfully completed.
758
759 You should be aware that update operations may take slightly longer
760 when the shadow register system is enabled, since more file access
761 operations are involved. Further, while the disk space required for
762 the shadow register data is modest for a small update operation, you
763 may prefer to disable the system if you are adding a very large number
764 of records to an already very large database (we use the terms
765 <it/large/ and <it/modest/ very loosely here, since every
766 application will have a different perception of size). To update the system
767 without the use of the the shadow files, simply run <tt/zebraidx/ with
768 the <tt/-n/ option (note that you do not have to execute the
769 <bf/commit/ command of <tt/zebraidx/ when you temporarily disable the
770 use of the shadow registers in this fashion. Note also that, just as
771 when the shadow registers are not enabled, server processes will be
772 barred from accessing the main register while the update procedure
773 takes place.
774
775 <sect>Running the Maintenance Interface (zebraidx)
776
777 <p>
778 The following is a complete reference to the command line interface to
779 the <tt/zebraidx/ application.
780
781 <bf/Syntax/
782 <tscreen><verb>
783 $ zebraidx &lsqb;options&rsqb; command &lsqb;directory&rsqb; ...
784 </verb></tscreen>
785 <bf/Options/
786 <descrip>
787 <tag>-t <it/type/</tag>Update all files as <it/type/. Currently, the
788 types supported are <tt/text/ and <tt/grs/<it/.filter/. If no
789 <it/filter/ is provided for the GRS (General Record Structure) type,
790 the canonical input format is assumed (see section <ref
791 id="local-representation" name="Local Representation">). Generally, it
792 is probably advisable to specify the record types in the
793 <tt/zebra.cfg/ file (see section <ref id="record-types" name="Record Types">).
794
795 <tag>-c <it/config-file/</tag>Read the configuration file
796 <it/config-file/ instead of <tt/zebra.cfg/.
797
798 <tag>-g <it/group/</tag>Update the files according to the group
799 settings for <it/group/ (see section <ref id="configuration-file"
800 name="The Zebra Configuration File">).
801
802 <tag>-d <it/database/</tag>The records located should be associated
803 with the database name <it/database/ for access through the Z39.50
804 server.
805
806 <tag>-d <it/mbytes/</tag>Use <it/mbytes/ of megabytes before flushing
807 keys to background storage. This setting affects performance when
808 updating large databases.
809
810 <tag>-n</tag>Disable the use of shadow registers for this operation
811 (see section <ref id="shadow-registers" name="Robust Updating - Using
812 Shadow Registers">).
813
814 <tag>-v <it/level/</tag>Set the log level to <it/level/. <it/level/
815 should be one of <tt/none/, <tt/debug/, and <tt/all/.
816
817 </descrip>
818
819 <bf/Commands/
820 <descrip>
821 <tag>Update <it/directory/</tag>Update the register with the files
822 contained in <it/directory/. If no directory is provided, a list of
823 files is read from <tt/stdin/. See section <ref
824 id="administrating" name="Administrating Zebra">.
825
826 <tag>Delete <it/directory/</tag>Remove the records corresponding to
827 the files found under <it/directory/ from the register.
828
829 <tag/Commit/Write the changes resulting from the last <bf/update/
830 commands to the register. This command is only available if the use of
831 shadow register files is enabled (see section <ref
832 id="shadow-registers" name="Robust Updating - Using Shadow
833 Registers">).
834
835 </descrip>
836
837 <sect>Running the Z39.50 Server (zebrasrv)
838
839 <p>
840 <bf/Syntax/
841 <tscreen><verb>
842 zebrasrv &lsqb;options&rsqb; &lsqb;listener-address ...&rsqb;
843 </verb></tscreen>
844
845 <bf/Options/
846 <descrip>
847 <tag>-a <it/APDU file/</tag> Specify a file for dumping PDUs (for diagnostic purposes).
848 The special name &dquot;-&dquot; sends output to <tt/stderr/.
849
850 <tag>-c <it/config-file/</tag> Read configuration information from <it/config-file/. The default configuration is <tt>./zebra.cfg</tt>.
851
852 <tag/-S/Don't fork on connection requests. This can be useful for
853 symbolic-level debugging. The server can only accept a single
854 connection in this mode.
855
856 <tag/-s/Use the SR protocol.
857
858 <tag/-z/Use the Z39.50 protocol (default). These two options complement
859 eachother. You can use both multiple times on the same command
860 line, between listener-specifications (see below). This way, you
861 can set up the server to listen for connections in both protocols
862 concurrently, on different local ports.
863
864 <tag>-l <it/logfile/</tag>Specify an output file for the diagnostic
865 messages. The default is to write this information to <tt/stderr/.
866
867 <tag>-v <it/log-level/</tag>The log level. Use a comma-separated list of members of the set
868 {fatal,debug,warn,log,all,none}.
869
870 <tag>-u <it/username/</tag>Set user ID. Sets the real UID of the server process to that of the
871 given <it/username/. It's useful if you aren't comfortable with having the
872 server run as root, but you need to start it as such to bind a
873 privileged port.
874
875 <tag>-w <it/working-directory/</tag>Change working directory.
876
877 <tag/-i/Run under the Internet superserver, <tt/inetd/.
878 </descrip>
879
880 A <it/listener-address/ consists of a transport mode followed by a
881 colon (:) followed by a listener address. The transport mode is
882 either <tt/osi/ or <tt/tcp/.
883
884 For TCP, an address has the form
885
886 <tscreen><verb>
887 hostname | IP-number &lsqb;: portnumber&rsqb;
888 </verb></tscreen>
889
890 The port number defaults to 210 (standard Z39.50 port).
891
892 For OSI (only available if the server is compiled with XTI/mOSI
893 support enabled), the address form is
894
895 <tscreen><verb>
896 &lsqb;t-selector /&rsqb; hostname | IP-number &lsqb;: portnumber&rsqb;
897 </verb></tscreen>
898
899 The transport selector is given as a string of hex digits (with an even
900 number of digits). The default port number is 102 (RFC1006 port).
901
902 Examples
903
904 <tscreen>
905 <verb>
906 tcp:dranet.dra.com
907
908 osi:0402/dbserver.osiworld.com:3000
909 </verb>
910 </tscreen>
911
912 In both cases, the special hostname &dquot;@&dquot; is mapped to
913 the address INADDR_ANY, which causes the server to listen on any local
914 interface. To start the server listening on the registered ports for
915 Z39.50 and SR over OSI/RFC1006, and to drop root privileges once the
916 ports are bound, execute the server like this (from a root shell):
917
918 <tscreen><verb>
919 zebrasrv -u daemon tcp:@ -s osi:@
920 </verb></tscreen>
921
922 You can replace <tt/daemon/ with another user, eg. your own account, or
923 a dedicated IR server account.
924
925 The default behavior for <tt/zebrasrv/ is to establish a single TCP/IP
926 listener, for the Z39.50 protocol, on port 9999.
927
928 <sect>The Record Model
929
930 <p>
931 The Zebra system is designed to support a wide range of data management
932 applications. The system can be configured to handle virtually any
933 kind of structured data. Each record in the system is associated with
934 a <it/record schema/ which lends context to the data elements of the
935 record. Any number of record schema can coexist in the system.
936 Although it may be wise to use only a single schema within
937 one database, the system poses no such restrictions.
938
939 Records pass through three different states during processing in the
940 system.
941
942 <itemize>
943 <item>When records are accessed by the system, they are represented
944 in their local, or native format. This might be SGML or HTML files,
945 News or Mail archives, MARC records. If the system doesn't already
946 know how to read the type of data you need to store, you can set up an
947 input filter by preparing conversion rules based on regular
948 expressions and a flexible scripting language (Tcl). The input filter
949 produces as output an internal representation:
950
951 <item>When records are processed by the system, they are represented
952 in a tree-structure, constructed by tagged data elements hanging off a
953 root node. The tagged elements may contain data or yet more tagged
954 elements in a recursive structure. The system performs various
955 actions on this tree structure (indexing, element selection, schema
956 mapping, etc.),
957
958 <item>Before transmitting records to the client, they are first
959 converted from the internal structure to a form suitable for exchange
960 over the network - according to the Z39.50 standard.
961 </itemize>
962
963 <sect1>Local Representation<label id="local-representation">
964
965 <p>
966 As mentioned earlier, Zebra places few restrictions on the type of
967 data that you can index and manage. Generally, whatever the form of
968 the data, it is parsed by an input filter specific to that format, and
969 turned into an internal structure that Zebra knows how to handle. This
970 process takes place whenever the record is accessed - for indexing and
971 retrieval.
972
973 <sect2>Canonical Input Format
974
975 <p>
976 Although input data can take any form, it is sometimes useful to
977 describe the record processing capabilities of the system in terms of
978 a single, canonical input format that gives access to the full
979 spectrum of structure and flexibility in the system. In Zebra, this
980 canonical format is an &dquot;SGML-like&dquot; syntax.
981
982 Consider a record describing an information resource (such a record is
983 sometimes known as a <it/locator record/). It might contain a field
984 describing the distributor of the information resource, which might in
985 turn be partitioned into various fields providing details about the
986 distributor, like this:
987
988 <tscreen><verb>
989 <Distributor>
990     <Name> USGS/WRD &etago;Name>
991     <Organization> USGS/WRD &etago;Organization>
992     <Street-Address>
993         U.S. GEOLOGICAL SURVEY, 505 MARQUETTE, NW
994     &etago;Street-Address>
995     <City> ALBUQUERQUE &etago;City>
996     <State> NM &etago;State>
997     <Zip-Code> 87102 &etago;Zip-Code>
998     <Country> USA &etago;Country>
999     <Telephone> (505) 766-5560 &etago;Telephone>
1000 &etago;Distributor>
1001 </verb></tscreen>
1002
1003 <it>NOTE: The indentation used above is used to illustrate how Zebra
1004 interprets the markup. The indentation, in itself, has no
1005 significance to the parser for the canonical input format, which
1006 discards superfluous whitespace.</it>
1007
1008 The keywords surrounded by &lt;...&gt; are <it/tags/, while the
1009 sections of text in between are the <it/data elements/. A data element
1010 is characterized by its location in the tree that is made up by the
1011 nested elements. Each element is terminated by a closing tag -
1012 beginning with &etago;, and containing the same symbolic tag-name as
1013 the corresponding opening tag. The general closing tag - &etago;&gt; -
1014 terminates the element started by the last opening tag. The
1015 structuring of elements is significant. The element <bf/Telephone/,
1016 for instance, may be indexed and presented to the client differently,
1017 depending on whether it appears inside the <bf/Distributor/ element,
1018 or some other, structured data element such a <bf/Supplier/ element.
1019
1020 <sect3>Record Root
1021
1022 <p>
1023 The first tag in a record describes the root node of the tree that
1024 makes up the total record. In the canonical input format, the root tag
1025 should contain the name of the schema that lends context to the
1026 elements of the record (see section <ref id="internal-representation"
1027 name="Internal Representation">). The following is a GILS record that
1028 contains only a single element (strictly speaking, that makes it an
1029 illegal GILS record, since the GILS profile includes several mandatory
1030 elements - Zebra does not validate the contents of a record against
1031 the Z39.50 profile, however - it merely attempts to match up elements
1032 of a local representation with the given schema):
1033
1034 <tscreen><verb>
1035 <gils>
1036     <title>Zen and the Art of Motorcycle Maintenance&etago;title>
1037 &etago;gils>
1038 </verb></tscreen>
1039
1040 <sect3>Variants
1041
1042 <p>
1043 Zebra allows you to provide individual data elements in a number of
1044 <it/variant forms/. Examples of variant forms are textual data
1045 elements which might appear in different languages, and images which
1046 may appear in different formats or layouts. The variant system in
1047 Zebra is
1048 essentially a representation of the variant mechanism of
1049 Z39.50-1995.
1050
1051 The following is an example of a title element which occurs in two
1052 different languages.
1053
1054 <tscreen><verb>
1055 <title>
1056   <var lang lang "eng">
1057     Zen and the Art of Motorcycle Maintenance&etago;>
1058   <var lang lang "dan">
1059     Zen og Kunsten at Vedligeholde en Motorcykel&etago;>
1060 &etago;title>
1061 </verb></tscreen>
1062
1063 The syntax of the <it/variant element/ is <tt>&lt;<bf/var/ <it/class
1064 type value/&gt;</tt>. The available values for the <it/class/ and
1065 <it/type/ fields are given by the variant set that is associated with the
1066 current schema (see section <ref id="variant-set" name="Variant Set
1067 File">).
1068
1069 Variant elements are terminated by the general end-tag &etago;>, by
1070 the variant end-tag &etago;var>, by the appearance of another variant
1071 tag with the same <it/class/ and <it/value/ settings, or by the
1072 appearance of another, normal tag. In other words, the end-tags for
1073 the variants used in the example above could have been saved.
1074
1075 Variant elements can be nested. The element
1076
1077 <tscreen><verb>
1078 <title>
1079   <var lang lang "eng"><var body iana "text/plain">
1080     Zen and the Art of Motorcycle Maintenance
1081 &etago;title>
1082 </verb></tscreen>
1083
1084 Associates two variant components to the variant list for the title
1085 element.
1086
1087 Given the nesting rules described above, we could write
1088
1089 <tscreen><verb>
1090 <title>
1091   <var body iana "text/plain>
1092     <var lang lang "eng">
1093       Zen and the Art of Motorcycle Maintenance
1094     <var lang lang "dan">
1095       Zen og Kunsten at Vedligeholde en Motorcykel
1096 &etago;title>
1097 </verb></tscreen>
1098
1099 The title element above comes in two variants. Both have the IANA body
1100 type &dquot;text/plain&dquot;, but one is in English, and the other in
1101 Danish. The client, using the element selection mechanism of Z39.50,
1102 can retrieve information about the available variant forms of data
1103 elements, or it can select specific variants based on the requirements
1104 of the end-user.
1105
1106 <sect2>Input Filters
1107
1108 <p>
1109 In order to handle general input formats, Zebra allows the
1110 operator to define filters which read individual records in their native format
1111 and produce an internal representation that the system can
1112 work with.
1113
1114 Input filters are ASCII files, generally with the suffix <tt/.flt/.
1115 The system looks for the files in the directories given in the
1116 <bf/profilePath/ setting in the <tt/zebra.cfg/ file.
1117
1118 Generally, an input filter consists of a sequence of rules, where each
1119 rule consists of a sequence of expressions, followed by an action. The
1120 expressions are evaluated against the contents of the input record,
1121 and the actions normally contribute to the generation of an internal
1122 representation of the record.
1123
1124 An expression can be either of the following:
1125
1126 <descrip>
1127 <tag/INIT/The action associated with this expression is evaluated
1128 exactly once in the lifetime of the application, before any records
1129 are read. It can be used in conjunction with an action that
1130 initializes tables or other resources that are used in the processing
1131 of input records.
1132
1133 <tag/BEGIN/Matches the beginning of the record. It can be used to
1134 initialize variables, etc. Typically, the <bf/BEGIN/ rule is also used
1135 to establish the root node of the record.
1136
1137 <tag/END/Matches the end of the record - when all of the contents
1138 of the record has been processed.
1139
1140 <tag>/pattern/</tag>Matches a string of characters from the input
1141 record.
1142
1143 <tag/BODY/This keyword may only be used between two patterns. It
1144 matches everything between (not including) those patterns.
1145
1146 <tag/FINISH/THe expression asssociated with this pattern is evaluated
1147 once, before the application terminates. It can be used to release
1148 system resources - typically ones allocated in the <bf/INIT/ step.
1149
1150 </descrip>
1151
1152 An action is surrounded by curly braces ({...}), and consists of a
1153 sequence of statements. Statements may be separated by newlines or
1154 semicolons (;). Within actions, the strings that matched the
1155 expressions immediately preceding the action can be referred to as
1156 &dollar;0, &dollar;1, &dollar;2, etc.
1157
1158 The available statements are:
1159
1160 <descrip>
1161
1162 <tag>begin <it/type &lsqb;parameter ... &rsqb;/</tag>Begin a new
1163 data element. The type is one of the following:
1164 <descrip>
1165 <tag/record/Begin a new record. The followingparameter should be the
1166 name of the schema that describes the structure of the record, eg.
1167 <tt/gils/ or <tt/wais/ (see below). The <tt/begin record/ call should
1168 precede
1169 any other use of the <bf/begin/ statement.
1170
1171 <tag/element/Begin a new tagged element. The parameter is the
1172 name of the tag. If the tag is not matched anywhere in the tagsets
1173 referenced by the current schema, it is treated as a local string
1174 tag.
1175
1176 <tag/variant/Begin a new node in a variant tree. The parameters are
1177 <it/class type value/.
1178
1179 </descrip>
1180
1181 <tag/data/Create a data element. The concatenated arguments make
1182 up the value of the data element. The option <tt/-text/ signals that
1183 the layout (whitespace) of the data should be retained for
1184 transmission. The option <tt/-element/ <it/tag/ wraps the data up in
1185 the <it/tag/. The use of the <tt/-element/ option is equivalent to
1186 preceding the command with a <bf/begin element/ command, and following
1187 it with the <bf/end/ command.
1188
1189 <tag>end <it/&lsqb;type&rsqb;/</tag>Close a tagged element. If no parameter is given,
1190 the last element on the stack is terminated. The first parameter, if
1191 any, is a type name, similar to the <bf/begin/ statement. For the
1192 <bf/element/ type, a tag name can be provided to terminate a specific tag.
1193
1194 </descrip>
1195
1196 The following input filter reads a Usenet news file, producing a
1197 record in the WAIS schema. Note that the body of a news posting is
1198 separated from the list of headers by a blank line (or rather a
1199 sequence of two newline characters.
1200
1201 <tscreen><verb>
1202 BEGIN                { begin record wais }
1203
1204 /^From:/ BODY /$/    { data -element name $1 }
1205 /^Subject:/ BODY /$/ { data -element title $1 }
1206 /^Date:/ BODY /$/    { data -element lastModified $1 }
1207 /\n\n/ BODY END      {
1208                         begin element bodyOfDisplay
1209                         begin variant body iana "text/plain"
1210                         data -text $1
1211                         end record
1212                      }
1213 </verb></tscreen>
1214
1215 If Zebra is compiled with support for Tcl (Tool Command Language)
1216 enabled, the statements described above are supplemented with a complete
1217 scripting environment, including control structures (conditional
1218 expressions and loop constructs), and powerful string manipulation
1219 mechanisms for modifying the elements of a record. Tcl is a popular
1220 scripting environment, with several tutorials available both online
1221 and in hardcopy.
1222
1223 <it>NOTE: Tcl support is not currently available, but will be
1224 included with one of the next alpha or beta releases.</it>
1225
1226 <it>NOTE: Variant support is not currently available in the input
1227 filter, but will be included with one of the next alpha or beta
1228 releases.</it>
1229
1230 <sect1>Internal Representation<label id="internal-representation">
1231
1232 <p>
1233 When records are manipulated by the system, they're represented in a
1234 tree-structure, with data elements at the leaf nodes, and tags or
1235 variant components at the non-leaf nodes. The root-node identifies the
1236 schema that lends context to the tagging and structuring of the
1237 record. Imagine a simple record, consisting of a 'title' element and
1238 an 'author' element:
1239
1240 <tscreen><verb>
1241         TITLE     "Zen and the Art of Motorcycle Maintenance"
1242 ROOT 
1243         AUTHOR    "Robert Pirsig"
1244 </verb></tscreen>
1245
1246 A slightly more complex record would have the author element consist
1247 of two elements, a surname and a first name:
1248
1249 <tscreen><verb>
1250         TITLE     "Zen and the Art of Motorcycle Maintenance"
1251 ROOT  
1252                   FIRST-NAME "Robert"
1253         AUTHOR
1254                   SURNAME    "Pirsig"
1255 </verb></tscreen>
1256
1257 The root of the record will refer to the record schema that describes
1258 the structuring of this particular record. The schema defines the
1259 element tags (TITLE, FIRST-NAME, etc.) that may occur in the record, as
1260 well as the structuring (SURNAME should appear below AUTHOR, etc.). In
1261 addition, the schema establishes element set names that are used by
1262 the client to request a subset of the elements of a given record. The
1263 schema may also establish rules for converting the record to a
1264 different schema, by stating, for each element, a mapping to a
1265 different tag path.
1266
1267 <sect2>Tagged Elements
1268
1269 <p>
1270 A data element is characterized by its tag, and its position in the
1271 structure of the record. For instance, while the tag &dquot;telephone
1272 number&dquot; may be used different places in a record, we may need to
1273 distinguish between these occurrences, both for searching and
1274 presentation purposes. For instance, while the phone numbers for the
1275 &dquot;customer&dquot; and the &dquot;service provider&dquot; are both
1276 representatives for the same type of resource (a telephone number), it
1277 is essential that they be kept separate. The record schema provides
1278 the structure of the record, and names each data element (defined by
1279 the sequence of tags - the tag path - by which the element can be
1280 reached from the root of the record).
1281
1282 <sect2>Variants
1283
1284 <p>
1285 The children of a tag node may be either more tag nodes, a data node
1286 (possibly accompanied by tag nodes),
1287 or a tree of variant nodes. The children of  variant nodes are either
1288 more variant nodes or a data node (possibly accompanied by more
1289 variant nodes). Each leaf node, which is normally a
1290 data node, corresponds to a <it/variant form/ of the tagged element
1291 identified by the tag which parents the variant tree. The following
1292 title element occurs in two different languages:
1293
1294 <tscreen><verb>
1295       VARIANT LANG=ENG  "War and Peace"
1296 TITLE
1297       VARIANT LANG=DAN  "Krig og Fred"
1298 </verb></tscreen>
1299
1300 Which of the two elements are transmitted to the client by the server
1301 depends on the specifications provided by the client, if any.
1302
1303 In practice, each variant node is associated with a triple of class,
1304 type, value, corresponding to the variant mechanism of Z39.50.
1305
1306 <sect2>Data Elements
1307
1308 <p>
1309 Data nodes have no children (they are always leaf nodes in the record
1310 tree).
1311
1312 <it>NOTE: Documentation needs extension here about types of nodes - numerical,
1313 textual, etc., plus the various types of inclusion notes.</it>
1314
1315 <sect1>Configuring Your Data Model<label id="data-model">
1316
1317 <p>
1318 The following sections describe the configuration files that govern
1319 the internal management of data records. The system searches for the files
1320 in the directories specified by the <bf/profilePath/ setting in the
1321 <tt/zebra.cfg/ file.
1322
1323 <sect2>The Abstract Syntax
1324
1325 <p>
1326 The abstract syntax definition (also known as an Abstract Record
1327 Structure, or ARS) is the focal point of the
1328 record schema description. For a given schema, the ABS file may state any
1329 or all of the following:
1330
1331 <itemize>
1332 <item>The object identifier of the Z39.50 schema associated
1333 with the ARS, so that it can be referred to by the client.
1334
1335 <item>The attribute set (which can possibly be a compound of multiple
1336 sets) which applies in the profile. This is used when indexing and
1337 searching the records belonging to the given profile.
1338
1339 <item>The Tag set (again, this can consist of several different sets).
1340 This is used when reading the records from a file, to recognize the
1341 different tags, and when transmitting the record to the client -
1342 mapping the tags to their numerical representation, if they are
1343 known.
1344
1345 <item>The variant set which is used in the profile. This provides a
1346 vocabulary for specifying the <it/forms/ of data that appear inside
1347 the records.
1348
1349 <item>Element set names, which are a shorthand way for the client to
1350 ask for a subset of the data elements contained in a record. Element
1351 set names, in the retrieval module, are mapped to <it/element
1352 specifications/, which contain information equivalent to the
1353 <it/Espec-1/ syntax of Z39.50.
1354
1355 <item>Map tables, which may specify mappings to <it/other/ database
1356 profiles, if desired.
1357
1358 <item>Possibly, a set of rules describing the mapping of elements to a
1359 MARC representation.
1360
1361 <item>A list of element descriptions (this is the actual ARS of the
1362 schema, in Z39.50 terms), which lists the ways in which the various
1363 tags can be used and organized hierarchically.
1364 </itemize>
1365
1366 Several of the entries above simply refer to other files, which
1367 describe the given objects.
1368
1369 <sect2>The Configuration Files
1370
1371 <p>
1372 This section describes the syntax and use of the various tables which
1373 are used by the retrieval module.
1374
1375 The number of different file types may appear daunting at first, but
1376 each type corresponds fairly clearly to a single aspect of the Z39.50
1377 retrieval facilities. Further, the average database administrator,
1378 who is simply reusing an existing profile for which tables already
1379 exist, shouldn't have to worry too much about the contents of these tables.
1380
1381 Generally, the files are simple ASCII files, which can be maintained
1382 using any text editor. Blank lines, and lines beginning with a (&num;) are
1383 ignored. Any characters on a line followed by a (&num;) are also ignored.
1384 All other
1385 lines contain <it/directives/, which provide some setting or value
1386 to the system. Generally, settings are characterized by a single
1387 keyword, identifying the setting, followed by a number of parameters.
1388 Some settings are repeatable (r), while others may occur only once in a
1389 file. Some settings are optional (o), whicle others again are
1390 mandatory (m).
1391
1392 <sect2>The Abstract Syntax (.abs) Files
1393
1394 <p>
1395 The name of this file type is slightly misleading in Z39.50 terms,
1396 since, apart from the actual abstract syntax of the profile, it also
1397 includes most of the other definitions that go into a database
1398 profile.
1399
1400 When a record in the canonical, SGML-like format is read from a file
1401 or from the database, the first tag of the file should reference the
1402 profile that governs the layout of the record. If the first tag of the
1403 record is, say, <tt>&lt;gils&gt;</tt>, the system will look for the profile
1404 definition in the file <tt/gils.abs/. Profile definitions are cached,
1405 so they only have to be read once during the lifespan of the current
1406 process. 
1407
1408 When writing your own input filters, the <bf/record-begin/ command
1409 introduces the profile, and should always be called first thing when
1410 introducing a new record.
1411
1412 The file may contain the following directives:
1413
1414 <descrip>
1415 <tag>name <it/symbolic-name/</tag> (m) This provides a shorthand name or
1416 description for the profile. Mostly useful for diagnostic purposes.
1417
1418 <tag>reference <it/OID-name/</tag> (m) The reference name of the OID for
1419 the profile. The reference names can be found in the <bf/util/
1420 module of <bf/YAZ/.
1421
1422 <tag>attset <it/filename/</tag> (m) The attribute set that is used for
1423 indexing and searching records belonging to this profile.
1424
1425 <tag>tagset <it/filename/</tag> (o) The tag set (if any) that describe
1426 that fields of the records.
1427
1428 <tag>varset <it/filename/</tag> (o) The variant set used in the profile.
1429
1430 <tag>maptab <it/filename/</tag> (o,r) This points to a
1431 conversion table that might be used if the client asks for the record
1432 in a different schema from the native one.
1433
1434 <tag>marc <it/filename/</tag> (o) Points to a file containing parameters
1435 for representing the record contents in the ISO2709 syntax. Read the
1436 description of the MARC representation facility below.
1437
1438 <tag>esetname <it/name filename/</tag> (o,r) Associates the
1439 given element set name with an element selection file. If an (@) is
1440 given in place of the filename, this corresponds to a null mapping for
1441 the given element set name.
1442
1443 <tag>elm <it/path name attribute/</tag> (o,r) Adds an element
1444 to the abstract record syntax of the schema. The <it/path/ follows the
1445 syntax which is suggested by the Z39.50 document - that is, a sequence
1446 of tags separated by slashes (/). Each tag is given as a
1447 comma-separated pair of tag type and -value surrounded by parenthesis.
1448 The <it/name/ is the name of the element, and the <it/attribute/
1449 specifies what attribute to use when indexing the element. A ! in
1450 place of the attribute name is equivalent to specifying an attribute
1451 name identical to the element name. A - in place of the attribute name
1452 specifies that no indexing is to take place for the given element.
1453 </descrip>
1454
1455 <it>
1456 NOTE: The mechanism for controlling indexing is not adequate for
1457 complex databases, and will probably be moved into a separate
1458 configuration table eventually.
1459 </it>
1460
1461 The following is an excerpt from the abstract syntax file for the GILS
1462 profile.
1463
1464 <tscreen><verb>
1465 name gils
1466 reference GILS-schema
1467 attset gils.att
1468 tagset gils.tag
1469 varset var1.var
1470
1471 maptab gils-usmarc.map
1472
1473 # Element set names
1474
1475 esetname VARIANT gils-variant.est  # for WAIS-compliance
1476 esetname B gils-b.est
1477 esetname G gils-g.est
1478 esetname F @
1479
1480 elm (1,10)              rank                        -
1481 elm (1,12)              url                         -
1482 elm (1,14)              localControlNumber     Local-number
1483 elm (1,16)              dateOfLastModification Date/time-last-modified
1484 elm (2,1)               Title                       !
1485 elm (4,1)               controlIdentifier      Identifier-standard
1486 elm (2,6)               abstract               Abstract
1487 elm (4,51)              purpose                     !
1488 elm (4,52)              originator                  - 
1489 elm (4,53)              accessConstraints           !
1490 elm (4,54)              useConstraints              !
1491 elm (4,70)              availability                -
1492 elm (4,70)/(4,90)       distributor                 -
1493 elm (4,70)/(4,90)/(2,7) distributorName             !
1494 elm (4,70)/(4,90)/(2,10 distributorOrganization     !
1495 elm (4,70)/(4,90)/(4,2) distributorStreetAddress    !
1496 elm (4,70)/(4,90)/(4,3) distributorCity             !
1497 </verb></tscreen>
1498
1499 <sect2>The Attribute Set (.att) Files<label id="attset-files">
1500
1501 <p>
1502 This file type describes the <bf/Use/ elements of an attribute set.
1503 It contains the following directives. 
1504
1505 <descrip>
1506
1507 <tag>name <it/symbolic-name/</tag> (m) This provides a shorthand name or
1508 description for the attribute set. Mostly useful for diagnostic purposes.
1509
1510 <tag>reference <it/OID-name/</tag> (m) The reference name of the OID for
1511 the attribute set. The reference names can be found in the <bf/util/
1512 module of <bf/YAZ/.
1513
1514 <tag>ordinal <it/integer/</tag> (m) This value will be used to represent the
1515 attribute set in the index. Care should be taken that each attribute
1516 set has a unique ordinal value.
1517
1518 <tag>include <it/filename/</tag> (o,r) This directive is used to
1519 include another attribute set as a part of the current one. This is
1520 used when a new attribute set is defined as an extension to another
1521 set. For instance, many new attribute sets are defined as extensions
1522 to the <bf/bib-1/ set. This is an important feature of the retrieval
1523 system of Z39.50, as it ensures the highest possible level of
1524 interoperability, as those access points of your database which are
1525 derived from the external set (say, bib-1) can be used even by clients
1526 who are unaware of the new set.
1527
1528 <tag>att <it/att-value att-name &lsqb;local-value&rsqb;/</tag> (o,r) This
1529 repeatable directive introduces a new attribute to the set. The
1530 attribute value is stored in the index (unless a <it/local-value/ is
1531 given, in which case this is stored). The name is used to refer to the
1532 attribute from the <it/abstract syntax/. </descrip>
1533
1534 This is an excerpt from the GILS attribute set definition. Notice how
1535 the file describing the <it/bib-1/ attribute set is referenced.
1536
1537 <tscreen><verb>
1538 name gils
1539 reference GILS-attset
1540 include bib1.att
1541 ordinal 2
1542
1543 att 2001                distributorName
1544 att 2002                indexTermsControlled
1545 att 2003                purpose
1546 att 2004                accessConstraints
1547 att 2005                useConstraints
1548 </verb></tscreen>
1549
1550 <sect2>The Tag Set (.tag) Files
1551
1552 <p>
1553 This file type defines the tagset of the profile, possibly by
1554 referencing other tag sets (most tag sets, for instance, will include
1555 tagsetG and tagsetM from the Z39.50 specification. The file may
1556 contain the following directives.
1557
1558 <descrip>
1559 <tag>name <it/symbolic-name/</tag> (m) This provides a shorthand name or
1560 description for the tag set. Mostly useful for diagnostic purposes.
1561
1562 <tag>reference <it/OID-name/</tag> (o) The reference name of the OID for
1563 the tag set. The reference names can be found in the <bf/util/
1564 module of <bf/YAZ/. The directive is optional, since not all tag sets
1565 are registered outside of their schema.
1566
1567 <tag>type <it/integer/</tag> (m) The type number of the tag within the schema
1568 profile.
1569
1570 <tag>include <it/filename/</tag> (o,r) This directive is used
1571 to include the definitions of other tag sets into the current one.
1572
1573 <tag>tag <it/number names type/</tag> (o,r) Introduces a new
1574 tag to the set. The <it/number/ is the tag number as used in the protocol
1575 (there is currently no mechanism for specifying string tags at this
1576 point, but this would be quick work to add). The <it/names/ parameter
1577 is a list of names by which the tag should be recognized in the input
1578 file format. The names should be separated by slashes (/). The
1579 <it/type/ is th recommended datatype of the tag. It should be one of
1580 the following:
1581 <itemize>
1582 <item>structured
1583 <item>string
1584 <item>numeric
1585 <item>bool
1586 <item>oid
1587 <item>generalizedtime
1588 <item>intunit
1589 <item>int
1590 <item>octetstring
1591 <item>null
1592 </itemize>
1593 </descrip>
1594
1595 The following is an excerpt from the TagsetG definition file.
1596
1597 <tscreen><verb>
1598 name tagsetg
1599 reference TagsetG
1600 type 2
1601
1602 tag     1       title           string
1603 tag     2       author          string
1604 tag     3       publicationPlace string
1605 tag     4       publicationDate string
1606 tag     5       documentId      string
1607 tag     6       abstract        string
1608 tag     7       name            string
1609 tag     8       date            generalizedtime
1610 tag     9       bodyOfDisplay   string
1611 tag     10      organization    string
1612 </verb></tscreen>
1613
1614 <sect2>The Variant Set (.var) Files<label id="variant-set">
1615
1616 <p>
1617 The variant set file is a straightforward representation of the
1618 variant set definitions associated with the protocol. At present, only
1619 the <it/Variant-1/ set is known.
1620
1621 These are the directives allowed in the file.
1622
1623 <descrip>
1624 <tag>name <it/symbolic-name/</tag> (m) This provides a shorthand name or
1625 description for the variant set. Mostly useful for diagnostic purposes.
1626
1627 <tag>reference <it/OID-name/</tag> (o) The reference name of the OID for
1628 the variant set, if one is required. The reference names can be found
1629 in the <bf/util/ module of <bf/YAZ/.
1630
1631 <tag>class <it/integer class-name/</tag> (m,r) Introduces a new
1632 class to the variant set.
1633
1634 <tag>type <it/integer type-name datatype/</tag> (m,r) Addes a
1635 new type to the current class (the one introduced by the most recent
1636 <bf/class/ directive). The type names belong to the same name space as
1637 the one used in the tag set definition file.
1638 </descrip>
1639
1640 The following is an excerpt from the file describing the variant set
1641 <it/Variant-1/.
1642
1643 <tscreen><verb>
1644 name variant-1
1645 reference Variant-1
1646
1647 class 1 variantId
1648
1649   type  1       variantId               octetstring
1650
1651 class 2 body
1652
1653   type  1       iana                    string
1654   type  2       z39.50                  string
1655   type  3       other                   string
1656 </verb></tscreen>
1657
1658 <sect2>The Element Set (.est) Files
1659
1660 <p>
1661 The element set specification files describe a selection of a subset
1662 of the elements of a database record. The element selection mechanism
1663 is equivalent to the one supplied by the <it/Espec-1/ syntax of the
1664 Z39.50 specification. In fact, the internal representation of an
1665 element set specification is identical to the <it/Espec-1/ structure,
1666 and we'll refer you to the description of that structure for most of
1667 the detailed semantics of the directives below.
1668
1669 <it>
1670 NOTE: Not all of the Espec-1 functionality has been implemented yet.
1671 The fields that are mentioned below all work as expected, unless
1672 otherwise is noted.
1673 </it>
1674
1675 The directives available in the element set file are as follows:
1676
1677 <descrip>
1678 <tag>defaultVariantSetId <it/OID-name/</tag> (o) If variants are used in
1679 the following, this should provide the name of the variantset used
1680 (it's not currently possible to specify a different set in the
1681 individual variant request). In almost all cases (certainly all
1682 profiles known to us), the name <tt/Variant-1/ should be given here.
1683
1684 <tag>defaultVariantRequest <it/variant-request/</tag> (o) This directive
1685 provides a default variant request for
1686 use when the individual element requests (see below) do not contain a
1687 variant request. Variant requests consist of a blank-separated list of
1688 variant components. A variant compont is a comma-separated,
1689 parenthesized triple of variant class, type, and value (the two former
1690 values being represented as integers). The value can currently only be
1691 entered as a string (this will change to depend on the definition of
1692 the variant in question). The special value (@) is interpreted as a
1693 null value, however.
1694
1695 <tag>simpleElement <it/path &lsqb;'variant' variant-request&rsqb;/</tag>
1696 (o,r) This corresponds to a simple element request in <it/Espec-1/. The
1697 path consists of a sequence of tag-selectors, where each of these can
1698 consist of either:
1699
1700 <itemize>
1701 <item>A simple tag, consisting of a comma-separated type-value pair in
1702 parenthesis, possibly followed by a colon (:) followed by an
1703 occurrences-specification (see below). The tag-value can be a number
1704 or a string. If the first character is an apostrophe ('), this forces
1705 the value to be interpreted as a string, even if it appears to be numerical.
1706
1707 <item>A WildThing, represented as a question mark (?), possibly
1708 followed by a colon (:) followed by an occurrences specification (see
1709 below).
1710
1711 <item>A WildPath, represented as an asterisk (*). Note that the last
1712 element of the path should not be a wildPath (wildpaths don't work in
1713 this version).
1714 </itemize>
1715
1716 The occurrences-specification can be either the string <tt/all/, the
1717 string <tt/last/, or an explicit value-range. The value-range is
1718 represented as an integer (the starting point), possibly followed by a
1719 plus (+) and a second integer (the number of elements, default being
1720 one).
1721
1722 The variant-request has the same syntax as the defaultVariantRequest
1723 above. Note that it may sometimes be useful to give an empty variant
1724 request, simply to disable the default for a specific set of fields
1725 (we aren't certain if this is proper <it/Espec-1/, but it works in
1726 this implementation).
1727 </descrip>
1728
1729 The following is an example of an element specification belonging to
1730 the GILS profile.
1731
1732 <tscreen><verb>
1733 simpleelement (1,10)
1734 simpleelement (1,12)
1735 simpleelement (2,1)
1736 simpleelement (1,14)
1737 simpleelement (4,1)
1738 simpleelement (4,52)
1739 </verb></tscreen>
1740
1741 <sect2>The Schema Mapping (.map) Files<label id="schema-mapping">
1742
1743 <p>
1744 Sometimes, the client might want to receive a database record in
1745 a schema that differs from the native schema of the record. For
1746 instance, a client might only know how to process WAIS records, while
1747 the database record is represented in a more specific schema, such as
1748 GILS. In this module, a mapping of data to one of the MARC formats is
1749 also thought of as a schema mapping (mapping the elements of the
1750 record into fields consistent with the given MARC specification, prior
1751 to actually converting the data to the ISO2709). This use of the
1752 object identifier for USMARC as a schema identifier represents an
1753 overloading of the OID which might not be entirely proper. However,
1754 it represents the dual role of schema and record syntax which
1755 is assumed by the MARC family in Z39.50.
1756
1757 <it>
1758 NOTE: The schema-mapping functions are so far limited to a
1759 straightforward mapping of elements. This should be extended with
1760 mechanisms for conversions of the element contents, and conditional
1761 mappings of elements based on the record contents.
1762 </it>
1763
1764 These are the directives of the schema mapping file format:
1765
1766 <descrip>
1767 <tag>targetName <it/name/</tag> (m) A symbolic name for the target schema
1768 of the table. Useful mostly for diagnostic purposes.
1769
1770 <tag>targetRef <it/OID-name/</tag> (m) An OID name for the target schema.
1771 This is used, for instance, by a server receiving a request to present
1772 a record in a different schema from the native one. The name, again,
1773 is found in the <bf/oid/ module of <bf/YAZ/.
1774
1775 <tag>map <it/element-name target-path/</tag> (o,r) Adds
1776 an element mapping rule to the table.
1777 </descrip>
1778
1779 <sect2>The MARC (ISO2709) Representation (.mar) Files
1780
1781 <p>
1782 This file provides rules for representing a record in the ISO2709
1783 format. The rules pertain mostly to the values of the constant-length
1784 header of the record.
1785
1786 <it>NOTE: This will be described better. We're in the process of
1787 re-evaluating and most likely changing the way that MARC records are
1788 handled by the system.</it>
1789
1790 <sect1>Exchange Formats
1791
1792 <p>
1793 Converting records from the internal structure to en exchange format
1794 is largely an automatic process. Currently, the following exchange
1795 formats are supported:
1796
1797 <itemize>
1798 <item>GRS-1. The internal representation is based on GRS-1, so the
1799 conversion here is straightforward. The system will create
1800 applied variant and supported variant lists as required, if a record
1801 contains variant information.
1802
1803 <item>SUTRS. Again, the mapping is fairly straighforward. Indentation
1804 is used to show the hierarchical structure of the record.
1805
1806 <item>ISO2709-based formats (USMARC, etc.). Only records with a
1807 two-level structure (corresponding to fields and subfields) can be
1808 directly mapped to ISO2709. For records with a different structuring
1809 (eg., GILS), the representation in a structure like USMARC involves a
1810 schema-mapping (see section <ref id="schema-mapping" name="Schema
1811 Mapping">), to an &dquot;implied&dquot; USMARC schema (implied,
1812 because there is no formal schema which specifies the use of the
1813 USMARC fields outside of ISO2709). The resultant, two-level record is
1814 then mapped directly from the internal representation to ISO2709. See
1815 the GILS schema definition files for a detailed example of this
1816 approach.
1817
1818 <item>Explain. This representation is only available for records
1819 belonging to the Explain schema.
1820
1821 </itemize>
1822
1823 <sect>License
1824
1825 <p>
1826 Copyright &copy; 1995, Index Data.
1827
1828 All rights reserved.
1829
1830 Use and redistribution in source or binary form, with or without
1831 modification, of any or all of this software and documentation is
1832 permitted, provided that the following conditions are met:
1833
1834 1. This copyright and permission notice appear with all copies of the
1835 software and its documentation. Notices of copyright or attribution
1836 which appear at the beginning of any file must remain unchanged.
1837
1838 2. The names of Index Data or the individual authors may not be used to
1839 endorse or promote products derived from this software without specific
1840 prior written permission.
1841
1842 3. Source code or binary versions of this software and its
1843 documentation may be used freely in not-for-profit applications. For
1844 profit applications - such as providing for-pay database services,
1845 marketing a product based in whole or in part on this software or its
1846 documentation, or generally distributing this software or its
1847 documentation under a different license - requires a commercial
1848 license from Index Data. The software may be installed and used for
1849 evaluation purposes in conjunction with a commercial application for a
1850 trial period of no more than 60 days.
1851
1852 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
1853 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
1854 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1855 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
1856 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
1857 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
1858 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
1859 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
1860 OF THIS SOFTWARE.
1861
1862 <sect>About Index Data and the Zebra Server
1863
1864 <p>
1865 Index Data is a consulting and software-development enterprise that
1866 specialises in library and information management systems. Our
1867 interests and expertise span a broad range of related fields, and one
1868 of our primary, long-term objectives is the development of a powerful
1869 information management
1870 system with open network interfaces and hypermedia capabilities.
1871
1872 We make this software available free of charge for not-for-profit
1873 purposes, as a service to the networking community, and to further
1874 the development and use of quality software for open network
1875 communication.
1876
1877 If you like this software, and would like to use all or part of it in
1878 a commercial product, or to provide a commercial database service,
1879 please contact us to discuss the details. We'll be happy to answer
1880 questions about the software, and about our services in general. If
1881 you have specific requirements to the software, we'll be glad to offer
1882 our advice - and if you need to adapt the software to a special
1883 purpose, our consulting services and expert knowledge of the software
1884 is available to you at favorable rates.
1885
1886 <tscreen>
1887 Index Data&nl
1888 Ryesgade 3&nl
1889 DK-2200 K&oslash;benhavn N&nl
1890 </tscreen>
1891
1892 <p>
1893 <tscreen><verb>
1894 Phone: +45 3536 3672
1895 Fax  : +45 3536 0449
1896 Email: info@index.ping.dk
1897 </verb></tscreen>
1898
1899 The <it>Random House College Dictionary</it>, 1975 edition
1900 offers this definition of the 
1901 word &dquot;Zebra&dquot;:
1902
1903 <it>
1904 Zebra, n., any of several horselike, African mammals of the genus Equus,
1905 having a characteristic pattern of black or dark-brown stripes on
1906 a whitish background.
1907 </it>
1908
1909 </article>