2 <!-- $Id: server.xml,v 1.1 2002-04-09 13:26:26 adam Exp $ -->
3 <title>The Z39.50 Server</title>
6 <title>Running the Z39.50 Server (zebrasrv)</title>
9 <emphasis remap="bf">Syntax</emphasis>
12 zebrasrv [options] [listener-address ...]
18 <emphasis remap="bf">Options</emphasis>
22 <term>-a <replaceable>APDU file</replaceable></term>
25 Specify a file for dumping PDUs (for diagnostic purposes).
26 The special name "-" sends output to <literal>stderr</literal>.
31 <term>-c <replaceable>config-file</replaceable></term>
34 Read configuration information from
35 <replaceable>config-file</replaceable>.
36 The default configuration is <literal>./zebra.cfg</literal>.
44 Don't fork on connection requests. This can be useful for
45 symbolic-level debugging. The server can only accept a single
46 connection in this mode.
54 Use the Z39.50 protocol (default). These two options complement
55 eachother. You can use both multiple times on the same command
56 line, between listener-specifications (see below). This way, you
57 can set up the server to listen for connections in both protocols
58 concurrently, on different local ports.
63 <term>-l <replaceable>logfile</replaceable></term>
66 Specify an output file for the diagnostic messages.
67 The default is to write this information to <literal>stderr</literal>.
72 <term>-v <replaceable>log-level</replaceable></term>
75 The log level. Use a comma-separated list of members of the set
76 {fatal,debug,warn,log,all,none}.
81 <term>-u <replaceable>username</replaceable></term>
84 Set user ID. Sets the real UID of the server process to that of the
85 given <replaceable>username</replaceable>.
86 It's useful if you aren't comfortable with having the
87 server run as root, but you need to start it as such to bind a
93 <term>-w <replaceable>working-directory</replaceable></term>
96 Change working directory.
104 Run under the Internet superserver, <literal>inetd</literal>.
105 Make sure you use the logfile option <literal>-l</literal> in
106 conjunction with this mode and specify the <literal>-l</literal>
107 option before any other options.
112 <term>-t <replaceable>timeout</replaceable></term>
115 Set the idle session timeout (default 60 minutes).
120 <term>-k <replaceable>kilobytes</replaceable></term>
123 Set the (approximate) maximum size of
124 present response messages. Default is 1024 Kb (1 Mb).
132 A <replaceable>listener-address</replaceable> consists of a transport
133 mode followed by a colon (:) followed by a listener address.
134 The transport mode is either <literal>ssl</literal> or
135 <literal>tcp</literal>.
139 For TCP, an address has the form
145 hostname | IP-number [: portnumber]
151 The port number defaults to 210 (standard Z39.50 port).
163 ssl:secure.lib.com:3000
169 In both cases, the special hostname "@" is mapped to
170 the address INADDR_ANY, which causes the server to listen on any local
171 interface. To start the server listening on the registered port for
172 Z39.50, and to drop root privileges once the ports are bound, execute
173 the server like this (from a root shell):
179 zebrasrv -u daemon tcp:@
185 You can replace <literal>daemon</literal> with another user, eg.
186 your own account, or a dedicated IR server account.
190 The default behavior for <literal>zebrasrv</literal> is to establish
191 a single TCP/IP listener, for the Z39.50 protocol, on port 9999.
196 <sect1 id="protocol-support">
197 <title>Z39.50 Protocol Support and Behavior</title>
200 <title>Initialization</title>
203 During initialization, the server will negotiate to version 3 of the
204 Z39.50 protocol, and the option bits for Search, Present, Scan,
205 NamedResultSets, and concurrentOperations will be set, if requested by
206 the client. The maximum PDU size is negotiated down to a maximum of
213 <title>Search</title>
216 The supported query type are 1 and 101. All operators are currently
217 supported with the restriction that only proximity units of type "word"
218 are supported for the proximity operator.
219 Queries can be arbitrarily complex.
220 Named result sets are supported, and result sets can be used as operands
222 Searches may span multiple databases.
226 The server has full support for piggy-backed present requests (see
227 also the following section).
231 <emphasis>Use</emphasis> attributes are interpreted according to the
232 attribute sets which have been loaded in the
233 <literal>zebra.cfg</literal> file, and are matched against specific
234 fields as specified in the <literal>.abs</literal> file which
235 describes the profile of the records which have been loaded.
236 If no Use attribute is provided, a default of Bib-1 Any is assumed.
240 If a <emphasis>Structure</emphasis> attribute of
241 <emphasis>Phrase</emphasis> is used in conjunction with a
242 <emphasis>Completeness</emphasis> attribute of
243 <emphasis>Complete (Sub)field</emphasis>, the term is matched
244 against the contents of the phrase (long word) register, if one
245 exists for the given <emphasis>Use</emphasis> attribute.
246 A phrase register is created for those fields in the
247 <literal>.abs</literal> file that contains a
248 <literal>p</literal>-specifier.
252 If <emphasis>Structure</emphasis>=<emphasis>Phrase</emphasis> is
253 used in conjunction with <emphasis>Incomplete Field</emphasis> - the
254 default value for <emphasis>Completeness</emphasis>, the
255 search is directed against the normal word registers, but if the term
256 contains multiple words, the term will only match if all of the words
257 are found immediately adjacent, and in the given order.
258 The word search is performed on those fields that are indexed as
259 type <literal>w</literal> in the <literal>.abs</literal> file.
263 If the <emphasis>Structure</emphasis> attribute is
264 <emphasis>Word List</emphasis>,
265 <emphasis>Free-form Text</emphasis>, or
266 <emphasis>Document Text</emphasis>, the term is treated as a
267 natural-language, relevance-ranked query.
268 This search type uses the word register, i.e. those fields
269 that are indexed as type <literal>w</literal> in the
270 <literal>.abs</literal> file.
274 If the <emphasis>Structure</emphasis> attribute is
275 <emphasis>Numeric String</emphasis> the term is treated as an integer.
276 The search is performed on those fields that are indexed
277 as type <literal>n</literal> in the <literal>.abs</literal> file.
281 If the <emphasis>Structure</emphasis> attribute is
282 <emphasis>URx</emphasis> the term is treated as a URX (URL) entity.
283 The search is performed on those fields that are indexed as type
284 <literal>u</literal> in the <literal>.abs</literal> file.
288 If the <emphasis>Structure</emphasis> attribute is
289 <emphasis>Local Number</emphasis> the term is treated as
290 native Zebra Record Identifier.
294 If the <emphasis>Relation</emphasis> attribute is
295 <emphasis>Equals</emphasis> (default), the term is matched
296 in a normal fashion (modulo truncation and processing of
297 individual words, if required).
298 If <emphasis>Relation</emphasis> is <emphasis>Less Than</emphasis>,
299 <emphasis>Less Than or Equal</emphasis>,
300 <emphasis>Greater than</emphasis>, or <emphasis>Greater than or
301 Equal</emphasis>, the term is assumed to be numerical, and a
302 standard regular expression is constructed to match the given
304 If <emphasis>Relation</emphasis> is <emphasis>Relevance</emphasis>,
305 the standard natural-language query processor is invoked.
309 For the <emphasis>Truncation</emphasis> attribute,
310 <emphasis>No Truncation</emphasis> is the default.
311 <emphasis>Left Truncation</emphasis> is not supported.
312 <emphasis>Process #</emphasis> is supported, as is
313 <emphasis>Regxp-1</emphasis>.
314 <emphasis>Regxp-2</emphasis> enables the fault-tolerant (fuzzy)
315 search. As a default, a single error (deletion, insertion,
316 replacement) is accepted when terms are matched against the register
321 <title>Regular expressions</title>
324 Each term in a query is interpreted as a regular expression if
325 the truncation value is either <emphasis>Regxp-1</emphasis> (102)
326 or <emphasis>Regxp-2</emphasis> (103).
327 Both query types follow the same syntax with the operands:
334 Matches the character <emphasis>x</emphasis>.
342 Matches any character.
347 <term><literal>[</literal>..<literal>]</literal></term>
350 Matches the set of characters specified;
351 such as <literal>[abc]</literal> or <literal>[a-c]</literal>.
363 Matches <emphasis>x</emphasis> zero or more times. Priority: high.
371 Matches <emphasis>x</emphasis> one or more times. Priority: high.
379 Matches <emphasis>x</emphasis> once or twice. Priority: high.
387 Matches <emphasis>x</emphasis>, then <emphasis>y</emphasis>.
393 <term>x|y</term>
396 Matches either <emphasis>x</emphasis> or <emphasis>y</emphasis>.
402 The order of evaluation may be changed by using parentheses.
406 If the first character of the <emphasis>Regxp-2</emphasis> query
407 is a plus character (<literal>+</literal>) it marks the
408 beginning of a section with non-standard specifiers.
409 The next plus character marks the end of the section.
410 Currently Zebra only supports one specifier, the error tolerance,
411 which consists one digit.
415 Since the plus operator is normally a suffix operator the addition to
416 the query syntax doesn't violate the syntax for standard regular
423 <title>Query examples</title>
426 Phrase search for <emphasis>information retrieval</emphasis> in
429 @attr 1=4 "information retrieval"
434 Ranked search for the same thing:
436 @attr 1=4 @attr 2=102 "Information retrieval"
441 Phrase search with a regular expression:
443 @attr 1=4 @attr 5=102 "informat.* retrieval"
448 Ranked search with a regular expression:
450 @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval"
455 In the GILS schema (<literal>gils.abs</literal>), the
456 west-bounding-coordinate is indexed as type <literal>n</literal>,
457 and is therefore searched by specifying
458 <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
459 To match all those records with west-bounding-coordinate greater
460 than -114 we use the following query:
462 @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
469 <title>Present</title>
471 The present facility is supported in a standard fashion. The requested
472 record syntax is matched against the ones supported by the profile of
473 each record retrieved. If no record syntax is given, SUTRS is the
474 default. The requested element set name, again, is matched against any
475 provided by the relevant record profiles.
481 The attribute combinations provided with the termListAndStartPoint are
482 processed in the same way as operands in a query (see above).
483 Currently, only the term and the globalOccurrences are returned with
484 the termInfo structure.
491 Z39.50 specifies three diffent types of sort criterias.
492 Of these Zebra supports the attribute specification type in which
493 case the use attribute specifies the "Sort register".
494 Sort registers are created for those fields that are of type "sort" in
495 the default.idx file.
496 The corresponding character mapping file in default.idx specifies the
497 ordinal of each character used in the actual sort.
501 Z39.50 allows the client to specify sorting on one or more input
502 result sets and one output result set.
503 Zebra supports sorting on one result set only which may or may not
504 be the same as the output result set.
510 If a Close PDU is received, the server will respond with a Close PDU
511 with reason=FINISHED, no matter which protocol version was negotiated
512 during initialization. If the protocol version is 3 or more, the
513 server will generate a Close PDU under certain circumstances,
514 including a session timeout (60 minutes by default), and certain kinds of
515 protocol errors. Once a Close PDU has been sent, the protocol
516 association is considered broken, and the transport connection will be
517 closed immediately upon receipt of further data, or following a short
523 <!-- Keep this comment at the end of the file
528 sgml-minimize-attributes:nil
529 sgml-always-quote-attributes:t
532 sgml-parent-document: "zebra.xml"
533 sgml-local-catalogs: nil
534 sgml-namecase-general:t