doc/server.xml

   1 <chapter id="server">
   2  <!-- $Id: server.xml,v 1.2 2002-04-09 19:20:23 adam Exp $ -->
   3  <title>The Z39.50 Server</title>
   4
   5  <sect1 id="zebrasrv">
   6   <title>Running the Z39.50 Server (zebrasrv)</title>
   7
   8   <para>
   9    <emphasis remap="bf">Syntax</emphasis>
  10
  11    <screen>
  12     zebrasrv &lsqb;options&rsqb; &lsqb;listener-address ...&rsqb;
  13    </screen>
  14
  15   </para>
  16
  17   <para>
  18    <emphasis remap="bf">Options</emphasis>
  19    <variablelist>
  20
  21     <varlistentry>
  22      <term>-a <replaceable>APDU file</replaceable></term>
  23      <listitem>
  24       <para>
  25        Specify a file for dumping PDUs (for diagnostic purposes).
  26        The special name "-" sends output to <literal>stderr</literal>.
  27       </para>
  28      </listitem>
  29     </varlistentry>
  30     <varlistentry>
  31      <term>-c <replaceable>config-file</replaceable></term>
  32      <listitem>
  33       <para>
  34        Read configuration information from
  35        <replaceable>config-file</replaceable>.
  36        The default configuration is <literal>./zebra.cfg</literal>.
  37       </para>
  38      </listitem>
  39     </varlistentry>
  40     <varlistentry>
  41      <term>-S</term>
  42      <listitem>
  43       <para>
  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.
  47       </para>
  48      </listitem>
  49     </varlistentry>
  50     <varlistentry>
  51      <term>-z</term>
  52      <listitem>
  53       <para>
  54        Use the Z39.50 protocol (default). These two options complement
  55        each other. 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.
  59       </para>
  60      </listitem>
  61     </varlistentry>
  62     <varlistentry>
  63      <term>-l <replaceable>logfile</replaceable></term>
  64      <listitem>
  65       <para>
  66        Specify an output file for the diagnostic messages.
  67        The default is to write this information to <literal>stderr</literal>.
  68       </para>
  69      </listitem>
  70     </varlistentry>
  71     <varlistentry>
  72      <term>-v <replaceable>log-level</replaceable></term>
  73      <listitem>
  74       <para>
  75        The log level. Use a comma-separated list of members of the set
  76        &lcub;fatal,debug,warn,log,all,none&rcub;.
  77       </para>
  78      </listitem>
  79     </varlistentry>
  80     <varlistentry>
  81      <term>-u <replaceable>username</replaceable></term>
  82      <listitem>
  83       <para>
  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
  88        privileged port.
  89       </para>
  90      </listitem>
  91     </varlistentry>
  92     <varlistentry>
  93      <term>-w <replaceable>working-directory</replaceable></term>
  94      <listitem>
  95       <para>
  96        Change working directory.
  97       </para>
  98      </listitem>
  99     </varlistentry>
 100     <varlistentry>
 101      <term>-i</term>
 102      <listitem>
 103       <para>
 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.
 108       </para>
 109      </listitem>
 110     </varlistentry>
 111     <varlistentry>
 112      <term>-t <replaceable>timeout</replaceable></term>
 113      <listitem>
 114       <para>
 115        Set the idle session timeout (default 60 minutes).
 116       </para>
 117      </listitem>
 118     </varlistentry>
 119     <varlistentry>
 120      <term>-k <replaceable>kilobytes</replaceable></term>
 121      <listitem>
 122       <para>
 123        Set the (approximate) maximum size of
 124        present response messages. Default is 1024 KB (1 MB).
 125       </para>
 126      </listitem>
 127     </varlistentry>
 128    </variablelist>
 129   </para>
 130
 131   <para>
 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>.
 136   </para>
 137
 138   <para>
 139    For TCP, an address has the form
 140   </para>
 141
 142   <para>
 143
 144    <screen>
 145     hostname | IP-number &lsqb;: portnumber&rsqb;
 146    </screen>
 147
 148   </para>
 149
 150   <para>
 151    The port number defaults to 210 (standard Z39.50 port).
 152   </para>
 153
 154   <para>
 155    Examples
 156   </para>
 157
 158   <para>
 159
 160    <screen>
 161     tcp:dranet.dra.com
 162
 163     ssl:secure.lib.com:3000
 164    </screen>
 165
 166   </para>
 167
 168   <para>
 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):
 174   </para>
 175
 176   <para>
 177
 178    <screen>
 179     zebrasrv -u daemon tcp:@
 180    </screen>
 181
 182   </para>
 183
 184   <para>
 185    You can replace <literal>daemon</literal> with another user, eg.
 186    your own account, or a dedicated IR server account.
 187   </para>
 188
 189   <para>
 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.
 192   </para>
 193
 194  </sect1>
 195
 196  <sect1 id="protocol-support">
 197   <title>Z39.50 Protocol Support and Behavior</title>
 198
 199   <sect2>
 200    <title>Initialization</title>
 201
 202    <para>
 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
 207     1 MB by default.
 208    </para>
 209
 210   </sect2>
 211
 212   <sect2 id="search">
 213    <title>Search</title>
 214
 215    <para>
 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
 221     without limitations.
 222     Searches may span multiple databases.
 223    </para>
 224
 225    <para>
 226     The server has full support for piggy-backed present requests (see
 227     also the following section).
 228    </para>
 229
 230    <para>
 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.
 237    </para>
 238
 239    <para>
 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.
 249    </para>
 250
 251    <para>
 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.
 260    </para>
 261
 262    <para>
 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.
 271    </para>
 272
 273    <para>
 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.
 278    </para>
 279
 280    <para>
 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.
 285    </para>
 286
 287    <para>
 288     If the <emphasis>Structure</emphasis> attribute is
 289     <emphasis>Local Number</emphasis> the term is treated as
 290     native Zebra Record Identifier.
 291    </para>
 292
 293    <para>
 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
 303     expression.
 304     If <emphasis>Relation</emphasis> is <emphasis>Relevance</emphasis>,
 305     the standard natural-language query processor is invoked.
 306    </para>
 307
 308    <para>
 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 &num;</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
 317     contents.
 318    </para>
 319
 320    <sect3>
 321     <title>Regular expressions</title>
 322
 323     <para>
 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:
 328      <variablelist>
 329
 330       <varlistentry>
 331        <term>x</term>
 332        <listitem>
 333         <para>
 334          Matches the character <emphasis>x</emphasis>.
 335         </para>
 336        </listitem>
 337       </varlistentry>
 338       <varlistentry>
 339        <term>.</term>
 340        <listitem>
 341         <para>
 342          Matches any character.
 343         </para>
 344        </listitem>
 345       </varlistentry>
 346       <varlistentry>
 347        <term><literal>[</literal>..<literal>]</literal></term>
 348        <listitem>
 349         <para>
 350          Matches the set of characters specified;
 351          such as <literal>[abc]</literal> or <literal>[a-c]</literal>.
 352         </para>
 353        </listitem>
 354       </varlistentry>
 355      </variablelist>
 356      and the operators:
 357      <variablelist>
 358
 359       <varlistentry>
 360        <term>x*</term>
 361        <listitem>
 362         <para>
 363          Matches <emphasis>x</emphasis> zero or more times. Priority: high.
 364         </para>
 365        </listitem>
 366       </varlistentry>
 367       <varlistentry>
 368        <term>x+</term>
 369        <listitem>
 370         <para>
 371          Matches <emphasis>x</emphasis> one or more times. Priority: high.
 372         </para>
 373        </listitem>
 374       </varlistentry>
 375       <varlistentry>
 376        <term>x?</term>
 377        <listitem>
 378         <para>
 379          Matches <emphasis>x</emphasis> once or twice. Priority: high.
 380         </para>
 381        </listitem>
 382       </varlistentry>
 383       <varlistentry>
 384        <term>xy</term>
 385        <listitem>
 386         <para>
 387          Matches <emphasis>x</emphasis>, then <emphasis>y</emphasis>.
 388          Priority: medium.
 389         </para>
 390        </listitem>
 391       </varlistentry>
 392       <varlistentry>
 393        <term>x&verbar;y</term>
 394        <listitem>
 395         <para>
 396          Matches either <emphasis>x</emphasis> or <emphasis>y</emphasis>.
 397          Priority: low.
 398         </para>
 399        </listitem>
 400       </varlistentry>
 401      </variablelist>
 402      The order of evaluation may be changed by using parentheses.
 403     </para>
 404
 405     <para>
 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.
 412     </para>
 413
 414     <para>
 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
 417      expressions.
 418     </para>
 419
 420    </sect3>
 421
 422    <sect3>
 423     <title>Query examples</title>
 424
 425     <para>
 426      Phrase search for <emphasis>information retrieval</emphasis> in
 427      the title-register:
 428      <screen>
 429       @attr 1=4 "information retrieval"
 430      </screen>
 431     </para>
 432
 433     <para>
 434      Ranked search for the same thing:
 435      <screen>
 436       @attr 1=4 @attr 2=102 "Information retrieval"
 437      </screen>
 438     </para>
 439
 440     <para>
 441      Phrase search with a regular expression:
 442      <screen>
 443       @attr 1=4 @attr 5=102 "informat.* retrieval"
 444      </screen>
 445     </para>
 446
 447     <para>
 448      Ranked search with a regular expression:
 449      <screen>
 450       @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval"
 451      </screen>
 452     </para>
 453
 454     <para>
 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:
 461      <screen>
 462       @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
 463      </screen>
 464     </para>
 465    </sect3>
 466   </sect2>
 467
 468   <sect2>
 469    <title>Present</title>
 470    <para>
 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.
 476    </para>
 477   </sect2>
 478   <sect2>
 479    <title>Scan</title>
 480    <para>
 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.
 485    </para>
 486   </sect2>
 487   <sect2>
 488    <title>Sort</title>
 489
 490    <para>
 491     Z39.50 specifies three different types of sort criteria.
 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.
 498    </para>
 499
 500    <para>
 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.
 505    </para>
 506   </sect2>
 507   <sect2>
 508    <title>Close</title>
 509    <para>
 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
 518     timeout.
 519    </para>
 520   </sect2>
 521  </sect1>
 522 </chapter>
 523  <!-- Keep this comment at the end of the file
 524  Local variables:
 525  mode: sgml
 526  sgml-omittag:t
 527  sgml-shorttag:t
 528  sgml-minimize-attributes:nil
 529  sgml-always-quote-attributes:t
 530  sgml-indent-step:1
 531  sgml-indent-data:t
 532  sgml-parent-document: "zebra.xml"
 533  sgml-local-catalogs: nil
 534  sgml-namecase-general:t
 535  End:
 536  -->