a737c75c33e9aa67ccdb13167fe3e0858cdeeb0f
[yaz-moved-to-github.git] / doc / book.xml
1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4 [
5      <!ENTITY % local SYSTEM "local.ent">
6      %local;
7      <!ENTITY % entities SYSTEM "entities.ent">
8      %entities;
9      <!ENTITY % idcommon SYSTEM "common/common.ent">
10      %idcommon;
11 ]>
12 <book>
13  <bookinfo>
14   <title>YAZ User&apos;s Guide and Reference</title>
15   <authorgroup>
16    <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
17    <author><firstname>Adam</firstname><surname>Dickmeiss</surname></author>
18    <author><firstname>Mike</firstname><surname>Taylor</surname></author>
19    <author><firstname>Heikki</firstname><surname>Levanto</surname></author>
20    <author><firstname>Dennis</firstname><surname>Schafroth</surname></author>
21   </authorgroup>
22   <releaseinfo>&version;</releaseinfo>
23   <copyright>
24    <year>&copyright-year;</year>
25    <holder>Index Data</holder>
26   </copyright>
27   <abstract>
28    <simpara>
29     This document is the programmer's guide and reference to the &yaz;
30     package version &version;. &yaz; is a compact toolkit that provides
31     access to the Z39.50 and SRU/Solr protocols, as well as a set of
32     higher-level tools for implementing the server and client
33     roles, respectively.
34     The documentation can be used on its own, or as a reference when
35     looking at the example applications provided with the package.
36    </simpara>
37    <simpara>
38     <inlinemediaobject>
39      <imageobject>
40       <imagedata fileref="common/id.png" format="PNG"/>
41      </imageobject>
42      <imageobject>
43       <imagedata fileref="common/id.eps" format="EPS"/>
44      </imageobject>
45     </inlinemediaobject>
46    </simpara></abstract>
47  </bookinfo>
48  <chapter id="introduction">
49   <title>Introduction</title>
50   <para>
51    &yaz; is a C/C++ library for information retrieval applications
52    using the Z39.50/SRU/Solr protocols for information retrieval.
53   </para>
54   <para>
55    Properties of &yaz;:
56    <itemizedlist>
57     <listitem>
58      <para>
59       Complete
60       <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
61       Amendments and Z39.50-2002 revision is supported.
62     </para>
63     </listitem>
64     <listitem>
65      <para>
66       Supports
67       <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
68       version 1.1, 1.2 and 2.0 (over HTTP and HTTPS).
69     </para>
70     </listitem>
71     <listitem>
72      <para>
73       Includes BER encoders/decoders for the
74       <ulink url="&url.ill;">ISO ILL</ulink>
75       protocol.
76     </para>
77     </listitem>
78     <listitem>
79      <para>
80       Supports
81       <ulink url="&url.solr;">Solr</ulink> Web Service version 1.4.x
82       (client side only)
83      </para>
84     </listitem>
85     <listitem>
86      <para>
87       Supports the following transports: BER over TCP/IP
88       (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
89       BER over unix local socket, and
90       <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
91     </para>
92     </listitem>
93     <listitem>
94      <para>
95       Secure Socket Layer support using
96       <ulink url="&url.gnutls;">GnuTLS</ulink>.
97       If enabled, &yaz; uses HTTPS transport (for SOAP) or
98       "Secure BER" (for Z39.50).
99      </para>
100     </listitem>
101     <listitem>
102      <para>
103       Offers
104       <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
105       Z39.50, SRU and Solr Web Service.
106     </para>
107     </listitem>
108     <listitem>
109      <para>
110       The &yaz; library offers a set of useful utilities
111       related to the protocols, such as MARC (ISO2709) parser,
112       CCL (ISO8777) parser,
113       <ulink url="&url.cql;">CQL</ulink>
114       parser, memory management routines, character set conversion.
115      </para>
116     </listitem>
117     <listitem>
118      <para>
119       Portable code. &yaz; compiles out-of-the box on most Unixes and
120       on Windows using Microsoft Visual C++.
121      </para>
122     </listitem>
123     <listitem>
124      <para>
125       Fast operation. The C based BER encoders/decoders as well
126       as the server component of &yaz; is very fast.
127     </para>
128     </listitem>
129     <listitem>
130      <para>
131       Liberal license that allows for commercial use of &yaz;.
132      </para>
133     </listitem>
134    </itemizedlist>
135   </para>
136
137   <sect1 id="introduction.reading">
138    <title>Reading this Manual</title>
139    <para>
140     Most implementors only need to read a fraction of the
141     material in thie manual, so a quick walkthrough of the chapters
142     is in order.
143    </para>
144    <itemizedlist>
145     <listitem>
146      <para>
147       <xref linkend="installation"/> contains installation
148       instructions for &yaz;. You don't need reading this
149       if you expect to download &yaz; binaries.
150       However, the chapter contains information about how
151       to make <emphasis>your</emphasis> application link
152       with &yaz;.
153      </para>
154     </listitem>
155     <listitem>
156      <para>
157       <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
158       This is definitely worth a read if you wish to develop a Z39.50/SRU
159       client.
160      </para>
161     </listitem>
162     <listitem>
163      <para>
164       <xref linkend="server"/> describes the generic frontend server
165       and explains how to develop server Z39.50/SRU applications for &yaz;.
166       Obviously worth reading if you're to develop a server.
167     </para>
168     </listitem>
169     <listitem>
170      <para>
171       <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
172       client. If you're developer and wish to test your server
173       or a server from another party, you might find this chapter
174       useful.
175     </para>
176     </listitem>
177     <listitem>
178      <para>
179       <xref linkend="asn"/> documents the most commonly used Z39.50
180       C data structures offered by the &yaz; API. Client
181       developers using ZOOM and non-Z39.50 implementors may skip this.
182      </para>
183     </listitem>
184     <listitem>
185      <para>
186       <xref linkend="soap"/> describes how SRU and SOAP is used
187       in &yaz;. Only if you're developing SRU applications
188       this section is a must.
189      </para>
190     </listitem>
191     <listitem>
192      <para>
193       <xref linkend="tools"/> contains sections for the various
194       tools offered by &yaz;. Scan through the material quickly
195       and see what's relevant to you! SRU implementors
196       might find the <link linkend="cql">CQL</link> section
197       particularly useful.
198      </para>
199     </listitem>
200     <listitem>
201      <para>
202       <xref linkend="odr"/> goes through the details of the
203       ODR module which is the work horse that encodes and decodes
204       BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
205       need reading this.
206       Most other Z39.50 implementors only need to read the first two
207       sections (<xref linkend="odr.introduction"/> and
208       <xref linkend="odr.use"/>).
209      </para>
210     </listitem>
211     <listitem>
212      <para>
213       <xref linkend="comstack"/> describes the network layer module
214       COMSTACK. Implementors using ZOOM or the generic frontend server
215       may skip this. Others, presumably, handling client/server
216      communication on their own should read this.
217      </para>
218     </listitem>
219    </itemizedlist>
220   </sect1>
221   <sect1 id="introduction.api">
222    <title>The API</title>
223    <para>
224     The <ulink url="&url.yaz;">&yaz;</ulink>
225     toolkit offers several different levels of access to the
226     <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
227     <ulink url="&url.ill;">ILL</ulink> and
228     <ulink url="&url.sru;">SRU</ulink>
229     protocols.
230     The level that you need to use depends on your requirements, and
231     the role (server or client) that you want to implement.
232     If you're developing a client application you should consider the
233     <link linkend="zoom">ZOOM</link> API.
234     It is, by far, the easiest way to develop clients in C.
235     Server implementers should consider the
236     <link linkend="server">generic frontend server</link>.
237     None of those high-level APIs support the whole protocol, but
238     they do include most facilities used in existing Z39.50 applications.
239    </para>
240    <para>
241     If you're using 'exotic' functionality (meaning anything not included in
242     the high-level APIs), developing non-standard extensions to Z39.50 or
243     you're going to develop an ILL application you'll have to learn the lower
244     level APIs of &yaz;.
245    </para>
246    <para>
247     The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
248    </para>
249    <figure id="yaz.layer">
250     <title>YAZ layers</title>
251     <mediaobject>
252      <imageobject>
253       <imagedata fileref="apilayer.png" format="PNG"/>
254      </imageobject>
255      <imageobject>
256       <imagedata fileref="apilayer.eps" format="EPS"/>
257      </imageobject>
258     </mediaobject>
259    </figure>
260    <para>
261     There are four layers.
262     <itemizedlist>
263      <listitem>
264       <para>A client or server application (or both).
265        This layer includes ZOOM and the generic frontend server.
266       </para>
267      </listitem>
268      <listitem>
269       <para>
270        The second layer provides a C represenation of the
271        protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
272        SRU.
273       </para>
274      </listitem>
275      <listitem>
276       <para>
277        The third layer encodes and decodes protocol data units to
278        simple packages (buffer with certain length). The &odr; module
279        encodes and decodes BER whereas the HTTP modules encodes and
280        decodes HTTP ruquests/responses.
281       </para>
282      </listitem>
283      <listitem>
284       <para>
285        The lowest layer is &comstack; which exchanges the encoded packages
286        with a peer process over a network.
287       </para>
288      </listitem>
289     </itemizedlist>
290    </para>
291    <para>
292     The &asn; module represents the ASN.1 definition of
293     the Z39.50 protocol. It establishes a set of type and
294     structure definitions, with one structure for each of the top-level
295     PDUs, and one structure or type for each of the contained ASN.1 types.
296     For primitive types, or other types that are defined by the ASN.1
297     standard itself (such as the EXTERNAL type), the C representation is
298     provided by the &odr; (Open Data Representation) subsystem.
299   </para>
300    <para>
301      &odr; is a basic mechanism for representing an
302     ASN.1 type in the C programming language, and for implementing BER
303     encoders and decoders for values of that type. The types defined in
304     the &asn; module generally have the prefix <literal>Z_</literal>, and
305     a suffix corresponding to the name of the type in the ASN.1
306     specification of the protocol (generally Z39.50-1995). In the case of
307     base types (those originating in the ASN.1 standard itself), the prefix
308     <literal>Odr_</literal> is sometimes seen. Either way, look for
309     the actual definition in either <filename>z-core.h</filename> (for the types
310     from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
311     types).
312     The &asn; library also provides functions (which are, in turn,
313     defined using &odr; primitives) for encoding and decoding data values.
314     Their general form is
315     <funcsynopsis>
316      <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
317       <paramdef>ODR <parameter>o</parameter></paramdef>
318       <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
319       <paramdef>int <parameter>optional</parameter></paramdef>
320       <paramdef>const char *<parameter>name</parameter></paramdef>
321      </funcprototype>
322     </funcsynopsis>
323     (note the lower-case &quot;z&quot; in the function name)
324    </para>
325    <note>
326     <para>
327      If you are using the premade definitions of the &asn; module, and you
328      are not adding new protocol of your own, the only parts of &odr; that you
329      need to worry about are documented in
330      <xref linkend="odr.use"/>.
331     </para>
332    </note>
333    <para>
334     When you have created a BER-encoded buffer, you can use the &comstack;
335     subsystem to transmit (or receive) data over the network. The &comstack;
336     module provides simple functions for establishing a connection
337     (passively or actively, depending on the role of your application),
338     and for exchanging BER-encoded PDUs over that connection. When you
339     create a connection endpoint, you need to specify what transport to
340     use (TCP/IP, SSL or UNIX sockets).
341     For the remainder of the connection's lifetime, you don't have
342     to worry about the underlying transport protocol at all - the &comstack;
343     will ensure that the correct mechanism is used.
344    </para>
345    <para>
346     We call the combined interfaces to &odr;, &asn;, and &comstack; the service
347     level API. It's the API that most closely models the Z39.50
348     service/protocol definition, and it provides unlimited access to all
349     fields and facilities of the protocol definitions.
350    </para>
351    <para>
352     The reason that the &yaz; service-level API is a conglomerate of the
353     APIs from three different submodules is twofold. First, we wanted to allow
354     the user a choice of different options for each major task. For instance,
355     if you don't like the protocol API provided by &odr;/&asn;, you
356     can use SNACC or BERUtils instead, and still have the benefits of the
357     transparent transport approach of the &comstack; module. Secondly,
358     we realize that you may have to fit the toolkit into an existing
359     event-processing structure, in a way that is incompatible with
360     the &comstack; interface or some other part of &yaz;.
361    </para>
362   </sect1>
363  </chapter>
364  <chapter id="installation">
365   <title>Compilation and Installation</title>
366   <sect1 id="installation-introduction">
367    <title>Introduction</title>
368    <para>
369     The latest version of the software will generally be found at:
370    </para>
371    <para>
372     <ulink url="&url.yaz.download;"/>
373    </para>
374    <para>
375     We have tried our best to keep the software portable, and on many
376     platforms, you should be able to compile everything with little or
377     no changes.
378    </para>
379    <para>
380     The software is regularly tested on
381     <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
382     <ulink url="&url.centos;">CentOS</ulink>,
383     <ulink url="&url.ubuntu;">Ubuntu Linux</ulink>,
384     <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
385     <ulink url="&url.macosx;">MAC OSX</ulink>,
386     <ulink url="&url.solaris;">Solaris</ulink>,
387     Windows 7, Windows XP.
388    </para>
389    <para>
390     Some versions have be known to work on HP/UX,
391     DEC Unix, <ulink url="&url.netbsd;">NetBSD</ulink>,
392     <ulink url="&url.openbsd;">OpenBSD</ulink>,
393     IBM AIX,
394     Data General DG/UX (with some CFLAGS tinkering),
395     SGI/IRIX, DDE Supermax, Apple Macintosh (using the Codewarrior programming
396     environment and the GUSI socket libraries),
397     IBM AS/400 .
398    </para>
399    <para>
400     If you move the software to other platforms, we'd be grateful if you'd
401     let us know about it. If you run into difficulties, we will try to help
402     if we can, and if you solve the problems, we would be happy to include
403     your fixes in the next release. So far, we have mostly avoided
404     <literal>#ifdefs</literal> for individual platforms, and we'd
405     like to keep it that way as far as it makes sense.
406    </para>
407    <para>
408     We maintain a mailing-list for the purpose of announcing new releases and
409     bug-fixes, as well as general discussion. Subscribe by
410     filling-in the form
411     <ulink url="&url.yaz.mailinglist;">here</ulink>.
412     General questions and problems can be directed at
413     <ulink url="&url.yaz.mail;"/>, or the address given at the top of
414      this document.
415    </para>
416   </sect1>
417   <sect1 id="installation.unix"><title>UNIX</title>
418    <para>
419     We provide
420     <ulink url="&url.debian;">Debian GNU/Linux</ulink> (i386 and amd64),
421     <ulink url="&url.ubuntu;">Ubuntu</ulink> (i386 and amd64)
422     and
423     <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
424     You should be able to create packages for other CPUs by building
425     them from the source package.
426    </para>
427    <para>
428     YAZ is also part of several packages repositories. Some of them are
429    </para>
430    <itemizedlist>
431     <listitem>
432      <para>
433       Solaris CSW: <ulink url="http://www.opencsw.org/packages/yaz/"/>
434      </para>
435     </listitem>
436     <listitem>
437      <para>
438       Solaris: <ulink url="http://unixpackages.com"/>
439      </para>
440     </listitem>
441     <listitem>
442      <para>
443       FreeBSD: <ulink url="http://www.freshports.org/net/yaz"/>
444      </para>
445     </listitem>
446     <listitem>
447      <para>
448       Debian: <ulink url="http://packages.debian.org/search?keywords=yaz"/>
449      </para>
450     </listitem>
451     <listitem>
452      <para>
453       Ubuntu: <ulink url="https://launchpad.net/ubuntu/+source/yaz"/>
454      </para>
455     </listitem>
456     <listitem>
457      <para>
458       NetBSD:
459       <ulink url="http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/net/yaz/README.html"/>
460      </para>
461     </listitem>
462    </itemizedlist>
463    <sect2 id="installation.source.unix">
464     <title>Compiling from source on Unix</title>
465     <para>
466      Note that if your system doesn't have a native ANSI C compiler, you may
467      have to acquire one separately. We recommend
468      <ulink url="&url.gcc;">GCC</ulink>.
469     </para>
470     <para>
471      If you wish to use character set conversion facilities in &yaz; or if you
472      are compiling &yaz; for use with Zebra it is a good idea to ensure that
473      the iconv library is installed. Some Unixes today already have it
474      - if not, we suggest
475      <ulink url="&url.libiconv;">GNU libiconv</ulink>.
476     </para>
477     <para>
478      YAZ 3.0.16 and later includes a wrapper for the
479      <ulink url="&url.icu;">ICU</ulink>
480      (International Components for Unicode).
481      In order to use this, the developer version of the ICU library
482      must be available. ICU support is recommended for applications
483      such as Pazpar2 and Zebra.
484     </para>
485     <para>
486      The <ulink url="&url.libxslt;">libxslt</ulink>,
487      <ulink url="&url.libxml2;">libxml2</ulink> librararies are required
488      if &yaz; is to support SRU/Solr.
489      These libraries are very portable and should compile out-of-the
490      box on virtually all Unix platforms. It is available in binary
491      forms for Linux and others.
492     </para>
493     <para>
494      The GNU tools
495      <ulink url="&url.autoconf;">Autoconf</ulink>,
496      <ulink url="&url.automake;">Automake</ulink> and
497      <ulink url="&url.libtool;">Libtool</ulink>
498      are used to generate Makefiles and configure &yaz; for the system.
499      You do <emphasis>not</emphasis> these tools unless you're using the
500      Git version of &yaz;.
501     </para>
502     <para>
503      The CQL parser for &yaz; is built using
504      GNU <ulink url="&url.bison;">Bison</ulink>.
505      This tool is only needed if you're using the Git version of &yaz;.
506     </para>
507     <para>
508      &yaz; includes a tiny ASN.1 compiler. This compiler is
509      written in <ulink url="&url.tcl;">Tcl</ulink>.
510      But as for Bison you do not need it unless you're using Git
511      version of &yaz; or you're using the compiler to built own codecs
512      for private ASN.1.
513     </para>
514     <para>
515      Generally it should be sufficient to run configure without options,
516      like this:
517     </para>
518     <screen>
519      ./configure
520     </screen>
521     <para>
522      The configure script attempts to use use the C compiler specified by
523      the <literal>CC</literal> environment variable. If not set, GNU C will be
524      used if it is available. The <literal>CFLAGS</literal> environment
525      variable holds options to be passed to the C compiler. If you're using
526      Bourne-compatible shell you may pass something like this to use a
527      particular C compiler with optimization enabled:
528     </para>
529     <screen>
530      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
531     </screen>
532     <para>
533      To customize &yaz;, the configure script also accepts a set of options.
534      The most important are:
535      <variablelist>
536       <varlistentry>
537        <term>
538         <literal>--prefix</literal>=<replaceable>prefix</replaceable>
539        </term>
540        <listitem>
541         <para>Specifies installation prefix for &yaz;. This is
542         only needed if you run <literal>make install</literal> later to
543         perform a "system" installation. The prefix is
544         <literal>/usr/local</literal> if not specified.
545         </para>
546        </listitem>
547       </varlistentry>
548       <varlistentry>
549        <term>
550         <literal>--enable-tcpd</literal>
551        </term>
552        <listitem>
553         <para>The front end server will be built using Wietse's
554         <ulink url="&url.tcpwrapper;">TCP wrapper library</ulink>.
555         It allows you to allow/deny clients depending on IP number.
556         The TCP wrapper library is often used in GNU/Linux and
557         BSD distributions.
558         See
559         <citerefentry>
560          <refentrytitle>hosts_access</refentrytitle>
561          <manvolnum>5</manvolnum>
562         </citerefentry>
563         and
564         <citerefentry>
565          <refentrytitle>tcpd</refentrytitle>
566          <manvolnum>8</manvolnum>
567          </citerefentry>.
568         </para>
569        </listitem>
570       </varlistentry>
571       <varlistentry>
572        <term>
573         <literal>--enable-threads</literal>
574        </term>
575        <listitem>
576         <para>&yaz; will be built using POSIX threads.
577         Specifically, <constant>_REENTRANT</constant> will be defined during
578         compilation.
579         </para>
580        </listitem>
581       </varlistentry>
582       <varlistentry>
583        <term>
584         <literal>--disable-shared</literal>
585        </term>
586        <listitem>
587         <para>The make process will not create shared
588         libraries (also known as shared objects <filename>.so</filename>).
589         By default, shared libraries are created -
590         equivalent to <literal>--enable-shared</literal>.
591        </para>
592        </listitem>
593       </varlistentry>
594       <varlistentry>
595        <term>
596         <literal>--disable-shared</literal>
597        </term>
598        <listitem>
599         <para>The make process will not create
600         static libraries (<filename>.a</filename>).
601         By default, static libraries are created -
602         equivalent to <literal>--enable-static</literal>.
603         </para>
604        </listitem>
605       </varlistentry>
606       <varlistentry>
607        <term>
608         <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
609        </term>
610        <listitem>
611         <para>Compile &yaz; with iconv library in directory
612         <replaceable>prefix</replaceable>. By default configure will
613         search for iconv on the system. Use this option if it
614         doesn't find iconv. Alternatively,
615         <literal>--without-iconv</literal>, can be uset to force &yaz;
616         not to use iconv.
617         </para>
618        </listitem>
619       </varlistentry>
620       <varlistentry>
621        <term>
622         <literal>--with-xslt</literal>[=<replaceable>prefix</replaceable>]
623        </term>
624        <listitem>
625         <para>Compile &yaz; with
626         <ulink url="&url.libxslt;">libxslt</ulink> in directory
627         <replaceable>prefix</replaceable>.
628         Use this option if you want XSLT and XML support.
629         By default, configure will
630         search for libxslt on the system. Use this option if it
631         libxslt is not found automatically. Alternatively,
632         <literal>--without-xslt</literal>, can be used to force &yaz;
633         not to use libxslt.
634         </para>
635        </listitem>
636       </varlistentry>
637       <varlistentry>
638        <term>
639         <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
640        </term>
641        <listitem>
642         <para>Compile &yaz; with
643         <ulink url="&url.libxml2;">libxml2</ulink> in directory
644         <replaceable>prefix</replaceable>.
645         Use this option if you want &yaz; to use XML and support SRU/Solr.
646         By default, configure will
647         search for libxml2 on the system. Use this option if it
648         libxml2 is not found automatically. Alternatively,
649         <literal>--without-xml2</literal>, can be used to force &yaz;
650         not to use libxml2.
651         </para>
652         <para>
653          Note that option <literal>--with-xslt</literal>
654          also enables libxml2.
655         </para>
656        </listitem>
657       </varlistentry>
658       <varlistentry>
659        <term>
660         <literal>--with-gnutls</literal>[=<replaceable>prefix</replaceable>]
661        </term>
662        <listitem>
663         <para>&yaz; will be linked with the GNU TLS libraries and
664         an SSL COMSTACK will be provided. By default configure enables
665         SSL support for YAZ if the GNU TLS development libraries are found
666         on the system.
667         </para>
668        </listitem>
669       </varlistentry>
670       <varlistentry>
671        <term>
672         <literal>--with-icu</literal>[=<replaceable>prefix</replaceable>]
673        </term>
674        <listitem>
675         <para>&yaz; will be linked the
676         <ulink url="&url.icu;">ICU</ulink> library in the prefix if given.
677         If prefix is not given, the libraries exposed by the script
678         <application>icu-config</application> will be used if found.
679         </para>
680        </listitem>
681       </varlistentry>
682
683       <varlistentry>
684        <term>
685         <literal>--with-libgcrypt</literal>[=<replaceable>prefix</replaceable>]
686        </term>
687        <listitem>
688         <para>&yaz; will be linked with
689         <ulink url="&url.libgcrypt;">Libgcrypt</ulink> in the prefix if given.
690         If prefix is not given, the libraries exposed by the script
691         <application>libgcrypt-config</application> will be used if found.
692         </para>
693        </listitem>
694       </varlistentry>
695       <varlistentry>
696        <term>
697         <literal>--with-memcached</literal>
698        </term>
699        <listitem>
700         <para>&yaz; will be linked with
701         <ulink url="&url.libmemcached;">libMemcached</ulink> to allow
702         for result-set caching for ZOOM.
703         The prefix can not be given. Note that YAZ will only search
704         for libMemcached if Libgcrypt is also enabled.
705        </para>
706        </listitem>
707       </varlistentry>
708      </variablelist>
709     </para>
710     <para>
711      When configured, build the software by typing:
712      <screen>
713       make
714      </screen>
715     </para>
716     <para>
717      The following files are generated by the make process:
718      <variablelist>
719       <varlistentry>
720        <term><filename>src/libyaz.la</filename></term>
721        <listitem><para>
722         Main &yaz; library. This is no ordinary library. It's
723         a Libtool archive.
724         By default, &yaz; creates a static library in
725         <filename>lib/.libs/libyaz.a</filename>.
726        </para></listitem>
727       </varlistentry>
728       <varlistentry>
729        <term><filename>src/libyaz_server.la</filename></term>
730        <listitem><para>
731          Generic Frontend server. This is an add-on for libyaz.la.
732          Code in this library uses POSIX threads functions - if POSIX
733          threads are available on the platform.
734         </para></listitem>
735       </varlistentry>
736       <varlistentry>
737        <term><filename>src/libyaz_icu.la</filename></term>
738        <listitem><para>
739         Functions that wrap the ICU library.
740         </para></listitem>
741       </varlistentry>
742       <varlistentry>
743        <term><filename>ztest/yaz-ztest</filename></term>
744        <listitem><para>Test Z39.50 server.
745        </para></listitem>
746       </varlistentry>
747       <varlistentry>
748        <term><filename>client/yaz-client</filename></term>
749        <listitem><para>Z39.50 client for testing the protocol.
750        See chapter <link linkend="yaz-client">
751        YAZ client</link> for more information.
752        </para></listitem>
753       </varlistentry>
754       <varlistentry>
755        <term><filename>util/yaz-config</filename></term>
756        <listitem><para>A Bourne-shell script, generated by configure, that
757        specifies how external applications should compile - and link with
758        &yaz;.
759        </para></listitem>
760       </varlistentry>
761       <varlistentry>
762        <term><filename>util/yaz-asncomp</filename></term>
763        <listitem><para>The ASN.1 compiler for &yaz;. Requires the
764        Tcl Shell, <application>tclsh</application>, in
765        <literal>PATH</literal> to operate.
766        </para></listitem>
767       </varlistentry>
768       <varlistentry>
769        <term><filename>util/yaz-iconv</filename></term>
770        <listitem><para>This program converts data in one character set to
771        another. This command exercises the YAZ character set
772        conversion API.
773        </para></listitem>
774       </varlistentry>
775       <varlistentry>
776        <term><filename>util/yaz-marcdump</filename></term>
777        <listitem><para>This program parses ISO2709 encoded MARC records
778        and prints them in line-format or XML.
779        </para></listitem>
780       </varlistentry>
781       <varlistentry>
782        <term><filename>util/yaz-icu</filename></term>
783        <listitem><para>This program exposes the ICU wrapper library if that
784        is enabled for YAZ. Only if ICU is available this program is
785        useful.
786        </para></listitem>
787       </varlistentry>
788       <varlistentry>
789        <term><filename>util/yaz-url</filename></term>
790        <listitem><para>This program is a simple HTTP page fetcher ala
791        wget or curl.
792        </para></listitem>
793       </varlistentry>
794       <varlistentry>
795        <term><filename>zoom/zoomsh</filename></term>
796        <listitem><para>
797         A simple shell implemented on top of the
798         <link linkend="zoom">ZOOM</link> functions.
799         The shell is a command line application that allows you to enter
800         simple commands to perform ZOOM operations.
801        </para></listitem>
802       </varlistentry>
803       <varlistentry>
804        <term><filename>zoom/zoomtst1</filename>,
805        <filename>zoom/zoomtst2</filename>, ..</term>
806        <listitem><para>
807         Several small applications that demonstrates the ZOOM API.
808        </para></listitem>
809       </varlistentry>
810      </variablelist>
811     </para>
812     <para>
813      If you wish to install &yaz; in system directories
814      <filename>/usr/local/bin</filename>,
815      <filename>/usr/local/lib</filename> .. etc, you can type:
816     </para>
817     <screen>
818      make install
819     </screen>
820     <para>
821      You probably need to have root access in order to perform this.
822      You must specify the <literal>--prefix</literal> option for configure if
823      you wish to install &yaz; in other directories than the default
824      <filename>/usr/local/</filename>.
825     </para>
826     <para>
827      If you wish to perform an un-installation of &yaz;, use:
828     </para>
829     <screen>
830      make uninstall
831     </screen>
832     <para>
833      This will only work if you haven't reconfigured &yaz; (and therefore
834      changed installation prefix). Note that uninstall will not
835      remove directories created by make install, e.g.
836      <filename>/usr/local/include/yaz</filename>.
837     </para>
838    </sect2>
839    <sect2 id="installation-linking-yaz-unix">
840     <title>How to make apps using YAZ on UNIX</title>
841     <para>
842      This section describes how to compile - and link your own
843      applications using the &yaz; toolkit.
844      If you're used to Makefiles this shouldn't be hard. As for
845      other libraries you have used before, you have to set a proper include
846      path for your C/C++ compiler and specify the location of
847      &yaz; libraries. You can do it by hand, but generally we suggest
848      you use the <filename>yaz-config</filename> that is generated
849      by <filename>configure</filename>. This is especially
850      important if you're using the threaded version of &yaz; which
851      require you to pass more options to your linker/compiler.
852     </para>
853     <para>
854      The <filename>yaz-config</filename> script accepts command line
855      options that makes the <filename>yaz-config</filename> script print
856      options that you should use in your make process.
857      The most important ones are:
858      <literal>--cflags</literal>, <literal>--libs</literal>
859      which prints C compiler flags, and linker flags respectively.
860     </para>
861     <para>
862      A small and complete <literal>Makefile</literal> for a C
863      application consisting of one source file,
864      <filename>myprog.c</filename>, may look like this:
865      <screen>
866       YAZCONFIG=/usr/local/bin/yaz-config
867       CFLAGS=`$(YAZCONFIG) --cflags`
868       LIBS=`$(YAZCONFIG) --libs`
869       myprog: myprog.o
870          $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
871       </screen>
872     </para>
873     <para>
874      The CFLAGS variable consists of a C compiler directive that will set
875      the include path to the <emphasis>parent</emphasis> directory
876      of <filename>yaz</filename>. That is, if &yaz; header files were
877      installed in <filename>/usr/local/include/yaz</filename>,
878      then include path is set to <filename>/usr/local/include</filename>.
879      Therefore, in your applications you should use
880      <screen>
881       #include &lt;yaz/proto.h>
882      </screen>
883      and <emphasis>not</emphasis>
884      <screen>
885       #include &lt;proto.h>
886      </screen>
887     </para>
888     <para>
889      For Libtool users, the <filename>yaz-config</filename> script provides
890      a different variant of option <literal>--libs</literal>, called
891      <literal>--lalibs</literal> that returns the name of the
892      Libtool archive(s) for &yaz; rather than the ordinary ones.
893     </para>
894     <para>
895      For applications using the threaded version of &yaz;,
896      specify <literal>threads</literal> after the
897      other options. When <literal>threads</literal> is given,
898      more flags and linker flags will be printed by
899      <filename>yaz-config</filename>. If our previous example was
900       using threads, you'd have to modify the lines that set
901      <literal>CFLAGS</literal> and <literal>LIBS</literal> as
902      follows:
903      <screen>
904       CFLAGS=`$(YAZCONFIG) --cflags threads`
905       LIBS=`$(YAZCONFIG) --libs threads`
906      </screen>
907      There is no need specify POSIX thread libraries in your Makefile.
908      The <literal>LIBS</literal> variable includes that as well.
909     </para>
910    </sect2>
911   </sect1>
912   <sect1 id="installation.win32">
913    <title>WIN32</title>
914    <para>The easiest way to install YAZ on Windows is by downloading
915    an installer from
916    <ulink url="&url.yaz.download.win32;">here</ulink>.
917    The installer comes with source too - in case you wish to
918    compile YAZ with different compiler options, etc.
919    </para>
920
921    <sect2 id="installation.win32.source">
922     <title>Compiling from Source on WIN32</title>
923     <para>
924      &yaz; is shipped with "makefiles" for the NMAKE tool that comes
925      with <ulink url="&url.vstudio;">
926      Microsoft Visual Studio</ulink>. It has been tested with
927      Microsoft Visual Studio 2003/2005/2008.
928     </para>
929     <para>
930      Start a command prompt and switch the sub directory
931      <filename>WIN</filename> where the file <filename>makefile</filename>
932      is located. Customize the installation by editing the
933      <filename>makefile</filename> file (for example by using notepad).
934      The following summarizes the most important settings in that file:
935      <variablelist>
936       <varlistentry>
937        <term><literal>DEBUG</literal></term>
938        <listitem><para>
939         If set to 1, the software is
940         compiled with debugging libraries (code generation is
941         multi-threaded debug DLL).
942         If set to 0, the software is compiled with release libraries
943         (code generation is multi-threaded DLL).
944        </para></listitem>
945       </varlistentry>
946       <varlistentry>
947        <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
948        <listitem><para>
949         If <literal>HAVE_TCL</literal> is set to 1, nmake will
950         use the ASN.1 compiler (<ulink url="&url.tcl;">Tcl</ulink> based).
951         You must set <literal>TCL</literal> to the full path of the Tcl
952         interpreter. A Windows version of Tcl is part of
953         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
954        </para>
955        <para>
956         If you do not have Tcl installed, set
957         <literal>HAVE_TCL</literal> to 0.
958        </para></listitem>
959       </varlistentry>
960       <varlistentry>
961        <term><literal>HAVE_BISON</literal>,
962        <literal>BISON</literal></term>
963        <listitem><para>
964         If GNU Bison is present, you might set <literal>HAVE_BISON</literal>
965         to 1 and specify the Bison executable in <literal>BISON</literal>.
966         Bison is only required if you use the Git version of
967         YAZ or if you modify the grammar for CQL
968         (<filename>cql.y</filename>).
969        </para>
970        <para>
971         A Windows version of GNU Bison is part of
972         <ulink url="&url.gitwindows;">Git for Windows</ulink>.
973        </para></listitem>
974       </varlistentry>
975       <varlistentry>
976        <term><literal>HAVE_ICONV</literal>,
977        <literal>ICONV_DIR</literal></term>
978        <listitem><para>
979         If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
980         with iconv support. In this configuration, set
981         <literal>ICONV_DIR</literal> to the iconv source directory.
982        </para></listitem>
983       </varlistentry>
984       <varlistentry>
985        <term><literal>HAVE_LIBXML2</literal>,
986        <literal>LIBXML2_DIR</literal></term>
987        <listitem>
988         <para>
989          If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
990          with SRU support. In this configuration, set
991          <literal>LIBXML2_DIR</literal> to the
992          <ulink url="&url.libxml2;">libxml2</ulink> source directory
993          and
994          <literal>ZLIB_DIR</literal> to the zlib directory.
995         </para>
996         <para>
997          Windows versions of libxslt, libxml2, zlib and iconv can be found
998          <ulink url="&url.libxml2.download.win32;">
999           Igor Zlatkovi&#x0107;' site</ulink>.
1000         </para>
1001         <note>
1002          <para>
1003           YAZ is not using zlib but libxml2 is depending on it.
1004          </para>
1005         </note>
1006        </listitem>
1007       </varlistentry>
1008       <varlistentry>
1009        <term><literal>HAVE_LIBXSLT</literal>,
1010        <literal>LIBXSLT_DIR</literal></term>
1011        <listitem>
1012         <para>
1013          If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
1014          with XSLT support. In this configuration, set
1015          <literal>LIBXSLT_DIR</literal> to the
1016          <ulink url="&url.libxslt;">libxslt</ulink> source directory.
1017         </para>
1018         <note>
1019          <para>
1020           libxslt depends libxml2.
1021          </para>
1022         </note>
1023        </listitem>
1024       </varlistentry>
1025       <varlistentry>
1026        <term><literal>HAVE_ICU</literal>,
1027        <literal>ICU_DIR</literal></term>
1028        <listitem>
1029         <para>
1030          If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
1031          with <ulink url="&url.icu;">ICU</ulink> support.
1032          In this configuration, set
1033          <literal>ICU_DIR</literal> to the
1034          <ulink url="&url.icu;">ICU</ulink> source directory.
1035         </para>
1036        </listitem>
1037       </varlistentry>
1038      </variablelist>
1039     </para>
1040     <para>
1041      When satisfied with the settings in the makefile, type
1042      <screen>
1043       nmake
1044      </screen>
1045     </para>
1046     <note>
1047      <para>
1048       If the <filename>nmake</filename> command is not found on your system
1049       you probably haven't defined the environment variables required to
1050       use that tool. To fix that, find and run the batch file
1051       <filename>vcvars32.bat</filename>. You need to run it from within
1052       the command prompt or set the environment variables "globally";
1053       otherwise it doesn't work.
1054      </para>
1055     </note>
1056     <para>
1057      If you wish to recompile &yaz; - for example if you modify
1058      settings in the <filename>makefile</filename> you can delete
1059      object files, etc by running.
1060      <screen>
1061       nmake clean
1062      </screen>
1063     </para>
1064     <para>
1065      The following files are generated upon successful compilation:
1066      <variablelist>
1067       <varlistentry>
1068        <term><filename>bin/yaz&soversion;.dll</filename> /
1069        <filename>bin/yaz&soversion;d.dll</filename></term>
1070        <listitem><para>
1071         &yaz; Release/Debug DLL.
1072        </para></listitem>
1073       </varlistentry>
1074       <varlistentry>
1075        <term><filename>lib/yaz&soversion;.lib</filename> /
1076        <filename>lib/yaz&soversion;d.lib</filename></term>
1077        <listitem><para>
1078         Import library for <filename>yaz&soversion;.dll</filename> /
1079         <filename>yaz&soversion;d.dll</filename>.
1080       </para></listitem>
1081       </varlistentry>
1082       <varlistentry>
1083        <term><filename>bin/yaz_cond&soversion;.dll</filename> /
1084        <filename>bin/yaz_cond&soversion;d.dll</filename></term>
1085        <listitem><para>
1086         Release/Debug DLL for condition variable utilities (condvar.c).
1087        </para></listitem>
1088       </varlistentry>
1089       <varlistentry>
1090        <term><filename>lib/yaz_cond&soversion;.lib</filename> /
1091        <filename>lib/yaz_cond&soversion;d.lib</filename></term>
1092        <listitem><para>
1093         Import library for <filename>yaz_cond&soversion;.dll</filename> /
1094         <filename>yaz_cond&soversion;d.dll</filename>.
1095        </para></listitem>
1096       </varlistentry>
1097       <varlistentry>
1098        <term><filename>bin/yaz_icu&soversion;.dll</filename> /
1099        <filename>bin/yaz_icu&soversion;d.dll</filename></term>
1100        <listitem><para>
1101         Release/Debug DLL for the ICU wrapper utility.
1102         Only build if HAVE_ICU is 1.
1103        </para></listitem>
1104       </varlistentry>
1105       <varlistentry>
1106        <term><filename>lib/yaz_icu&soversion;.lib</filename> /
1107        <filename>lib/yaz_icu&soversion;d.lib</filename></term>
1108        <listitem><para>
1109         Import library for <filename>yaz_icu&soversion;.dll</filename> /
1110         <filename>yaz_icu&soversion;d.dll</filename>.
1111        </para></listitem>
1112       </varlistentry>
1113       <varlistentry>
1114        <term><filename>bin/yaz-ztest.exe</filename></term>
1115        <listitem><para>
1116         Z39.50 multi-threaded test/example server. It's a WIN32
1117         console application.
1118       </para></listitem>
1119       </varlistentry>
1120       <varlistentry>
1121        <term><filename>bin/yaz-client.exe</filename></term>
1122        <listitem><para>
1123         &yaz; Z39.50 client application. It's a WIN32 console application.
1124         See chapter <link linkend="yaz-client">YAZ client</link> for more
1125         information.
1126       </para></listitem>
1127       </varlistentry>
1128       <varlistentry>
1129        <term><filename>bin/yaz-icu.exe</filename></term>
1130        <listitem><para>This program exposes the ICU wrapper library if that
1131        is enabled for YAZ. Only if ICU is available this program is
1132        build.
1133       </para></listitem>
1134       </varlistentry>
1135       <varlistentry>
1136        <term><filename>bin/zoomsh.exe</filename></term>
1137        <listitem><para>
1138         Simple console application implemented on top of the
1139         <link linkend="zoom">ZOOM</link> functions.
1140         The application is a command line shell that allows you to enter
1141         simple commands to perform ZOOM operations.
1142       </para></listitem>
1143       </varlistentry>
1144       <varlistentry>
1145        <term><filename>bin/zoomtst1.exe</filename>,
1146        <filename>bin/zoomtst2.exe</filename>, ..</term>
1147        <listitem><para>
1148         Several small applications that demonstrates the ZOOM API.
1149       </para></listitem>
1150       </varlistentry>
1151      </variablelist>
1152     </para>
1153    </sect2>
1154
1155    <sect2 id="installation-linking-yaz-win32">
1156     <title>How to make apps using YAZ on WIN32</title>
1157     <para>
1158      This section will go though the process of linking your WIN32
1159      applications with &yaz;.
1160     </para>
1161     <para>
1162      Some people are confused by the fact that we use the nmake
1163      tool to build &yaz;. They think they have to do that too - in order
1164      to make their WIN32 applications work with &yaz;. The good news is that
1165      you don't have to. You can use the integrated environment of
1166      Visual Studio if desired for your own application.
1167     </para>
1168     <para>
1169      When setting up a project or Makefile you have to set the following:
1170      <variablelist>
1171       <varlistentry>
1172        <term>include path</term>
1173        <listitem><para>
1174         Set it to the <filename>include</filename> directory of &yaz;.
1175         </para></listitem>
1176       </varlistentry>
1177       <varlistentry>
1178        <term>import library <filename>yaz&soversion;.lib</filename></term>
1179        <listitem><para>
1180         You must link with this library. It's located in the
1181         sub directory <filename>lib</filename> of &yaz;.
1182         If you want to link with the debug version of &yaz;, you must
1183         link against <filename>yaz&soversion;d.lib</filename> instead.
1184        </para></listitem>
1185       </varlistentry>
1186       <varlistentry>
1187        <term>dynamic link library
1188        <filename>yaz&soversion;.dll</filename>
1189        </term>
1190        <listitem><para>
1191         This DLL must be in your execution path when you invoke
1192         your application. Specifically, you should distribute this
1193         DLL with your application.
1194        </para></listitem>
1195       </varlistentry>
1196      </variablelist>
1197     </para>
1198    </sect2>
1199   </sect1>
1200  </chapter>
1201  <!--
1202      ### Still to document:
1203      ZOOM_connection_errcode(c)
1204      ZOOM_connection_errmsg(c)
1205      ZOOM_connection_addinfo(c)
1206      ZOOM_connection_addinfo(c)
1207      ZOOM_connection_diagset(c);
1208      ZOOM_connection_save_apdu_wrbuf
1209      ZOOM_diag_str(error)
1210      ZOOM_resultset_record_immediate(s, pos)
1211      ZOOM_resultset_cache_reset(r)
1212      ZOOM_options_set_callback(opt, function, handle)
1213      ZOOM_options_create_with_parent2(parent1, parent2)
1214      ZOOM_options_getl(opt, name, len)
1215      ZOOM_options_setl(opt, name, value, len)
1216      ZOOM_options_get_bool(opt, name, defa)
1217      ZOOM_options_get_int(opt, name, defa)
1218      ZOOM_options_set_int(opt, name, value)
1219  -->
1220  <chapter id="zoom">
1221   <title>ZOOM</title>
1222   <para>
1223    &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
1224    an initiative started by Mike Taylor (Mike is from the UK, which
1225    explains the peculiar name of the model). The goal of &zoom; is to
1226    provide a common Z39.50 client API not bound to a particular
1227    programming language or toolkit.
1228   </para>
1229   <para>
1230    From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
1231    You can make SRU ZOOM connections by specifying scheme
1232    <literal>http://</literal> for the hostname for a connection.
1233    The dialect of SRU used is specified by the value of the
1234    connection's <literal>sru</literal> option, which may be SRU over
1235    HTTP GET (<literal>get</literal>),
1236    SRU over HTTP POST (<literal>post</literal>), (SRU over
1237    SOAP) (<literal>soap</literal>) or <literal>solr</literal>
1238    (<ulink url="&url.solr;">Solr</ulink> Web Service).
1239    Using the facility for embedding options in target strings, a
1240    connection can be forced to use SRU rather the SRW (the default) by
1241    prefixing the target string with <literal>sru=get,</literal>, like this:
1242    <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
1243   </para>
1244   <para>
1245    <ulink url="&url.solr;">Solr</ulink>  protocol support was added to
1246    YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
1247    HTTP based protocols.
1248   </para>
1249   <para>
1250    The lack of a simple Z39.50 client API for &yaz; has become more
1251    and more apparent over time. So when the first &zoom; specification
1252    became available,
1253    an implementation for &yaz; was quickly developed. For the first time, it is
1254    now as easy (or easier!) to develop clients than servers with &yaz;. This
1255    chapter describes the &zoom; C binding. Before going further, please
1256    reconsider whether C is the right programming language for the job.
1257    There are other language bindings available for &yaz;, and still
1258    more
1259    are in active development. See the
1260    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
1261    more information.
1262   </para>
1263   <para>
1264    In order to fully understand this chapter you should read and
1265    try the example programs <literal>zoomtst1.c</literal>,
1266    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
1267    directory.
1268   </para>
1269   <para>
1270    The C language misses features found in object oriented languages
1271    such as C++, Java, etc. For example, you'll have to manually,
1272    destroy all objects you create, even though you may think of them as
1273    temporary. Most objects has a <literal>_create</literal> - and a
1274    <literal>_destroy</literal> variant.
1275    All objects are in fact pointers to internal stuff, but you don't see
1276    that because of typedefs. All destroy methods should gracefully ignore a
1277    <literal>NULL</literal> pointer.
1278   </para>
1279   <para>
1280    In each of the sections below you'll find a sub section called
1281    protocol behavior, that describes how the API maps to the Z39.50
1282    protocol.
1283   </para>
1284   <sect1 id="zoom-connections">
1285    <title>Connections</title>
1286    <para>The Connection object is a session with a target.
1287    </para>
1288    <synopsis>
1289     #include &lt;yaz/zoom.h>
1290
1291     ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
1292
1293     ZOOM_connection ZOOM_connection_create(ZOOM_options options);
1294
1295     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
1296                                  int portnum);
1297     void ZOOM_connection_destroy(ZOOM_connection c);
1298    </synopsis>
1299    <para>
1300     Connection objects are created with either function
1301     <function>ZOOM_connection_new</function> or
1302     <function>ZOOM_connection_create</function>.
1303     The former creates and automatically attempts to establish a network
1304     connection with the target. The latter doesn't establish
1305     a connection immediately, thus allowing you to specify options
1306     before establishing network connection using the function
1307     <function>ZOOM_connection_connect</function>.
1308     If the port number, <literal>portnum</literal>, is zero, the
1309     <literal>host</literal> is consulted for a port specification.
1310     If no port is given, 210 is used. A colon denotes the beginning of
1311     a port number in the host string. If the host string includes a
1312     slash, the following part specifies a database for the connection.
1313    </para>
1314    <para>
1315     You can prefix the host with a scheme followed by colon. The
1316     default scheme is <literal>tcp</literal> (Z39.50 protocol).
1317     The scheme <literal>http</literal> selects SRU/get over HTTP by default,
1318     but can overridded to use SRU/post, SRW and the Solr protocol.
1319    </para>
1320    <para>
1321     You can prefix the scheme-qualified host-string with one or more
1322     comma-separated
1323     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
1324     sequences, each of which represents an option to be set into the
1325     connection structure <emphasis>before</emphasis> the
1326     protocol-level connection is forged and the initialization
1327     handshake takes place.  This facility can be used to provide
1328     authentication credentials, as in host-strings such as:
1329     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
1330    </para>
1331    <para>
1332     Connection objects should be destroyed using the function
1333     <function>ZOOM_connection_destroy</function>.
1334    </para>
1335    <synopsis>
1336     void ZOOM_connection_option_set(ZOOM_connection c,
1337                                     const char *key, const char *val);
1338
1339     void ZOOM_connection_option_setl(ZOOM_connection c,
1340                                      const char *key,
1341                                      const char *val, int len);
1342
1343     const char *ZOOM_connection_option_get(ZOOM_connection c,
1344                                            const char *key);
1345     const char *ZOOM_connection_option_getl(ZOOM_connection c,
1346                                             const char *key,
1347                                             int *lenp);
1348    </synopsis>
1349    <para>
1350     The functions <function>ZOOM_connection_option_set</function> and
1351     <function>ZOOM_connection_option_setl</function> allows you to
1352     set an option given by <parameter>key</parameter> to the value
1353     <parameter>value</parameter> for the connection.
1354     For <function>ZOOM_connection_option_set</function>, the
1355     value is assumed to be a 0-terminated string. Function
1356     <function>ZOOM_connection_option_setl</function> specifies a
1357     value of a certain size (len).
1358    </para>
1359    <para>
1360     Functions <function>ZOOM_connection_option_get</function> and
1361     <function>ZOOM_connection_option_getl</function> returns
1362     the value for an option given by <parameter>key</parameter>.
1363    </para>
1364    <table id="zoom-connection-options" frame="top">
1365     <title>ZOOM Connection Options</title>
1366     <tgroup cols="3">
1367      <colspec colwidth="4*" colname="name"></colspec>
1368      <colspec colwidth="7*" colname="description"></colspec>
1369      <colspec colwidth="3*" colname="default"></colspec>
1370      <thead>
1371       <row>
1372        <entry>Option</entry>
1373        <entry>Description</entry>
1374        <entry>Default</entry>
1375       </row>
1376      </thead>
1377      <tbody>
1378       <row><entry>
1379        implementationName</entry><entry>Name of Your client
1380       </entry><entry>none</entry></row>
1381       <row><entry>
1382        user</entry><entry>Authentication user name
1383       </entry><entry>none</entry></row>
1384       <row><entry>
1385        group</entry><entry>Authentication group name
1386       </entry><entry>none</entry></row>
1387       <row><entry>
1388        password</entry><entry>Authentication password.
1389       </entry><entry>none</entry></row>
1390       <row><entry>
1391        authenticationMode</entry><entry>How authentication is encoded.
1392       </entry><entry>basic</entry></row>
1393       <row><entry>
1394        host</entry><entry>Target host. This setting is "read-only".
1395        It's automatically set internally when connecting to a target.
1396       </entry><entry>none</entry></row>
1397       <row><entry>
1398        proxy</entry><entry>Proxy host. If set, the logical host
1399        is encoded in the otherInfo area of the Z39.50 Init PDU
1400        with OID 1.2.840.10003.10.1000.81.1.
1401       </entry><entry>none</entry></row>
1402       <row><entry>
1403        clientIP</entry><entry>Client IP. If set, is
1404        encoded in the otherInfo area of a Z39.50 PDU with OID
1405        1.2.840.10003.10.1000.81.3. Holds the original IP addreses
1406        of a client. Is used of ZOOM is used in a gateway of some sort.
1407       </entry><entry>none</entry></row>
1408       <row><entry>
1409        async</entry><entry>If true (1) the connection operates in
1410        asynchronous operation which means that all calls are non-blocking
1411        except
1412        <link linkend="zoom.events"><function>ZOOM_event</function></link>.
1413       </entry><entry>0</entry></row>
1414       <row><entry>
1415        maximumRecordSize</entry><entry> Maximum size of single record.
1416       </entry><entry>1 MB</entry></row>
1417       <row><entry>
1418        preferredMessageSize</entry><entry> Maximum size of multiple records.
1419       </entry><entry>1 MB</entry></row>
1420       <row><entry>
1421        lang</entry><entry> Language for negotiation.
1422       </entry><entry>none</entry></row>
1423       <row><entry>
1424        charset</entry><entry> Character set for negotiation.
1425       </entry><entry>none</entry></row>
1426       <row><entry>
1427        serverImplementationId</entry><entry>
1428        Implementation ID of server.  (The old targetImplementationId
1429        option is also supported for the benefit of old applications.)
1430       </entry><entry>none</entry></row>
1431       <row><entry>
1432        targetImplementationName</entry><entry>
1433        Implementation Name of server.  (The old
1434        targetImplementationName option is also supported for the
1435        benefit of old applications.)
1436       </entry><entry>none</entry></row>
1437       <row><entry>
1438        serverImplementationVersion</entry><entry>
1439        Implementation Version of server.  (the old
1440        targetImplementationVersion option is also supported for the
1441        benefit of old applications.)
1442       </entry><entry>none</entry></row>
1443       <row><entry>
1444        databaseName</entry><entry>One or more database names
1445        separated by character plus (<literal>+</literal>), which to
1446        be used by subsequent search requests on this Connection.
1447       </entry><entry>Default</entry></row>
1448       <row><entry>
1449        piggyback</entry><entry>True (1) if piggyback should be
1450        used in searches; false (0) if not.
1451       </entry><entry>1</entry></row>
1452       <row><entry>
1453        smallSetUpperBound</entry><entry>If hits is less than or equal to this
1454        value, then target will return all records using small element set name
1455       </entry><entry>0</entry></row>
1456       <row><entry>
1457        largeSetLowerBound</entry><entry>If hits is greater than this
1458        value, the target will return no records.
1459       </entry><entry>1</entry></row>
1460       <row><entry>
1461        mediumSetPresentNumber</entry><entry>This value represents
1462        the number of records to be returned as part of a search when when
1463        hits is less than or equal to large set lower bound and if hits
1464        is greater than small set upper bound.
1465       </entry><entry>0</entry></row>
1466       <row><entry>
1467        smallSetElementSetName</entry><entry>
1468        The element set name to be used for small result sets.
1469       </entry><entry>none</entry></row>
1470       <row><entry>
1471        mediumSetElementSetName</entry><entry>
1472        The element set name to be for medium-sized result sets.
1473       </entry><entry>none</entry></row>
1474       <row><entry>
1475        init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
1476        After a successful Init, these options may be interrogated to
1477        discover whether the server claims to support the specified
1478        operations.
1479       </entry><entry>none</entry></row>
1480       <row>
1481        <entry>sru</entry><entry>
1482        SRU/Solr transport type. Must be either <literal>soap</literal>,
1483        <literal>get</literal>, <literal>post</literal>, or
1484        <literal>solr</literal>.
1485       </entry><entry>soap</entry></row>
1486       <row><entry>
1487        sru_version</entry><entry>
1488        SRU/SRW version. Should be <literal>1.1</literal>, or
1489        <literal>1.2</literal>. This is , prior to connect, the version
1490        to offer (highest version). And following connect (in fact
1491        first operation), holds the negotiated version with the server
1492        (same or lower version).
1493       </entry><entry>1.2</entry></row>
1494       <row id="zoom.facets.option"><entry>
1495        facets</entry><entry>
1496        Requested or recommend facets may be given before a search is sent.
1497        The value of this setting is described in <xref linkend="facets"/>
1498        For inspection of the facets returned, refer to the functions
1499        described in <xref linkend="zoom.facets"/>.
1500       </entry><entry>none</entry></row>
1501       <row><entry>
1502        apdulog</entry><entry>
1503        If set to a true value such as "1", a log of low-level
1504        protocol packets is emitted on standard error stream.  This
1505        can be very useful for debugging.
1506       </entry><entry>0</entry></row>
1507       <row><entry>
1508        saveAPDU</entry><entry>
1509        If set to a true value such as "1", a log of low-level
1510        protocol packets is saved. The log can be retrieved by reading
1511        option APDU. Setting saveAPDU always has the side effect of
1512        resetting the currently saved log. This setting is
1513        <emphasis>write-only</emphasis>. If read, NULL will be returned.
1514        It is only recognized in
1515        <function>ZOOM_connection_option_set</function>.
1516       </entry><entry>0</entry></row>
1517       <row><entry>
1518        APDU</entry><entry>
1519        Returns the log of protocol packets. Will be empty if logging
1520        is not enabled (see saveAPDU above). This setting is
1521        <emphasis>read-only</emphasis>. It is only recognized if used
1522        in call to <function>ZOOM_connection_option_get</function> or
1523        <function>ZOOM_connection_option_getl</function>.
1524       </entry><entry></entry></row>
1525       <row><entry>
1526        memcached</entry><entry>
1527        If given and non-empty,
1528        <ulink url="&url.libmemcached;">libMemcached</ulink>
1529        will be configured for the connection.
1530        This option is inspected by ZOOM when a connection is  established.
1531        If the <literal>memcached</literal> option is given
1532        and YAZ is compiled without libMemcached support, an internal
1533        diagnostic (10018) will be thrown.
1534        libMemcached support is available for YAZ 5.0.13 or later. If this
1535        option is supplied for an earlier version of YAZ, it is
1536        <emphasis>ignored</emphasis>.
1537        The value of this option is a string passed verbatim to
1538        the <function>memcached</function> function part of libMemcached.
1539        Refer to man page
1540        <ulink url="http://manned.org/memcached.3">memcached(3)</ulink>.
1541        Earlier versions of libMemcached
1542        do not offer this function. In this case only the option
1543        <literal>--server=</literal><replaceable>host</replaceable> may
1544        be given (YAZ emulates that part of libMemcached).
1545       </entry><entry>none</entry></row>
1546      </tbody>
1547     </tgroup>
1548    </table>
1549    <para>
1550     If either option <literal>lang</literal> or <literal>charset</literal>
1551     is set, then
1552     <ulink url="&url.z39.50.charneg;">
1553      Character Set and Language Negotiation</ulink> is in effect.
1554    </para>
1555    <synopsis>
1556      int ZOOM_connection_error(ZOOM_connection c, const char **cp,
1557                                const char **addinfo);
1558      int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
1559                                  const char **addinfo, const char **dset);
1560    </synopsis>
1561    <para>
1562     Function <function>ZOOM_connection_error</function> checks for
1563     errors for the last operation(s) performed. The function returns
1564     zero if no errors occurred; non-zero otherwise indicating the error.
1565     Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
1566     holds messages for the error and additional-info if passed as
1567     non-<literal>NULL</literal>. Function
1568     <function>ZOOM_connection_error_x</function> is an extended version
1569     of <function>ZOOM_connection_error</function> that is capable of
1570     returning name of diagnostic set in <parameter>dset</parameter>.
1571    </para>
1572    <sect2 id="zoom-connection-z39.50">
1573     <title>Z39.50 Protocol behavior</title>
1574     <para>
1575      The calls <function>ZOOM_connection_new</function> and
1576      <function>ZOOM_connection_connect</function> establishes a TCP/IP
1577      connection and sends an Initialize Request to the target if
1578      possible. In addition, the calls waits for an Initialize Response
1579      from the target and the result is inspected (OK or rejected).
1580     </para>
1581     <para>
1582      If <literal>proxy</literal> is set then the client will establish
1583      a TCP/IP connection with the peer as specified by the
1584      <literal>proxy</literal> host and the hostname as part of the
1585      connect calls will be set as part of the Initialize Request.
1586      The proxy server will then "forward" the PDU's transparently
1587      to the target behind the proxy.
1588     </para>
1589     <para>
1590      For the authentication parameters, if option <literal>user</literal>
1591      is set and both options <literal>group</literal> and
1592      <literal>pass</literal> are unset, then Open style
1593      authentication is used (Version 2/3) in which case the username
1594      is usually followed by a slash, then by a password.
1595      If either <literal>group</literal>
1596      or <literal>pass</literal> is set then idPass authentication
1597      (Version 3 only) is used. If none of the options are set, no
1598      authentication parameters are set as part of the Initialize Request
1599      (obviously).
1600     </para>
1601     <para>
1602      When option <literal>async</literal> is 1, it really means that
1603      all network operations are postponed (and queued) until the
1604      function <literal>ZOOM_event</literal> is invoked. When doing so
1605      it doesn't make sense to check for errors after
1606      <literal>ZOOM_connection_new</literal> is called since that
1607      operation "connecting - and init" is still incomplete and the
1608      API cannot tell the outcome (yet).
1609     </para>
1610     </sect2>
1611    <sect2 id="zoom.sru.init.behavior">
1612     <title>SRU/Solr Protocol behavior</title>
1613     <para>
1614      The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
1615      Inititialize Request, so  the connection phase merely establishes a
1616      TCP/IP connection with the HTTP server.
1617     </para>
1618     <para>Most of the ZOOM connection options do not
1619      affect SRU/Solr and they are ignored. However, future versions
1620      of &yaz; might honor <literal>implementationName</literal> and
1621      put that as part of User-Agent header for HTTP requests.
1622      </para>
1623     <para>
1624      The <literal>charset</literal> is used in the Content-Type header
1625      of HTTP requests.
1626     </para>
1627     <para>
1628      Setting <literal>authentcationMode</literal> specifies how
1629      authentication parameters are encoded for HTTP. The default is
1630      "<literal>basic</literal>" where <literal>user</literal> and
1631      <literal>password</literal> are encoded by using HTTP basic
1632      authentication.
1633      </para>
1634     <para>
1635      If <literal>authentcationMode</literal> is "<literal>url</literal>", then
1636      user and password are encoded in the URL by parameters
1637      <literal>x-username</literal> and <literal>x-password</literal> as
1638      given by the SRU standard.
1639     </para>
1640    </sect2>
1641   </sect1>
1642   <sect1 id="zoom.query">
1643    <title>Queries</title>
1644    <para>
1645     Query objects represents queries.
1646    </para>
1647    <synopsis>
1648      ZOOM_query ZOOM_query_create(void);
1649
1650      void ZOOM_query_destroy(ZOOM_query q);
1651
1652      int ZOOM_query_prefix(ZOOM_query q, const char *str);
1653
1654      int ZOOM_query_cql(ZOOM_query s, const char *str);
1655
1656      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
1657
1658      int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
1659                             const char *criteria);
1660    </synopsis>
1661    <para>
1662     Create query objects using <function>ZOOM_query_create</function>
1663     and destroy them by calling <function>ZOOM_query_destroy</function>.
1664     RPN-queries can be specified in <link linkend="PQF">PQF</link>
1665     notation by using the
1666     function <function>ZOOM_query_prefix</function>.
1667     The <function>ZOOM_query_cql</function> specifies a CQL
1668     query to be sent to the server/target.
1669     More query types will be added in future versions of &yaz;, such as
1670     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
1671     etc. In addition to a search, a sort criteria may be set. Function
1672     <function>ZOOM_query_sortby</function> enables Z39.50 sorting and
1673     it takes sort criteria using the same string notation as
1674     yaz-client's <link linkend="sortspec">sort command</link>.
1675    </para>
1676    <para id="zoom.query.sortby2">
1677     <function>ZOOM_query_sortby2</function> is similar to
1678     <function>ZOOM_query_sortby</function> but allows a strategy for
1679     sorting. The reason for the strategy parameter is that some
1680     protocols offers multiple ways of performing sorting.
1681     For example, Z39.50 has the standard sort, which is performed after
1682     search on an existing result set.
1683     It's also possible to use CQL in Z39.50 as the query type and use
1684     CQL's SORTBY keyword. Finally, Index Data's
1685     Zebra server also allows sorting to be specified as part of RPN (Type 7).
1686    </para>
1687    <table id="zoom-sort-strategy" frame="top">
1688     <title>ZOOM sort strategy</title>
1689     <tgroup cols="2">
1690      <colspec colwidth="2*" colname="name"/>
1691      <colspec colwidth="5*" colname="description"/>
1692      <thead>
1693       <row>
1694        <entry>Name</entry>
1695        <entry>Description</entry>
1696       </row>
1697      </thead>
1698      <tbody>
1699       <row>
1700        <entry>z39.50</entry><entry>Z39.50 resultset sort</entry>
1701       </row>
1702       <row>
1703        <entry>type7</entry><entry>Sorting embedded in RPN(Type-7)</entry>
1704       </row>
1705       <row>
1706        <entry>cql</entry><entry>CQL SORTBY</entry>
1707       </row>
1708       <row>
1709        <entry>sru11</entry><entry>SRU sortKeys parameter</entry>
1710       </row>
1711       <row>
1712        <entry>solr</entry><entry>Solr sort</entry>
1713       </row>
1714       <row>
1715        <entry>embed</entry><entry>type7 for Z39.50, cql for SRU,
1716         solr for Solr protocol</entry>
1717       </row>
1718      </tbody>
1719     </tgroup>
1720    </table>
1721   </sect1>
1722   <sect1 id="zoom.resultsets"><title>Result sets</title>
1723    <para>
1724     The result set object is a container for records returned from
1725     a target.
1726    </para>
1727    <synopsis>
1728      ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
1729
1730      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
1731                                                const char *q);
1732      void ZOOM_resultset_destroy(ZOOM_resultset r);
1733    </synopsis>
1734    <para>
1735     Function <function>ZOOM_connection_search</function> creates
1736     a result set given a connection and query.
1737     Destroy a result set by calling
1738     <function>ZOOM_resultset_destroy</function>.
1739     Simple clients may using PQF only may use function
1740     <function>ZOOM_connection_search_pqf</function> in which case
1741     creating query objects is not necessary.
1742    </para>
1743    <synopsis>
1744      void ZOOM_resultset_option_set(ZOOM_resultset r,
1745                                     const char *key, const char *val);
1746
1747      const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
1748
1749      size_t ZOOM_resultset_size(ZOOM_resultset r);
1750    </synopsis>
1751    <para>
1752     Functions <function>ZOOM_resultset_options_set</function> and
1753     <function>ZOOM_resultset_get</function> sets and gets an option
1754     for a result set similar to <function>ZOOM_connection_option_get</function>
1755     and <function>ZOOM_connection_option_set</function>.
1756    </para>
1757    <para>
1758     The number of hits also called result-count is returned by
1759     function <function>ZOOM_resultset_size</function>.
1760    </para>
1761    <table id="zoom.resultset.options"
1762     frame="top"><title>ZOOM Result set Options</title>
1763     <tgroup cols="3">
1764      <colspec colwidth="4*" colname="name"></colspec>
1765      <colspec colwidth="7*" colname="description"></colspec>
1766      <colspec colwidth="2*" colname="default"></colspec>
1767      <thead>
1768       <row>
1769        <entry>Option</entry>
1770        <entry>Description</entry>
1771        <entry>Default</entry>
1772       </row>
1773      </thead>
1774      <tbody>
1775       <row><entry>
1776         start</entry><entry>Offset of first record to be
1777         retrieved from target. First record has offset 0 unlike the
1778         protocol specifications where first record has position 1.
1779         This option affects ZOOM_resultset_search and
1780         ZOOM_resultset_search_pqf and must be set before any of
1781         these functions are invoked. If a range of
1782         records must be fetched manually after search,
1783         function ZOOM_resultset_records should be used.
1784        </entry><entry>0</entry></row>
1785       <row><entry>
1786         count</entry><entry>Number of records to be retrieved.
1787         This option affects ZOOM_resultset_search and
1788         ZOOM_resultset_search_pqf and must be set before any of
1789         these functions are invoked.
1790        </entry><entry>0</entry></row>
1791       <row><entry>
1792         presentChunk</entry><entry>The number of records to be
1793         requested from the server in each chunk (present request). The
1794         value 0 means to request all the records in a single chunk.
1795         (The old <literal>step</literal>
1796         option is also supported for the benefit of old applications.)
1797        </entry><entry>0</entry></row>
1798       <row><entry>
1799         elementSetName</entry><entry>Element-Set name of records.
1800         Most targets should honor element set name <literal>B</literal>
1801         and <literal>F</literal> for brief and full respectively.
1802        </entry><entry>none</entry></row>
1803       <row><entry>
1804         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
1805         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
1806        </entry><entry>none</entry></row>
1807       <row><entry>
1808         schema</entry><entry>Schema for retrieval, such as
1809         <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
1810        </entry><entry>none</entry></row>
1811       <row><entry>
1812         setname</entry><entry>Name of Result Set (Result Set ID).
1813         If this option isn't set, the ZOOM module will automatically
1814         allocate a result set name.
1815        </entry><entry>default</entry></row>
1816       <row><entry>
1817         rpnCharset</entry><entry>Character set for RPN terms.
1818         If this is set, ZOOM C will assume that the ZOOM application is
1819         running UTF-8. Terms in RPN queries are then converted to the
1820         rpnCharset. If this is unset, ZOOM C will not assume any encoding
1821         of RPN terms and no conversion is performed.
1822        </entry><entry>none</entry></row>
1823      </tbody>
1824     </tgroup>
1825    </table>
1826    <para>
1827     For servers that support Search Info report, the following
1828     options may be read using <function>ZOOM_resultset_get</function>.
1829     This detailed information is read after a successful search has
1830     completed.
1831    </para>
1832    <para>
1833     This information is a list of of items, where each item is
1834     information about a term or subquery. All items in the list
1835     are prefixed by
1836     <literal>SearchResult.</literal><replaceable>no</replaceable>
1837     where no presents the item number (0=first, 1=second).
1838     Read <literal>searchresult.size</literal> to determine the
1839     number of items.
1840    </para>
1841    <table id="zoom.search.info.report.options"
1842     frame="top"><title>Search Info Report Options</title>
1843     <tgroup cols="2">
1844      <colspec colwidth="4*" colname="name"></colspec>
1845      <colspec colwidth="7*" colname="description"></colspec>
1846      <thead>
1847       <row>
1848        <entry>Option</entry>
1849        <entry>Description</entry>
1850       </row>
1851      </thead>
1852      <tbody>
1853       <row>
1854        <entry>searchresult.size</entry>
1855        <entry>
1856         number of search result entries. This option is-nonexistant
1857         if no entries are returned by the server.
1858        </entry>
1859       </row>
1860       <row>
1861        <entry>searchresult.<replaceable>no</replaceable>.id</entry>
1862        <entry>sub query ID</entry>
1863       </row>
1864       <row>
1865        <entry>searchresult.<replaceable>no</replaceable>.count</entry>
1866        <entry>result count for item (number of hits)</entry>
1867       </row>
1868       <row>
1869        <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
1870        <entry>subquery term</entry>
1871       </row>
1872       <row>
1873        <entry>
1874         searchresult.<replaceable>no</replaceable>.interpretation.term
1875        </entry>
1876        <entry>interpretation term</entry>
1877       </row>
1878       <row>
1879        <entry>
1880         searchresult.<replaceable>no</replaceable>.recommendation.term
1881        </entry>
1882        <entry>recommendation term</entry>
1883       </row>
1884      </tbody>
1885     </tgroup>
1886    </table>
1887    <sect2 id="zoom.z3950.resultset.sort">
1888     <title>Z39.50 Result-set Sort</title>
1889     <synopsis>
1890      void ZOOM_resultset_sort(ZOOM_resultset r,
1891                               const char *sort_type, const char *sort_spec);
1892
1893      int ZOOM_resultset_sort1(ZOOM_resultset r,
1894                               const char *sort_type, const char *sort_spec);
1895     </synopsis>
1896     <para>
1897      <function>ZOOM_resultset_sort</function> and
1898      <function>ZOOM_resultset_sort1</function> both sort an existing
1899      result-set. The sort_type parameter is not use. Set it to "yaz".
1900      The sort_spec is same notation as ZOOM_query_sortby and identical
1901      to that offered by yaz-client's
1902      <link linkend="sortspec">sort command</link>.
1903     </para>
1904     <para>
1905      These functions only work for Z39.50. Use the more generic utility
1906      <link linkend="zoom.query.sortby2">
1907       <function>ZOOM_query_sortby2</function></link>
1908      for other protocols (and even Z39.50).
1909     </para>
1910    </sect2>
1911    <sect2 id="zoom.z3950.resultset.behavior">
1912     <title>Z39.50 Protocol behavior</title>
1913     <para>
1914      The creation of a result set involves at least a SearchRequest
1915      - SearchResponse protocol handshake. Following that, if a sort
1916      criteria was specified as part of the query, a SortRequest -
1917      SortResponse handshake takes place. Note that it is necessary to
1918      perform sorting before any retrieval takes place, so no records will
1919      be returned from the target as part of the SearchResponse because these
1920      would be unsorted. Hence, piggyback is disabled when sort criteria
1921      are set. Following Search - and a possible sort - Retrieval takes
1922      place - as one or more Present Requests/Response pairs being
1923      transferred.
1924      </para>
1925     <para>
1926      The API allows for two different modes for retrieval. A high level
1927      mode which is somewhat more powerful and a low level one.
1928      The low level is enabled when searching on a Connection object
1929      for which the settings
1930      <literal>smallSetUpperBound</literal>,
1931      <literal>mediumSetPresentNumber</literal> and
1932      <literal>largeSetLowerBound</literal> are set. The low level mode
1933      thus allows you to precisely set how records are returned as part
1934      of a search response as offered by the Z39.50 protocol.
1935      Since the client may be retrieving records as part of the
1936      search response, this mode doesn't work well if sorting is used.
1937      </para>
1938     <para>
1939      The high-level mode allows you to fetch a range of records from
1940      the result set with a given start offset. When you use this mode
1941      the client will automatically use piggyback if that is possible
1942      with the target and perform one or more present requests as needed.
1943      Even if the target returns fewer records as part of a present response
1944      because of a record size limit, etc. the client will repeat sending
1945      present requests. As an example, if option <literal>start</literal>
1946      is 0 (default) and <literal>count</literal> is 4, and
1947      <literal>piggyback</literal> is 1 (default) and no sorting criteria
1948      is specified, then the client will attempt to retrieve the 4
1949      records as part the search response (using piggyback). On the other
1950      hand, if either <literal>start</literal> is positive or if
1951      a sorting criteria is set, or if <literal>piggyback</literal>
1952      is 0, then the client will not perform piggyback but send Present
1953      Requests instead.
1954     </para>
1955     <para>
1956      If either of the options <literal>mediumSetElementSetName</literal> and
1957      <literal>smallSetElementSetName</literal> are unset, the value
1958      of option <literal>elementSetName</literal> is used for piggyback
1959      searches. This means that for the high-level mode you only have
1960      to specify one elementSetName option rather than three.
1961      </para>
1962    </sect2>
1963    <sect2 id="zoom.sru.resultset.behavior">
1964     <title>SRU Protocol behavior</title>
1965     <para>
1966      Current version of &yaz; does not take advantage of a result set id
1967      returned by the SRU server. Future versions might do, however.
1968      Since, the ZOOM driver does not save result set IDs any
1969      present (retrieval) is transformed to a SRU SearchRetrieveRequest
1970      with same query but, possibly, different offsets.
1971     </para>
1972     <para>
1973      Option <literal>schema</literal> specifies SRU schema
1974      for retrieval. However, options <literal>elementSetName</literal> and
1975      <literal>preferredRecordSyntax</literal> are ignored.
1976     </para>
1977     <para>
1978      Options <literal>start</literal> and <literal>count</literal>
1979      are supported by SRU.
1980      The remaining options
1981      <literal>piggyback</literal>,
1982      <literal>smallSetUpperBound</literal>,
1983      <literal>largeSetLowerBound</literal>,
1984      <literal>mediumSetPresentNumber</literal>,
1985      <literal>mediumSetElementSetName</literal>,
1986       <literal>smallSetElementSetName</literal> are
1987      unsupported.
1988     </para>
1989     <para>
1990      SRU supports CQL queries, <emphasis>not</emphasis> PQF.
1991      If PQF is used, however, the PQF query is transferred anyway
1992      using non-standard element <literal>pQuery</literal> in
1993      SRU SearchRetrieveRequest.
1994     </para>
1995     <para>
1996      Solr queries has to be done in Solr query format.
1997     </para>
1998     <para>
1999      Unfortunately, SRU or Solr does not define a database setting. Hence,
2000      <literal>databaseName</literal> is unsupported and ignored.
2001      However, the path part in host parameter for functions
2002      <function>ZOOM_connecton_new</function> and
2003      <function>ZOOM_connection_connect</function> acts as a
2004      database (at least for the &yaz; SRU server).
2005     </para>
2006    </sect2>
2007   </sect1>
2008   <sect1 id="zoom.records">
2009    <title>Records</title>
2010    <para>
2011     A record object is a retrieval record on the client side -
2012     created from result sets.
2013    </para>
2014    <synopsis>
2015      void ZOOM_resultset_records(ZOOM_resultset r,
2016                                  ZOOM_record *recs,
2017                                  size_t start, size_t count);
2018      ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
2019
2020      const char *ZOOM_record_get(ZOOM_record rec, const char *type,
2021                                  size_t *len);
2022
2023      int ZOOM_record_error(ZOOM_record rec, const char **msg,
2024                            const char **addinfo, const char **diagset);
2025
2026      ZOOM_record ZOOM_record_clone(ZOOM_record rec);
2027
2028      void ZOOM_record_destroy(ZOOM_record rec);
2029    </synopsis>
2030    <para>
2031     References to temporary records are returned by functions
2032     <function>ZOOM_resultset_records</function> or
2033     <function>ZOOM_resultset_record</function>.
2034     </para>
2035    <para>
2036     If a persistent reference to a record is desired
2037     <function>ZOOM_record_clone</function> should be used.
2038     It returns a record reference that should be destroyed
2039     by a call to <function>ZOOM_record_destroy</function>.
2040    </para>
2041    <para>
2042     A single record is returned by function
2043     <function>ZOOM_resultset_record</function> that takes a
2044     position as argument. First record has position zero.
2045     If no record could be obtained <literal>NULL</literal> is returned.
2046    </para>
2047    <para>
2048     Error information for a record can be checked with
2049     <function>ZOOM_record_error</function> which returns non-zero
2050     (error code) if record is in error, called <emphasis>Surrogate
2051      Diagnostics</emphasis> in Z39.50.
2052    </para>
2053    <para>
2054     Function <function>ZOOM_resultset_records</function> retrieves
2055     a number of records from a result set. Parameter <literal>start</literal>
2056     and <literal>count</literal> specifies the range of records to
2057     be returned. Upon completion array
2058     <literal>recs[0], ..recs[count-1]</literal>
2059     holds record objects for the records. The array of records
2060      <literal>recs</literal> should be allocated prior the call
2061     <function>ZOOM_resultset_records</function>. Note that for those
2062     records that couldn't be retrieved from the target
2063     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
2064    </para>
2065    <para id="zoom.record.get">
2066     In order to extract information about a single record,
2067     <function>ZOOM_record_get</function> is provided. The
2068     function returns a pointer to certain record information. The
2069     nature (type) of the pointer depends on the parameter,
2070     <parameter>type</parameter>.
2071    </para>
2072    <para>
2073     The <parameter>type</parameter> is a string of the format:
2074    </para>
2075    <para>
2076     <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]
2077    </para>
2078    <para>
2079     where <replaceable>format</replaceable> specifies the format of the
2080     returned record, <replaceable>from</replaceable>
2081     specifies the character set of the record in its original form
2082     (as returned by the server), <replaceable>to</replaceable> specifies
2083     the output (returned)
2084     character set encoding.
2085     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
2086     If charset is not given, then no character set conversion takes place.
2087    </para>
2088
2089    <para>OPAC records may be returned in a different
2090      set from the bibliographic MARC record. If this is this the case,
2091     <replaceable>opacfrom</replaceable> should be set to the character set
2092     of the OPAC record part.
2093    </para>
2094    <note>
2095      <para>
2096        Specifying the OPAC record character set requires YAZ 4.1.5 or later.
2097      </para>
2098    </note>
2099    <para>
2100     The format argument controls whether record data should be XML
2101     pretty-printed (post process operation).
2102     It is enabled only if format value <replaceable>v</replaceable> is
2103     <literal>1</literal> and the record content is XML well-formed.
2104    </para>
2105    <para>
2106     In addition, for certain types, the length
2107     <literal>len</literal> passed will be set to the size in bytes of
2108     the returned information.
2109     </para>
2110    <para>
2111     The following are the supported values for <replaceable>form</replaceable>.
2112     <variablelist>
2113      <varlistentry><term><literal>database</literal></term>
2114       <listitem><para>Database of record is returned
2115         as a C null-terminated string. Return type
2116         <literal>const char *</literal>.
2117        </para></listitem>
2118      </varlistentry>
2119      <varlistentry><term><literal>syntax</literal></term>
2120       <listitem><para>The transfer syntax of the record is returned
2121         as a C null-terminated string containing the symbolic name of
2122         the record syntax, e.g. <literal>Usmarc</literal>. Return type
2123         is
2124         <literal>const char *</literal>.
2125        </para></listitem>
2126      </varlistentry>
2127      <varlistentry><term><literal>schema</literal></term>
2128       <listitem><para>The schema of the record is returned
2129         as a C null-terminated string. Return type is
2130         <literal>const char *</literal>.
2131        </para></listitem>
2132      </varlistentry>
2133      <varlistentry><term><literal>render</literal></term>
2134       <listitem><para>The record is returned in a display friendly
2135         format. Upon completion buffer is returned
2136         (type <literal>const char *</literal>) and length is stored in
2137         <literal>*len</literal>.
2138        </para></listitem>
2139      </varlistentry>
2140      <varlistentry><term><literal>raw</literal></term>
2141       <listitem><para>The record is returned in the internal
2142         YAZ specific format. For GRS-1, Explain, and others, the
2143         raw data is returned as type
2144         <literal>Z_External *</literal> which is just the type for
2145         the member <literal>retrievalRecord</literal> in
2146         type <literal>NamePlusRecord</literal>.
2147         For SUTRS and octet aligned record (including all MARCs) the
2148         octet buffer is returned and the length of the buffer.
2149        </para></listitem>
2150      </varlistentry>
2151      <varlistentry><term><literal>xml</literal></term>
2152       <listitem><para>The record is returned in XML if possible.
2153         SRU, Solr and Z39.50 records with transfer syntax XML are
2154         returned verbatim. MARC records are returned in
2155         <ulink url="&url.marcxml;">
2156          MARCXML
2157          </ulink>
2158         (converted from ISO2709 to MARCXML by YAZ).
2159         OPAC records are also converted to XML and the
2160         bibliographic record is converted to MARCXML (when possible).
2161         GRS-1 records are not supported for this form.
2162         Upon completion, the XML buffer is returned
2163         (type <literal>const char *</literal>) and length is stored in
2164         <literal>*len</literal>.
2165        </para></listitem>
2166      </varlistentry>
2167      <varlistentry><term><literal>opac</literal></term>
2168       <listitem><para>OPAC information for record is returned in XML
2169         if an OPAC record is present at the position given. If no
2170         OPAC record is present, a NULL pointer is returned.
2171        </para></listitem>
2172      </varlistentry>
2173      <varlistentry><term><literal>txml</literal></term>
2174       <listitem><para>The record is returned in TurboMARC if possible.
2175         SRU and Z39.50 records with transfer syntax XML are
2176         returned verbatim. MARC records are returned in
2177         <link linkend="tools.turbomarc">
2178          TurboMARC
2179         </link>
2180         (converted from ISO2709 to TurboMARC by YAZ).
2181         Upon completion, the XML buffer is returned
2182         (type <literal>const char *</literal>) and length is stored in
2183         <literal>*len</literal>.
2184        </para></listitem>
2185      </varlistentry>
2186      <varlistentry><term><literal>json</literal></term>
2187       <listitem><para>Like xml, but MARC records are converted to
2188         <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>.
2189        </para></listitem>
2190      </varlistentry>
2191
2192     </variablelist>
2193    </para>
2194    <para>
2195     Most
2196     <ulink url="&url.marc21;">MARC21</ulink>
2197     records uses the
2198     <ulink url="&url.marc8;">MARC-8</ulink>
2199     character set encoding.
2200     An application that wishes to display in Latin-1 would use
2201     <screen>
2202      render; charset=marc8,iso-8859-1
2203     </screen>
2204    </para>
2205    <sect2 id="zoom.z3950.record.behavior">
2206     <title>Z39.50 Protocol behavior</title>
2207     <para>
2208      The functions <function>ZOOM_resultset_record</function> and
2209      <function>ZOOM_resultset_records</function> inspects the client-side
2210      record cache. Records not found in cache are fetched using
2211      Present.
2212      The functions may block (and perform network I/O)  - even though option
2213      <literal>async</literal> is 1, because they return records objects.
2214      (and there's no way to return records objects without retrieving them!).
2215      </para>
2216     <para>
2217      There is a trick, however, in the usage of function
2218      <function>ZOOM_resultset_records</function> that allows for
2219      delayed retrieval (and makes it non-blocking). By using
2220      a null pointer for <parameter>recs</parameter> you're indicating
2221      you're not interested in getting records objects
2222      <emphasis>now</emphasis>.
2223     </para>
2224    </sect2>
2225    <sect2 id="zoom.sru.record.behavior">
2226     <title>SRU/Solr Protocol behavior</title>
2227     <para>
2228      The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
2229      as if they where Z39.50 records with transfer syntax XML and
2230      no element set name or database name.
2231     </para>
2232    </sect2>
2233   </sect1>
2234   <sect1 id="zoom.facets"><title>Facets</title>
2235    <para>
2236     Facet operations is not part of the official ZOOM specification, but
2237     is an Index Data extension for YAZ-based Z39.50 targets,
2238     <ulink url="&url.solr;">Solr</ulink> and SRU 2.0 targets.
2239
2240     Facets may be requestd by the
2241      <link linkend="zoom.facets.option">facets</link> option before a
2242     search is sent.
2243     For inspection of the returned facets, the following functions are
2244     available:
2245    </para>
2246    <synopsis>
2247     ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
2248
2249     ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
2250                                                     const char *facet_name);
2251
2252     ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
2253                                                              int pos);
2254
2255     size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
2256
2257     const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
2258
2259     size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
2260
2261     const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
2262                                           size_t idx, int *freq);
2263    </synopsis>
2264    <para>
2265     References to temporary structures are returned by all functions.
2266     They are only valid as long the Result set is valid.
2267     <function>ZOOM_resultset_get_facet_field</function> or
2268     <function>ZOOM_resultset_get_facet_field_by_index</function>.
2269     <function>ZOOM_resultset_facets</function>.
2270     <function>ZOOM_facet_field_name</function>.
2271     <function>ZOOM_facet_field_get_term</function>.
2272     </para>
2273    <para id="zoom.resultset.get_facet_field">
2274     A single Facet field  is returned by function
2275     <function>ZOOM_resultset_get_facet_field</function> or
2276     <function>ZOOM_resultset_get_facet_field_by_index</function> that takes
2277     a  result set and facet name or positive index respectively. First
2278     facet has position zero. If no facet could be obtained (invalid name
2279     or index out of bounds) <literal>NULL</literal> is returned.
2280    </para>
2281    <para id="zoom.resultset.facets">
2282     An array of facets field can be returned by
2283     <function>ZOOM_resultset_facets</function>. The length of the array is
2284     given by <function>ZOOM_resultset_facets_size</function>. The array is
2285     zero-based and last entry will be at
2286     <function>ZOOM_resultset_facets_size(result_set)</function>-1.
2287    </para>
2288    <para id="zoom.resultset.facets_names">
2289     It is possible to interate over facets by name, by calling
2290     <function>ZOOM_resultset_facets_names</function>.
2291     This will return an const array of char * where each string can be used
2292     as parameter for <function>ZOOM_resultset_get_facet_field</function>.
2293    </para>
2294    <para>
2295    Function <function>ZOOM_facet_field_name</function> gets the request
2296     facet name from a returned facet field.
2297    </para>
2298    <para>
2299     Function <function>ZOOM_facet_field_get_term</function> returns the
2300     idx'th term and term count for a facet field.
2301     Idx must between 0 and
2302     <function>ZOOM_facet_field_term_count</function>-1, otherwise the
2303     returned reference will be <literal>NULL</literal>. On a valid idx, the
2304     value of the freq reference will be the term count.
2305     The <literal>freq</literal> parameter must be valid pointer to integer.
2306    </para>
2307    </sect1>
2308   <sect1 id="zoom.scan"><title>Scan</title>
2309    <para>
2310     This section describes an interface for Scan. Scan is not an
2311     official part of the ZOOM model yet. The result of a scan operation
2312     is the <literal>ZOOM_scanset</literal> which is a set of terms
2313     returned by a target.
2314    </para>
2315
2316    <para>
2317     The Scan interface is supported for both Z39.50, SRU and Solr.
2318    </para>
2319
2320    <synopsis>
2321     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
2322                                       const char *startpqf);
2323
2324     ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
2325                                        ZOOM_query q);
2326
2327     size_t ZOOM_scanset_size(ZOOM_scanset scan);
2328
2329     const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
2330                                   size_t *occ, size_t *len);
2331
2332     const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
2333                                           size_t *occ, size_t *len);
2334
2335     void ZOOM_scanset_destroy(ZOOM_scanset scan);
2336
2337     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
2338                                         const char *key);
2339
2340     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
2341                                  const char *val);
2342     </synopsis>
2343    <para>
2344     The scan set is created by function
2345     <function>ZOOM_connection_scan</function> which performs a scan
2346     operation on the connection using the specified
2347     <parameter>startpqf</parameter>.
2348     If the operation was successful, the size of the scan set can be
2349     retrieved by a call to <function>ZOOM_scanset_size</function>.
2350     Like result sets, the items are numbered 0,..size-1.
2351     To obtain information about a particular scan term, call function
2352     <function>ZOOM_scanset_term</function>. This function takes
2353     a scan set offset <literal>pos</literal> and returns a pointer
2354     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
2355     non-present.
2356     If present, the <literal>occ</literal> and <literal>len</literal>
2357     are set to the number of occurrences and the length
2358     of the actual term respectively.
2359     <function>ZOOM_scanset_display_term</function> is similar to
2360     <function>ZOOM_scanset_term</function> except that it returns
2361     the <emphasis>display term</emphasis> rather than the raw term.
2362     In a few cases, the term is different from display term. Always
2363     use the display term for display and the raw term for subsequent
2364     scan operations (to get more terms, next scan result, etc).
2365    </para>
2366    <para>
2367     A scan set may be freed by a call to function
2368     <function>ZOOM_scanset_destroy</function>.
2369     Functions <function>ZOOM_scanset_option_get</function> and
2370     <function>ZOOM_scanset_option_set</function> retrieves and sets
2371     an option respectively.
2372    </para>
2373    <para>
2374     The <parameter>startpqf</parameter> is a subset of PQF, namely
2375     the Attributes+Term part. Multiple <literal>@attr</literal> can
2376     be used. For example to scan in title (complete) phrases:
2377     <literallayout>
2378      @attr 1=4 @attr 6=2 "science o"
2379     </literallayout>
2380    </para>
2381    <para>
2382     The <function>ZOOM_connecton_scan1</function> is a newer and
2383     more generic alternative to <function>ZOOM_connection_scan</function>
2384     which allows to use both CQL and PQF for Scan.
2385    </para>
2386    <table frame="top" id="zoom.scanset.options">
2387     <title>ZOOM Scan Set Options</title>
2388     <tgroup cols="3">
2389      <colspec colwidth="4*" colname="name"></colspec>
2390      <colspec colwidth="7*" colname="description"></colspec>
2391      <colspec colwidth="2*" colname="default"></colspec>
2392      <thead>
2393       <row>
2394        <entry>Option</entry>
2395        <entry>Description</entry>
2396        <entry>Default</entry>
2397       </row>
2398      </thead>
2399      <tbody>
2400       <row><entry>
2401         number</entry><entry>Number of Scan Terms requested in next scan.
2402         After scan it holds the actual number of terms returned.
2403        </entry><entry>20</entry></row>
2404       <row><entry>
2405         position</entry><entry>Preferred Position of term in response
2406         in next scan; actual position after completion of scan.
2407        </entry><entry>1</entry></row>
2408       <row><entry>
2409         stepSize</entry><entry>Step Size
2410        </entry><entry>0</entry></row>
2411       <row><entry>
2412         scanStatus</entry><entry>An integer indicating the Scan Status
2413         of last scan.
2414        </entry><entry>0</entry></row>
2415       <row><entry>
2416         rpnCharset</entry><entry>Character set for RPN terms.
2417         If this is set, ZOOM C will assume that the ZOOM application is
2418         running UTF-8. Terms in RPN queries are then converted to the
2419         rpnCharset. If this is unset, ZOOM C will not assume any encoding
2420         of RPN terms and no conversion is performed.
2421        </entry><entry>none</entry></row>
2422      </tbody>
2423     </tgroup>
2424    </table>
2425   </sect1>
2426   <sect1 id="zoom.extendedservices">
2427    <title>Extended Services</title>
2428    <para>
2429     ZOOM offers an interface to a subset of the Z39.50 extended services
2430     as well as a few privately defined ones:
2431    </para>
2432    <itemizedlist>
2433     <listitem>
2434      <para>
2435       Z39.50 Item Order (ILL).
2436       See <xref linkend="zoom.item.order"/>.
2437      </para>
2438     </listitem>
2439     <listitem>
2440      <para>
2441       Record Update. This allows a client to insert, modify or delete
2442       records.
2443       See <xref linkend="zoom.record.update"/>.
2444      </para>
2445     </listitem>
2446     <listitem>
2447      <para>
2448       Database Create. This a non-standard feature. Allows a client
2449       to create a database.
2450       See <xref linkend="zoom.database.create"/>.
2451      </para>
2452     </listitem>
2453     <listitem>
2454      <para>
2455       Database Drop. This a non-standard feature. Allows a client
2456       to delete/drop a database.
2457       See <xref linkend="zoom.database.drop"/>.
2458      </para>
2459      </listitem>
2460     <listitem>
2461      <para>
2462       Commit operation. This a non-standard feature. Allows a client
2463       to commit operations.
2464       See <xref linkend="zoom.commit"/>.
2465      </para>
2466     </listitem>
2467     <!-- all the ILL PDU options should go here too -->
2468    </itemizedlist>
2469    <para>
2470     To create an extended service operation a <literal>ZOOM_package</literal>
2471     must be created. The operation is a five step operation. The
2472     package is created, package is configured by means of options,
2473     the package is send, result is inspected (by means of options),
2474     the package is destroyed.
2475    </para>
2476    <synopsis>
2477     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
2478                                          ZOOM_options options);
2479
2480     const char *ZOOM_package_option_get(ZOOM_package p,
2481                                         const char *key);
2482     void ZOOM_package_option_set(ZOOM_package p, const char *key,
2483                                  const char *val);
2484     void ZOOM_package_send(ZOOM_package p, const char *type);
2485
2486     void ZOOM_package_destroy(ZOOM_package p);
2487    </synopsis>
2488    <para>
2489     The <function>ZOOM_connection_package</function> creates a
2490     package for the connection given using the options specified.
2491    </para>
2492    <para>
2493     Functions <function>ZOOM_package_option_get</function> and
2494     <function>ZOOM_package_option_set</function> gets and sets
2495     options.
2496    </para>
2497    <para>
2498     <function>ZOOM_package_send</function> sends
2499     the package the via connection specified in
2500     <function>ZOOM_connection_package</function>.
2501     The <parameter>type</parameter> specifies the actual extended service
2502     package type to be sent.
2503    </para>
2504    <table frame="top" id="zoom.extendedservices.options">
2505     <title>Extended Service Common Options</title>
2506     <tgroup cols="3">
2507      <colspec colwidth="4*" colname="name"></colspec>
2508      <colspec colwidth="7*" colname="description"></colspec>
2509      <colspec colwidth="3*" colname="default"></colspec>
2510      <thead>
2511       <row>
2512        <entry>Option</entry>
2513        <entry>Description</entry>
2514        <entry>Default</entry>
2515       </row>
2516      </thead>
2517      <tbody>
2518       <row>
2519        <entry>package-name</entry>
2520        <entry>Extended Service Request package name. Must be specified
2521        as part of a request</entry>
2522        <entry>none</entry>
2523       </row>
2524       <row>
2525        <entry>user-id</entry>
2526        <entry>User ID of Extended Service Package. Is a request option</entry>
2527        <entry>none</entry>
2528       </row>
2529       <row>
2530        <entry>function</entry>
2531        <entry>
2532         Function of package - one of <literal>create</literal>,
2533         <literal>delete</literal>, <literal>modify</literal>. Is
2534         a request option.
2535        </entry>
2536        <entry><literal>create</literal></entry>
2537       </row>
2538       <row>
2539        <entry>waitAction</entry>
2540        <entry>
2541         Wait action for package. Possible values:
2542         <literal>wait</literal>, <literal>waitIfPossible</literal>,
2543         <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
2544        </entry>
2545        <entry><literal>waitIfPossible</literal></entry>
2546       </row>
2547       <row>
2548        <entry>targetReference</entry>
2549        <entry>
2550         Target Reference. This is part of the response as returned
2551         by the server. Read it after a successful operation.
2552        </entry>
2553        <entry><literal>none</literal></entry>
2554       </row>
2555      </tbody>
2556     </tgroup>
2557    </table>
2558    <sect2 id="zoom.item.order">
2559     <title>Item Order</title>
2560     <para>
2561      For Item Order, type must be set to <literal>itemorder</literal> in
2562      <function>ZOOM_package_send</function>.
2563     </para>
2564
2565     <table frame="top" id="zoom.item.order.options">
2566      <title>Item Order Options</title>
2567      <tgroup cols="3">
2568       <colspec colwidth="4*" colname="name"></colspec>
2569       <colspec colwidth="7*" colname="description"></colspec>
2570       <colspec colwidth="3*" colname="default"></colspec>
2571       <thead>
2572        <row>
2573         <entry>Option</entry>
2574         <entry>Description</entry>
2575         <entry>Default</entry>
2576        </row>
2577       </thead>
2578       <tbody>
2579        <row>
2580         <entry>contact-name</entry>
2581         <entry>ILL contact name</entry>
2582         <entry>none</entry>
2583        </row>
2584        <row>
2585         <entry>contact-phone</entry>
2586         <entry>ILL contact phone</entry>
2587         <entry>none</entry>
2588        </row>
2589        <row>
2590         <entry>contact-email</entry>
2591         <entry>ILL contact email</entry>
2592         <entry>none</entry>
2593        </row>
2594        <row>
2595         <entry>itemorder-item</entry>
2596         <entry>Position for item (record) requested. An integer</entry>
2597         <entry>1</entry>
2598        </row>
2599       </tbody>
2600      </tgroup>
2601     </table>
2602    </sect2>
2603    <sect2 id="zoom.record.update">
2604     <title>Record Update</title>
2605     <para>
2606      For Record Update, type must be set to <literal>update</literal> in
2607      <function>ZOOM_package_send</function>.
2608     </para>
2609     <table frame="top" id="zoom.record.update.options">
2610      <title>Record Update Options</title>
2611      <tgroup cols="3">
2612       <colspec colwidth="4*" colname="name"></colspec>
2613       <colspec colwidth="7*" colname="description"></colspec>
2614       <colspec colwidth="3*" colname="default"></colspec>
2615       <thead>
2616        <row>
2617         <entry>Option</entry>
2618         <entry>Description</entry>
2619         <entry>Default</entry>
2620        </row>
2621       </thead>
2622       <tbody>
2623        <row>
2624         <entry>action</entry>
2625         <entry>
2626          The update action. One of
2627          <literal>specialUpdate</literal>,
2628          <literal>recordInsert</literal>,
2629          <literal>recordReplace</literal>,
2630          <literal>recordDelete</literal>,
2631          <literal>elementUpdate</literal>.
2632         </entry>
2633         <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
2634        </row>
2635        <row>
2636         <entry>recordIdOpaque</entry>
2637         <entry>Opaque Record ID</entry>
2638         <entry>none</entry>
2639        </row>
2640        <row>
2641         <entry>recordIdNumber</entry>
2642         <entry>Record ID number</entry>
2643         <entry>none</entry>
2644        </row>
2645        <row>
2646         <entry>record</entry>
2647         <entry>The record itself</entry>
2648         <entry>none</entry>
2649        </row>
2650        <row>
2651         <entry>recordOpaque</entry>
2652         <entry>Specifies an opaque record which is
2653           encoded as an ASN.1 ANY type with the OID as tiven by option
2654           <literal>syntax</literal> (see below).
2655           Option <literal>recordOpaque</literal> is an alternative
2656           to record - and <literal>record</literal> option (above) is
2657           ignored if recordOpaque is set. This option is only available in
2658           YAZ 3.0.35 and later and is meant to facilitate Updates with
2659           servers from OCLC.
2660         </entry>
2661         <entry>none</entry>
2662        </row>
2663        <row>
2664         <entry>syntax</entry>
2665         <entry>The record syntax (transfer syntax). Is a string that
2666          is a known record syntax.
2667         </entry>
2668         <entry>no syntax</entry>
2669        </row>
2670        <row>
2671         <entry>databaseName</entry>
2672         <entry>Database from connection object</entry>
2673         <entry>Default</entry>
2674        </row>
2675        <row>
2676         <entry>correlationInfo.note</entry>
2677         <entry>Correlation Info Note (string)</entry>
2678         <entry>none</entry>
2679        </row>
2680        <row>
2681         <entry>correlationInfo.id</entry>
2682         <entry>Correlation Info ID (integer)</entry>
2683         <entry>none</entry>
2684        </row>
2685        <row>
2686         <entry>elementSetName</entry>
2687         <entry>Element Set for Record</entry>
2688         <entry>none</entry>
2689        </row>
2690        <row>
2691         <entry>updateVersion</entry>
2692         <entry>Record Update version which holds one of the values
2693          1, 2 or 3. Each version has a distinct OID:
2694          1.2.840.10003.9.5
2695          (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
2696          1.2.840.10003.9.5.1
2697          (second version) and
2698          1.2.840.10003.9.5.1.1
2699          (<ulink url="&url.z39.50.extupdate3;">third and
2700           newest version</ulink>).
2701         </entry>
2702         <entry>3</entry>
2703        </row>
2704       </tbody>
2705      </tgroup>
2706     </table>
2707
2708    </sect2>
2709
2710    <sect2 id="zoom.database.create"><title>Database Create</title>
2711     <para>
2712      For Database Create, type must be set to <literal>create</literal> in
2713      <function>ZOOM_package_send</function>.
2714     </para>
2715
2716     <table frame="top" id="zoom.database.create.options">
2717      <title>Database Create Options</title>
2718      <tgroup cols="3">
2719       <colspec colwidth="4*" colname="name"></colspec>
2720       <colspec colwidth="7*" colname="description"></colspec>
2721       <colspec colwidth="3*" colname="default"></colspec>
2722       <thead>
2723        <row>
2724         <entry>Option</entry>
2725         <entry>Description</entry>
2726         <entry>Default</entry>
2727        </row>
2728       </thead>
2729       <tbody>
2730        <row>
2731         <entry>databaseName</entry>
2732         <entry>Database from connection object</entry>
2733         <entry>Default</entry>
2734        </row>
2735       </tbody>
2736      </tgroup>
2737     </table>
2738    </sect2>
2739    <sect2 id="zoom.database.drop">
2740     <title>Database Drop</title>
2741     <para>
2742      For Database Drop, type must be set to <literal>drop</literal> in
2743      <function>ZOOM_package_send</function>.
2744     </para>
2745     <table frame="top" id="zoom.database.drop.options">
2746      <title>Database Drop Options</title>
2747      <tgroup cols="3">
2748       <colspec colwidth="4*" colname="name"></colspec>
2749       <colspec colwidth="7*" colname="description"></colspec>
2750       <colspec colwidth="3*" colname="default"></colspec>
2751       <thead>
2752        <row>
2753         <entry>Option</entry>
2754         <entry>Description</entry>
2755         <entry>Default</entry>
2756        </row>
2757       </thead>
2758       <tbody>
2759        <row>
2760         <entry>databaseName</entry>
2761         <entry>Database from connection object</entry>
2762         <entry>Default</entry>
2763        </row>
2764       </tbody>
2765      </tgroup>
2766     </table>
2767    </sect2>
2768    <sect2 id="zoom.commit">
2769     <title>Commit Operation</title>
2770     <para>
2771      For Commit, type must be set to <literal>commit</literal> in
2772      <function>ZOOM_package_send</function>.
2773     </para>
2774    </sect2>
2775    <sect2 id="zoom.extended.services.behavior">
2776     <title>Protocol behavior</title>
2777     <para>
2778      All the extended services are Z39.50-only.
2779     </para>
2780     <note>
2781      <para>
2782       The database create, drop and commit services are privately defined
2783       operations.
2784       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
2785       definitions.
2786      </para>
2787     </note>
2788    </sect2>
2789   </sect1>
2790   <sect1 id="zoom.options">
2791    <title>Options</title>
2792    <para>
2793     Most &zoom; objects provide a way to specify options to change behavior.
2794     From an implementation point of view a set of options is just like
2795     an associative array / hash.
2796    </para>
2797    <synopsis>
2798      ZOOM_options ZOOM_options_create(void);
2799
2800      ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
2801
2802      void ZOOM_options_destroy(ZOOM_options opt);
2803    </synopsis>
2804    <synopsis>
2805      const char *ZOOM_options_get(ZOOM_options opt, const char *name);
2806
2807      void ZOOM_options_set(ZOOM_options opt, const char *name,
2808                            const char *v);
2809    </synopsis>
2810    <synopsis>
2811      typedef const char *(*ZOOM_options_callback)
2812                             (void *handle, const char *name);
2813
2814      ZOOM_options_callback
2815              ZOOM_options_set_callback(ZOOM_options opt,
2816                                        ZOOM_options_callback c,
2817                                        void *handle);
2818    </synopsis>
2819   </sect1>
2820   <sect1 id="zoom.queryconversions">
2821    <title>Query conversions</title>
2822    <synopsis>
2823     int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
2824                            ZOOM_connection conn);
2825
2826     int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
2827                            const char *config,
2828                            int *ccl_error, const char **error_string,
2829                            int *error_pos);
2830    </synopsis>
2831    <para>
2832     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
2833     client-side, into RPN which may be passed to the server.
2834     This is useful for server's that don't themselves
2835     support CQL, for which <function>ZOOM_query_cql</function> is useless.
2836     `conn' is used  only as a place to stash diagnostics if compilation
2837     fails; if this information is not needed, a null pointer may be used.
2838     The CQL conversion is driven by option <literal>cqlfile</literal> from
2839     connection conn. This specifies a conversion file (eg pqf.properties)
2840     which <emphasis>must</emphasis> be present.
2841    </para>
2842    <para>
2843     <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
2844     client-side, into RPN which may be passed to the server.
2845     The conversion is driven by the specification given by
2846     <literal>config</literal>. Upon completion 0 is returned on success; -1
2847     is returned on on failure. Om failure <literal>error_string</literal> and
2848     <literal>error_pos</literal> holds error message and position of
2849     first error in original CCL string.
2850    </para>
2851   </sect1>
2852   <sect1 id="zoom.events"><title>Events</title>
2853    <para>
2854     If you're developing non-blocking applications, you have to deal
2855     with events.
2856    </para>
2857    <synopsis>
2858     int ZOOM_event(int no, ZOOM_connection *cs);
2859    </synopsis>
2860    <para>
2861     The <function>ZOOM_event</function> executes pending events for
2862     a number of connections. Supply the number of connections in
2863     <literal>no</literal> and an array of connections in
2864     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
2865     A pending event could be a sending a search, receiving a response,
2866     etc.
2867     When an event has occurred for one of the connections, this function
2868     returns a positive integer <literal>n</literal> denoting that an event
2869     occurred for connection <literal>cs[n-1]</literal>.
2870     When no events are pending for the connections, a value of zero is
2871     returned.
2872     To ensure that all outstanding requests are performed call this function
2873     repeatedly until zero is returned.
2874    </para>
2875    <para>
2876     If <function>ZOOM_event</function> returns and returns non-zero, the
2877     last event that occurred can be expected.
2878    </para>
2879    <synopsis>
2880     int ZOOM_connection_last_event(ZOOM_connection cs);
2881    </synopsis>
2882    <para>
2883     <function>ZOOM_connection_last_event</function> returns an event type
2884     (integer) for the last event.
2885    </para>
2886
2887    <table frame="top" id="zoom.event.ids">
2888     <title>ZOOM Event IDs</title>
2889     <tgroup cols="2">
2890      <colspec colwidth="4*" colname="name"></colspec>
2891      <colspec colwidth="7*" colname="description"></colspec>
2892      <thead>
2893       <row>
2894        <entry>Event</entry>
2895        <entry>Description</entry>
2896       </row>
2897      </thead>
2898      <tbody>
2899       <row>
2900        <entry>ZOOM_EVENT_NONE</entry>
2901        <entry>No event has occurred</entry>
2902       </row>
2903       <row>
2904        <entry>ZOOM_EVENT_CONNECT</entry>
2905        <entry>TCP/IP connect has initiated</entry>
2906       </row>
2907       <row>
2908        <entry>ZOOM_EVENT_SEND_DATA</entry>
2909        <entry>Data has been transmitted (sending)</entry>
2910       </row>
2911       <row>
2912        <entry>ZOOM_EVENT_RECV_DATA</entry>
2913        <entry>Data has been received)</entry>
2914       </row>
2915       <row>
2916        <entry>ZOOM_EVENT_TIMEOUT</entry>
2917        <entry>Timeout</entry>
2918       </row>
2919       <row>
2920        <entry>ZOOM_EVENT_UNKNOWN</entry>
2921        <entry>Unknown event</entry>
2922       </row>
2923       <row>
2924        <entry>ZOOM_EVENT_SEND_APDU</entry>
2925        <entry>An APDU has been transmitted (sending)</entry>
2926       </row>
2927       <row>
2928        <entry>ZOOM_EVENT_RECV_APDU</entry>
2929        <entry>An APDU has been received</entry>
2930       </row>
2931       <row>
2932        <entry>ZOOM_EVENT_RECV_RECORD</entry>
2933        <entry>A result-set record has been received</entry>
2934       </row>
2935       <row>
2936        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
2937        <entry>A search result been received</entry>
2938       </row>
2939      </tbody>
2940     </tgroup>
2941    </table>
2942   </sect1>
2943  </chapter>
2944  <chapter id="server">
2945   <title>Generic server</title>
2946   <sect1 id="server.introduction"><title>Introduction</title>
2947    <para>
2948     If you aren't into documentation, a good way to learn how the
2949     back end interface works is to look at the <filename>backend.h</filename>
2950     file. Then, look at the small dummy-server in
2951     <filename>ztest/ztest.c</filename>. The <filename>backend.h</filename>
2952     file also makes a good reference, once you've chewed your way through
2953     the prose of this file.
2954    </para>
2955    <para>
2956     If you have a database system that you would like to make available by
2957     means of Z39.50 or SRU, &yaz; basically offers your two options. You
2958     can use the APIs provided by the &asn;, &odr;, and &comstack;
2959     modules to
2960     create and decode PDUs, and exchange them with a client.
2961     Using this low-level interface gives you access to all fields and
2962     options of the protocol, and you can construct your server as close
2963     to your existing database as you like.
2964     It is also a fairly involved process, requiring
2965     you to set up an event-handling mechanism, protocol state machine,
2966     etc. To simplify server implementation, we have implemented a compact
2967     and simple, but reasonably full-functioned server-frontend that will
2968     handle most of the protocol mechanics, while leaving you to
2969     concentrate on your database interface.
2970    </para>
2971    <note>
2972     <para>
2973      The backend interface was designed in anticipation of a specific
2974      integration task, while still attempting to achieve some degree of
2975      generality. We realize fully that there are points where the
2976      interface can be improved significantly. If you have specific
2977      functions or parameters that you think could be useful, send us a
2978      mail (or better, sign on to the mailing list referred to in the
2979      top-level README file). We will try to fit good suggestions into future
2980      releases, to the extent that it can be done without requiring
2981      too many structural changes in existing applications.
2982     </para>
2983    </note>
2984    <note>
2985     <para>
2986      The &yaz; server does not support XCQL.
2987      </para>
2988    </note>
2989   </sect1>
2990   <sect1 id="server.frontend">
2991    <title>The Database Frontend</title>
2992    <para>
2993     We refer to this software as a generic database frontend. Your
2994     database system is the <emphasis>backend database</emphasis>, and the
2995     interface between the two is called the <emphasis>backend API</emphasis>.
2996     The backend API consists of a small number of function handlers and
2997     structure definitions. You are required to provide the
2998     <function>main()</function> routine for the server (which can be
2999     quite simple), as well as a set of handlers to match each of the
3000     prototypes.
3001     The interface functions that you write can use any mechanism you like
3002     to communicate with your database system: You might link the whole
3003     thing together with your database application and access it by
3004     function calls; you might use IPC to talk to a database server
3005     somewhere; or you might link with third-party software that handles
3006     the communication for you (like a commercial database client library).
3007     At any rate, the handlers will perform the tasks of:
3008    </para>
3009    <itemizedlist>
3010     <listitem><para>
3011      Initialization.
3012     </para></listitem>
3013     <listitem><para>
3014      Searching.
3015     </para></listitem>
3016     <listitem><para>
3017      Fetching records.
3018     </para></listitem>
3019     <listitem><para>
3020      Scanning the database index (optional - if you wish to implement SCAN).
3021     </para></listitem>
3022     <listitem><para>
3023      Extended Services (optional).
3024     </para></listitem>
3025     <listitem><para>
3026      Result-Set Delete (optional).
3027     </para></listitem>
3028     <listitem><para>
3029      Result-Set Sort (optional).
3030     </para></listitem>
3031     <listitem><para>
3032      Return Explain for SRU (optional).
3033     </para></listitem>
3034    </itemizedlist>
3035    <para>
3036     (more functions will be added in time to support as much of
3037     Z39.50-1995 as possible).
3038    </para>
3039   </sect1>
3040   <sect1 id="server.backend">
3041    <title>The Backend API</title>
3042    <para>
3043     The header file that you need to use the interface are in the
3044     <filename>include/yaz</filename> directory. It's called
3045     <filename>backend.h</filename>. It will include other files from
3046     the <filename>include/yaz</filename> directory, so you'll
3047     probably want to use the -I option of your compiler to tell it
3048     where to find the files. When you run
3049     <literal>make</literal> in the top-level &yaz; directory,
3050     everything you need to create your server is to link with the
3051     <filename>lib/libyaz.la</filename> library.
3052    </para>
3053   </sect1>
3054   <sect1 id="server.main">
3055    <title>Your main() Routine</title>
3056    <para>
3057     As mentioned, your <function>main()</function> routine can be quite brief.
3058     If you want to initialize global parameters, or read global configuration
3059     tables, this is the place to do it. At the end of the routine, you should
3060     call the function
3061    </para>
3062    <synopsis>
3063 int statserv_main(int argc, char **argv,
3064                   bend_initresult *(*bend_init)(bend_initrequest *r),
3065                   void (*bend_close)(void *handle));
3066    </synopsis>
3067    <para>
3068     The third and fourth arguments are pointers to handlers. Handler
3069     <function>bend_init</function> is called whenever the server receives
3070     an Initialize Request, so it serves as a Z39.50 session initializer. The
3071     <function>bend_close</function> handler is called when the session is
3072     closed.
3073    </para>
3074    <para>
3075     <function>statserv_main</function> will establish listening sockets
3076     according to the parameters given. When connection requests are received,
3077     the event handler will typically <function>fork()</function> and
3078     create a sub-process to handle a new connection.
3079     Alternatively the server may be setup to create threads for each
3080     connection.
3081     If you do use global variables and forking, you should be aware, then,
3082     that these cannot be shared between associations, unless you explicitly
3083     disable forking by command line parameters.
3084    </para>
3085    <para>
3086     The server provides a mechanism for controlling some of its behavior
3087     without using command-line options. The function
3088    </para>
3089    <synopsis>
3090     statserv_options_block *statserv_getcontrol(void);
3091    </synopsis>
3092    <para>
3093     will return a pointer to a <literal>struct statserv_options_block</literal>
3094     describing the current default settings of the server. The structure
3095     contains these elements:
3096     <variablelist>
3097      <varlistentry>
3098       <term><literal>int dynamic</literal></term>
3099       <listitem><para>
3100        A boolean value, which determines whether the server
3101        will fork on each incoming request (TRUE), or not (FALSE). Default is
3102        TRUE. This flag is only read by UNIX-based servers (WIN32 based servers
3103        doesn't fork).
3104      </para></listitem>
3105      </varlistentry>
3106      <varlistentry>
3107       <term><literal>int threads</literal></term>
3108       <listitem><para>
3109        A boolean value, which determines whether the server
3110        will create a thread on each incoming request (TRUE), or not (FALSE).
3111        Default is FALSE. This flag is only read by UNIX-based servers
3112        that offer POSIX Threads support.
3113        WIN32-based servers always operate in threaded mode.
3114      </para></listitem>
3115      </varlistentry>
3116      <varlistentry>
3117       <term><literal>int inetd</literal></term>
3118       <listitem><para>
3119        A boolean value, which determines whether the server
3120        will operates under a UNIX INET daemon (inetd). Default is FALSE.
3121      </para></listitem>
3122      </varlistentry>
3123      <varlistentry>
3124       <term><literal>char logfile[ODR_MAXNAME+1]</literal></term>
3125       <listitem><para>File for diagnostic output (&quot;&quot;: stderr).
3126      </para></listitem>
3127      </varlistentry>
3128      <varlistentry>
3129       <term><literal>char apdufile[ODR_MAXNAME+1]</literal></term>
3130       <listitem><para>
3131        Name of file for logging incoming and outgoing APDUs
3132        (&quot;&quot;: don't log APDUs, &quot;-&quot;:
3133        <literal>stderr</literal>).
3134      </para></listitem>
3135      </varlistentry>
3136      <varlistentry>
3137       <term><literal>char default_listen[1024]</literal></term>
3138       <listitem><para>Same form as the command-line specification of
3139       listener address. &quot;&quot;: no default listener address.
3140       Default is to listen at &quot;tcp:@:9999&quot;. You can only
3141       specify one default listener address in this fashion.
3142      </para></listitem>
3143      </varlistentry>
3144      <varlistentry>
3145       <term><literal>enum oid_proto default_proto;</literal></term>
3146       <listitem><para>Either <literal>PROTO_Z3950</literal> or
3147       <literal>PROTO_SR</literal>.
3148       Default is <literal>PROTO_Z39_50</literal>.
3149      </para></listitem>
3150      </varlistentry>
3151      <varlistentry>
3152       <term><literal>int idle_timeout;</literal></term>
3153       <listitem><para>Maximum session idle-time, in minutes. Zero indicates
3154       no (infinite) timeout. Default is 15 minutes.
3155      </para></listitem>
3156      </varlistentry>
3157      <varlistentry>
3158       <term><literal>int maxrecordsize;</literal></term>
3159       <listitem><para>Maximum permissible record (message) size. Default
3160       is 64 MB. This amount of memory will only be allocated if a
3161       client requests a very large amount of records in one operation
3162       (or a big record).
3163       Set it to a lower number if you are worried about resource
3164       consumption on your host system.
3165      </para></listitem>
3166      </varlistentry>
3167      <varlistentry>
3168       <term><literal>char configname[ODR_MAXNAME+1]</literal></term>
3169       <listitem><para>Passed to the backend when a new connection is received.
3170      </para></listitem>
3171      </varlistentry>
3172      <varlistentry>
3173       <term><literal>char setuid[ODR_MAXNAME+1]</literal></term>
3174       <listitem><para>Set user id to the user specified, after binding
3175       the listener addresses.
3176      </para></listitem>
3177      </varlistentry>
3178      <varlistentry>
3179       <term>
3180        <literal>void (*bend_start)(struct statserv_options_block *p)</literal>
3181       </term>
3182       <listitem><para>Pointer to function which is called after the
3183       command line options have been parsed - but before the server
3184       starts listening.
3185       For forked UNIX servers this handler is called in the mother
3186       process; for threaded servers this handler is called in the
3187       main thread.
3188       The default value of this pointer is NULL in which case it
3189       isn't invoked by the frontend server.
3190       When the server operates as an NT service this handler is called
3191       whenever the service is started.
3192       </para></listitem>
3193      </varlistentry>
3194      <varlistentry>
3195       <term>
3196        <literal>void (*bend_stop)(struct statserv_options_block *p)</literal>
3197       </term>
3198       <listitem><para>Pointer to function which is called whenever the server
3199       has stopped listening for incoming connections. This function pointer
3200       has a default value of NULL in which case it isn't called.
3201       When the server operates as an NT service this handler is called
3202       whenever the service is stopped.
3203       </para></listitem>
3204      </varlistentry>
3205      <varlistentry>
3206       <term><literal>void *handle</literal></term>
3207       <listitem><para>User defined pointer (default value NULL).
3208       This is a per-server handle that can be used to specify "user-data".
3209       Do not confuse this with the session-handle as returned by bend_init.
3210       </para></listitem>
3211      </varlistentry>
3212     </variablelist>
3213    </para>
3214    <para>
3215     The pointer returned by <literal>statserv_getcontrol</literal> points to
3216     a static area. You are allowed to change the contents of the structure,
3217     but the changes will not take effect before you call
3218    </para>
3219    <synopsis>
3220 void statserv_setcontrol(statserv_options_block *block);
3221    </synopsis>
3222    <note>
3223     <para>
3224      that you should generally update this structure before calling
3225      <function>statserv_main()</function>.
3226     </para>
3227    </note>
3228   </sect1>
3229   <sect1 id="server.backendfunctions">
3230    <title>The Backend Functions</title>
3231    <para>
3232     For each service of the protocol, the backend interface declares one or
3233     two functions. You are required to provide implementations of the
3234     functions representing the services that you wish to implement.
3235    </para>
3236    <sect2 id="server.init">
3237     <title>Init</title>
3238     <synopsis>
3239 bend_initresult (*bend_init)(bend_initrequest *r);
3240     </synopsis>
3241     <para>
3242      This handler is called once for each new connection request, after
3243      a new process/thread has been created, and an Initialize Request has
3244      been received from the client. The pointer to the
3245      <function>bend_init</function> handler is passed in the call to
3246      <function>statserv_start</function>.
3247     </para>
3248     <para>
3249      This handler is also called when operating in SRU mode - when
3250      a connection has been made (even though SRU does not offer
3251      this service).
3252     </para>
3253     <para>
3254      Unlike previous versions of YAZ, the <function>bend_init</function> also
3255      serves as a handler that defines the Z39.50 services that the backend
3256      wish to support. Pointers to <emphasis>all</emphasis> service handlers,
3257      including search - and fetch must be specified here in this handler.
3258     </para>
3259     <para>
3260      The request - and result structures are defined as
3261     </para>
3262     <synopsis>
3263 typedef struct bend_initrequest
3264 {
3265     /** \brief user/name/password to be read */
3266     Z_IdAuthentication *auth;
3267     /** \brief encoding stream (for results) */
3268     ODR stream;
3269     /** \brief printing stream */
3270     ODR print;
3271     /** \brief decoding stream (use stream for results) */
3272     ODR decode;
3273     /** \brief reference ID */
3274     Z_ReferenceId *referenceId;
3275     /** \brief peer address of client */
3276     char *peer_name;
3277
3278     /** \brief character set and language negotiation
3279
3280     see include/yaz/z-charneg.h
3281     */
3282     Z_CharSetandLanguageNegotiation *charneg_request;
3283
3284     /** \brief character negotiation response */
3285     Z_External *charneg_response;
3286
3287     /** \brief character set (encoding) for query terms
3288
3289     This is NULL by default. It should be set to the native character
3290     set that the backend assumes for query terms */
3291     char *query_charset;
3292
3293     /** \brief whehter query_charset also applies to recors
3294
3295     Is 0 (No) by default. Set to 1 (yes) if records is in the same
3296     character set as queries. If in doubt, use 0 (No).
3297     */
3298     int records_in_same_charset;
3299
3300     char *implementation_id;
3301     char *implementation_name;
3302     char *implementation_version;
3303
3304     /** \brief Z39.50 sort handler */
3305     int (*bend_sort)(void *handle, bend_sort_rr *rr);
3306     /** \brief SRU/Z39.50 search handler */
3307     int (*bend_search)(void *handle, bend_search_rr *rr);
3308     /** \brief SRU/Z39.50 fetch handler */
3309     int (*bend_fetch)(void *handle, bend_fetch_rr *rr);
3310     /** \brief SRU/Z39.50 present handler */
3311     int (*bend_present)(void *handle, bend_present_rr *rr);
3312     /** \brief Z39.50 extended services handler */
3313     int (*bend_esrequest) (void *handle, bend_esrequest_rr *rr);
3314     /** \brief Z39.50 delete result set handler */
3315     int (*bend_delete)(void *handle, bend_delete_rr *rr);
3316     /** \brief Z39.50 scan handler */
3317     int (*bend_scan)(void *handle, bend_scan_rr *rr);
3318     /** \brief Z39.50 segment facility handler */
3319     int (*bend_segment)(void *handle, bend_segment_rr *rr);
3320     /** \brief SRU explain handler */
3321     int (*bend_explain)(void *handle, bend_explain_rr *rr);
3322     /** \brief SRU scan handler */
3323     int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);
3324     /** \brief SRU record update handler */
3325     int (*bend_srw_update)(void *handle, bend_update_rr *rr);
3326
3327     /** \brief whether named result sets are supported (0=disable, 1=enable) */
3328     int named_result_sets;
3329 } bend_initrequest;
3330
3331 typedef struct bend_initresult
3332 {
3333     int errcode;               /* 0==OK */
3334     char *errstring;           /* system error string or NULL */
3335     void *handle;              /* private handle to the backend module */
3336 } bend_initresult;
3337     </synopsis>
3338     <para>
3339      In general, the server frontend expects that the
3340      <literal>bend_*result</literal> pointer that you return is valid at
3341      least until the next call to a <literal>bend_* function</literal>.
3342      This applies to all of the functions described herein. The parameter
3343      structure passed to you in the call belongs to the server frontend, and
3344      you should not make assumptions about its contents after the current
3345      function call has completed. In other words, if you want to retain any
3346      of the contents of a request structure, you should copy them.
3347     </para>
3348     <para>
3349      The <literal>errcode</literal> should be zero if the initialization of
3350      the backend went well. Any other value will be interpreted as an error.
3351      The <literal>errstring</literal> isn't used in the current version, but
3352      one option would be to stick it in the initResponse as a VisibleString.
3353      The <literal>handle</literal> is the most important parameter. It should
3354      be set to some value that uniquely identifies the current session to
3355      the backend implementation. It is used by the frontend server in any
3356      future calls to a backend function.
3357      The typical use is to set it to point to a dynamically allocated state
3358      structure that is private to your backend module.
3359     </para>
3360     <para>
3361      The <literal>auth</literal> member holds the authentication information
3362      part of the Z39.50 Initialize Request. Interpret this if your serves
3363      requires authentication.
3364     </para>
3365     <para>
3366      The members <literal>peer_name</literal>,
3367      <literal>implementation_id</literal>,
3368      <literal>implementation_name</literal> and
3369      <literal>implementation_version</literal> holds
3370      DNS of client, ID of implementor, name
3371      of client (Z39.50) implementation - and version.
3372     </para>
3373     <para>
3374      The <literal>bend_</literal> - members are set to NULL when
3375      <function>bend_init</function> is called. Modify the pointers by
3376      setting them to point to backend functions.
3377     </para>
3378    </sect2>
3379    <sect2 id="server.search.retrieve">
3380     <title>Search and Retrieve</title>
3381     <para>
3382      We now describe the handlers that are required to support search -
3383      and retrieve. You must support two functions - one for search - and one
3384      for fetch (retrieval of one record). If desirable you can provide a
3385      third handler which is called when a present request is received which
3386      allows you to optimize retrieval of multiple-records.
3387     </para>
3388     <synopsis>
3389 int (*bend_search) (void *handle, bend_search_rr *rr);
3390
3391 typedef struct {
3392     char *setname;             /* name to give to this set */
3393     int replace_set;           /* replace set, if it already exists */
3394     int num_bases;             /* number of databases in list */
3395     char **basenames;          /* databases to search */
3396     Z_ReferenceId *referenceId;/* reference ID */
3397     Z_Query *query;            /* query structure */
3398     ODR stream;                /* encode stream */
3399     ODR decode;                /* decode stream */
3400     ODR print;                 /* print stream */
3401
3402     bend_request request;
3403     bend_association association;
3404     int *fd;
3405     int hits;                  /* number of hits */
3406     int errcode;               /* 0==OK */
3407     char *errstring;           /* system error string or NULL */
3408     Z_OtherInformation *search_info; /* additional search info */
3409     char *srw_sortKeys;        /* holds SRU/SRW sortKeys info */
3410     char *srw_setname;         /* holds SRU/SRW generated resultsetID */
3411     int *srw_setnameIdleTime;  /* holds SRU/SRW life-time */
3412     int estimated_hit_count;   /* if hit count is estimated */
3413     int partial_resultset;     /* if result set is partial */
3414 } bend_search_rr;
3415     </synopsis>
3416     <para>
3417      The <function>bend_search</function> handler is a fairly close
3418      approximation of a protocol Z39.50 Search Request - and Response PDUs
3419      The <literal>setname</literal> is the resultSetName from the protocol.
3420      You are required to establish a mapping between the set name and whatever
3421      your backend database likes to use.
3422      Similarly, the <literal>replace_set</literal> is a boolean value
3423      corresponding to the resultSetIndicator field in the protocol.
3424      <literal>num_bases/basenames</literal> is a length of/array of character
3425      pointers to the database names provided by the client.
3426      The <literal>query</literal> is the full query structure as defined in
3427      the protocol ASN.1 specification.
3428      It can be either of the possible query types, and it's up to you to
3429      determine if you can handle the provided query type.
3430      Rather than reproduce the C interface here, we'll refer you to the
3431      structure definitions in the file
3432      <filename>include/yaz/z-core.h</filename>. If you want to look at the
3433      attributeSetId OID of the RPN query, you can either match it against
3434      your own internal tables, or you can use the <link linkend="tools.oid">
3435      OID tools</link>.
3436     </para>
3437     <para>
3438      The structure contains a number of hits, and an
3439      <literal>errcode/errstring</literal> pair. If an error occurs
3440      during the search, or if you're unhappy with the request, you should
3441      set the errcode to a value from the BIB-1 diagnostic set. The value
3442      will then be returned to the user in a nonsurrogate diagnostic record
3443      in the response. The <literal>errstring</literal>, if provided, will
3444      go in the addinfo field. Look at the protocol definition for the
3445      defined error codes, and the suggested uses of the addinfo field.
3446     </para>
3447     <para>
3448      The <function>bend_search</function> handler is also called when
3449      the frontend server receives a SRU SearchRetrieveRequest.
3450      For SRU, a CQL query is usually provided by the client.
3451      The CQL query is available as part of <literal>Z_Query</literal>
3452      structure (note that CQL is now part of Z39.50 via an external).
3453      To support CQL in existing implementations that only do Type-1,
3454      we refer to the CQL-to-PQF tool described
3455      <link linkend="cql.to.pqf">here</link>.
3456     </para>
3457     <para>
3458      To maintain backwards compatibility, the frontend server
3459      of yaz always assume that error codes are BIB-1 diagnostics.
3460      For SRU operation, a Bib-1 diagnostic code is mapped to
3461      SRU diagnostic.
3462     </para>
3463     <synopsis>
3464 int (*bend_fetch) (void *handle, bend_fetch_rr *rr);
3465
3466 typedef struct bend_fetch_rr {
3467     char *setname;             /* set name */
3468     int number;                /* record number */
3469     Z_ReferenceId *referenceId;/* reference ID */
3470     Odr_oid *request_format;        /* format, transfer syntax (OID) */
3471     Z_RecordComposition *comp; /* Formatting instructions */
3472     ODR stream;                /* encoding stream - memory source if req */
3473     ODR print;                 /* printing stream */
3474
3475     char *basename;            /* name of database that provided record */
3476     int len;                   /* length of record or -1 if structured */
3477     char *record;              /* record */
3478     int last_in_set;           /* is it?  */
3479     Odr_oid *output_format;        /* response format/syntax (OID) */
3480     int errcode;               /* 0==success */
3481     char *errstring;           /* system error string or NULL */
3482     int surrogate_flag;        /* surrogate diagnostic */
3483     char *schema;              /* string record schema input/output */
3484 } bend_fetch_rr;
3485     </synopsis>
3486     <para>
3487      The frontend server calls the <function>bend_fetch</function> handler