User-defined retrieval records for yaz-ztest YAZ-714

[yaz-moved-to-github.git] / doc / yaz-ztest-man.xml

diff --git a/doc/yaz-ztest-man.xml b/doc/yaz-ztest-man.xml
index 14f743c..dfa1b3a 100644 (file)
--- a/doc/yaz-ztest-man.xml
+++ b/doc/yaz-ztest-man.xml
@@ -1,5 +1,5 @@
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
 [
      <!ENTITY % local SYSTEM "local.ent">
      %local;
@@ -15,26 +15,28 @@
  <refentryinfo>
   <productname>YAZ</productname>
   <productnumber>&version;</productnumber>
+  <info><orgname>Index Data</orgname></info>
  </refentryinfo>
- 
+
  <refmeta>
   <refentrytitle>yaz-ztest</refentrytitle>
   <manvolnum>8</manvolnum>
+  <refmiscinfo class="manual">System management commands</refmiscinfo>
  </refmeta>
- 
+
  <refnamediv>
   <refname>yaz-ztest</refname>
-  <refpurpose>Z39.50 Test Server</refpurpose>
+  <refpurpose>Z39.50/SRU Test Server</refpurpose>
  </refnamediv>
- 
+
  <refsynopsisdiv>
   &gfs-synopsis;
  </refsynopsisdiv>
  <refsect1><title>DESCRIPTION</title>
   <para>
-   <command>yaz-ztest</command> is a Z39.50 test server that uses
-   the YAZ generic frontend server API.
-   The server acts as a real Z39.50 server but does not use a database.
+   <command>yaz-ztest</command> is a Z39.50/SRU test server that uses
+   the YAZ generic frontend server (GFS) API.
+   The server acts as a real Z39.50/SRU server but does not use a database.
    It returns a random hit count and returns a subset of a few built-in
    records.
   </para>
@@ -62,14 +64,30 @@
    <title>TESTING</title>
    <para>
     <command>yaz-ztest</command> normally returns a random hit count between
-    0 and 24. However, if a query term includes leading digits, then the 
+    0 and 24. However, if a query term includes leading digits, then the
     integer value of that term is used as hit count. This allows testers
     to return any number of hits. <command>yaz-ztest</command> includes
-    24 MARC records for testing. Hit counts exceeding 24 will make 
+    24 MARC records for testing. Hit counts exceeding 24 will make
     <command>yaz-ztest</command> return the same record batch over and over..
     So record at position 1, 25, 49, etc .. are equivalent.
    </para>
    <para>
+    For XML if no element set is given or element has value "marcxml",
+    MARCXML is returned (each of the 24 dummy records converted from
+    ISO2709 to XML). For element set OP, OPAC XML is returned.
+   </para>
+   <para>
+    yaz-ztest may also return predefined XML records (for testing).
+    This is enabled if <literal>YAZ_ZTEST_XML_FETCH</literal> environment
+    variable is defined. A record is fetched form a file (one record per file).
+    The path for the filename is
+    <replaceable>F</replaceable><replaceable>E</replaceable><literal>.</literal><replaceable>d</replaceable><literal>.xml</literal>
+    where <replaceable>F</replaceable> is the YAZ_ZTEST_XML_FETCH value
+    (possibly
+    empty), <replaceable>E</replaceable> is element-set,
+    <replaceable>d</replaceable> is record position (starting from 1).
+   </para>
+   <para>
      The following databases are honored by <command>yaz-ztest</command>:
      <literal>Default</literal>, <literal>slow</literal>
      and <literal>db.*</literal> (all databases with prefix "db"). Any
@@ -94,7 +112,7 @@
      a random sleep between the first and second number.
    </para>
    <para>
-     The database parameter <literal>seed</literal> takes an integer 
+     The database parameter <literal>seed</literal> takes an integer
      as value. This will call <literal>srand</literal> with this integer to
      ensure that the random behavior can be re-played.
    </para>