*.php
htmlhelp.hhp
toc.hhc
+manref.xml
-## $Id: Makefile.am,v 1.59 2006-09-04 12:11:40 adam Exp $
+## $Id: Makefile.am,v 1.60 2006-09-05 12:01:31 adam Exp $
docdir=$(datadir)/doc/$(PACKAGE)$(PACKAGE_SUFFIX)
SUBDIRS = common
+XMLMAN = zebraidx.xml zebrasrv.xml idzebra-config.xml
+
XMLFILES = \
administration.xml \
architecture.xml \
examples.xml \
field-structure.xml \
- idzebra-config-man.xml \
indexdata.xml \
installation.xml \
introduction.xml \
quickstart.xml \
recordmodel-alvisxslt.xml \
recordmodel-grs.xml \
- server.xml \
+ manref.xml \
zebra.xml \
- zebraidx-commands.xml \
- zebraidx-man.xml \
- zebraidx-options.xml \
- zebraidx.xml \
- zebrasrv-man.xml \
zebrasrv-options.xml \
zebrasrv-synopsis.xml \
- zebrasrv-virtual.xml
+ zebrasrv-virtual.xml
HTMLFILES = index.html
zebrasrv$(PACKAGE_SUFFIX).8 \
idzebra-config$(PACKAGE_SUFFIX).1
-REFFILES=zebraidx-man.xml zebrasrv-man.xml idzebra-config-man.xml
-
doc_DATA = $(HTMLFILES) $(PNGFILES)
man_MANS = $(MANFILES)
-EXTRA_DIST = $(XMLFILES) $(REFFILES) \
- $(doc_DATA) $(EPSFILES) $(man_MANS) $(REFFILES) \
+EXTRA_DIST = $(XMLFILES) $(XMLMAN) \
+ $(doc_DATA) $(EPSFILES) $(man_MANS) \
marc_indexing.xml entities.ent local.ent.in
-zebraidx$(PACKAGE_SUFFIX).1: zebraidx-man.xml zebraidx-options.xml zebraidx-commands.xml
- $(MAN_COMPILE) $(srcdir)/zebraidx-man.xml
+zebraidx$(PACKAGE_SUFFIX).1: zebraidx.xml
+ $(MAN_COMPILE) $(srcdir)/zebraidx.xml
mv zebraidx.1 zebraidx$(PACKAGE_SUFFIX).1
-zebrasrv$(PACKAGE_SUFFIX).8: zebrasrv-man.xml zebrasrv-options.xml \
+zebrasrv$(PACKAGE_SUFFIX).8: zebrasrv.xml zebrasrv-options.xml \
zebrasrv-synopsis.xml zebrasrv-virtual.xml
- $(MAN_COMPILE) $(srcdir)/zebrasrv-man.xml
+ $(MAN_COMPILE) $(srcdir)/zebrasrv.xml
mv zebrasrv.8 zebrasrv$(PACKAGE_SUFFIX).8
-idzebra-config$(PACKAGE_SUFFIX).1: idzebra-config-man.xml
- $(MAN_COMPILE) $(srcdir)/idzebra-config-man.xml
+idzebra-config$(PACKAGE_SUFFIX).1: idzebra-config.xml
+ $(MAN_COMPILE) $(srcdir)/idzebra-config.xml
mv idzebra-config.1 idzebra-config$(PACKAGE_SUFFIX).1
$(HTMLFILES): $(XMLFILES)
pdfjadetex zebra.tex >/dev/null
pdfjadetex zebra.tex >/dev/null
+
+manref.xml: $(XMLMAN) $(srcdir)/common/ref2dbinc.xsl
+ rm -f manref.xml
+ for i in $(XMLMAN); do \
+ xsltproc $(srcdir)/common/stripref.xsl $(srcdir)/$$i | sed 1d >> manref.xml; \
+ done
+
gils.txt: gils.sgml
sgml2txt -f gils.sgml
<chapter id="administration">
- <!-- $Id: administration.xml,v 1.43 2006-09-03 21:37:26 adam Exp $ -->
+ <!-- $Id: administration.xml,v 1.44 2006-09-05 12:01:31 adam Exp $ -->
<title>Administrating Zebra</title>
<!-- ### It's a bit daft that this chapter (which describes half of
the configuration-file formats) is separated from
</sect2>
</sect1>
-
- <sect1 id="gfs-config">
- <title>YAZ Frontend 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;
-
- <para>
- Section "Virtual Hosts" in the YAZ manual.
- <filename>http://www.indexdata.dk/yaz/doc/server.vhosts.tkl</filename>
- </para>
- </sect1>
-
-
-
</chapter>
<!-- Keep this comment at the end of the file
-<!-- $Id: entities.ent,v 1.3 2006-09-03 21:37:26 adam Exp $ -->
+<!-- $Id: entities.ent,v 1.4 2006-09-05 12:01:31 adam Exp $ -->
<!ENTITY chap-introduction SYSTEM "introduction.xml">
<!ENTITY chap-installation SYSTEM "installation.xml">
<!ENTITY chap-quickstart SYSTEM "quickstart.xml">
<!ENTITY chap-administration SYSTEM "administration.xml">
<!ENTITY chap-querymodel SYSTEM "querymodel.xml">
<!ENTITY chap-zebraidx SYSTEM "zebraidx.xml">
-<!ENTITY chap-server SYSTEM "server.xml">
<!ENTITY chap-recordmodel-grs SYSTEM "recordmodel-grs.xml">
<!ENTITY chap-recordmodel-alvisxslt SYSTEM "recordmodel-alvisxslt.xml">
<!ENTITY chap-field-structure SYSTEM "field-structure.xml">
<!ENTITY app-license SYSTEM "license.xml">
<!ENTITY app-indexdata SYSTEM "indexdata.xml">
-
-<!ENTITY zebraidx-options SYSTEM "zebraidx-options.xml">
-<!ENTITY zebraidx-commands SYSTEM "zebraidx-commands.xml">
+<!ENTITY manref SYSTEM "manref.xml">
<!ENTITY zebrasrv-synopsis SYSTEM "zebrasrv-synopsis.xml">
<!ENTITY zebrasrv-options SYSTEM "zebrasrv-options.xml">
<!ENTITY zebrasrv-virtual SYSTEM "zebrasrv-virtual.xml">
<!ENTITY gfs-synopsis-app "zebrasrv">
-<!ENTITY ref-architecture-representation '
- <xref linkend="architecture-representation"/>'>
-<!ENTITY ref-record-types '
- <xref linkend="record-types"/>'>
-<!ENTITY ref-configuration-file '
- <xref linkend="zebra-cfg"/>'>
-<!ENTITY ref-shadow-registers '
- <xref linkend="shadow-registers"/>'>
<chapter id="fields-and-charsets">
- <!-- $Id: field-structure.xml,v 1.1 2006-09-03 21:37:26 adam Exp $ -->
+ <!-- $Id: field-structure.xml,v 1.2 2006-09-05 12:01:31 adam Exp $ -->
<title>Field Structure and Character Sets
</title>
<variablelist>
<varlistentry>
- <term>index <emphasis>field type code</emphasis></term>
+ <term>index <replaceable>field type code</replaceable></term>
<listitem>
<para>
This directive introduces a new search index code.
The argument is a one-character code to be used in the
.abs files to select this particular index type. An index, roughly,
corresponds to a particular structure attribute during search. Refer
- to <xref linkend="search"/>.
+ to <xref linkend="zebrasrv-search"/>.
</para>
</listitem></varlistentry>
<varlistentry>
- <term>sort <emphasis>field code type</emphasis></term>
+ <term>sort <replaceable>field code type</replaceable></term>
<listitem>
<para>
This directive introduces a
</para>
</listitem></varlistentry>
<varlistentry>
- <term>completeness <emphasis>boolean</emphasis></term>
+ <term>completeness <replaceable>boolean</replaceable></term>
<listitem>
<para>
This directive enables or disables complete field indexing.
- The value of the <emphasis>boolean</emphasis> should be 0
+ The value of the <replaceable>boolean</replaceable> should be 0
(disable) or 1. If completeness is enabled, the index entry will
contain the complete contents of the field (up to a limit), with words
(non-space characters) separated by single space characters
</para>
</listitem></varlistentry>
<varlistentry>
- <term>charmap <emphasis>filename</emphasis></term>
+ <term>charmap <replaceable>filename</replaceable></term>
<listitem>
<para>
This is the filename of the character
<variablelist>
<varlistentry>
- <term>lowercase <emphasis>value-set</emphasis></term>
+ <term>lowercase <replaceable>value-set</replaceable></term>
<listitem>
<para>
This directive introduces the basic value set of the field type.
</para>
</listitem></varlistentry>
<varlistentry>
- <term>uppercase <emphasis>value-set</emphasis></term>
+ <term>uppercase <replaceable>value-set</replaceable></term>
<listitem>
<para>
This directive introduces the
</para>
</listitem></varlistentry>
<varlistentry>
- <term>space <emphasis>value-set</emphasis></term>
+ <term>space <replaceable>value-set</replaceable></term>
<listitem>
<para>
This directive introduces the character
</para>
</listitem></varlistentry>
<varlistentry>
- <term>map <emphasis>value-set</emphasis>
- <emphasis>target</emphasis></term>
+ <term>map <replaceable>value-set</replaceable>
+ <replaceable>target</replaceable></term>
<listitem>
<para>
This directive introduces a mapping between each of the
+++ /dev/null
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
-[
- <!ENTITY % local SYSTEM "local.ent">
- %local;
-]>
-<!-- $Id: idzebra-config-man.xml,v 1.2 2006-08-14 12:18:48 adam Exp $ -->
-<refentry id="idzebra-config">
-
- <refmeta>
- <refentrytitle>idzebra-config</refentrytitle>
- <manvolnum>1</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>idzebra-config</refname>
- <refpurpose>Script to get information about idzebra</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>idzebra-config</command>
- <arg choice="opt"><option>--prefix[=<replaceable>DIR</replaceable>]</option></arg>
- <arg choice="opt"><option>--version</option></arg>
- <arg choice="opt"><option>--libs</option></arg>
- <arg choice="opt"><option>--lalibs</option></arg>
- <arg choice="opt"><option>--cflags</option></arg>
- <arg choice="opt"><option>--tab</option></arg>
- <arg choice="opt"><option>--modules</option></arg>
- <arg choice="opt" rep="repeat">libraries</arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1><title>DESCRIPTION</title>
- <para>
- <command>idzebra-config</command> is a script that returns information
- that your own software should use to build software that uses idzebra.
- </para>
-
- <para>
- The following libraries are supported:
- </para>
-
- <para>
- None
- </para>
-
- </refsect1>
-
- <refsect1><title>OPTIONS</title>
-
- <variablelist>
- <varlistentry>
- <term>--prefix[=<replaceable>DIR</replaceable>]</term>
- <listitem><para>
- Returns prefix of idzebra or assume a different one if DIR is
- specified.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--version</term>
- <listitem><para>
- Returns version of idzebra.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--libs</term>
- <listitem><para>
- Library specification be used when linking with idzebra.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--lalibs</term>
- <listitem><para>
- Return library specification.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--cflags</term>
- <listitem><para>
- Return C Compiler flags.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--tab</term>
- <listitem><para>
- Return directory of idzebra tables.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--modules</term>
- <listitem><para>
- Return directory for Zebra modules.
- </para></listitem>
- </varlistentry>
-
- </variablelist>
- </refsect1>
-
- <refsect1><title>FILES</title>
- <para>
- <filename>&prefix;/bin/idzebra-config-2.0</filename>
- </para>
- <para>
- <filename>&prefix;/lib/libidzebra*2.0.a</filename>
- </para>
- <para>
- <filename>&prefix;/include/idzebra-2.0/idzebra/*.h</filename>
- </para>
- </refsect1>
- <!--
- <refsect1><title>SEE ALSO</title>
- <para>
- yaz(7)
- </para>
- <para>
- Section "How to make apps using YAZ on UNIX" in the YAZ manual.
- </para>
- </refsect1>
- -->
-</refentry>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
-End:
--->
--- /dev/null
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+[
+ <!ENTITY % local SYSTEM "local.ent">
+ %local;
+ <!ENTITY % entities SYSTEM "entities.ent">
+ %entities;
+ <!ENTITY % common SYSTEM "common/common.ent">
+ %common;
+]>
+<!-- $Id: idzebra-config.xml,v 1.1 2006-09-05 12:01:31 adam Exp $ -->
+<refentry id="idzebra-config">
+ <refentryinfo>
+ <productname>ZEBRA</productname>
+ <productnumber>&version;</productnumber>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>idzebra-config</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>idzebra-config</refname>
+ <refpurpose>Script to get information about idzebra</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>idzebra-config</command>
+ <arg choice="opt"><option>--prefix[=<replaceable>DIR</replaceable>]</option></arg>
+ <arg choice="opt"><option>--version</option></arg>
+ <arg choice="opt"><option>--libs</option></arg>
+ <arg choice="opt"><option>--lalibs</option></arg>
+ <arg choice="opt"><option>--cflags</option></arg>
+ <arg choice="opt"><option>--tab</option></arg>
+ <arg choice="opt"><option>--modules</option></arg>
+ <arg choice="opt" rep="repeat">libraries</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ <command>idzebra-config</command> is a script that returns information
+ that your own software should use to build software that uses idzebra.
+ </para>
+
+ <para>
+ The following libraries are supported:
+ </para>
+
+ <para>
+ None
+ </para>
+
+ </refsect1>
+
+ <refsect1><title>OPTIONS</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>--prefix[=<replaceable>DIR</replaceable>]</term>
+ <listitem><para>
+ Returns prefix of idzebra or assume a different one if DIR is
+ specified.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--version</term>
+ <listitem><para>
+ Returns version of idzebra.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--libs</term>
+ <listitem><para>
+ Library specification be used when linking with idzebra.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--lalibs</term>
+ <listitem><para>
+ Return library specification.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--cflags</term>
+ <listitem><para>
+ Return C Compiler flags.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--tab</term>
+ <listitem><para>
+ Return directory of idzebra tables.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--modules</term>
+ <listitem><para>
+ Return directory for Zebra modules.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1><title>FILES</title>
+ <para>
+ <filename>&prefix;/bin/idzebra-config-2.0</filename>
+ </para>
+ <para>
+ <filename>&prefix;/lib/libidzebra*2.0.a</filename>
+ </para>
+ <para>
+ <filename>&prefix;/include/idzebra-2.0/idzebra/*.h</filename>
+ </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-local-catalogs: nil
+sgml-namecase-general:t
+End:
+-->
+++ /dev/null
-<chapter id="zebrasrv">
- <!-- $Id: server.xml,v 1.26 2006-09-03 21:37:27 adam Exp $ -->
- <title>The Z39.50 Server</title>
-
- <sect1 id="zebrasrv-running">
- <title>Running the Z39.50 Server (zebrasrv)</title>
-
- <!--
- FIXME - We need to be consistent here, zebraidx had the options at the
- end, and lots of explaining text before them. Same for zebrasvr! -H
- FIXME - At least we need a small intro, what is zebrasvr, and how it
- can be run (inetd, nt service, stand-alone program, daemon...) -H
- -->
-
- <!-- re-write by MC, using the newly created input files for the
- zebrasrv manpage -->
-
-
- <sect2 id="zebrasrv-description"><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
- boolean search expressions and relevance-ranked free-text queries.
- </para>
- <para>
- <command>zebrasrv</command> is the Z39.50 and <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>/U frontend
- server for the <command>Zebra</command> indexer.
- </para>
- <para>
- On Unix you can run the <command>zebrasrv</command>
- server from the command line - and put it
- in the background. It may also operate under the inet daemon.
- On WIN32 you can run the server as a console application or
- as a WIN32 Service.
- </para>
- </sect2>
-
- <sect2 id="zebrasrv-synopsis">
- <title>Synopsis</title>
- &zebrasrv-synopsis;
- </sect2>
-
- <sect2 id="zebrasrv-options">
- <title>Options</title>
-
- <para>
- The options for <command>zebrasrv</command> are the same
- as those for YAZ' <command>yaz-ztest</command>.
- Option <literal>-c</literal> specifies a Zebra configuration
- file - if omitted <filename>zebra.cfg</filename> is read.
- </para>
-
- &zebrasrv-options;
- </sect2>
-
- <sect2 id="zebrasrv-files"><title>Files</title>
- <para>
- <filename>zebra.cfg</filename>
- </para>
- </sect2>
- <sect2 id="zebrasrv-see-also"><title>See Also</title>
- <para>
- <citerefentry>
- <refentrytitle>zebraidx</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>yaz-ztest</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>
- </para>
- <para>
- The Zebra software is Copyright <command>Index Data</command>
- <filename>http://www.indexdata.dk</filename>
- and distributed under the
- GPLv2 license.
- </para>
- </sect2>
-
- <!--
- <para>
- <emphasis remap="bf">Syntax</emphasis>
-
- <screen>
- zebrasrv [options] [listener-address ...]
- </screen>
-
- </para>
-
- <para>
- <emphasis remap="bf">Options</emphasis>
- <variablelist>
-
- <varlistentry>
- <term>-a <replaceable>APDU file</replaceable></term>
- <listitem>
- <para>
- Specify a file for dumping PDUs (for diagnostic purposes).
- The special name "-" sends output to <literal>stderr</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-c <replaceable>config-file</replaceable></term>
- <listitem>
- <para>
- Read configuration information from
- <replaceable>config-file</replaceable>.
- The default configuration is <literal>./zebra.cfg</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-S</term>
- <listitem>
- <para>
- Don't fork on connection requests. This can be useful for
- symbolic-level debugging. The server can only accept a single
- connection in this mode.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-z</term>
- <listitem>
- <para>
- Use the Z39.50 protocol. Currently the only protocol supported.
- The option is retained for historical reasons, and for future
- extensions.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-l <replaceable>logfile</replaceable></term>
- <listitem>
- <para>
- Specify an output file for the diagnostic messages.
- The default is to write this information to <literal>stderr</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-v <replaceable>log-level</replaceable></term>
- <listitem>
- <para>
- The log level. Use a comma-separated list of members of the set
- {fatal,debug,warn,log,all,none}.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-u <replaceable>username</replaceable></term>
- <listitem>
- <para>
- Set user ID. Sets the real UID of the server process to that of the
- given <replaceable>username</replaceable>.
- It's useful if you aren't comfortable with having the
- server run as root, but you need to start it as such to bind a
- privileged port.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-w <replaceable>working-directory</replaceable></term>
- <listitem>
- <para>
- Change working directory.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-i</term>
- <listitem>
- <para>
- Run under the Internet superserver, <literal>inetd</literal>.
- Make sure you use the logfile option <literal>-l</literal> in
- conjunction with this mode and specify the <literal>-l</literal>
- option before any other options.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-t <replaceable>timeout</replaceable></term>
- <listitem>
- <para>
- Set the idle session timeout (default 60 minutes).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-k <replaceable>kilobytes</replaceable></term>
- <listitem>
- <para>
- Set the (approximate) maximum size of
- present response messages. Default is 1024 KB (1 MB).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- -->
- </sect1>
-
-
- <sect1 id="protocol-support">
- <title>Z39.50 Protocol Support and Behavior</title>
-
- <sect2 id="zebrasrv-initialization">
- <title>Initialization</title>
-
- <para>
- During initialization, the server will negotiate to version 3 of the
- Z39.50 protocol, and the option bits for Search, Present, Scan,
- NamedResultSets, and concurrentOperations will be set, if requested by
- the client. The maximum PDU size is negotiated down to a maximum of
- 1 MB by default.
- </para>
-
- </sect2>
-
- <sect2 id="search">
- <title>Search</title>
-
- <!--
- FIXME - Need to explain the string tag stuff before people get bogged
- down with all these attribute numbers. Perhaps in its own
- chapter? -H
- -->
-
- <para>
- The supported query type are 1 and 101. All operators are currently
- supported with the restriction that only proximity units of type "word"
- are supported for the proximity operator.
- Queries can be arbitrarily complex.
- Named result sets are supported, and result sets can be used as operands
- without limitations.
- Searches may span multiple databases.
- </para>
-
- <para>
- The server has full support for piggy-backed retrieval (see
- also the following section).
- </para>
-
- </sect2>
-
- <sect2 id="zebrasrv-present">
- <title>Present</title>
- <para>
- The present facility is supported in a standard fashion. The requested
- record syntax is matched against the ones supported by the profile of
- each record retrieved. If no record syntax is given, SUTRS is the
- default. The requested element set name, again, is matched against any
- provided by the relevant record profiles.
- </para>
- </sect2>
- <sect2 id="zebrasrv-scan">
- <title>Scan</title>
- <para>
- The attribute combinations provided with the termListAndStartPoint are
- processed in the same way as operands in a query (see above).
- Currently, only the term and the globalOccurrences are returned with
- the termInfo structure.
- </para>
- </sect2>
- <sect2 id="zebrasrv-sort">
- <title>Sort</title>
-
- <para>
- Z39.50 specifies three different types of sort criteria.
- Of these Zebra supports the attribute specification type in which
- case the use attribute specifies the "Sort register".
- Sort registers are created for those fields that are of type "sort" in
- the default.idx file.
- The corresponding character mapping file in default.idx specifies the
- ordinal of each character used in the actual sort.
- </para>
-
- <para>
- Z39.50 allows the client to specify sorting on one or more input
- result sets and one output result set.
- Zebra supports sorting on one result set only which may or may not
- be the same as the output result set.
- </para>
- </sect2>
- <sect2 id="zebrasrv-close">
- <title>Close</title>
- <para>
- If a Close PDU is received, the server will respond with a Close PDU
- with reason=FINISHED, no matter which protocol version was negotiated
- during initialization. If the protocol version is 3 or more, the
- server will generate a Close PDU under certain circumstances,
- including a session timeout (60 minutes by default), and certain kinds of
- protocol errors. Once a Close PDU has been sent, the protocol
- association is considered broken, and the transport connection will be
- closed immediately upon receipt of further data, or following a short
- timeout.
- </para>
- </sect2>
-
- <sect2 id="zebrasrv-explain">
- <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>.
- 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>
- </sect2>
- </sect1>
-</chapter>
-
-
-<chapter id="zebrasrv-sru">
- <title>The SRU/SRW Server</title>
- <para>
- In addition to Z39.50, Zebra supports the more recent and
- web-friendly IR protocol SRU, described at
- <ulink url="http://www.loc.gov/sru"/>.
- SRU is ``Search/Retrieve via URL'', a simple, REST-like protocol
- that uses HTTP GET to request search responses. The request
- itself is made of parameters such as
- <literal>query</literal>,
- <literal>startRecord</literal>,
- <literal>maximumRecords</literal>
- and
- <literal>recordSchema</literal>;
- the response is an XML document containing hit-count, result-set
- records, diagnostics, etc. SRU can be thought of as a re-casting
- of Z39.50 semantics in web-friendly terms; or as a standardisation
- of the ad-hoc query parameters used by search engines such as Google
- and AltaVista; or as a superset of A9's OpenSearch (which it
- predates).
- </para>
- <para>
- Zebra further supports SRW, described at
- <ulink url="http://www.loc.gov/srw"/>.
- SRW is the ``Search/Retrieve Web Service'', a SOAP-based alternative
- implementation of the abstract protocol that SRU implements as HTTP
- GET requests. In SRW, requests are encoded as XML documents which
- are posted to the server. The responses are identical to those
- returned by SRU servers, except that they are wrapped in a several
- layers of SOAP envelope.
- </para>
- <para>
- Zebra supports all three protocols - Z39.50, SRU and SRW - on the
- same port, recognising what protocol is used by each incoming
- requests and handling them accordingly. This is a achieved through
- the use of Deep Magic; civilians are warned not to stand too close.
- </para>
- <para>
- From here on, ``SRU'' is used to indicate both the SRU and SRW
- protocols, as they are identical except for the transport used for
- the protocol packets and Zebra's support for them is equivalent.
- </para>
-
- <sect1 id="zebrasrv-sru-run">
- <title>Running the SRU Server (zebrasrv)</title>
- <para>
- Because Zebra supports all three protocols on one port, it would
- seem to follow that the SRU server is run in the same way as
- the Z39.50 server, as described above. This is true, but only in
- an uninterestingly vacuous way: a Zebra server run in this manner
- will indeed recognise and accept SRU requests; but since it
- doesn't know how to handle the CQL queries that these protocols
- use, all it can do is send failure responses.
- </para>
- <note>
- <para>
- It is possible to cheat, by having SRU search Zebra with
- a PQF query instead of CQL, using the
- <literal>x-pquery</literal>
- parameter instead of
- <literal>query</literal>.
- This is a
- <emphasis role="strong">non-standard extension</emphasis>
- of CQL, and a
- <emphasis role="strong">very naughty</emphasis>
- thing to do, but it does give you a way to see Zebra serving SRU
- ``right out of the box''. If you start your favourite Zebra
- server in the usual way, on port 9999, then you can send your web
- browser to:
- </para>
- <screen>
- 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
- first record in the result-set found by the query
- <literal>mineral</literal>. (For clarity, the SRU URL is shown
- here broken across lines, but the lines should be joined to gether
- to make single-line URL for the browser to submit.)
- </para>
- </note>
- <para>
- In order to turn on Zebra's support for CQL queries, it's necessary
- to have the YAZ generic front-end (which Zebra uses) translate them
- into the Z39.50 Type-1 query format that is used internally. And
- to do this, the generic front-end's own configuration file must be
- used. This file is described
- <link linkend="gfs-config">elsewhere</link>;
- the salient point for SRU support is that
- <command>zebrasrv</command>
- must be started with the
- <literal>-f frontendConfigFile</literal>
- option rather than the
- <literal>-c zebraConfigFile</literal>
- option,
- and that the front-end configuration file must include both a
- reference to the Zebra configuration file and the CQL-to-PQF
- translator configuration file.
- </para>
- <para>
- A minimal front-end configuration file that does this would read as
- follows:
- </para>
- <screen><![CDATA[
- <yazgfs>
- <server>
- <config>zebra.cfg</config>
- <cql2rpn>../../tab/pqf.properties</cql2rpn>
- </server>
- </yazgfs>
-]]></screen>
- <para>
- The
- <literal><config></literal>
- element contains the name of the Zebra configuration file that was
- previously specified by the
- <literal>-c</literal>
- command-line argument, and the
- <literal><cql2rpn></literal>
- element contains the name of the CQL properties file specifying how
- 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="zebrasrv-sru-support">
- <title>SRU and SRW Protocol Support and Behavior</title>
- <para>
- Zebra running as an SRU server supports SRU version 1.1, including
- CQL version 1.1. In particular, it provides support for the
- following elements of the protocol.
- </para>
-
- <sect2 id="zebrasrvr-search-and-retrieval">
- <title>Search and Retrieval</title>
- <para>
- Zebra fully supports SRU's core
- <literal>searchRetrieve</literal>
- operation, as described at
- <ulink url="http://www.loc.gov/standards/sru/sru-spec.html"/>
- </para>
- <para>
- One of the great strengths of SRU is that it mandates a standard
- query language, CQL, and that all conforming implementations can
- therefore be trusted to correctly interpret the same queries. It
- 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"/>).
- 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 id="zebrasrv-scan">
- <title>Scan</title>
- <para>
- Zebra supports SRU's
- <literal>scan</literal>
- operation, as described at
- <ulink url="http://www.loc.gov/standards/sru/scan/"/>.
- Scanning using CQL syntax is the default, where the
- standard <literal>scanClause</literal> parameter is used.
- </para>
- <para>
- In addition, a
- mutant form of SRU scan is 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 id="zebrasrv-explain">
- <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 id="zebrasrv-sru-examples">
- <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 id="zebrasrv-non-sru-ops">
- <title>Initialization, Present, Sort, Close</title>
- <para>
- In the Z39.50 protocol, Initialization, Present, Sort and Close
- are separate operations. In SRU, however, these operations do not
- exist.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- SRU has no explicit initialization handshake phase, but
- commences immediately with searching, scanning and explain
- operations.
- </para>
- </listitem>
- <listitem>
- <para>
- Neither does SRU have a close operation, since the protocol is
- stateless and each request is self-contained. (It is true that
- multiple SRU request/response pairs may be implemented as
- multiple HTTP request/response pairs over a single persistent
- TCP/IP connection; but the closure of that connection is not a
- protocol-level operation.)
- </para>
- </listitem>
- <listitem>
- <para>
- Retrieval in SRU is part of the
- <literal>searchRetrieve</literal> operation, in which a search
- is submitted and the response includes a subset of the records
- in the result set. There is no direct analogue of Z39.50's
- Present operation which requests records from an established
- result set. In SRU, this is achieved by sending a subsequent
- <literal>searchRetrieve</literal> request with the query
- <literal>cql.resultSetId=</literal><emphasis>id</emphasis> where
- <emphasis>id</emphasis> is the identifier of the previously
- generated result-set.
- </para>
- </listitem>
- <listitem>
- <para>
- Sorting in CQL is done within the
- <literal>searchRetrieve</literal> operation - in v1.1, by an
- explicit <literal>sort</literal> parameter, but the forthcoming
- v1.2 or v2.0 will most likely use an extension of the query
- language, CQL for sorting: see
- <ulink url="http://zing.z3950.org/cql/sorting.html"/>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- It can be seen, then, that while Zebra operating as an SRU server
- does not provide the same set of operations as when operating as a
- Z39.50 server, it does provide equivalent functionality.
- </para>
- </sect2>
- </sect1>
-</chapter>
-
- <!-- Keep this comment at the end of the file
- Local variables:
- mode: sgml
- sgml-omittag:t
- sgml-shorttag:t
- sgml-minimize-attributes:nil
- sgml-always-quote-attributes:t
- sgml-indent-step:1
- sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
- sgml-local-catalogs: nil
- sgml-namecase-general:t
- End:
- -->
[
<!ENTITY % local SYSTEM "local.ent">
%local;
- <!ENTITY % entities SYSTEM "entities.ent">
+ <!ENTITY % entities SYSTEM "entities.ent">
%entities;
- <!ENTITY % common SYSTEM "common/common.ent">
+ <!ENTITY % common SYSTEM "common/common.ent">
%common;
+
+ <!ENTITY test SYSTEM "test.xml">
]>
-<!-- $Id: zebra.xml,v 1.8 2006-09-03 21:37:27 adam Exp $ -->
+<!-- $Id: zebra.xml,v 1.9 2006-09-05 12:01:31 adam Exp $ -->
<book id="zebra">
<bookinfo>
<title>Zebra - User's Guide and Reference</title>
&chap-recordmodel-grs;
&chap-recordmodel-alvisxslt;
&chap-field-structure;
- &chap-zebraidx;
- &chap-server;
- &app-license;
- &app-indexdata;
+
+ <reference>
+ <title>Reference</title>
+ &manref;
+ </reference>
+
+ &app-license;
+ &app-indexdata;
</book>
<!-- Keep this comment at the end of the file
+++ /dev/null
-<!--
- $Id: zebraidx-commands.xml,v 1.4 2006-04-25 12:26:27 marc Exp $
- Commands for zebraidx.
- Included in both manual and man page for zebraidx
--->
-<variablelist>
- <varlistentry>
- <term>update <replaceable>directory</replaceable></term>
- <listitem>
- <para>
- Update the register with the files contained in
- <replaceable>directory</replaceable>.
- If no directory is provided, a list of files is read from
- <literal>stdin</literal>.
- See <xref linkend="administration"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>delete <replaceable>directory</replaceable></term>
- <listitem>
- <para>
- Remove the records corresponding to the files found under
- <replaceable>directory</replaceable> from the register.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>commit</term>
- <listitem>
- <para>
- Write the changes resulting from the last <literal>update</literal>
- commands to the register. This command is only available if the use of
- shadow register files is enabled
- (see <xref linkend="shadow-registers"/>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>clean</term>
- <listitem><para>
- Clean shadow files and "forget" changes.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>create <replaceable>database</replaceable></term>
- <listitem><para>
- Create database.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>drop <replaceable>database</replaceable></term>
- <listitem><para>
- Drop database (delete database).
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>init</term>
- <listitem><para>
- Deletes an entire register (all files in shadow+register areas).
- </para></listitem>
- </varlistentry>
-</variablelist>
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document: "zebra.xml"
-sgml-local-catalogs: nil
-sgml-namecase-general:t
-End:
--->
+++ /dev/null
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
-[
- <!ENTITY zebraidx-options SYSTEM "zebraidx-options.xml">
- <!ENTITY zebraidx-commands SYSTEM "zebraidx-commands.xml">
- <!ENTITY % ref-head "the section entitled">
- <!ENTITY % ref-tail "in <citetitle>Zebra - User's Guide
- and Reference</citetitle>">
-
- <!ENTITY ref-architecture-representation "">
- <!ENTITY ref-local-representation "<citetitle>Local Representation</citetitle>">
- <!ENTITY ref-record-types "<citetitle>Record Types</citetitle>">
- <!ENTITY ref-configuration-file "<citetitle>The Zebra Configuration File</citetitle>">
- <!ENTITY ref-shadow-registers "<citetitle>Safe Updating - Using Shadow
- Registers</citetitle>">
-]>
-<!-- $Id: zebraidx-man.xml,v 1.1 2006-05-24 19:12:46 adam Exp $ -->
-<refentry id="zebraidx">
-
- <refmeta>
- <refentrytitle>zebraidx</refentrytitle>
- <manvolnum>1</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>zebraidx</refname>
- <refpurpose>Zebra Administrative Tool</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>zebraidx</command>
- <arg choice="opt"><option>-t <replaceable>type</replaceable></option></arg>
- <arg choice="opt"><option>-c <replaceable>config</replaceable></option></arg>
- <arg choice="opt"><option>-g <replaceable>group</replaceable></option></arg>
- <arg choice="opt"><option>-d <replaceable>database</replaceable></option></arg>
- <arg choice="opt"><option>-m <replaceable>mbytes</replaceable></option></arg>
- <arg choice="opt"><option>-n</option></arg>
- <arg choice="opt"><option>-s</option></arg>
- <arg choice="opt"><option>-v <replaceable>level</replaceable></option></arg>
- <arg choice="opt"><option>-l <replaceable>file</replaceable></option></arg>
- <arg choice="opt"><option>-L</option></arg>
- <arg choice="opt"><option>-f <replaceable>number</replaceable></option></arg>
- <arg choice="opt"><option>-v</option></arg>
- <arg choice="req"><replaceable>command</replaceable></arg>
- <arg choice="opt" rep="repeat"><replaceable>file</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1><title>DESCRIPTION</title>
- <para>
- <command>zebraidx</command> allows you to insert, delete or updates
- records in Zebra. <command>zebraidx</command> accepts a set options
- (see below) and exactly one command (mandatory).
- </para>
- </refsect1>
- <refsect1>
- <title>COMMANDS</title>
- &zebraidx-commands;
- </refsect1>
- <refsect1>
- <title>OPTIONS</title>
- &zebraidx-options;
- </refsect1>
- <refsect1><title>FILES</title>
- <para>
- <filename>zebra.cfg</filename>
- </para>
- </refsect1>
- <refsect1><title>SEE ALSO</title>
- <para>
- <citerefentry>
- <refentrytitle>zebrasrv</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>
- </para>
- <para id="shadow-registers">
- See "shadow registers" in Zebra manual
- </para>
- <para id="administration">
- See "administration" in Zebra manual
- </para>
- </refsect1>
-</refentry>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
-End:
--->
+++ /dev/null
-<!--
- $Id: zebraidx-options.xml,v 1.6 2006-04-25 12:26:27 marc Exp $
- Options for zebraidx.
- Included in both manual and man page for zebraidx
--->
-<variablelist>
-
- <varlistentry>
- <term>-t <replaceable>type</replaceable></term>
- <listitem>
- <para>
- Update all files as <replaceable>type</replaceable>. Currently, the
- types supported are <literal>text</literal> and
- <literal>grs</literal><replaceable>.subtype</replaceable>.
- If no <replaceable>subtype</replaceable> is provided for the GRS
- (General Record Structure) type, the canonical input format
- is assumed (see &ref-architecture-representation;).
- Generally, it is probably advisable to specify the record types
- in the <literal>zebra.cfg</literal> file (see
- &ref-record-types;), to avoid confusion at
- subsequent updates.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-c <replaceable>config-file</replaceable></term>
- <listitem>
- <para>
- Read the configuration file
- <replaceable>config-file</replaceable> instead of
- <literal>zebra.cfg</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-g <replaceable>group</replaceable></term>
- <listitem>
- <para>
- Update the files according to the group
- settings for <replaceable>group</replaceable>
- (see &ref-configuration-file;).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-d <replaceable>database</replaceable></term>
- <listitem>
- <para>
- The records located should be associated with the database name
- <replaceable>database</replaceable> for access through the Z39.50 server.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-l <replaceable>file</replaceable></term>
- <listitem>
- <para>
- Write log messages to <replaceable>file</replaceable> instead
- of <literal>stderr</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-m <replaceable>mbytes</replaceable></term>
- <listitem>
- <para>
- Use <replaceable>mbytes</replaceable> of memory before flushing
- keys to background storage. This setting affects performance when
- updating large databases.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-L</term>
- <listitem>
- <para>
- Makes zebraidx skip symbolic links. By default, zebraidx follows
- them.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-n</term>
- <listitem>
- <para>
- Disable the use of shadow registers for this operation
- (see &ref-shadow-registers;).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-s</term>
- <listitem>
- <para>
- Show analysis of the indexing process. The maintenance
- program works in a read-only mode and doesn't change the state
- of the index. This options is very useful when you wish to test a
- new profile.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-V</term>
- <listitem>
- <para>
- Show Zebra version.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-v <replaceable>level</replaceable></term>
- <listitem>
- <para>
- Set the log level to <replaceable>level</replaceable>.
- <replaceable>level</replaceable> should be one of
- <literal>none</literal>, <literal>debug</literal>, and
- <literal>all</literal>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document: "zebra.xml"
-sgml-local-catalogs: nil
-sgml-namecase-general:t
-End:
--->
-<chapter id="zebraidx">
- <!-- $Id: zebraidx.xml,v 1.8 2006-04-25 12:26:27 marc Exp $ -->
- <title>Running the Maintenance Interface (zebraidx)</title>
-
- <para>
- The following is a complete reference to the command line interface to
- the <literal>zebraidx</literal> application.
- </para>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+[
+ <!ENTITY % local SYSTEM "local.ent">
+ %local;
+ <!ENTITY % entities SYSTEM "entities.ent">
+ %entities;
+ <!ENTITY % common SYSTEM "common/common.ent">
+ %common;
+]>
+<!-- $Id: zebraidx.xml,v 1.9 2006-09-05 12:01:31 adam Exp $ -->
+<refentry id="zebraidx">
+ <refentryinfo>
+ <productname>ZEBRA</productname>
+ <productnumber>&version;</productnumber>
+ </refentryinfo>
- <para>
- Syntax
- </para>
-
+ <refmeta>
+ <refentrytitle>zebraidx</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>zebraidx</refname>
+ <refpurpose>Zebra Administrative Tool</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
<cmdsynopsis>
<command>zebraidx</command>
<arg choice="opt"><option>-t <replaceable>type</replaceable></option></arg>
<arg choice="req"><replaceable>command</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>file</replaceable></arg>
</cmdsynopsis>
-
- <!-- ### swap order of commands and options -->
+ </refsynopsisdiv>
- <para>
- Commands
- &zebraidx-commands;
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ <command>zebraidx</command> allows you to insert, delete or updates
+ records in Zebra. <command>zebraidx</command> accepts a set options
+ (see below) and exactly one command (mandatory).
</para>
+ </refsect1>
+ <refsect1>
+ <title>COMMANDS</title>
+ <variablelist>
+ <varlistentry>
+ <term>update <replaceable>directory</replaceable></term>
+ <listitem>
+ <para>
+ Update the register with the files contained in
+ <replaceable>directory</replaceable>.
+ If no directory is provided, a list of files is read from
+ <literal>stdin</literal>.
+ See <link linkend="administration">Administration</link> in the Zebra
+ Manual.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>delete <replaceable>directory</replaceable></term>
+ <listitem>
+ <para>
+ Remove the records corresponding to the files found under
+ <replaceable>directory</replaceable> from the register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>commit</term>
+ <listitem>
+ <para>
+ Write the changes resulting from the last <literal>update</literal>
+ commands to the register. This command is only available if the use of
+ shadow register files is enabled
+ (see <link linkend="shadow-registers">Shadow Registers</link> in the
+ Zebra Manual).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>clean</term>
+ <listitem><para>
+ Clean shadow files and "forget" changes.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>create <replaceable>database</replaceable></term>
+ <listitem><para>
+ Create database.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>drop <replaceable>database</replaceable></term>
+ <listitem><para>
+ Drop database (delete database).
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>init</term>
+ <listitem><para>
+ Deletes an entire register (all files in shadow+register areas).
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>OPTIONS</title>
+ <variablelist>
+
+ <varlistentry>
+ <term>-t <replaceable>type</replaceable></term>
+ <listitem>
+ <para>
+ Update all files as <replaceable>type</replaceable>. Currently, the
+ types supported are <literal>text</literal>, <literal>alvis</literal>
+ and <literal>grs</literal><replaceable>.subtype</replaceable>.
+ Generally, it is probably advisable to specify the record types
+ in the <literal>zebra.cfg</literal> file (see
+ <link linkend="record-types">Record Types</link> in the Zebra manual),
+ to avoid confusion at subsequent updates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-c <replaceable>config-file</replaceable></term>
+ <listitem>
+ <para>
+ Read the configuration file
+ <replaceable>config-file</replaceable> instead of
+ <literal>zebra.cfg</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-g <replaceable>group</replaceable></term>
+ <listitem>
+ <para>
+ Update the files according to the group
+ settings for <replaceable>group</replaceable>
+ (see <link linkend="zebra-cfg">Zebra Configuration File</link> in
+ the Zebra manual).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-d <replaceable>database</replaceable></term>
+ <listitem>
+ <para>
+ The records located should be associated with the database name
+ <replaceable>database</replaceable> for access through the Z39.50 server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-l <replaceable>file</replaceable></term>
+ <listitem>
+ <para>
+ Write log messages to <replaceable>file</replaceable> instead
+ of <literal>stderr</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-m <replaceable>mbytes</replaceable></term>
+ <listitem>
+ <para>
+ Use <replaceable>mbytes</replaceable> of memory before flushing
+ keys to background storage. This setting affects performance when
+ updating large databases.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-L</term>
+ <listitem>
+ <para>
+ Makes zebraidx skip symbolic links. By default, zebraidx follows
+ them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-n</term>
+ <listitem>
+ <para>
+ Disable the use of shadow registers for this operation
+ (see <link linkend="shadow-registers">Shadow Registers in
+ the Zebra manual</link>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-s</term>
+ <listitem>
+ <para>
+ Show analysis of the indexing process. The maintenance
+ program works in a read-only mode and doesn't change the state
+ of the index. This options is very useful when you wish to test a
+ new profile.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-V</term>
+ <listitem>
+ <para>
+ Show Zebra version.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-v <replaceable>level</replaceable></term>
+ <listitem>
+ <para>
+ Set the log level to <replaceable>level</replaceable>.
+ <replaceable>level</replaceable> should be one of
+ <literal>none</literal>, <literal>debug</literal>, and
+ <literal>all</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1><title>FILES</title>
<para>
- Options:
- &zebraidx-options;
- </para>
+ <filename>zebra.cfg</filename>
+ </para>
+ </refsect1>
+ <refsect1><title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>zebrasrv</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+</refsect1>
+</refentry>
-</chapter>
- <!-- Keep this comment at the end of the file
- Local variables:
- mode: sgml
- sgml-omittag:t
- sgml-shorttag:t
- sgml-minimize-attributes:nil
- sgml-always-quote-attributes:t
- sgml-indent-step:1
- sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
- sgml-local-catalogs: nil
- sgml-namecase-general:t
- End:
- -->
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-local-catalogs: nil
+sgml-namecase-general:t
+End:
+-->
+++ /dev/null
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
-[
- <!ENTITY % local SYSTEM "local.ent">
- %local;
- <!ENTITY % entities SYSTEM "entities.ent">
- %entities;
- <!ENTITY % common SYSTEM "common/common.ent">
- %common;
- <!ENTITY zebrasrv-synopsis SYSTEM "zebrasrv-synopsis.xml">
- <!ENTITY zebrasrv-options SYSTEM "zebrasrv-options.xml">
- <!ENTITY zebrasrv-virtual SYSTEM "zebrasrv-virtual.xml">
- <!ENTITY gfs-synopsis-app "zebrasrv">
- <!ENTITY reference-tools-cql-map 'section "Specifiction of CQL to RPN mappings"'>
-]>
-
- <!-- <!ENTITY zebrasrv-commands SYSTEM "zebrasrv-commands.xml"> -->
-
-
-<!-- $Id: zebrasrv-man.xml,v 1.2 2006-06-13 13:45:08 marc Exp $ -->
-<refentry id="zebrasrv">
-
- <refmeta>
- <refentrytitle>zebrasrv</refentrytitle>
- <manvolnum>8</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>zebrasrv</refname>
- <refpurpose>Zebra Server</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <!--
- <cmdsynopsis>
- <command>zebrasrv</command>
- <arg choice="opt"><option>-a <replaceable>file</replaceable></option></arg>
- <arg choice="opt"><option>-v <replaceable>level</replaceable></option></arg>
- <arg choice="opt"><option>-l <replaceable>file</replaceable></option></arg>
- <arg choice="opt"><option>-u <replaceable>uid</replaceable></option></arg>
- <arg choice="opt"><option>-c <replaceable>config</replaceable></option></arg>
- <arg choice="opt"><option>-t <replaceable>minutes</replaceable></option></arg>
- <arg choice="opt"><option>-k <replaceable>kilobytes</replaceable></option></arg>
- <arg choice="opt"><option>-d <replaceable>daemon</replaceable></option></arg>
- <arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
- <arg choice="opt"><option>-ziST1</option></arg>
- <arg choice="opt" rep="repeat">listener-spec</arg>
- </cmdsynopsis>
- -->
- &zebrasrv-synopsis;
- </refsynopsisdiv>
- <refsect1><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
- boolean search expressions and relevance-ranked free-text queries.
- </para>
- <para>
- <command>zebrasrv</command> is the Z39.50 and SRW/U frontend
- server for the <command>Zebra</command> indexer.
- </para>
- <para>
- On Unix you can run the <command>zebrasrv</command>
- server from the command line - and put it
- in the background. It may also operate under the inet daemon.
- On WIN32 you can run the server as a console application or
- as a WIN32 Service.
- </para>
- </refsect1>
- <!--
- <refsect1>
- <title>COMMANDS</title>
- &zebrasrv-commands;
- </refsect1>
- -->
- <refsect1>
- <title>OPTIONS</title>
-
- <para>
- The options for <command>zebrasrv</command> are the same
- as those for YAZ' <command>yaz-ztest</command>.
- Option <literal>-c</literal> specifies a Zebra configuration
- file - if omitted <filename>zebra.cfg</filename> is read.
- </para>
-
- &zebrasrv-options;
- </refsect1>
- <refsect1><title>VIRTUAL HOSTS</title>
- <para>
- <command>zebrasrv</command> uses the YAZ server
- </para>
- &zebrasrv-virtual;
- </refsect1>
- <refsect1><title>FILES</title>
- <para>
- <filename>zebra.cfg</filename>
- </para>
- </refsect1>
- <refsect1><title>SEE ALSO</title>
- <para>
- <citerefentry>
- <refentrytitle>zebraidx</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>yaz-ztest</refentrytitle>
- <manvolnum>8</manvolnum>
- </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 CQL 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
- GPLv2 license.
- </para>
- </refsect1>
-</refentry>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
-End:
--->
<!--
- $Id: zebrasrv-options.xml,v 1.5 2006-04-25 12:26:27 marc Exp $
+ $Id: zebrasrv-options.xml,v 1.6 2006-09-05 12:01:31 adam Exp $
Options for generic frontend server and yaz-ztest.
Included in both manual and man page for yaz-ztest
Note - these files have been altered for zebrasrv, and are not in
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
-sgml-parent-document: "yaz.xml"
+sgml-parent-document: "zebrasrv.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
<!--
- $Id: zebrasrv-synopsis.xml,v 1.3 2006-04-25 12:26:27 marc Exp $
+ $Id: zebrasrv-synopsis.xml,v 1.4 2006-09-05 12:01:31 adam Exp $
cmd description of YAZ GFS application.
Included in both manual and man page for yaz-ztest
-->
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
-sgml-parent-document: "yaz.xml"
+sgml-parent-document: "zebrasrv.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
<!--
- $Id: zebrasrv-virtual.xml,v 1.7 2006-06-13 13:45:08 marc Exp $
+ $Id: zebrasrv-virtual.xml,v 1.8 2006-09-05 12:01:31 adam Exp $
Description of the virtual host mechanism in YAZ GFS
Included in both manual and man page for yaz-ztest
-->
<para>
A backend can be configured to execute in a particular working
directory. Or the YAZ frontend may perform <ulink url="&url.cql;">CQL</ulink> to RPN conversion, thus
- allowing traditional Z39.50 backends to be offered as a <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>/ <ulink url="&url.sru;">SRU</ulink>
- service. <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>/ <ulink url="&url.sru;">SRU</ulink> Explain information for a particular backend may also
- be specified.
+ allowing traditional Z39.50 backends to be offered as a
+<ulink url="&url.sru;">SRU</ulink> service.
+ SRU Explain information for a particular backend may also be specified.
</para>
<para>
For the HTTP protocol, the virtual host is specified in the Host header.
<varlistentry><term>element <literal>explain</literal> (optional)</term>
<listitem>
<para>
- Specifies <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>/ <ulink url="&url.sru;">SRU</ulink> ZeeRex content for this server. Copied verbatim
- to the client. As things are now, some of the Explain content
- seems redundant because host information, etc. is also stored
- elsewhere.
+ Specifies <ulink url="&url.sru;">SRU</ulink> ZeeRex content for this
+ server - copied verbatim to the client.
+ As things are now, some of the Explain content seems redundant
+ because host information, etc. is also stored elsewhere.
</para>
<para>
The format of the Explain record is described in detail, with
- examples, on the file ZeeRex web-site,
- <ulink url="http://explain.z3950.org/"></ulink>.
+ examples, on the file at the
+ <ulink url="&url.zeerex.explain;">ZeeRex</ulink> web-site.
</para>
</listitem>
</varlistentry>
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
-sgml-parent-document: "yaz.xml"
+sgml-parent-document: "zebrasrv.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
--- /dev/null
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+[
+ <!ENTITY % local SYSTEM "local.ent">
+ %local;
+ <!ENTITY % entities SYSTEM "entities.ent">
+ %entities;
+ <!ENTITY % common SYSTEM "common/common.ent">
+ %common;
+]>
+ <!-- $Id: zebrasrv.xml,v 1.1 2006-09-05 12:01:31 adam Exp $ -->
+<refentry id="zebrasrv">
+ <refentryinfo>
+ <productname>ZEBRA</productname>
+ <productnumber>&version;</productnumber>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>zebrasrv</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>zebrasrv</refname>
+ <refpurpose>Zebra Server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ &zebrasrv-synopsis;
+ </refsynopsisdiv>
+ <refsect1><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
+ boolean search expressions and relevance-ranked free-text queries.
+ </para>
+ <para>
+ <command>zebrasrv</command> is the Z39.50 and SRU frontend
+ server for the <command>Zebra</command> search engine and indexer.
+ </para>
+ <para>
+ On Unix you can run the <command>zebrasrv</command>
+ server from the command line - and put it
+ in the background. It may also operate under the inet daemon.
+ On WIN32 you can run the server as a console application or
+ as a WIN32 Service.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>OPTIONS</title>
+
+ <para>
+ The options for <command>zebrasrv</command> are the same
+ as those for YAZ' <command>yaz-ztest</command>.
+ Option <literal>-c</literal> specifies a Zebra configuration
+ file - if omitted <filename>zebra.cfg</filename> is read.
+ </para>
+
+ &zebrasrv-options;
+ </refsect1>
+
+ <refsect1 id="protocol-support">
+ <title>Z39.50 Protocol Support and Behavior</title>
+
+ <refsect2 id="zebrasrv-initialization">
+ <title>Z39.50 Initialization</title>
+
+ <para>
+ During initialization, the server will negotiate to version 3 of the
+ Z39.50 protocol, and the option bits for Search, Present, Scan,
+ NamedResultSets, and concurrentOperations will be set, if requested by
+ the client. The maximum PDU size is negotiated down to a maximum of
+ 1 MB by default.
+ </para>
+
+ </refsect2>
+
+ <refsect2 id="zebrasrv-search">
+ <title>Z39.50 Search</title>
+
+ <para>
+ The supported query type are 1 and 101. All operators are currently
+ supported with the restriction that only proximity units of type "word"
+ are supported for the proximity operator.
+ Queries can be arbitrarily complex.
+ Named result sets are supported, and result sets can be used as operands
+ without limitations.
+ Searches may span multiple databases.
+ </para>
+
+ <para>
+ The server has full support for piggy-backed retrieval (see
+ also the following section).
+ </para>
+
+ </refsect2>
+
+ <refsect2 id="zebrasrv-present">
+ <title>Z39.50 Present</title>
+ <para>
+ The present facility is supported in a standard fashion. The requested
+ record syntax is matched against the ones supported by the profile of
+ each record retrieved. If no record syntax is given, SUTRS is the
+ default. The requested element set name, again, is matched against any
+ provided by the relevant record profiles.
+ </para>
+ </refsect2>
+ <refsect2 id="zebrasrv-scan">
+ <title>Z39.50 Scan</title>
+ <para>
+ The attribute combinations provided with the termListAndStartPoint are
+ processed in the same way as operands in a query (see above).
+ Currently, only the term and the globalOccurrences are returned with
+ the termInfo structure.
+ </para>
+ </refsect2>
+ <refsect2 id="zebrasrv-sort">
+ <title>Z39.50 Sort</title>
+
+ <para>
+ Z39.50 specifies three different types of sort criteria.
+ Of these Zebra supports the attribute specification type in which
+ case the use attribute specifies the "Sort register".
+ Sort registers are created for those fields that are of type "sort" in
+ the default.idx file.
+ The corresponding character mapping file in default.idx specifies the
+ ordinal of each character used in the actual sort.
+ </para>
+
+ <para>
+ Z39.50 allows the client to specify sorting on one or more input
+ result sets and one output result set.
+ Zebra supports sorting on one result set only which may or may not
+ be the same as the output result set.
+ </para>
+ </refsect2>
+ <refsect2 id="zebrasrv-close">
+ <title>Z39.50 Close</title>
+ <para>
+ If a Close PDU is received, the server will respond with a Close PDU
+ with reason=FINISHED, no matter which protocol version was negotiated
+ during initialization. If the protocol version is 3 or more, the
+ server will generate a Close PDU under certain circumstances,
+ including a session timeout (60 minutes by default), and certain kinds of
+ protocol errors. Once a Close PDU has been sent, the protocol
+ association is considered broken, and the transport connection will be
+ closed immediately upon receipt of further data, or following a short
+ timeout.
+ </para>
+ </refsect2>
+
+ <refsect2 id="zebrasrv-explain">
+ <title>Z39.50 Explain</title>
+ <para>
+ Zebra maintains a "classic"
+ <ulink url="&url.z39.50.explain;">Z39.50 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>.
+ 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>
+ </refsect2>
+ </refsect1>
+ <refsect1 id="zebrasrv-sru">
+ <title>The SRU Server</title>
+ <para>
+ In addition to Z39.50, Zebra supports the more recent and
+ web-friendly IR protocol <ulink url="&url.sru;">SRU</ulink>.
+ SRU can be carried over SOAP or a REST-like protocol
+ that uses HTTP GET or POST to request search responses. The request
+ itself is made of parameters such as
+ <literal>query</literal>,
+ <literal>startRecord</literal>,
+ <literal>maximumRecords</literal>
+ and
+ <literal>recordSchema</literal>;
+ the response is an XML document containing hit-count, result-set
+ records, diagnostics, etc. SRU can be thought of as a re-casting
+ of Z39.50 semantics in web-friendly terms; or as a standardisation
+ of the ad-hoc query parameters used by search engines such as Google
+ and AltaVista; or as a superset of A9's OpenSearch (which it
+ predates).
+ </para>
+ <para>
+ Zebra supports Z39.50, SRU GET, SRU POST, SRU SOAP (SRW)
+ - on the same port, recognising what protocol is used by each incoming
+ requests and handling them accordingly. This is a achieved through
+ the use of Deep Magic; civilians are warned not to stand too close.
+ </para>
+ <refsect2 id="zebrasrv-sru-run">
+ <title>Running zebrasrv as an SRU Server</title>
+ <para>
+ Because Zebra supports all protocols on one port, it would
+ seem to follow that the SRU server is run in the same way as
+ the Z39.50 server, as described above. This is true, but only in
+ an uninterestingly vacuous way: a Zebra server run in this manner
+ will indeed recognise and accept SRU requests; but since it
+ doesn't know how to handle the CQL queries that these protocols
+ use, all it can do is send failure responses.
+ </para>
+ <note>
+ <para>
+ It is possible to cheat, by having SRU search Zebra with
+ a PQF query instead of CQL, using the
+ <literal>x-pquery</literal>
+ parameter instead of
+ <literal>query</literal>.
+ This is a
+ <emphasis role="strong">non-standard extension</emphasis>
+ of CQL, and a
+ <emphasis role="strong">very naughty</emphasis>
+ thing to do, but it does give you a way to see Zebra serving SRU
+ ``right out of the box''. If you start your favourite Zebra
+ server in the usual way, on port 9999, then you can send your web
+ browser to:
+ </para>
+ <screen>
+ 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
+ first record in the result-set found by the query
+ <literal>mineral</literal>. (For clarity, the SRU URL is shown
+ here broken across lines, but the lines should be joined to gether
+ to make single-line URL for the browser to submit.)
+ </para>
+ </note>
+ <para>
+ In order to turn on Zebra's support for CQL queries, it's necessary
+ to have the YAZ generic front-end (which Zebra uses) translate them
+ into the Z39.50 Type-1 query format that is used internally. And
+ to do this, the generic front-end's own configuration file must be
+ used. See <xref linkend="gfs-config"/>;
+ the salient point for SRU support is that
+ <command>zebrasrv</command>
+ must be started with the
+ <literal>-f frontendConfigFile</literal>
+ option rather than the
+ <literal>-c zebraConfigFile</literal>
+ option,
+ and that the front-end configuration file must include both a
+ reference to the Zebra configuration file and the CQL-to-PQF
+ translator configuration file.
+ </para>
+ <para>
+ A minimal front-end configuration file that does this would read as
+ follows:
+ </para>
+ <screen>
+<![CDATA[
+ <yazgfs>
+ <server>
+ <config>zebra.cfg</config>
+ <cql2rpn>../../tab/pqf.properties</cql2rpn>
+ </server>
+ </yazgfs>
+]]></screen>
+ <para>
+ The
+ <literal><config></literal>
+ element contains the name of the Zebra configuration file that was
+ previously specified by the
+ <literal>-c</literal>
+ command-line argument, and the
+ <literal><cql2rpn></literal>
+ element contains the name of the CQL properties file specifying how
+ 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>
+ </refsect2>
+ </refsect1>
+ <refsect1 id="zebrasrv-sru-support">
+ <title>SRU Protocol Support and Behavior</title>
+ <para>
+ Zebra running as an SRU server supports SRU version 1.1, including
+ CQL version 1.1. In particular, it provides support for the
+ following elements of the protocol.
+ </para>
+
+ <refsect2 id="zebrasrvr-search-and-retrieval">
+ <title>SRU Search and Retrieval</title>
+ <para>
+ Zebra supports the
+ <ulink url="&url.sru.searchretrieve;">SRU searchRetrieve</ulink>
+ operation.
+ </para>
+ <para>
+ One of the great strengths of SRU is that it mandates a standard
+ query language, CQL, and that all conforming implementations can
+ therefore be trusted to correctly interpret the same queries. It
+ is with some shame, then, that we admit that Zebra also supports
+ an additional query language, our own Prefix Query Format
+ (<ulink url="&url.yaz.pqf;">PQF</ulink>).
+ 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>
+ </refsect2>
+
+ <refsect2 id="zebrasrv-sru-scan">
+ <title>SRU Scan</title>
+ <para>
+ Zebra supports <ulink url="&url.sru.scan;">SRU scan</ulink>
+ operation.
+ Scanning using CQL syntax is the default, where the
+ standard <literal>scanClause</literal> parameter is used.
+ </para>
+ <para>
+ In addition, a
+ mutant form of SRU scan is 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>
+ </refsect2>
+
+ <refsect2 id="zebrasrv-sru-explain">
+ <title>SRU Explain</title>
+ <para>
+ Zebra supports <ulink url="&url.sru.explain;">SRU explain</ulink>.
+ </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
+ <xref linkend="gfs-config"/>.
+ </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 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>
+ </refsect2>
+
+ <refsect2 id="zebrasrv-non-sru-ops">
+ <title>Other SRU operations</title>
+ <para>
+ In the Z39.50 protocol, Initialization, Present, Sort and Close
+ are separate operations. In SRU, however, these operations do not
+ exist.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ SRU has no explicit initialization handshake phase, but
+ commences immediately with searching, scanning and explain
+ operations.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Neither does SRU have a close operation, since the protocol is
+ stateless and each request is self-contained. (It is true that
+ multiple SRU request/response pairs may be implemented as
+ multiple HTTP request/response pairs over a single persistent
+ TCP/IP connection; but the closure of that connection is not a
+ protocol-level operation.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Retrieval in SRU is part of the
+ <literal>searchRetrieve</literal> operation, in which a search
+ is submitted and the response includes a subset of the records
+ in the result set. There is no direct analogue of Z39.50's
+ Present operation which requests records from an established
+ result set. In SRU, this is achieved by sending a subsequent
+ <literal>searchRetrieve</literal> request with the query
+ <literal>cql.resultSetId=</literal><emphasis>id</emphasis> where
+ <emphasis>id</emphasis> is the identifier of the previously
+ generated result-set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Sorting in CQL is done within the
+ <literal>searchRetrieve</literal> operation - in v1.1, by an
+ explicit <literal>sort</literal> parameter, but the forthcoming
+ v1.2 or v2.0 will most likely use an extension of the query
+ language, <ulink url="&url.cql.sorting;">CQL sorting</ulink>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ It can be seen, then, that while Zebra operating as an SRU server
+ does not provide the same set of operations as when operating as a
+ Z39.50 server, it does provide equivalent functionality.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1 id="zebrasrv-sru-examples">
+ <title>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>
+
+ </refsect1>
+
+ <refsect1 id="gfs-config"><title>YAZ server virtual hosts</title>
+ &zebrasrv-virtual;
+ </refsect1>
+
+ <refsect1><title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>zebraidx</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </para>
+</refsect1>
+</refentry>
+
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document: "zebra.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->
projects / idzebra-moved-to-github.git / commitdiff