<chapter id="server">
- <!-- $Id: server.xml,v 1.13 2006-02-16 12:28:52 mike Exp $ -->
+ <!-- $Id: server.xml,v 1.19 2006-04-25 12:26:26 marc Exp $ -->
<title>The Z39.50 Server</title>
<sect1 id="zebrasrv">
zebrasrv manpage -->
- <sect2><title>DESCRIPTION</title>
+ <sect2><title>Description</title>
<para>Zebra is a high-performance, general-purpose structured text indexing
and retrieval engine. It reads structured records in a variety of input
formats (eg. email, XML, MARC) and allows access to them through exact
</sect2>
<sect2>
- <title>SYNOPSIS</title>
+ <title>Synopsis</title>
&zebrasrv-synopsis;
</sect2>
<sect2>
- <title>OPTIONS</title>
+ <title>Options</title>
<para>
The options for <command>zebrasrv</command> are the same
&zebrasrv-options;
</sect2>
- <sect2 id="gfs-config"><title>VIRTUAL HOSTS</title>
- <para>
- <command>zebrasrv</command> uses the YAZ server frontend and does
- support multiple virtual servers behind multiple listening sockets.
- </para>
- &zebrasrv-virtual;
- </sect2>
- <sect2><title>FILES</title>
+
+ <sect2><title>Files</title>
<para>
<filename>zebra.cfg</filename>
</para>
</sect2>
- <sect2><title>SEE ALSO</title>
+ <sect2><title>See Also</title>
<para>
<citerefentry>
<refentrytitle>zebraidx</refentrytitle>
</citerefentry>
</para>
<para>
- Section "The Z39.50 Server" in the Zebra manual.
- <filename>http://www.indexdata.dk/zebra/doc/server.tkl</filename>
- </para>
- <para>
- Section "Virtual Hosts" in the YAZ manual.
- <filename>http://www.indexdata.dk/yaz/doc/server.vhosts.tkl</filename>
- </para>
- <para>
- Section "Specification of <ulink url="http://www.loc.gov/standards/sru/cql/">CQL</ulink> to RPN mappings" in the YAZ manual.
- <filename>http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map</filename>
- </para>
- <para>
The Zebra software is Copyright <command>Index Data</command>
<filename>http://www.indexdata.dk</filename>
and distributed under the
browser to:
</para>
<screen>
- http://localhost:9999/Default?version=1.1&
- operation=searchRetrieve&
- x-pquery=mineral&
- startRecord=1&
- maximumRecords=1
+ http://localhost:9999/Default?version=1.1
+ &operation=searchRetrieve
+ &x-pquery=mineral
+ &startRecord=1
+ &maximumRecords=1
</screen>
<para>
This will display the XML-formatted SRU response that includes the
various CQL indexes, relations, etc. are translated into Type-1
queries.
</para>
+ <para>
+ A zebra server running with such a configuration can then be
+ queried using proper, conformant SRU URLs with CQL queries:
+ </para>
+ <screen>
+ http://localhost:9999/Default?version=1.1
+ &operation=searchRetrieve
+ &query=title=utah and description=epicent*
+ &startRecord=1
+ &maximumRecords=1
+ </screen>
</sect1>
<sect1 id="server-sru-support">
is with some shame, then, that we admit that Zebra also supports
an additional query language, our own Prefix Query Format (PQF,
<ulink url="http://indexdata.com/yaz/doc/tools.tkl#PQF"/>).
-x-pquery
-
-
+ A PQF query is submitted by using the extension parameter
+ <literal>x-pquery</literal>,
+ in which case the
+ <literal>query</literal>
+ parameter must be omitted, which makes the request not valid SRU.
+ Please don't do this.
</para>
</sect2>
<sect2>
<title>Scan</title>
<para>
- ###
+ Zebra does <emphasis>not</emphasis> support SRU's
+ <literal>scan</literal>
+ operation, as described at
+ <ulink url="http://www.loc.gov/standards/sru/scan/"/>
+ </para>
+ <para>
+ This is a rather embarrassing surprise as the pieces are all
+ there: Z39.50 scan is supported, and SRU scan requests are
+ recognised and diagnosed. To add further to the embarrassment, a
+ mutant form of SRU scan <emphasis>is</emphasis> supported, using
+ the non-standard <literal>x-pScanClause</literal> parameter in
+ place of the standard <literal>scanClause</literal> to scan on a
+ PQF query clause.
</para>
</sect2>
<sect2>
<title>Explain</title>
<para>
- ###
+ Zebra fully supports SRU's core
+ <literal>explain</literal>
+ operation, as described at
+ <ulink url="http://www.loc.gov/standards/sru/explain/index.html"/>
+ </para>
+ <para>
+ The ZeeRex record explaining a database may be requested either
+ with a fully fledged SRU request (with
+ <literal>operation</literal>=<literal>explain</literal>
+ and version-number specified)
+ or with a simple HTTP GET at the server's basename.
+ The ZeeRex record returned in response is the one embedded
+ in the YAZ Frontend Server configuration file that is described in the
+ <link linkend="gfs-config">Virtual Hosts</link> documentation.
</para>
+ <para>
+ Unfortunately, the data found in the
+ CQL-to-PQF text file must be added by hand-craft into the explain
+ section of the YAZ Frontend Server configuration file to be able
+ to provide a suitable explain record.
+ Too bad, but this is all extreme
+ new alpha stuff, and a lot of work has yet to be done ..
+ </para>
+ <para>
+ There is no linkeage whatsoever between the Z39.50 explain model
+ and the SRU/SRW explain response (well, at least not implemented
+ in Zebra, that is ..). Zebra does not provide a means using
+ Z39.50 to obtain the ZeeRex record.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Some SRU Examples</title>
+ <para>
+ Surf into <literal>http://localhost:9999</literal>
+ to get an explain response, or use
+ <screen><![CDATA[
+ http://localhost:9999/?version=1.1&operation=explain
+ ]]></screen>
+ </para>
+ <para>
+ See number of hits for a query
+ <screen><![CDATA[
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=text=(plant%20and%20soil)
+ ]]></screen>
+ </para>
+ <para>
+ Fetch record 5-7 in Dublin Core format
+ <screen><![CDATA[
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=text=(plant%20and%20soil)
+ &startRecord=5&maximumRecords=2&recordSchema=dc
+ ]]></screen>
+ </para>
+ <para>
+ Even search using PQF queries using the <emphasis>extended naughty
+ verb</emphasis> <literal>x-pquery</literal>
+ <screen><![CDATA[
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &x-pquery=@attr%201=text%20@and%20plant%20soil
+ ]]></screen>
+ </para>
+ <para>
+ Or scan indexes using the <emphasis>extended extremely naughty
+ verb</emphasis> <literal>x-pScanClause</literal>
+ <screen><![CDATA[
+ http://localhost:9999/?version=1.1&operation=scan
+ &x-pScanClause=@attr%201=text%20something
+ ]]></screen>
+ <emphasis>Don't do this in production code!</emphasis>
+ But it's a great fast debugging aid.
+ </para>
</sect2>
<sect2>