No more manifest files
[yaz-moved-to-github.git] / doc / yaz-ztest-man.xml
1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
2  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
3 [
4      <!ENTITY % local SYSTEM "local.ent">
5      %local;
6      <!ENTITY % entities SYSTEM "entities.ent">
7      %entities;
8      <!ENTITY % idcommon SYSTEM "common/common.ent">
9      %idcommon;
10      <!ENTITY gfs-synopsis-app "yaz-ztest">
11      <!ENTITY reference-tools-cql-map 'section "Specifiction of CQL to RPN mappings"'>
12      <!ENTITY reference-tools-cql-map 'section "CCL Qualifiers"'>
13 ]>
14 <refentry id="yaz-ztest">
15  <refentryinfo>
16   <productname>YAZ</productname>
17   <productnumber>&version;</productnumber>
18   <orgname>Index Data</orgname>
19  </refentryinfo>
20
21  <refmeta>
22   <refentrytitle>yaz-ztest</refentrytitle>
23   <manvolnum>8</manvolnum>
24   <refmiscinfo class="manual">System management commands</refmiscinfo>
25  </refmeta>
26
27  <refnamediv>
28   <refname>yaz-ztest</refname>
29   <refpurpose>Z39.50/SRU Test Server</refpurpose>
30  </refnamediv>
31
32  <refsynopsisdiv>
33   &gfs-synopsis;
34  </refsynopsisdiv>
35  <refsect1><title>DESCRIPTION</title>
36   <para>
37    <command>yaz-ztest</command> is a Z39.50/SRU test server that uses
38    the YAZ generic frontend server (GFS) API.
39    The server acts as a real Z39.50/SRU server but does not use a database.
40    It returns a random hit count and returns a subset of a few built-in
41    records.
42   </para>
43   <para>
44    The <replaceable>listener-spec</replaceable> consists of a transport
45    mode followed by a colon, followed by a listener address. The
46    transport mode is either <literal>tcp</literal>, <literal>unix</literal>,
47    or <literal>ssl</literal>.
48   </para>
49   <para>
50    For TCP and SSL, an address has the form:
51    <screen>
52     hostname | IP-number [ : portnumber ]
53    </screen>
54   </para>
55   <para>
56    For UNIX local socket, the address is the filename of the local socket.
57   </para>
58  </refsect1>
59  <refsect1>
60   <title>OPTIONS</title>
61   &gfs-options;
62  </refsect1>
63  <refsect1>
64    <title>TESTING</title>
65    <para>
66     <command>yaz-ztest</command> normally returns a random hit count between
67     0 and 24. However, if a query term includes leading digits, then the
68     integer value of that term is used as hit count. This allows testers
69     to return any number of hits. <command>yaz-ztest</command> includes
70     24 MARC records for testing. Hit counts exceeding 24 will make
71     <command>yaz-ztest</command> return the same record batch over and over.
72     So record at position 1, 25, 49, etc. are equivalent.
73    </para>
74    <para>
75     For XML, if no element set is given or element has value "marcxml",
76     MARCXML is returned (each of the 24 dummy records converted from
77     ISO2709 to XML). For element set OP, then OPAC XML is returned.
78    </para>
79    <para>
80     yaz-ztest may also return predefined XML records (for testing).
81     This is enabled if <literal>YAZ_ZTEST_XML_FETCH</literal> environment
82     variable is defined. A record is fetched from a file (one record per file).
83     The path for the filename is
84     <replaceable>F</replaceable><replaceable>E</replaceable><literal>.</literal><replaceable>d</replaceable><literal>.xml</literal>
85     where <replaceable>F</replaceable> is the YAZ_ZTEST_XML_FETCH value
86     (possibly
87     empty), <replaceable>E</replaceable> is element-set,
88     <replaceable>d</replaceable> is record position (starting from 1).
89    </para>
90    <para>
91      The following databases are honored by <command>yaz-ztest</command>:
92      <literal>Default</literal>, <literal>slow</literal>
93      and <literal>db.*</literal> (all databases with prefix "db"). Any
94      other database will make <command>yaz-ztest</command> return diagnostic
95      109: "Database unavailable".
96    </para>
97    <para>
98      Options for search may be included in the form or URL get arguments
99      included as part of the Z39.50 database name. The following
100      database options are present: <literal>search-delay</literal>,
101      <literal>present-delay</literal>, <literal>fetch-delay</literal>
102      and <literal>seed</literal>.
103    </para>
104    <para>
105      The former, delay type options, specify
106      a fake delay (sleep) that <command>yaz-ztest</command> will perform
107      when searching, presenting, fetching records respectively.
108      The value of the delay may either be a fixed floating point
109      value which specifies the delay in seconds.
110      Alternatively the value may be given as two floating point numbers
111      separated by colon, which will make <command>yaz-ztest</command> perform
112      a random sleep between the first and second number.
113    </para>
114    <para>
115      The database parameter <literal>seed</literal> takes an integer
116      as value. This will call <literal>srand</literal> with this integer to
117      ensure that the random behavior can be re-played.
118    </para>
119    <para>
120      Suppose we want searches to take between 0.1 and 0.5 seconds and
121      a fetch to take 0.2 second. To access test database Default we'd use:
122      <literal>Default?search-delay=0.1:0.5&amp;fetch-delay=0.2</literal>.
123    </para>
124  </refsect1>
125  <refsect1><title>GFS CONFIGURATION AND VIRTUAL HOSTS</title>
126   &gfs-virtual;
127  </refsect1>
128  <refsect1><title>FILES</title>
129   <para>
130    <filename>yaz-&lt;version&gt;/ztest/yaz-ztest.c</filename>
131   </para>
132   <para>
133    <filename>yaz-&lt;version&gt;/include/yaz/backend.h</filename>
134   </para>
135  </refsect1>
136  <refsect1><title>SEE ALSO</title>
137   <para>
138    <citerefentry>
139     <refentrytitle>yaz</refentrytitle>
140     <manvolnum>7</manvolnum>
141    </citerefentry>
142    <citerefentry>
143     <refentrytitle>yaz-log</refentrytitle>
144     <manvolnum>7</manvolnum>
145    </citerefentry>
146   </para>
147  </refsect1>
148 </refentry>
149
150 <!-- Keep this comment at the end of the file
151 Local variables:
152 mode: nxml
153 nxml-child-indent: 1
154 End:
155 -->