doc/server.xml

   1 <chapter id="server">
   2  <!-- $Id: server.xml,v 1.16 2006-02-16 16:50:18 marc Exp $ -->
   3  <title>The Z39.50 Server</title>
   4
   5  <sect1 id="zebrasrv">
   6   <title>Running the Z39.50 Server (zebrasrv)</title>
   7
   8   <!--
   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
  13   -->
  14
  15   <!-- re-write by MC, using the newly created input files for the
  16    zebrasrv manpage -->
  17
  18
  19  <sect2><title>Description</title>
  20     <para>Zebra is a high-performance, general-purpose structured text indexing
  21    and retrieval engine. It reads structured records in a variety of input
  22    formats (eg. email, XML, MARC) and allows access to them through exact
  23    boolean search expressions and relevance-ranked free-text queries.
  24    </para>
  25    <para>
  26     <command>zebrasrv</command> is the Z39.50 and  <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>/U frontend
  27     server for the <command>Zebra</command> indexer.
  28    </para>
  29    <para>
  30     On Unix you can run the <command>zebrasrv</command>
  31     server from the command line - and put it
  32     in the background. It may also operate under the inet daemon.
  33     On WIN32 you can run the server as a console application or
  34     as a WIN32 Service.
  35    </para>
  36   </sect2>
  37
  38  <sect2>
  39    <title>Synopsis</title>
  40     &zebrasrv-synopsis;
  41  </sect2>
  42
  43  <sect2>
  44    <title>Options</title>
  45
  46    <para>
  47     The options for <command>zebrasrv</command> are the same
  48     as those for YAZ' <command>yaz-ztest</command>.
  49     Option <literal>-c</literal> specifies a Zebra configuration
  50     file - if omitted <filename>zebra.cfg</filename> is read.
  51    </para>
  52
  53   &zebrasrv-options;
  54   </sect2>
  55
  56   <sect2><title>Files</title>
  57    <para>
  58     <filename>zebra.cfg</filename>
  59    </para>
  60   </sect2>
  61   <sect2><title>See Also</title>
  62    <para>
  63     <citerefentry>
  64      <refentrytitle>zebraidx</refentrytitle>
  65      <manvolnum>1</manvolnum>
  66     </citerefentry>,
  67     <citerefentry>
  68      <refentrytitle>yaz-ztest</refentrytitle>
  69      <manvolnum>8</manvolnum>
  70     </citerefentry>
  71    </para>
  72    <para>
  73     The Zebra software is Copyright <command>Index Data</command>
  74     <filename>http://www.indexdata.dk</filename>
  75     and distributed under the
  76     GPLv2 license.
  77    </para>
  78   </sect2>
  79
  80   <!--
  81   <para>
  82    <emphasis remap="bf">Syntax</emphasis>
  83
  84    <screen>
  85     zebrasrv [options] [listener-address ...]
  86    </screen>
  87
  88   </para>
  89
  90   <para>
  91    <emphasis remap="bf">Options</emphasis>
  92    <variablelist>
  93
  94     <varlistentry>
  95      <term>-a <replaceable>APDU file</replaceable></term>
  96      <listitem>
  97       <para>
  98        Specify a file for dumping PDUs (for diagnostic purposes).
  99        The special name "-" sends output to <literal>stderr</literal>.
 100       </para>
 101      </listitem>
 102     </varlistentry>
 103     <varlistentry>
 104      <term>-c <replaceable>config-file</replaceable></term>
 105      <listitem>
 106       <para>
 107        Read configuration information from
 108        <replaceable>config-file</replaceable>.
 109        The default configuration is <literal>./zebra.cfg</literal>.
 110       </para>
 111      </listitem>
 112     </varlistentry>
 113     <varlistentry>
 114      <term>-S</term>
 115      <listitem>
 116       <para>
 117        Don't fork on connection requests. This can be useful for
 118        symbolic-level debugging. The server can only accept a single
 119        connection in this mode.
 120       </para>
 121      </listitem>
 122     </varlistentry>
 123     <varlistentry>
 124      <term>-z</term>
 125      <listitem>
 126       <para>
 127        Use the Z39.50 protocol. Currently the only protocol supported.
 128        The option is retained for historical reasons, and for future
 129        extensions.
 130       </para>
 131      </listitem>
 132     </varlistentry>
 133     <varlistentry>
 134      <term>-l <replaceable>logfile</replaceable></term>
 135      <listitem>
 136       <para>
 137        Specify an output file for the diagnostic messages.
 138        The default is to write this information to <literal>stderr</literal>.
 139       </para>
 140      </listitem>
 141     </varlistentry>
 142     <varlistentry>
 143      <term>-v <replaceable>log-level</replaceable></term>
 144      <listitem>
 145       <para>
 146        The log level. Use a comma-separated list of members of the set
 147        {fatal,debug,warn,log,all,none}.
 148       </para>
 149      </listitem>
 150     </varlistentry>
 151     <varlistentry>
 152      <term>-u <replaceable>username</replaceable></term>
 153      <listitem>
 154       <para>
 155        Set user ID. Sets the real UID of the server process to that of the
 156        given <replaceable>username</replaceable>.
 157        It's useful if you aren't comfortable with having the
 158        server run as root, but you need to start it as such to bind a
 159        privileged port.
 160       </para>
 161      </listitem>
 162     </varlistentry>
 163     <varlistentry>
 164      <term>-w <replaceable>working-directory</replaceable></term>
 165      <listitem>
 166       <para>
 167        Change working directory.
 168       </para>
 169      </listitem>
 170     </varlistentry>
 171     <varlistentry>
 172      <term>-i</term>
 173      <listitem>
 174       <para>
 175        Run under the Internet superserver, <literal>inetd</literal>.
 176        Make sure you use the logfile option <literal>-l</literal> in
 177        conjunction with this mode and specify the <literal>-l</literal>
 178        option before any other options.
 179       </para>
 180      </listitem>
 181     </varlistentry>
 182     <varlistentry>
 183      <term>-t <replaceable>timeout</replaceable></term>
 184      <listitem>
 185       <para>
 186        Set the idle session timeout (default 60 minutes).
 187       </para>
 188      </listitem>
 189     </varlistentry>
 190     <varlistentry>
 191      <term>-k <replaceable>kilobytes</replaceable></term>
 192      <listitem>
 193       <para>
 194        Set the (approximate) maximum size of
 195        present response messages. Default is 1024 KB (1 MB).
 196       </para>
 197      </listitem>
 198     </varlistentry>
 199    </variablelist>
 200   </para>
 201   -->
 202  </sect1>
 203
 204
 205  <sect1 id="protocol-support">
 206   <title>Z39.50 Protocol Support and Behavior</title>
 207
 208   <sect2>
 209    <title>Initialization</title>
 210
 211    <para>
 212     During initialization, the server will negotiate to version 3 of the
 213     Z39.50 protocol, and the option bits for Search, Present, Scan,
 214     NamedResultSets, and concurrentOperations will be set, if requested by
 215     the client. The maximum PDU size is negotiated down to a maximum of
 216     1 MB by default.
 217    </para>
 218
 219   </sect2>
 220
 221   <sect2 id="search">
 222    <title>Search</title>
 223
 224    <!--
 225     FIXME - Need to explain the string tag stuff before people get bogged
 226             down with all these attribute numbers. Perhaps in its own
 227             chapter? -H
 228    -->
 229
 230    <para>
 231     The supported query type are 1 and 101. All operators are currently
 232     supported with the restriction that only proximity units of type "word"
 233     are supported for the proximity operator.
 234     Queries can be arbitrarily complex.
 235     Named result sets are supported, and result sets can be used as operands
 236     without limitations.
 237     Searches may span multiple databases.
 238    </para>
 239
 240    <para>
 241     The server has full support for piggy-backed retrieval (see
 242     also the following section).
 243    </para>
 244
 245    <para>
 246     <emphasis>Use</emphasis> attributes are interpreted according to the
 247     attribute sets which have been loaded in the
 248     <literal>zebra.cfg</literal> file, and are matched against specific
 249     fields as specified in the <literal>.abs</literal> file which
 250     describes the profile of the records which have been loaded.
 251     If no Use attribute is provided, a default of Bib-1 Any is assumed.
 252    </para>
 253
 254    <para>
 255     If a <emphasis>Structure</emphasis> attribute of
 256     <emphasis>Phrase</emphasis> is used in conjunction with a
 257     <emphasis>Completeness</emphasis> attribute of
 258     <emphasis>Complete (Sub)field</emphasis>, the term is matched
 259     against the contents of the phrase (long word) register, if one
 260     exists for the given <emphasis>Use</emphasis> attribute.
 261     A phrase register is created for those fields in the
 262     <literal>.abs</literal> file that contains a
 263     <literal>p</literal>-specifier.
 264     <!-- ### whatever the hell _that_ is -->
 265    </para>
 266
 267    <para>
 268     If <emphasis>Structure</emphasis>=<emphasis>Phrase</emphasis> is
 269     used in conjunction with <emphasis>Incomplete Field</emphasis> - the
 270     default value for <emphasis>Completeness</emphasis>, the
 271     search is directed against the normal word registers, but if the term
 272     contains multiple words, the term will only match if all of the words
 273     are found immediately adjacent, and in the given order.
 274     The word search is performed on those fields that are indexed as
 275     type <literal>w</literal> in the <literal>.abs</literal> file.
 276    </para>
 277
 278    <para>
 279     If the <emphasis>Structure</emphasis> attribute is
 280     <emphasis>Word List</emphasis>,
 281     <emphasis>Free-form Text</emphasis>, or
 282     <emphasis>Document Text</emphasis>, the term is treated as a
 283     natural-language, relevance-ranked query.
 284     This search type uses the word register, i.e. those fields
 285     that are indexed as type <literal>w</literal> in the
 286     <literal>.abs</literal> file.
 287    </para>
 288
 289    <para>
 290     If the <emphasis>Structure</emphasis> attribute is
 291     <emphasis>Numeric String</emphasis> the term is treated as an integer.
 292     The search is performed on those fields that are indexed
 293     as type <literal>n</literal> in the <literal>.abs</literal> file.
 294    </para>
 295
 296    <para>
 297     If the <emphasis>Structure</emphasis> attribute is
 298     <emphasis>URx</emphasis> the term is treated as a URX (URL) entity.
 299     The search is performed on those fields that are indexed as type
 300     <literal>u</literal> in the <literal>.abs</literal> file.
 301    </para>
 302
 303    <para>
 304     If the <emphasis>Structure</emphasis> attribute is
 305     <emphasis>Local Number</emphasis> the term is treated as
 306     native Zebra Record Identifier.
 307    </para>
 308
 309    <para>
 310     If the <emphasis>Relation</emphasis> attribute is
 311     <emphasis>Equals</emphasis> (default), the term is matched
 312     in a normal fashion (modulo truncation and processing of
 313     individual words, if required).
 314     If <emphasis>Relation</emphasis> is <emphasis>Less Than</emphasis>,
 315     <emphasis>Less Than or Equal</emphasis>,
 316     <emphasis>Greater than</emphasis>, or <emphasis>Greater than or
 317      Equal</emphasis>, the term is assumed to be numerical, and a
 318     standard regular expression is constructed to match the given
 319     expression.
 320     If <emphasis>Relation</emphasis> is <emphasis>Relevance</emphasis>,
 321     the standard natural-language query processor is invoked.
 322    </para>
 323
 324    <para>
 325     For the <emphasis>Truncation</emphasis> attribute,
 326     <emphasis>No Truncation</emphasis> is the default.
 327     <emphasis>Left Truncation</emphasis> is not supported.
 328     <emphasis>Process # in search term</emphasis> is supported, as is
 329     <emphasis>Regxp-1</emphasis>.
 330     <emphasis>Regxp-2</emphasis> enables the fault-tolerant (fuzzy)
 331     search. As a default, a single error (deletion, insertion,
 332     replacement) is accepted when terms are matched against the register
 333     contents.
 334    </para>
 335
 336    <sect3>
 337     <title>Regular expressions</title>
 338
 339     <para>
 340      Each term in a query is interpreted as a regular expression if
 341      the truncation value is either <emphasis>Regxp-1</emphasis> (102)
 342      or <emphasis>Regxp-2</emphasis> (103).
 343      Both query types follow the same syntax with the operands:
 344      <variablelist>
 345
 346       <varlistentry>
 347        <term>x</term>
 348        <listitem>
 349         <para>
 350          Matches the character <emphasis>x</emphasis>.
 351         </para>
 352        </listitem>
 353       </varlistentry>
 354       <varlistentry>
 355        <term>.</term>
 356        <listitem>
 357         <para>
 358          Matches any character.
 359         </para>
 360        </listitem>
 361       </varlistentry>
 362       <varlistentry>
 363        <term><literal>[</literal>..<literal>]</literal></term>
 364        <listitem>
 365         <para>
 366          Matches the set of characters specified;
 367          such as <literal>[abc]</literal> or <literal>[a-c]</literal>.
 368         </para>
 369        </listitem>
 370       </varlistentry>
 371      </variablelist>
 372      and the operators:
 373      <variablelist>
 374
 375       <varlistentry>
 376        <term>x*</term>
 377        <listitem>
 378         <para>
 379          Matches <emphasis>x</emphasis> zero or more times. Priority: high.
 380         </para>
 381        </listitem>
 382       </varlistentry>
 383       <varlistentry>
 384        <term>x+</term>
 385        <listitem>
 386         <para>
 387          Matches <emphasis>x</emphasis> one or more times. Priority: high.
 388         </para>
 389        </listitem>
 390       </varlistentry>
 391       <varlistentry>
 392        <term>x?</term>
 393        <listitem>
 394         <para>
 395          Matches <emphasis>x</emphasis> zero or once. Priority: high.
 396         </para>
 397        </listitem>
 398       </varlistentry>
 399       <varlistentry>
 400        <term>xy</term>
 401        <listitem>
 402         <para>
 403          Matches <emphasis>x</emphasis>, then <emphasis>y</emphasis>.
 404          Priority: medium.
 405         </para>
 406        </listitem>
 407       </varlistentry>
 408       <varlistentry>
 409        <term>x|y</term>
 410        <listitem>
 411         <para>
 412          Matches either <emphasis>x</emphasis> or <emphasis>y</emphasis>.
 413          Priority: low.
 414         </para>
 415        </listitem>
 416       </varlistentry>
 417      </variablelist>
 418      The order of evaluation may be changed by using parentheses.
 419     </para>
 420
 421     <para>
 422      If the first character of the <emphasis>Regxp-2</emphasis> query
 423      is a plus character (<literal>+</literal>) it marks the
 424      beginning of a section with non-standard specifiers.
 425      The next plus character marks the end of the section.
 426      Currently Zebra only supports one specifier, the error tolerance,
 427      which consists one digit.
 428     </para>
 429
 430     <para>
 431      Since the plus operator is normally a suffix operator the addition to
 432      the query syntax doesn't violate the syntax for standard regular
 433      expressions.
 434     </para>
 435
 436    </sect3>
 437
 438    <sect3>
 439     <title>Query examples</title>
 440
 441     <para>
 442      Phrase search for <emphasis>information retrieval</emphasis> in
 443      the title-register:
 444      <screen>
 445       @attr 1=4 "information retrieval"
 446      </screen>
 447     </para>
 448
 449     <para>
 450      Ranked search for the same thing:
 451      <screen>
 452       @attr 1=4 @attr 2=102 "Information retrieval"
 453      </screen>
 454     </para>
 455
 456     <para>
 457      Phrase search with a regular expression:
 458      <screen>
 459       @attr 1=4 @attr 5=102 "informat.* retrieval"
 460      </screen>
 461     </para>
 462
 463     <para>
 464      Ranked search with a regular expression:
 465      <screen>
 466       @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval"
 467      </screen>
 468     </para>
 469
 470     <para>
 471      In the GILS schema (<literal>gils.abs</literal>), the
 472      west-bounding-coordinate is indexed as type <literal>n</literal>,
 473      and is therefore searched by specifying
 474      <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
 475      To match all those records with west-bounding-coordinate greater
 476      than -114 we use the following query:
 477      <screen>
 478       @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
 479      </screen>
 480     </para>
 481    </sect3>
 482   </sect2>
 483
 484   <sect2>
 485    <title>Present</title>
 486    <para>
 487     The present facility is supported in a standard fashion. The requested
 488     record syntax is matched against the ones supported by the profile of
 489     each record retrieved. If no record syntax is given, SUTRS is the
 490     default. The requested element set name, again, is matched against any
 491     provided by the relevant record profiles.
 492    </para>
 493   </sect2>
 494   <sect2>
 495    <title>Scan</title>
 496    <para>
 497     The attribute combinations provided with the termListAndStartPoint are
 498     processed in the same way as operands in a query (see above).
 499     Currently, only the term and the globalOccurrences are returned with
 500     the termInfo structure.
 501    </para>
 502   </sect2>
 503   <sect2>
 504    <title>Sort</title>
 505
 506    <para>
 507     Z39.50 specifies three different types of sort criteria.
 508     Of these Zebra supports the attribute specification type in which
 509     case the use attribute specifies the "Sort register".
 510     Sort registers are created for those fields that are of type "sort" in
 511     the default.idx file.
 512     The corresponding character mapping file in default.idx specifies the
 513     ordinal of each character used in the actual sort.
 514    </para>
 515
 516    <para>
 517     Z39.50 allows the client to specify sorting on one or more input
 518     result sets and one output result set.
 519     Zebra supports sorting on one result set only which may or may not
 520     be the same as the output result set.
 521    </para>
 522   </sect2>
 523   <sect2>
 524    <title>Close</title>
 525    <para>
 526     If a Close PDU is received, the server will respond with a Close PDU
 527     with reason=FINISHED, no matter which protocol version was negotiated
 528     during initialization. If the protocol version is 3 or more, the
 529     server will generate a Close PDU under certain circumstances,
 530     including a session timeout (60 minutes by default), and certain kinds of
 531     protocol errors. Once a Close PDU has been sent, the protocol
 532     association is considered broken, and the transport connection will be
 533     closed immediately upon receipt of further data, or following a short
 534     timeout.
 535    </para>
 536   </sect2>
 537  </sect1>
 538 </chapter>
 539
 540
 541 <chapter id="server-sru">
 542  <title>The SRU/SRW Server</title>
 543  <para>
 544   In addition to Z39.50, Zebra supports the more recent and
 545   web-friendly IR protocol SRU, described at
 546   <ulink url="http://www.loc.gov/sru"/>.
 547   SRU is ``Search/Retrieve via URL'', a simple, REST-like protocol
 548   that uses HTTP GET to request search responses.  The request
 549   itself is made of parameters such as
 550   <literal>query</literal>,
 551   <literal>startRecord</literal>,
 552   <literal>maximumRecords</literal>
 553   and
 554   <literal>recordSchema</literal>;
 555   the response is an XML document containing hit-count, result-set
 556   records, diagnostics, etc.  SRU can be thought of as a re-casting
 557   of Z39.50 semantics in web-friendly terms; or as a standardisation
 558   of the ad-hoc query parameters used by search engines such as Google
 559   and AltaVista; or as a superset of A9's OpenSearch (which it
 560   predates).
 561  </para>
 562  <para>
 563   Zebra further supports SRW, described at
 564   <ulink url="http://www.loc.gov/srw"/>.
 565   SRW is the ``Search/Retrieve Web Service'', a SOAP-based alternative
 566   implementation of the abstract protocol that SRU implements as HTTP
 567   GET requests.  In SRW, requests are encoded as XML documents which
 568   are posted to the server.  The responses are identical to those
 569   returned by SRU servers, except that they are wrapped in a several
 570   layers of SOAP envelope.
 571  </para>
 572  <para>
 573   Zebra supports all three protocols - Z39.50, SRU and SRW - on the
 574   same port, recognising what protocol is used by each incoming
 575   requests and handling them accordingly.  This is a achieved through
 576   the use of Deep Magic; civilians are warned not to stand too close.
 577  </para>
 578  <para>
 579   From here on, ``SRU'' is used to indicate both the SRU and SRW
 580   protocols, as they are identical except for the transport used for
 581   the protocol packets and Zebra's support for them is equivalent.
 582  </para>
 583
 584  <sect1 id="server-sru-run">
 585   <title>Running the SRU Server (zebrasrv)</title>
 586   <para>
 587    Because Zebra supports all three protocols on one port, it would
 588    seem to follow that the SRU server is run in the same way as
 589    the Z39.50 server, as described above.  This is true, but only in
 590    an uninterestingly vacuous way: a Zebra server run in this manner
 591    will indeed recognise and accept SRU requests; but since it
 592    doesn't know how to handle the CQL queries that these protocols
 593    use, all it can do is send failure responses.
 594   </para>
 595   <note>
 596    <para>
 597     It is possible to cheat, by having SRU search Zebra with
 598     a PQF query instead of CQL, using the
 599     <literal>x-pquery</literal>
 600     parameter instead of
 601     <literal>query</literal>.
 602     This is a
 603     <emphasis role="strong">non-standard extension</emphasis>
 604     of CQL, and a
 605     <emphasis role="strong">very naughty</emphasis>
 606     thing to do, but it does give you a way to see Zebra serving SRU
 607     ``right out of the box''.  If you start your favourite Zebra
 608     server in the usual way, on port 9999, then you can send your web
 609     browser to:
 610   </para>
 611   <screen>
 612         http://localhost:9999/Default?version=1.1
 613                 &amp;operation=searchRetrieve
 614                 &amp;x-pquery=mineral
 615                 &amp;startRecord=1
 616                 &amp;maximumRecords=1
 617   </screen>
 618   <para>
 619     This will display the XML-formatted SRU response that includes the
 620     first record in the result-set found by the query
 621     <literal>mineral</literal>.  (For clarity, the SRU URL is shown
 622     here broken across lines, but the lines should be joined to gether
 623     to make single-line URL for the browser to submit.)
 624    </para>
 625   </note>
 626   <para>
 627    In order to turn on Zebra's support for CQL queries, it's necessary
 628    to have the YAZ generic front-end (which Zebra uses) translate them
 629    into the Z39.50 Type-1 query format that is used internally.  And
 630    to do this, the generic front-end's own configuration file must be
 631    used.  This file is described
 632    <link linkend="gfs-config">elsewhere</link>;
 633    the salient point for SRU support is that
 634    <command>zebrasrv</command>
 635    must be started with the
 636    <literal>-f&nbsp;frontendConfigFile</literal>
 637    option rather than the
 638    <literal>-c&nbsp;zebraConfigFile</literal>
 639    option,
 640    and that the front-end configuration file must include both a
 641    reference to the Zebra configuration file and the CQL-to-PQF
 642    translator configuration file.
 643   </para>
 644   <para>
 645    A minimal front-end configuration file that does this would read as
 646    follows:
 647   </para>
 648   <screen><![CDATA[
 649         <yazgfs>
 650           <server>
 651             <config>zebra.cfg</config>
 652             <cql2rpn>../../tab/pqf.properties</cql2rpn>
 653           </server>
 654         </yazgfs>
 655 ]]></screen>
 656   <para>
 657    The
 658    <literal>&lt;config&gt;</literal>
 659    element contains the name of the Zebra configuration file that was
 660    previously specified by the
 661    <literal>-c</literal>
 662    command-line argument, and the
 663    <literal>&lt;cql2rpn&gt;</literal>
 664    element contains the name of the CQL properties file specifying how
 665    various CQL indexes, relations, etc. are translated into Type-1
 666    queries.
 667   </para>
 668   <para>
 669    A zebra server running with such a configuration can then be
 670    queried using proper, conformant SRU URLs with CQL queries:
 671   </para>
 672   <screen>
 673         http://localhost:9999/Default?version=1.1
 674                 &amp;operation=searchRetrieve
 675                 &amp;query=title=utah and description=epicent*
 676                 &amp;startRecord=1
 677                 &amp;maximumRecords=1
 678   </screen>
 679  </sect1>
 680
 681  <sect1 id="server-sru-support">
 682   <title>SRU and SRW Protocol Support and Behavior</title>
 683   <para>
 684    Zebra running as an SRU server supports SRU version 1.1, including
 685    CQL version 1.1.  In particular, it provides support for the
 686    following elements of the protocol.
 687   </para>
 688
 689   <sect2>
 690    <title>Search and Retrieval</title>
 691    <para>
 692     Zebra fully supports SRU's core
 693     <literal>searchRetrieve</literal>
 694     operation, as described at
 695     <ulink url="http://www.loc.gov/standards/sru/sru-spec.html"/>
 696    </para>
 697    <para>
 698     One of the great strengths of SRU is that it mandates a standard
 699     query language, CQL, and that all conforming implementations can
 700     therefore be trusted to correctly interpret the same queries.  It
 701     is with some shame, then, that we admit that Zebra also supports
 702     an additional query language, our own Prefix Query Format (PQF,
 703     <ulink url="http://indexdata.com/yaz/doc/tools.tkl#PQF"/>).
 704     A PQF query is submitted by using the extension parameter
 705     <literal>x-pquery</literal>,
 706     in which case the
 707     <literal>query</literal>
 708     parameter must be omitted, which makes the request not valid SRU.
 709     Please don't do this.
 710    </para>
 711   </sect2>
 712
 713   <sect2>
 714    <title>Scan</title>
 715    <para>
 716     Zebra does <emphasis>not</emphasis> support SRU's
 717     <literal>scan</literal>
 718     operation, as described at
 719     <ulink url="http://www.loc.gov/standards/sru/scan/"/>
 720    </para>
 721    <para>
 722     This is a rather embarrassing surprise as the pieces are all
 723     there: Z39.50 scan is supported, and SRU scan requests are
 724     recognised and diagnosed.  To add further to the embarrassment, a
 725     mutant form of SRU scan <emphasis>is</emphasis> supported, using
 726     the non-standard <literal>x-pScanClause</literal> parameter in
 727     place of the standard <literal>scanClause</literal> to scan on a
 728     PQF query clause.
 729    </para>
 730   </sect2>
 731
 732   <sect2>
 733    <title>Explain</title>
 734    <para>
 735     Zebra fully supports SRU's core
 736     <literal>explain</literal>
 737     operation, as described at
 738     <ulink url="http://www.loc.gov/standards/sru/explain/index.html"/>
 739    </para>
 740    <para>
 741     The ZeeRex record explaining a database may be requested either
 742     with a fully fledged SRU request (with
 743     <literal>operation</literal>=<literal>explain</literal>
 744     and version-number specified)
 745     or with a simple HTTP GET at the server's basename.
 746    </para>
 747     <para>
 748      Unfortunately, the data found in the
 749      CQL-to-PQF text file must be added by hand-craft into the explain
 750      section of the YAZ Frontend Server configuration file to be able
 751      to provide a suitable explain record.
 752      Too bad, but this is all extreme
 753      new alpha stuff, and a lot of work has yet to be done ..
 754     </para>
 755     <para>
 756      There is no linkeage whatsoever between the Z39.50 explain model
 757      and the SRU/SRW explain response (well, at least not implemented
 758      in Zebra, that is ..).
 759      </para>
 760   </sect2>
 761
 762   <sect2>
 763    <title>Some SRU Examples</title>
 764     <para>
 765      Surf into <literal>http://localhost:9999</literal>
 766      to get an explain response, or use
 767      <screen>
 768      <![CDATA[
 769       http://localhost:9999/?version=1.1&operation=explain
 770      ]]>
 771      </screen>
 772     </para>
 773     <para>
 774      See number of hits for a query
 775      <screen>
 776      <![CDATA[
 777        http://localhost:9999/?version=1.1&operation=searchRetrieve
 778                        &query=text=(plant%20and%20soil)
 779      ]]>
 780      </screen>
 781     </para>
 782     <para>
 783       Fetch record 5-7 in Dublin Core format
 784      <screen>
 785      <![CDATA[
 786        http://localhost:9999/?version=1.1&operation=searchRetrieve
 787                        &query=text=(plant%20and%20soil)
 788                        &startRecord=5&maximumRecords=2&recordSchema=dc
 789
 790      ]]>
 791      </screen>
 792     </para>
 793     <para>
 794      Even search using PQF queries using the <emphasis>extended naughty
 795      verb</emphasis> <literal>x-pquery</literal>
 796      <screen>
 797      <![CDATA[
 798       http://localhost:9999/?version=1.1&operation=searchRetrieve
 799                        &x-pquery=@attr%201=text%20@and%20plant%20soil
 800      ]]>
 801      </screen>
 802      or scan indexes using the <emphasis>extended extremely naughty
 803      verb</emphasis> <literal>x-pScanClause</literal>
 804      <screen>
 805      <![CDATA[
 806       http://localhost:9999/?version=1.1&operation=scan
 807                        &x-pScanClause=@attr%201=text%20something
 808      ]]>
 809      </screen>
 810      <emphasis>Don't do this in production code!</emphasis>
 811      But it's a great fast debugging aid.
 812     </para>
 813   </sect2>
 814
 815   <sect2>
 816    <title>Initialization, Present, Sort, Close</title>
 817    <para>
 818     In the Z39.50 protocol, Initialization, Present, Sort and Close
 819     are separate operations.  In SRU, however, these operations do not
 820     exist.
 821    </para>
 822    <itemizedlist>
 823     <listitem>
 824      <para>
 825       SRU has no explicit initialization handshake phase, but
 826       commences immediately with searching, scanning and explain
 827       operations.
 828      </para>
 829     </listitem>
 830     <listitem>
 831      <para>
 832       Neither does SRU have a close operation, since the protocol is
 833       stateless and each request is self-contained.  (It is true that
 834       multiple SRU request/response pairs may be implemented as
 835       multiple HTTP request/response pairs over a single persistent
 836       TCP/IP connection; but the closure of that connection is not a
 837       protocol-level operation.)
 838      </para>
 839     </listitem>
 840     <listitem>
 841      <para>
 842       Retrieval in SRU is part of the
 843       <literal>searchRetrieve</literal> operation, in which a search
 844       is submitted and the response includes a subset of the records
 845       in the result set.  There is no direct analogue of Z39.50's
 846       Present operation which requests records from an established
 847       result set.  In SRU, this is achieved by sending a subsequent
 848       <literal>searchRetrieve</literal> request with the query
 849       <literal>cql.resultSetId=</literal><emphasis>id</emphasis> where
 850       <emphasis>id</emphasis> is the identifier of the previously
 851       generated result-set.
 852      </para>
 853     </listitem>
 854     <listitem>
 855      <para>
 856       Sorting in CQL is done within the
 857       <literal>searchRetrieve</literal> operation - in v1.1, by an
 858       explicit <literal>sort</literal> parameter, but the forthcoming
 859       v1.2 or v2.0 will most likely use an extension of the query
 860       language, CQL for sorting: see
 861       <ulink url="http://zing.z3950.org/cql/sorting.html"/>
 862      </para>
 863     </listitem>
 864    </itemizedlist>
 865    <para>
 866     It can be seen, then, that while Zebra operating as an SRU server
 867     does not provide the same set of operations as when operating as a
 868     Z39.50 server, it does provide equivalent functionality.
 869    </para>
 870   </sect2>
 871  </sect1>
 872 </chapter>
 873
 874  <!-- Keep this comment at the end of the file
 875  Local variables:
 876  mode: sgml
 877  sgml-omittag:t
 878  sgml-shorttag:t
 879  sgml-minimize-attributes:nil
 880  sgml-always-quote-attributes:t
 881  sgml-indent-step:1
 882  sgml-indent-data:t
 883  sgml-parent-document: "zebra.xml"
 884  sgml-local-catalogs: nil
 885  sgml-namecase-general:t
 886  End:
 887  -->