<chapter id="server">
- <!-- $Id: server.xml,v 1.14 2006-02-16 13:27:18 mike Exp $ -->
+ <!-- $Id: server.xml,v 1.22 2006-06-07 13:17:48 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
</screen>
</para>
</sect3>
- </sect2>
-
+ </sect2>
+
<sect2>
<title>Present</title>
<para>
timeout.
</para>
</sect2>
+
+ <sect2>
+ <title>Explain</title>
+ <para>
+ Zebra maintains a "classic"
+ <ulink url="&url.z39.50.explain;">Explain</ulink> database
+ on the side.
+ This database is called <literal>IR-Explain-1</literal> and can be
+ searched using the attribute set <literal>exp-1</literal>.
+ </para>
+ <para>
+ The records in the explain database are of type
+ <literal>grs.sgml</literal> and can be retrieved as
+ <literal>SUTRS</literal>, <literal>XML</literal>,
+ <literal>GRS-1</literal> and <literal>ASN.1</literal> Explain.
+ </para>
+ <para>
+ Classic Explain only defines retrieaval of Explain information
+ via ASN.1. Pratically no Z39.50 clients supports this. Fortunately
+ they don't have to - since Zebra allows retrieval of this information
+ in the other formats.
+ </para>
+ <para>
+ The root element for the Explain grs.sgml records is
+ <literal>explain</literal>, thus
+ <filename>explain.abs</filename> is used for indexing.
+ </para>
+ <note>
+ <para>
+ Zebra <emphasis>must</emphasis> be able to locate
+ <filename>explain.abs</filename> in order to index the Explain
+ records properly. Zebra will work without it but the information
+ will not be searchable.
+ </para>
+ </note>
+ <para>
+ The following Explain categories are supported:
+ <literal>CategoryList</literal>, <literal>TargetInfo</literal>,
+ <literal>DatabaseInfo</literal>, <literal>AttributeDetails</literal>.
+ </para>
+ <para>
+ The following Explain search atributes are supported:
+ <literal>ExplainCategory</literal> (@attr 1=1),
+ <literal>DatabaseName</literal> (@attr 1=3),
+ <literal>DateAdded</literal> (@attr 1=9),
+ <literal>DateChanged</literal>(@ayyt 1=10).
+ See <filename>tab/explain.att</filename> for more information.
+ </para>
+
+ <sect3>
+ <title>Example searches with yaz-client</title>
+
+
+ <para>
+ List supported categories to find out which explain commands are
+ supported:
+ <screen>
+ Z> base IR-Explain-1
+ Z> @attr exp1 1=1 categorylist
+ Z> form sutrs
+ Z> show 1+2
+ </screen>
+ </para>
+
+ <para>
+ Get target info, that is, investigate which databases exist at
+ this server endpoint:
+ <screen>
+ Z> base IR-Explain-1
+ Z> @attr exp1 1=1 targetinfo
+ Z> form xml
+ Z> show 1+1
+ Z> form grs-1
+ Z> show 1+1
+ Z> form sutrs
+ Z> show 1+1
+ </screen>
+ </para>
+
+ <para>
+ List all supported databases, the number of hits
+ is the number of databases found, which most commonly are the
+ following two:
+ the <literal>Default</literal> and the
+ <literal>IR-Explain-1</literal> databases.
+ <screen>
+ Z> base IR-Explain-1
+ Z> f @attr exp1 1=1 databaseinfo
+ Z> form sutrs
+ Z> show 1+2
+ </screen>
+ </para>
+
+ <para>
+ Get database info record for database <literal>Default</literal>.
+ <screen>
+ Z> base IR-Explain-1
+ Z> @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default
+ </screen>
+ Identical query with explicitly specified attribute set:
+ <screen>
+ Z> base IR-Explain-1
+ Z> @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default
+ </screen>
+ </para>
+
+ <para>
+ Get attribute details record for database
+ <literal>Default</literal>.
+ This query is very useful to study the internal Zebra indexes.
+ If records have been indexed using the <literal>alvis</literal>
+ XSLT filter, the string representation names of the known indexes can be
+ found.
+ <screen>
+ Z> base IR-Explain-1
+ Z> @and @attr exp1 1=1 attributedetails @attr exp1 1=3 Default
+ </screen>
+ Identical query with explicitly specified attribute set:
+ <screen>
+ Z> base IR-Explain-1
+ Z> @attrset exp1 @and @attr 1=1 attributedetails @attr 1=3 Default
+ </screen>
+ </para>
+
+ </sect3>
+ </sect2>
</sect1>
</chapter>
<title>Explain</title>
<para>
Zebra fully supports SRU's core
- <literal>searchRetrieve</literal>
+ <literal>explain</literal>
operation, as described at
<ulink url="http://www.loc.gov/standards/sru/explain/index.html"/>
</para>
<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>