-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
-<!ENTITY gfs-options SYSTEM "gfs-options.xml">
-<!ENTITY gfs-virtual SYSTEM "gfs-virtual.xml">
-<!ENTITY gfs-synopsis SYSTEM "gfs-synopsis.xml">
-<!ENTITY gfs-synopsis-app "yaz-ztest">
-<!ENTITY reference-tools-cql-map 'section "Specifiction of CQL to RPN mappings"'>
+<!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;
+ <!ENTITY % entities SYSTEM "entities.ent">
+ %entities;
+ <!ENTITY % idcommon SYSTEM "common/common.ent">
+ %idcommon;
+ <!ENTITY gfs-synopsis-app "yaz-ztest">
+ <!ENTITY reference-tools-cql-map 'section "Specifiction of CQL to RPN mappings"'>
+ <!ENTITY reference-tools-cql-map 'section "CCL Qualifiers"'>
]>
-<!-- $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $ -->
<refentry id="yaz-ztest">
-
+ <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>
- <!--
- $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $
- cmd description of YAZ GFS application.
- Included in both manual and man page for yaz-ztest
--->
-
-<cmdsynopsis>
- <command>yaz-ztest</command>
- <arg choice="opt"><option>-install</option></arg>
- <arg choice="opt"><option>-installa</option></arg>
- <arg choice="opt"><option>-remove</option></arg>
- <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>-f <replaceable>vconfig</replaceable></option></arg>
- <arg choice="opt"><option>-C <replaceable>fname</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>-p <replaceable>pidfile</replaceable></option></arg>
- <arg choice="opt"><option>-ziDST1</option></arg>
- <arg choice="opt" rep="repeat">listener-spec</arg>
-</cmdsynopsis>
-
-<!-- Keep this Emacs mode comment at the end of the file
-Local variables:
-mode: nxml
-End:
--->
-
+ <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>
</refsect1>
<refsect1>
<title>OPTIONS</title>
-
-<!--
- $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $
- Options for generic frontend server and yaz-ztest.
- Included in both manual and man page for yaz-ztest
--->
-<variablelist>
-
- <varlistentry><term><literal>-a </literal>
- <replaceable>file</replaceable></term>
- <listitem><para>
- Specify a file for dumping PDUs (for diagnostic purposes).
- The special name <literal>-</literal> (dash) sends output to
- <literal>stderr</literal>.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-S</literal></term>
- <listitem><para>
- Don't fork or make threads on connection requests. This is good for
- debugging, but not recommended for real operation: Although the
- server is asynchronous and non-blocking, it can be nice to keep
- a software malfunction (okay then, a crash) from affecting all
- current users.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-1</literal></term>
- <listitem><para>
- Like <literal>-S</literal> but after one session the server
- exits. This mode is for debugging <emphasis>only</emphasis>.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-T</literal></term>
- <listitem><para>
- Operate the server in threaded mode. The server creates a thread
- for each connection rather than a fork a process. Only available
- on UNIX systems that offers POSIX threads.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-s</literal></term>
- <listitem><para>
- Use the SR protocol (obsolete).
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-z</literal></term>
- <listitem><para>
- Use the Z39.50 protocol (default). This option and <literal>-s</literal>
- complement each other.
- You can use both multiple times on the same command
- line, between listener-specifications (see below). This way, you
- can set up the server to listen for connections in both protocols
- concurrently, on different local ports.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-l </literal>
- <replaceable>file</replaceable></term>
- <listitem><para>The logfile.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-c </literal>
- <replaceable>config</replaceable></term>
- <listitem><para>A user option that serves as a specifier for some
- sort of configuration, usually a filename.
- The argument to this option is transferred to member
- <literal>configname</literal> of the
- <literal>statserv_options_block</literal>.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-f </literal>
- <replaceable>vconfig</replaceable></term>
- <listitem><para>This specifies an XML file that describes
- one or more YAZ frontend virtual servers.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-C </literal>
- <replaceable>fname</replaceable></term>
- <listitem><para>Sets SSL certificate file name for server (PEM).
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-v </literal>
- <replaceable>level</replaceable></term>
- <listitem><para>
- The log level. Use a comma-separated list of members of the set
- {fatal,debug,warn,log,malloc,all,none}.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-u </literal>
- <replaceable>uid</replaceable></term>
- <listitem><para>
- Set user ID. Sets the real UID of the server process to that of the
- given user. 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><literal>-w </literal>
- <replaceable>dir</replaceable></term>
- <listitem><para>
- The server changes to this directory during before listening
- on incoming connections. This option is useful
- when the server is operating from the <application>inetd</application>
- daemon (see <literal>-i</literal>).
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-p </literal>
- <replaceable>pidfile</replaceable></term>
- <listitem><para>
- Specifies that the server should write its Process ID to
- file given by <replaceable>pidfile</replaceable>.
- A typical location would be <filename>/var/run/yaz-ztest.pid</filename>.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-i</literal></term>
- <listitem><para>
- Use this to make the the server run from the
- <application>inetd</application> server (UNIX only).
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-D</literal></term>
- <listitem><para>
- Use this to make the server put itself in the background and
- run as a daemon. If neither <literal>-i</literal> nor
- <literal>-D</literal> is given, the server starts in the foreground.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-install</literal></term>
- <listitem><para>
- Use this to install the server as an NT service
- (Windows NT/2000/XP only).
- Control the server by going to the Services in the Control Panel.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-installa</literal></term>
- <listitem><para>
- Use this to install and activate the server as an NT service
- (Windows NT/2000/XP only).
- Control the server by going to the Services in the Control Panel.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-remove</literal></term>
- <listitem><para>
- Use this to remove the server from the NT services
- (Windows NT/2000/XP only).
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-t </literal>
- <replaceable>minutes</replaceable></term>
- <listitem><para>
- Idle session timeout, in minutes.
- </para></listitem></varlistentry>
-
- <varlistentry><term><literal>-k </literal>
- <replaceable>size</replaceable></term>
- <listitem><para>
- Maximum record size/message size, in kilobytes.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term><literal>-d </literal>
- <replaceable>daemon</replaceable></term>
- <listitem><para>
- Set name of daemon to be used in hosts access file.
- See
- <citerefentry>
- <refentrytitle>hosts_access</refentrytitle>
- <manvolnum>5</manvolnum>
- </citerefentry>
- and
- <citerefentry>
- <refentrytitle>tcpd</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry><term><literal>-m </literal>
- <replaceable>time-format</replaceable></term>
- <listitem><para>
- Sets the format of time-stamps in the log-file. Specify a string in
- the input format to <literal>strftime()</literal>.
- </para></listitem>
- </varlistentry>
-
-</variablelist>
-<!-- Keep this Emacs mode comment at the end of the file
-Local variables:
-mode: nxml
-End:
--->
-
-
+ &gfs-options;
</refsect1>
- <refsect1><title>VIRTUAL HOSTS</title>
- <!--
- $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $
- Description of the virtual host mechanism in YAZ GFS
- Included in both manual and man page for yaz-ztest
--->
-
-<para>
- The Virtual hosts mechanism allows a YAZ frontend server to
- support multiple backends. A backend is selected on the basis of
- the TCP/IP binding (port+listening adddress) and/or the virtual host.
-</para>
-<para>
- A backend can be configured to execute in a particular working
- directory. Or the YAZ frontend may perform CQL to RPN conversion, thus
- allowing traditional Z39.50 backends to be offered as a SRW/SRU
- service. SRW/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.
- For the Z39.50 protocol, the virtual host is specified as in the
- Initialize Request in the OtherInfo, OID 1.2.840.10003.10.1000.81.1.
-</para>
-<note>
- <para>
- Not all Z39.50 clients allows the VHOST information to be set.
- For those the selection of the backend must rely on the
- TCP/IP information alone (port and address).
- </para>
-</note>
-<para>
- The YAZ frontend server uses XML to describe the backend
- configurations. Command-line option <literal>-f</literal>
- specifies filename of the XML configuration.
-</para>
-<para>
- The configuration uses the root element <literal>yazgfs</literal>.
- This element includes a list of <literal>listen</literal> elements,
- followed by one or more <literal>server</literal> elements.
-</para>
-<para>
- The <literal>listen</literal> describes listener (transport end point),
- such as TCP/IP, Unix file socket or SSL server. Content for
- a listener:
- <variablelist>
- <varlistentry><term>CDATA (required)</term>
- <listitem>
- <para>
- The CDATA for the <literal>listen</literal> element holds the
- listener string, such as <literal>tcp:@:210</literal>,
- <literal>tcp:server1:2100</literal>,
- etc.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>attribute <literal>id</literal> (optional)</term>
- <listitem>
- <para>
- identifier for this listener. This may be referred to from
- server sections.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <note>
- <para>
- We expect more information to be added for the listen section in
- a future version, such as CERT file for SSL servers.
- </para>
- </note>
-</para>
-<para>
- The <literal>server</literal> describes a server and the parameters
- for this server type. Content for a server:
- <variablelist>
- <varlistentry><term>attribute <literal>id</literal> (optional)</term>
- <listitem>
- <para>
- Identifier for this server. Currently not used for anything,
- but it might be for logging purposes.
+ <refsect1>
+ <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
+ 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
+ <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
+ other database will make <command>yaz-ztest</command> return diagnostic
+ 109: "Database unavailable".
+ </para>
+ <para>
+ Options for search may be included in the form or URL get arguments
+ included as part of the Z39.50 database name. The following
+ database options are present: <literal>search-delay</literal>,
+ <literal>present-delay</literal>, <literal>fetch-delay</literal>
+ and <literal>seed</literal>.
+ </para>
+ <para>
+ The former, delay type options, specify
+ a fake delay (sleep) that <command>yaz-ztest</command> will perform
+ when searching, presenting, fetching records respectively.
+ The value of the delay may either be a fixed floating point
+ value which specifies the delay in seconds.
+ Alternatively the value may be given as two floating point numbers
+ separated by colon, which wil make <command>yaz-ztest</command> perform
+ a random sleep between the first and second number.
+ </para>
+ <para>
+ 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>
+ <para>
+ Suppose we want searches to take between 0.1 and 0.5 seconds and
+ a fetch to take 0.2 second. To access test database Default we'd use:
+ <literal>Default?search-delay=0.1:0.5&fetch-delay=0.2</literal>.
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>attribute <literal>listenref</literal> (optional)</term>
- <listitem>
- <para>
- Specifies listener for this server. If this attribute is not
- given, the server is accessible from all listener. In order
- for the server to be used for real, howeever, the virtual host
- must match (if specified in the configuration).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>config</literal> (optional)</term>
- <listitem>
- <para>
- Specifies the server configuration. This is equivalent
- to the config specified using command line option
- <literal>-c</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>directory</literal> (optional)</term>
- <listitem>
- <para>
- Specifies a working directory for this backend server. If
- specifid, the YAZ fronend changes current working directory
- to this directory whenever a backend of this type is
- started (backend handler bend_start), stopped (backend handler hand_stop)
- and initialized (bend_init).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>host</literal> (optional)</term>
- <listitem>
- <para>
- Specifies the virtual host for this server. If this is specified
- a client <emphasis>must</emphasis> specify this host string in
- order to use this backend.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>cql2rpn</literal> (optional)</term>
- <listitem>
- <para>
- Specifies a filename that includes CQL to RPN conversion for this
- backend server. See section "Specifiction of CQL to RPN mappings"
- If given, the backend server will only "see" a Type-1/RPN query.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>stylesheet</literal> (optional)</term>
- <listitem>
- <para>
- Specifies the stylesheet reference to be part of SRU HTTP responses
- when the client does not specify one. If neither this is given, nor
- the client specifies one, no stylesheet reference is part of the
- SRU HTTP response.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>docpath</literal> (optional)</term>
- <listitem>
- <para>
- Specifies a path for local file access using HTTP. All URLs with
- a leading prefix (/ exluded) that matches the value of docpath
- are used for file access. For example, if the server is to offer
- access in directory <literal>xsl</literal>, the docpath would be
- <literal>xsl</literal> and all URLs of the form
- <literal>http://host/exl</literal> will result in a local file access.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>element <literal>explain</literal> (optional)</term>
- <listitem>
- <para>
- Specifies SRW/SRU ZeeRex content for this server. Copied verbatim
- to the client. As things are now, some of the Explain content
- seeem redundant because host information, etc. is also stored
- elsewhere.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-</para>
-
-<para>
- The XML below configures a server that accepts connections from
- two ports, TCP/IP port 9900 and a local UNIX file socket.
- We name the TCP/IP server <literal>public</literal> and the
- other server <literal>internal</literal>.
- </para>
- <screen>
- <![CDATA[
- <yazgfs>
- <listen id="public">tcp:@:9900</listen>
- <listen id="internal">unix:/var/tmp/socket</listen>
- <server id="server1">
- <host>server1.mydomain</host>
- <directory>/var/www/s1</directory>
- <config>config.cfg</config>
- </server>
- <server id="server2">
- <host>server2.mydomain</host>
- <directory>/var/www/s2</directory>
- <config>config.cfg</config>
- <cql2rpn>../etc/pqf.properties</cql2rpn>
- <explain xmlns="http://explain.z3950.org/dtd/2.0/">
- <serverInfo>
- <host>server2.mydomain</host>
- <port>9900</port>
- <database>a</database>
- </serverInfo>
- </explain>
- </server>
- <server id="server3" listenref="internal">
- <directory>/var/www/s3</directory>
- <config>config.cfg</config>
- </server>
- </yazgfs>
-]]>
- </screen>
-<para>
- There are three configured backend servers. The first two
- servers, <literal>"server1"</literal> and <literal>"server2"</literal>,
- can be reached by both listener addresses - since
- no <literal>listenref</literal> attribute is specified.
- In order to distinguish between the two a virtual host has
- been specified for each of server in the <literal>host</literal>
- elements.
-</para>
-<para>
- For <literal>"server2"</literal> elements for CQL to RPN conversion
- is supported and explain information has been added (a short one here
- to keep the example small).
-</para>
-<para>
- The third server, <literal>"server3"</literal> can only be reached
- via listener <literal>"internal"</literal>.
-</para>
-
-<!-- Keep this Emacs mode comment at the end of the file
-Local variables:
-mode: nxml
-End:
--->
-
-
+ </refsect1>
+ <refsect1><title>GFS CONFIGURATION AND VIRTUAL HOSTS</title>
+ &gfs-virtual;
</refsect1>
<refsect1><title>FILES</title>
<para>
<filename>yaz-<version>/include/yaz/backend.h</filename>
</para>
</refsect1>
- <refsect1 id="tools.cql.map"><title>SEE ALSO</title>
+ <refsect1><title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>yaz</refentrytitle>
- <manvolnum>7</manvolnum></citerefentry>
- </para>
- <para>
- Section "Generic server" in the YAZ manual.
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>yaz-log</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
</para>
</refsect1>
</refentry>
-<!-- Keep this Emacs mode comment at the end of the file
+
+<!-- Keep this comment at the end of the file
Local variables:
-mode: nxml
+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:
-->
projects / yaz-moved-to-github.git / blobdiff