Add zebrasrv.pid
[idzebra-moved-to-github.git] / doc / gils.sgml
1 <!doctype linuxdoc system>
2
3 <!--
4   $Id: gils.sgml,v 1.5 1997-12-12 06:37:53 adam Exp $
5 -->
6
7 <article>
8 <title>Serving GILS Records with Zebra
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.5 $
11 <abstract>
12 This document explains how to set up a simple database of Government
13 Information Locator Records using the Zebra retrieval engine and
14 Z39.50 server (version 1.0a6 or later).
15 </abstract>
16
17 <sect>Introduction
18
19 <p>
20 Zebra is a powerful and versatile information management system
21 which allows you to construct arbitrarily complex record structures
22 and manage
23 efficient, robust databases.
24
25 Since the internal data modeling tools of Zebra are based on the
26 Z39.50-1995 standard, the system is well-suited to support a complex
27 database profile such as the one specified by the GILS profile.
28 Because GILS is expected by many to play an important role in the
29 evolving, global information society, and because the GILS profile has
30 proven useful to a number of different applications outside of its
31 dedicated domain, the public distribution of Zebra includes a
32 configuration set-up which makes it a simple matter to establish a new
33 GILS database.
34
35 This document, which is a supplement to the general documentation set
36 for Zebra, explains in simple terms how you can easily set up your own
37 GILS-compliant database service.
38
39 <sect>Retrieving and Unpacking Zebra
40
41 <p>
42 The first step is to download the software. If you are using a WWW
43 browser, you can point it at the Zebra distribution archive at
44 <tt>&lt;<htmlurl url="http://www.indexdata.dk/zebra.html"
45 name="http://www.indexdata.dk/zebra.html">&gt;</tt>, and follow the link named
46 <it/Download the latest version of the software (xxx)/, where <it/xxx/
47 is the current version of Zebra.
48
49 If you use an FTP client, you can use normal, anonymous FTP. Connect
50 to the host <tt/ftp.indexdata.dk/, log in as <tt/ftp/, and give your
51 Email-address as the password. Then type <tt>cd index/yaz</tt>, and
52 use the <tt/dir/ command to locate the current version of Zebra. The
53 file will be named <tt/zebra-xxx/, where <tt/xxx/ is the current
54 version of the software. Remember to use the <tt/bin/ command before
55 using <tt/get/ to download the software.
56
57 Once the distribution archive has been dowloaded, it must be
58 decompressed. To do this, use the command <tt/gunzip/ command (if your
59 system doesn't have the <tt/gunzip/ program, you will need to acquire
60 this separately). Finally, use the command <tt>tar xvf
61 &lt;file&gt;</tt> to unpack the archive.
62
63 If you downloaded the source version of the software (this is the only
64 option today, although we expect to release binary versions for Linux,
65 SunOS, and Digital Unix shortly), you will have to compile Zebra
66 before you can use it.
67
68 On many of the major version of the Unix operating system, compiling
69 Zebra is a simple matter of typing <tt/make/ in the top-level
70 distribution directory (this is the directory that was created when
71 you executed <tt/tar/). Normally, Zebra compiles cleanly at least on
72 Linux, Digital Unix (DEC OSF/1), and IBM AIX. On certain platforms
73 (such as SunOS), you will need to edit the top-level <tt/Makefile/ to
74 set the <tt/ELIBS/ variable to include the Berkeley Socket
75 Libraries. On other Unix platforms, you <it/may/ need to modify
76 Makefiles or header files, but in general, we have found Zebra to be
77 easily portable across modern Unix-versions. You do need an ANSI-C
78 compliant compiler (you'll see a long list of Syntax-errors during the
79 compile if your default compiler is not ANSI C), but again, this is
80 standard on most modern Unix-systems. If you don't have one, the
81 freely available GNU C compiler is available for many systems.
82
83 <sect>The First GILS Database
84
85 <p>
86 Having successfully acquired the software, it's time to try it out.
87 The directory <tt/test/ under the main distribution directory contains
88 a small sample database of GILS records.
89
90 <it>NOTE: The records included in the distribution are part of a
91 sample set provided by the US Geological Survey, as a service to GILS
92 implementors. They are included for testing and demonstrating the
93 software, and neither the USGS or Index Data nor anyone else should be
94 held responsible for their contents.</it>
95
96 If you <tt/cd/ to the <tt/test/ directory, the first thing to notice
97 is the file <tt/zebra.cfg/. There has to be a file like this present
98 whenever you run Zebra - it establishes various settings and defaults,
99 and we'll return to its contents below (a detailed
100 description is found in the general Zebra documentation file).
101
102 The subdirectory <tt/records/ contains the sample records. We'll get
103 back to them, too.
104
105 The first order of business is to index the sample records, and create
106 the access files required by the Z39.50 server. To do this, position
107 yourself in the <tt/test/ directory, and type the command
108
109 <tscreen><verb>
110 $ ../index/zebraidx update records
111 </verb></tscreen>
112
113 The indexing program will respond with a stream of control
114 information, and when it completes, the database is ready. To start
115 the Z39.50 server, type the command <tt>../index/zebrasrv</tt>.
116
117 Assuming that nothing unfortunate happened, you are now running a
118 GILS-compliant Z39.50 server on the port 9999 on your local machine
119 (to learn how to run the server at a different port, and redirect the
120 diagnostic output to a file, consult the section on <it/Running
121 zebrasrv/ in the general documentation).
122 The database containing the sample records is named <tt/Default/.
123
124 To test the server, you can use any compatible Z39.50 client. You can
125 also use the simple demonstration client which is included with Zebra
126 itself. To do this, start a new session on your machine (or put the
127 server in the background). Change to the directory <tt>yaz/client</tt>
128 under the main Zebra distribution directory. Now execute the command
129
130 <tscreen><verb>
131 $ ./client tcp:localhost:9999
132 </verb></tscreen>
133
134 If all went well, the client will tell you that it has established an
135 association with your test server. To test it, try out these commands:
136
137 <tscreen><verb>
138 Z> find surficial
139 Z> show 1
140 </verb></tscreen>
141
142 The default retrieval syntax for the client is USMARC. To try other
143 formats for the same record, try:
144
145 <tscreen><verb>
146 Z>format sutrs
147 Z>show 1
148 Z>format grs-1
149 Z>show 1
150 Z>elements B
151 Z>show 1
152 </verb></tscreen>
153
154 You can learn more about the sample client by reading the <tt/README/
155 file in the <tt/yaz/ directory.
156
157 <sect>The Records
158
159 <p>
160 The GILS profile is only concerned with the communication that takes
161 place between two compliant systems. It doesn't mandate how the client
162 application should behave, and it doesn't tell you how you should
163 maintain and process data at the server side. Specifically, while the
164 profile specifies a number of different exchange format for retrieval
165 records.
166
167 For the purposes of this discussion, we will be using a simple,
168 SGML-like representation of the GILS record structure. There is
169 nothing magical or sacrosanct about this format, but it is easy to
170 read and write, and because of its semblance of SGML and HTML, it is
171 familiar to many people. If you would like to use a different, local
172 representation for your GILS records, you can read the general Zebra
173 documentation to learn how to establish a custom input filter for your
174 particular record format.
175
176 In the SGML-like syntax, each record should begin with the tag
177 <tt/&lt;gils&gt;/. This selects the GILS profile, and provides context
178 for the content tags which follow. Similarly, each record should
179 finish with the end-tag <tt/&etago;gils&gt;/.
180
181 The body of the record is made up by a sequence of tagged elements,
182 reflecting the <it/abstract record syntax/ of the GILS profile. Some
183 of these elements contain simple data, or text, while others contain
184 more tagged elements - these are complex, or constructed, data
185 elements. The tag names generally correspond to the tag names provided
186 in the GILS profile. Capitalization is ignored in tag names, as are
187 dashes (-). Hence, <tt/local-subject-index/ is equivalent to
188 <tt/LocalSubjectIndex/ which is the same as <tt/LOCALSUBJECTINDEX/.
189
190 It is useful to look at the records in the <tt>test/records</tt> as
191 examples of how SGML-formatted GILS record can look. Note that
192 whitespace is generally ignored, so you can choose whatever layout of
193 your records that suits you best.
194
195 <sect>The Zebra Configuration File
196
197 <p>
198 As mentioned, the Zebra indexer and server always look for the file
199 <tt/zebra.cfg/ in their current working directory (unless they are
200 told to look for it elsewhere with the <tt/-c/ option). The example
201 file in the <tt/test/ directory represents all but the bare minimum
202 for such a file. We find the
203 following to be a powerful setup for a GILS-like database (everything
204 preceded by (&num;) is ignored by the software):
205
206 <tscreen><verb>
207 #
208 # Sample configuration file for GILS database
209 #
210
211 # Where are the configuration files located?
212 profilePath: /usr/local/lib/zebra
213
214 # Load attribute sets for searching
215 attset bib1.att
216 attset gils.att
217
218 # Records are identified by their path in the file system
219 recordId: file
220
221 # Store information about records to allow deletion and updating
222 storeKeys: 1
223
224 # Records are structured
225 recordType: grs
226
227 # Where to store the indexes
228 register: /datadisk/index:500M
229
230 # Where to store temporary data while merging with register
231 shadow: /datadisk/shadow:500M
232 </verb></tscreen>
233
234 If you like, you can paste this file straight into a <tt/zebra.cfg/
235 file ready for your own use (with a bit of editing of the pathnames).
236 In the following, we'll explain the individual settings. For the full
237 story on the <tt/zebra.cfg/ file and the configuration options of
238 Zebra, you should read the general documentation.
239
240 <descrip>
241
242 <tag/profilePath/ This field tells Zebra where to look for the
243 configuration files. In the distribution, these files are located in
244 the <tt/tab/ directory, but you may wish to put them someplace else
245 for convenience. If necessary, you can provide multiple directory
246 paths, separated by (:).
247
248 <tag/attset/ This field tells the Zebra server which attribute sets it
249 should support for searching. You could get by with just loading the
250 GILS set, but if you load BIB-1 as well, Zebra will support both sets
251 for those GILS attributes that are inherited from BIB-1.
252
253 <tag/recordId/ The <tt/recordId: file/ setting tells Zebra that
254 individual records should be identified by the physical files in which
255 they are located. In this mode, your database will always (after an
256 update operation) reflect the contents of the directory (or
257 directories).
258
259 <tag/storeKeys/ This setting tells Zebra to store additional
260 information about each record, to facilitate updating. In combination
261 with the <tt/recordId: file/ setting, this is a very convenient
262 maintenance option. If you maintain your records as individual files
263 in a directory tree, you have only to run <tt/zebraidx/ with the
264 top-level directory as an argument. If new files are added, they are
265 entered into the database. If they are modified, the indexes are
266 changed accordingly, and if they are deleted from the filesystem (or
267 renamed), the indexes are also updated correctly, the next time you
268 run <tt/zebraidx/.
269
270 <tag/recordType/ This setting selects the type of processing which is
271 to take place when a record is accessed by the indexer or the Z39.50
272 server. GRS stands for <it/Generic Record Syntax/, and signals that
273 the records are structured.
274
275 <tag/register/ In the first test above, you may have noticed that the
276 <tt/zebraidx/ created a number of files in the working directory. Some
277 of these files, which contain the indexing information for the
278 database, can grow quite large, and it is sometimes useful to place
279 them in a separate directory or file system. You should provide the
280 path of the directory followed by a colon (:), followed by the maximum
281 amounts of megabytes (M) or kilobytes (K) of disk space that Zebra is
282 allowed to use in the given directory. If you specify more than one
283 directory:size combination <it/on the same line/, Zebra will fill up
284 each directory from left to right. This feature is essential if your
285 database is so large that the registers cannot fit into a single
286 partition of your disk.
287
288 <tag/shadow/ The format of this setting is the same as for the one
289 above. If you provide one or more directory for the &dquot;shadow
290 system&dquot;, you enable the safe updating system of the Zebra
291 indexer. When changes to the records are merged into the register
292 files, the files are not changed immediately. Instead, the changes are
293 written into separate files, or &dquot;shadow files&dquot;. At the end
294 of the merging process, or in a separate operation, the changes are
295 &dquot;committed&dquot;, and written into the register files
296 themselves. This final step is carried out by the command <tt/zebraidx
297 commit/ - the <tt/commit/ directive can also be given on the same
298 command line as the <tt/update/ directive - at the end of the command
299 line. The shadow file system can consume a lot of disk space -
300 particularly in a large update operation which involves almost all of
301 the index, but the benefits are substantial. If the system crashes
302 during an update procedure, or the process is otherwise interrupted,
303 the registers are left in an unknown state, and are effectively
304 rendered useless - this can be unfortunate if the index is very large,
305 but the use of the shadow system greatly reduces the risk of an index
306 being damaged in this way. Further, when the shadow system is enabled,
307 your clients may access the Zebra server without interruption
308 throughout the update and commit procedures - Zebra will ensure that
309 the parts of the register accessed by the server are always
310 consistent.
311
312 </descrip>
313
314 <sect>Creating Your Own Database
315
316 <p>
317 Whenever we create a new database with Zebra, we find it useful to
318 first set up a new, empty directory. This directory will contain the
319 configuration file, the lock files maintained by Zebra (unless you
320 specify a different location for these), and any logs of updates and
321 server runs that you may wish to keep around. The first thing to do is
322 set up the <tt/zebra.cfg/ file for your database. You can copy the one
323 from the <tt/test/ directory, or you can create a new one using the
324 example settings described in the previous section. Once you get your
325 server up and running, you may want to read the description of the
326 <tt/zebra.cfg/ file in the general documentation, to set up additional
327 defaults for database names, etc.
328
329 If you copy one of these files, you should be careful to update the
330 pathnames to reflect the setup of your own database. In particular, if
331 you want to specify one or more directories for the register files
332 and/or the shadow files, you should make sure that these directories
333 exist and are accessible to the user ID which will run the Zebra
334 processes.
335
336 You need to make sure that your GILS records are available, too. For
337 small to medium-sized (say, less than 100,000 records) databases, it
338 is sometimes preferable to maintain the records as individual files
339 somewhere in the file system. Zebra will, by default, access these
340 files directly whenever the user requests to see a specific record.
341 However, you can set up Zebra to maintain the database records in
342 other ways, too. Consult the general documentation for details.
343
344 Finally, you need to run <tt/zebraidx/ to create the index files, and
345 start up the server, <tt/zebrasrv/ (the server can be run from the
346 <tt/inetd/ if required), and you are in business.
347
348 To access the data, you can use a dedicated Z39.50 client, or you can
349 set up a WWW/Z39.50 gateway to allow common WWW browsers to search
350 your data. CNIDR's
351 Isite
352 package includes a good, free gateway that you can experiment with.
353
354 </article>