2 <!-- $Id: server.xml,v 1.4 2002-10-11 09:05:09 adam Exp $ -->
3 <title>The Z39.50 Server</title>
6 <title>Running the Z39.50 Server (zebrasrv)</title>
9 FIXME - We need to be consistent here, zebraidx had the options at the
10 end, and lots of explaining text before them. Same for zebrasvr! -H
11 FIXME - At least we need a small intro, what is zebrasvr, and how it
12 can be run (inetd, nt service, stand-alone program, daemon...) -H
16 <emphasis remap="bf">Syntax</emphasis>
19 zebrasrv [options] [listener-address ...]
25 <emphasis remap="bf">Options</emphasis>
29 <term>-a <replaceable>APDU file</replaceable></term>
32 Specify a file for dumping PDUs (for diagnostic purposes).
33 The special name "-" sends output to <literal>stderr</literal>.
38 <term>-c <replaceable>config-file</replaceable></term>
41 Read configuration information from
42 <replaceable>config-file</replaceable>.
43 The default configuration is <literal>./zebra.cfg</literal>.
51 Don't fork on connection requests. This can be useful for
52 symbolic-level debugging. The server can only accept a single
53 connection in this mode.
61 Use the Z39.50 protocol. Currently the only protocol supported.
62 The option is retained for historical reasons, and for future
68 <term>-l <replaceable>logfile</replaceable></term>
71 Specify an output file for the diagnostic messages.
72 The default is to write this information to <literal>stderr</literal>.
77 <term>-v <replaceable>log-level</replaceable></term>
80 The log level. Use a comma-separated list of members of the set
81 {fatal,debug,warn,log,all,none}.
86 <term>-u <replaceable>username</replaceable></term>
89 Set user ID. Sets the real UID of the server process to that of the
90 given <replaceable>username</replaceable>.
91 It's useful if you aren't comfortable with having the
92 server run as root, but you need to start it as such to bind a
98 <term>-w <replaceable>working-directory</replaceable></term>
101 Change working directory.
109 Run under the Internet superserver, <literal>inetd</literal>.
110 Make sure you use the logfile option <literal>-l</literal> in
111 conjunction with this mode and specify the <literal>-l</literal>
112 option before any other options.
117 <term>-t <replaceable>timeout</replaceable></term>
120 Set the idle session timeout (default 60 minutes).
125 <term>-k <replaceable>kilobytes</replaceable></term>
128 Set the (approximate) maximum size of
129 present response messages. Default is 1024 KB (1 MB).
137 A <replaceable>listener-address</replaceable> consists of an optional
138 transport mode followed by a colon (:) followed by a listener address.
139 The transport mode is either <literal>ssl</literal> or
140 <literal>tcp</literal> (default).
144 For TCP, an address has the form
150 hostname | IP-number [: portnumber]
156 The port number defaults to 210 (standard Z39.50 port) for
157 privileged users (root), and 9999 for normal users.
169 ssl:secure.lib.com:3000
175 In both cases, the special hostname "@" is mapped to
176 the address INADDR_ANY, which causes the server to listen on any local
177 interface. To start the server listening on the registered port for
178 Z39.50, and to drop root privileges once the ports are bound, execute
179 the server like this (from a root shell):
191 You can replace <literal>daemon</literal> with another user, eg.
192 your own account, or a dedicated IR server account.
196 The default behavior for <literal>zebrasrv</literal> is to establish
197 a single TCP/IP listener, for the Z39.50 protocol, on port 9999.
202 <sect1 id="protocol-support">
203 <title>Z39.50 Protocol Support and Behavior</title>
206 <title>Initialization</title>
209 During initialization, the server will negotiate to version 3 of the
210 Z39.50 protocol, and the option bits for Search, Present, Scan,
211 NamedResultSets, and concurrentOperations will be set, if requested by
212 the client. The maximum PDU size is negotiated down to a maximum of
219 <title>Search</title>
222 FIXME - Need to explain the string tag stuff before people get bogged
223 down with all these attribute numbers. Perhaps in its own
228 The supported query type are 1 and 101. All operators are currently
229 supported with the restriction that only proximity units of type "word"
230 are supported for the proximity operator.
231 Queries can be arbitrarily complex.
232 Named result sets are supported, and result sets can be used as operands
234 Searches may span multiple databases.
238 The server has full support for piggy-backed present requests (see
239 also the following section).
243 <emphasis>Use</emphasis> attributes are interpreted according to the
244 attribute sets which have been loaded in the
245 <literal>zebra.cfg</literal> file, and are matched against specific
246 fields as specified in the <literal>.abs</literal> file which
247 describes the profile of the records which have been loaded.
248 If no Use attribute is provided, a default of Bib-1 Any is assumed.
252 If a <emphasis>Structure</emphasis> attribute of
253 <emphasis>Phrase</emphasis> is used in conjunction with a
254 <emphasis>Completeness</emphasis> attribute of
255 <emphasis>Complete (Sub)field</emphasis>, the term is matched
256 against the contents of the phrase (long word) register, if one
257 exists for the given <emphasis>Use</emphasis> attribute.
258 A phrase register is created for those fields in the
259 <literal>.abs</literal> file that contains a
260 <literal>p</literal>-specifier.
264 If <emphasis>Structure</emphasis>=<emphasis>Phrase</emphasis> is
265 used in conjunction with <emphasis>Incomplete Field</emphasis> - the
266 default value for <emphasis>Completeness</emphasis>, the
267 search is directed against the normal word registers, but if the term
268 contains multiple words, the term will only match if all of the words
269 are found immediately adjacent, and in the given order.
270 The word search is performed on those fields that are indexed as
271 type <literal>w</literal> in the <literal>.abs</literal> file.
275 If the <emphasis>Structure</emphasis> attribute is
276 <emphasis>Word List</emphasis>,
277 <emphasis>Free-form Text</emphasis>, or
278 <emphasis>Document Text</emphasis>, the term is treated as a
279 natural-language, relevance-ranked query.
280 This search type uses the word register, i.e. those fields
281 that are indexed as type <literal>w</literal> in the
282 <literal>.abs</literal> file.
286 If the <emphasis>Structure</emphasis> attribute is
287 <emphasis>Numeric String</emphasis> the term is treated as an integer.
288 The search is performed on those fields that are indexed
289 as type <literal>n</literal> in the <literal>.abs</literal> file.
293 If the <emphasis>Structure</emphasis> attribute is
294 <emphasis>URx</emphasis> the term is treated as a URX (URL) entity.
295 The search is performed on those fields that are indexed as type
296 <literal>u</literal> in the <literal>.abs</literal> file.
300 If the <emphasis>Structure</emphasis> attribute is
301 <emphasis>Local Number</emphasis> the term is treated as
302 native Zebra Record Identifier.
306 If the <emphasis>Relation</emphasis> attribute is
307 <emphasis>Equals</emphasis> (default), the term is matched
308 in a normal fashion (modulo truncation and processing of
309 individual words, if required).
310 If <emphasis>Relation</emphasis> is <emphasis>Less Than</emphasis>,
311 <emphasis>Less Than or Equal</emphasis>,
312 <emphasis>Greater than</emphasis>, or <emphasis>Greater than or
313 Equal</emphasis>, the term is assumed to be numerical, and a
314 standard regular expression is constructed to match the given
316 If <emphasis>Relation</emphasis> is <emphasis>Relevance</emphasis>,
317 the standard natural-language query processor is invoked.
321 For the <emphasis>Truncation</emphasis> attribute,
322 <emphasis>No Truncation</emphasis> is the default.
323 <emphasis>Left Truncation</emphasis> is not supported.
324 <emphasis>Process #</emphasis> is supported, as is
325 <emphasis>Regxp-1</emphasis>.
326 <emphasis>Regxp-2</emphasis> enables the fault-tolerant (fuzzy)
327 search. As a default, a single error (deletion, insertion,
328 replacement) is accepted when terms are matched against the register
333 <title>Regular expressions</title>
336 Each term in a query is interpreted as a regular expression if
337 the truncation value is either <emphasis>Regxp-1</emphasis> (102)
338 or <emphasis>Regxp-2</emphasis> (103).
339 Both query types follow the same syntax with the operands:
346 Matches the character <emphasis>x</emphasis>.
354 Matches any character.
359 <term><literal>[</literal>..<literal>]</literal></term>
362 Matches the set of characters specified;
363 such as <literal>[abc]</literal> or <literal>[a-c]</literal>.
375 Matches <emphasis>x</emphasis> zero or more times. Priority: high.
383 Matches <emphasis>x</emphasis> one or more times. Priority: high.
391 Matches <emphasis>x</emphasis> zero or once. Priority: high.
399 Matches <emphasis>x</emphasis>, then <emphasis>y</emphasis>.
405 <term>x|y</term>
408 Matches either <emphasis>x</emphasis> or <emphasis>y</emphasis>.
414 The order of evaluation may be changed by using parentheses.
418 If the first character of the <emphasis>Regxp-2</emphasis> query
419 is a plus character (<literal>+</literal>) it marks the
420 beginning of a section with non-standard specifiers.
421 The next plus character marks the end of the section.
422 Currently Zebra only supports one specifier, the error tolerance,
423 which consists one digit.
427 Since the plus operator is normally a suffix operator the addition to
428 the query syntax doesn't violate the syntax for standard regular
435 <title>Query examples</title>
438 Phrase search for <emphasis>information retrieval</emphasis> in
441 @attr 1=4 "information retrieval"
446 Ranked search for the same thing:
448 @attr 1=4 @attr 2=102 "Information retrieval"
453 Phrase search with a regular expression:
455 @attr 1=4 @attr 5=102 "informat.* retrieval"
460 Ranked search with a regular expression:
462 @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval"
467 In the GILS schema (<literal>gils.abs</literal>), the
468 west-bounding-coordinate is indexed as type <literal>n</literal>,
469 and is therefore searched by specifying
470 <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
471 To match all those records with west-bounding-coordinate greater
472 than -114 we use the following query:
474 @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
481 <title>Present</title>
483 The present facility is supported in a standard fashion. The requested
484 record syntax is matched against the ones supported by the profile of
485 each record retrieved. If no record syntax is given, SUTRS is the
486 default. The requested element set name, again, is matched against any
487 provided by the relevant record profiles.
493 The attribute combinations provided with the termListAndStartPoint are
494 processed in the same way as operands in a query (see above).
495 Currently, only the term and the globalOccurrences are returned with
496 the termInfo structure.
503 Z39.50 specifies three different types of sort criteria.
504 Of these Zebra supports the attribute specification type in which
505 case the use attribute specifies the "Sort register".
506 Sort registers are created for those fields that are of type "sort" in
507 the default.idx file.
508 The corresponding character mapping file in default.idx specifies the
509 ordinal of each character used in the actual sort.
513 Z39.50 allows the client to specify sorting on one or more input
514 result sets and one output result set.
515 Zebra supports sorting on one result set only which may or may not
516 be the same as the output result set.
522 If a Close PDU is received, the server will respond with a Close PDU
523 with reason=FINISHED, no matter which protocol version was negotiated
524 during initialization. If the protocol version is 3 or more, the
525 server will generate a Close PDU under certain circumstances,
526 including a session timeout (60 minutes by default), and certain kinds of
527 protocol errors. Once a Close PDU has been sent, the protocol
528 association is considered broken, and the transport connection will be
529 closed immediately upon receipt of further data, or following a short
535 <!-- Keep this comment at the end of the file
540 sgml-minimize-attributes:nil
541 sgml-always-quote-attributes:t
544 sgml-parent-document: "zebra.xml"
545 sgml-local-catalogs: nil
546 sgml-namecase-general:t